feat: Agent callbacks and Multi-Agent definition for adk by N3kox · Pull Request #590 · cloudwego/eino

N3kox · 2025-11-28T09:40:51Z

What type of PR is this?

feat

Check the PR title.

Title matches the format: <type>(optional scope): <description>
The description is user-oriented and clear.
Attach the PR updating the user documentation if usage-level awareness is required: N/A

(Optional) Translate the PR title into Chinese.

feat: 为 ADK 引入 Agent 与 Runner 的 Callback 能力

(Optional) More detailed description for this PR (en / zh).

en:

Introduce agent-level callbacks for ADK.
- Add callback hooks to current AgentMiddleware : BeforeAgent and OnEvents
- Add AgentMiddlewareChecker interface. If an agent implements AgentMiddlewareChecker and enables agent middlewares internally, hooks run inside the agent; otherwise, agent middlewares are executed by the flowAgent.
- flowAgent / ChatModelAgent / workflowAgent Run/Resume adapt to middleware aspect execution, with partial refactoring of ChatModelAgent to adapt to runtime middleware injection and execution.
- Add middlewares configuration to Plan-Execute and Supervisor Agent
- Add globalAgentMiddlewares to inject the same middleware at the outermost layer of all agent runtimes from a global perspective.
Introduce Multi-Agent for ADK.
- Add Multi-Agent structure, at the same conceptual level as ChatModelAgent / WorkflowAgents, to solve the problem that Agent operations are at a flat level and difficult to observe in TransferAgent scenarios.
- flowAgent adapts to Multi-Agent operation
- Supervisor Agent constructor returns Multi-Agent
Add WithGraphCallbacks AgentRunOption, which provides eino graph/chain callback injection inside an agent (mainly for ChatModelAgent).
Provide utility helpers (NewAsyncOnSingleEventHandler, NewSyncOnSingleEventHandler, BypassIterator) for event processing.
Add tests to verify middleware execution validity (order, deduplication, termination behavior, interruption/resume flows with tool calls, and global agent middleware propagation).

zh:

ADK 支持 Agent 级别的回调
- 向现有的 AgentMiddleware 中新增切面: BeforeAgent 和 OnEvents
- 新增 AgentMiddlewareChecker 接口用于检查 Agent 是否支持内部运行 AgentMiddleware。如果支持，AgentMiddleware 将在 Agent 内部运行（由 Agent 自行实现运行逻辑）；否则将由 flowAgent 在 Agent 外部运行。
- flowAgent / ChatModelAgent / workflowAgent Run/Resume 适配 middleware 切面运行，对 ChatModelAgent 部分重构来适配运行时的 middleware 注入与运行。
- 新增 globalAgentMiddlewares，以全局角度向所有 agent 运行时最外侧注入相同的中间件
ADK 支持 Multi-Agent 概念
- 新增 Multi-Agent 结构，概念层级与 ChatModelAgent / WorkflowAgents 一致，用于解决 TransferAgent 情况下各 Agent 运行处于平铺的层级难以进行观测的问题。
- flowAgent 对 Multi-Agent 运行进行适配
- Supervisor Agent 构造方法返回 Multi-Agent
增加 WithGraphCallbacks AgentRunOption，提供向 Agent 内部的 graph/chain 运行 eino callback 的能力（主要面向 ChatModelAgent）
提供多个工具方法，用于处理 Iterator 中的 Events (NewAsyncOnSingleEventHandler, NewSyncOnSingleEventHandler, BypassIterator)
补全 middleware 测试，保证功能正确性（顺序、去重、提前终止、中断恢复场景、工具调用、globalAgentMiddlewares 等）

(Optional) Which issue(s) this PR fixes:

Relates to #513.

To fully resolve the issue here, further adaption in eino-ext is required.

(optional) The PR that updates user documentation:

N/A

github-actions · 2025-11-28T10:23:03Z

📊 Coverage Report:

File coverage threshold (20%) satisfied:	PASS
Package coverage threshold (30%) satisfied:	PASS
Total coverage threshold (83%) satisfied:	PASS
Total test coverage: 84.6% (6909/8166)

marwan38 · 2025-11-28T10:49:45Z

Does this PR resolve/relate to #513?
Thank you

N3kox · 2025-12-02T03:17:29Z

Does this PR resolve/relate to #513? Thank you

Yes, this pr, combined with further prs in eino-ext, will resolve the issues here.

codecov · 2025-12-03T09:50:57Z

Codecov Report

❌ Patch coverage is 86.02151% with 65 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.65%. Comparing base (8d7ea18) to head (72ff0d0).

Files with missing lines	Patch %	Lines
adk/chatmodel.go	85.77%	19 Missing and 12 partials ⚠️
adk/flow.go	83.78%	7 Missing and 5 partials ⚠️
adk/utils.go	70.37%	6 Missing and 2 partials ⚠️
adk/multi_agent.go	86.04%	3 Missing and 3 partials ⚠️
adk/agent_middleware.go	91.11%	3 Missing and 1 partial ⚠️
adk/prebuilt/supervisor/supervisor.go	83.33%	1 Missing and 1 partial ⚠️
adk/workflow.go	94.87%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #590      +/-   ##
==========================================
+ Coverage   80.36%   80.65%   +0.29%     
==========================================
  Files         124      126       +2     
  Lines       11906    12176     +270     
==========================================
+ Hits         9568     9821     +253     
- Misses       1607     1613       +6     
- Partials      731      742      +11

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

shentongmartin · 2025-12-29T12:05:23Z

adk/utils.go

+
+// BypassIterator creates a goroutine that simply passes events from the input iterator to the output generator.
+// This is useful when you need to do something without modifying events.
+func BypassIterator(iter *AsyncIterator[*AgentEvent], gen *AsyncGenerator[*AgentEvent]) {


需要大写吗

要的吧，这个也是实现方可能用到的方法，内部反而目前没有使用。
当前不提供 utils 我觉得也 ok。

shentongmartin · 2025-12-29T12:17:10Z

adk/agent_middleware.go

+	Messages []Message
+}
+
+type EntranceType string


我再考虑下

InvocationType？

shentongmartin · 2025-12-29T12:18:34Z

adk/agent_middleware.go

+
+	// internal properties, read only
+	agentName string
+	entrance  EntranceType


指的是当前这个 Agent 是 Run/Resume ，还是 Runner 入口是 Run/Resume？

前者，不该有后者这个概念吧，Agent 不感知 Runner

shentongmartin · 2025-12-29T12:20:11Z

adk/agent_middleware.go

+			continue
+		}
+		dedup[mw.Name] = struct{}{}
+		helper.beforeAgentFns = append(helper.beforeAgentFns, mw.BeforeAgent)


mw.BeforeAgents, mw.OnEvents 判空？

bydesign，BeforeAgents 第 n 个立刻返回时，前 n-1 个 OnEvents 要执行，设置空的 func 是为了 padding index，判空由运行时处理

adk/multi_agent.go

adk/utils.go

adk/flow.go

shentongmartin · 2025-12-29T12:32:29Z

adk/flow.go

+		if termIter != nil {
+			return termIter
+		}
+		// TODO: set back input in runCtx ?


需要，这个是 mw 实现方需要用到的方法

…ang ci lint

jaxxjj · 2026-01-25T16:08:54Z

挺需要 agent level的 callback

notbucai · 2026-02-03T14:28:06Z

有preview version 了嘛，现在观测上太难受了

N3kox force-pushed the feat/adk_cb branch 2 times, most recently from 8061819 to 58ffba4 Compare November 28, 2025 10:19

N3kox force-pushed the feat/adk_cb branch from 58ffba4 to 4812654 Compare December 2, 2025 03:14

N3kox force-pushed the feat/adk_cb branch 3 times, most recently from 818b8c4 to 52ba21c Compare December 3, 2025 09:47

N3kox force-pushed the feat/adk_cb branch from 52ba21c to f4b756c Compare December 3, 2025 11:32

N3kox changed the title ~~feat: agent callbacks for adk~~ feat: Runner / Agent callbacks for adk Dec 3, 2025

N3kox marked this pull request as ready for review December 4, 2025 02:48

N3kox marked this pull request as draft December 4, 2025 06:07

N3kox changed the title ~~feat: Runner / Agent callbacks for adk~~ feat: Agent callbacks and Multi-Agent definition for adk Dec 23, 2025

N3kox force-pushed the feat/adk_cb branch 4 times, most recently from 5019423 to 0f2c0cf Compare December 23, 2025 07:13

N3kox marked this pull request as ready for review December 23, 2025 07:19

shentongmartin reviewed Dec 30, 2025

View reviewed changes

N3kox force-pushed the feat/adk_cb branch from 0f2c0cf to 85b5d8d Compare December 30, 2025 09:16

N3kox force-pushed the feat/adk_cb branch from 159f57d to 000dc68 Compare January 7, 2026 07:11

N3kox added 4 commits January 7, 2026 17:23

feat: Agent callbacks and Multi-Agent definition for adk

69c1559

fix: duplicate graph callback injection in ChatModelAgent.Run

c756302

refactor: EntranceType to InvocationType

c726a20

refactor: rename AgentContext.EntranceType to InvocationType, fix gol…

72ff0d0

…ang ci lint

N3kox force-pushed the feat/adk_cb branch from 7e8ec03 to 72ff0d0 Compare January 7, 2026 09:25

Conversation

N3kox commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What type of PR is this?

Check the PR title.

(Optional) Translate the PR title into Chinese.

(Optional) More detailed description for this PR (en / zh).

(Optional) Which issue(s) this PR fixes:

(optional) The PR that updates user documentation:

Uh oh!

github-actions bot commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Coverage Report:

Uh oh!

marwan38 commented Nov 28, 2025

Uh oh!

N3kox commented Dec 2, 2025

Uh oh!

codecov bot commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaxxjj commented Jan 25, 2026

Uh oh!

notbucai commented Feb 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

5 participants

N3kox commented Nov 28, 2025 •

edited

Loading

github-actions bot commented Nov 28, 2025 •

edited

Loading

codecov bot commented Dec 3, 2025 •

edited

Loading