temporal-agent-kit 0.0.1__tar.gz → 0.12.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- temporal_agent_kit-0.12.0/LICENSE +21 -0
- temporal_agent_kit-0.12.0/PKG-INFO +538 -0
- temporal_agent_kit-0.12.0/README.md +486 -0
- temporal_agent_kit-0.12.0/pyproject.toml +201 -0
- temporal_agent_kit-0.12.0/setup.cfg +4 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/__init__.py +25 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/agent.py +169 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/agent_client.py +694 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/agent_protocol/__init__.py +184 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/agent_protocol/agent_interface.py +1189 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/agent_protocol/events.py +1260 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/agent_protocol/subagent_interface.py +101 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/agent_schema.py +279 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/agent_workflow.py +4303 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/__init__.py +18 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/google_genai_plugin/__init__.py +79 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/google_genai_plugin/_errors.py +81 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/google_genai_plugin/_gemini_activity.py +288 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/google_genai_plugin/_google_genai_plugin.py +98 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/google_genai_plugin/_interactions_activity.py +439 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/google_genai_plugin/_interactions_conversation.py +212 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/google_genai_plugin/_interactions_models.py +31 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/google_genai_plugin/_interactions_workflow.py +56 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/google_genai_plugin/_models.py +121 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/google_genai_plugin/_temporal_api_client.py +292 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/google_genai_plugin/_temporal_async_client.py +64 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/google_genai_plugin/_temporal_file_search_stores.py +109 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/google_genai_plugin/_temporal_files.py +169 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/google_genai_plugin/_temporal_interactions.py +147 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/google_genai_plugin/workflow.py +96 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/integration_helpers/__init__.py +33 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/integration_helpers/_stream_observer.py +170 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/jev/__init__.py +46 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/jev/evaluator.py +554 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/__init__.py +57 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/_heartbeat_decorator.py +38 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/_invoke_model_activity.py +457 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/_kit.py +779 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/_mcp.py +537 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/_model_parameters.py +127 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/_nexus_mcp.py +220 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/_openai_runner.py +377 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/_otel_trace_interceptor.py +96 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/_temporal_model_stub.py +317 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/_temporal_openai_agents.py +425 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/_temporal_trace_provider.py +211 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/_trace_interceptor.py +457 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/sandbox/__init__.py +1 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/sandbox/_sandbox_client_provider.py +285 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/sandbox/_temporal_activity_models.py +218 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/sandbox/_temporal_sandbox_client.py +124 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/sandbox/_temporal_sandbox_session.py +239 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/testing.py +262 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/openai_agents/workflow.py +495 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/pydantic_ai.py +700 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/strands_agents/__init__.py +45 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/strands_agents/_bytes_values.py +142 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/strands_agents/_failure_converter.py +132 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/strands_agents/_heartbeat_decorator.py +38 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/strands_agents/_kit.py +611 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/strands_agents/_model_activity.py +276 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/strands_agents/_plugin.py +264 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/strands_agents/_sandbox_activity.py +358 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/strands_agents/_sync_calls.py +109 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/strands_agents/_temporal_activity_tool.py +299 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/strands_agents/_temporal_agent.py +318 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/strands_agents/_temporal_mcp_client.py +198 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/strands_agents/_temporal_mcp_tool.py +195 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/strands_agents/_temporal_model.py +269 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/strands_agents/_temporal_sandbox.py +204 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/strands_agents/_worker_env_ref.py +86 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/strands_agents/workflow.py +113 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ai_sdks/typesafe.py +98 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/code_mode/__init__.py +82 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/code_mode/_texts.py +7 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/code_mode/activity_fs.py +417 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/code_mode/driver.py +363 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/code_mode/monty_stepper.py +437 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/code_mode/mount_decl.py +301 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/code_mode/okf.py +470 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/code_mode/okf_tool.py +173 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/code_mode/stubs.py +368 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/code_mode/tool.py +279 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/code_mode/vfs.py +912 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/development.py +198 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/nexus_agent_adapter/__init__.py +5 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/nexus_agent_adapter/generated/__init__.py +71 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/nexus_agent_adapter/generated/_definitions.py +553 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/nexus_agent_adapter/generated/models.py +2983 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/nexus_agent_adapter/generated/services.py +91 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/nexus_agent_adapter/handler.py +362 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/nexus_agent_adapter/worker.py +65 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/plugin.py +279 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/skills/temporal-agent-kit-python/SKILL.md +42 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/skills/temporal-agent-kit-python/agents/openai.yaml +4 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/skills/temporal-agent-kit-python/assets/starter/README.md.tmpl +117 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/skills/temporal-agent-kit-python/assets/starter/agents.toml.tmpl +7 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/skills/temporal-agent-kit-python/assets/starter/env.example.tmpl +3 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/skills/temporal-agent-kit-python/assets/starter/gitignore.tmpl +6 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/skills/temporal-agent-kit-python/assets/starter/my_agent/__init__.py.tmpl +0 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/skills/temporal-agent-kit-python/assets/starter/my_agent/worker.py.tmpl +80 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/skills/temporal-agent-kit-python/assets/starter/my_agent/workflow.py.tmpl +83 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/skills/temporal-agent-kit-python/assets/starter/pyproject.toml.tmpl +12 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/skills/temporal-agent-kit-python/references/advanced.md +60 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/skills/temporal-agent-kit-python/references/api.md +110 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/skills/temporal-agent-kit-python/references/authoring.md +76 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/skills/temporal-agent-kit-python/references/verification.md +17 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/state/__init__.py +43 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/state/base.py +580 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/state/containers.py +514 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/state/decl.py +148 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/state/drafts.py +423 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/state/errors.py +39 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/state/events.py +34 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/state/ref.py +179 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/state/session.py +55 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/steering.py +48 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/stream_context.py +40 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/stream_merge/__init__.py +32 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/stream_merge/cursor.py +166 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/stream_merge/gates.py +160 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/stream_merge/merge.py +500 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/subagent_activities.py +358 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/subagent_toolset.py +357 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ui/__init__.py +12 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ui/dist/assets/index-qL8BGF2O.css +1 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ui/dist/assets/index-zr9S-DTS.js +180 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ui/dist/favicon.svg +4 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ui/dist/index.html +14 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/ui/dist/temporal-logo.svg +3 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/utils/__init__.py +6 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/utils/large_payload.py +227 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/utils/task_queue.py +21 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/web/__init__.py +52 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/web/agent_starts.py +51 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/web/app.py +786 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/web/cli.py +357 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/web/client.py +87 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/web/dev.py +69 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/web/doctor.py +56 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/web/file_view.py +156 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/web/registry.py +143 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/web/serve.py +94 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/web/session_manager.py +165 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/web/session_manager_worker.py +90 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/web/task_queue_status.py +158 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit/web/temporal_ui.py +47 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit.egg-info/PKG-INFO +538 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit.egg-info/SOURCES.txt +151 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit.egg-info/dependency_links.txt +1 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit.egg-info/entry_points.txt +2 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit.egg-info/requires.txt +40 -0
- temporal_agent_kit-0.12.0/temporal_agent_kit.egg-info/top_level.txt +1 -0
- temporal_agent_kit-0.0.1/.gitignore +0 -39
- temporal_agent_kit-0.0.1/PKG-INFO +0 -16
- temporal_agent_kit-0.0.1/README.md +0 -5
- temporal_agent_kit-0.0.1/pyproject.toml +0 -19
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Temporal Technologies Inc. All rights reserved.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,538 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: temporal-agent-kit
|
|
3
|
+
Version: 0.12.0
|
|
4
|
+
Summary: Temporal Agent Kit (experimental) — durable agents on Temporal, with the AI SDKs you already use.
|
|
5
|
+
Author: Temporal Technologies Inc.
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/temporal-community/temporal-agent-harness
|
|
8
|
+
Project-URL: Repository, https://github.com/temporal-community/temporal-agent-harness
|
|
9
|
+
Project-URL: Issues, https://github.com/temporal-community/temporal-agent-harness/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/temporal-community/temporal-agent-harness/releases
|
|
11
|
+
Keywords: temporal,workflow,agents,agent-kit,llm,ai
|
|
12
|
+
Classifier: Development Status :: 2 - Pre-Alpha
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
17
|
+
Requires-Python: >=3.11
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Requires-Dist: temporalio>=1.35.0
|
|
21
|
+
Requires-Dist: pydantic>=2.12
|
|
22
|
+
Requires-Dist: pyyaml>=6.0
|
|
23
|
+
Provides-Extra: genai
|
|
24
|
+
Requires-Dist: google-genai>=2.0.0; extra == "genai"
|
|
25
|
+
Requires-Dist: google-auth>=2.53.0; extra == "genai"
|
|
26
|
+
Provides-Extra: s3
|
|
27
|
+
Requires-Dist: temporalio[aioboto3]>=1.35.0; extra == "s3"
|
|
28
|
+
Provides-Extra: openai-agents
|
|
29
|
+
Requires-Dist: openai-agents>=0.22.0; extra == "openai-agents"
|
|
30
|
+
Requires-Dist: mcp<3,>=2.1.1; extra == "openai-agents"
|
|
31
|
+
Requires-Dist: temporalio[opentelemetry]>=1.35.0; extra == "openai-agents"
|
|
32
|
+
Provides-Extra: pydantic-ai
|
|
33
|
+
Requires-Dist: pydantic-ai-slim[temporal]>=2.53; extra == "pydantic-ai"
|
|
34
|
+
Provides-Extra: strands-agents
|
|
35
|
+
Requires-Dist: strands-agents>=1.64.0; extra == "strands-agents"
|
|
36
|
+
Requires-Dist: botocore<2,>=1.40.61; extra == "strands-agents"
|
|
37
|
+
Requires-Dist: mcp<3,>=2.1.1; extra == "strands-agents"
|
|
38
|
+
Requires-Dist: mcp-types<3,>=2.2.0; extra == "strands-agents"
|
|
39
|
+
Requires-Dist: temporalio-mcp<0.3,>=0.2.0; extra == "strands-agents"
|
|
40
|
+
Provides-Extra: ui
|
|
41
|
+
Requires-Dist: fastapi[standard]>=0.136.3; extra == "ui"
|
|
42
|
+
Provides-Extra: code-mode
|
|
43
|
+
Requires-Dist: pydantic-monty==1.0.0; extra == "code-mode"
|
|
44
|
+
Provides-Extra: nexus-mcp
|
|
45
|
+
Requires-Dist: temporal-nexus-mcp; extra == "nexus-mcp"
|
|
46
|
+
Requires-Dist: openai-agents>=0.22.0; extra == "nexus-mcp"
|
|
47
|
+
Requires-Dist: mcp<3,>=2.1.1; extra == "nexus-mcp"
|
|
48
|
+
Requires-Dist: temporalio[opentelemetry]>=1.35.0; extra == "nexus-mcp"
|
|
49
|
+
Provides-Extra: typesafe
|
|
50
|
+
Requires-Dist: temporalio-typesafe<0.1,>=0.0.1; extra == "typesafe"
|
|
51
|
+
Dynamic: license-file
|
|
52
|
+
|
|
53
|
+
# Temporal Agent Kit for Python
|
|
54
|
+
|
|
55
|
+
Build durable agents using Python, Temporal, and your preferred AI SDK.
|
|
56
|
+
|
|
57
|
+
[Project overview](https://github.com/temporal-community/temporal-agent-harness/blob/main/README.md) · [TypeScript guide](https://github.com/temporal-community/temporal-agent-harness/blob/main/typescript/packages/core/README.md) · [Harness API](https://github.com/temporal-community/temporal-agent-harness/blob/main/docs/api/README.md)
|
|
58
|
+
|
|
59
|
+
<a id="coding-agent-setup-and-starter"></a>
|
|
60
|
+
|
|
61
|
+
## Quickstart
|
|
62
|
+
|
|
63
|
+
Create an agent, install its coding-agent skill, and open a working session in four steps.
|
|
64
|
+
No repository checkout or Bazel installation is needed.
|
|
65
|
+
|
|
66
|
+
> **Available with the next Python release.** The `init`, `skills`, `dev`, and `doctor` commands
|
|
67
|
+
> are not in the published 0.8.0 package. Once the new release is published, the `@latest`
|
|
68
|
+
> command below selects it. Until then, use the [manual setup](#build-with-it--install-from-pypi)
|
|
69
|
+
> with published packages.
|
|
70
|
+
|
|
71
|
+
You need **Python 3.11+**, [uv](https://docs.astral.sh/uv/getting-started/installation/), the
|
|
72
|
+
[Temporal CLI](https://docs.temporal.io/cli), and an OpenAI API key for the starter's `ask` handler.
|
|
73
|
+
|
|
74
|
+
### 1. Create the project
|
|
75
|
+
|
|
76
|
+
Run this from the directory where you want the new project:
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
uvx temporal-agent-kit@latest init my-agent
|
|
80
|
+
cd my-agent
|
|
81
|
+
uv sync
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
`uvx` supplies the CLI before you have a project. `init` creates `my_agent/workflow.py`,
|
|
85
|
+
`my_agent/worker.py`, `agents.toml`, a `pyproject.toml` named after the directory, and a README.
|
|
86
|
+
It pins the installed Agent Kit version with the `ui` and `openai-agents` extras and refuses to
|
|
87
|
+
overwrite existing files. `uv sync` installs the project and its dependencies. The starter's
|
|
88
|
+
weather tool returns sample data.
|
|
89
|
+
|
|
90
|
+
### 2. Configure it and install the skill
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
cp env.example .env.local
|
|
94
|
+
uv run temporal-agent-kit schema my_agent.workflow:OpenAIHelloAgentWorkflow -o agent.schema.json
|
|
95
|
+
uv run temporal-agent-kit skills install # asks which coding agents to install the skill for
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
`.env.local` is where `OPENAI_API_KEY` goes once you try `ask`; never commit it. `schema` exports
|
|
99
|
+
your agent's handlers and types to `agent.schema.json`. `skills install` asks which coding agents
|
|
100
|
+
you use and copies this SDK release's skill, with authoring, API, advanced-feature, and
|
|
101
|
+
verification references, into the directories they read:
|
|
102
|
+
|
|
103
|
+
| Choice | `--for` | Skill directory | Read by |
|
|
104
|
+
| --- | --- | --- | --- |
|
|
105
|
+
| 1 | `claude` | `.claude/skills` | Claude Code |
|
|
106
|
+
| 2 | `agents` | `.agents/skills` | Codex and other agents that read the shared `.agents/skills` directory |
|
|
107
|
+
|
|
108
|
+
Choose both if you use Claude Code alongside another agent. To skip the question, as in scripts,
|
|
109
|
+
pass the choices: `skills install --for claude --for agents`.
|
|
110
|
+
Installing the Python package bundles the
|
|
111
|
+
skill; this explicit step makes it discoverable in your project. For a tool with another skill
|
|
112
|
+
directory, run `uv run temporal-agent-kit skills path` to locate the bundled resources, or
|
|
113
|
+
use `skills install --dest <directory>`.
|
|
114
|
+
|
|
115
|
+
### 3. Start the three services
|
|
116
|
+
|
|
117
|
+
Run each command in its own terminal, all from this project directory:
|
|
118
|
+
|
|
119
|
+
**Terminal 1 — Temporal service** (skip if your configured Temporal service is already running):
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
temporal server start-dev
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
**Terminal 2 — shared session manager, API, and Agent Kit console:**
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
uv run temporal-agent-kit dev agents.toml
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
**Terminal 3 — your Python agent worker:**
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
uv run --env-file .env.local python -m my_agent.worker
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
The console is prebuilt in the Python package; no Node.js or frontend build is needed. `dev` runs
|
|
138
|
+
the session-manager worker and the API/console server in one process; `session-manager` and
|
|
139
|
+
`serve` remain available as separate commands for deployments. Defaults are `localhost:7233` and
|
|
140
|
+
namespace `default`. For another Temporal service, export the same `TEMPORAL_*` connection
|
|
141
|
+
settings in each service terminal. `.env.local` above loads only into the agent worker. Keep
|
|
142
|
+
`TASK_QUEUE_PREFIX` consistent across services. Keep all three processes running.
|
|
143
|
+
|
|
144
|
+
### 4. Verify, then develop with your coding agent
|
|
145
|
+
|
|
146
|
+
1. Open the **Agent Kit console at <http://localhost:8000>**. Create a session for
|
|
147
|
+
**OpenAI Hello (Python)**.
|
|
148
|
+
2. Send a `ping` message. The message box's handler button names the handler your
|
|
149
|
+
message goes to; a new session starts on `ping`. Type any text, such as `hello`,
|
|
150
|
+
and press Enter. Expect the same text back without a model request or an API key.
|
|
151
|
+
3. Send an `ask` message. This step calls OpenAI:
|
|
152
|
+
1. Set `OPENAI_API_KEY` in `.env.local`.
|
|
153
|
+
2. Restart the worker so it reads the key, which it loads only at startup: in Terminal 3,
|
|
154
|
+
press Ctrl+C, then run `uv run --env-file .env.local python -m my_agent.worker` again.
|
|
155
|
+
Leave the other services running; your session picks up where it left off once
|
|
156
|
+
the worker is back.
|
|
157
|
+
3. Switch the message box to `ask`: click the handler button (it shows `ping`) and choose
|
|
158
|
+
`ask`, or type `/` in the message box and pick `ask` from the list. The button now shows
|
|
159
|
+
`ask`, and later messages go to `ask` until you switch again.
|
|
160
|
+
4. Send **“What's the weather in Paris?”**. Expect a streamed reply and a completed
|
|
161
|
+
`get_weather` tool trace with sample weather data.
|
|
162
|
+
4. Reload the page and confirm the session reconnects.
|
|
163
|
+
5. Check configuration and service availability:
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
uv run temporal-agent-kit doctor --registry agents.toml
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Add `--json` for a machine-readable report. The doctor checks the registry and schemas, Temporal
|
|
170
|
+
connectivity, task queue pollers, and the API without creating or resetting sessions. A failed
|
|
171
|
+
check exits 1. Temporal's own workflow UI is at <http://localhost:8233>; it is separate from the
|
|
172
|
+
Agent Kit console.
|
|
173
|
+
|
|
174
|
+
With the services running, open the project in your coding agent. Reload its session if it was
|
|
175
|
+
already running, then ask it to use the skill:
|
|
176
|
+
|
|
177
|
+
| Tool | Prompt |
|
|
178
|
+
| --- | --- |
|
|
179
|
+
| Codex | `Use $temporal-agent-kit-python to help me build this agent. Explain the starter, then verify it with ping before making model calls.` |
|
|
180
|
+
| Claude Code | `/temporal-agent-kit-python Explain the starter, then verify it with ping before making model calls.` |
|
|
181
|
+
|
|
182
|
+
Edit `my_agent/workflow.py` to change your agent and `my_agent/worker.py` for worker configuration.
|
|
183
|
+
After changes, stop the worker, regenerate the schema with the command in step 2, and restart
|
|
184
|
+
it with the command in step 3. Use a new session for changed workflow behavior.
|
|
185
|
+
Commit `agent.schema.json` and `uv.lock`.
|
|
186
|
+
|
|
187
|
+
After upgrading the SDK, rerun the `skills install` commands to update unchanged skill files.
|
|
188
|
+
Local edits produce a conflict and are preserved. Application-client guidance is in the installed
|
|
189
|
+
skill's `references/api.md`.
|
|
190
|
+
|
|
191
|
+
See [coding-agent development](https://github.com/temporal-community/temporal-agent-harness/blob/main/docs/agent-development.md)
|
|
192
|
+
for skill discovery and updates. The `init`, `skills`, and `doctor` commands ship with the base
|
|
193
|
+
package; `dev`, `serve`, and OpenAPI export require the `ui` extra.
|
|
194
|
+
|
|
195
|
+
<a id="installation"></a>
|
|
196
|
+
|
|
197
|
+
## Installation and manual reference
|
|
198
|
+
|
|
199
|
+
For a new application, start with the [four-step quickstart](#quickstart) above.
|
|
200
|
+
The reference below covers existing projects, model integration extras, and repository examples.
|
|
201
|
+
|
|
202
|
+
### Try the example agents
|
|
203
|
+
|
|
204
|
+
Clone at a release tag. You need [just](https://just.systems/),
|
|
205
|
+
[Bazelisk](https://github.com/bazelbuild/bazelisk) installed as `bazel`, and the
|
|
206
|
+
[`temporal` CLI](https://docs.temporal.io/cli) (see [Requirements](https://github.com/temporal-community/temporal-agent-harness/blob/main/docs/guides/examples.md#requirements)).
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
git clone --branch 0.12.0 https://github.com/temporal-community/temporal-agent-harness.git
|
|
210
|
+
cd temporal-agent-kit
|
|
211
|
+
cp .env.example .env.local # then set GEMINI_API_KEY (and/or OPENAI_API_KEY)
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Then run two commands in separate terminals to get going with all example agents:
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
just temporal # 1. local Temporal dev server (needs the `temporal` CLI)
|
|
218
|
+
just dev # 2. session-manager, Agent Kit server and all example agent workers
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Open <http://localhost:8000> and start a session. There's no install step — the recipes build with
|
|
222
|
+
Bazel, which fetches dependencies on first run. Every example follows the same four recipes; see
|
|
223
|
+
[Run the examples](https://github.com/temporal-community/temporal-agent-harness/blob/main/docs/guides/examples.md#run-the-examples) for the rest of them, including running all eight behind
|
|
224
|
+
one UI.
|
|
225
|
+
|
|
226
|
+
Git will note that you're in "detached HEAD" — that's expected, it just means you're sitting on
|
|
227
|
+
the tag rather than on a branch. Later, move to a newer release with
|
|
228
|
+
`git fetch --tags && git checkout <version>`, or see what changed between two of them with
|
|
229
|
+
`git diff 0.11.0 0.12.0`.
|
|
230
|
+
|
|
231
|
+
### Build with it — install from PyPI
|
|
232
|
+
|
|
233
|
+
Use this path to build your own agents in your own project. You don’t need to clone this repository.
|
|
234
|
+
|
|
235
|
+
Agent Kit is published to
|
|
236
|
+
[PyPI](https://pypi.org/project/temporal-agent-kit/). In a
|
|
237
|
+
[`uv`](https://docs.astral.sh/uv/)-managed project:
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
uv add 'temporal-agent-kit[ui]==0.12.0'
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
Or declare it in `pyproject.toml` — an ordinary dependency, no `[tool.uv.sources]` needed:
|
|
244
|
+
|
|
245
|
+
```toml
|
|
246
|
+
[project]
|
|
247
|
+
dependencies = [
|
|
248
|
+
# Everything past the base install is an opt-in extra — combine as many as you need
|
|
249
|
+
# in the one spec, e.g. [ui,code-mode,genai]:
|
|
250
|
+
#
|
|
251
|
+
# ui the browser UI/API server dependencies
|
|
252
|
+
# code-mode the sandbox a worker runs Code Mode scripts in
|
|
253
|
+
# genai the Google Gemini integration
|
|
254
|
+
# openai-agents the OpenAI Agents SDK integration
|
|
255
|
+
# pydantic-ai the Pydantic AI integration
|
|
256
|
+
# strands-agents the Strands Agents integration
|
|
257
|
+
# typesafe typed decisions and the Jev auto mode evaluator, via the canonical
|
|
258
|
+
# temporalio-typesafe plugin
|
|
259
|
+
# s3 S3-backed offload for large payloads
|
|
260
|
+
#
|
|
261
|
+
# What each one pulls in, and when you actually need it, is in the Extras table below.
|
|
262
|
+
"temporal-agent-kit[ui]==0.12.0",
|
|
263
|
+
]
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
Then run `uv sync`. Pin the exact version: this project is pre-1.0 and APIs change between
|
|
267
|
+
releases — see [Versioning and stability](#versioning-and-stability).
|
|
268
|
+
|
|
269
|
+
#### Run the web UI — no checkout, no Node
|
|
270
|
+
|
|
271
|
+
The package installs a `temporal-agent-kit` command; the `ui` extra adds its server runtime —
|
|
272
|
+
`uv run` it, the way you would any other project tool. It serves the browser UI built into the
|
|
273
|
+
wheel: nothing to clone, nothing to build. One command per terminal:
|
|
274
|
+
|
|
275
|
+
```bash
|
|
276
|
+
# 1. A local Temporal dev server (needs the `temporal` CLI). Its own Web UI: http://localhost:8233
|
|
277
|
+
temporal server start-dev
|
|
278
|
+
|
|
279
|
+
# 2. The packaged session-manager worker. It hosts SessionManagerWorkflow, which starts your
|
|
280
|
+
# agents as child workflows — without it the server comes up but has nothing to answer
|
|
281
|
+
# /api/agents or session creation, since both are workflow queries.
|
|
282
|
+
uv run temporal-agent-kit session-manager
|
|
283
|
+
|
|
284
|
+
# 3. The prebuilt Svelte UI + JSON API on http://localhost:8000
|
|
285
|
+
uv run temporal-agent-kit serve ./agents.toml
|
|
286
|
+
|
|
287
|
+
# 4. Your own worker, hosting your agent workflows on their own task queue
|
|
288
|
+
uv run python -m my_app.worker
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
Open <http://localhost:8000> and create a session. `serve` accepts several registries and merges
|
|
292
|
+
them (`serve one/agents.toml two/agents.toml`), so a single UI can list agents from more than one
|
|
293
|
+
project. From the next release, `temporal-agent-kit dev ./agents.toml` runs steps 2 and 3 in
|
|
294
|
+
one process, as the quickstart does.
|
|
295
|
+
|
|
296
|
+
That registry is what lists the launchable agents:
|
|
297
|
+
|
|
298
|
+
```toml
|
|
299
|
+
[[agents]]
|
|
300
|
+
key = "my-agent"
|
|
301
|
+
workflow_type = "MyAgent"
|
|
302
|
+
task_queue = "my-agent-task-queue"
|
|
303
|
+
label = "My Agent"
|
|
304
|
+
description = "A short description shown in the UI."
|
|
305
|
+
schema = "MyAgent.schema.json" # optional; see below
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
`schema` is the agent's schema document, relative to the registry, which the
|
|
309
|
+
`schema` subcommand writes from its class:
|
|
310
|
+
|
|
311
|
+
```bash
|
|
312
|
+
uv run temporal-agent-kit schema my_app.workflow:MyAgentWorkflow -o MyAgent.schema.json
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
The server reads what the agent takes to start from it and never imports the agent's code. If its
|
|
316
|
+
`@agent.init` takes a `data` model after its config, required (`data: MyData`) or optional
|
|
317
|
+
(`data: MyData | None = None`), `GET /api/agents` publishes it and the console asks for it in a
|
|
318
|
+
form before starting a session. `POST /api/sessions` answers `422` when `data` is missing for an
|
|
319
|
+
agent that requires it or sent to one that takes none; the agent validates the data itself. Without
|
|
320
|
+
`schema`, any `data` a caller sends goes through for the agent to validate. Regenerate the schema
|
|
321
|
+
when the agent's init data changes. (This repo's examples have Bazel generate each `agents.toml`
|
|
322
|
+
and its schemas; see `bazel/agents.bzl`.)
|
|
323
|
+
|
|
324
|
+
Both subcommands resolve their Temporal connection through temporalio's standard client config,
|
|
325
|
+
so they land on the same namespace. With nothing configured they use `localhost:7233` — the
|
|
326
|
+
`start-dev` default. Note that a `temporal.toml` in the **current directory is not picked up
|
|
327
|
+
automatically**; point at a project-local file (or a Temporal Cloud profile) explicitly:
|
|
328
|
+
|
|
329
|
+
```bash
|
|
330
|
+
TEMPORAL_CONFIG_FILE=./temporal.toml TEMPORAL_PROFILE=cloud \
|
|
331
|
+
uv run temporal-agent-kit serve ./agents.toml
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
`uv run temporal-agent-kit --help` documents the full precedence order.
|
|
335
|
+
|
|
336
|
+
Need the API and UI mounted inside your own FastAPI service instead? See
|
|
337
|
+
[Self-hosting the web app](https://github.com/temporal-community/temporal-agent-harness/blob/main/docs/api/hosting.md#self-hosting-the-web-app).
|
|
338
|
+
|
|
339
|
+
#### Extras
|
|
340
|
+
|
|
341
|
+
Agent authors import the runtime from `temporal_agent_kit`; the base install carries
|
|
342
|
+
only `temporalio` and `pydantic`, so nothing drags in an AI SDK you don't use. Everything else is
|
|
343
|
+
opt-in:
|
|
344
|
+
|
|
345
|
+
| Extra | Add it when you… |
|
|
346
|
+
| --- | --- |
|
|
347
|
+
| `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. |
|
|
348
|
+
| `code-mode` | run a worker that hosts **Code Mode** agents; pulls in [`pydantic-monty`](https://pypi.org/project/pydantic-monty/), the sandbox the scripts run in. Importing `agent` needs nothing extra; building a `code_mode_tool` does. |
|
|
349
|
+
| `genai` | use the **Google Gemini** integration (`ai_sdks.google_genai_plugin`). |
|
|
350
|
+
| `openai-agents` | use the **OpenAI Agents SDK** integration (`ai_sdks.openai_agents`). |
|
|
351
|
+
| `pydantic-ai` | use the **Pydantic AI** integration (`ai_sdks.pydantic_ai`). |
|
|
352
|
+
| `strands-agents` | use the **Strands Agents** integration (`ai_sdks.strands_agents`); pulls in `strands-agents` and the MCP packages its `TemporalMCPClient` uses. |
|
|
353
|
+
| `typesafe` | make typed [TypeSafe](https://docs.typesafe.ai) System One calls (`ai_sdks.typesafe`), or use **`ai_sdks.jev.jev_evaluator`**, the Jev-backed auto mode evaluator; pulls in [`temporalio-typesafe`](https://pypi.org/project/temporalio-typesafe/). Register its `TypeSafePlugin` on the worker, before `AgentKitPlugin`. |
|
|
354
|
+
| `s3` | offload large payloads to S3. The default local-filesystem driver needs nothing extra. |
|
|
355
|
+
|
|
356
|
+
Combine them in one spec, e.g. `uv add 'temporal-agent-kit[ui,code-mode,genai]==0.12.0'`.
|
|
357
|
+
|
|
358
|
+
|
|
359
|
+
## Versioning and stability
|
|
360
|
+
|
|
361
|
+
**Pin to a release.** Every release is listed on the
|
|
362
|
+
[releases page](https://github.com/temporal-community/temporal-agent-harness/releases) and
|
|
363
|
+
published to [PyPI](https://pypi.org/project/temporal-agent-kit/). A release tag marks a
|
|
364
|
+
commit that is known-good at the moment it was cut: the tests passed, and the published wheel and
|
|
365
|
+
sdist were built from that commit, browser UI included.
|
|
366
|
+
|
|
367
|
+
Two artifacts come out of a release, and they pin differently:
|
|
368
|
+
|
|
369
|
+
- **The library** — pin an exact version from PyPI (`temporal-agent-kit==0.12.0`).
|
|
370
|
+
- **The examples** — check out the matching git tag. They are *not* shipped in the package, so a
|
|
371
|
+
PyPI install gives you the library, the packaged UI, and the CLI, but no `examples/` tree.
|
|
372
|
+
|
|
373
|
+
**This project is very early and experimental - `main` may break at any time.**
|
|
374
|
+
|
|
375
|
+
Releases are cut when the maintainers judge the state stable ([how](https://github.com/temporal-community/temporal-agent-harness/blob/main/RELEASE.md)). This project is
|
|
376
|
+
**experimental** and pre-1.0: APIs will change between releases, without warning. Pinning is what
|
|
377
|
+
keeps that churn from reaching you unannounced — so pin, and upgrade deliberately when you want
|
|
378
|
+
to try out new Agent Kit capabilities.
|
|
379
|
+
|
|
380
|
+
|
|
381
|
+
## A taste
|
|
382
|
+
|
|
383
|
+
```python
|
|
384
|
+
from datetime import timedelta
|
|
385
|
+
|
|
386
|
+
from pydantic import BaseModel
|
|
387
|
+
from temporalio.contrib.workflow_streams import WorkflowStream
|
|
388
|
+
from temporalio.workflow import ActivityConfig
|
|
389
|
+
|
|
390
|
+
from temporal_agent_kit import AgentWorkflowRunner, agent
|
|
391
|
+
from temporal_agent_kit.agent_protocol import AgentConfig, MidTurn, ToolApprovalPolicy
|
|
392
|
+
|
|
393
|
+
|
|
394
|
+
# A durable, activity-backed tool: runs as a retried, observable Temporal activity and
|
|
395
|
+
# publishes its own tool_start/tool_end events on the turn stream.
|
|
396
|
+
@agent.activity_tool_defn(
|
|
397
|
+
activity_config=ActivityConfig(start_to_close_timeout=timedelta(seconds=30)),
|
|
398
|
+
)
|
|
399
|
+
async def search_flights(origin: str, destination: str, date: str) -> str:
|
|
400
|
+
...
|
|
401
|
+
|
|
402
|
+
|
|
403
|
+
# Strongly-typed messages — an agent operation is more than a string in and a string out.
|
|
404
|
+
class PlanTrip(BaseModel):
|
|
405
|
+
destination: str
|
|
406
|
+
nights: int
|
|
407
|
+
|
|
408
|
+
|
|
409
|
+
class Itinerary(BaseModel):
|
|
410
|
+
summary: str
|
|
411
|
+
total_usd: float
|
|
412
|
+
|
|
413
|
+
|
|
414
|
+
# The agent's own init data, passed after the AgentConfig when a session starts.
|
|
415
|
+
class TravelerProfile(BaseModel):
|
|
416
|
+
"""Who the agent is planning for."""
|
|
417
|
+
|
|
418
|
+
name: str
|
|
419
|
+
home_airport: str
|
|
420
|
+
|
|
421
|
+
|
|
422
|
+
# @agent.defn makes the class a Temporal workflow and provides its run method, which drives
|
|
423
|
+
# the turn loop. Add an optional `@agent.setup` / `@agent.teardown` method for one-time async
|
|
424
|
+
# work before the first message or after the agent closes.
|
|
425
|
+
@agent.defn
|
|
426
|
+
class TravelAgent:
|
|
427
|
+
@agent.init
|
|
428
|
+
def __init__(self, config: AgentConfig, profile: TravelerProfile | None = None) -> None:
|
|
429
|
+
# Tool approvals are safe-by-default; here, auto-approve only tools that
|
|
430
|
+
# statically declare themselves inherently safe.
|
|
431
|
+
self._runner = AgentWorkflowRunner(
|
|
432
|
+
config,
|
|
433
|
+
stream=WorkflowStream(),
|
|
434
|
+
approval_policy_default=ToolApprovalPolicy.allow_inherently_safe(),
|
|
435
|
+
)
|
|
436
|
+
# Optional, so a caller may start it without a profile. Declare it without the
|
|
437
|
+
# `| None = None` to make it required.
|
|
438
|
+
self._profile = profile
|
|
439
|
+
|
|
440
|
+
# A typed, self-describing operation. The agent advertises this signature, so callers —
|
|
441
|
+
# your code or another agent — can drive it programmatically. Your turn logic goes here:
|
|
442
|
+
# call your AI SDK, run tools through the runner, and return the typed reply.
|
|
443
|
+
# (See examples/monty for a complete, model-in-the-loop agent on the Gemini integration.)
|
|
444
|
+
@agent.accepts
|
|
445
|
+
async def plan_trip(self, request: PlanTrip) -> Itinerary:
|
|
446
|
+
...
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
|
|
450
|
+
### Closing idle agents
|
|
451
|
+
|
|
452
|
+
An agent's workflow stays open between messages until something closes it. While it waits for
|
|
453
|
+
the next message the agent is *idle*: no turn is running, and it consumes no compute. A Temporal
|
|
454
|
+
workflow that is waiting is durable state on the server, not a process spinning on a worker.
|
|
455
|
+
Staying open is what lets a conversation pick up where it left off, hours or days later.
|
|
456
|
+
|
|
457
|
+
Some agents are of no use once their user stops interacting with them. Take the agent behind a
|
|
458
|
+
chat box on a web page whose session is not kept: when the user leaves, nothing will ever send
|
|
459
|
+
it another message. For an agent like that, give the runner an idle timeout, and it closes the
|
|
460
|
+
agent once no one has talked to it for that long:
|
|
461
|
+
|
|
462
|
+
```python
|
|
463
|
+
self._runner = AgentWorkflowRunner(
|
|
464
|
+
config,
|
|
465
|
+
stream=WorkflowStream(),
|
|
466
|
+
approval_policy_default=ToolApprovalPolicy.allow_inherently_safe(),
|
|
467
|
+
close_after_idle_default=timedelta(minutes=30),
|
|
468
|
+
)
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
In TypeScript, it is `defineAgent({ closeAfterIdleDefault: "30 minutes", ... })`.
|
|
472
|
+
|
|
473
|
+
Once the agent has been idle for that long, the runner closes it the same way a `close` signal
|
|
474
|
+
does:
|
|
475
|
+
|
|
476
|
+
- `@agent.teardown` runs;
|
|
477
|
+
- the stream's last event is `agent_closed` with reason `idle_timeout_expired`, and
|
|
478
|
+
`agent_status` reports the same `close_reason`;
|
|
479
|
+
- a message sent afterwards is refused with `AgentClosed`.
|
|
480
|
+
|
|
481
|
+
Only idle time counts. A running turn is never idle, even one that waits hours on a tool call,
|
|
482
|
+
a human approval, or a subagent; the clock starts again from zero each time a turn ends.
|
|
483
|
+
|
|
484
|
+
A caller can override the agent's default when it starts a session, with
|
|
485
|
+
`AgentConfig(close_after_idle=...)`; `timedelta(0)` means never close on idle. If the user
|
|
486
|
+
comes back after their agent has closed, `AgentClient.start_and_submit_message` starts a new
|
|
487
|
+
session under the same workflow id. It starts fresh, without the closed session's conversation.
|
|
488
|
+
|
|
489
|
+
> **Subagents never close on idle.** This is deliberate: a parent owns the whole lifecycle of
|
|
490
|
+
> its subagents. It may leave a subagent waiting between messages for as long as it likes, and
|
|
491
|
+
> it alone decides when that subagent ends, with `stop_<key>`. So whenever a parent starts a
|
|
492
|
+
> subagent, Agent Kit turns the subagent's idle timeout off, overriding any default the
|
|
493
|
+
> subagent's own agent sets.
|
|
494
|
+
|
|
495
|
+
## Running a worker — one plugin
|
|
496
|
+
|
|
497
|
+
An agent is a Temporal workflow, so it runs on a Temporal worker. `AgentKitPlugin` is the
|
|
498
|
+
single registration that wires that worker (and its client) for Agent Kit — you never
|
|
499
|
+
assemble Agent Kit's activity list or its data converter by hand:
|
|
500
|
+
|
|
501
|
+
```python
|
|
502
|
+
from temporalio.client import Client
|
|
503
|
+
from temporalio.envconfig import ClientConfig
|
|
504
|
+
from temporalio.worker import Worker
|
|
505
|
+
|
|
506
|
+
from temporal_agent_kit.plugin import AgentKitPlugin
|
|
507
|
+
|
|
508
|
+
client = await Client.connect(
|
|
509
|
+
**ClientConfig.load_client_connect_config(),
|
|
510
|
+
# Your AI SDK's plugin first, the Agent Kit plugin last.
|
|
511
|
+
plugins=[OpenAIAgentsPlugin(model_params=...), AgentKitPlugin(tools=MY_TOOLS)],
|
|
512
|
+
)
|
|
513
|
+
|
|
514
|
+
worker = Worker(client, task_queue="my-agent", workflows=[TravelAgent])
|
|
515
|
+
await worker.run()
|
|
516
|
+
```
|
|
517
|
+
|
|
518
|
+
The worker declares only its workflows. Adding the plugin brings:
|
|
519
|
+
|
|
520
|
+
- Agent Kit's **data converter** (Pydantic + large-payload offload) — add the plugin to every
|
|
521
|
+
client, worker, and server in the deployment so they all agree on it;
|
|
522
|
+
- the durable **activity body** of each `@agent.activity_tool_defn` tool in `tools=` (pass your
|
|
523
|
+
whole toolset — tools with no worker-side body are skipped);
|
|
524
|
+
- the **subagent** and **Code Mode** activities.
|
|
525
|
+
|
|
526
|
+
Order it last, after any AI SDK's plugin, so that SDK's payload converter wins. Registering it
|
|
527
|
+
on the client is enough — Temporal applies a client's plugins to workers built from it.
|
|
528
|
+
|
|
529
|
+
|
|
530
|
+
## Further reading
|
|
531
|
+
|
|
532
|
+
- [Harness API and session lifecycle](https://github.com/temporal-community/temporal-agent-harness/blob/main/docs/api/README.md)
|
|
533
|
+
- [Messages and handler behavior](https://github.com/temporal-community/temporal-agent-harness/blob/main/docs/guides/messages.md)
|
|
534
|
+
- [Approvals and auto mode](https://github.com/temporal-community/temporal-agent-harness/blob/main/docs/guides/approvals.md)
|
|
535
|
+
- [Code Mode, files, and subagents](https://github.com/temporal-community/temporal-agent-harness/blob/main/docs/guides/code-mode.md)
|
|
536
|
+
- [Build a React or Svelte UI](https://github.com/temporal-community/temporal-agent-harness/blob/main/docs/guides/client-ui.md)
|
|
537
|
+
- [Run the repository examples](https://github.com/temporal-community/temporal-agent-harness/blob/main/docs/guides/examples.md)
|
|
538
|
+
- [Embed the web app in FastAPI](https://github.com/temporal-community/temporal-agent-harness/blob/main/docs/api/hosting.md)
|