Compozy Symbol
ALPHA
DocsInstallGetting StartedFeaturesPricing
Quick StartDatabaseDeploymentConfigurationKnowledge BasesArchitectureTroubleshootingGuidesCoreCLI ReferenceSchema DefinitionAPI Reference

Execution Stream Events

Event catalog for workflow, agent, and task streaming endpoints

Overview

Execution streams emit Server-Sent Events (SSE) with a consistent structure across workflows, agents, and tasks. Each frame includes:

  • id — monotonically increasing integer.
  • event — event type token.
  • data — JSON object for structured streams or plain text for llm_chunk.

Heartbeats are sent every 15 seconds as comment frames (: ping) to keep intermediaries aware of the open connection.

id: 42
event: workflow_status
data: {"status":"RUNNING","step":"agent_start","ts":"2025-10-22T16:05:31.431Z"}

Event Catalog

EventComponentData ShapeNotes
workflow_startWorkflowJSON { exec_id, ts, workflow_id }Emitted once when the workflow begins.
workflow_statusWorkflowJSON { status, step?, usage?, ts }Durable status transitions with optional usage deltas.
agent_startWorkflow/AgentJSON { agent_id, ts, step? }Signals the start of an agent step within a workflow.
tool_callWorkflow/AgentJSON { tool_name, args, ts }Records structured tool invocations.
agent_statusAgentJSON { status, ts, component }High-level agent status updates.
task_statusTaskJSON { status, ts, component }High-level task status updates.
structured_deltaAgent/TaskJSON { partial, ts }Optional structured partial outputs when schemas are present.
llm_chunkAgent/TaskText lineProgressive text chunks; best-effort delivery.
completeAllJSON { status, result?, usage?, duration_ms? }Terminal success payload.
errorAllJSON { message, code?, ts }Terminal failure payload.

Structured mode events (workflow_*, agent_status, task_status, structured_delta, complete, error) support resumption via Last-Event-ID. Text-mode llm_chunk events are not replayed on reconnect; rely on the final completion event for durability.

Resume Semantics

  • Durable streams (workflows and structured agent/task) cache the last event ID. Provide Last-Event-ID on reconnect to receive only newer events.
  • Text-mode streams (llm_chunk) resume from “now” when reconnecting. Persist the accumulated output client-side if you need a complete transcript.
  • The poll_ms query parameter (default 500, allowed 250-2000) tunes Temporal/repository polling for durable streams. Use the events query parameter to reduce traffic to specific event types.

Client Checklists

  • Always set Accept: text/event-stream and disable HTTP buffering proxies (for example, curl -N).
  • Persist the last processed id for durable streams to resume cleanly.
  • Expect periodic heartbeats (: ping) and ignore them in parsers.
  • Close the stream after receiving complete or error to free server resources.
API Overview — Streaming
Understand how to consume SSE endpoints, including examples and parameters.
Workflow API
Endpoint reference for managing workflows and streaming execution updates.
CLI Executions
Learn when to use CLI polling versus REST streaming and how to combine them.