Strands Agents SDK
Build AI agents in Python using the Strands SDK (Apache-2.0, from AWS).
Validated against: strands-agents==1.23.0, INLINECODE1
Prerequisites
CODEBLOCK0
Core Concept: Bedrock Is the Default
INLINECODE2 with no model= argument defaults to Amazon Bedrock — specifically us.anthropic.claude-sonnet-4-20250514-v1:0 in us-west-2. This requires AWS credentials. To use a different provider, pass model= explicitly.
Default model constant: INLINECODE7
Quick Start — Local Agent (Ollama)
CODEBLOCK1
Note: Not all open-source models support tool-calling. Abliterated models often lose function-calling during the abliteration process. Test with a stock model (qwen3, llama3.x, mistral) first.
Quick Start — Bedrock (Default Provider)
CODEBLOCK2
Quick Start — Anthropic (Direct API)
CODEBLOCK3
Requires ANTHROPIC_API_KEY environment variable.
Quick Start — OpenAI
CODEBLOCK4
Requires OPENAI_API_KEY environment variable.
Creating Custom Tools
Use the @tool decorator. Type hints become the schema; the docstring becomes the description:
CODEBLOCK5
ToolContext
Tools can access agent state via ToolContext:
CODEBLOCK6
Built-in Tools (46 available)
INLINECODE12 provides pre-built tools:
CODEBLOCK7
Full list: calculator, file_read, file_write, shell, http_request, editor, image_reader, python_repl, current_time, think, stop, sleep, environment, retrieve, search_video, chat_video, speak, generate_image, generate_image_stability, diagram, journal, memory, agent_core_memory, elasticsearch_memory, mongodb_memory, mem0_memory, rss, cron, batch, workflow, use_agent, use_llm, use_aws, use_computer, load_tool, handoff_to_user, slack, swarm, graph, a2a_client, mcp_client, exa, tavily, bright_data, nova_reels.
Hot reload: Agent(load_tools_from_directory=True) watches ./tools/ for changes.
MCP Integration
Connect to any Model Context Protocol server. MCPClient implements ToolProvider — pass it directly in the tools list:
CODEBLOCK8
SSE transport:
CODEBLOCK9
Multi-Agent Patterns
Agents as Tools
Nest agents — inner agents become tools for the outer agent:
CODEBLOCK10
Swarm Pattern
Self-organizing agent teams with shared context and autonomous handoff coordination:
CODEBLOCK11
Swarm auto-injects a handoff_to_agent tool. Agents hand off by calling it with the target agent's name. Supports interrupt/resume, session persistence, and repetitive-handoff detection.
Graph Pattern (DAG)
Deterministic dependency-based execution via GraphBuilder:
CODEBLOCK12
Supports cycles (feedback loops) with builder.reset_on_revisit(True), execution timeouts, and nested graphs (Graph as a node in another Graph).
A2A Protocol (Agent-to-Agent)
Expose a Strands agent as an A2A-compatible server for inter-agent communication:
CODEBLOCK13
Connect to A2A agents with the a2a_client tool from strands-agents-tools. A2A implements Google's Agent-to-Agent protocol for standardized cross-process/cross-network agent communication.
Session Persistence
Persist conversations across agent runs:
CODEBLOCK14
Both Swarm and Graph support session managers for persisting multi-agent state.
Bidirectional Streaming (Experimental)
Real-time voice/text conversations with persistent audio streams:
CODEBLOCK15
Supports interruption detection, concurrent tool execution, and continuous back-and-forth audio. Experimental — API subject to change.
System Prompts
CODEBLOCK16
Strands also supports list[SystemContentBlock] for structured system prompts with cache control.
Observability
Native OpenTelemetry tracing:
CODEBLOCK17
Every tool call, model invocation, handoff, and lifecycle event is instrumentable.
Bedrock-Specific Features
- - Guardrails:
guardrail_id + guardrail_version in BedrockModel config — content filtering, PII detection, input/output redaction - Cache points: System prompt and tool definition caching for cost optimization
- Streaming: On by default, disable with INLINECODE68
- Region: Defaults to
us-west-2, override via region_name param or AWS_REGION env - Cross-region inference: Model IDs prefixed with
us. use cross-region inference profiles
Scaffolding a New Agent
CODEBLOCK18
Creates a ready-to-run agent directory with tools, config, and entry point.
Running an Agent
CODEBLOCK19
Model Providers Reference (11 total)
| Provider | Class | Init | Notes |
|---|
| Bedrock | INLINECODE73 | INLINECODE74 | Default, eagerly imported |
| Ollama |
OllamaModel |
OllamaModel("http://host:11434", model_id=...) |
host is positional |
| Anthropic |
AnthropicModel |
AnthropicModel(model_id=..., max_tokens=4096) |
max_tokens required |
| OpenAI |
OpenAIModel |
OpenAIModel(model_id=...) |
OPENAI_API_KEY |
| Gemini |
GeminiModel |
GeminiModel(model_id=...) |
api_key in client_args |
| Mistral |
MistralModel |
MistralModel(model_id=...) | Mistral API key |
| LiteLLM |
LiteLLMModel |
LiteLLMModel(model_id=...) | Meta-provider (Cohere, Groq, etc.) |
| LlamaAPI |
LlamaAPIModel |
LlamaAPIModel(model_id=...) | Meta Llama API |
| llama.cpp |
LlamaCppModel |
LlamaCppModel(...) | Local server, OpenAI-compatible |
| SageMaker |
SageMakerAIModel |
SageMakerAIModel(...) | Custom AWS endpoints |
| Writer |
WriterModel |
WriterModel(model_id=...) | Writer platform |
All non-Bedrock providers are lazy-loaded — dependencies imported only when referenced.
Import pattern: from strands.models.<provider> import <Class> (or from strands.models import <Class> for lazy-load).
Tips
- -
Agent() without model= requires AWS credentials (Bedrock default) - INLINECODE103 requires
max_tokens — omitting it causes a runtime error - INLINECODE105
host is positional: INLINECODE107 - Abliterated Ollama models often lose tool-calling support — use stock models for tool-using agents
- Swarm agents need
name= and description= for handoff routing - INLINECODE110 watches
./tools/ for hot-reloaded tool files - Use
agent.tool.my_tool() to call tools directly without LLM routing - INLINECODE113 is a
ToolProvider — pass it directly in tools=[mcp], don't call list_tools_sync() manually when using with Agent - Session managers work with Agent, Swarm, and Graph
- Pin your
strands-agents version — the SDK is young and APIs evolve between releases
Strands Agents SDK
使用 Strands SDK（Apache-2.0 许可，来自 AWS）在 Python 中构建 AI 代理。
已验证版本：strands-agents==1.23.0，strands-agents-tools==0.2.19
前置条件
bash
安装 SDK + 工具（推荐使用 pipx 进行隔离安装）
pipx install strands-agents-builder # 包含 strands-agents + strands-agents-tools + CLI
或直接安装
pip install strands-agents strands-agents-tools
核心概念：Bedrock 为默认
Agent() 在不指定 model= 参数时，默认使用 Amazon Bedrock——具体为 us-west-2 区域的 us.anthropic.claude-sonnet-4-20250514-v1:0。这需要 AWS 凭证。要使用其他提供商，请显式传递 model= 参数。
默认模型常量：strands.models.bedrock.DEFAULTBEDROCKMODEL_ID
快速入门——本地代理（Ollama）
python
from strands import Agent
from strands.models.ollama import OllamaModel
host 是必需的位置参数
model = OllamaModel(http://localhost:11434, model_id=qwen3:latest)
agent = Agent(model=model)
result = agent(法国的首都是什么？)
print(result)
注意： 并非所有开源模型都支持工具调用。经过消融处理的模型通常在消融过程中丢失了函数调用能力。请先使用原始模型（qwen3、llama3.x、mistral）进行测试。
快速入门——Bedrock（默认提供商）
python
from strands import Agent
未指定模型 → BedrockModel（Claude Sonnet 4，us-west-2）
需要 AWS 凭证（~/.aws/credentials 或环境变量）
agent = Agent()
result = agent(解释量子计算)
显式指定 Bedrock 模型：
from strands.models import BedrockModel
model = BedrockModel(model_id=us.anthropic.claude-sonnet-4-20250514-v1:0)
agent = Agent(model=model)
快速入门——Anthropic（直接 API）
python
from strands import Agent
from strands.models.anthropic import AnthropicModel
max_tokens 是 Required[int]——必须提供
model = AnthropicModel(model
id=claude-sonnet-4-20250514, maxtokens=4096)
agent = Agent(model=model)
result = agent(解释量子计算)
需要 ANTHROPICAPIKEY 环境变量。
快速入门——OpenAI
python
from strands import Agent
from strands.models.openai import OpenAIModel
model = OpenAIModel(model_id=gpt-4.1)
agent = Agent(model=model)
需要 OPENAIAPIKEY 环境变量。
创建自定义工具
使用 @tool 装饰器。类型提示成为模式；文档字符串成为描述：
python
from strands import Agent, tool
@tool
def read_file(path: str) -> str:
读取指定路径的文件内容。
参数：
path：要读取的文件系统路径。
with open(path) as f:
return f.read()
@tool
def write_file(path: str, content: str) -> str:
将内容写入文件。
参数：
path：要写入的文件系统路径。
content：要写入的文本内容。
with open(path, w) as f:
f.write(content)
return f已将 {len(content)} 字节写入 {path}
agent = Agent(model=model, tools=[readfile, writefile])
agent(读取 /tmp/test.txt 并总结它)
ToolContext
工具可以通过 ToolContext 访问代理状态：
python
from strands import tool
from strands.types.tools import ToolContext
@tool
def statefultool(query: str, toolcontext: ToolContext) -> str:
一个访问代理状态的工具。
参数：
query：输入查询。
# 访问共享的代理状态
count = toolcontext.state.get(callcount, 0) + 1
toolcontext.state[callcount] = count
return f第 #{count} 次调用：{query}
内置工具（46 个可用）
strands-agents-tools 提供预构建的工具：
python
from strandstools import calculator, fileread, filewrite, shell, httprequest
agent = Agent(model=model, tools=[calculator, file_read, shell])
完整列表：calculator、fileread、filewrite、shell、httprequest、editor、imagereader、pythonrepl、currenttime、think、stop、sleep、environment、retrieve、searchvideo、chatvideo、speak、generateimage、generateimagestability、diagram、journal、memory、agentcorememory、elasticsearchmemory、mongodbmemory、mem0memory、rss、cron、batch、workflow、useagent、usellm、useaws、usecomputer、loadtool、handofftouser、slack、swarm、graph、a2aclient、mcpclient、exa、tavily、brightdata、nova_reels。
热重载：Agent(loadtoolsfrom_directory=True) 会监视 ./tools/ 目录的变化。
MCP 集成
连接到任何模型上下文协议服务器。MCPClient 实现了 ToolProvider——直接在工具列表中传递它：
python
from strands import Agent
from strands.tools.mcp import MCPClient
from mcp import stdio_client, StdioServerParameters
MCPClient 接受一个返回传输层的可调用对象
mcp = MCPClient(lambda: stdio_client(StdioServerParameters(
command=uvx,
args=[some-mcp-server@latest]
)))
作为上下文管理器使用——MCPClient 是一个 ToolProvider
with mcp:
agent = Agent(model=model, tools=[mcp])
agent(使用 MCP 工具做点什么)
SSE 传输：
python
from mcp.client.sse import sse_client
mcp = MCPClient(lambda: sse_client(http://localhost:8080/sse))
多代理模式
代理作为工具
嵌套代理——内部代理成为外部代理的工具：
python
researcher = Agent(model=model, system_prompt=你是一个研究助手。)
writer = Agent(model=model, system_prompt=你是一个写作者。)
orchestrator = Agent(
model=model,
tools=[researcher, writer],
system_prompt=你协调研究和写作任务。
)
orchestrator(研究量子计算并写一篇博客文章)
群体模式
具有共享上下文和自主交接协调的自组织代理团队：
python
from strands.multiagent.swarm import Swarm
代理需要 name + description 用于交接识别
researcher = Agent(
model=model,
name=researcher,
description=查找和总结信息
)
writer = Agent(
model=model,
name=writer,
description=创建精炼的内容
)
swarm = Swarm(
nodes=[researcher, writer],
entry_point=researcher, # 可选——默认为第一个代理
max_handoffs=20, # 默认值
max_iterations=20, # 默认值
execution_timeout=900.0, # 默认 15 分钟
node_timeout=300.0 # 每个节点默认 5 分钟
)
result = swarm(研究 AI 代理，然后交给写作者写一篇博客文章)
群体自动注入一个 handofftoagent 工具。代理通过使用目标代理的名称调用它来进行交接。支持中断/恢复、会话持久化和重复交接检测。
图模式（DAG）
通过 GraphBuilder 进行基于依赖关系的确定性执行：
python
from strands.multiagent.graph import GraphBuilder
builder = GraphBuilder()
researchnode = builder.addnode(researcher, node_id=research)
writingnode = builder.addnode(writer, node_id=writing)
builder.add_edge(research, writing)
builder.setentrypoint(research)
可选：条件边
builder.add_edge(research, writing,
condition=lambda state: complete in str(state.completed_nodes))
graph = builder.build()
result = graph(写一篇关于 AI 代理的博客文章)
支持
