google / google/adk-python

Emit agent/node lifecycle events (start/finish) in runner.run_async

未关闭
#6,267 2 条评论 0 个 reaction 已指派 2 人 已被 @i-yliu 认领 在 GitHub 查看
agent engine needs review
主要语言
Python
星标
21.5k
派生
4k
平均合并
1 天 22 小时
30 天内合并 PR
31

描述

### 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.**

贡献指南

打开贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。