> ## Documentation Index > Fetch the complete documentation index at: https://docs.shannon.run/llms.txt > Use this file to discover all available pages before exploring further. # Event Types Catalog > Complete reference for Shannon streaming event types ## Overview Shannon emits **real-time events** via Server-Sent Events (SSE) to provide visibility into task execution. This document catalogs the **37 event types** actually emitted by the platform, their structure, and when they occur. Events provide: * **Real-time progress** - Track task execution as it happens * **Debugging insights** - LLM prompts, tool invocations, agent reasoning * **Cost monitoring** - Track token usage and costs in real-time * **Multi-agent coordination** - Observe team formation and collaboration * **Error recovery** - Monitor error handling and recovery attempts ## Event Structure All events follow this base structure: ```json theme={null} { "workflow_id": "wf-550e8400-e29b-41d4-a716-446655440000", "type": "AGENT_THINKING", "agent_id": "agent-001", "message": "Analyzing task complexity...", "timestamp": "2024-10-27T10:00:00Z", "seq": 42, "stream_id": "stream-abc123", "payload": {} } ``` ### Base Fields | Field | Type | Description | | ------------- | -------- | ------------------------------------------------------------------ | | `workflow_id` | string | Unique task/workflow identifier | | `type` | string | Event type (see catalog below) | | `agent_id` | string | Agent that emitted the event | | `message` | string | Human-readable event description | | `timestamp` | ISO 8601 | When the event occurred | | `seq` | integer | Sequence number for ordering | | `stream_id` | string | Stream identifier for reconnection | | `payload` | object | Event-specific payload (optional; serialized as `payload` in JSON) | *** ## Event Categories Events are organized into logical categories: 1. **Workflow Events** - Task lifecycle 2. **Agent Events** - Agent execution 3. **Tool Events** - Tool invocations 4. **Pattern Events** - Cognitive pattern execution 5. **Team Events** - Multi-agent coordination 6. **LLM Events** - Language model interactions 7. **Progress Events** - Task progress and status 8. **System Events** - Errors and system state *** ## Event Type Quick Reference Authoritative list of event types emitted by Shannon: | Event Type | Category | Description | | -------------------------- | ---------------- | ---------------------------------------------------------------- | | `WORKFLOW_STARTED` | Workflow | Task begins execution | | `WORKFLOW_COMPLETED` | Workflow | Task completes successfully | | `WORKFLOW_PAUSING` | Workflow control | Pause requested; workflow preparing to pause | | `WORKFLOW_PAUSED` | Workflow control | Workflow paused at a checkpoint | | `WORKFLOW_RESUMED` | Workflow control | Workflow resumed after pause | | `WORKFLOW_CANCELLING` | Workflow control | Cancel requested; workflow preparing to terminate | | `WORKFLOW_CANCELLED` | Workflow control | Workflow cancelled at a checkpoint | | `AGENT_STARTED` | Agent | Agent begins processing | | `AGENT_THINKING` | Agent | Agent reasoning/planning | | `AGENT_COMPLETED` | Agent | Agent finishes successfully | | `AGENT_FAILED` | Agent | Agent encountered an error | | `TOOL_INVOKED` | Tool | Tool is called | | `TOOL_OBSERVATION` | Tool | Agent observes tool result | | `TEAM_RECRUITED` | Team | Multi-agent team assembled | | `TEAM_RETIRED` | Team | Team disbanded | | `TEAM_STATUS` | Team | Team coordination update | | `DEPENDENCY_SATISFIED` | Team | Dependencies resolved | | `DELEGATION` | Team | Task delegated to another agent | | `MESSAGE_SENT` | Message | Agent sends message | | `MESSAGE_RECEIVED` | Message | Agent receives message | | `LLM_PROMPT` | LLM | Prompt sent to LLM | | `LLM_PARTIAL` | LLM | Incremental LLM output | | `LLM_OUTPUT` | LLM | Final LLM output | | `PROGRESS` | Progress | General progress update | | `DATA_PROCESSING` | Progress | Processing/analyzing data | | `WAITING` | Progress | Waiting for resources | | `ERROR_OCCURRED` | System | Error occurred | | `ERROR_RECOVERY` | System | Error recovery attempt | | `APPROVAL_REQUESTED` | System | Human approval needed | | `APPROVAL_DECISION` | System | Approval decision made | | `WORKSPACE_UPDATED` | System | Memory/context updated | | `ROLE_ASSIGNED` | System | Agent role assigned | | `STATUS_UPDATE` | System | General status update | | `BUDGET_THRESHOLD` | System/Progress | Budget warning threshold reached for a task | | `THREAD_MESSAGE_DELTA` | Stream | Incremental message content chunk | | `THREAD_MESSAGE_COMPLETED` | Stream | Message content fully delivered | | `STREAM_END` | Stream | Explicit end-of-stream signal (no more events for this workflow) | **Total**: 37 event types Note: Events such as `WORKFLOW_FAILED`, `TASK_COMPLETED`, `TOOL_COMPLETED`, `TOOL_FAILED`, and `BUDGET_UPDATE` are not emitted by the streaming API. Failures are surfaced via `ERROR_OCCURRED`; completion is indicated by `WORKFLOW_COMPLETED`. `STREAM_END` is emitted as a lifecycle signal after completion/termination when streaming ends. *** ## Workflow Events Events related to the overall task workflow. ### WORKFLOW\_STARTED **Emitted**: When a task begins execution **Data**: ```json theme={null} { "type": "WORKFLOW_STARTED", "message": "Workflow started", "data": { "query": "Analyze Q4 sales data", "mode": "STANDARD", "session_id": "sess-123", "estimated_complexity": 0.75 } } ``` **Fields**: * `query`: Original task query * `mode`: Execution mode (SIMPLE, STANDARD, COMPLEX) * `session_id`: Session identifier * `estimated_complexity`: Complexity score (0.0-1.0) *** ### WORKFLOW\_COMPLETED **Emitted**: When a task completes successfully **Data**: ```json theme={null} { "type": "WORKFLOW_COMPLETED", "message": "Workflow completed successfully", "data": { "result": "Analysis complete. Key findings: ...", "duration_ms": 45000, "total_tokens": 5420, "total_cost_usd": 0.0814, "agents_used": 3, "tools_invoked": 7 } } ``` **Fields**: * `result`: Final task result * `duration_ms`: Total execution time * `total_tokens`: Cumulative token usage * `total_cost_usd`: Total cost * `agents_used`: Number of agents invoked * `tools_invoked`: Number of tool calls *** ## Selected Examples ### AGENT\_THINKING ```json theme={null} { "type": "AGENT_THINKING", "agent_id": "researcher", "message": "Analyzing data structure...", "timestamp": "2025-01-20T10:00:02Z" } ``` ### TOOL\_INVOKED / TOOL\_OBSERVATION ```json theme={null} { "type": "TOOL_INVOKED", "message": "web_search: q=\"LLM caching\"" } { "type": "TOOL_OBSERVATION", "message": "web_search: 12 results" } ``` ### LLM\_OUTPUT ```json theme={null} { "type": "LLM_OUTPUT", "message": "Final summary of findings..." } ``` ### ERROR\_OCCURRED ```json theme={null} { "type": "ERROR_OCCURRED", "message": "Provider rate limit exceeded", "data": { "error": "RATE_LIMIT", "retry_after": 30 } } ``` ### APPROVAL\_REQUESTED ```json theme={null} { "type": "APPROVAL_REQUESTED", "message": "Delete temporary files older than 30 days?", "data": { "approval_id": "appr-456" } } ``` **Common Error Types**: * `BUDGET_EXCEEDED` - Cost/token limit reached * `TIMEOUT` - Execution timeout * `TOOL_EXECUTION_FAILED` - Tool error * `LLM_ERROR` - LLM provider error * `INVALID_INPUT` - Malformed request *** ## Agent Events Events related to individual agent execution. ### AGENT\_STARTED **Emitted**: When an agent begins processing **Data**: ```json theme={null} { "type": "AGENT_STARTED", "agent_id": "data-analyst", "message": "Agent started", "data": { "role": "data-analyst", "subtask": "Analyze revenue trends", "tools_available": ["csv_loader", "pandas", "matplotlib"] } } ``` *** ### AGENT\_THINKING **Emitted**: Agent is reasoning/processing (most frequent event) **Data**: ```json theme={null} { "type": "AGENT_THINKING", "agent_id": "data-analyst", "message": "Analyzing data structure...", "data": { "thought": "I need to first load the CSV and examine column types", "next_action": "invoke_tool", "confidence": 0.85 } } ``` **Usage**: Display as progress indicator to user *** ### AGENT\_COMPLETED **Emitted**: Agent finished its subtask **Data**: ```json theme={null} { "type": "AGENT_COMPLETED", "agent_id": "data-analyst", "message": "Agent completed successfully", "data": { "result": "Revenue increased 15% YoY", "tokens_used": 1200, "cost_usd": 0.018, "duration_ms": 8000 } } ``` *** ### AGENT\_FAILED **Emitted**: Agent encountered an error **Data**: ```json theme={null} { "type": "AGENT_FAILED", "agent_id": "data-analyst", "message": "Agent failed: Tool execution error", "data": { "error": "TOOL_EXECUTION_FAILED", "error_message": "CSV file not found", "recoverable": true } } ``` *** ## Tool Events Events related to tool invocations. ### TOOL\_INVOKED **Emitted**: When a tool is called **Data**: ```json theme={null} { "type": "TOOL_INVOKED", "message": "Invoking tool: csv_loader", "data": { "tool_name": "csv_loader", "tool_args": { "file_path": "sales_q4.csv" }, "timeout_seconds": 30 } } ``` *** ### TOOL\_OBSERVATION **Emitted**: Agent observes a tool result **Data**: ```json theme={null} { "type": "TOOL_OBSERVATION", "message": "Tool result: csv_loader", "data": { "tool_name": "csv_loader", "result": { "rows": 15000, "columns": 12, "sample": ["date", "product", "revenue", "..."] }, "duration_ms": 450, "truncated": false } } ``` **Fields**: * `tool_name`: Name of the tool that was invoked * `result`: Tool output (structured data or text) * `duration_ms`: Tool execution time * `truncated`: Whether result was truncated (true if > 2000 chars) **Note**: Large tool results are automatically truncated to 2000 characters with UTF-8 safety to prevent overwhelming the streaming connection. The `truncated` field indicates if this occurred. Full results are always available in the task completion response. *** *** ## Pattern Events Pattern selection and decomposition events are not part of the public streaming schema and are omitted for brevity. *** ## Team Events Multi-agent team coordination and management. ### TEAM\_RECRUITED **Emitted**: When a team of agents is assembled for execution **Data**: ```json theme={null} { "type": "TEAM_RECRUITED", "message": "Team recruited: 3 agents", "data": { "team_size": 3, "agents": [ { "agent_id": "data-analyst", "role": "analyst", "capabilities": ["data_loading", "analysis"] }, { "agent_id": "visualizer", "role": "visualization", "capabilities": ["charts", "graphs"] }, { "agent_id": "writer", "role": "report_generation", "capabilities": ["summarization", "writing"] } ] } } ``` *** ### TEAM\_RETIRED **Emitted**: When a team is disbanded after task completion **Data**: ```json theme={null} { "type": "TEAM_RETIRED", "message": "Team retired after task completion", "data": { "team_size": 3, "duration_ms": 45000, "total_tokens": 8000, "reason": "task_completed" } } ``` *** ### TEAM\_STATUS **Emitted**: Periodic updates on multi-agent team coordination **Data**: ```json theme={null} { "type": "TEAM_STATUS", "message": "Team progress update", "data": { "active_agents": 2, "idle_agents": 1, "tasks_completed": 5, "tasks_remaining": 3, "coordination_mode": "parallel" } } ``` *** ### DEPENDENCY\_SATISFIED **Emitted**: When task dependencies are resolved and execution can proceed **Data**: ```json theme={null} { "type": "DEPENDENCY_SATISFIED", "message": "Dependencies satisfied for subtask-3", "data": { "subtask_id": "subtask-3", "satisfied_dependencies": ["subtask-1", "subtask-2"], "can_proceed": true } } ``` *** ## Message Events Agent-to-agent communication. ### MESSAGE\_SENT **Emitted**: Agent sends message to another agent **Data**: ```json theme={null} { "type": "MESSAGE_SENT", "agent_id": "supervisor", "message": "Message sent to data-analyst", "data": { "to": "data-analyst", "content": "Please analyze revenue trends", "message_type": "DELEGATION" } } ``` *** ### MESSAGE\_RECEIVED **Emitted**: Agent receives message **Data**: ```json theme={null} { "type": "MESSAGE_RECEIVED", "agent_id": "data-analyst", "message": "Message received from supervisor", "data": { "from": "supervisor", "content": "Please analyze revenue trends", "acknowledged": true } } ``` *** ## LLM Events Language model interaction events for debugging and monitoring. ### LLM\_PROMPT **Emitted**: When a prompt is sent to the LLM (sanitized for privacy) **Data**: ```json theme={null} { "type": "LLM_PROMPT", "message": "Sending prompt to LLM", "data": { "model": "gpt-5", "prompt_length": 1200, "max_tokens": 2000, "temperature": 0.7, "sanitized_prompt": "Analyze the provided data..." } } ``` *** ### LLM\_PARTIAL **Emitted**: Incremental LLM output chunk during streaming **Data**: ```json theme={null} { "type": "LLM_PARTIAL", "message": "Received partial LLM output", "data": { "chunk": "Based on the analysis", "chunk_index": 5, "total_tokens_so_far": 50 } } ``` *** ### LLM\_OUTPUT **Emitted**: Final LLM output for a step **Data**: ```json theme={null} { "type": "LLM_OUTPUT", "message": "LLM output complete", "data": { "output": "Analysis complete. Revenue increased 15% YoY...", "model": "gpt-5", "provider": "openai", "usage": { "total_tokens": 350, "input_tokens": 200, "output_tokens": 150 }, "cost_usd": 0.0105, "duration_ms": 2000 } } ``` **Fields**: * `output`: Complete LLM response text * `model`: Model used (canonical name) * `provider`: LLM provider (openai, anthropic, google, xai, etc.) * `usage`: OpenAI-compatible usage object containing: * `total_tokens`: Total tokens (input + output) * `input_tokens`: Input/prompt tokens * `output_tokens`: Generated tokens * `cost_usd`: Estimated cost in USD * `duration_ms`: Request duration in milliseconds **Note**: Usage metadata follows OpenAI's standard format and is now available for all providers including OpenAI, Anthropic, Google, Groq, xAI, and OpenAI-compatible endpoints. The `usage` object structure matches OpenAI's streaming response format for seamless integration. See the [OpenAI-Compatible API](/en/api/rest/openai-compatible) for details on using Shannon with OpenAI SDKs. *** ## Progress Events Task progress and status updates for user feedback. ### PROGRESS **Emitted**: General progress update during execution **Data**: ```json theme={null} { "type": "PROGRESS", "message": "Progress: 60% complete", "data": { "percentage": 60, "current_step": 3, "total_steps": 5, "current_task": "Generating visualizations" } } ``` *** ### DATA\_PROCESSING **Emitted**: Agent is processing or analyzing data **Data**: ```json theme={null} { "type": "DATA_PROCESSING", "message": "Processing sales data", "data": { "operation": "data_analysis", "records_processed": 15000, "total_records": 15000, "processing_stage": "aggregation" } } ``` *** ### WAITING **Emitted**: Agent is waiting for resources or responses **Data**: ```json theme={null} { "type": "WAITING", "message": "Waiting for dependencies", "data": { "waiting_for": "subtask-2", "wait_reason": "dependency_not_satisfied", "estimated_wait_seconds": 10 } } ``` *** ## System Events System-level events and errors. ### ERROR\_OCCURRED **Emitted**: System error during execution **Data**: ```json theme={null} { "type": "ERROR_OCCURRED", "message": "Database connection failed", "data": { "error_type": "DATABASE_ERROR", "error_message": "Connection timeout", "recoverable": true, "retry_count": 2, "max_retries": 3 } } ``` *** ### ERROR\_RECOVERY **Emitted**: System is recovering from an error **Data**: ```json theme={null} { "type": "ERROR_RECOVERY", "message": "Recovering from database connection error", "data": { "error_type": "DATABASE_ERROR", "recovery_action": "retry_connection", "attempt": 2, "max_attempts": 3, "success": true } } ``` *** ### APPROVAL\_REQUESTED **Emitted**: Human approval needed to proceed **Data**: ```json theme={null} { "type": "APPROVAL_REQUESTED", "message": "Approval requested for file system access", "data": { "approval_id": "appr-123", "tool_name": "file_system", "operation": "write", "risk_level": "HIGH", "timeout_seconds": 1800, "details": { "file_path": "/data/critical.db", "action": "delete" } } } ``` *** ### APPROVAL\_DECISION **Emitted**: Human has made an approval decision **Data**: ```json theme={null} { "type": "APPROVAL_DECISION", "message": "Approval granted", "data": { "approval_id": "appr-123", "decision": "approved", "approved_by": "user-456", "timestamp": "2024-10-27T10:05:00Z", "comments": "Verified action is necessary" } } ``` **Decision Values**: * `approved` - Action allowed to proceed * `denied` - Action blocked * `timeout` - No decision within timeout period *** ### WORKSPACE\_UPDATED **Emitted**: Working memory/context updated **Data**: ```json theme={null} { "type": "WORKSPACE_UPDATED", "message": "Workspace updated", "data": { "key": "loaded_datasets", "value": ["sales_q4.csv"], "action": "ADD" } } ``` *** ### ROLE\_ASSIGNED **Emitted**: Agent role assigned during execution **Data**: ```json theme={null} { "type": "ROLE_ASSIGNED", "agent_id": "agent-002", "message": "Role assigned: data-analyst", "data": { "role": "data-analyst", "capabilities": ["data_loading", "analysis", "visualization"], "tools": ["csv_loader", "pandas", "matplotlib"] } } ``` *** ### STATUS\_UPDATE **Emitted**: General status update for the task or workflow **Data**: ```json theme={null} { "type": "STATUS_UPDATE", "message": "Task processing update", "data": { "status": "string", "details": "string" } } ``` *** ### THREAD\_MESSAGE\_DELTA **Emitted**: Incremental content chunk during streaming response generation **Data**: ```json theme={null} { "type": "THREAD_MESSAGE_DELTA", "message": "Content chunk", "data": { "delta": "string", "index": 0 } } ``` *** ### THREAD\_MESSAGE\_COMPLETED **Emitted**: Full message content has been delivered **Data**: ```json theme={null} { "type": "THREAD_MESSAGE_COMPLETED", "message": "Message complete", "data": { "content": "string", "total_tokens": 0 } } ``` *** ### BUDGET\_THRESHOLD **Emitted**: Token budget reaches a warning threshold (typically 80% of limit) **Data**: ```json theme={null} { "type": "BUDGET_THRESHOLD", "message": "Task budget at 85.0% (threshold: 80.0%)", "data": { "usage_percent": 85.0, "threshold_percent": 80.0, "tokens_used": 8500, "tokens_budget": 10000, "level": "warning", "budget_type": "task" } } ``` **Fields**: * `usage_percent`: Current usage as a percentage (e.g., 85.0) * `threshold_percent`: Warning threshold percentage (e.g., 80.0) * `tokens_used`: Cumulative tokens consumed so far * `tokens_budget`: Maximum allowed tokens for the task * `level`: Severity level (`"warning"`) * `budget_type`: Type of budget that triggered the event (`"task"`) **Usage**: Monitor this event to warn users before hitting hard budget limits, allowing graceful degradation or early termination decisions. *** ## Event Ordering Events are **strictly ordered** by sequence number (`seq`): ```json theme={null} {"seq": 1, "type": "WORKFLOW_STARTED"} {"seq": 2, "type": "AGENT_STARTED"} {"seq": 3, "type": "AGENT_THINKING"} {"seq": 4, "type": "TOOL_INVOKED"} {"seq": 5, "type": "LLM_OUTPUT"} {"seq": 6, "type": "WORKFLOW_COMPLETED"} ``` **Properties**: * Sequence numbers are monotonically increasing * No gaps in sequence (every number from 1 to N) * Events from same workflow always ordered correctly *** ## Typical Event Flow (Simplified) ``` 1. WORKFLOW_STARTED 2. AGENT_STARTED 3. AGENT_THINKING 4. TOOL_INVOKED (optional) 5. LLM_OUTPUT (final answer) 6. WORKFLOW_COMPLETED ``` ## Event Persistence Events are stored in: * **PostgreSQL**: Permanent event log * **Redis**: Recent events (hot cache) * **Real-time**: SSE stream **Retrieving Historical Events**: ```bash theme={null} # Get all events for a task GET /api/v1/tasks/{task_id}/events?limit=1000 ``` *** ## Event Reliability and Guarantees ### Ordering Guarantees Shannon provides **strict ordering** within a single workflow: * Events are numbered sequentially (`seq` field) * No gaps in sequence numbers (1, 2, 3, ...) * Events from the same workflow always arrive in order * Events from different workflows may be interleaved ### Delivery Guarantees * **At-least-once delivery**: Events may be delivered multiple times (use `seq` for deduplication) * **Event persistence**: All events stored in PostgreSQL `event_logs` table * **Hot cache**: Recent events cached in Redis for fast retrieval * **Historical access**: Query past events via REST API ### Stream Reconnection If SSE connection drops: ```python theme={null} # Reconnect and resume from last sequence number last_seq = 42 # Last received event for event in client.stream_events(workflow_id, from_seq=last_seq + 1): process_event(event) ``` ### Event Retention | Storage | Retention Period | Purpose | Event Types | | ---------- | ------------------- | ------------------- | ---------------------- | | Redis | 24 hours | Real-time streaming | All events | | PostgreSQL | 90 days (default) | Historical queries | Critical events only\* | | Archival | 1+ years (optional) | Long-term audit | Configurable | **PostgreSQL Selective Persistence**: To optimize database performance, only critical events are persisted to PostgreSQL, including: `WORKFLOW_COMPLETED`, `AGENT_COMPLETED`, `TOOL_INVOKED`, `LLM_OUTPUT`, and `ERROR_OCCURRED`. Ephemeral events like `LLM_PARTIAL`, `HEARTBEAT`, and `AGENT_THINKING` are excluded from database writes (reducing write load by \~92%) but remain fully available via real-time SSE streaming and Redis cache. See [Database Schema](/en/architecture/database-schema#event-logs-table) for event storage details. *** ## Related Topics SSE and WebSocket streaming SDK streaming guide View task history Debug streaming issues