企业官网建设流程全解析

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

导读

本文围绕 strands SDK Python 分支 v0.2.0 版本的发布变更展开，系统梳理该版本在 Agent 执行模型、结构化输出、模型接入、可观测性与内部架构上的关键演进。读者将掌握：新引入的迭代式事件循环与迭代式 Agent 用法、Agent State 状态管理的语义、Mistral / OpenAI reasoning 内容等模型层能力、tracer 重构后的自定义配置方式，以及本次破坏性变更（移除 FunctionTool）对升级的影响。文中所有结论均以当前仓库源码与配置为佐证。

版本总览

strands SDK 的 Python 分支在 v0.2.0（2025-07-02 发布）完成了从"一次性调用"到"可迭代、可状态化"执行模型的转变。本次版本的核心主题可以概括为四类：

1. 迭代式执行模型：事件循环（event loop）、Agent 与结构化输出全部迭代化；
2. Agent 状态（Agent State）：Agent 携带可序列化状态跨会话运行；
3. 模型层扩展：新增 Mistral 支持、OpenAI 推理内容（reasoning content）、Bedrock 常见错误补充异常信息、boto3 会话区域复用；
4. 可观测性与内部清理：tracer 重构、自定义 tracer provider、GenAI 语义约定更新、移除 FunctionTool 等破坏性变更。

该版本同时迎来了两位新贡献者（siddhantwaghjale 与 RingoIngo2），涉及 A2A tools as skills 与模型并发请求 debug 日志两项功能。包的版本由 git tag 驱动（tag_regex = "^python/v(?P<version>.+)$"），见 strands-py/pyproject.toml。

迭代式执行模型：事件循环、Agent 与结构化输出的统一迭代化

v0.2.0 最核心的架构变化，是 PR #268、#291、#295、#328 共同将执行链路改造为迭代器（iterator）驱动：

• 迭代式事件循环（iterative event loop，PR #268）：Agent 主循环被重构成可逐步推进的迭代过程，调用方可以按需拉取事件流，而不是被动等待整个回合结束；
• 迭代式 Agent（iterative agent，PR #295）：Agent 本身支持迭代式执行，允许在回合之间注入控制逻辑；
• 迭代式结构化输出（iterative structured output，PR #291）：结构化输出流程同样改为迭代器语义，配合 Mistral 的structured_output迁移（PR #305，见 strands-py/src/strands/models/mistral.py）实现统一的流式体验；
• executor 工具运行改为 yield（PR #328）：工具执行器executor - run tools - yield，工具结果以生成器方式产出，进一步强化整条链路的流式特性。

从源码看，Agent.run的内部实现调用self._execute_event_loop_cycle(...)循环推进事件循环（见 strands-py/src/strands/agent/agent.py），StructuredOutputContext在每次调用中注册并清理结构化输出工具。这意味着 v0.2.0 之后，开发者可以用标准的 Python 迭代/异步迭代方式消费 Agent 产生的中间事件，为流式 UI、逐步调试和细粒度控制打开了空间。

Agent State：可序列化的状态管理

PR #292 引入Agent State，PR #334 将相关单元测试整合。当前仓库中AgentState定义为JSONSerializableDict的类型别名（见 strands-py/src/strands/agent/state.py），是 Agent 构造参数之一。

Agent构造函数接受state: AgentState | dict | None（见 strands-py/src/strands/agent/agent.py）：

• 传入AgentState对象时直接使用；
• 传入普通 dict 时包装为AgentState(state)；
• 其他类型抛出ValueError("state must be an AgentState object or a dict")（见 strands-py/src/strands/agent/agent.py）；
• 缺省时初始化为空AgentState()。

在会话恢复场景中，Agent从持久化数据里还原self.state = AgentState(data["state"])（见 strands-py/src/strands/agent/agent.py），说明 state 是跨调用持久化的核心载体。对构建多轮、可恢复的生产 Agent 而言，这是 v0.2.0 提供的标准状态通道。

模型层：Mistral 接入、OpenAI 推理内容与 Bedrock 错误增强

新增 Mistral 模型支持

PR #284 为 strands 引入 Mistral 支持，PR #305 将 Mistral 的structured_output迁移为迭代器实现。安装时需要引入对应 extra：

pip install 'strands-agents[mistral]'

extra 声明位于 strands-py/pyproject.toml：mistral = ["mistralai>=2.0.0,<3.0.0"]。模型实现位于 strands-py/src/strands/models/mistral.py。

OpenAI Provider 增加 reasoning content

PR #187 为 OpenAI 模型 provider 增加推理内容支持。在 strands-py/src/strands/models/openai.py 中可以看到完整的推理内容链路：

• 读取message.reasoning_content（兼容message.reasoning字段）作为推理文本（L638-L646）；
• 流式场景下从choice.delta提取reasoning_content或reasoning，并切换到reasoning_content数据块类型（L755-L767）；
• 流式事件中，reasoning_content数据会被转换为contentBlockDelta下的reasoningContent文本块（L584-L585）。

同时代码中保留了对推理模型多轮对话限制的警告：当检测到历史消息中包含reasoningContent时，提示 Chat Completions API 不支持多轮推理内容（L410-L419）。

Bedrock 常见错误补充异常信息

PR #290 为常见 Bedrock 错误增加异常信息。从 strands-py/src/strands/models/bedrock.py 可以观察到模型层对reasoningContent的完整处理，包括：

• 对 DeepSeek 系列模型的特殊过滤——reasoningContent在 DeepSeek 多轮对话中存在已知问题，代码会丢弃并记录过滤日志（L836-L896）；
• 完整保留reasoningText的text与signature字段、redactedContent字段（L1064-L1080）；
• 流式增量事件中同样透出reasoningContent的文本与签名（L1606-L1621）。

会话区域复用

PR #299 让 strands 在可能时使用 boto3 会话中的 region，避免重复配置区域信息，属于 Bedrock/会话层的一致性问题修复。

结构化输出：保留$defs与工具化实现

PR #294 修复了工具 schema 生成时移除$defs的问题，使嵌套 JSON Schema 的$defs定义得以保留——这对于包含复用子模型的复杂 Pydantic 输出类型至关重要。

当前仓库中的实现为StructuredOutputTool（见 strands-py/src/strands/tools/structured_output/structured_output_tool.py）：

• 工具 spec 按 Pydantic 模型类缓存（_TOOL_SPEC_CACHE），命中后深拷贝返回（L55-L57）；
• 工具描述被强制改写为"仅在返回最终结果前最后一次调用"的指令（L38-L42）；
• 校验成功时通过StructuredOutputContext.store_result保存结果（L112-L114）；
• 校验失败时（ValidationError）逐字段生成错误明细，以error状态的 ToolResult 回传给模型，让其自行决定是否修正重试（L124-L146）；
• 其他异常则记录堆栈并返回错误结果（L148-L157）。

这解释了 v0.2.0 中"结构化输出迭代化"的落地形态：结构化输出不再是一个独立的黑盒 API，而是注册进工具注册表的普通工具，走统一的工具执行与错误处理管线。

可观测性：tracer 重构与自定义 provider

v0.2.0 对可观测性做了密集投入，共 6 项相关变更：

• tracer 重构（PR #286）：重构 tracer 模块（refactor tracer），同时修正了 tracer.py 中一处引用不存在参数的 docstring（PR #293）；
• 自定义 tracer_provider 与 chain 设置（PR #316）：允许用户注入自定义的tracer_provider，并支持自定义链路（chain）装配；
• GenAI span 语义约定更新（PR #319）：按 OpenTelemetry 生成式 AI 语义约定更新 span 属性；
• token span 更新（PR #296）：更新 spanKind 与 token 相关 attributes；
• 停止传递 callback handler（PR #323）：执行链路不再层层传递回调处理器，简化了追踪上下文的管理；
• 模型并发请求 debug 日志（PR #297）：为模型 converse 请求增加 debug 级日志，便于排查 Bedrock 等服务的请求明细。

依赖侧，otel 相关依赖作为顶层依赖固定为opentelemetry-api/opentelemetry-sdk1.30.x 以上（见 strands-py/pyproject.toml），且提供otelextra 引入 OTLP HTTP 导出器（strands-py/pyproject.toml）。升级到 v0.2.0 后，需要按新语义约定重新核对既有 dashboard 的 span 命名与 token 属性。

A2A：Tools as Skills

PR #287 在 A2A（Agent-to-Agent）scope 下将tools 作为 skills暴露，使跨 Agent 调用时可以按技能（skill）粒度描述与路由工具。A2A 相关依赖集中在a2aextra（a2a-sdk、uvicorn、fastapi 等，见 strands-py/pyproject.toml），相关实现可参考 strands-py/src/strands/agent/a2a_agent.py。

破坏性变更与内部清理

v0.2.0 包含若干破坏性/移除性变更，升级时需特别注意：

• 移除 FunctionTool（PR #325）：Remove FunctionTool as a breaking change。依赖FunctionTool的代码必须迁移到新的工具抽象（如AgentTool体系，见 strands-py/src/strands/tools/structured_output/structured_output_tool.py 中的实现模式）；
• 移除 Agent 调用后的 kwargs 展开（PR #289）：remove kwargs spread after agent call，调用返回值的处理方式需要调整；
• 移除未使用代码（PR #326）：清理死代码，减少维护面。

此外还有两项涉及调用形态的"other"类变更：stop passing around callback handler（PR #323，见上）与executor - run tools - yield（PR #328），都要求使用者以迭代/事件流的方式消费工具结果。

杂项修复与文档

• 文档警告修复（PR #303）：修复文档构建警告；
• #320 复现测试（PR #322）：新增复现测试用例，为后续修复提供回归保障；
• 新增贡献者：siddhantwaghjale（Mistral 支持）与 RingoIngo2（debug 日志）。

升级建议与源码指引

升级到 v0.2.0 时建议按以下顺序核对：

1. 工具层：替换所有FunctionTool用法（PR #325），确认$defs保留后嵌套 schema 仍能通过校验（PR #294）；
2. 执行层：将 Agent/事件循环调用改造成可迭代消费形态（PR #268/#295/#328），工具结果改为从生成器获取；
3. 状态层：如有跨会话需求，通过Agent(state=...)传入AgentState（strands-py/src/strands/agent/state.py）；
4. 模型层：Mistral 用户按strands-agents[mistral]extra 安装（strands-py/pyproject.toml）；OpenAI 推理模型用户确认reasoning_content的消费逻辑（strands-py/src/strands/models/openai.py）；
5. 可观测性：按 GenAI 语义约定更新 span 属性，如需自定义链路可注入tracer_provider（PR #316/#319）。

本文涉及的版本事实均来自 site/src/content/changelog/sdk/python-v0.2.0.md，源码佐证见 strands-py/src/strands/agent/agent.py、strands-py/src/strands/models/ 与 strands-py/pyproject.toml。相关集成测试可在 strands-py/tests_integ/ 中继续追踪对应能力的行为验证。

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