Emit agent/node lifecycle events (start/finish) in runner.run_async
- Lingua principale
- Python
- Stelle
- 21.5k
- Fork
- 4k
- Merge medio
- 1g 14h
- PR unite (30g)
- 37
Descrizione
### Context
We maintain the **AG-UI ↔ ADK middleware** (`ag-ui-adk`, part of [ag-ui-protocol/ag-ui](https://github.com/ag-ui-protocol/ag-ui)). To emit AG-UI's `STEP_STARTED` / `STEP_FINISHED` events — which bracket the nodes/phases of a run — from ADK workflows, the middleware must know when each node/agent **starts and finishes**.
### Problem
The `runner.run_async` stream carries text / tool-call / state / reasoning events, but **no explicit "agent X started / finished" boundaries**. Consumers that want to bracket work per node/agent (workflows, multi-agent, loops) must **infer** boundaries from `author` / `branch` transitions, which is lossy:
- exact **parallel-branch end** can't be observed (only inferred at the run boundary), and
- a `ParallelAgent` inside a `LoopAgent` can't be split per iteration — the events are identical across iterations (see #6266).
### ADK already has the lifecycle internally
- `before_agent_callback` / `after_agent_callback` fire **once per agent invocation** (including once per `LoopAgent` iteration).
- The 2.0 Workflow graph engine has `_node_status` / `node_tracing` / `_node_runner`.
It is simply not **surfaced in the public event stream**.
### Ask
Optionally (behind a flag/config) emit lightweight **lifecycle events** — agent/node **started** and **finished** — into `runner.run_async`, authored by the agent, so any consumer can bracket nodes exactly: including per `LoopAgent` iteration and exact parallel-branch boundaries.
### Prior art / parity
Other agent frameworks already emit these, and AG-UI integrations map them directly to `STEP_STARTED` / `STEP_FINISHED`:
- **CrewAI** → `MethodExecutionStartedEvent` / `MethodExecutionFinishedEvent`
- **AWS Strands** → `multiagent_node_start` / `multiagent_node_stop`
Surfacing lifecycle events in the stream would let the ADK integration reach the same precision, without consumers having to install their own plugin/callback to observe boundaries.
### Motivation
We need this to faithfully emit **all** AG-UI event types from ADK; `STEP_STARTED`/`STEP_FINISHED` is currently the one category the ADK integration can only approximate. See the AG-UI PR: ag-ui-protocol/ag-ui#2076.
### Related
#6266 is a minimal, loop-scoped subset of this (just expose the loop iteration index). **This issue is the general form and would subsume #6266.**
Guida per i contributori
Apri la guida per i contributori
Valutazione
Questa issue non è ancora stata valutata.