Strands Agents SDK

使用 Strands SDK（Apache-2.0 协议，来自 AWS）在 Python 中构建 AI 代理。

已验证兼容版本：strands-agents==1.23.0、strands-agents-tools==0.2.19

前提条件

# 安装 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.anthropic.claude-sonnet-4-20250514-v1:0（部署于 us-west-2 区域）。该配置要求提供有效的 AWS 凭据。如需使用其他模型提供商，请显式传入 model= 参数。

默认模型常量：strands.models.bedrock.DEFAULT_BEDROCK_MODEL_ID

快速开始 —— 本地代理（Ollama）

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)

注意： 并非所有开源模型均支持工具调用（tool-calling）。经 abliteration 处理后的模型通常会在该过程中丢失函数调用能力。建议优先使用标准模型（如 qwen3、llama3.x、mistral）进行测试。

快速开始 —— Bedrock（默认提供商）

from strands import Agent

# 未指定 model → 使用 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）

from strands import Agent
from strands.models.anthropic import AnthropicModel

# max_tokens 是 Required[int] 类型 —— 必须提供
model = AnthropicModel(model_id="claude-sonnet-4-20250514", max_tokens=4096)
agent = Agent(model=model)
result = agent("解释量子计算")

需设置 ANTHROPIC_API_KEY 环境变量。

快速开始 —— OpenAI

from strands import Agent
from strands.models.openai import OpenAIModel

model = OpenAIModel(model_id="gpt-4.1")
agent = Agent(model=model)

需设置 OPENAI_API_KEY 环境变量。

创建自定义工具

使用 @tool 装饰器。类型提示将自动转为工具 Schema；函数文档字符串（docstring）将作为工具描述：

from strands import Agent, tool

@tool
def read_file(path: str) -> str:
    """读取指定路径文件的内容。

    Args:
        path: 待读取的文件系统路径。
    """
    with open(path) as f:
        return f.read()

@tool
def write_file(path: str, content: str) -> str:
    """将内容写入文件。

    Args:
        path: 待写入的文件系统路径。
        content: 待写入的文本内容。
    """
    with open(path, 'w') as f:
        f.write(content)
    return f"已向 {path} 写入 {len(content)} 字节"

agent = Agent(model=model, tools=[read_file, write_file])
agent("读取 /tmp/test.txt 并总结其内容")

ToolContext

工具可通过 ToolContext 访问代理状态：

from strands import tool
from strands.types.tools import ToolContext

@tool
def stateful_tool(query: str, tool_context: ToolContext) -> str:
    """一个可访问代理状态的工具。

    Args:
        query: 输入查询。
    """
    # 访问共享的代理状态
    count = tool_context.state.get("call_count", 0) + 1
    tool_context.state["call_count"] = count
    return f"第 {count} 次调用：{query}"

内置工具（共 46 个）

strands-agents-tools 提供了预置工具集：

from strands_tools import calculator, file_read, file_write, shell, http_request
agent = Agent(model=model, tools=[calculator, file_read, shell])

完整列表：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。

热重载支持：Agent(load_tools_from_directory=True) 将监听 ./tools/ 目录下的变更。

MCP 集成

连接任意 Model Context Protocol（MCP）服务器。MCPClient 实现了 ToolProvider 接口，可直接传入 tools 列表中：

from strands import Agent
from strands.tools.mcp import MCPClient
from mcp import stdio_client, StdioServerParameters

# MCPClient 接收一个返回 transport 的可调用对象
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 传输方式：

from mcp.client.sse import sse_client
mcp = MCPClient(lambda: sse_client("http://localhost:8080/sse"))

多代理模式

代理作为工具

嵌套代理 —— 内层代理将成为外层代理的可用工具：

researcher = Agent(model=model, system_prompt="你是一名研究助理。")
writer = Agent(model=model, system_prompt="你是一名撰稿人。")

orchestrator = Agent(
    model=model,
    tools=[researcher, writer],
    system_prompt="你负责协调研究与写作任务。"
)
orchestrator("研究量子计算，并撰写一篇博客文章")

Swarm 模式

具备共享上下文和自主交接协调能力的自组织代理团队：

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 代理，然后交由撰稿人生成博客文章")

Swarm 自动注入 handoff_to_agent 工具。代理通过调用该工具并传入目标代理名称实现交接。支持中断/恢复（interrupt/resume）、会话持久化及重复交接检测。

图模式（DAG）

通过 GraphBuilder 实现基于确定性依赖关系的执行流程：

from strands.multiagent.graph import GraphBuilder

builder = GraphBuilder()
research_node = builder.add_node(researcher, node_id="research")
writing_node = builder.add_node(writer, node_id="writing")
builder.add_edge("research", "writing")
builder.set_entry_point("research")

# 可选：条件边
# builder.add_edge("research", "writing",
#     condition=lambda state: "complete" in str(state.completed_nodes))

graph = builder.build()
result = graph("撰写一篇关于 AI 代理的博客文章")

支持循环（反馈回路），可通过 builder.reset_on_revisit(True) 启用；支持执行超时控制及嵌套图（Graph 可作为另一 Graph 中的一个节点）。

A2A 协议（Agent-to-Agent）

将 Strands 代理暴露为兼容 A2A 协议的服务端，以支持跨代理通信：

from strands.multiagent.a2a import A2AServer

server = A2AServer(
    agent=my_agent,
    host="127.0.0.1",
    port=9000,
    version="0.0.1"
)
server.start()  # 启动 uvicorn

可使用 strands-agents-tools 中的 a2a_client 工具连接 A2A 代理。A2A 协议实现了 Google 提出的 Agent-to-Agent 标准，用于进程间/网络间代理的标准化通信。

会话持久化

在多次代理运行之间持久化对话历史：

from strands.session.file_session_manager import FileSessionManager

session = FileSessionManager(session_file_path="./sessions/my_session.json")
agent = Agent(model=model, session_manager=session)

# 其他可用选项：
from strands.session.s3_session_manager import S3SessionManager
session = S3SessionManager(bucket_name="my-bucket", session_id="session-1")

Swarm 和 Graph 均支持会话管理器，用于持久化多代理状态。

双向流式传输（实验性功能）

支持实时语音/文本对话及持续音频流：

from strands.experimental.bidi.agent import BidiAgent
from strands.experimental.bidi.models.nova_sonic import NovaSonicModel

# 支持的模型：NovaSonicModel、GeminiLiveModel、OpenAIRealtimeModel
model = NovaSonicModel(region="us-east-1")
agent = BidiAgent(model=model, tools=[my_tool])

支持中断检测、并发工具执行及连续双向音频交互。此功能处于实验阶段，API 可能变动。

系统提示词（System Prompts）

agent = Agent(
    model=model,
    system_prompt="你是 Hex，一位敏锐而机智的 AI 助手。",
    tools=[read_file, write_file]
)

Strands 还支持 list[SystemContentBlock] 类型的结构化系统提示词，并可启用缓存控制。

可观测性（Observability）

原生集成 OpenTelemetry 追踪：

agent = Agent(
    model=model,
    trace_attributes={"project": "my-agent", "environment": "dev"}
)

每次工具调用、模型推理、代理交接及生命周期事件均可被追踪和监控。

Bedrock 特有功能

• 防护栏（Guardrails）：在 BedrockModel 配置中指定 guardrail_id 与 guardrail_version —— 支持内容过滤、PII 检测、输入/输出脱敏
• 缓存点（Cache points）：对系统提示词与工具定义进行缓存，以优化成本
• 流式响应（Streaming）：默认启用，可通过 streaming=False 关闭
• 区域（Region）：默认为 us-west-2，可通过 region_name 参数或 AWS_REGION 环境变量覆盖
• 跨区域推理（Cross-region inference）：以 us. 开头的模型 ID 将使用跨区域推理配置文件

搭建新代理项目

python3 {baseDir}/scripts/create-agent.py my-agent --provider ollama --model qwen3:latest
python3 {baseDir}/scripts/create-agent.py my-agent --provider anthropic
python3 {baseDir}/scripts/create-agent.py my-agent --provider bedrock
python3 {baseDir}/scripts/create-agent.py my-agent --provider openai --model gpt-4.1

生成一个开箱即用的代理项目目录，包含工具、配置及入口文件。

运行代理

python3 {baseDir}/scripts/run-agent.py path/to/agent.py "你的提示词"
python3 {baseDir}/scripts/run-agent.py path/to/agent.py --interactive

模型提供商参考（共 11 种）

所有非 Bedrock 提供商均为 惰性加载（lazy-loaded） —— 仅在首次引用时导入对应依赖。

导入方式：from strands.models. import （或使用 from strands.models import 触发惰性加载）。

使用提示

• Agent() 若未传入 model=，则需配置 AWS 凭据（因默认使用 Bedrock）
• AnthropicModel 必须传入 max_tokens，否则运行时报错
• OllamaModel 的 host 是位置参数：OllamaModel("http://...", model_id="...")
• 经 abliteration 处理的 Ollama 模型通常不支持工具调用 —— 构建工具型代理时请优先选用标准模型
• Swarm 代理必须指定 name= 和 description=，以支持交接路由
• Agent(load_tools_from_directory=True) 将监听 ./tools/ 目录，实现工具文件热重载
• 可通过 agent.tool.my_tool() 直接调用工具，绕过 LLM 路由
• MCPClient 是一个 ToolProvider —— 可直接传入 tools=[mcp]，在与 Agent 配合使用时无需手动调用 list_tools_sync()
• 会话管理器同时适用于 Agent、Swarm 和 Graph
• 请锁定 strands-agents 版本 —— 该 SDK 尚处早期阶段，各版本间 API 可能发生变化