企业官网建设流程全解析

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

版本信息：strands-agents（Python SDK）1.32.0，发布于 2026-03-20，属于非破坏性（breaking: false）的修复型小版本。本次更新共包含 3 项修复，分别落在 OpenTelemetry 指标采集、模型依赖管理与双向流式（bidirectional streaming）响应处理三个方向，并迎来了两位新贡献者（stephentreacy、atian8179）。

strands-agents 是 harness-sdk 仓库中面向生产环境 AI Agent 的开源 Python SDK，与 TypeScript 版本共享同一套 Agent harness 设计理念，支持任意模型、任意云环境。v1.32.0 是一个典型的"稳定优先"小版本：没有新增功能，全部精力用于让可观测性数据更完整、让依赖解析更可控、让流式工具调用语义更准确。本文将以该版本 changelog（site/src/content/changelog/sdk/python-v1.32.0.md）为骨架，逐条拆解三项修复的来龙去脉，并结合仓库源码说明它们为什么重要、修复后行为如何、以及你升级后应当如何验证。

一、v1.32.0 变更总览

该版本的 frontmatter 完整记录了发布元数据，与站点侧渲染（site/src/config/changelog.ts）中的 SDK 流标签约定一致：Python 流对应Strands harness Python。三条变更均为fix类型、均不破坏现有 API，具体如下：

版本发布同时收录了两位新贡献者：stephentreacy（PR #1903）与atian8179（PR #1827）。对社区而言，这一版本也意味着双向流式（bidi）工具调用路径得到了更严谨的语义修正。

二、修复一：事件循环（Event Loop）周期指标补全结束时间与耗时

变更原文：ensure all cycle metrics include end time and duration（PR #1903，作者 stephentreacy，commitadfeb97）

2.1 这项修复针对什么问题

strands-agents 的事件循环（event loop）是 Agent 主循环的核心：每一轮"模型调用 + 工具执行"构成一个 cycle。为了对 Agent 进行可观测性监控，SDK 会为每个 cycle 记录 OTel 指标，包括 cycle 计数、起始计数、结束计数以及耗时直方图。修复前，部分 cycle 指标缺少**结束时间（end time）与耗时（duration）**的落盘，导致基于 OTel 的监控面板难以稳定地计算周期耗时趋势。

2.2 源码中的指标骨架

该修复直接作用于事件循环指标聚合层，核心实现集中在 strands-py/src/strands/telemetry/metrics.py：

• Trace数据类（约 L50-L101）内置了end_time字段与end(end_time)、duration()方法，duration()在 trace 未结束时返回None，结束时返回end_time - start_time，并在序列化输出中同时携带end_time与duration两个键；
• EventLoopMetrics维护cycle_durations: list[float]，并提供start_cycle()（约 L277）与end_cycle()（约 L305）两个入口；
• end_cycle()内部完成三件事：累加event_loop_end_cycle计数器、通过event_loop_cycle_duration直方图记录本次耗时、将耗时追加进cycle_durations列表，最后调用cycle_trace.end(end_time)为 trace 补上结束时间戳。

这正对应 changelog 中"所有 cycle 指标都包含结束时间与耗时"的修复目标：无论是计数器、直方图还是 trace，都以同一套end_time/duration语义收口。

2.3 事件循环中指标的实际触发点

指标并非凭空产生，而是在事件循环的执行路径上被真实调用。在 strands-py/src/strands/event_loop/event_loop.py 中：

• event_loop_cycle函数在每轮开始时通过agent.event_loop_metrics.start_cycle(attributes=attributes)开启一个 cycle（约 L271），并生成唯一event_loop_cycle_id；
• 在正常结束路径（约 L335）与异常/中断路径（约 L366）上均调用agent.event_loop_metrics.end_cycle(...)收尾；
• 递归子循环（约 L788）与工具调用循环结束处（约 L968）同样调用end_cycle，确保无论 Agent 从哪条路径退出 cycle，指标都能被完整记录。

这意味着修复后的行为是全局性的：只要是经由事件循环执行的 Agent 会话，每个 cycle 的结束时间与耗时都会稳定出现在 OTel 指标流中。

2.4 对应的 OTel 指标名

MetricsClient在 metrics.py（约 L587-L653）注册了相关埋点：

• event_loop_cycle_count（Counter）
• event_loop_start_cycle（Counter）
• event_loop_end_cycle（Counter）
• event_loop_cycle_duration（Histogram，单位秒）
• tool_duration（Histogram，单位秒）

升级到 v1.32.0 后，你可以在 OTel 采集端重点观察event_loop_cycle_duration直方图是否持续产出数据——这是验证本修复最直接的方式。仓库的遥测测试 strands-py/tests/strands/telemetry/test_telemetry.py 与 strands-py/tests/strands/event_loop/test_event_loop.py 覆盖了指标采集与汇总逻辑，可作为回归参考。

三、修复二：为 mistralai 依赖收紧上界

变更原文：pin upper bound for mistralai dependency（PR #1935，作者 mkmeral，commitae28397）

3.1 为什么需要给依赖加上界

Mistral 模型在 strands-agents 中通过独立的模型适配层接入，对应的可选依赖组为mistral。给mistralai设置上界（upper bound）是依赖治理的常见手段：当上游 SDK 发布破坏性变更（例如修改客户端 API、消息结构或流式事件格式）时，不加限制的宽松区间（如>=2.0.0）会让使用pip install的用户在下次安装时静默拉到不兼容版本，从而破坏模型适配层。

3.2 当前 pyproject.toml 中的实际约束

修复后的依赖声明位于 strands-py/pyproject.toml 第 55 行：

mistral = ["mistralai>=2.0.0,<3.0.0"]

即：最低要求2.0.0，最高不得超过3.0.0。这与仓库中其他模型适配组的管理风格一致，例如openai组（openai>=1.68.0,<3.0.0）、gemini组（google-genai>=1.67.0,<3.0.0）都采用"下限满足功能、上限规避破坏"的双端约束策略。同一文件第 51-53 行还以注释形式记录了 litellm 因 Python 3.14 兼容性问题而收紧版本的先例，可见该仓库对依赖版本治理有明确的工程规范。

3.3 落地位置与升级建议

• 模型适配层实现位于 strands-py/src/strands/models/mistral.py，其从mistralai.client导入Mistral客户端，因此mistralai的 API 形态直接影响适配层正确性；
• 相应测试位于 strands-py/tests/strands/models/test_mistral.py，使用了mistralai.client.models中的UserMessage类型构造消息。

升级到 v1.32.0 后，若你使用 Mistral 模型，建议执行pip install "strands-agents[mistral]"并确认解析结果落在mistralai>=2.0.0,<3.0.0区间内；若你的既有环境已装有mistralai 3.x，则需要主动降级以满足新约束。

四、修复三：流式响应含 toolUse 块时覆盖 end_turn stop reason

变更原文：override end_turn stop reason when streaming response contains toolUse blocks（PR #1827，作者 atian8179，commit38c1ab6）

4.1 场景背景

strands-agents 的实验性双向流式（bidirectional streaming，简称 bidi）能力允许 Agent 与模型之间建立持续的双向数据流。模型在流式输出中可能先发出END_TURN之类的结束信号，但随后又携带工具调用块（toolUse/tool_use）。如果 SDK 直接采信END_TURN作为最终 stop reason，Agent 循环就会错误地认为回合已结束，从而跳过本应执行的工具调用——这是流式工具调用场景中典型的"过早终止"缺陷。

4.2 修复后的行为：以工具调用语义覆盖结束信号

修复的核心逻辑体现在 strands-py/src/strands/experimental/bidi/models/bedrock.py（约 L819-L831）：

• 流式事件流中解析content_end事件并提取stopReason；
• 当stopReason == "END_TURN"但当前响应实际包含工具调用块（非最终文本）时，不再把END_TURN当作回合终点，而是将其改写为tool_use语义；
• 当stopReason == "INTERRUPTED"时映射为barge_in（用户打断），其余正常结束映射为complete，并继续维护响应转录。

这种"以响应实际内容为准、覆盖协议层结束信号"的策略，保证 Agent 的决策循环不会被提前切断。同一路径上的其他模型适配层也遵循类似的 stop reason 语义，例如 strands-py/src/strands/experimental/bidi/models/google.py 在正常结束回合时上报stop_reason="complete"。

4.3 stop reason 在下游如何被消费

• 在事件循环层，strands-py/src/strands/experimental/bidi/agent/loop.py 会依据stop_reason分派逻辑：用户打断（barge_in）、事件自然结束（event.stop_reason）、模型出错/不完整（error/incomplete，约 L605-L695）；
• 在遥测层，strands-py/src/strands/experimental/bidi/_telemetry.py（约 L103-L120）将stop_reason映射为 OTel 语义约定属性gen_ai.response.finish_reason，使"工具调用导致回合结束"这一行为在监控数据中可被清晰检索；
• 在转录层，strands-py/src/strands/experimental/bidi/io/transcript.py 通过stop_reason == "barge_in"识别并记录打断事件。

修复后，当流式响应包含工具调用块时，你会在遥测中看到gen_ai.response.finish_reason=tool_use而非错误的end_turn，Agent 也会正常进入工具执行阶段。

五、升级验证清单与影响范围

5.1 兼容性说明

v1.32.0 的三条变更breaking均为false，不涉及公共 API 破坏，升级路径平滑。但请注意以下行为差异：

• OTel 指标：event_loop_cycle_duration等周期指标的完整性提升，监控告警规则可以开始依赖end_time/duration字段；
• 依赖解析：Mistral 用户需要满足mistralai>=2.0.0,<3.0.0，若当前解析结果超出该区间，请在升级前调整；
• bidi 流式：流式工具调用的回合结束语义更准确，依赖旧"提前结束"行为的自定义逻辑（如有）需要同步审视。

5.2 建议的验证步骤

1. 升级后运行 SDK 自带遥测测试与事件循环测试，确认指标埋点路径无回归：strands-py/tests/strands/telemetry/test_telemetry.py；
2. 执行pip install "strands-agents[mistral]" --dry-run（或pip index versions mistralai）核对依赖区间；
3. 若使用 bidi 能力，构造一个"流式响应含工具调用"的用例，检查事件循环最终 stop reason 是否为tool_use，并在 OTel 后端确认gen_ai.response.finish_reason取值。

六、结语

v1.32.0 是 strands-agents Python SDK 在可观测性、依赖治理与流式语义三个维度的一次集中打磨：OTel 周期指标从此具备完整的时间维度，Mistral 依赖版本得到明确锚定，双向流式场景下的工具调用回合不再被错误的end_turn信号提前终结。对于正在生产环境运行 Agent harness 的团队，这是一个值得平滑升级的稳定版本；对于想深入了解事件循环指标链路与 bidi 流式实现的开发者，本文给出的源码路径（metrics.py、event_loop.py、bedrock.py）可作为继续阅读的入口。

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