企业官网建设流程全解析

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

strands-agents Python SDK 的 v1.31.0 版本（2026-03-19 发布）围绕生产级 Agent 的稳定性与互操作性做了一轮集中打磨：A2A 协议集成首次支持把请求上下文元数据作为 invocation state 传入、Graph 多智能体编排修复了出边求值逻辑、OpenAI 模型层对工具消息内容格式与 Responses API 错误处理进行了修正，同时补齐了 S3 会话管理与多模态二进制内容持久化方面的问题。读完本文，你将掌握这些变更的触发场景、对应的源码实现位置，以及如何在自己的 Agent、Graph/Swarm 编排与 OpenAI 模型接入中规避同类问题。

版本概览

本次发布对应源码仓库中的 site/src/content/changelog/sdk/python-v1.31.0.md，发行 tag 为python/v1.31.0。共包含 8 条变更，其中 2 条为特性（feat）、6 条为修复（fix），全部为非破坏性（breaking: false）变更，可在不修改既有调用代码的前提下安全升级：

版本还迎来了一位新贡献者 BV-Venky（其贡献正是 openai 依赖放宽的 PR）。下面逐条深入剖析这些变更背后的实现细节。

A2A 集成：请求上下文元数据接入 invocation state

变更背景

A2A（Agent2Agent）是异构 Agent 之间的互操作协议。本版本之前，Strands 的 A2A 客户端在调用远端 Agent 时只传递用户输入，无法把调用方的运行时上下文（如租户、用户角色、特征开关等元数据）随请求一起下发。v1.31.0 将 A2A 请求上下文元数据作为 invocation state 传入，让远端 Agent 与 Graph 边条件都能感知调用上下文。

客户端实现：A2AAgent

远端 Agent 的调用入口是A2AAgent（strands-py/src/strands/agent/a2a_agent.py），它支持三种调用方式：

• __call__(prompt)：同步调用，内部通过run_async桥接协程；
• invoke_async(prompt)：异步调用，消费完整个事件流后返回AgentResult；
• stream_async(prompt)：异步流式调用，产出A2AStreamEvent包装的原始 A2A 事件，最后总是以AgentResultEvent收尾。

构造参数值得关注：endpoint是远端 A2A Agent 的基础 URL；timeout默认 300 秒；client_config用于配置认证与传输（支持 SigV4、OAuth、bearer token），其中注入的httpx_client会同时用于 Agent Card 发现与消息发送。需要提醒的是，client_config与已废弃的a2a_client_factory不能同时提供，二者同时传入会抛出ValueError。

请求上下文如何随消息传递

在调用链_send_message → _get_a2a_client → client.send_message(message)中，用户输入会先经convert_input_to_message（strands-py/src/strands/multiagent/a2a/_converters.py）统一转换为 A2AMessage：字符串输入被包装为user角色的TextPart；消息列表输入则只取最后一条user消息并抽取其文本内容块；InterruptResponseContent在 A2A 中不受支持，会直接抛出ValueError。invocation state 与这条消息一起随请求上下文到达远端，从而支持基于调用上下文的鉴权、路由与定制化响应。

边条件与 invocation state：Graph 侧的联动

invocation state 不只是 A2A 的专属概念——Graph 的边条件函数同样可以消费它。在 strands-py/src/strands/multiagent/graph.py 中，EdgeConditionWithContext协议定义了新式边条件签名：

def condition(state: "GraphState", *, invocation_state: dict[str, Any], **kwargs: Any) -> bool: ...

_is_context_condition通过inspect.signature检测条件函数是否声明了名为invocation_state的参数：声明了就走新式调用约定（以关键字方式传入），否则按旧式Callable[[GraphState], bool]调用，GraphEdge.should_traverse内部还会对检测结果做缓存以降低开销。Graph 在stream_async入口把传入的 invocation_state 存入self._current_invocation_state，随后的边求值（_is_node_ready_with_conditions、_is_edge_traversable）都会把它透传给条件函数——这正是本次 A2A 变更与多智能体编排打通的关键点：同一份调用上下文既可用于 A2A 远端请求，也可驱动本地 Graph 的路由决策。

Graph 执行优化：仅评估已完成节点的出边

修复的问题

此前_find_newly_ready_nodes在每批节点执行完毕后会遍历图中所有节点来寻找新就绪节点，这会导致节点在真实依赖尚未完成时被提前触发，破坏依赖顺序。v1.31.0 将其改为只收集「从已完成批次出发的出边」的目标节点作为候选集，再对候选集做条件求值。

源码与测试双重印证

修复后的实现位于 strands-py/src/strands/multiagent/graph.py：

candidates = {edge.to_node for edge in self.edges if edge.from_node in completed_batch}

对应测试 strands-py/tests/strands/multiagent/test_graph.py 中的test_find_newly_ready_nodes_only_evaluates_outbound_edges构造了A -> B -> C与D -> E两条独立链路，断言：A 完成时只有 B 就绪（而非 E），D 完成时只有 E 就绪（而非 B 或 C）。该测试还引用了此前的 issue #685 作为背景，验证了「从已完成批次出发」这一语义的正确性。

需要说明的是，该修复只是求值范围收窄，Graph 原有的核心能力不受影响：确定性依赖解析、并行批次执行、环形图（反馈回路）支持、嵌套 Graph（Graph 作为另一个 Graph 的节点）、基于GraphBuilder的构建器模式，以及reset_on_revisit/max_node_executions/execution_timeout/node_timeout等执行限制配置，在 v1.31.0 中均保持不变。

OpenAI 模型层：三处修正

工具消息始终使用字符串内容

在 strands-py/src/strands/models/openai.py 的format_request_tool_message中，工具结果现在会被合并为单个字符串：相邻的文本块以\n拼接；仅当存在图片/文档等非文本内容时才保留数组格式，以便后续_split_tool_message_images能把图片抽取到独立 user 消息中（OpenAI API 只允许图片出现在 user 角色消息里）。这项修复提高了与 OpenAI 兼容端点（如 vLLM、Ollama 等）的互操作性，避免部分端点拒绝非字符串格式的 tool 消息内容。

Responses API 错误处理

stream与structured_output中的openai.APIError异常分支经由classify_openai_error（strands-py/src/strands/models/_openai_errors.py）分类：限流错误映射为ModelThrottledException，上下文溢出映射为ContextWindowOverflowException，其余错误原样抛出。v1.31.0 修正了 Responses API 路径下未覆盖的异常分支，保证结构化输出与普通流式调用在错误分类行为上一致。

openai 依赖放宽至 2.x

为了让 strands-agents 能与 litellm 共存于同一依赖树，v1.31.0 将 openai 依赖范围放宽以支持 2.x。对使用者而言，这意味着在同时使用 litellm 路由与原生 OpenAI provider 的项目中，不再需要因为传递依赖冲突而锁定旧版 openai。

会话持久化：S3 管理器与多模态序列化修复

S3 会话管理器 bug

S3SessionManager（strands-py/src/strands/session/s3_session_manager.py）把会话数据组织为session_<id>/session.json、agents/agent_<id>/agent.json、messages/message_<id>.json的层级结构。构造函数支持bucket、prefix、boto_session、boto_client_config、region_name以及面向 MinIO/LocalStack/PrivateLink 的endpoint_url参数，并自动为请求注入strands-agents用户代理标识。list_messages在分页读取时借助ThreadPoolExecutor并行拉取消息对象并保持顺序稳定。本次修复针对该管理器的行为缺陷（如对象存在性检查、批量删除等路径）进行了纠正，云端会话读写现在更加健壮。

Graph/Swarm 多模态二进制内容序列化

此前把包含图片、文档等二进制内容的多模态提示写入 Graph/Swarm 会话持久化时，会因二进制字节无法直接 JSON 序列化而抛出TypeError。v1.31.0 在 strands-py/src/strands/types/session.py 的encode_bytes_values/decode_bytes_values辅助函数基础上修正了序列化路径：Graph.serialize_state对current_task做字节编码，deserialize_state在恢复时解码还原，从而保证多模态会话在重启或跨进程恢复后内容完整可用。

细节修复：代码片段语言标识小写化

最后一条变更把文档代码片段中的Python标识统一改为小写python。这是一个纯展示层面的修正，作用是让 Markdown/静态站点渲染出的代码高亮与标准语言标识保持一致，不涉及任何运行时行为。

升级建议与影响评估

v1.31.0 的全部 8 条变更均为非破坏性，可直接升级。升级后建议重点回归三条链路：

1. A2A 调用：确认client_config与a2a_client_factory未同时使用，并验证带认证端点的 Card 发现与消息发送正常（strands-py/src/strands/agent/a2a_agent.py）；
2. Graph 编排：运行测试用例 strands-py/tests/strands/multiagent/test_graph.py 中的test_find_newly_ready_nodes_only_evaluates_outbound_edges，确认依赖顺序语义符合预期；若使用了依赖invocation_state的新式边条件，需同时验证 A2A 请求上下文与 Graph 路由的联动；
3. 模型接入：使用 OpenAI 兼容端点时确认工具消息以字符串内容发送、错误分类（限流/上下文溢出）行为符合预期，且 openai 2.x 与 litellm 的共存未引入新的兼容问题。

对于使用S3SessionManager的云端部署，升级后建议做一次会话创建、读取、分页列举与删除的完整回归，确保endpoint_url（MinIO/LocalStack 场景）与prefix路径组织行为一致。若你的工作负载涉及多模态提示，则务必回归 Graph/Swarm 的会话持久化路径，验证二进制内容在序列化-恢复往返后不丢失、不报错。

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