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 装饰器。类型提示将自动转为 JSON 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 的 callable
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 工具。智能体通过调用该工具并传入目标智能体名称完成交接。支持中断/恢复、会话持久化及重复交接检测。

图模式（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 可能发生变化