Support Step/Event Correlation

[contextablemark]

Problem

Within a single agent's run, STEP_STARTED/FINISHED creates named lifecycle boundaries for workflow phases, but events emitted between those boundaries have no field linking them to the step. This means:

1. No correlation: You can't say "this TEXT_MESSAGE was produced during step X"
2. No parallel workflow nodes: If a single agent's internal workflow has parallel branches (e.g., LangGraph parallel nodes, ADK v2 Workflow Runtime fan-out within one agent), interleaved events can't be sorted by node

This is a different concern from supporting concurrent/nested runs. That proposal handles inter-agent hierarchy (which agent produced this event). This proposal handles intra-agent structure (which workflow node within an agent's execution produced this event).

Community Remarks

From Discord:

"I thought of using steps, but there is no way today to correlate steps to other normal events such as text events. Can we add an optional property to the other generic events called step_id or parent_step_id?"

Proposed Changes

Add optional stepId to BaseEvent and to STEP_STARTED:

export const BaseEventSchema = z.object({
  type: z.nativeEnum(EventType),
  timestamp: z.number().optional(),
  rawEvent: z.any().optional(),
  runId: z.string().optional(),      // From Proposal 1
  stepId: z.string().optional(),     // NEW: correlates this event to a step
}).passthrough();

export const StepStartedEventSchema = BaseEventSchema.extend({
  type: z.literal(EventType.STEP_STARTED),
  stepName: z.string(),
  stepId: z.string().optional(),       // NEW: unique identifier for this step instance
  parentStepId: z.string().optional(), // NEW: for nested workflow nodes
});

Example: LangGraph Workflow with Parallel Nodes

A LangGraph agent with parallel branches — all within one run:

RUN_STARTED (runId: "agent-1")

STEP_STARTED (stepName: "fetch_data", stepId: "s1")
TOOL_CALL_START (toolCallName: "query_db", stepId: "s1")
TOOL_CALL_END (stepId: "s1")
STEP_FINISHED (stepName: "fetch_data", stepId: "s1")

STEP_STARTED (stepName: "transform_a", stepId: "s2")
STEP_STARTED (stepName: "transform_b", stepId: "s3")
TEXT_MESSAGE_CONTENT (delta: "Processing batch A...", stepId: "s2")
TEXT_MESSAGE_CONTENT (delta: "Processing batch B...", stepId: "s3")
STEP_FINISHED (stepName: "transform_b", stepId: "s3")
STEP_FINISHED (stepName: "transform_a", stepId: "s2")

STEP_STARTED (stepName: "merge", stepId: "s4")
STATE_DELTA (patch: [...], stepId: "s4")
STEP_FINISHED (stepName: "merge", stepId: "s4")

RUN_FINISHED (runId: "agent-1")

Example: AWS Strands Multi-Agent Node Execution

RUN_STARTED (runId: "strands-1")

STEP_STARTED (stepName: "tool_use:search_agent", stepId: "s1")
TOOL_CALL_START (toolCallName: "web_search", stepId: "s1")
TOOL_CALL_END (stepId: "s1")
TEXT_MESSAGE_CONTENT (delta: "Search results indicate...", stepId: "s1")
STEP_FINISHED (stepName: "tool_use:search_agent", stepId: "s1")

STEP_STARTED (stepName: "tool_use:analysis_agent", stepId: "s2")
REASONING_MESSAGE_CONTENT (delta: "Considering the data...", stepId: "s2")
TEXT_MESSAGE_CONTENT (delta: "My analysis shows...", stepId: "s2")
STEP_FINISHED (stepName: "tool_use:analysis_agent", stepId: "s2")

RUN_FINISHED (runId: "strands-1")

Framework	Why It Needs This
LangGraph	Already emits STEP_STARTED/FINISHED with node names, but the events between step boundaries (text, tool calls, state changes) can't be linked back to the step. This is the framework where the gap is most visible today.
AWS Strands	Same pattern — emits step events from multiagent_node_start/stop, but events within the step float freely in the stream.
Google ADK v2 (expected)	Workflow Runtime nodes map directly to steps. Fan-out within a single agent's workflow produces interleaved events that need per-step attribution.
Vercel AI SDK	maxSteps enables multi-turn tool execution. Each iteration could be a step, but tool call events within an iteration have no step link.
CrewAI	Has task/step concepts in its execution model that could map to step-correlated events.