[ADK] Add structured AgentEvent types for debugging, tracing and durable event logs
- Dominant language
- Go
- Stars
- 13k
- Forks
- 1.1k
- Avg merge
- 4h 6m
- Merged PRs (30d)
- 41
Description
## Summary
I would like to propose adding structured event types and metadata to ADK `AgentEvent`.
Eino ADK currently exposes agent execution through `AsyncIterator[*AgentEvent]`, which is very useful. However, for debugging, tracing, UI rendering, and durable event logs, applications often need to distinguish different event kinds in a stable way.
## Motivation
When building an agent runtime or service layer on top of Eino, developers need to observe and persist events such as:
- Agent start/end
- Model start/end
- Model stream delta
- Tool start/end
- Tool stream delta
- Agent transfer
- Interrupt
- Resume
- Error
- Final answer
Currently, users can infer some of this from `AgentEvent.Output`, `AgentEvent.Action`, and callbacks, but there is no single structured event taxonomy that can be used reliably by UIs, tracing systems, or durable event stores.
## Proposed Design
Add an explicit event type field and structured metadata to `AgentEvent`.
A rough shape could be:
```go
type AgentEventType string
const (
AgentEventAgentStart AgentEventType = "agent_start"
AgentEventAgentEnd AgentEventType = "agent_end"
AgentEventModelStart AgentEventType = "model_start"
AgentEventModelEnd AgentEventType = "model_end"
AgentEventModelDelta AgentEventType = "model_delta"
AgentEventToolStart AgentEventType = "tool_start"
AgentEventToolEnd AgentEventType = "tool_end"
AgentEventToolDelta AgentEventType = "tool_delta"
AgentEventTransfer AgentEventType = "transfer"
AgentEventInterrupt AgentEventType = "interrupt"
AgentEventResume AgentEventType = "resume"
AgentEventError AgentEventType = "error"
)
type AgentEvent struct {
Type AgentEventType
AgentName string
RunPath []RunStep
Output *AgentOutput
Action *AgentAction
Err error
Metadata map[string]any
}
```
The exact API does not have to match this sketch, but having a stable event taxonomy would be very helpful.
## Expected Benefits
- Easier debugging for complex multi-agent workflows
- Easier integration with tracing systems such as Langfuse/Cozeloop/OpenTelemetry
- Easier implementation of WebSocket/SSE agent service layers
- Easier durable event storage and replay
- Better compatibility with visual debugging tools
## Related Issues / PRs
This request is related to existing observability and debugging needs, including:
- #603: Langfuse trace information missing
- #614: Framework is powerful but hard to debug
- #590: Agent callbacks and Multi-Agent definition for ADK
This issue is intended to focus specifically on a stable ADK event taxonomy and event metadata model.
Contributor guide
Assessment
This issue has not been assessed yet.