feat: add STEP_STARTED/STEP_FINISHED AG-UI lifecycle events

[jackzhao8886]

What

Adds standard AG-UI Step lifecycle events so agents can distinguish reasoning/thinking output from the final answer output within a single run.

Why

In the AG-UI event stream, multiple text segments currently have no semantic marker — clients can't tell which text is intermediate reasoning vs. the final reply. This adds the AG-UI-native STEP_STARTED / STEP_FINISHED lifecycle events to mark named phases (e.g. reasoning, final_answer).

Changes

• Add STEP_STARTED / STEP_FINISHED to the EventType enum
• Serialize them as native StepStartedEvent / StepFinishedEvent in the AG-UI protocol
• Accept both stepName (camelCase) and step_name (snake_case) input keys
• Warn and fall back to CustomEvent when stepName is missing
• Silently skip step events in the OpenAI protocol (no native support there)
• Unit tests for AG-UI serialization, snake_case input, missing-stepName fallback, full lifecycle, and OpenAI skip behavior
• Fully backward compatible — streams from agents that don't emit step events are unchanged

Usage

yield AgentEvent(event=EventType.STEP_STARTED, data={"stepName": "reasoning"})
yield "let me think..."
yield AgentEvent(event=EventType.STEP_FINISHED, data={"stepName": "reasoning"})
yield AgentEvent(event=EventType.STEP_STARTED, data={"stepName": "final_answer"})
yield "the answer is 42."
yield AgentEvent(event=EventType.STEP_FINISHED, data={"stepName": "final_answer"})

Test

pytest tests/unittests/server/ — 243 passed.

🤖 Generated with Claude Code

[jackzhao8886]

暂时关闭：客户（神州租车）真实诉求是在多步 Agent 场景下区分「中间旁白文本」与「最终正文」。本 PR 提供的 STEP 事件是正确机制，但需先确认客户接入方式——若为托管 SuperAgent/runloop，emit STEP 的产出逻辑需在 runloop 实现（不在本 PR 范围）。待确认后再决定是否重开。

[Copilot]

Pull request overview

This PR adds first-class AG-UI “Step lifecycle” events (STEP_STARTED / STEP_FINISHED) to the server event model and AG-UI protocol serialization so clients can distinguish intermediate phases (e.g. reasoning) from the final answer within a single run, while keeping the OpenAI protocol behavior unchanged (step events are skipped).

Changes:

• Added STEP_STARTED / STEP_FINISHED to EventType and documented their recommended usage in server-facing examples.
• Implemented AG-UI serialization into native StepStartedEvent / StepFinishedEvent, accepting both stepName and step_name (with warning + CustomEvent fallback when missing).
• Added unit tests covering AG-UI serialization, snake_case input, missing stepName fallback, full lifecycle ordering, and OpenAI skip behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/unittests/server/test_step_events.py	Adds focused unit tests for AG-UI step lifecycle serialization and OpenAI protocol skipping behavior.
agentrun/server/server.py	Updates public docstring example to use AgentEvent and stepName for step lifecycle events.
agentrun/server/openai_protocol.py	Explicitly skips step lifecycle events during OpenAI stream formatting.
agentrun/server/model.py	Adds new EventType values and expands documentation examples for step lifecycle events.
agentrun/server/agui_protocol.py	Encodes STEP_STARTED / STEP_FINISHED into native AG-UI step events (or warns + falls back to CustomEvent).
agentrun/server/init.py	Updates module-level usage example to prefer step lifecycle events over custom step events.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.