feat(agents): opt-in agent lifecycle events (start/finish) in the stream

[ferponse]

What

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 — e.g. exact parallel-branch end can't be observed, and a ParallelAgent inside a LoopAgent can't be split per iteration (its events are identical across iterations, see #6266).

This adds an opt-in RunConfig.emit_agent_lifecycle_events (default False). When enabled, every agent invocation yields a lightweight lifecycle marker event before its logic and after it — authored by the agent, carrying Event.custom_metadata['agent_lifecycle'] == 'start' | 'finish' (plus the agent's branch).

Fixes #6267.

Why

We're building the AG-UI ↔ ADK middleware (ag-ui-adk), which maps ADK workflow nodes to AG-UI STEP_STARTED / STEP_FINISHED events. Explicit lifecycle events let any consumer bracket nodes exactly, matching what other agent frameworks already emit (CrewAI MethodExecutionStarted/Finished, AWS Strands multiagent_node_start/stop).

How

• New RunConfig.emit_agent_lifecycle_events: bool = False.
• BaseAgent.run_async emits a start marker once the agent is actually going to run (i.e. not short-circuited by before_agent_callback) and a paired finish marker on every exit path.
• Marker events reuse the existing Event.custom_metadata bucket — no Event schema change — and propagate through the tree (run_config is copied into each sub-agent context), so they fire per agent, including per LoopAgent iteration.

Default-off: existing event streams are byte-for-byte unchanged.

Example

LoopAgent(max_iterations=2, sub_agents=[ParallelAgent(sub_agents=[p, q])]) with emit_agent_lifecycle_events=True:

loop [start]
  par [start]
    p [start]  q [start]   …content…   p [finish]  q [finish]
  par [finish]
  par [start]                                             ← iteration 2
    p [start]  q [start]   …content…   p [finish]  q [finish]
  par [finish]
loop [finish]

Every node gets a balanced start/finish per invocation, so iterations and parallel branches are exactly bracketed.

Tests

tests/unittests/agents/test_base_agent.py: added test_run_async_emits_agent_lifecycle_events (start → content → finish) and test_no_agent_lifecycle_events_by_default (backward-compat: stream unchanged). The agents test suite (test_base_agent, test_loop_agent, test_sequential_agent, test_parallel_agent, test_run_config) passes.

Notes

• This is the general form proposed in Emit agent/node lifecycle events (start/finish) in runner.run_async #6267; it subsumes the minimal, loop-scoped LoopAgent: surface the current iteration index in the event stream #6266 (LoopAgent iteration index), which has its own PR.
• Kept intentionally minimal and opt-in as a starting point — happy to iterate on the event shape (e.g. a dedicated field/enum instead of custom_metadata) per maintainer preference.