The repository or configuration that created this release differ from a previous release. View details.
Temporal Agent Kit for Python
Build durable agents using Python, Temporal, and your preferred AI SDK.
Project overview · TypeScript guide · Harness API
Quickstart
Create an agent, install its coding-agent skill, and open a working session in four steps. No repository checkout or Bazel installation is needed.
Available with the next Python release. The
init,skills,dev, anddoctorcommands are not in the published 0.8.0 package. Once the new release is published, the@latestcommand below selects it. Until then, use the manual setup with published packages.
You need Python 3.11+, uv, the
Temporal CLI, and an OpenAI API key for the starter's ask handler.
1. Create the project
Run this from the directory where you want the new project:
uvx temporal-agent-kit@latest init my-agent
cd my-agent
uv sync
uvx supplies the CLI before you have a project. init creates my_agent/workflow.py,
my_agent/worker.py, agents.toml, a pyproject.toml named after the directory, and a README.
It pins the installed Agent Kit version with the ui and openai-agents extras and refuses to
overwrite existing files. uv sync installs the project and its dependencies. The starter's
weather tool returns sample data.
2. Configure it and install the skill
cp env.example .env.local
uv run temporal-agent-kit schema my_agent.workflow:OpenAIHelloAgentWorkflow -o agent.schema.json
uv run temporal-agent-kit skills install # asks which coding agents to install the skill for
.env.local is where OPENAI_API_KEY goes once you try ask; never commit it. schema exports
your agent's handlers and types to agent.schema.json. skills install asks which coding agents
you use and copies this SDK release's skill, with authoring, API, advanced-feature, and
verification references, into the directories they read:
| Choice | --for |
Skill directory | Read by |
|---|---|---|---|
| 1 | claude |
.claude/skills |
Claude Code |
| 2 | agents |
.agents/skills |
Codex and other agents that read the shared .agents/skills directory |
Choose both if you use Claude Code alongside another agent. To skip the question, as in scripts,
pass the choices: skills install --for claude --for agents.
Installing the Python package bundles the
skill; this explicit step makes it discoverable in your project. For a tool with another skill
directory, run uv run temporal-agent-kit skills path to locate the bundled resources, or
use skills install --dest <directory>.
3. Start the three services
Run each command in its own terminal, all from this project directory:
Terminal 1 — Temporal service (skip if your configured Temporal service is already running):
temporal server start-dev
Terminal 2 — shared session manager, API, and Agent Kit console:
uv run temporal-agent-kit dev agents.toml
Terminal 3 — your Python agent worker:
uv run --env-file .env.local python -m my_agent.worker
The console is prebuilt in the Python package; no Node.js or frontend build is needed. dev runs
the session-manager worker and the API/console server in one process; session-manager and
serve remain available as separate commands for deployments. Defaults are localhost:7233 and
namespace default. For another Temporal service, export the same TEMPORAL_* connection
settings in each service terminal. .env.local above loads only into the agent worker. Keep
TASK_QUEUE_PREFIX consistent across services. Keep all three processes running.
4. Verify, then develop with your coding agent
-
Open the Agent Kit console at http://localhost:8000. Create a session for OpenAI Hello (Python).
-
Send a
pingmessage. The message box's handler button names the handler your message goes to; a new session starts onping. Type any text, such ashello, and press Enter. Expect the same text back without a model request or an API key. -
Send an
askmessage. This step calls OpenAI:- Set
OPENAI_API_KEYin.env.local. - Restart the worker so it reads the key, which it loads only at startup: in Terminal 3,
press Ctrl+C, then run
uv run --env-file .env.local python -m my_agent.workeragain. Leave the other services running; your session picks up where it left off once the worker is back. - Switch the message box to
ask: click the handler button (it showsping) and chooseask, or type/in the message box and pickaskfrom the list. The button now showsask, and later messages go toaskuntil you switch again. - Send “What's the weather in Paris?”. Expect a streamed reply and a completed
get_weathertool trace with sample weather data.
- Set
-
Reload the page and confirm the session reconnects.
-
Check configuration and service availability:
uv run temporal-agent-kit doctor --registry agents.toml
Add --json for a machine-readable report. The doctor checks the registry and schemas, Temporal
connectivity, task queue pollers, and the API without creating or resetting sessions. A failed
check exits 1. Temporal's own workflow UI is at http://localhost:8233; it is separate from the
Agent Kit console.
With the services running, open the project in your coding agent. Reload its session if it was already running, then ask it to use the skill:
| Tool | Prompt |
|---|---|
| Codex | Use $temporal-agent-kit-python to help me build this agent. Explain the starter, then verify it with ping before making model calls. |
| Claude Code | /temporal-agent-kit-python Explain the starter, then verify it with ping before making model calls. |
Edit my_agent/workflow.py to change your agent and my_agent/worker.py for worker configuration.
After changes, stop the worker, regenerate the schema with the command in step 2, and restart
it with the command in step 3. Use a new session for changed workflow behavior.
Commit agent.schema.json and uv.lock.
After upgrading the SDK, rerun the skills install commands to update unchanged skill files.
Local edits produce a conflict and are preserved. Application-client guidance is in the installed
skill's references/api.md.
See coding-agent development
for skill discovery and updates. The init, skills, and doctor commands ship with the base
package; dev, serve, and OpenAPI export require the ui extra.
Installation and manual reference
For a new application, start with the four-step quickstart above. The reference below covers existing projects, model integration extras, and repository examples.
Try the example agents
Clone at a release tag. You need just,
Bazelisk installed as bazel, and the
temporal CLI (see Requirements).
git clone --branch 0.12.1 https://github.com/temporal-community/temporal-agent-kit.git
cd temporal-agent-kit
cp .env.example .env.local # then set GEMINI_API_KEY (and/or OPENAI_API_KEY)
Then run two commands in separate terminals to get going with all example agents:
just temporal # 1. local Temporal dev server (needs the `temporal` CLI)
just dev # 2. session-manager, Agent Kit server and all example agent workers
Open http://localhost:8000 and start a session. There's no install step — the recipes build with Bazel, which fetches dependencies on first run. Every example follows the same four recipes; see Run the examples for the rest of them, including running all eight behind one UI.
Git will note that you're in "detached HEAD" — that's expected, it just means you're sitting on
the tag rather than on a branch. Later, move to a newer release with
git fetch --tags && git checkout <version>, or see what changed between two of them with
git diff 0.12.0 0.12.1.
Build with it — install from PyPI
Use this path to build your own agents in your own project. You don’t need to clone this repository.
Agent Kit is published to
PyPI. In a
uv-managed project:
uv add 'temporal-agent-kit[ui]==0.12.1'
Or declare it in pyproject.toml — an ordinary dependency, no [tool.uv.sources] needed:
[project]
dependencies = [
# Everything past the base install is an opt-in extra — combine as many as you need
# in the one spec, e.g. [ui,code-mode,genai]:
#
# ui the browser UI/API server dependencies
# code-mode the sandbox a worker runs Code Mode scripts in
# genai the Google Gemini integration
# openai-agents the OpenAI Agents SDK integration
# pydantic-ai the Pydantic AI integration
# strands-agents the Strands Agents integration
# typesafe typed decisions and the Jev auto mode evaluator, via the canonical
# temporalio-typesafe plugin
# s3 S3-backed offload for large payloads
#
# What each one pulls in, and when you actually need it, is in the Extras table below.
"temporal-agent-kit[ui]==0.12.1",
]
Then run uv sync. Pin the exact version: this project is pre-1.0 and APIs change between
releases — see Versioning and stability.
Run the web UI — no checkout, no Node
The package installs a temporal-agent-kit command; the ui extra adds its server runtime —
uv run it, the way you would any other project tool. It serves the browser UI built into the
wheel: nothing to clone, nothing to build. One command per terminal:
# 1. A local Temporal dev server (needs the `temporal` CLI). Its own Web UI: http://localhost:8233
temporal server start-dev
# 2. The packaged session-manager worker. It hosts SessionManagerWorkflow, which starts your
# agents as child workflows — without it the server comes up but has nothing to answer
# /api/agents or session creation, since both are workflow queries.
uv run temporal-agent-kit session-manager
# 3. The prebuilt Svelte UI + JSON API on http://localhost:8000
uv run temporal-agent-kit serve ./agents.toml
# 4. Your own worker, hosting your agent workflows on their own task queue
uv run python -m my_app.worker
Open http://localhost:8000 and create a session. serve accepts several registries and merges
them (serve one/agents.toml two/agents.toml), so a single UI can list agents from more than one
project. From the next release, temporal-agent-kit dev ./agents.toml runs steps 2 and 3 in
one process, as the quickstart does.
That registry is what lists the launchable agents:
[[agents]]
key = "my-agent"
workflow_type = "MyAgent"
task_queue = "my-agent-task-queue"
label = "My Agent"
description = "A short description shown in the UI."
schema = "MyAgent.schema.json" # optional; see below
schema is the agent's schema document, relative to the registry, which the
schema subcommand writes from its class:
uv run temporal-agent-kit schema my_app.workflow:MyAgentWorkflow -o MyAgent.schema.json
The server reads what the agent takes to start from it and never imports the agent's code. If its
@agent.init takes a data model after its config, required (data: MyData) or optional
(data: MyData | None = None), GET /api/agents publishes it and the console asks for it in a
form before starting a session. POST /api/sessions answers 422 when data is missing for an
agent that requires it or sent to one that takes none; the agent validates the data itself. Without
schema, any data a caller sends goes through for the agent to validate. Regenerate the schema
when the agent's init data changes. (This repo's examples have Bazel generate each agents.toml
and its schemas; see bazel/agents.bzl.)
Both subcommands resolve their Temporal connection through temporalio's standard client config,
so they land on the same namespace. With nothing configured they use localhost:7233 — the
start-dev default. Note that a temporal.toml in the current directory is not picked up
automatically; point at a project-local file (or a Temporal Cloud profile) explicitly:
TEMPORAL_CONFIG_FILE=./temporal.toml TEMPORAL_PROFILE=cloud \
uv run temporal-agent-kit serve ./agents.toml
uv run temporal-agent-kit --help documents the full precedence order.
Need the API and UI mounted inside your own FastAPI service instead? See Self-hosting the web app.
Extras
Agent authors import the runtime from temporal_agent_kit; the base install carries
only temporalio and pydantic, so nothing drags in an AI SDK you don't use. Everything else is
opt-in:
| Extra | Add it when you… |
|---|---|
ui |
want the browser UI and HTTP API server (pulls in fastapi[standard], including Uvicorn). The built Svelte assets are always in the wheel; only the server runtime is gated here, so agent-worker installs stay small. |
code-mode |
run a worker that hosts Code Mode agents; pulls in pydantic-monty, the sandbox the scripts run in. Importing agent needs nothing extra; building a code_mode_tool does. |
genai |
use the Google Gemini integration (ai_sdks.google_genai_plugin). |
openai-agents |
use the OpenAI Agents SDK integration (ai_sdks.openai_agents). |
pydantic-ai |
use the Pydantic AI integration (ai_sdks.pydantic_ai). |
strands-agents |
use the Strands Agents integration (ai_sdks.strands_agents); pulls in strands-agents and the MCP packages its TemporalMCPClient uses. |
typesafe |
make typed TypeSafe System One calls (ai_sdks.typesafe), or use ai_sdks.jev.jev_evaluator, the Jev-backed auto mode evaluator; pulls in temporalio-typesafe. Register its TypeSafePlugin on the worker, before AgentKitPlugin. |
s3 |
offload large payloads to S3. The default local-filesystem driver needs nothing extra. |
Combine them in one spec, e.g. uv add 'temporal-agent-kit[ui,code-mode,genai]==0.12.1'.
Versioning and stability
Pin to a release. Every release is listed on the releases page and published to PyPI. A release tag marks a commit that is known-good at the moment it was cut: the tests passed, and the published wheel and sdist were built from that commit, browser UI included.
Two artifacts come out of a release, and they pin differently:
- The library — pin an exact version from PyPI (
temporal-agent-kit==0.12.1). - The examples — check out the matching git tag. They are not shipped in the package, so a
PyPI install gives you the library, the packaged UI, and the CLI, but no
examples/tree.
This project is very early and experimental - main may break at any time.
Releases are cut when the maintainers judge the state stable (how). This project is experimental and pre-1.0: APIs will change between releases, without warning. Pinning is what keeps that churn from reaching you unannounced — so pin, and upgrade deliberately when you want to try out new Agent Kit capabilities.
A taste
from datetime import timedelta
from pydantic import BaseModel
from temporalio.contrib.workflow_streams import WorkflowStream
from temporalio.workflow import ActivityConfig
from temporal_agent_kit import AgentWorkflowRunner, agent
from temporal_agent_kit.agent_protocol import AgentConfig, MidTurn, ToolApprovalPolicy
# A durable, activity-backed tool: runs as a retried, observable Temporal activity and
# publishes its own tool_start/tool_end events on the turn stream.
@agent.activity_tool_defn(
activity_config=ActivityConfig(start_to_close_timeout=timedelta(seconds=30)),
)
async def search_flights(origin: str, destination: str, date: str) -> str:
...
# Strongly-typed messages — an agent operation is more than a string in and a string out.
class PlanTrip(BaseModel):
destination: str
nights: int
class Itinerary(BaseModel):
summary: str
total_usd: float
# The agent's own init data, passed after the AgentConfig when a session starts.
class TravelerProfile(BaseModel):
"""Who the agent is planning for."""
name: str
home_airport: str
# @agent.defn makes the class a Temporal workflow and provides its run method, which drives
# the turn loop. Add an optional `@agent.setup` / `@agent.teardown` method for one-time async
# work before the first message or after the agent closes.
@agent.defn
class TravelAgent:
@agent.init
def __init__(self, config: AgentConfig, profile: TravelerProfile | None = None) -> None:
# Tool approvals are safe-by-default; here, auto-approve only tools that
# statically declare themselves inherently safe.
self._runner = AgentWorkflowRunner(
config,
stream=WorkflowStream(),
approval_policy_default=ToolApprovalPolicy.allow_inherently_safe(),
)
# Optional, so a caller may start it without a profile. Declare it without the
# `| None = None` to make it required.
self._profile = profile
# A typed, self-describing operation. The agent advertises this signature, so callers —
# your code or another agent — can drive it programmatically. Your turn logic goes here:
# call your AI SDK, run tools through the runner, and return the typed reply.
# (See examples/monty for a complete, model-in-the-loop agent on the Gemini integration.)
@agent.accepts
async def plan_trip(self, request: PlanTrip) -> Itinerary:
...
Closing idle agents
An agent's workflow stays open between messages until something closes it. While it waits for the next message the agent is idle: no turn is running, and it consumes no compute. A Temporal workflow that is waiting is durable state on the server, not a process spinning on a worker. Staying open is what lets a conversation pick up where it left off, hours or days later.
Some agents are of no use once their user stops interacting with them. Take the agent behind a chat box on a web page whose session is not kept: when the user leaves, nothing will ever send it another message. For an agent like that, give the runner an idle timeout, and it closes the agent once no one has talked to it for that long:
self._runner = AgentWorkflowRunner(
config,
stream=WorkflowStream(),
approval_policy_default=ToolApprovalPolicy.allow_inherently_safe(),
close_after_idle_default=timedelta(minutes=30),
)
In TypeScript, it is defineAgent({ closeAfterIdleDefault: "30 minutes", ... }).
Once the agent has been idle for that long, the runner closes it the same way a close signal
does:
@agent.teardownruns;- the stream's last event is
agent_closedwith reasonidle_timeout_expired, andagent_statusreports the sameclose_reason; - a message sent afterwards is refused with
AgentClosed.
Only idle time counts. A running turn is never idle, even one that waits hours on a tool call, a human approval, or a subagent; the clock starts again from zero each time a turn ends.
A caller can override the agent's default when it starts a session, with
AgentConfig(close_after_idle=...); timedelta(0) means never close on idle. If the user
comes back after their agent has closed, AgentClient.start_and_submit_message starts a new
session under the same workflow id. It starts fresh, without the closed session's conversation.
Subagents never close on idle. This is deliberate: a parent owns the whole lifecycle of its subagents. It may leave a subagent waiting between messages for as long as it likes, and it alone decides when that subagent ends, with
stop_<key>. So whenever a parent starts a subagent, Agent Kit turns the subagent's idle timeout off, overriding any default the subagent's own agent sets.
Running a worker — one plugin
An agent is a Temporal workflow, so it runs on a Temporal worker. AgentKitPlugin is the
single registration that wires that worker (and its client) for Agent Kit — you never
assemble Agent Kit's activity list or its data converter by hand:
from temporalio.client import Client
from temporalio.envconfig import ClientConfig
from temporalio.worker import Worker
from temporal_agent_kit.plugin import AgentKitPlugin
client = await Client.connect(
**ClientConfig.load_client_connect_config(),
# Your AI SDK's plugin first, the Agent Kit plugin last.
plugins=[OpenAIAgentsPlugin(model_params=...), AgentKitPlugin(tools=MY_TOOLS)],
)
worker = Worker(client, task_queue="my-agent", workflows=[TravelAgent])
await worker.run()
The worker declares only its workflows. Adding the plugin brings:
- Agent Kit's data converter (Pydantic + large-payload offload) — add the plugin to every client, worker, and server in the deployment so they all agree on it;
- the durable activity body of each
@agent.activity_tool_defntool intools=(pass your whole toolset — tools with no worker-side body are skipped); - the subagent and Code Mode activities.
Order it last, after any AI SDK's plugin, so that SDK's payload converter wins. Registering it on the client is enough — Temporal applies a client's plugins to workers built from it.
Further reading
Metadata
Release files for temporal-agent-kit 0.12.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Change of provenance
The repository or configuration that created these release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| temporal_agent_kit-0.12.1.tar.gz | 888.9 kB | With provenance | Details for temporal_agent_kit-0.12.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| temporal_agent_kit-0.12.1-py3-none-any.whl | Python 3 | none | any | Details for temporal_agent_kit-0.12.1-py3-none-any.whl |
Total release size: 1.8 MB
Release files / temporal_agent_kit-0.12.1.tar.gz
Change of provenance
This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
| Download URL | temporal_agent_kit-0.12.1.tar.gz |
|---|---|
| Size | 888.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
00e04210b7242578c83c111c42630e7f947e0f49018da6b3ecaf44287395db5d
|
|
BLAKE2b-256 checksum How to use checksums |
82c99e705d7aec91067dceb05e9f6497f4f2fce8edae66ad236a2ccb4ca05e36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / temporal_agent_kit-0.12.1-py3-none-any.whl
Change of provenance
This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
| Download URL | temporal_agent_kit-0.12.1-py3-none-any.whl |
|---|---|
| Size | 957.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c8544756cd72f323a6ca81f92431301f0fc7d89bec057f3b6f3ce7e238645405
|
|
BLAKE2b-256 checksum How to use checksums |
11de61aad21d606b43f96ae97e3337d6f3eee25b5daff2f4a3fb2c624cd6b0c0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for temporal-agent-kit 0.12.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Change of provenance
The repository and configuration that created this release differ from a previous release.
While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.
Repository
Configuration
- Removed 0.12.0 github.com/temporal-community/temporal-agent-harness/blob/90e932a5c927dfb75c98c92cfd088c989d5de5ea/.github/workflows/publish-agent-kit.yml
- Added 0.12.1 github.com/temporal-community/temporal-agent-kit/blob/a9be10fee59c10e74e09c63bdaf4fac9c5c21b2f/.github/workflows/publish-agent-kit.yml
Attestation for temporal_agent_kit-0.12.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.