在最新的 eino v0.9.7 版本中，有一个非常关键的修复值得重点关注：
fix(adk): wire ModelFailoverConfig into agentic ReAct path
这次更新虽然从提交内容来看只有 1 个 commit、2 个文件变更、62 行新增、8 行删除，但它修复的是一个容易被忽略、却会直接影响稳定性的核心问题：
当 Typed Agent 配置了工具（Tools）时，ReAct 路径下的 ModelFailoverConfig 可能不会真正生效。
对于依赖模型容错、自动切换、故障恢复的场景来说，这个修复非常重要。下面就结合这次 v0.9.7 的更新内容，详细拆解这次变更到底改了什么、为什么改、验证了什么，以及它对 Typed Agent 的实际意义。
一、v0.9.7 更新概览
本次版本信息如下：
- 版本号：v0.9.7
- 发布时间：2026年6月15日
- 更新类型：修复
- 变更摘要：
- 修复 adk 中 agentic ReAct 路径没有正确接入 ModelFailoverConfig 的问题
从变更规模来看：
- 1 commit
- 2 files changed
- 1 contributor
- 72 additions
- 8 deletions
看起来是一个小版本修复，但它针对的是 Typed Agent 在 带工具 场景下的 failover 逻辑，这类问题往往不是功能“缺失”，而是“配置传递断裂”，实际影响会在运行时才暴露出来。
二、这次修复的核心问题是什么
这次更新的提交信息已经把问题说得很清楚：
fix(adk): wire ModelFailoverConfig into agentic ReAct path
意思是：
把 ModelFailoverConfig 接入 agentic ReAct 执行路径。
结合测试说明可以进一步明确问题本质：
buildAgenticReActRunFunc 之前丢掉了 failover config，导致 ModelFailoverConfig 对于那些配置了任何 tools 的 typed agents 来说形同虚设。
也就是说，问题并不在 ModelFailoverConfig 本身，而在于：
- Typed Agent 走 Agentic ReAct 路径时
- 如果配置了 tools
- 构建运行函数的过程中
- ModelFailoverConfig 没有被正确传入内部模型包装配置
- 最终导致故障切换逻辑不执行
这个问题最危险的地方在于：
表面上你配置了 failover，但实际运行时它没有被用上。
三、为什么这个问题会发生在 ReAct with-tools 路径
从这次修改点可以看出，问题发生在 buildAgenticReActRunFunc 这个函数里。
在 Typed Chat Model Agent 中，执行路径会根据是否存在 tools 等配置进入不同逻辑。
而这次修复针对的是：
- agentic ReAct path
- with-tools
- *schema.AgenticMessage
也就是说，这不是普通纯模型生成路径，而是：
这也是为什么新增测试专门叫：
TestAgenticFailoverGenerate_WithTools
它就是为了验证：
在有 tools 的 ReAct 场景下，ModelFailoverConfig 是否真的被执行。
四、这次代码修改具体改了什么
这次变更主要集中在 adk/chatmodel.go，同时新增了一个测试用例在 adk/agentic_test.go。
1. adk/chatmodel.go 中的关键改动
这次在 buildAgenticReActRunFunc 里，给 typedModelWrapperConfig 增加了：
- failoverConfig: any(a.modelFailoverConfig).(*ModelFailoverConfig[*schema.AgenticMessage])
原来这里的配置中，已经有：
- handlers
- middlewares
- retryConfig
- toolInfos
但是 缺少 failoverConfig。
也就是说，模型包装器拿到的配置里只有重试，没有故障切换。
本次修复就是把：
- a.modelFailoverConfig
正确塞进：
- typedModelWrapperConfig[*schema.AgenticMessage]
从而让 ReAct with-tools 路径也能够感知 failover 配置。
2. 同文件中的执行上下文也补充了 failover 相关信息
在 withTypedChatModelAgentExecCtx 这段上下文构建中，也新增了：
- failoverLastSuccessModel: agenticModel
这个字段的加入说明：
在执行过程中，系统不仅要知道当前模型是谁，还要能记录 failover 场景下“上一次成功的模型”。
这对于后续故障切换恢复逻辑是非常关键的，因为 failover 不只是“换一个模型”，还需要知道：
- 之前成功的是哪个模型
- 失败时的错误是什么
- 当前第几次 failover
- 是否继续重试或切换
这次修复虽然看起来只是增加了一个字段，但从语义上说，它补齐了 failover 执行链路中的上下文信息。
五、新增测试做了什么
为了防止这个问题再次回归，本次更新新增了一个非常有针对性的测试：
TestAgenticFailoverGenerate_WithTools
这个测试的目标写得很明确：
验证 ModelFailoverConfig 在带工具的 ReAct 路径上是否生效。
防止 buildAgenticReActRunFunc 丢失 failover config，导致 typed agents 在配置了 tools 时 failover 失效。
这段测试逻辑很完整，结构如下：
1. 初始化测试上下文
ctx := context.Background()
使用基础上下文启动测试流程。
2. 构造两个模型
模型 m1
- 第一次生成时直接失败
- 返回错误：m1 generate failed
- 并记录调用次数
模型 m2
- 作为 failover 备用模型
- 生成成功
- 返回文本：failover ok with tools
这两个模型用于验证：
- 主模型失败后是否会触发 failover
- failover 后是否真的切换到了备用模型
3. 构造一个 dummy tool
dummyTool := newSlowTool("dummy_tool", 0, "ok")
这里的关键点是：
测试场景明确包含 tools。
因为问题就出在 ReAct with-tools 路径，所以这个 tool 不是可有可无，而是验证问题是否复现的核心条件。
4. 创建 TypedChatModelAgent
通过 NewTypedChatModelAgent 创建 agent，并配置：
- Name
- Description
- Model: m1
- ToolsConfig
- ModelFailoverConfig
其中 ModelFailoverConfig 是测试的重点，包含：
- MaxRetries: 1
- ShouldFailover: 只要有错误就触发 failover
- GetFailoverModel: 返回备用模型 m2，同时校验 failover 上下文
5. 在 GetFailoverModel 中检查上下文
这里验证了几个关键点：
- getFailoverCalls 计数是否增加
- failoverCtx.FailoverAttempt 是否为 1
- failoverCtx.LastErr 是否等于 m1Err
这些断言说明 failover 不只是被触发了，而且其上下文信息也是正确的。
6. 使用 Runner 执行 agent
runner := NewTypedRunner(TypedRunnerConfig[*schema.AgenticMessage]{Agent: agent})
iter := runner.Run(ctx, []*schema.AgenticMessage{schema.UserAgenticMessage("hello")})
随后 drain 事件流，获取最终消息。
7. 验证最终结果
测试最终断言：
- 返回结果不为空
- 内容为 "failover ok with tools"
- m1 调用 1 次
- m2 调用 1 次
- GetFailoverModel 调用 1 次
最后一个断言尤其关键：
如果 GetFailoverModel 没有被调用，说明 failover config 在 buildAgenticReActRunFunc 中被丢掉了。
这也正是此次修复要避免的问题。
六、这次修复的意义
虽然这次更新只有很少的文件改动，但它解决的是一个非常实际的稳定性问题。
1. 让 failover 配置真正进入 ReAct 执行链路
以前可能是“写了配置但没生效”，现在变成“配置能够被正确传递并执行”。
2. 修复 typed agents 在带 tools 场景下的容错断层
对于使用 typed agents 的应用来说，工具调用是很常见的能力。
如果带工具后 failover 失效，那么应用在模型异常时就可能直接失败，而不是自动切换备用模型。
3. 提升故障恢复的可靠性
ModelFailoverConfig 的意义就在于：
- 遇到错误时自动兜底
- 降低单模型依赖
- 提升系统可用性
而这次修复确保了这项能力在 agentic ReAct path 中真正生效。
七、从代码层面看，这次修复为何重要
这次改动的本质不是“新增功能”，而是补齐配置透传。
很多框架中的复杂执行路径，问题往往不在核心逻辑，而在中间层：
- 某个配置字段忘了传
- 某个 wrapper 没接上
- 某个上下文没保存
- 某条分支逻辑与主路径不一致
这次的 buildAgenticReActRunFunc 就属于这种情况。
如果没有对应测试，很容易在后续开发中再次回退。
因此，新增加的 TestAgenticFailoverGenerate_WithTools 不只是一个普通单测，它实际上是一个 回归保护测试，专门防止这类“路径分支遗失配置”的问题重新出现。
八、这次 v0.9.7 对使用者意味着什么
如果你正在使用 eino 的 Typed Chat Model Agent，尤其是以下场景：
- 使用 *schema.AgenticMessage
- 配置了 tools
- 依赖 ModelFailoverConfig
- 希望在模型失败时自动切换备用模型
那么这次 v0.9.7 很关键，因为它修复了之前可能失效的路径。
也就是说，升级之后：
- ReAct with-tools 场景下的 failover 更可信
- 备用模型切换逻辑更完整
- 故障处理链路更一致
九、这次更新的完整要点回顾
最后，把这次 v0.9.7 的内容浓缩成几个核心点：
更新信息
- 版本：v0.9.7
- 发布时间：2026年6月15日
- 更新类型：修复
修复内容
- 修复 adk 中 agentic ReAct 路径未正确接入 ModelFailoverConfig 的问题
代码修改
- adk/chatmodel.go
- 在 buildAgenticReActRunFunc 中补上 failoverConfig
- 在执行上下文中增加 failoverLastSuccessModel
- adk/agentic_test.go
- 新增 TestAgenticFailoverGenerate_WithTools
- 验证带工具的 ReAct 路径下 failover 是否生效
验证重点
- 主模型失败后是否调用 failover
- 是否正确进入备用模型
- GetFailoverModel 是否被执行
- failover 上下文信息是否正确
十、结语
代码地址：github.com/cloudwego/eino
总的来说，eino v0.9.7 这次更新虽然体量不大，但修复非常精准，直指一个关键问题：
Typed Agent 在带工具的 ReAct 路径下，ModelFailoverConfig 之前没有真正接入，导致 failover 失效。
这次补丁完成后，整个链路更完整：
- 配置能传进去
- 上下文能保存
- 失败能触发切换
- 测试能防止回归
对于依赖 Typed Agent 和模型容错机制的开发者来说，这是一次非常值得关注的小版本更新。
