# temporal-community/temporal-agent-kit architecture

> Architecture diagram of the GitHub repository temporal-community/temporal-agent-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/temporal-community/temporal-agent-kit
- Repository: https://github.com/temporal-community/temporal-agent-kit
- Video tour (about a minute): https://gitdiagram.com/temporal-community/temporal-agent-kit/video

## Overview

Temporal Agent Kit is a Python and TypeScript toolkit for building AI agents as durable Temporal workflows. A user or application submits typed messages through an SDK client; the workflow runs agent behavior, streams events, and can pause for approvals or callbacks. Workers and model plugins connect agent code to Temporal, while the Python harness API and session manager support launching and inspecting sessions in the console. The repository also contains Code Mode, typed UI clients, and Nexus/Chat integrations. Some subsystem paths are present in the tree but were not sampled, so their internal wiring is omitted.

Main entry points: [`python/temporal_agent_kit/agent_workflow.py`](https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/agent_workflow.py) (Agent Workflow), [`python/temporal_agent_kit/plugin.py`](https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/plugin.py) (Worker Plugins), [`nexus/ui_connector/router/workflow.go`](https://github.com/temporal-community/temporal-agent-kit/blob/main/nexus/ui_connector/router/workflow.go) (Connector Router), [`python/temporal_agent_kit/agent_client.py`](https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/agent_client.py) (Agent Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent Runtime"]
  node_agent_workflow["Agent Workflow<br/>[agent_workflow.py]"]
  node_agent_protocol["Typed Protocol<br/>[agent_interface.py]"]
  node_agent_events["Stream Events<br/>[events.py]"]
  node_agent_client["Agent Client<br/>[agent_client.py]"]
  node_stream_merge["Stream Merge<br/>[merge.py]"]
  node_agent_state["Agent State<br/>[session.py]"]
  node_code_mode["Code Mode<br/>[driver.py]"]
end

subgraph group_integrations["Agent Integrations"]
  node_plugin["Worker Plugins<br/>[plugin.py]"]
  node_openai_plugin["OpenAI Agents<br/>[_kit.py]"]
  node_google_plugin["Google GenAI"]
  node_strands_plugin["Strands Agents<br/>[_plugin.py]"]
end

subgraph group_harness["Harness Services"]
  node_web_api["Harness API<br/>[app.py]"]
  node_session_manager["Session Manager<br/>[session_manager.py]"]
  node_session_worker["Manager Worker"]
end

subgraph group_interfaces["User Interfaces"]
  node_console["Agent Console<br/>[App.svelte]"]
  node_typed_client["Typed Client<br/>[session.ts]"]
end

subgraph group_connectors["Nexus and Connectors"]
  node_nexus_resolver["Nexus Resolver<br/>[resolver.py]"]
  node_mcp_gateway["MCP Gateway"]
  node_connector_router["Connector Router<br/>[workflow.go]"]
  node_slack_inbound["Slack Webhook<br/>[server.go]"]
  node_linear_inbound["Linear Webhook<br/>[server.go]"]
  node_teams_inbound["Teams Webhook<br/>[server.go]"]
end

node_user(("User or App"))
node_temporal["Temporal Service"]

node_user -->|"uses"| node_console
node_console -->|"calls"| node_web_api
node_web_api -->|"uses"| node_temporal
node_session_worker -->|"hosts manager"| node_temporal
node_agent_workflow -->|"runs on"| node_temporal
node_agent_workflow -->|"uses types"| node_agent_protocol
node_agent_workflow -->|"uses events"| node_agent_events
node_agent_workflow -->|"uses state"| node_agent_state
node_agent_workflow -->|"integrates via"| node_plugin
node_agent_client -->|"uses types"| node_agent_protocol
node_agent_client -->|"merges streams"| node_stream_merge
node_plugin -.->|"includes"| node_openai_plugin
node_plugin -.->|"includes"| node_google_plugin
node_plugin -.->|"includes"| node_strands_plugin
node_session_manager -->|"starts child"| node_agent_workflow
node_session_worker -->|"hosts"| node_session_manager
node_typed_client -.->|"communicates with"| node_agent_workflow
node_mcp_gateway -.->|"registers tools"| node_nexus_resolver
node_mcp_gateway -->|"calls external MCP"| node_user
node_slack_inbound -->|"starts workflow"| node_connector_router
node_linear_inbound -->|"routes input"| node_connector_router
node_teams_inbound -->|"starts workflow"| node_connector_router

click node_agent_workflow "https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/agent_workflow.py"
click node_agent_protocol "https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/agent_protocol/agent_interface.py"
click node_agent_events "https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/agent_protocol/events.py"
click node_agent_client "https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/agent_client.py"
click node_stream_merge "https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/stream_merge/merge.py"
click node_agent_state "https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/state/session.py"
click node_code_mode "https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/code_mode/driver.py"
click node_plugin "https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/plugin.py"
click node_openai_plugin "https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/ai_sdks/openai_agents/_kit.py"
click node_google_plugin "https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/ai_sdks/google_genai_plugin/_google_genai_plugin.py"
click node_strands_plugin "https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/ai_sdks/strands_agents/_plugin.py"
click node_web_api "https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/web/app.py"
click node_session_manager "https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/web/session_manager.py"
click node_session_worker "https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/web/session_manager_worker.py"
click node_console "https://github.com/temporal-community/temporal-agent-kit/blob/main/typescript/apps/ui/src/App.svelte"
click node_typed_client "https://github.com/temporal-community/temporal-agent-kit/blob/main/typescript/packages/client/src/session.ts"
click node_nexus_resolver "https://github.com/temporal-community/temporal-agent-kit/blob/main/nexus/mcp/nexus_mcp/resolver.py"
click node_mcp_gateway "https://github.com/temporal-community/temporal-agent-kit/blob/main/nexus/mcp/nexus_mcp/durable_tools_gateway/registry_service_handler.py"
click node_connector_router "https://github.com/temporal-community/temporal-agent-kit/blob/main/nexus/ui_connector/router/workflow.go"
click node_slack_inbound "https://github.com/temporal-community/temporal-agent-kit/blob/main/nexus/ui_connector/slack/inbound/server.go"
click node_linear_inbound "https://github.com/temporal-community/temporal-agent-kit/blob/main/nexus/ui_connector/linear/inbound/server.go"
click node_teams_inbound "https://github.com/temporal-community/temporal-agent-kit/blob/main/nexus/ui_connector/teams/inbound/server.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent_workflow,node_agent_protocol,node_agent_events,node_agent_client,node_stream_merge,node_agent_state,node_code_mode,node_user toneBlue
class node_plugin,node_openai_plugin,node_google_plugin,node_strands_plugin toneAmber
class node_web_api,node_session_manager,node_session_worker toneMint
class node_console,node_typed_client toneRose
class node_nexus_resolver,node_mcp_gateway,node_connector_router,node_slack_inbound,node_linear_inbound,node_teams_inbound,node_temporal toneIndigo
```

## Components

### Agent Runtime

- [Agent Workflow](https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/agent_workflow.py): `python/temporal_agent_kit/agent_workflow.py`
- [Typed Protocol](https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/agent_protocol/agent_interface.py): `python/temporal_agent_kit/agent_protocol/agent_interface.py`
- [Stream Events](https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/agent_protocol/events.py): `python/temporal_agent_kit/agent_protocol/events.py`
- [Agent Client](https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/agent_client.py): `python/temporal_agent_kit/agent_client.py`
- [Stream Merge](https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/stream_merge/merge.py): `python/temporal_agent_kit/stream_merge/merge.py`
- [Agent State](https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/state/session.py): `python/temporal_agent_kit/state/session.py`
- [Code Mode](https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/code_mode/driver.py): `python/temporal_agent_kit/code_mode/driver.py`

### Agent Integrations

- [Worker Plugins](https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/plugin.py): `python/temporal_agent_kit/plugin.py`
- [OpenAI Agents](https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/ai_sdks/openai_agents/_kit.py): `python/temporal_agent_kit/ai_sdks/openai_agents/_kit.py`
- [Google GenAI](https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/ai_sdks/google_genai_plugin/_google_genai_plugin.py): `python/temporal_agent_kit/ai_sdks/google_genai_plugin/_google_genai_plugin.py`
- [Strands Agents](https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/ai_sdks/strands_agents/_plugin.py): `python/temporal_agent_kit/ai_sdks/strands_agents/_plugin.py`

### Harness Services

- [Harness API](https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/web/app.py): `python/temporal_agent_kit/web/app.py`
- [Session Manager](https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/web/session_manager.py): `python/temporal_agent_kit/web/session_manager.py`
- [Manager Worker](https://github.com/temporal-community/temporal-agent-kit/blob/main/python/temporal_agent_kit/web/session_manager_worker.py): `python/temporal_agent_kit/web/session_manager_worker.py`

### User Interfaces

- [Agent Console](https://github.com/temporal-community/temporal-agent-kit/blob/main/typescript/apps/ui/src/App.svelte): `typescript/apps/ui/src/App.svelte`
- [Typed Client](https://github.com/temporal-community/temporal-agent-kit/blob/main/typescript/packages/client/src/session.ts): `typescript/packages/client/src/session.ts`

### Nexus and Connectors

- [Nexus Resolver](https://github.com/temporal-community/temporal-agent-kit/blob/main/nexus/mcp/nexus_mcp/resolver.py): `nexus/mcp/nexus_mcp/resolver.py`
- [MCP Gateway](https://github.com/temporal-community/temporal-agent-kit/blob/main/nexus/mcp/nexus_mcp/durable_tools_gateway/registry_service_handler.py): `nexus/mcp/nexus_mcp/durable_tools_gateway/registry_service_handler.py`
- [Connector Router](https://github.com/temporal-community/temporal-agent-kit/blob/main/nexus/ui_connector/router/workflow.go): `nexus/ui_connector/router/workflow.go`
- [Slack Webhook](https://github.com/temporal-community/temporal-agent-kit/blob/main/nexus/ui_connector/slack/inbound/server.go): `nexus/ui_connector/slack/inbound/server.go`
- [Linear Webhook](https://github.com/temporal-community/temporal-agent-kit/blob/main/nexus/ui_connector/linear/inbound/server.go): `nexus/ui_connector/linear/inbound/server.go`
- [Teams Webhook](https://github.com/temporal-community/temporal-agent-kit/blob/main/nexus/ui_connector/teams/inbound/server.go): `nexus/ui_connector/teams/inbound/server.go`

### Other components

- **User or App**
- **Temporal Service**

## Connections

- User or App → Agent Console: uses (evidence: `README.md`)
- Agent Console → Harness API: calls (evidence: `README.md`)
- Harness API → Temporal Service: uses (evidence: `README.md`)
- Manager Worker → Temporal Service: hosts manager (evidence: `README.md`)
- Agent Workflow → Temporal Service: runs on (evidence: `README.md`)
- Agent Workflow → Typed Protocol: uses types (evidence: `python/temporal_agent_kit/agent_workflow.py`)
- Agent Workflow → Stream Events: uses events (evidence: `python/temporal_agent_kit/agent_workflow.py`)
- Agent Workflow → Agent State: uses state (evidence: `python/temporal_agent_kit/agent_workflow.py`)
- Agent Workflow → Worker Plugins: integrates via (evidence: `README.md`)
- Agent Client → Typed Protocol: uses types (evidence: `python/temporal_agent_kit/agent_client.py`)
- Agent Client → Stream Merge: merges streams (evidence: `python/temporal_agent_kit/agent_client.py`)
- Worker Plugins → OpenAI Agents: includes
- Worker Plugins → Google GenAI: includes
- Worker Plugins → Strands Agents: includes
- Session Manager → Agent Workflow: starts child (evidence: `python/temporal_agent_kit/web/session_manager.py`)
- Manager Worker → Session Manager: hosts (evidence: `python/temporal_agent_kit/web/session_manager_worker.py`)
- Typed Client → Agent Workflow: communicates with
- MCP Gateway → Nexus Resolver: registers tools
- MCP Gateway → User or App: calls external MCP (evidence: `nexus/mcp/nexus_mcp/durable_tools_gateway/registry_service_handler.py`)
- Slack Webhook → Connector Router: starts workflow (evidence: `nexus/ui_connector/slack/inbound/server.go`)
- Linear Webhook → Connector Router: routes input (evidence: `nexus/ui_connector/linear/inbound/server.go`)
- Teams Webhook → Connector Router: starts workflow (evidence: `nexus/ui_connector/teams/inbound/server.go`)
