Support Concurrent/Nested Runs

[contextablemark]

Problem

Three related gaps converge here:

1. No concurrent execution. Frameworks like LangGraph and ADK v2 support fan-out where a parent agent spawns multiple child agents in parallel. AG-UI prohibits RUN_STARTED during an active run, so there's no way to represent this.

2. No mid-run delegation. When an orchestrator agent delegates to a specialist during its own run — a pattern used by LangGraph subgraphs, Claude Agent SDK nested agents, and ADK v2 Task API — the delegation flattens into a single event stream, losing the structural parent-child relationship.

3. No event-to-run correlation. Even if we allow concurrent runs, runId only exists on RUN_STARTED/FINISHED — the events in between (text messages, tool calls, state changes) don't declare which run they belong to. Interleaved events from concurrent runs would be impossible to untangle.

Community Remarks

From Discord:

"How can I model parallel subagents events using AGUI. The main issue I'm facing is that I want to communicate each agents events such as thinking, tool calls etc. And these agents can run in parallel."

Proposed Changes

Three changes that work together:

1a. Add runId to BaseEvent (optional)

export const BaseEventSchema = z.object({
  type: z.nativeEnum(EventType),
  timestamp: z.number().optional(),
  rawEvent: z.any().optional(),
  runId: z.string().optional(),     // NEW: which run this event belongs to
}).passthrough();

When only one run is active (the common case today), runId can be omitted — all events implicitly belong to the single active run. When multiple runs are concurrent, runId is required on every event so clients can group them.

1b. Make invokingRunId semantic on RUN_STARTED

Remove the "only one active run" constraint. Instead, the verifier tracks a set of active run IDs:

Key design decision: no LIFO ordering constraint. Fan-out children can finish in any order. The only rule is a parent run cannot finish while it has active children.

1c. Add agentId to RUN_STARTED (optional)

This ties a run to an agent identity, linking to multiAgent.subAgents[] for discovery. Each run is owned by one agent — the hierarchy of runs is the hierarchy of agent delegation.

Example: Fan-out with Parallel Agents

Applicable to: LangGraph parallel branches, ADK v2 Workflow Runtime fan-out, AWS Strands multi-agent nodes

RUN_STARTED  (runId: "orch", agentId: "orchestrator")
TEXT_MESSAGE_CONTENT (runId: "orch", delta: "I'll analyze this from two angles...")

RUN_STARTED  (runId: "research", invokingRunId: "orch", agentId: "researcher")
RUN_STARTED  (runId: "analysis", invokingRunId: "orch", agentId: "analyst")

TEXT_MESSAGE_CONTENT (runId: "analysis", delta: "The data shows...")
TOOL_CALL_START      (runId: "research", toolCallName: "search")
TEXT_MESSAGE_CONTENT (runId: "research", delta: "Found 3 papers...")
TOOL_CALL_END        (runId: "research")

RUN_FINISHED (runId: "analysis")   // analyst finishes first — any order OK
RUN_FINISHED (runId: "research")   // researcher finishes second

TEXT_MESSAGE_CONTENT (runId: "orch", delta: "Based on both analyses...")
RUN_FINISHED (runId: "orch")       // parent finishes last (after all children)

Example: Sequential Delegation

Applicable to: Claude Agent SDK nested agents, ADK v2 Task API, A2A delegation

RUN_STARTED  (runId: "main", agentId: "coordinator")
TEXT_MESSAGE_CONTENT (runId: "main", delta: "Let me get a specialist opinion...")

RUN_STARTED  (runId: "sub1", invokingRunId: "main", agentId: "specialist")
TEXT_MESSAGE_CONTENT (runId: "sub1", delta: "Based on my analysis...")
RUN_FINISHED (runId: "sub1")

TEXT_MESSAGE_CONTENT (runId: "main", delta: "The specialist confirms...")
RUN_FINISHED (runId: "main")

What This Enables

• UIs can render agent delegation trees (collapsible sub-agent sections)
• Concurrent agent output is untangled by runId on each event
• Agent identity is structurally linked to runs, not a naming convention
• Parent-child lifecycle is enforced (parent can't finish before children)
• Fan-out children can finish in any order (not constrained to LIFO)
• Backwards compatible: single-run agents work exactly as before

Backwards Compatibility

• Agents that emit a single run with no children work exactly as today
• runId on BaseEvent is optional — when absent, events belong to the single active run
• invokingRunId and agentId on RUN_STARTED are optional
• Consider a capability flag (transport.concurrentRuns: true) so clients can declare support

Framework	Why It Needs This
LangGraph	Native graph-based parallelism with fan-out/fan-in. Subgraph streaming already isolates event streams internally, but AG-UI can't represent the parent-child relationship or concurrent branches.
Claude Agent SDK	Supports nested agent delegation. Currently flattens into a single event stream, losing structural attribution.
AWS Strands	Multi-agent nodes with handoff events. Currently approximates structure via STEP_STARTED/FINISHED with "node_type:node_id" naming.
Google ADK v2 (expected)	Workflow Runtime supports parallel node execution; Task API delegates to sub-agents mid-run. Both require concurrent runs with hierarchy.

[ashwin-pc]

How would this work with the retry and edit flows that are described in the serialization doc in the AG-UI readme? We used something like this initially but because the parentRunId was reserved for that flow, we had to rewrite the stack to not use parentRunId and instead use stepid since that was cleaner and served the same semantic purposes

[contextablemark]

How would this work with the retry and edit flows that are described in the serialization doc in the AG-UI readme? We used something like this initially but because the parentRunId was reserved for that flow, we had to rewrite the stack to not use parentRunId and instead use stepid since that was cleaner and served the same semantic purposes

Can you provide a link to the serialization doc in the readme? But if you ended up using stepId then maybe step/event correlation covers it.

[ashwin-pc]

This is the doc I was referring to :) https://docs.ag-ui.com/concepts/serialization

[contextablemark]

This is the doc I was referring to :) https://docs.ag-ui.com/concepts/serialization

Ahh yes... I'd forgotten about that. Maybe "invokingRunId" instead.