AutoGineer
Generated banner for Temporal Developer
Generated logo for Temporal Developer

Temporal Developer

OpenAIOfficialCreated by TemporalDistributed by OpenAI

  • Skill
  • Tool integration
  • Software development
  • MIT
  • Low risk
Download ZIP

From the author

Develop, debug, and manage Temporal applications across Python, TypeScript, Go, Java, .NET, Ruby, and Rust. Use when the user is building workflows, activities, or workers with a Temporal SDK, debugging issues like non-determinism errors, stuck workflows, or activity retries, using Temporal CLI, Temporal Server, or Temporal Cloud, or working with durable execution concepts like signals, queries, heartbeats, versioning, continue-as-new, child workflows, or saga patterns. Also use when the user mentions "run a Temporal workflow from the CLI", "start a dev server", "run temporal server start-dev", "temporal workflow start", "temporal workflow execute", "temporal workflow signal", "temporal workflow query", "temporal workflow update".
— the description by Temporal

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

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/openai/temporal-developer/download

  2. Unzip 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:

  1. Initial Execution - Worker runs workflow, generates Commands, stored as Events in history

  2. Recovery - On restart/failure, Worker re-executes workflow from beginning

  3. Matching - SDK compares generated Commands against stored Events

  4. Restoration - Uses stored Activity results instead of re-executing

If Commands don't match Events = Non-determinism Error = Workflow blocked

Workflow CodeCommandEvent
Execute activityScheduleActivityTaskActivityTaskScheduled
Sleep/timerStartTimerTimerStarted
Child workflowStartChildWorkflowExecutionChildWorkflowExecutionStarted

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

  1. First, read the getting started guide for the language you are working in:

    • Python -> read references/python/python.md

    • TypeScript -> read references/typescript/typescript.md

    • Go -> read references/go/go.md

    • Java -> read references/java/java.md

    • .NET (C#) -> read references/dotnet/dotnet.md

    • Ruby -> read references/ruby/ruby.md

    • Rust -> read references/rust/rust.md (in Public Preview)

  2. Second, read appropriate core and language-specific references for the task at hand.

Primary References

  • references/core/determinism.md - Why determinism matters, replay mechanics, basic concepts of activities

    • Language-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 mistakes

    • Language-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 running

    • Language-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 procedures

  • references/core/error-reference.md - Common error types, workflow status reference

  • references/core/interactive-workflows.md - Testing signals, updates, queries

  • references/core/dev-management.md - Dev cycle & management of server and workers

  • references/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 concepts

    • Language-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 Temporal

  • references/{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

references/python/integrations/google-adk.md

Temporal Google ADK Integration

Overview

temporalio.contrib.google_adk_agents makes Google ADK agents durable on the Temporal Python SDK: ADK model calls run through Temporal Activities, tools dispatch through Activities or the workflow thread, and non-deterministic primitives (time.time(), uuid.uuid4()) are replaced with deterministic workflow equivalents inside the sandbox.

The integration is built on the Python SDK Plugin system and ships as part of the temporalio package via the google-adk extra.

[!NOTE] This feature is in Public Preview. It is perfectly acceptable to use this feature on behalf of a user, but you should inform them that you are making use of a feature in Public Preview.

For general Temporal AI/LLM patterns (retries, rate limits, multi-agent orchestration) see references/core/ai-patterns.md and references/python/ai-patterns.md.

Prerequisites

DependencyMinimum version
Temporal Python SDK1.24.0
Google ADKa working google-adk install (pulled in by the extra)

You also need access to a supported model (e.g. a Gemini API key for gemini-flash-latest / gemini-2.5-pro) and a running Temporal server — temporal server start-dev for local development, self-hosted, or Temporal Cloud.

Install

pip install "temporalio[google-adk]"

The extra name is google-adk (hyphen). The module path is temporalio.contrib.google_adk_agents (note the _agents suffix).

Public API

SymbolImportPurpose
GoogleAdkPluginfrom temporalio.contrib.google_adk_agents import GoogleAdkPluginClient/Worker plugin: determinism replacement + Pydantic/ADK passthrough
TemporalModelfrom temporalio.contrib.google_adk_agents import TemporalModelLLM model wrapper that routes model calls through a Temporal Activity
activity_toolfrom temporalio.contrib.google_adk_agents.workflow import activity_toolWraps a plain @activity.defn function as an ADK tool
TemporalMcpToolSetfrom temporalio.contrib.google_adk_agents import TemporalMcpToolSetExecutes MCP tools as Temporal Activities
TemporalMcpToolSetProviderfrom temporalio.contrib.google_adk_agents import TemporalMcpToolSetProviderFactory wired into GoogleAdkPlugin(toolset_providers=[...]) so MCP activities register with the worker

Configure the plugin on Client and Worker

GoogleAdkPlugin() must be attached to the Temporal Client used to build the worker. It installs the determinism replacements, configures Pydantic/ADK serialization, and registers the model and MCP activities on the worker.

import asyncio
from temporalio.client import Client
from temporalio.worker import Worker
from temporalio.contrib.google_adk_agents import GoogleAdkPlugin

async def main():
    client = await Client.connect(
        "localhost:7233",
        plugins=[GoogleAdkPlugin()],
    )

    worker = Worker(
        client,
        task_queue="my-agent-task-queue",
        workflows=[WeatherAgentWorkflow],
        activities=[get_weather],
    )
    await worker.run()

asyncio.run(main())

Attach the same plugin when starting workflows from a client process so that data converters and toolset providers line up across both sides:

client = await Client.connect(
    "localhost:7233",
    plugins=[GoogleAdkPlugin()],
)
result = await client.execute_workflow(
    WeatherAgentWorkflow.run,
    "What's the weather in San Francisco?",
    id="weather-agent-1",
    task_queue="my-agent-task-queue",
)

Define tools with activity_tool

Write the underlying function as a normal Temporal Activity, then wrap it with activity_tool(...) to produce a tool that ADK can attach to an Agent. The wrapper records timeouts and retry policy at construction time, so each invocation runs as a Temporal Activity with those settings.

from datetime import timedelta
from temporalio import activity
from temporalio.common import RetryPolicy
from temporalio.contrib.google_adk_agents.workflow import activity_tool

@activity.defn
async def get_weather(city: str) -> str:
    return f"72°F and sunny in {city}"

weather_tool = activity_tool(
    get_weather,
    start_to_close_timeout=timedelta(seconds=30),
    retry_policy=RetryPolicy(maximum_attempts=3),
)

Register the underlying @activity.defn function on the worker's activities= list — activity_tool does not auto-register it.

Use TemporalModel on the Agent

TemporalModel(model_name, activity_config=ActivityConfig(...)) wraps any ADK-supported model so each call lands in a Temporal Activity. ActivityConfig comes from temporalio.workflow and accepts the usual per-Activity settings (timeouts, retry policy, task queue, summary, etc.).

from google.adk.agents import Agent
from temporalio.contrib.google_adk_agents import TemporalModel
from temporalio.workflow import ActivityConfig

agent = Agent(
    name="weather_agent",
    model=TemporalModel(
        "gemini-flash-latest",
        activity_config=ActivityConfig(summary="Weather Agent"),
    ),
    tools=[weather_tool],
)

Streaming responses are not currently supported through TemporalModel.

Wrap the agent in a Workflow

Workflows drive ADK in the same way as a non-Temporal program: build an InMemoryRunner, create a session, and iterate run_async. Use contextlib.aclosing so the async generator is closed deterministically, and consume the events to collect the final assistant text.

from contextlib import aclosing
from google.adk.runners import InMemoryRunner
from google.genai import types
from temporalio import workflow

@workflow.defn
class WeatherAgentWorkflow:
    @workflow.run
    async def run(self, user_message: str) -> str:
        runner = InMemoryRunner(agent=agent, app_name="weather_app")
        session = await runner.session_service.create_session(
            user_id="user", app_name="weather_app",
        )
        result = ""
        async with aclosing(
            runner.run_async(
                user_id="user",
                session_id=session.id,
                new_message=types.Content(
                    role="user",
                    parts=[types.Part.from_text(text=user_message)],
                ),
            )
        ) as events:
            async for event in events:
                if event.content and event.content.parts:
                    for part in event.content.parts:
                        if part.text:
                            result = part.text
        return result

Determinism rules still apply to the workflow body itself: don't read the wall clock, generate random IDs, or perform I/O outside Activities or the ADK-managed model/tool calls. The plugin redirects time.time() and uuid.uuid4() to workflow.now() and workflow.uuid4() when running inside a workflow, but new non-deterministic call sites you add (e.g. random, datetime.now(), network I/O) are not covered.

MCP tools

To expose MCP tools to an ADK agent through Temporal, register a TemporalMcpToolSetProvider on the plugin and attach a matching TemporalMcpToolSet to the agent. The provider factory builds the underlying ADK McpToolset; the same factory is also passed as not_in_workflow_toolset= on the workflow-side TemporalMcpToolSet so local runs (e.g. adk run / adk web) execute the toolset directly.

from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters
from temporalio.contrib.google_adk_agents import (
    GoogleAdkPlugin,
    TemporalMcpToolSet,
    TemporalMcpToolSetProvider,
    TemporalModel,
)

def toolset_factory(_):
    return McpToolset(
        connection_params=StdioConnectionParams(
            server_params=StdioServerParameters(
                command="npx",
                args=["-y", "@modelcontextprotocol/server-filesystem", "/path"],
            ),
        ),
    )

toolset_provider = TemporalMcpToolSetProvider("my-tools", toolset_factory)

client = await Client.connect(
    "localhost:7233",
    plugins=[GoogleAdkPlugin(toolset_providers=[toolset_provider])],
)

agent = Agent(
    name="tool_agent",
    model=TemporalModel("gemini-flash-latest"),
    tools=[TemporalMcpToolSet("my-tools", not_in_workflow_toolset=toolset_factory)],
)

The provider name ("my-tools" above) must match between TemporalMcpToolSetProvider and TemporalMcpToolSet. Always pass not_in_workflow_toolset= — without it, local execution outside a workflow has no fallback path.

Local fallback for adk run / adk web

TemporalModel, activity_tool, and TemporalMcpToolSet detect when they are invoked outside a workflow and execute directly against the underlying model, function, or MCP toolset. The same agent definition therefore works both under adk run / adk web for local development and under a Temporal worker in production — no separate code paths.

Common mistakes

  • Mixing up ActivityConfig and ActivityOptions. TemporalModel takes activity_config=ActivityConfig(...) from temporalio.workflow.

  • Forgetting not_in_workflow_toolset on TemporalMcpToolSet. Required for local fallback.

  • Skipping GoogleAdkPlugin() on the client used by execute_workflow. Data-converter and toolset wiring lives on the plugin; using only the worker-side plugin leads to serialization errors.

  • Registering activity_tool(...) wrappers in activities=. Register the underlying @activity.defn function instead.

  • Forgetting non-determinism rules. As with Temporal broadly, workflow code must be deterministic. This plugin makes it a bit easier by auto-replacing common sources of non-determinism with Temporal durable variants, but you are strongly encouraged to just use those explicitly. In workflow code: use workflow.now(), etc. In activity code: use time.time() or whatever standard non-deterministic things, NOT workflow.* calls.

  • Expecting streaming responses. Not currently supported via TemporalModel.

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.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download temporal-developer.zip