cloudwego / cloudwego/eino

[ADK] Add structured AgentEvent types for debugging, tracing and durable event logs

Open
#997 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.