Event Types Catalog

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:

{
  "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:

Workflow Events - Task lifecycle
Agent Events - Agent execution
Tool Events - Tool invocations
Pattern Events - Cognitive pattern execution
Team Events - Multi-agent coordination
LLM Events - Language model interactions
Progress Events - Task progress and status
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:

{
  "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:

{
  "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

{
  "type": "AGENT_THINKING",
  "agent_id": "researcher",
  "message": "Analyzing data structure...",
  "timestamp": "2025-01-20T10:00:02Z"
}

TOOL_INVOKED / TOOL_OBSERVATION

{ "type": "TOOL_INVOKED", "message": "web_search: q=\"LLM caching\"" }
{ "type": "TOOL_OBSERVATION", "message": "web_search: 12 results" }

LLM_OUTPUT

{
  "type": "LLM_OUTPUT",
  "message": "Final summary of findings..."
}

ERROR_OCCURRED

{
  "type": "ERROR_OCCURRED",
  "message": "Provider rate limit exceeded",
  "data": { "error": "RATE_LIMIT", "retry_after": 30 }
}

APPROVAL_REQUESTED

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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 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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "type": "STATUS_UPDATE",
  "message": "Task processing update",
  "data": {
    "status": "string",
    "details": "string"
  }
}

THREAD_MESSAGE_DELTA

Emitted: Incremental content chunk during streaming response generation Data:

{
  "type": "THREAD_MESSAGE_DELTA",
  "message": "Content chunk",
  "data": {
    "delta": "string",
    "index": 0
  }
}

THREAD_MESSAGE_COMPLETED

Emitted: Full message content has been delivered Data:

{
  "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:

{
  "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):

{"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)

WORKFLOW_STARTED
AGENT_STARTED
AGENT_THINKING
TOOL_INVOKED (optional)
LLM_OUTPUT (final answer)
WORKFLOW_COMPLETED

Event Persistence

Events are stored in:

PostgreSQL: Permanent event log
Redis: Recent events (hot cache)
Real-time: SSE stream

Retrieving Historical Events:

# 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:

# 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 for event storage details.

Streaming API

SSE and WebSocket streaming

Python SDK Streaming

SDK streaming guide

List Tasks

View task history

Troubleshooting

Debug streaming issues

​Overview

​Event Structure

​Base Fields

​Event Categories

​Event Type Quick Reference

​Workflow Events

​WORKFLOW_STARTED

​WORKFLOW_COMPLETED

​Selected Examples

​AGENT_THINKING

​TOOL_INVOKED / TOOL_OBSERVATION

​LLM_OUTPUT

​ERROR_OCCURRED

​APPROVAL_REQUESTED

​Agent Events

​AGENT_STARTED

​AGENT_THINKING

​AGENT_COMPLETED

​AGENT_FAILED

​Tool Events

​TOOL_INVOKED

​TOOL_OBSERVATION

​Pattern Events

​Team Events

​TEAM_RECRUITED

​TEAM_RETIRED

​TEAM_STATUS

​DEPENDENCY_SATISFIED

​Message Events

​MESSAGE_SENT

​MESSAGE_RECEIVED

​LLM Events

​LLM_PROMPT

​LLM_PARTIAL

​LLM_OUTPUT

​Progress Events

​PROGRESS

​DATA_PROCESSING

​WAITING

​System Events

​ERROR_OCCURRED

​ERROR_RECOVERY

​APPROVAL_REQUESTED

​APPROVAL_DECISION

​WORKSPACE_UPDATED

​ROLE_ASSIGNED

​STATUS_UPDATE

​THREAD_MESSAGE_DELTA

​THREAD_MESSAGE_COMPLETED

​BUDGET_THRESHOLD

​Event Ordering

​Typical Event Flow (Simplified)

​Event Persistence

​Event Reliability and Guarantees

​Ordering Guarantees

​Delivery Guarantees

​Stream Reconnection

​Event Retention

​Related Topics

Streaming API

Python SDK Streaming

List Tasks

Troubleshooting

Overview

Event Structure

Base Fields

Event Categories

Event Type Quick Reference

Workflow Events

WORKFLOW_STARTED

WORKFLOW_COMPLETED

Selected Examples

AGENT_THINKING

TOOL_INVOKED / TOOL_OBSERVATION

LLM_OUTPUT

ERROR_OCCURRED

APPROVAL_REQUESTED

Agent Events

AGENT_STARTED

AGENT_THINKING

AGENT_COMPLETED

AGENT_FAILED

Tool Events

TOOL_INVOKED

TOOL_OBSERVATION

Pattern Events

Team Events

TEAM_RECRUITED

TEAM_RETIRED

TEAM_STATUS

DEPENDENCY_SATISFIED

Message Events

MESSAGE_SENT

MESSAGE_RECEIVED

LLM Events

LLM_PROMPT

LLM_PARTIAL

LLM_OUTPUT

Progress Events

PROGRESS

DATA_PROCESSING

WAITING

System Events

ERROR_OCCURRED

ERROR_RECOVERY

APPROVAL_REQUESTED

APPROVAL_DECISION

WORKSPACE_UPDATED

ROLE_ASSIGNED

STATUS_UPDATE

THREAD_MESSAGE_DELTA

THREAD_MESSAGE_COMPLETED

BUDGET_THRESHOLD

Event Ordering

Typical Event Flow (Simplified)

Event Persistence

Event Reliability and Guarantees

Ordering Guarantees

Delivery Guarantees

Stream Reconnection

Event Retention

Related Topics