# strands-agents/sdk-python architecture

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

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

## Overview

1. **What this repo is**
   - `strands-agents` is a Python SDK for building AI agents. It is not an application server; it is a reusable library centered on an agent runtime that orchestrates model calls, tools, state, hooks, and optional multi-agent flows.

2. **Primary architectural boundary**
   - The public package lives under `src/strands/` and is the stable runtime surface.
   - `tests/` contains unit coverage for each subsystem, while `tests_integ/` exercises real provider and protocol integrations such as model APIs, MCP, A2A, streaming, and bidirectional audio/text flows.

3. **Core agent runtime**
   - The main execution path is the agent loop: `agent/`, `event_loop/`, and `types/`.
   - `Agent` coordinates model prompts, tool invocation, response handling, interruptions, retries, and conversation management.
   - `event_loop/` is the control plane that repeatedly calls the model, interprets tool requests, runs tools, and feeds results back into the model until a terminal answer is produced.

4. **Model provider layer**
   - `models/` contains provider-specific adapters for Bedrock, Anthropic, Gemini, LiteLLM, LlamaAPI, llama.cpp, Mistral, Ollama, OpenAI, OpenAI Responses, SageMaker, and Writer.
   - This layer isolates provider-specific request/response shapes behind a common model interface so the rest of the agent stack can remain provider-agnostic.
   - The README indicates Bedrock is the default provider path, with AWS credentials and model access required for production use.

5. **Tooling subsystem**
   - `tools/` is a first-class subsystem for declaring, validating, loading, and executing tools.
   - It includes decorators, a registry, loaders, watchers for hot reload, validators, and executors for sequential or concurrent tool runs.
   - Tools are part of the model-agent feedback loop: the model selects a tool, the runtime executes it, and the tool result is injected back into the conversation.

6. **MCP integration boundary**
   - `tools/mcp/` integrates Model Context Protocol servers as external tool providers.
   - The SDK can connect to remote MCP endpoints, list exported tools, instrument calls, and adapt MCP tasks/resources into the agent tool model.
   - This is a major external boundary because it turns remote MCP servers into dynamically available capabilities for an agent.

7. **Conversation state and persistence**
   - `agent/conversation_manager/` and `session/` handle state retention across turns and across runs.
   - Conversation managers include null, sliding-window, and summarizing strategies, which control context growth and model token usage.
   - Session managers support file-based, repository-backed, and S3-backed persistence, separating transient conversational memory from durable storage.

8. **Hooks, callbacks, and observability**
   - `hooks/` and `handlers/` provide event interception around agent activity and tool execution.
   - `telemetry/` adds tracing and metrics, while `handlers/callback_handler.py` suggests callback-style integrations for external consumers.
   - This forms the observability and extension boundary: other systems can react to lifecycle events without modifying the core loop.

9. **Multi-agent and A2A support**
   - `multiagent/` contains graph and swarm coordination primitives for orchestrating multiple agents.
   - `multiagent/a2a/` provides Agent-to-Agent server and executor support, acting as a protocol boundary for agent collaboration and delegation.
   - `agent/_agent_as_tool.py` shows that a single agent can also be wrapped and exposed as a tool to another agent, which is a key composition pattern.

10. **Experimental bidirectional streaming stack**
   - `experimental/bidi/` is a separate asynchronous runtime for persistent, real-time, bidirectional conversations.
   - It includes its own agent, loop, I/O abstractions, model adapters, event types, and a `stop_conversation` tool.
   - Supported providers here are distinct from the standard request/response path: Amazon Nova Sonic, Gemini Live, and OpenAI Realtime API.

11. **Experimental steering, checkpointing, and hooks**
   - `experimental/steering/` provides a policy/context/action model for steering model and tool behavior.
   - `experimental/checkpoint/` suggests snapshot or recovery support for experimental state management.
   - `experimental/hooks/` extends the hook system into bidirectional and multi-agent event flows, keeping experimental event contracts separate from the core API.

12. **Plugins and vendored extensions**
   - `plugins/` defines a plugin abstraction and decorator/registry pattern for loading extensions.
   - `vended_plugins/` contains packaged, opinionated extensions such as skills and steering components that ship with the SDK.
   - This separation suggests a core library plus optional extension bundles, rather than a monolithic runtime.

13. **Typed domain model**
   - `types/` centralizes shared schemas for agents, tools, sessions, events, streaming, media, interruptions, citations, traces, and guardrails.
   - These types are the connective tissue between subsystems, defining the contracts that models, tools, hooks, sessions, and multi-agent components all exchange.

14. **Packaging and delivery**
   - The repo is structured as a Python package with extras for optional features such as bidirectional streaming and audio I/O.
   - CI and release workflows indicate publishing to PyPI and a Lambda layer, so the architecture includes both library distribution and cloud deployment packaging as first-class concerns.

Main entry points: [`src/strands/agent/agent.py`](https://github.com/strands-agents/sdk-python/blob/main/src/strands/agent/agent.py) (Agent), [`src/strands/types/__init__.py`](https://github.com/strands-agents/sdk-python/blob/main/src/strands/types/__init__.py) (Types), [`src/strands/tools/tools.py`](https://github.com/strands-agents/sdk-python/blob/main/src/strands/tools/tools.py) (Tools API), [`src/strands/__init__.py`](https://github.com/strands-agents/sdk-python/blob/main/src/strands/__init__.py) (strands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_pkg["strands<br/>public package<br/>[__init__.py]"]
  node_agent["Agent<br/>runtime coordinator<br/>[agent.py]"]
  node_loop(("Event loop<br/>control loop<br/>[event_loop.py]"))
  node_conv["Conversation<br/>context policy"]
  node_session[("Session store<br/>persistence<br/>[session_manager.py]")]
  node_types["Types<br/>shared contracts<br/>[__init__.py]"]
  node_models["Model adapters<br/>provider layer<br/>[model.py]"]
end

subgraph group_tools["Tools & MCP"]
  node_tools_api["Tools API<br/>tooling core<br/>[tools.py]"]
  node_mcp["MCP bridge<br/>remote tools<br/>[mcp_client.py]"]
  node_structured["Structured output<br/>tool wrapper"]
end

subgraph group_extensions["Extensions"]
  node_hooks["Hooks<br/>lifecycle events<br/>[registry.py]"]
  node_handlers["Callbacks<br/>external handlers"]
  node_telemetry["Telemetry<br/>tracing metrics<br/>[tracer.py]"]
  node_plugins["Plugins<br/>extension registry<br/>[registry.py]"]
  node_vended["Vended plugins<br/>bundled extensions<br/>[__init__.py]"]
end

subgraph group_multiagent["Multi-agent"]
  node_multi["Multi-agent<br/>coordination<br/>[graph.py]"]
  node_a2a["A2A boundary<br/>agent protocol<br/>[server.py]"]
  node_agent_tool["Agent as tool<br/>composition pattern<br/>[_agent_as_tool.py]"]
end

subgraph group_experimental["Experimental"]
  node_bidi(("Bidirectional runtime<br/>experimental loop<br/>[agent.py]"))
  node_bidi_models["Realtime models<br/>bidi adapters<br/>[model.py]"]
  node_steering["Steering<br/>policy layer<br/>[handler.py]"]
end

node_pkg -->|"exports"| node_agent
node_pkg -->|"exports"| node_tools_api
node_pkg -->|"exports"| node_models
node_pkg -->|"exports"| node_multi
node_agent -->|"drives"| node_loop
node_agent -->|"uses"| node_conv
node_agent -->|"persists"| node_session
node_loop -->|"calls"| node_models
node_loop -->|"executes"| node_tools_api
node_loop -->|"exchanges"| node_types
node_conv -->|"shapes"| node_types
node_session -->|"stores"| node_types
node_models -->|"implements"| node_types
node_tools_api -->|"wraps"| node_structured
node_tools_api -->|"loads"| node_mcp
node_tools_api -->|"defines"| node_types
node_hooks -->|"intercepts"| node_agent
node_handlers -->|"subscribes"| node_hooks
node_telemetry -->|"observes"| node_agent
node_plugins -->|"loads"| node_vended
node_multi -->|"serves"| node_a2a
node_multi -->|"coordinates"| node_agent
node_agent_tool -->|"composes"| node_agent
node_bidi -->|"uses"| node_bidi_models
node_bidi -->|"exchanges"| node_types
node_steering -->|"configures"| node_types
node_vended -->|"bundles"| node_steering

click node_pkg "https://github.com/strands-agents/sdk-python/blob/main/src/strands/__init__.py"
click node_agent "https://github.com/strands-agents/sdk-python/blob/main/src/strands/agent/agent.py"
click node_loop "https://github.com/strands-agents/sdk-python/blob/main/src/strands/event_loop/event_loop.py"
click node_conv "https://github.com/strands-agents/sdk-python/blob/main/src/strands/agent/conversation_manager/conversation_manager.py"
click node_session "https://github.com/strands-agents/sdk-python/blob/main/src/strands/session/session_manager.py"
click node_types "https://github.com/strands-agents/sdk-python/blob/main/src/strands/types/__init__.py"
click node_models "https://github.com/strands-agents/sdk-python/blob/main/src/strands/models/model.py"
click node_tools_api "https://github.com/strands-agents/sdk-python/blob/main/src/strands/tools/tools.py"
click node_mcp "https://github.com/strands-agents/sdk-python/blob/main/src/strands/tools/mcp/mcp_client.py"
click node_structured "https://github.com/strands-agents/sdk-python/blob/main/src/strands/tools/structured_output/structured_output_tool.py"
click node_hooks "https://github.com/strands-agents/sdk-python/blob/main/src/strands/hooks/registry.py"
click node_handlers "https://github.com/strands-agents/sdk-python/blob/main/src/strands/handlers/callback_handler.py"
click node_telemetry "https://github.com/strands-agents/sdk-python/blob/main/src/strands/telemetry/tracer.py"
click node_plugins "https://github.com/strands-agents/sdk-python/blob/main/src/strands/plugins/registry.py"
click node_vended "https://github.com/strands-agents/sdk-python/blob/main/src/strands/vended_plugins/__init__.py"
click node_multi "https://github.com/strands-agents/sdk-python/blob/main/src/strands/multiagent/graph.py"
click node_a2a "https://github.com/strands-agents/sdk-python/blob/main/src/strands/multiagent/a2a/server.py"
click node_agent_tool "https://github.com/strands-agents/sdk-python/blob/main/src/strands/agent/_agent_as_tool.py"
click node_bidi "https://github.com/strands-agents/sdk-python/blob/main/src/strands/experimental/bidi/agent/agent.py"
click node_bidi_models "https://github.com/strands-agents/sdk-python/blob/main/src/strands/experimental/bidi/models/model.py"
click node_steering "https://github.com/strands-agents/sdk-python/blob/main/src/strands/experimental/steering/core/handler.py"

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_pkg,node_agent,node_loop,node_conv,node_session,node_types,node_models toneBlue
class node_tools_api,node_mcp,node_structured toneAmber
class node_hooks,node_handlers,node_telemetry,node_plugins,node_vended toneMint
class node_multi,node_a2a,node_agent_tool toneRose
class node_bidi,node_bidi_models,node_steering toneIndigo
```

## Components

### Core runtime

Primary agent execution path and shared state

- [strands](https://github.com/strands-agents/sdk-python/blob/main/src/strands/__init__.py): public package · Stable SDK surface for composing agents and integrations · `src/strands/__init__.py`
- [Agent](https://github.com/strands-agents/sdk-python/blob/main/src/strands/agent/agent.py): runtime coordinator · Coordinates prompts, tools, interruptions, retries, and conversation flow · `src/strands/agent/agent.py`
- [Event loop](https://github.com/strands-agents/sdk-python/blob/main/src/strands/event_loop/event_loop.py): control loop · Repeats model calls, handles tool requests, and drives terminal responses · `src/strands/event_loop/event_loop.py`
- [Conversation](https://github.com/strands-agents/sdk-python/blob/main/src/strands/agent/conversation_manager/conversation_manager.py): context policy · Manages conversational context with null, sliding-window, and summarizing strategies · `src/strands/agent/conversation_manager/conversation_manager.py`
- [Session store](https://github.com/strands-agents/sdk-python/blob/main/src/strands/session/session_manager.py): persistence · Durable session backends for file, repository, and S3 storage · `src/strands/session/session_manager.py`
- [Types](https://github.com/strands-agents/sdk-python/blob/main/src/strands/types/__init__.py): shared contracts · Central schemas for agents, tools, sessions, events, streaming, media, and traces · `src/strands/types/__init__.py`
- [Model adapters](https://github.com/strands-agents/sdk-python/blob/main/src/strands/models/model.py): provider layer · Common interface over Bedrock, Anthropic, Gemini, OpenAI, and other providers · `src/strands/models/model.py`

### Tools & MCP

Tool declaration, execution, and remote capability loading

- [Tools API](https://github.com/strands-agents/sdk-python/blob/main/src/strands/tools/tools.py): tooling core · Decorators, registry, loaders, validators, watchers, and executors for tools · `src/strands/tools/tools.py`
- [MCP bridge](https://github.com/strands-agents/sdk-python/blob/main/src/strands/tools/mcp/mcp_client.py): remote tools · Connects Model Context Protocol servers into the agent tool model · `src/strands/tools/mcp/mcp_client.py`
- [Structured output](https://github.com/strands-agents/sdk-python/blob/main/src/strands/tools/structured_output/structured_output_tool.py): tool wrapper · Helpers for schema-driven outputs and response shaping · `src/strands/tools/structured_output/structured_output_tool.py`

### Extensions

Hooks, telemetry, plugins, and packaged additions

- [Hooks](https://github.com/strands-agents/sdk-python/blob/main/src/strands/hooks/registry.py): lifecycle events · Event interception and registry for agent and tool activity · `src/strands/hooks/registry.py`
- [Callbacks](https://github.com/strands-agents/sdk-python/blob/main/src/strands/handlers/callback_handler.py): external handlers · Callback-style integrations for consuming agent events · `src/strands/handlers/callback_handler.py`
- [Telemetry](https://github.com/strands-agents/sdk-python/blob/main/src/strands/telemetry/tracer.py): tracing metrics · Tracing, metrics, and instrumentation for runtime visibility · `src/strands/telemetry/tracer.py`
- [Plugins](https://github.com/strands-agents/sdk-python/blob/main/src/strands/plugins/registry.py): extension registry · Plugin abstraction and registry for loading optional extensions · `src/strands/plugins/registry.py`
- [Vended plugins](https://github.com/strands-agents/sdk-python/blob/main/src/strands/vended_plugins/__init__.py): bundled extensions · Packaged skills and steering components shipped with the SDK · `src/strands/vended_plugins/__init__.py`

### Multi-agent

Coordination and agent-to-agent boundaries

- [Multi-agent](https://github.com/strands-agents/sdk-python/blob/main/src/strands/multiagent/graph.py): coordination · Graph and swarm orchestration for multiple collaborating agents · `src/strands/multiagent/graph.py`
- [A2A boundary](https://github.com/strands-agents/sdk-python/blob/main/src/strands/multiagent/a2a/server.py): agent protocol · Agent-to-agent server and executor support for delegation and collaboration · `src/strands/multiagent/a2a/server.py`
- [Agent as tool](https://github.com/strands-agents/sdk-python/blob/main/src/strands/agent/_agent_as_tool.py): composition pattern · Wraps one agent so it can be invoked as a tool by another agent · `src/strands/agent/_agent_as_tool.py`

### Experimental

Alternate bidirectional and steering runtimes

- [Bidirectional runtime](https://github.com/strands-agents/sdk-python/blob/main/src/strands/experimental/bidi/agent/agent.py): experimental loop · Persistent real-time runtime for audio/text streaming conversations · `src/strands/experimental/bidi/agent/agent.py`
- [Realtime models](https://github.com/strands-agents/sdk-python/blob/main/src/strands/experimental/bidi/models/model.py): bidi adapters · Adapters for Nova Sonic, Gemini Live, and OpenAI Realtime · `src/strands/experimental/bidi/models/model.py`
- [Steering](https://github.com/strands-agents/sdk-python/blob/main/src/strands/experimental/steering/core/handler.py): policy layer · Policy/context/action handling for steering model and tool behavior · `src/strands/experimental/steering/core/handler.py`

## Connections

- strands → Agent: exports · Public SDK entrypoint exposes agent runtime primitives
- strands → Tools API: exports · Public package exposes tooling APIs
- strands → Model adapters: exports · Public package exposes provider adapters
- strands → Multi-agent: exports · Public package exposes multi-agent coordination
- Agent → Event loop: drives · Agent delegates execution to the event loop
- Agent → Conversation: uses · Agent consults conversation policy for context growth
- Agent → Session store: persists · Agent state can be stored across runs
- Event loop → Model adapters: calls · Loop invokes provider models for each turn
- Event loop → Tools API: executes · Tool requests are resolved through the tools subsystem
- Event loop → Types: exchanges · Loop consumes shared event and message contracts
- Conversation → Types: shapes · Conversation strategies operate on shared agent/session types
- Session store → Types: stores · Session backends persist typed session state
- Model adapters → Types: implements · Provider adapters conform to shared model message types
- Tools API → Structured output: wraps · Structured output is modeled as a tool-assisted path
- Tools API → MCP bridge: loads · MCP servers are surfaced as dynamic tools
- Tools API → Types: defines · Tools subsystem uses shared tool and execution contracts
- Hooks → Agent: intercepts · Hooks observe agent lifecycle and tool events
- Callbacks → Hooks: subscribes · Callback handler is an external consumer of hook events
- Telemetry → Agent: observes · Tracing and metrics wrap core runtime behavior
- Plugins → Vended plugins: loads · Registry can load bundled extension packages
- Multi-agent → A2A boundary: serves · Multi-agent subsystem exposes A2A protocol support
- Multi-agent → Agent: coordinates · Graphs and swarms orchestrate multiple agents
- Agent as tool → Agent: composes · An agent can be adapted into a tool for delegation
- Bidirectional runtime → Realtime models: uses · Bidirectional runtime relies on realtime provider adapters
- Bidirectional runtime → Types: exchanges · Realtime events and I/O use bidirectional typed contracts
- Steering → Types: configures · Steering policies operate over shared action and context types
- Vended plugins → Steering: bundles · Packaged extensions include steering components
