# strands-agents/harness-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/strands-agents/harness-sdk
- Repository: https://github.com/strands-agents/harness-sdk

## Overview

#### Repository Scope and Entry Points
Strands Agents is a monorepo for model-driven AI-agent SDKs in Python and TypeScript, plus an MCP documentation server, developer CLI, documentation site, and AWS-backed integration-test infrastructure. Public SDK entry points are `strands-py/src/strands/__init__.py` and `strands-ts/src/index.ts` (with Node-specific exports in `strands-ts/src/index.node.ts`). The central invocation APIs are `strands-py/src/strands/agent/agent.py` and `strands-ts/src/agent/agent.ts`.

#### Agent Execution Core
Each SDK centers on an `Agent` that owns prompt/conversation state, a model, tools, and lifecycle controls. Agent invocation drives an iterative model/tool loop, producing results and streamed events. Python orchestration is split between `strands-py/src/strands/agent/agent.py`, `strands-py/src/strands/event_loop/event_loop.py`, and `strands-py/src/strands/event_loop/streaming.py`; TypeScript consolidates core invocation in `strands-ts/src/agent/agent.ts` with tool dispatch in `strands-ts/src/agent/tool-caller.ts`.

#### Model Provider Boundary
A shared model abstraction isolates agent logic from LLM transports, schemas, streaming, retries, and provider-specific error behavior. Python implementations include Bedrock, Anthropic, Gemini, OpenAI, and local/aggregator providers under `strands-py/src/strands/models/model.py`, `strands-py/src/strands/models/bedrock.py`, and `strands-py/src/strands/models/openai.py`. TypeScript counterparts are `strands-ts/src/models/model.ts`, `strands-ts/src/models/bedrock.ts`, and `strands-ts/src/models/openai/model.ts`. Amazon Bedrock is the default; external services include AWS, Anthropic, OpenAI, Google, and others through adapters.

#### Tools, MCP, and Execution Safety
Models select registered tool schemas; executors validate and invoke them sequentially or concurrently, returning results to the loop. Core Python paths are `strands-py/src/strands/tools/registry.py`, `strands-py/src/strands/tools/executors/concurrent.py`, and `strands-py/src/strands/tools/mcp/mcp_client.py`; TypeScript paths are `strands-ts/src/registry/tool-registry.ts`, `strands-ts/src/tools/executors/concurrent.ts`, and `strands-ts/src/mcp/client.ts`. Sandboxes separate tool execution from host environments using local POSIX, Docker, or SSH implementations: `strands-py/src/strands/sandbox/docker.py` and `strands-ts/src/sandbox/docker.ts`.

#### Extensibility, Control, and State
Hooks, middleware, plugins, and interventions provide interception boundaries around agent/model/tool stages for logging, authorization, human approval, steering, and cancellation. Key paths are `strands-py/src/strands/_middleware/stages.py`, `strands-py/src/strands/interventions/registry.py`, `strands-ts/src/middleware/stages.ts`, and `strands-ts/src/interventions/handler.ts`. Conversation/context managers constrain token growth, while session, storage, and memory layers persist or retrieve state; e.g., `strands-py/src/strands/agent/conversation_manager/conversation_manager.py`, `strands-py/src/strands/memory/memory_manager.py`, `strands-ts/src/session/session-manager.ts`, and `strands-ts/src/storage/s3-storage.ts`. Durable integrations include filesystem and Amazon S3; Bedrock Knowledge Bases are vended memory stores.

#### Multi-Agent, Observability, and Streaming
Agents can compose as tools or execute through graph, swarm, and Agent-to-Agent (A2A) protocols. Primary implementations are `strands-py/src/strands/multiagent/graph.py`, `strands-py/src/strands/multiagent/a2a/server.py`, `strands-ts/src/multiagent/graph.ts`, and `strands-ts/src/a2a/express-server.ts`. Telemetry traces and metrics agent decisions and operations through `strands-py/src/strands/telemetry/tracer.py` and `strands-ts/src/telemetry/tracer.ts`. Python additionally exposes experimental bidirectional text/audio agents for Gemini Live, Nova Sonic, and OpenAI Realtime under `strands-py/src/strands/experimental/bidi/agent/agent.py`.

#### Supporting Products and Delivery
`strands-mcp/src/strands_mcp_server/__main__.py` starts a Python MCP server that fetches, processes, indexes, caches, and serves project documentation. `strandly/src/cli.ts` is the workspace developer CLI. The Astro documentation application is rooted at `site/src/pages/index.astro`, content is defined in `site/src/content.config.ts`, and custom rendering/routing resides in `site/src/route-middleware.ts`. GitHub Actions package, test, release, and deploy the SDKs and site; AWS CDK integration-test resources are defined by `test-infra/bin/test-infra.ts` and `test-infra/lib/stacks/test-infra-stack.ts`.

Main entry points: [`strands-py/src/strands/agent/agent.py`](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/agent/agent.py) (Agent), [`strands-py/src/strands/event_loop/event_loop.py`](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/event_loop/event_loop.py) (Event loop), [`strands-ts/src/agent/agent.ts`](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/agent/agent.ts) (Agent & tool caller), [`strands-py/src/strands/__init__.py`](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/__init__.py) (Python public SDK)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python SDK"]
  node_py_entry["Python public SDK<br/>package entry<br/>[__init__.py]"]
  node_py_agent["Agent<br/>invocation API<br/>[agent.py]"]
  node_py_loop["Event loop<br/>orchestrator<br/>[event_loop.py]"]
  node_py_streaming["Streaming<br/>event stream<br/>[streaming.py]"]
  node_py_models{{"Model abstraction<br/>provider boundary<br/>[model.py]"}}
  node_py_bedrock["Bedrock adapter<br/>model provider<br/>[bedrock.py]"]
  node_py_tools["Tool registry &amp; executor<br/>tool runtime<br/>[concurrent.py]"]
  node_py_mcp["MCP client<br/>tool transport<br/>[mcp_client.py]"]
  node_py_controls["Middleware &amp; interventions<br/>control boundary<br/>[stages.py]"]
  node_py_state[("Conversation &amp; memory<br/>state management<br/>[memory_manager.py]")]
  node_py_multiagent["Multi-agent graph<br/>agent composition<br/>[graph.py]"]
  node_py_telemetry["Telemetry<br/>observability<br/>[tracer.py]"]
end

subgraph group_typescript["TypeScript SDK"]
  node_ts_entry["TypeScript public SDK<br/>package entry<br/>[index.ts]"]
  node_ts_agent["Agent &amp; tool caller<br/>invocation runtime<br/>[agent.ts]"]
  node_ts_models{{"Model abstraction<br/>provider boundary<br/>[model.ts]"}}
  node_ts_tools["Tool registry &amp; executor<br/>tool runtime<br/>[concurrent.ts]"]
  node_ts_state[("Session &amp; S3 storage<br/>durable state<br/>[s3-storage.ts]")]
end

subgraph group_products["Supporting products"]
  node_mcp_server["Documentation MCP server<br/>[__main__.py]"]
  node_cli["Strandly CLI<br/>developer CLI<br/>[cli.ts]"]
  node_docs_site["Documentation site<br/>Astro application<br/>[index.astro]"]
end

subgraph group_delivery["Delivery"]
  node_ci["GitHub Actions<br/>CI/CD"]
  node_test_infra["AWS test infrastructure<br/>CDK stack"]
end

node_py_entry -->|"exports"| node_py_agent
node_py_agent -->|"invokes"| node_py_loop
node_py_agent -->|"manages context"| node_py_state
node_py_agent -->|"runs through"| node_py_controls
node_py_loop -->|"calls model"| node_py_models
node_py_loop -->|"dispatches tools"| node_py_tools
node_py_loop -->|"emits events"| node_py_streaming
node_py_models -->|"implements"| node_py_bedrock
node_py_tools -->|"uses remote tools"| node_py_mcp
node_py_agent -->|"composes agents"| node_py_multiagent
node_py_agent -.->|"traces"| node_py_telemetry
node_ts_entry -->|"exports"| node_ts_agent
node_ts_agent -->|"calls model"| node_ts_models
node_ts_agent -->|"dispatches tools"| node_ts_tools
node_ts_agent -->|"persists state"| node_ts_state
node_py_mcp -->|"connects"| node_mcp_server
node_cli -.->|"supports development"| node_py_entry
node_ci -->|"packages and releases"| node_py_entry
node_ci -->|"packages and releases"| node_ts_entry
node_ci -->|"deploys"| node_docs_site
node_ci -->|"runs integration tests"| node_test_infra

click node_py_entry "https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/__init__.py"
click node_py_agent "https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/agent/agent.py"
click node_py_loop "https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/event_loop/event_loop.py"
click node_py_streaming "https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/event_loop/streaming.py"
click node_py_models "https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/model.py"
click node_py_bedrock "https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/bedrock.py"
click node_py_tools "https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/tools/executors/concurrent.py"
click node_py_mcp "https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/tools/mcp/mcp_client.py"
click node_py_controls "https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/_middleware/stages.py"
click node_py_state "https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/memory/memory_manager.py"
click node_py_multiagent "https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/multiagent/graph.py"
click node_py_telemetry "https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/telemetry/tracer.py"
click node_ts_entry "https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/index.ts"
click node_ts_agent "https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/agent/agent.ts"
click node_ts_models "https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/models/model.ts"
click node_ts_tools "https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/tools/executors/concurrent.ts"
click node_ts_state "https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/storage/s3-storage.ts"
click node_mcp_server "https://github.com/strands-agents/harness-sdk/blob/main/strands-mcp/src/strands_mcp_server/__main__.py"
click node_cli "https://github.com/strands-agents/harness-sdk/blob/main/strandly/src/cli.ts"
click node_docs_site "https://github.com/strands-agents/harness-sdk/blob/main/site/src/pages/index.astro"
click node_test_infra "https://github.com/strands-agents/harness-sdk/blob/main/test-infra/lib/stacks/test-infra-stack.ts"

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_py_entry,node_py_agent,node_py_loop,node_py_streaming,node_py_models,node_py_bedrock,node_py_tools,node_py_mcp,node_py_controls,node_py_state,node_py_multiagent,node_py_telemetry toneBlue
class node_ts_entry,node_ts_agent,node_ts_models,node_ts_tools,node_ts_state toneAmber
class node_mcp_server,node_cli,node_docs_site toneMint
class node_ci,node_test_infra toneRose
```

## Components

### Python SDK

- [Python public SDK](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/__init__.py): package entry · `strands-py/src/strands/__init__.py`
- [Agent](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/agent/agent.py): invocation API · Owns conversation, model, tools, and lifecycle. · `strands-py/src/strands/agent/agent.py`
- [Event loop](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/event_loop/event_loop.py): orchestrator · Runs the iterative model and tool loop. · `strands-py/src/strands/event_loop/event_loop.py`
- [Streaming](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/event_loop/streaming.py): event stream · `strands-py/src/strands/event_loop/streaming.py`
- [Model abstraction](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/model.py): provider boundary · Normalizes transports, schemas, retries, and streaming. · `strands-py/src/strands/models/model.py`
- [Bedrock adapter](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/models/bedrock.py): model provider · Default Amazon Bedrock integration. · `strands-py/src/strands/models/bedrock.py`
- [Tool registry & executor](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/tools/executors/concurrent.py): tool runtime · Validates and concurrently invokes selected tools. · `strands-py/src/strands/tools/executors/concurrent.py`
- [MCP client](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/tools/mcp/mcp_client.py): tool transport · `strands-py/src/strands/tools/mcp/mcp_client.py`
- [Middleware & interventions](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/_middleware/stages.py): control boundary · Intercepts stages for approval, steering, and cancellation. · `strands-py/src/strands/_middleware/stages.py`
- [Conversation & memory](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/memory/memory_manager.py): state management · Constrains context and retrieves or persists memory. · `strands-py/src/strands/memory/memory_manager.py`
- [Multi-agent graph](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/multiagent/graph.py): agent composition · `strands-py/src/strands/multiagent/graph.py`
- [Telemetry](https://github.com/strands-agents/harness-sdk/blob/main/strands-py/src/strands/telemetry/tracer.py): observability · `strands-py/src/strands/telemetry/tracer.py`

### TypeScript SDK

- [TypeScript public SDK](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/index.ts): package entry · Also has Node-specific exports. · `strands-ts/src/index.ts`
- [Agent & tool caller](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/agent/agent.ts): invocation runtime · Consolidates invocation and tool dispatch. · `strands-ts/src/agent/agent.ts`
- [Model abstraction](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/models/model.ts): provider boundary · `strands-ts/src/models/model.ts`
- [Tool registry & executor](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/tools/executors/concurrent.ts): tool runtime · `strands-ts/src/tools/executors/concurrent.ts`
- [Session & S3 storage](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/storage/s3-storage.ts): durable state · `strands-ts/src/storage/s3-storage.ts`

### Supporting products

- [Documentation MCP server](https://github.com/strands-agents/harness-sdk/blob/main/strands-mcp/src/strands_mcp_server/__main__.py): MCP server · Indexes, caches, and serves project documentation. · `strands-mcp/src/strands_mcp_server/__main__.py`
- [Strandly CLI](https://github.com/strands-agents/harness-sdk/blob/main/strandly/src/cli.ts): developer CLI · `strandly/src/cli.ts`
- [Documentation site](https://github.com/strands-agents/harness-sdk/blob/main/site/src/pages/index.astro): Astro application · `site/src/pages/index.astro`

### Delivery

- **GitHub Actions**: CI/CD · Packages, tests, releases, and deploys SDKs and site.
- [AWS test infrastructure](https://github.com/strands-agents/harness-sdk/blob/main/test-infra/lib/stacks/test-infra-stack.ts): CDK stack · Integration-test resources. · `test-infra/lib/stacks/test-infra-stack.ts`

## Connections

- Python public SDK → Agent: exports
- Agent → Event loop: invokes
- Agent → Conversation & memory: manages context
- Agent → Middleware & interventions: runs through
- Event loop → Model abstraction: calls model
- Event loop → Tool registry & executor: dispatches tools
- Event loop → Streaming: emits events
- Model abstraction → Bedrock adapter: implements
- Tool registry & executor → MCP client: uses remote tools
- Agent → Multi-agent graph: composes agents
- Agent → Telemetry: traces
- TypeScript public SDK → Agent & tool caller: exports
- Agent & tool caller → Model abstraction: calls model
- Agent & tool caller → Tool registry & executor: dispatches tools
- Agent & tool caller → Session & S3 storage: persists state
- MCP client → Documentation MCP server: connects
- Strandly CLI → Python public SDK: supports development
- GitHub Actions → Python public SDK: packages and releases
- GitHub Actions → TypeScript public SDK: packages and releases
- GitHub Actions → Documentation site: deploys
- GitHub Actions → AWS test infrastructure: runs integration tests