feat(adk): add BeforeFinalAnswer hook to ChatModelAgentMiddleware

[shentongmartin]

Problem

When a ChatModelAgent produces a final answer (no tool calls), there was no way to inspect or reject it before the agent exits. Users had no quality gate for cases like:

• FinishReason=length (context window overflow, truncated response)
• Empty content (model returned nothing useful)
• Repeated or low-quality output

The earlier approach of extending ModelRetryConfig to handle these cases blurred the line between transient error recovery and response quality gating — two fundamentally different concerns.

Solution

Add a BeforeFinalAnswer hook to ChatModelAgentMiddleware that acts as a quality gate on final answers. When the model produces a response with no tool calls, the hook inspects it and decides: accept (agent exits) or reject (loop back for another iteration).

type ChatModelAgentMiddleware interface {
    // ...existing methods...
    BeforeFinalAnswer(ctx context.Context, state *ChatModelAgentState) (context.Context, bool, *ChatModelAgentState, error)
}

The hook receives the full ChatModelAgentState (with the model's response as the last message in Messages). It can:

• Inspect FinishReason, content, or any aspect of the response
• Modify state.Messages (e.g., append a "please continue" user message)
• Return accept=false to trigger another iteration

Rejected answers count toward MaxIterations, providing a natural cap against runaway loops.

Key Insight

The hook is embedded directly in the existing graph branch — no extra node needed for routing. In the ReAct graph, the toolCallCheck branch already decides between "tool calls → continue loop" and "no tool calls → exit." We extend this same branch to become a 3-way decision:

ChatModel → [toolCallCheck branch]
              → compose.END              (no tool calls + accepted)
              → FinalAnswerRejection     (no tool calls + rejected → loops back to ChatModel)
              → CancelCheck              (tool calls → tool execution loop, unchanged)

The FinalAnswerRejection node is needed solely for type conversion (Message → []Message from state) — the actual decision logic lives entirely in the branch function. This keeps the graph topology minimal.

A second insight: the stateModelWrapper already writes the model's response into State.Messages via compose.ProcessState before the branch runs. So the hook naturally sees the complete response without any special plumbing.

Decisions

Why a middleware hook instead of extending ModelRetryConfig?

ModelRetryConfig is about transient error recovery — low-level, sits in the model wrapper, fires on error returns. Response quality gating is a higher-level concern that should integrate with the agent's iteration system. Making it a middleware hook means:

• It composes with other middleware (BeforeModelRewriteState, AfterModelRewriteState, etc.)
• It naturally uses MaxIterations for capping (no separate MaxRetries to configure)
• It doesn't interfere with error retry semantics
• Each rejected attempt is visible to the user via AgentEvent (the event sender sits inside the retry wrapper)

Why convert the no-tools path from Chain to Graph?

The no-tools path previously used compose.NewChain (linear, no loop). To support BeforeFinalAnswer rejection (which requires looping back), we converted it to compose.NewGraph with the same Init → ChatModel → [branch] topology. This gives uniform architecture between tools and no-tools paths, and the MaxIterations enforcement is identical.

Summary

Problem	Solution
No quality gate for model final answers (truncated, empty, low-quality)	BeforeFinalAnswer hook on ChatModelAgentMiddleware — inspect and accept/reject
Response quality was conflated with error retry in ModelRetryConfig	Separate concerns: ModelRetryConfig for errors only, BeforeFinalAnswer for response quality
No-tools path used Chain (no loop capability)	Converted to Graph with same branch-based architecture as ReAct path

---

问题

当 ChatModelAgent 产生最终回答（无 tool 调用）时，没有机制在 agent 退出之前检查或拒绝该回答。用户无法对以下场景做质量把关：

• FinishReason=length（上下文窗口溢出，回答被截断）
• 空内容（模型没有返回有用内容）
• 重复或低质量输出

之前尝试扩展 ModelRetryConfig 来处理这些场景，但这模糊了瞬态错误恢复和响应质量把关之间的界限——这是两个本质不同的关注点。

方案

在 ChatModelAgentMiddleware 上新增 BeforeFinalAnswer 钩子，作为最终回答的质量关卡。当模型产生无 tool 调用的响应时，该钩子检查并决定：接受（agent 正常退出）或拒绝（循环回去进行下一次迭代）。

type ChatModelAgentMiddleware interface {
    // ...已有方法...
    BeforeFinalAnswer(ctx context.Context, state *ChatModelAgentState) (context.Context, bool, *ChatModelAgentState, error)
}

钩子接收完整的 ChatModelAgentState（模型的回答是 Messages 中的最后一条消息）。它可以：

• 检查 FinishReason、内容或回答的任何方面
• 修改 state.Messages（例如追加一条 "请继续" 的用户消息）
• 返回 accept=false 触发新一轮迭代

被拒绝的回答计入 MaxIterations，自然防止无限循环。

核心洞见

钩子直接嵌入现有的图分支中 —— 路由无需额外节点。在 ReAct 图中，toolCallCheck 分支原本在 "有 tool 调用 → 继续循环" 和 "无 tool 调用 → 退出" 之间做决策。我们将这个分支扩展为三路决策：

ChatModel → [toolCallCheck branch]
              → compose.END              (无 tool 调用 + 接受)
              → FinalAnswerRejection     (无 tool 调用 + 拒绝 → 循环回 ChatModel)
              → CancelCheck              (有 tool 调用 → tool 执行循环，不变)

FinalAnswerRejection 节点仅用于类型转换（Message → 从 state 读取 []Message）—— 实际决策逻辑完全在分支函数中。这保持了图拓扑的精简。

第二个洞见：stateModelWrapper 在分支运行之前就已经通过 compose.ProcessState 将模型的响应写入了 State.Messages。因此钩子无需任何特殊处理就能看到完整的响应。

决策

为什么用中间件钩子而不是扩展 ModelRetryConfig？

ModelRetryConfig 用于瞬态错误恢复 —— 底层的、位于模型 wrapper 中的、在 error 返回时触发。响应质量把关是更高层次的关注点，应该与 agent 的迭代系统集成。作为中间件钩子意味着：

• 与其他中间件组合（BeforeModelRewriteState、AfterModelRewriteState 等）
• 自然使用 MaxIterations 做上限（无需单独配置 MaxRetries）
• 不干扰错误重试语义
• 每次被拒绝的尝试都通过 AgentEvent 对用户可见

为什么将无 tools 路径从 Chain 转换为 Graph？

无 tools 路径之前使用 compose.NewChain（线性，无循环能力）。为支持 BeforeFinalAnswer 拒绝（需要循环回去），我们将其转换为 compose.NewGraph，使用相同的 Init → ChatModel → [branch] 拓扑。这使 tools 路径和无 tools 路径的架构统一，且 MaxIterations 的强制机制完全一致。

总结

问题	方案
模型最终回答没有质量关卡（截断、空内容、低质量）	ChatModelAgentMiddleware 上的 BeforeFinalAnswer 钩子 —— 检查并接受/拒绝
响应质量与 ModelRetryConfig 中的错误重试混为一谈	关注点分离：ModelRetryConfig 仅处理错误，BeforeFinalAnswer 处理响应质量
无 tools 路径使用 Chain（无循环能力）	转换为 Graph，与 ReAct 路径使用相同的分支架构

[codecov]

Codecov Report

❌ Patch coverage is 80.00000% with 23 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (alpha/09@28a9142). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
adk/react.go	79.27%	20 Missing and 3 partials ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             alpha/09     #922   +/-   ##
===========================================
  Coverage            ?   82.52%           
===========================================
  Files               ?      161           
  Lines               ?    21610           
  Branches            ?        0           
===========================================
  Hits                ?    17834           
  Misses              ?     2552           
  Partials            ?     1224           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.