feat(adk): add WithShouldSendEvent for selective event filtering

[shentongmartin]

Selective Event Filtering for Event Sender Wrappers

Problem

Users have no way to control which events are emitted by eventSenderModelWrapper / eventSenderToolWrapper. Every model response and tool result unconditionally produces an event. When users want to suppress events for internal/helper tools or filter model responses, they must build custom middleware from scratch.

Solution

Add a WithShouldSendEvent option that both NewEventSenderModelWrapper and NewEventSenderToolWrapper accept:

adk.NewEventSenderToolWrapper(adk.WithShouldSendEvent(func(event *adk.AgentEvent) bool {
    return event.Output.MessageOutput.ToolName != "internal_helper"
}))

The predicate receives a defensive copy of the *AgentEvent (via the existing copyAgentEvent), so users can safely inspect any field—including consuming a streaming MessageStream—without breaking the original event delivered to the Runner consumer.

Decisions

Why a predicate on *AgentEvent instead of a simpler filter (e.g., tool name allowlist)?

A predicate gives maximum flexibility—users can filter by role, tool name, action presence, message content (non-streaming), or any combination. A simpler API would either be too restrictive or grow into multiple options over time.

Why defensive copy before calling the predicate?

If a user's predicate consumes the MessageStream (e.g., calling Recv() to inspect content), the original event's stream would be permanently drained. copyAgentEvent forks the stream via .Copy(2), giving the predicate an independent copy. For non-streaming events, the cost is a lightweight struct copy.

Why share SendEventOption between both wrappers?

Both wrappers produce *AgentEvent with the same structure. A shared option type avoids unnecessary duplication while letting users apply the same filtering logic to both if desired.

Key Insight

Single-use streaming resources (MessageStream) require defensive copying at API boundaries where user code might consume them. The existing copyAgentEvent + stream .Copy(2) pattern solves this: fork the stream, give one fork to the user callback, keep the other for the framework. This "tee at the boundary" pattern ensures user-facing predicates can never break the internal event pipeline.

Summary

Problem	Solution
No way to suppress specific model/tool events	WithShouldSendEvent(func(*AgentEvent) bool) option on both event sender wrappers
User predicate could consume streaming events, breaking the Runner consumer	Defensive copy via copyAgentEvent before calling the predicate

---

事件发送器包装器的选择性事件过滤

问题

用户无法控制 eventSenderModelWrapper / eventSenderToolWrapper 发出哪些事件。每个模型响应和工具结果都会无条件地产生事件。当用户想要抑制内部/辅助工具的事件或过滤模型响应时，必须从头构建自定义中间件。

解决方案

添加 WithShouldSendEvent 选项，NewEventSenderModelWrapper 和 NewEventSenderToolWrapper 均可接受：

adk.NewEventSenderToolWrapper(adk.WithShouldSendEvent(func(event *adk.AgentEvent) bool {
    return event.Output.MessageOutput.ToolName != "internal_helper"
}))

谓词函数接收 *AgentEvent 的防御性副本（通过已有的 copyAgentEvent），因此用户可以安全地检查任何字段——包括消费流式 MessageStream——而不会破坏交付给 Runner 消费者的原始事件。

设计决策

为什么使用 *AgentEvent 谓词而非更简单的过滤器（如工具名称白名单）？

谓词提供最大灵活性——用户可以按角色、工具名称、Action 存在性、消息内容（非流式）或任意组合进行过滤。更简单的 API 要么限制过多，要么随时间增长为多个选项。

为什么在调用谓词前进行防御性复制？

如果用户的谓词消费了 MessageStream（例如调用 Recv() 检查内容），原始事件的流将被永久耗尽。copyAgentEvent 通过 .Copy(2) 分叉流，为谓词提供独立副本。对于非流式事件，开销仅为轻量级结构体复制。

为什么两个包装器共享 SendEventOption？

两个包装器都产生相同结构的 *AgentEvent。共享选项类型避免了不必要的重复，同时允许用户在需要时对两者应用相同的过滤逻辑。

关键洞察

单次使用的流式资源（MessageStream）在用户代码可能消费它们的 API 边界处需要防御性复制。已有的 copyAgentEvent + 流 .Copy(2) 模式解决了这个问题：分叉流，将一个分支给用户回调，保留另一个给框架。这种"边界处分流"模式确保用户端谓词永远不会破坏内部事件管道。

总结

问题	解决方案
无法抑制特定模型/工具事件	两个事件发送器包装器上的 WithShouldSendEvent(func(*AgentEvent) bool) 选项
用户谓词可能消费流式事件，破坏 Runner 消费者	调用谓词前通过 copyAgentEvent 进行防御性复制

[github-actions]

🚨 Breaking API Changes Detected

Package: github.com/cloudwego/eino/adk

Incompatible changes:

• NewEventSenderModelWrapper: changed from func() ChatModelAgentMiddleware to func(...SendEventOption) ChatModelAgentMiddleware
• NewEventSenderToolWrapper: changed from func() ChatModelAgentMiddleware to func(...SendEventOption) ChatModelAgentMiddleware

Review Guidelines

Please ensure that:

• The changes are absolutely necessary
• They are properly documented
• Migration guides are provided if needed

⚠️ Please resolve this thread after reviewing the breaking changes.

[codecov]

Codecov Report

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

Files with missing lines	Patch %	Lines
adk/wrappers.go	88.46%	0 Missing and 3 partials ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             alpha/09     #930   +/-   ##
===========================================
  Coverage            ?   81.50%           
===========================================
  Files               ?      158           
  Lines               ?    18934           
  Branches            ?        0           
===========================================
  Hits                ?    15432           
  Misses              ?     2365           
  Partials            ?     1137           

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