企业官网建设流程全解析

• 人工智能
• 大模型
• AI Agent
• Agent 框架
• 多智能体
• 工具调用
• MCP 服务

本文基于 Python SDK v1.22.0 发布说明（2026-01-13 发布）展开，系统梳理该版本在 Agent 执行层、Bedrock 模型层、MCP 工具链与工程化方面的全部变更，并结合 strands-py 仓库源码深入解析每个更新点的底层实现与使用方式。读完本文，你将掌握 v1.22.0 中 AgentBase 协议接口的契约、guardrail_latest_message与invocation_state的正确用法，以及 MCP 资源操作和并发保护背后的机制，便于评估升级收益并安全迁移。

版本概览：一次无破坏性变更的增量发布

v1.22.0 是 strands-agents Python SDK 的一次全量增量发布，所有条目均标记为breaking: false，意味着升级不会破坏既有调用方式。本次发布共包含 21 条变更，按类型分布为：功能（feat）5 条、修复（fix）7 条、其他（other）7 条、文档（docs）1 条、工程维护（chore）2 条；按领域（areas）划分，主要覆盖agent、model、mcp、tool四大块，并迎来 4 位新贡献者（aiancheruk、emattiza、schleidl、tirth14）。

从版本发布说明可以清晰看到本版本的三个主线：

1. Agent 执行层规范化——引入AgentBase协议接口、向模型传递invocation_state、为并行调用增加并发保护；
2. Bedrock 模型层精细化——新增guardrail_latest_message选项，并持续完善 Guardrail 内容包装逻辑；
3. MCP 工具链补全——在 MCP Tools 中加入资源（Resource）操作，并修复后台线程 contextvars 传播与错误处理中的字符串格式化问题。

下文按领域逐一展开，并在关键节点给出源码证据。

Agent 层：AgentBase 协议、invocation_state 与并发保护

引入 AgentBase Protocol 作为统一接口契约

本次发布最重要的结构性变更来自 PR 1126：引入AgentBaseProtocol 作为 agent 类必须实现的接口。在 strands-py/src/strands/agent/base.py 中可以看到它的定义：

@runtime_checkable class AgentBase(Protocol): """Protocol defining the interface for all agent types in Strands. This protocol defines the minimal contract that all agent implementations must satisfy. """

该协议使用typing.Protocol并标记为runtime_checkable，声明了三个核心方法契约：

• invoke_async(prompt, **kwargs) -> AgentResult：异步执行 agent；
• __call__(prompt, **kwargs) -> AgentResult：同步执行入口；
• stream_async(prompt, **kwargs) -> AsyncIterator[Any]：流式执行，产出事件序列。

从源码结构看，协议的最小契约覆盖了同步调用、异步调用与流式调用三种形态，Agent主类通过多重继承同时实现AgentBase与LocalAgent（见 strands-py/src/strands/agent/agent.py），而多智能体场景中的A2AAgent同样实现了该协议（见 strands-py/src/strands/agent/a2a_agent.py）。同时AgentBase已加入包级导出：在 strands-py/src/strands/init.py 与 strands-py/src/strands/agent/init.py 中均可在顶层from strands import AgentBase直接导入。

这一变更的价值在于：任何实现了该协议的自定义 agent 类，都可以在类型层面与框架的多智能体编排、hook 事件系统互操作，例如 strands-py/src/strands/hooks/events.py 中的BeforeInvocationEvent等事件即以 agent 为载荷，协议的引入让这些跨模块引用有了可静态检查的统一类型。

将 extra command content 作为 prompt 提供给 agent

PR 1419 实现了一个实用的功能增强：把额外的命令内容（extra command content）直接作为 prompt 传给 agent。这在 CLI / 脚本驱动场景下非常有用——调用方可以把命令行上下文、环境信息或附加指令追加进模型输入，而不必手动拼装消息历史。结合 strands-py/src/strands/agent/agent.py 中invoke_async的签名可以看到，调用入口接收invocation_state与各类转发参数，该功能使外部命令内容能够作为自然语言提示进入 agent 的执行循环。

向模型提供商传递 invocation_state

PR 1414 让invocation_state可以一路透传到模型提供商。在 strands-py/src/strands/agent/agent.py 中，invoke_async的invocation_state参数被描述为“通过事件循环透传的附加参数”（Additional parameters to pass through the event loop），同步入口__call__（strands-py/src/strands/agent/agent.py）同样支持。

从 strands-py/src/strands/_middleware/README.md 的说明可以推断其语义演进：invocation_state是每次调用（per-invocation）的状态字典，它与messages的区别在于——messages在构建 middleware 上下文时会被深拷贝，而invocation_state以引用方式共享，是 hook 与 event loop 读写活动状态（如 agent 引用、取消信号等）的载体（见 strands-py/src/strands/agent/_agent_as_tool.py）。v1.22.0 将其进一步延伸至模型提供商，意味着中间件、hook 写入的状态可以在模型请求构造阶段被读取，为自定义请求参数注入打开了通道。

并发保护：防止并行调用破坏 agent 状态

PR 1453 为 agent 增加了并发保护机制，避免并行调用并发写入导致 agent 状态损坏。其实现位于独立的 strands-py/src/strands/agent/_concurrency.py，核心是_ConcurrencyController（见 strands-py/src/strands/agent/agent.py 的实例化）。在 strands-py/src/strands/agent/agent.py 中可以看到执行流程：

• begin(idempotency_token)在调用开始时登记并返回 token；
• 执行完成或异常后分别调用complete(..., result=...)/complete(..., error=...)；
• 当并发模式为THROW时（strands-py/src/strands/agent/agent.py），会在收尾时release_lock()释放并发锁。

控制器暴露mode（见 strands-py/src/strands/agent/_concurrency.py），对应 agent 的concurrent_invocation_mode配置。这意味着：如果你的业务场景可能对同一 agent 实例发起并发调用（例如多个后台任务共享一个 agent），v1.22.0 之后可以选择“抛错”或“排队”等策略，从框架层面杜绝状态竞态。

Bedrock 模型层：guardrail_latest_message 与 Guardrail 内容包装

新选项 guardrail_latest_message

PR 1224 为 Bedrock 模型提供商新增了guardrail_latest_message配置项。在 strands-py/src/strands/models/bedrock.py 的BedrockConfig文档中，其含义为：

Flag to send only the latest user message to guardrails. Defaults to False.

字段类型为bool | None（strands-py/src/strands/models/bedrock.py），默认False，即默认情况下沿用原有行为（对所有消息应用 Guardrail 包装）。

底层实现：定位最后一条含文本/图像的用户消息

该选项的实现在消息格式化阶段。_format_bedrock_messages（strands-py/src/strands/models/bedrock.py）会预先调用_find_last_user_text_message_index（strands-py/src/strands/models/bedrock.py），从消息列表末尾向前查找最后一条包含文本或图像内容的 user 消息：

def _find_last_user_text_message_index(self, messages: Messages) -> int | None: for idx, msg in reversed(list(enumerate(messages))): if msg["role"] == "user" and any("text" in cb or "image" in cb for cb in msg.get("content", [])): return idx return None

随后（strands-py/src/strands/models/bedrock.py），当消息索引等于该位置时，文本内容被包装为{"guardContent": {"text": {"text": ...}}}，图像内容则先校验格式是否在 Bedrock Guardrail 支持的枚举内（GuardrailConverseImageFormat），不支持的图像格式会打印警告并跳过包装。

这个实现的精妙之处在于：即使工具执行循环在用户消息之后追加了toolResult（role 同样为 user），也能准确命中真正的用户文本消息（源码注释明确指出这一点，见 strands-py/src/strands/models/bedrock.py）。对于多轮工具调用场景，这能显著降低 Guardrail 调用成本并避免对工具结果做不必要的安全审查。

使用示例

from strands.models.bedrock import BedrockModel model = BedrockModel( model_id="global.anthropic.claude-sonnet-4-6", guardrail_id="your-guardrail-id", guardrail_latest_message=True, # 仅将最后一条用户文本/图像消息送入 Guardrail )

注意：guardrail_latest_message只影响 Guardrail 内容包装的目标消息，guardrail_id、guardrail_trace、guardrail_version、guardrail_redact_input/output等选项的语义不变（完整字段见 strands-py/src/strands/models/bedrock.py）。

Bedrock 相关联动修复

同一版本还包含一项“make calculator tool more robust to LLM output variations”（PR 1445，scope: integ）：集成测试中的计算器工具被加固，以容忍大模型输出格式的变化。这属于工具层健壮性改进，与模型层变更相互配合，减少模型输出不规范时的解析失败。

MCP 工具链：资源操作、contextvars 传播与错误修复

新增 MCP 资源（Resource）操作

PR 1117 在 MCP Tools 中加入了资源操作能力，补齐了 MCP 协议中 tools/prompts 之外的重要维度。在 strands-py/src/strands/tools/mcp/mcp_client.py 中可以看到三个新的同步 API：

• list_resources_sync(pagination_token=None) -> ListResourcesResult（strands-py/src/strands/tools/mcp/mcp_client.py）：列出 MCP 服务器当前可用的资源，支持分页 token；
• read_resource_sync(uri) -> ReadResourceResult（strands-py/src/strands/tools/mcp/mcp_client.py）：按 URI 读取资源内容，兼容字符串与AnyUrl两种传参；
• list_resource_templates_sync(pagination_token=None) -> ListResourceTemplatesResult（strands-py/src/strands/tools/mcp/mcp_client.py）：列出资源模板，模板定义的是可动态访问资源的 URI 模式。

实现上，这些方法均在后台线程会话（_background_thread_session）上通过_invoke_on_background_thread执行异步调用并同步等待结果，与 MCP 客户端整体“连接运行在后台线程”的架构保持一致（见 strands-py/src/strands/tools/mcp/mcp_client.py 的模块说明）。此外，消息内容映射也支持嵌入资源（TextResourceContents，见 strands-py/src/strands/tools/mcp/mcp_client.py），agent 可以直接消费 MCP 服务器返回的资源内容。

修复 contextvars 向后台线程的传播

PR 1444 修复了contextvars 未能传播到后台线程的问题（scope: mcp）。由于 MCP 客户端连接运行在后台线程，若 contextvars（如请求 ID、trace ID、用户上下文）没有显式复制到该线程，将导致异步上下文中读取不到调用方的上下文变量，进而影响日志关联与中间件行为。该修复确保通过_invoke_on_background_thread发起的调用能继承调用方线程的 contextvars。

修复 MCP 客户端错误处理中的字符串格式化错误

PR 1446（scope: mcp）修复了 MCP 客户端错误处理路径中的字符串格式化问题。这类问题通常表现为占位符与参数数量不匹配导致的TypeError或日志输出错乱，会让真实的 MCP 连接/调用错误被掩盖。修复后错误信息能够正确渲染，便于定位 MCP 服务器异常。

多模态（Bidi）模型：导出与稳定性调整

本版本对 Bidi（双向实时）模型做了一组调整：

• 导出 BidiGeminiLiveModel 与 BidiOpenAIRealtimeModel（PR 1383）：将两种实时多模态模型加入包的__init__顶层导出，使from strands import BidiGeminiLiveModel这类导入成为官方支持的入口，简化使用方代码；
• bidi - async - 移除取消调用（PR 1357）：在异步路径中移除了一个多余的取消调用，避免取消信号在异步执行中被错误触发；
• bidi - 将 Python 3.12 检查移至 nova sonic 模块（PR 1439）：把 3.12 版本兼容性检查从通用路径收敛到 nova sonic 专属模块，降低对其他模型的误伤可能。

Bidi 相关模块位于 strands-py/src/strands/models 目录下。若你的项目使用实时语音/流式多模态交互，建议升级后验证异步会话的取消行为与 3.12 环境的导入路径。

修复与健壮性：模型导入、非流式响应与 Gemini 异常

• 修复可选导入模型的 import 错误（PR 1384）：此前某些模型在可选依赖未安装时会在导入阶段抛错，v1.22.0 修复了这类导入错误，让模型模块在缺少可选依赖时也能被安全导入，用户只有在实际使用对应模型时才需要安装相关依赖；
• 修复 Gemini 模型 UnboundLocal 异常（PR 1420，scope: gemini）：修复了一个因局部变量在分支中未初始化而触发的UnboundLocalError；
• 修复 LiteLLM 非流式响应处理（PR 512）：针对 issue #477 修复 LiteLLM 在非流式响应场景下的处理逻辑，保证streaming=False时响应解析正确。

这三项修复都属于“让更多模型组合开箱即用”的范畴，尤其对使用 Gemini、LiteLLM 聚合层或按需安装模型依赖的用户直接受益。

工程化与文档：依赖维护、安全声明与发布流程

• 更新 GitHub agent action 引用 S3_SESSION_BUCKET（PR 1418，type: docs）：文档/CI 配置中的 GitHub agent action 改为引用S3_SESSION_BUCKET环境变量，使会话存储指向 S3 桶，适配使用 S3 持久化会话的场景；
• 新增 Security.md（PR 1454）：为仓库补充安全策略文档，仓库根目录已有 SECURITY.md；
• 更新发布说明 SOP（PR 1456，type: chore）：完善发布说明的标准操作流程，本 changelog 的结构（sdk/language/version/tag/date/entries/newContributorsfrontmatter）即这一 SOP 的产物；
• 依赖范围放宽：pytest 允许范围从>=8.0.0,<9.0.0放宽至>=8.0.0,<10.0.0（PR 1161），Sphinx 从>=5.0.0,<9.0.0放宽至>=5.0.0,<10.0.0（PR 1426），均为开发依赖的兼容性扩展；
• 更新至 Opus 4.5（PR 1471）：项目内部模型引用更新至 Claude Opus 4.5。

升级建议与总结

v1.22.0 是一次无破坏性变更的版本，但包含若干值得关注的行为增强点：

1. 若使用 Bedrock Guardrail 且关注成本/延迟：开启guardrail_latest_message=True，仅对最后一条用户文本/图像消息做 Guardrail 包装，多轮工具调用场景收益尤其明显（底层定位逻辑见 strands-py/src/strands/models/bedrock.py）；
2. 若实现自定义 agent 类：遵循AgentBase协议（同步/异步/流式三入口）即可与框架类型系统互操作，协议定义见 strands-py/src/strands/agent/base.py；
3. 若存在并发调用同一 agent 的场景：利用新增的并发保护机制（strands-py/src/strands/agent/_concurrency.py）配置concurrent_invocation_mode，避免状态竞态；
4. 若深度使用 MCP 服务器：可借助list_resources_sync/read_resource_sync/list_resource_templates_sync直接消费服务器资源（见 strands-py/src/strands/tools/mcp/mcp_client.py），并确认升级后 contextvars 传播与错误信息渲染正常。

整体来看，v1.22.0 的变更体现了“协议化接口 + 精细化的模型控制 + 完整的 MCP 能力”三条演进主线：既有面向框架开发者的结构性调整（AgentBase），也有面向生产用户的实用开关（guardrail_latest_message），还有面向工具生态的能力补全（MCP 资源操作）。升级风险低、收益明确，值得计划内推进。

• 人工智能
• 大模型
• AI Agent
• Agent 框架
• 多智能体
• 工具调用
• MCP 服务