How strands-agents/sdk-python works
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: agent.py Agent · types/__init__.py Types · tools.py Tools API · strands/__init__.py strands
Components 21
Core runtime
Primary agent execution path and shared state
- strands · Stable SDK surface for composing agents and integrations
src/strands/__init__.py - Agent · Coordinates prompts, tools, interruptions, retries, and conversation flow
src/strands/agent/agent.py - Event loop · Repeats model calls, handles tool requests, and drives terminal responses
src/strands/event_loop/event_loop.py - Conversation · Manages conversational context with null, sliding-window, and summarizing strategies
src/strands/agent/conversation_manager/conversation_manager.py - Session store · Durable session backends for file, repository, and S3 storage
src/strands/session/session_manager.py - Types · Central schemas for agents, tools, sessions, events, streaming, media, and traces
src/strands/types/__init__.py - Model adapters · 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 · Decorators, registry, loaders, validators, watchers, and executors for tools
src/strands/tools/tools.py - MCP bridge · Connects Model Context Protocol servers into the agent tool model
src/strands/tools/mcp/mcp_client.py - Structured output · 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 · Event interception and registry for agent and tool activity
src/strands/hooks/registry.py - Callbacks · Callback-style integrations for consuming agent events
src/strands/handlers/callback_handler.py - Telemetry · Tracing, metrics, and instrumentation for runtime visibility
src/strands/telemetry/tracer.py - Plugins · Plugin abstraction and registry for loading optional extensions
src/strands/plugins/registry.py - Vended plugins · 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 · Graph and swarm orchestration for multiple collaborating agents
src/strands/multiagent/graph.py - A2A boundary · Agent-to-agent server and executor support for delegation and collaboration
src/strands/multiagent/a2a/server.py - Agent as tool · 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 · Persistent real-time runtime for audio/text streaming conversations
src/strands/experimental/bidi/agent/agent.py - Realtime models · Adapters for Nova Sonic, Gemini Live, and OpenAI Realtime
src/strands/experimental/bidi/models/model.py - Steering · Policy/context/action handling for steering model and tool behavior
src/strands/experimental/steering/core/handler.py
Connections 27
- 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