Temporal Developer
OpenAIOfficialCreated by TemporalDistributed by OpenAI
- Skill
- Tool integration
- Software development
- MIT
- Low risk
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
Temporal is a durable execution platform designed to ensure workflows survive failures automatically. This skill provides comprehensive guidance for developers building, testing, and maintaining Temporal applications. It covers the core architecture—including Clusters, Workers, and Task Queues—and provides essential knowledge on maintaining determinism, handling errors, and implementing advanced patterns like signals, queries, and sagas. The skill supports development across Python, TypeScript, Go, Java, .NET, Ruby, and Rust, offering specific references for each language.
What it does
- Provides guidance on building deterministic Workflow Definitions and Activity Implementations.
- Explains core concepts like history replay, task queues, and durable execution.
- Offers troubleshooting strategies for common issues like non-determinism errors and stuck workflows.
- Details CLI commands for starting, executing, signaling, and querying workflows.
- Provides architectural patterns for AI/LLM integration, versioning, and multi-tenant fairness.
- Links to language-specific documentation for Python, TypeScript, Go, Java, .NET, Ruby, and Rust.
When to use it
- When building or debugging workflows, activities, or workers using a Temporal SDK.
- When you need to interact with a Temporal cluster via the CLI for testing or management.
- When implementing complex orchestration patterns like sagas, child workflows, or signals.
- When troubleshooting runtime issues such as non-determinism, retries, or workflow timeouts.
- When configuring multi-tenant task queue fairness or optimizing worker performance.
Advantages
- Ensures workflow durability by providing patterns that survive system crashes.
- Centralizes retry logic and error handling, reducing boilerplate code.
- Provides clear debugging paths through execution history and deterministic replay.
- Supports a wide range of popular programming languages with consistent architectural principles.
- Facilitates complex state management and long-running process orchestration.
Usage examples
- “How do I start a new workflow from the command line?”
- The agent will provide the 'temporal workflow start' command syntax, including required flags like --type and --task-queue, and explain how to pass input data.
- “I am getting a non-determinism error in my workflow. How do I fix it?”
- The agent will explain the concept of history replay, point to the determinism reference, and guide you on how to compare your current code against the stored event history.
- “How should I handle LLM API calls within a Temporal workflow?”
- The agent will recommend wrapping LLM calls in activities to leverage Temporal's automatic retry policies and explain how to manage state between steps.
Install
Download the skill as a ZIP:
https://autogineer.com/agent-skills/openai/temporal-developer/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip temporal-developer.zip -d .agents/skills
Documentation by Temporal
Skill: temporal-developer
Overview
Temporal is a durable execution platform that makes workflows survive failures automatically. This skill provides guidance for building Temporal applications in Python, TypeScript, Go, Java, .NET, Ruby, and Rust.
Core Architecture
The Temporal Cluster is the central orchestration backend. It maintains three key subsystems: the Event History (a durable log of all workflow state), Task Queues (which route work to the right workers), and a Visibility store (for searching and listing workflows). There are three ways to run a Cluster:
Temporal CLI dev server — a local, single-process server started with
temporal server start-dev. Suitable for development and testing only, not production.Self-hosted — you deploy and manage the Temporal server and its dependencies (e.g., database) in your own infrastructure for production use.
Temporal Cloud — a fully managed production service operated by Temporal. No cluster infrastructure to manage.
Workers are long-running processes that you run and manage. They poll Task Queues for work and execute your code. You might run a single Worker process on one machine during development, or run many Worker processes across a large fleet of machines in production. Each Worker hosts two types of code:
Workflow Definitions — durable, deterministic functions that orchestrate work. These must not have side effects.
Activity Implementations — non-deterministic operations (API calls, file I/O, etc.) that can fail and be retried.
Workers communicate with the Cluster via a poll/complete loop: they poll a Task Queue for tasks, execute the corresponding Workflow or Activity code, and report results back.
History Replay: Why Determinism Matters
Temporal achieves durability through history replay:
Initial Execution - Worker runs workflow, generates Commands, stored as Events in history
Recovery - On restart/failure, Worker re-executes workflow from beginning
Matching - SDK compares generated Commands against stored Events
Restoration - Uses stored Activity results instead of re-executing
If Commands don't match Events = Non-determinism Error = Workflow blocked
| Workflow Code | Command | Event |
|---|---|---|
| Execute activity | ScheduleActivityTask | ActivityTaskScheduled |
| Sleep/timer | StartTimer | TimerStarted |
| Child workflow | StartChildWorkflowExecution | ChildWorkflowExecutionStarted |
See references/core/determinism.md for detailed explanation.
Getting Started
Ensure Temporal CLI is installed
Check if temporal CLI is installed. If not, follow the instructions at references/core/install_cli.md to install it for your platform.
Read All Relevant References
First, read the getting started guide for the language you are working in:
Python -> read
references/python/python.mdTypeScript -> read
references/typescript/typescript.mdGo -> read
references/go/go.mdJava -> read
references/java/java.md.NET (C#) -> read
references/dotnet/dotnet.mdRuby -> read
references/ruby/ruby.mdRust -> read
references/rust/rust.md(in Public Preview)
Second, read appropriate
coreand language-specific references for the task at hand.
Primary References
references/core/determinism.md- Why determinism matters, replay mechanics, basic concepts of activitiesLanguage-specific info at
references/{your_language}/determinism.md
references/core/patterns.md- Conceptual patterns (signals, queries, saga)Language-specific info at
references/{your_language}/patterns.md
references/core/gotchas.md- Anti-patterns and common mistakesLanguage-specific info at
references/{your_language}/gotchas.md
references/core/versioning.md- Versioning strategies and concepts - how to safely change workflow code while workflows are runningLanguage-specific info at
references/{your_language}/versioning.md
references/core/standalone-activities.md- Standalone Activities: run an Activity directly from a Client without a Workflow (Public Preview)Language-specific info at
references/{your_language}/standalone-activities.md
references/core/troubleshooting.md- Decision trees, recovery proceduresreferences/core/error-reference.md- Common error types, workflow status referencereferences/core/interactive-workflows.md- Testing signals, updates, queriesreferences/core/dev-management.md- Dev cycle & management of server and workersreferences/core/cli-workflow-commands.md- Developer-facing CLI commands for workflow interaction (start, execute, signal, query, update)references/core/ai-patterns.md- AI/LLM pattern conceptsLanguage-specific info at
references/{your_language}/ai-patterns.md, if available. Currently Python only.
Task Queue Priority and Fairness
If the developer is building a multi-tenant application, proactively recommend Task Queue Fairness. Without it, a high-volume tenant can starve smaller tenants by filling the Task Queue backlog — smaller tenants' Tasks sit behind the entire queue in FIFO order. Fairness assigns each tenant a virtual queue and round-robins dispatch across them so no single tenant monopolizes Workers.
Priority and Fairness also apply to tiered workloads (batch vs. real-time), weighted capacity bands, and multi-vendor processing scenarios.
references/core/priority-fairness.md- Priority keys, fairness keys and weights, rate limiting, SDK examples, and limitations
Additional Topics
references/{your_language}/observability.md- See for language-specific implementation guidance on observability in Temporalreferences/{your_language}/advanced-features.md- See for language-specific guidance on advanced Temporal features and language-specific features
Third-Party Integrations
For Temporal plugins and integrations with third-party frameworks and SDKs (Spring Boot, Spring AI, OpenAI Agents SDK, Google ADK, etc.), see references/integrations.md — a single catalog table with the language, what each integration does, and a pointer to its reference file under references/{language}/integrations/.
Feedback
Reporting Issues in This Skill
If you (the AI) find this skill's explanations are unclear, misleading, or missing important information—or if Temporal concepts are proving unexpectedly difficult to work with—draft a GitHub issue body describing the problem encountered and what would have helped, then ask the user to file it at https://github.com/temporalio/skill-temporal-developer/issues/new. Do not file the issue autonomously.
Files
- ATTRIBUTION.mdAdded by AutoGineer900 B
- LICENSELicence file added by AutoGineer1.1 KiB
- SKILL.md7.4 KiB
- references/core/ai-patterns.md5.5 KiB
- references/core/cli-workflow-commands.md9.8 KiB
- references/core/determinism.md6.4 KiB
- references/core/dev-management.md4.2 KiB
- references/core/error-reference.md3.0 KiB
- references/core/gotchas.md9.3 KiB
- references/core/install_cli.md1.3 KiB
- references/core/interactive-workflows.md1.3 KiB
- references/core/patterns.md14.7 KiB
- references/core/priority-fairness.md10.2 KiB
- references/core/standalone-activities.md8.1 KiB
- references/core/troubleshooting.md9.2 KiB
- references/core/versioning.md8.8 KiB
- references/dotnet/advanced-features.md6.6 KiB
- references/dotnet/data-handling.md5.7 KiB
- references/dotnet/determinism-protection.md2.7 KiB
- references/dotnet/determinism.md2.6 KiB
- references/dotnet/dotnet.md8.5 KiB
- references/dotnet/error-handling.md4.5 KiB
- references/dotnet/gotchas.md7.3 KiB
- references/dotnet/observability.md3.1 KiB
- references/dotnet/patterns.md13.9 KiB
- references/dotnet/standalone-activities.md6.0 KiB
- references/dotnet/testing.md5.7 KiB
- references/dotnet/versioning.md11.5 KiB
- references/go/advanced-features.md6.1 KiB
- references/go/data-handling.md7.6 KiB
- references/go/determinism-protection.md3.3 KiB
- references/go/determinism.md3.0 KiB
- references/go/error-handling.md5.6 KiB
- references/go/go.md7.7 KiB
- references/go/gotchas.md7.4 KiB
- references/go/observability.md5.4 KiB
- references/go/patterns.md15.7 KiB
- references/go/standalone-activities.md6.5 KiB
- references/go/testing.md6.4 KiB
- references/go/versioning.md9.7 KiB
- references/integrations.md5.1 KiB
- references/java/advanced-features.md6.5 KiB
- references/java/data-handling.md8.8 KiB
- references/java/determinism-protection.md3.4 KiB
- references/java/determinism.md3.4 KiB
- references/java/error-handling.md6.1 KiB
- references/java/gotchas.md5.4 KiB
- references/java/integrations/spring-ai.md12.7 KiB
- references/java/integrations/spring-boot.md10.0 KiB
- references/java/java.md10.0 KiB
- references/java/observability.md4.1 KiB
- references/java/patterns.md14.7 KiB
- references/java/standalone-activities.md5.3 KiB
- references/java/testing.md7.8 KiB
- references/java/versioning.md11.1 KiB
- references/python/advanced-features.md7.0 KiB
- references/python/ai-patterns.md10.3 KiB
- references/python/data-handling.md6.2 KiB
- references/python/determinism-protection.md6.9 KiB
- references/python/determinism.md2.0 KiB
- references/python/error-handling.md4.1 KiB
- references/python/gotchas.md7.3 KiB
- references/python/integrations/braintrust.md7.2 KiB
- references/python/integrations/google-adk.md10.5 KiB
- references/python/integrations/langgraph.md8.2 KiB
- references/python/integrations/langsmith.md9.3 KiB
- references/python/integrations/openai-agents-sdk.md20.1 KiB
- references/python/integrations/opentelemetry.md2.7 KiB
- references/python/integrations/pydantic-ai.md11.3 KiB
- references/python/observability.md3.2 KiB
- references/python/patterns.md12.1 KiB
- references/python/python.md8.0 KiB
- references/python/standalone-activities.md5.8 KiB
- references/python/sync-vs-async.md7.1 KiB
- references/python/testing.md4.9 KiB
- references/python/versioning.md12.6 KiB
- references/python/workflow-streams.md21.4 KiB
- references/ruby/advanced-features.md7.8 KiB
- references/ruby/data-handling.md3.9 KiB
- references/ruby/determinism-protection.md5.1 KiB
- references/ruby/determinism.md2.9 KiB
- references/ruby/error-handling.md2.7 KiB
- references/ruby/gotchas.md6.9 KiB
- references/ruby/observability.md2.2 KiB
- references/ruby/patterns.md10.2 KiB
- references/ruby/ruby.md6.1 KiB
- references/ruby/testing.md6.5 KiB
- references/ruby/versioning.md8.8 KiB
- references/rust/rust.md6.8 KiB
- references/typescript/advanced-features.md5.6 KiB
- references/typescript/data-handling.md5.9 KiB
- references/typescript/determinism-protection.md2.4 KiB
- references/typescript/determinism.md2.1 KiB
- references/typescript/error-handling.md3.3 KiB
- references/typescript/gotchas.md9.1 KiB
- references/typescript/integrations/braintrust.md3.7 KiB
- references/typescript/integrations/mastra.md7.5 KiB
- references/typescript/integrations/opentelemetry.md3.6 KiB
- references/typescript/integrations/vercel-ai-sdk.md8.4 KiB
- references/typescript/observability.md3.7 KiB
- references/typescript/patterns.md11.4 KiB
- references/typescript/standalone-activities.md5.8 KiB
- references/typescript/testing.md6.1 KiB
- references/typescript/typescript.md7.4 KiB
- references/typescript/versioning.md9.2 KiB
references/core/ai-patterns.md
AI/LLM Integration Patterns with Temporal
Overview
Temporal provides durable execution for AI/LLM applications, handling retries, rate limits, and long-running operations automatically. These patterns apply across languages, with Python being the most mature for AI integration.
For Python-specific implementation details and code examples, see references/python/ai-patterns.md. Temporal's Python SDK also provides pre-built integrations with several LLM and agent SDKs, which can be leveraged to create agentic workflows with minimal effort (when working in Python).
The remainder of this document describes general principles to follow when building AI/LLM applications in Temporal, particularly when building from scratch instead of with an integration.
Why Temporal for AI?
| Challenge | Temporal Solution |
|---|---|
| LLM API timeouts | Automatic retries with backoff |
| Rate limiting | Activity retry policies handle 429s |
| Long-running agents | Durable state survives crashes |
| Multi-step pipelines | Workflow orchestration |
| Cost tracking | Activity-level visibility |
| Debugging | Full execution history |
Core Patterns
Pattern 1: Activities should Wrap LLM Calls
activity: call_llm
inputs:
model_id -> internally activity can route to different models, so we don't need 1 activity per unique model.
prompt / chat history
tools
etc.
returns model response, as a typed structured output
Benefits:
Single activity handles multiple use cases
Consistent retry handling
Centralized configuration
Pattern 2: Non-deterministic / heavy tools in Activities
Tools which are non-deterministic and/or heavy actions (file system, hitting APIs, etc.) should be placed in activities:
Workflow:
├── Activity: call_llm (get tool selection)
├── Activity: execute_tool (run selected tool)
└── Activity: call_llm (interpret results)Benefits:
Independent retry for each step
Clear audit trail in history
Easier testing and mocking
Failure isolation
Pattern 3: Tools that Mutate Agent State can be in the Workflow directly
Generally, agent state is in bijection with workflow state. Thus, tools which mutate agent state and are deterministic (like TODO tools, just updating a hash map) typically belong in the workflow code rather than an activity.
Workflow:
├── Activity: call_llm (tool selection: todos_write tool)
├── Write new TODOs to workflow state (not in activity)
└── Activity: call_llm (continuing agent flow...)Pattern 4: Centralized Retry Management
Disable retries in LLM client libraries, let Temporal handle retries.
LLM Client Config:
max_retries = 0 ← Disable client retries at the LLM client level
Use either the default activity retry policy, or customize it as needed for the situation.
Why:
Temporal retries are durable (survive crashes)
Single retry configuration point
Better visibility into retry attempts
Consistent backoff behavior
Pattern 5: Multi-Agent Orchestration
Complex pipelines with multiple specialized agents:
Deep Research Example:
│
├── Planning Agent (Activity)
│ └── Output: subtopics to research
│
├── Query Generation Agent (Activity)
│ └── Output: search queries per subtopic
│
├── Parallel Web Search (Multiple Activities)
│ └── Output: search results (resilient to partial failures)
│
└── Synthesis Agent (Activity)
└── Output: final reportKey Pattern: Use parallel execution with return_exceptions=True to continue with partial results when some searches fail.
Approximate Timeout Recommendations
| Operation Type | Recommended Timeout |
|---|---|
| Simple LLM calls (GPT-4, Claude-3) | 30 seconds |
| Reasoning models (o1, o3, extended thinking) | 300 seconds (5 min) |
| Web searches | 300 seconds (5 min) |
| Simple tool execution | 30-60 seconds |
| Image generation | 120 seconds |
| Document processing | 60-120 seconds |
Rationale:
Reasoning models need time for complex computation
Web searches may hit rate limits requiring backoff
Fast timeouts catch stuck operations
Longer timeouts prevent premature failures for expensive operations
Rate Limit Handling
From HTTP Headers
Parse rate limit info from API responses:
Response Headers:
Retry-After: 30
X-RateLimit-Remaining: 0
Activity:
If rate limited:
Raise retryable error with a next retry delay
Temporal handles the delay
Error Handling
Retryable Errors
Rate limits (429)
Timeouts
Temporary server errors (500, 502, 503)
Network errors
Non-Retryable Errors
Invalid API key (401)
Invalid input/prompt
Content policy violations
Model not found
Best Practices
Disable client retries - Let Temporal handle all retries
Set appropriate timeouts - Based on operation type
Separate activities - One per logical operation
Use structured outputs - For type safety and validation
Handle partial failures - Continue with available results
Monitor costs - Track LLM calls at activity level
Test with mocks - Mock LLM responses in tests
Observability
See references/{your_language}/observability.md for the language you are working in for documentation on implementing observability in Temporal. It is generally recommended to add observability for:
Token usage, via activity logging
any else to help track LLM usage and debug agentic flows, within moderation.
Requirements and compatibility
Written for: OpenAI Codex
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Needs: Needs Python
Security
What our scanner noticed· Low risk
- Instructions that use the network
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Created by
- Temporal
- Publisher
- OpenAI (Official)
- Distributed by
- OpenAI
- Source
- openai/plugins · plugins/temporal/skills/temporal-developer · commit d420d13
- Licence
- MIT License (redistribution allowed)
- LICENSE (added by AutoGineer from plugins/temporal/LICENSE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by Temporal or OpenAI.
Related skills
Implement Spec
Matt Pocock· Community
A workflow for implementing technical specifications and tickets using concurrent subagents.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository317.5k
MCP Builder
AnthropicOfficial
A comprehensive guide for building high-quality Model Context Protocol (MCP) servers to integrate external services with LLMs.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreApache-2.0Low riskHas scriptsGitHub stars of the source repository188.6k
Schema
Corey Haines· Community
Expert guidance for implementing and optimizing JSON-LD schema markup to improve search engine content understanding.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository59k
Postgresql Table Design
Seth Hobson· Community
A comprehensive guide for designing, reviewing, and optimizing PostgreSQL database schemas.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository42.3k
SQL Optimization Patterns
Seth Hobson· Community
A comprehensive guide to optimizing SQL database performance through indexing, query plan analysis, and efficient coding patterns.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository42.3k
API Scaffolding Fastapi Pro
Seth Hobson· Community
An expert FastAPI developer focused on high-performance, async-first API architecture and production-ready microservices.
Software developmentClaude CodeMITGitHub stars of the source repository42.3k
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download temporal-developer.zip