feat(adk): integrate AgenticMessage into ADK

[shentongmartin]

Integrate AgenticMessage into ADK

Problem

The Eino framework only supported *schema.Message as the message type for agent communication. To support richer agentic interactions — including structured content blocks, MCP tool calls, multi-modal content, and vendor-specific extensions — the framework needs a new message type (*schema.AgenticMessage) integrated across all layers: schema definition, component interfaces, compose graph, ADK agent runtime, callbacks, and checkpoint serialization.

Solution

This PR introduces *schema.AgenticMessage as a first-class message type across the entire Eino stack, parameterized via the MessageType constraint (*schema.Message | *schema.AgenticMessage).

Schema Layer

• AgenticMessage with structured ContentBlock variants (text, tool call, tool result, MCP operations, images, etc.)
• Full streaming concat support for AgenticMessage
• Helper constructors: UserAgenticMessage, AssistantAgenticMessage, ToolAgenticMessage, etc.
• Vendor extension packages: schema/openai, schema/claude, schema/gemini for provider-specific metadata
• Custom GobEncode/GobDecode on MCPListToolsItem to handle jsonschema.Schema (which contains unexported orderedmap.OrderedMap fields)

Component Layer

• model.BaseModel[M] generic interface unifying BaseChatModel and AgenticModel via type aliases (backward compatible)
• prompt.AgenticChatTemplate for agentic prompt templates
• Agentic callback types for model (AgenticCallbackInput/Output) and prompt components
• ComponentOfAgenticModel, ComponentOfAgenticPrompt constants

Compose Layer

• AgenticToolsNode for executing agentic tool calls within compose graphs
• ComponentOfAgenticToolsNode constant
• Graph/chain/workflow methods for adding agentic model and tools nodes
• Checkpoint support extended for agentic message variants

ADK Layer

• TypedAgent[M], TypedChatModelAgent[M], TypedRunner[M] — all core types parameterized by MessageType
• Non-generic aliases (Agent, ChatModelAgent, Runner, etc.) default to *schema.Message for backward compatibility
• TypedAgentTool[M] for wrapping agents as tools, now supporting both *schema.Message and *schema.AgenticMessage in fullChatHistoryAsInput mode
• Cancel mechanism (TypedCancellable[M]) with preemptive and cooperative cancellation
• TurnLoop[T, M MessageType] — push-based streaming event loop now generic over both item type T and message type M, enabling orchestration of *schema.AgenticMessage agents
• agentsmd middleware for auto-injecting Agents.md into model context
• Checkpoint save/resume with gob serialization for *schema.AgenticMessage variants
• Internal state type typedState is unexported — users interact with it via ChatModelAgentState in middleware callbacks or the State alias

Callbacks

• ComponentOfAgenticAgent, AgenticAgentCallbackInput/Output, AgenticAgentCallbackHandler in HandlerHelper — the full OnStart/OnEnd callback pipeline now fires for agentic agents
• AgenticAgentCallbackHandler deliberately omits OnError — the ADK runtime does not fire OnError for agent callbacks (same as non-agentic AgentCallbackHandler), so including it would be dead code

Decisions

Why TypedAgent[M] with type aliases instead of a unified generic-only API?

Go's callback system uses interface{} (CallbackInput/CallbackOutput), so generics can't enforce type safety at callback boundaries. Type aliases (type Agent = TypedAgent[*schema.Message]) let existing code compile unchanged while new code can opt into TypedAgent[*schema.AgenticMessage]. Each component's callback layer uses distinct agentic-variant types (e.g., AgenticAgentCallbackHandler) rather than generic callback types, matching the pattern used by model, prompt, and tools node callbacks.

Why custom GobEncode on MCPListToolsItem instead of JSON for the whole message?

The any fields in AgenticMessage content blocks carry concrete types that would lose type information through JSON round-tripping. By targeting GobEncode/GobDecode at the narrowest problematic type (MCPListToolsItem, which contains *jsonschema.Schema with unexported orderedmap.OrderedMap fields), we preserve native gob encoding for all other fields.

Why add M MessageType directly to TurnLoop instead of using the Typed* + alias pattern?

TurnLoop is unreleased API. Adding M MessageType directly to the existing types (TurnLoop[T, M] instead of TypedTurnLoop[T, M] + type TurnLoop = TypedTurnLoop[T, *schema.Message]) avoids unnecessary API surface. The asymmetry with other ADK types (which use Typed* + alias) is acceptable for unreleased API since there are no backward compatibility constraints.

Why no OnError on AgenticAgentCallbackHandler?

The ADK runtime (flow.go) never fires TimingOnError for agent callbacks — neither for *schema.Message agents nor *schema.AgenticMessage agents. AgentCallbackHandler omits OnError for this reason; AgenticAgentCallbackHandler matches this by also omitting it, rather than declaring a dead field that would never be called.

Why no convenience constructors (NewRunnerFrom, NewChatModelAgentFrom, New*AgentFrom)?

These were thin wrappers over the Typed* constructors with minimal value — users only save one line at the cost of additional API surface. Removing them keeps the API minimal. Users use NewTypedChatModelAgent[M] / NewTypedRunner[M] / NewTypedSequentialAgent[M] etc. directly.

Why is TypedState unexported (typedState)?

TypedState appears in zero exported function signatures or struct fields. It only exists to support the State type alias (type State = typedState[*schema.Message]). Exporting it would add to the API surface without enabling any new use case — users interact with state through ChatModelAgentState in middleware callbacks, not through TypedState directly.

Key Insight

The ADK's flow.go uses a two-phase type dispatch: compile-time generics (TypedAgent[M]) handle agent execution, while runtime type checks (if _, ok := any(zero).(*schema.Message); ok) bridge to the non-generic callback system. Every such guard is a load-bearing dispatch point — a missing else branch silently disables the entire callback pipeline for agentic agents. The correct pattern is to always add the *schema.AgenticMessage branch whenever adding *schema.Message callback logic.

This same pattern appears in agent tools: the fullChatHistoryAsInput code path in agent_tool.go dispatches on message type to retrieve chat history from the correct typed state. Each dispatch point must handle both message types, or the feature silently fails for one type.

Summary

Problem	Solution
No structured message type for agentic interactions	*schema.AgenticMessage with typed content blocks, concat, vendor extensions
Model/prompt/tools interfaces only work with *schema.Message	Generic BaseModel[M], AgenticChatTemplate, AgenticToolsNode with backward-compatible type aliases
ADK agents can't use *schema.AgenticMessage	TypedAgent[M], TypedRunner[M] and all supporting types parameterized by MessageType
Agent callbacks silently skip agentic agents	ComponentOfAgenticAgent + AgenticAgentCallbackHandler + else branches in all flow.go dispatch points
Checkpoint serialization fails for AgenticMessage with jsonschema.Schema	Targeted GobEncode/GobDecode on MCPListToolsItem
No cancel mechanism for long-running agents	TypedCancellable[M] with preemptive and cooperative cancellation
No way to auto-inject agent metadata into model context	agentsmd middleware
Agent tool fullChatHistoryAsInput fails for agentic agents	case *schema.AgenticMessage: branch with getAgenticReactChatHistory
TurnLoop only works with *schema.Message agents	TurnLoop[T, M MessageType] — all types parameterized by message type
AgenticAgentCallbackHandler.OnError was dead code	Removed — ADK runtime doesn't fire OnError for agent callbacks
Convenience constructors added unnecessary API surface	Removed NewRunnerFrom, NewChatModelAgentFrom, New*AgentFrom — users use Typed* constructors directly
TypedState exported without external usage	Unexported to typedState — users access state via State alias or ChatModelAgentState in middleware

---

将 AgenticMessage 集成到 ADK 中

问题

Eino 框架仅支持 *schema.Message 作为 Agent 通信的消息类型。为了支持更丰富的 agentic 交互——包括结构化内容块、MCP 工具调用、多模态内容和厂商特定扩展——框架需要一种新的消息类型（*schema.AgenticMessage），并将其集成到所有层：schema 定义、组件接口、compose 图、ADK agent 运行时、回调和检查点序列化。

方案

本 PR 将 *schema.AgenticMessage 作为一等消息类型引入整个 Eino 技术栈，通过 MessageType 约束（*schema.Message | *schema.AgenticMessage）进行参数化。

Schema 层

• 带有结构化 ContentBlock 变体（文本、工具调用、工具结果、MCP 操作、图片等）的 AgenticMessage
• AgenticMessage 的完整流式 concat 支持
• 辅助构造函数：UserAgenticMessage、AssistantAgenticMessage、ToolAgenticMessage 等
• 厂商扩展包：schema/openai、schema/claude、schema/gemini
• MCPListToolsItem 上的自定义 GobEncode/GobDecode 处理 jsonschema.Schema

组件层

• model.BaseModel[M] 泛型接口，通过类型别名统一 BaseChatModel 和 AgenticModel（向后兼容）
• prompt.AgenticChatTemplate 用于 agentic 提示模板
• 模型和提示组件的 agentic 回调类型

Compose 层

• AgenticToolsNode 用于在 compose 图中执行 agentic 工具调用
• 图/链/工作流支持添加 agentic 模型和工具节点
• 检查点扩展支持 agentic 消息变体

ADK 层

• TypedAgent[M]、TypedChatModelAgent[M]、TypedRunner[M] — 所有核心类型按 MessageType 参数化
• 非泛型别名（Agent、ChatModelAgent、Runner 等）默认为 *schema.Message，保持向后兼容
• TypedAgentTool[M] 现已支持 *schema.Message 和 *schema.AgenticMessage 的 fullChatHistoryAsInput 模式
• TurnLoop[T, M MessageType] — 基于推送的流式事件循环，现可编排 *schema.AgenticMessage agent
• 取消机制（TypedCancellable[M]）支持抢占式和协作式取消
• agentsmd 中间件自动注入 Agents.md 到模型上下文
• 内部状态类型 typedState 未导出 — 用户通过 middleware 回调中的 ChatModelAgentState 或 State 别名与之交互

回调

• ComponentOfAgenticAgent、AgenticAgentCallbackInput/Output、AgenticAgentCallbackHandler — 完整的 OnStart/OnEnd 回调管线
• AgenticAgentCallbackHandler 刻意省略 OnError — ADK 运行时不会为 agent 回调触发 OnError（与非 agentic 的 AgentCallbackHandler 保持一致），包含它只会是死代码

决策

为什么使用独立的 ComponentOfAgenticAgent 而不是泛型化回调？

回调系统通过 interface{} 传递数据，泛型在回调边界无法提供类型安全。每个组件的回调层使用独立的 agentic 变体类型，与 model、prompt、tools node 的回调模式保持一致。

为什么在 MCPListToolsItem 上做自定义 GobEncode 而不是整个消息用 JSON？

AgenticMessage 中 any 字段携带的具体类型在 JSON 往返序列化中会丢失类型信息。通过将 GobEncode/GobDecode 精确定位到问题最窄的类型（MCPListToolsItem），其他字段保留原生 gob 编码。

为什么直接给 TurnLoop 加 M MessageType 而不用 Typed* + 别名模式？

TurnLoop 是未发布 API。直接在现有类型上添加 M MessageType（TurnLoop[T, M]）而不是创建 TypedTurnLoop[T, M] + type TurnLoop = TypedTurnLoop[T, *schema.Message]，可以避免不必要的 API 表面积。与其他 ADK 类型（使用 Typed* + 别名）的不对称性，对于未发布 API 是可以接受的。

为什么 AgenticAgentCallbackHandler 没有 OnError？

ADK 运行时（flow.go）从不为 agent 回调触发 TimingOnError — 无论是 *schema.Message agent 还是 *schema.AgenticMessage agent。AgentCallbackHandler 因此省略了 OnError；AgenticAgentCallbackHandler 也同样省略，而不是声明一个永远不会被调用的死字段。

为什么没有便捷构造器（NewRunnerFrom、NewChatModelAgentFrom、New*AgentFrom）？

这些是 Typed* 构造器的薄封装，收益极小 — 用户仅节省一行代码，却增加了 API 表面积。移除它们保持 API 最小化。用户直接使用 NewTypedChatModelAgent[M] / NewTypedRunner[M] / NewTypedSequentialAgent[M] 等。

为什么 TypedState 未导出（typedState）？

TypedState 未出现在任何导出函数签名或结构体字段中。它仅用于支持 State 类型别名（type State = typedState[*schema.Message]）。导出它会增加 API 表面积而不带来任何新用例 — 用户通过 middleware 回调中的 ChatModelAgentState 与状态交互，而不是直接使用 TypedState。

核心洞察

ADK 的 flow.go 使用两阶段类型分发：编译时泛型处理 agent 执行，运行时类型检查桥接到非泛型回调系统。每个 *schema.Message 守卫都是承载关键分发逻辑的点——缺少 else 分支会静默禁用该路径的整个回调管线。正确模式是：添加 *schema.Message 回调逻辑时，必须同时添加 *schema.AgenticMessage 分支。

同样的模式出现在 agent tool 中：agent_tool.go 的 fullChatHistoryAsInput 代码路径根据消息类型分发，从正确的类型化状态中检索聊天历史。每个分发点都必须处理两种消息类型，否则功能会静默失效。

摘要

问题	方案
没有用于 agentic 交互的结构化消息类型	*schema.AgenticMessage + 类型化内容块、concat、厂商扩展
模型/提示/工具接口仅适用于 *schema.Message	泛型 BaseModel[M]、AgenticChatTemplate、AgenticToolsNode + 向后兼容类型别名
ADK agent 无法使用 *schema.AgenticMessage	TypedAgent[M]、TypedRunner[M] 等按 MessageType 参数化
Agent 回调静默跳过 agentic agent	ComponentOfAgenticAgent + AgenticAgentCallbackHandler + flow.go 分发点的 else 分支
AgenticMessage 的检查点序列化因 jsonschema.Schema 失败	MCPListToolsItem 上的精确 GobEncode/GobDecode
长运行 agent 没有取消机制	TypedCancellable[M] 支持抢占式和协作式取消
无法自动注入 agent 元数据到模型上下文	agentsmd 中间件
Agent tool 的 fullChatHistoryAsInput 对 agentic agent 失败	case *schema.AgenticMessage: 分支 + getAgenticReactChatHistory
TurnLoop 仅支持 *schema.Message agent	TurnLoop[T, M MessageType] — 所有类型按消息类型参数化
AgenticAgentCallbackHandler.OnError 是死代码	已移除 — ADK 运行时不会为 agent 回调触发 OnError
便捷构造器增加不必要的 API 表面积	移除 NewRunnerFrom、NewChatModelAgentFrom、New*AgentFrom — 用户直接使用 Typed* 构造器
TypedState 导出但无外部使用	未导出为 typedState — 用户通过 State 别名或 middleware 中的 ChatModelAgentState 访问状态

[codecov]

Codecov Report

❌ Patch coverage is 78.66858% with 298 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (alpha/09@77d5e7e). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
adk/runctx.go	52.80%	49 Missing and 10 partials ⚠️
adk/react.go	70.37%	42 Missing and 6 partials ⚠️
adk/chatmodel.go	81.93%	36 Missing and 7 partials ⚠️
adk/failover_chatmodel.go	72.41%	29 Missing and 3 partials ⚠️
adk/wrappers.go	82.60%	19 Missing and 5 partials ⚠️
adk/flow.go	82.75%	16 Missing and 4 partials ⚠️
adk/runner.go	80.45%	13 Missing and 4 partials ⚠️
adk/interface.go	83.69%	10 Missing and 5 partials ⚠️
adk/agent_tool.go	78.72%	6 Missing and 4 partials ⚠️
schema/agentic_message.go	71.42%	4 Missing and 4 partials ⚠️
... and 5 more

Additional details and impacted files

@@             Coverage Diff             @@
##             alpha/09     #920   +/-   ##
===========================================
  Coverage            ?   82.25%           
===========================================
  Files               ?      161           
  Lines               ?    21471           
  Branches            ?        0           
===========================================
  Hits                ?    17660           
  Misses              ?     2590           
  Partials            ?     1221           

☔ 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.