# temporal-community/temporal-agent-harness architecture

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

- Interactive diagram: https://gitdiagram.com/temporal-community/temporal-agent-harness
- Repository: https://github.com/temporal-community/temporal-agent-harness

## Overview

Temporal Agent Harness is a Python framework for durable, composable AI agents, with web and typed-UI components for running and observing sessions. The main workflow is user session creation, child-workflow execution, and streaming results to a client; agent turns can also involve tools, approvals, callbacks, and subagents. The graph includes documented SDK and integration capabilities. Some links rely on README statements because the corresponding implementation excerpts were not supplied; these are identified by README evidence rather than implying those files were inspected.

Main entry points: [`temporal_agent_harness/harness/agent_workflow.py`](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/agent_workflow.py) (Agent workflow), [`temporal_agent_harness/web/app.py`](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/web/app.py) (Web API), [`temporal_agent_harness/harness/agent_client.py`](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/agent_client.py) (Agent client), [`temporal_agent_harness/web/session_manager.py`](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/web/session_manager.py) (Session manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent runtime"]
  node_agent["Agent workflow<br/>[agent_workflow.py]"]
  node_protocol["Agent protocol<br/>[agent_interface.py]"]
  node_events["Lifecycle events<br/>[events.py]"]
  node_agentclient["Agent client<br/>[agent_client.py]"]
  node_streammerge["Stream merging"]
  node_state["Agent state"]
  node_plugin["Worker plugin<br/>[plugin.py]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_approvals["Tool approvals<br/>[approver.py]"]
  node_codemode["Code Mode<br/>[driver.py]"]
  node_callbacks["Callback tools"]
  node_subagents["Subagents"]
end

subgraph group_integrations["SDK integrations"]
  node_openai["OpenAI Agents adapter"]
  node_gemini["Gemini adapter<br/>[workflow.py]"]
  node_pydantic["Pydantic AI adapter"]
end

subgraph group_web["Web sessions"]
  node_webapp["Web API<br/>[app.py]"]
  node_manager["Session manager<br/>[session_manager.py]"]
end

subgraph group_clients["Client interfaces"]
  node_webclient["Browser API client<br/>[session.ts]"]
  node_streamtypes["Stream protocol types<br/>[frames.ts]"]
  node_svelte["Svelte SDK<br/>[session.svelte.ts]"]
  node_react["React SDK<br/>[session.ts]"]
  node_ui["Harness UI<br/>[App.svelte]"]
end

node_user(("Agent user"))
node_temporal[("Temporal service")]
node_model(("AI SDK / model"))

node_user -->|"creates session"| node_webapp
node_webapp -->|"queries sessions"| node_manager
node_manager -->|"starts child"| node_agent
node_manager -->|"runs workflow"| node_temporal
node_agent -->|"durable execution"| node_temporal
node_agent -->|"invokes AI SDK"| node_model
node_agent -.->|"implements contract"| node_protocol
node_agent -->|"publishes events"| node_events
node_agentclient -->|"sends updates"| node_temporal
node_webapp -->|"reads interface"| node_agentclient
node_agentclient -->|"uses contract"| node_protocol
node_agentclient -->|"merges stream"| node_streammerge
node_agent -.->|"maintains state"| node_state
node_agent -->|"requests approval"| node_approvals
node_agent -->|"runs scripts"| node_codemode
node_agent -->|"dispatches callbacks"| node_callbacks
node_agent -->|"composes agents"| node_subagents
node_plugin -->|"registers runtime"| node_temporal
node_openai -->|"adapts turns"| node_agent
node_gemini -->|"adapts turns"| node_agent
node_pydantic -->|"adapts turns"| node_agent
node_webclient -.->|"calls API"| node_webapp
node_webapp -->|"streams events"| node_streamtypes
node_streamtypes -->|"types events"| node_events
node_svelte -.->|"wraps sessions"| node_webclient
node_react -.->|"wraps sessions"| node_webclient
node_ui -->|"uses SDK"| node_svelte
node_user -->|"observes session"| node_ui

click node_webapp "https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/web/app.py"
click node_manager "https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/web/session_manager.py"
click node_agent "https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/agent_workflow.py"
click node_protocol "https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/agent_protocol/agent_interface.py"
click node_events "https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/agent_protocol/events.py"
click node_agentclient "https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/agent_client.py"
click node_streammerge "https://github.com/temporal-community/temporal-agent-harness/tree/main/temporal_agent_harness/harness/stream_merge"
click node_state "https://github.com/temporal-community/temporal-agent-harness/tree/main/temporal_agent_harness/harness/state"
click node_approvals "https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/jev_approvals/approver.py"
click node_codemode "https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/code_mode/driver.py"
click node_callbacks "https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/agent_protocol/subagent_interface.py"
click node_subagents "https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/subagent_toolset.py"
click node_plugin "https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/plugin.py"
click node_openai "https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/ai_sdks/openai_agents_harness.py"
click node_gemini "https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/ai_sdks/google_genai_plugin/workflow.py"
click node_pydantic "https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/ai_sdks/pydantic_ai_harness.py"
click node_webclient "https://github.com/temporal-community/temporal-agent-harness/blob/main/packages/client/src/session.ts"
click node_streamtypes "https://github.com/temporal-community/temporal-agent-harness/blob/main/packages/client/src/frames.ts"
click node_svelte "https://github.com/temporal-community/temporal-agent-harness/blob/main/packages/svelte/src/lib/session.svelte.ts"
click node_react "https://github.com/temporal-community/temporal-agent-harness/blob/main/packages/react/src/session.ts"
click node_ui "https://github.com/temporal-community/temporal-agent-harness/blob/main/ui/src/App.svelte"

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,node_protocol,node_events,node_agentclient,node_streammerge,node_state,node_plugin,node_user toneBlue
class node_approvals,node_codemode,node_callbacks,node_subagents,node_temporal toneAmber
class node_openai,node_gemini,node_pydantic toneMint
class node_webapp,node_manager toneRose
class node_webclient,node_streamtypes,node_svelte,node_react,node_ui,node_model toneIndigo
```

## Components

### Agent runtime

- [Agent workflow](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/agent_workflow.py): `temporal_agent_harness/harness/agent_workflow.py`
- [Agent protocol](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/agent_protocol/agent_interface.py): `temporal_agent_harness/harness/agent_protocol/agent_interface.py`
- [Lifecycle events](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/agent_protocol/events.py): `temporal_agent_harness/harness/agent_protocol/events.py`
- [Agent client](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/agent_client.py): `temporal_agent_harness/harness/agent_client.py`
- [Stream merging](https://github.com/temporal-community/temporal-agent-harness/tree/main/temporal_agent_harness/harness/stream_merge): `temporal_agent_harness/harness/stream_merge`
- [Agent state](https://github.com/temporal-community/temporal-agent-harness/tree/main/temporal_agent_harness/harness/state): `temporal_agent_harness/harness/state`
- [Worker plugin](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/plugin.py): `temporal_agent_harness/plugin.py`

### Agent capabilities

- [Tool approvals](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/jev_approvals/approver.py): `temporal_agent_harness/harness/jev_approvals/approver.py`
- [Code Mode](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/code_mode/driver.py): `temporal_agent_harness/harness/code_mode/driver.py`
- [Callback tools](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/agent_protocol/subagent_interface.py): `temporal_agent_harness/harness/agent_protocol/subagent_interface.py`
- [Subagents](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/harness/subagent_toolset.py): `temporal_agent_harness/harness/subagent_toolset.py`

### SDK integrations

- [OpenAI Agents adapter](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/ai_sdks/openai_agents_harness.py): `temporal_agent_harness/ai_sdks/openai_agents_harness.py`
- [Gemini adapter](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/ai_sdks/google_genai_plugin/workflow.py): `temporal_agent_harness/ai_sdks/google_genai_plugin/workflow.py`
- [Pydantic AI adapter](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/ai_sdks/pydantic_ai_harness.py): `temporal_agent_harness/ai_sdks/pydantic_ai_harness.py`

### Web sessions

- [Web API](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/web/app.py): `temporal_agent_harness/web/app.py`
- [Session manager](https://github.com/temporal-community/temporal-agent-harness/blob/main/temporal_agent_harness/web/session_manager.py): `temporal_agent_harness/web/session_manager.py`

### Client interfaces

- [Browser API client](https://github.com/temporal-community/temporal-agent-harness/blob/main/packages/client/src/session.ts): `packages/client/src/session.ts`
- [Stream protocol types](https://github.com/temporal-community/temporal-agent-harness/blob/main/packages/client/src/frames.ts): `packages/client/src/frames.ts`
- [Svelte SDK](https://github.com/temporal-community/temporal-agent-harness/blob/main/packages/svelte/src/lib/session.svelte.ts): `packages/svelte/src/lib/session.svelte.ts`
- [React SDK](https://github.com/temporal-community/temporal-agent-harness/blob/main/packages/react/src/session.ts): `packages/react/src/session.ts`
- [Harness UI](https://github.com/temporal-community/temporal-agent-harness/blob/main/ui/src/App.svelte): `ui/src/App.svelte`

### Other components

- **Agent user**
- **Temporal service**
- **AI SDK / model**

## Connections

- Agent user → Web API: creates session (evidence: `README.md`)
- Web API → Session manager: queries sessions (evidence: `temporal_agent_harness/web/app.py`)
- Session manager → Agent workflow: starts child (evidence: `temporal_agent_harness/web/session_manager.py`)
- Session manager → Temporal service: runs workflow (evidence: `README.md`)
- Agent workflow → Temporal service: durable execution (evidence: `README.md`)
- Agent workflow → AI SDK / model: invokes AI SDK (evidence: `README.md`)
- Agent workflow → Agent protocol: implements contract
- Agent workflow → Lifecycle events: publishes events (evidence: `README.md`)
- Agent client → Temporal service: sends updates (evidence: `temporal_agent_harness/harness/agent_client.py`)
- Web API → Agent client: reads interface (evidence: `temporal_agent_harness/web/app.py`)
- Agent client → Agent protocol: uses contract (evidence: `temporal_agent_harness/harness/agent_client.py`)
- Agent client → Stream merging: merges stream (evidence: `temporal_agent_harness/harness/agent_client.py`)
- Agent workflow → Agent state: maintains state
- Agent workflow → Tool approvals: requests approval (evidence: `README.md`)
- Agent workflow → Code Mode: runs scripts (evidence: `README.md`)
- Agent workflow → Callback tools: dispatches callbacks (evidence: `README.md`)
- Agent workflow → Subagents: composes agents (evidence: `README.md`)
- Worker plugin → Temporal service: registers runtime (evidence: `README.md`)
- OpenAI Agents adapter → Agent workflow: adapts turns (evidence: `README.md`)
- Gemini adapter → Agent workflow: adapts turns (evidence: `README.md`)
- Pydantic AI adapter → Agent workflow: adapts turns (evidence: `README.md`)
- Browser API client → Web API: calls API
- Web API → Stream protocol types: streams events (evidence: `packages/client/src/frames.ts`)
- Stream protocol types → Lifecycle events: types events (evidence: `packages/client/src/frames.ts`)
- Svelte SDK → Browser API client: wraps sessions
- React SDK → Browser API client: wraps sessions
- Harness UI → Svelte SDK: uses SDK (evidence: `ui/src/App.svelte`)
- Agent user → Harness UI: observes session (evidence: `README.md`)