企业官网建设流程全解析

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

本篇文章基于当前仓库中 Python SDK v1.23.0 发布说明 展开，系统梳理该版本在模型重试、钩子（Hook）体系、模型兼容性、遥测与多智能体等方向的全部变更，并结合 strands-py 源码逐一佐证其底层实现。读完本文，你将掌握Agent(retry_strategy=...)的完整用法与指数退避原理、BeforeInvocationEvent消息注入能力、OTEL_SERVICE_NAME覆盖规则，以及 Bedrock / Gemini / LiteLLM 相关修复的具体影响。

版本总览：一次以稳定性与可观测性为主的增量发布

python/v1.23.0于 2026-01-21 发布，共包含 20 条变更记录，全部为**非破坏性（breaking: false）**更新，从类型上可分为：

• 新特性（feat）：可配置的模型调用重试策略、OTEL_SERVICE_NAME覆盖服务名、允许对AfterModelCallEvents进行 steering、多智能体钩子事件从实验性毕业；
• 缺陷修复（fix）：MCP 会话挂起、AgentResult.__str__引文提取、Bedrock 强制工具选择时禁用思考模式、Gemini 唯一toolUseId、LiteLLM 流式响应缺失usage属性、PEP 563 与@tool装饰器不兼容等；
• 其他（other）：S3 会话并行读取、Swarm 中断/恢复周期执行时间累积、A2A artifact 更新事件、BidiAgent 支持 Nova Sonic 2，以及依赖升级与测试稳定性改进。

本次发布还迎来了 8 位新贡献者（maxrabin、tmokmss、okamototk、strands-agent、brycewcole、CrysisDeu、AirswitchAsa、lanazhang），其中大部分贡献直接落在上面提到的模型兼容性与钩子能力上。

核心新特性：可配置的模型调用重试策略（retry_strategy）

v1.23.0 最重要的功能新增是 Agent 支持通过retry_strategy参数控制模型调用遇到节流（throttling）等瞬时错误时的重试行为。

三种配置方式

从 agent.py 的构造签名可以看到，retry_strategy是一个类型为ModelRetryStrategy | _DefaultRetryStrategySentinel | None的参数，实际解析逻辑（见 agent.py）区分三种情况：

若传入的类型不是ModelRetryStrategy，Agent 会抛出ValueError("retry_strategy must be an instance of ModelRetryStrategy")进行校验。

指数退避的底层实现

ModelRetryStrategy 是一个基于钩子机制实现的HookProvider，其核心参数与算法如下：

• max_attempts：总模型尝试次数（默认 6），超过后直接抛出原始异常；
• initial_delay：初始退避秒数（默认 4），前两次重试使用，随后每次翻倍；
• max_delay：退避上限秒数（默认 240），防止无限拉长。

延迟计算公式为min(initial_delay * (2**attempt), max_delay)，因此默认配置下 5 次重试的延迟序列为4s → 8s → 16s → 32s → 64s，第 6 次尝试仍失败才放弃（见 _retry.py 的文档说明）。

钩子驱动的重试流程

该策略通过register_hooks注册两个回调（_retry.py）：

1. AfterModelCallEvent：每次模型调用结束后触发。若event.stop_response不为空（调用成功）或event.exception为空，则重置重试状态；若异常且is_retryable()返回 True，则递增尝试计数、await asyncio.sleep(delay)后置event.retry = True触发重试（_retry.py）；
2. AfterInvocationEvent：整个 invocation 结束后重置重试状态，保证跨请求不残留计数。

默认的is_retryable()只识别ModelThrottledException，但实现文档明确说明：子类化并重写is_retryable即可在不重写整个重试策略的情况下扩展或收窄可重试异常集合（_retry.py）。同时 Agent 构造完成后会通过self.hooks.add_hook(self._retry_strategy)把策略注册进钩子体系（agent.py）。

在模型路由场景中，router.py 也会以HookOrder.MODEL_ROUTING顺序监听AfterModelCallEvent，并在路由推进失败时调用event.agent._retry_strategy._reset_retry_state()重置状态，保证与重试策略协同工作。

配套测试验证

test_agent_retry.py 覆盖了四个关键场景：默认策略参数（max_attempts=6）、None禁用重试（等价max_attempts=1）、自定义参数生效（max_attempts=3, initial_delay=2, max_delay=60）、以及非法类型触发ValueError。这些测试可以直接作为你使用retry_strategy时的最小示例。

钩子体系增强：消息可见性、事件可 steering 与多智能体事件转正

BeforeInvocationEvent 暴露输入消息

PR #1474 让 BeforeInvocationEvent 携带messages: Messages | None字段。该事件在Agent.__call__、Agent.stream_async、Agent.structured_output三类 API 调用开始时触发，钩子可以通过就地修改messages实现内容脱敏或转换，也可以通过设置cancel（布尔值或字符串）取消本次 invocation。这对安全审计、输入校验、隐私脱敏类钩子非常有价值——以往需要在更深的调用链中拦截输入，现在在请求入口即可完成。

AfterModelCallEvent 支持 steering

PR #1429 允许对AfterModelCallEvent（hooks/events.py）进行 steering。在 strands 的 steering 机制中，事件监听器可以“接管”事件结果，结合本次重试策略同样基于该事件实现，意味着开发者现在可以在模型调用返回后、重试判定前插入自定义逻辑——例如根据stop_reason或异常类型动态改写模型输出、注入自定义错误处理。相关实现可参见 steering 核心处理器 与 事件定义。

多智能体钩子事件从实验性毕业

PR #1498 将多智能体（multiagent）钩子事件从 experimental 状态转为正式 API。结合 PR #1478 实现的“interrupts - graph - hook based”能力，v1.23.0 之后，多智能体图（graph）场景下的中断可以由钩子事件驱动，而非只能在代码中硬编码中断点。这意味着编排逻辑可以以声明式钩子的方式表达，图执行的控制流更加灵活。

模型兼容性修复：Bedrock、Gemini 与 LiteLLM

Bedrock：强制工具选择时禁用思考模式

PR #1495 修复了 Bedrock 模型在强制tool_choice（强制模型必须调用指定工具）时仍可能开启思考模式（thinking mode）的问题。工具强制选择与思考链同时启用会破坏工具调用的确定性，修复后系统在强制tool_choice场景下自动禁用思考模式，保证工具调用路径的稳定。

Gemini：唯一 toolUseId

PR #1201 为 Gemini 模型提供唯一的toolUseId。此前 Gemini 在多次工具调用时可能出现工具使用 ID 重复，导致工具结果与调用无法一一对应；配合 PR #1521 引入的本地tool_use_id_to_name映射（gemini - tool_use_id_to_name - local），Gemini 的工具调用追踪链路在本次版本中得到完整补强。

LiteLLM：容忍缺失的 usage 属性

PR #1520 修复了通过 LiteLLM 接入模型时，ModelResponseStream可能缺失usage属性的问题。流式响应并非总能携带 token 用量统计，修复后相关代码路径对缺失usage采取容错处理，避免在统计 token 时抛出AttributeError中断流式输出。

遥测：用 OTEL_SERVICE_NAME 覆盖服务名

PR #1400 支持通过环境变量OTEL_SERVICE_NAME覆盖 OpenTelemetry 资源中的服务名。在 telemetry/config.py 中：

service_name = os.getenv("OTEL_SERVICE_NAME", "strands-agents").strip()

即默认服务名为strands-agents，设置了OTEL_SERVICE_NAME后，上报到 OTLP 后端的 trace/metric 资源均会带上自定义服务名。该模块同时支持OTEL_EXPORTER_OTLP_ENDPOINT（OTLP 端点 URL）与OTEL_EXPORTER_OTLP_HEADERS（请求头）等标准环境变量（config.py），便于在 Kubernetes 或多租户环境中区分不同服务实例的遥测数据。

多智能体与 A2A：Swarm 计时修复、Nova Sonic 2 与 artifact 事件

• Swarm 执行时间累积（PR #1502）：修复了多智能体 swarm 在 interrupt/resume（中断/恢复）周期中execution_time被重置的问题，现在执行时间在多次恢复中正确累积，避免“恢复后执行时间倒退”的统计失真。
• BidiAgent 支持 Nova Sonic 2（PR #1476）：BidiAgent 新增对 Nova Sonic 2 语音模型的支持，扩展了双向语音会话的模型覆盖面。
• A2A artifact 更新事件（PR #1401）：A2A（Agent-to-Agent）协议交互改用 artifact update 事件传递内容，使跨 Agent 内容推送语义更贴合 A2A 规范。

会话存储：S3SessionManager.list_messages() 并行读取

PR #1186 为 S3 会话存储 的S3SessionManager.list_messages()增加了并行读取能力。当会话消息分散在多个 S3 对象时，串行拉取会成为长会话的瓶颈；并行读取显著缩短了历史消息的加载时间。这是对长会话、恢复断点场景直接有效的性能优化。

工具与工程质量：PEP 563、测试稳定性与依赖升级

• PEP 563 兼容性修复（PR #1494）：修复了@tool装饰器装饰的工具在启用from __future__ import annotations（PEP 563 延迟注解）时的兼容性问题，确保注解为字符串形式时工具 schema 的生成不受影响；
• 测试去睡眠化（PR #1497）：将单元测试中的sleep等待替换为显式信号（signaling），消除测试中的隐式时序依赖，降低 CI 抖动；
• Guardrail 测试稳定性（PR #1505）：降低 guardrail 输出脱敏（redact）测试的 flakiness；
• 工具链现代化（PR #1336）：更新 ruff 配置，应用 pyupgrade 规则以现代化 Python 语法，为后续版本迁移到更新语法特性铺路；
• 依赖升级：sphinx-rtd-theme上限从<2.0.0放宽到<4.0.0（PR #1466），websockets上限从<16.0.0放宽到<17.0.0（PR #1451），均为兼容性扩围；
• AgentResult.__str__引文提取（PR #1489）：__str__输出时正确从citationsContent中提取文本，避免在字符串表示中暴露原始结构或造成格式化异常；
• MCP 会话挂起修复（PR #1396）：通过检查会话关闭状态（session closure state）防止 MCP 客户端在会话已关闭时继续等待，杜绝 Agent 进程挂起。

升级与使用建议

1. 为生产 Agent 显式配置重试：默认 6 次尝试、最长 240s 退避对大多数节流场景足够；若你对延迟敏感，可自定义ModelRetryStrategy(max_attempts=3, initial_delay=1, max_delay=30)收紧策略；需要完全关闭重试时传retry_strategy=None；
2. 接入 OpenTelemetry 时设置服务名：在部署环境中配置OTEL_SERVICE_NAME环境变量，配合OTEL_EXPORTER_OTLP_ENDPOINT，即可在控制台按服务维度区分遥测数据；
3. 钩子消费者注意消息可变性：BeforeInvocationEvent.messages支持就地修改用于脱敏，但修改会影响后续模型调用输入，需谨慎设计；
4. 升级无忧：本次全部变更均为非破坏性，Agent构造参数与既有钩子 API 完全向后兼容，可放心升级。

整体而言，v1.23.0 是一次典型的“稳定性 + 可观测性 + 模型兼容性”增量发布：重试策略与遥测服务名覆盖提升了生产可用性，Gemini/Bedrock/LiteLLM 的修复扫清了多模型接入的隐患，钩子体系与多智能体事件的能力演进则为更复杂的编排场景打开了空间。

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