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.
Shannon 通过服务器发送事件(Server-Sent Events, SSE)发出实时事件 。本文档记录平台实际发出的 35 种事件类型 、它们的结构以及发生时机。
事件提供:
实时进度 - 实时跟踪任务执行
调试洞察 - LLM 提示词、工具调用、智能体推理
成本监控 - 实时跟踪 token 使用量和成本
多智能体协调 - 观察团队组建和协作
错误恢复 - 监控错误处理和恢复尝试
事件结构
所有事件遵循以下基础结构:
{
"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" : {}
}
基础字段
字段 类型 描述 workflow_idstring 唯一的任务/工作流标识符 typestring 事件类型(参见下面的目录) agent_idstring 发出事件的智能体 messagestring 人类可读的事件描述 timestampISO 8601 事件发生时间 seqinteger 用于排序的序列号 stream_idstring 用于重连的流标识符 payloadobject 事件特定的载荷(可选,序列化为 payload)
事件分类
事件被组织为逻辑分类:
工作流事件 - 任务生命周期
智能体事件 - 智能体执行
工具事件 - 工具调用
模式事件 - 认知模式执行
团队事件 - 多智能体协调
LLM 事件 - 语言模型交互
进度事件 - 任务进度和状态
系统事件 - 错误和系统状态
事件类型快速参考(权威)
事件类型 分类 描述 WORKFLOW_STARTED工作流 任务开始执行 WORKFLOW_COMPLETED工作流 任务成功完成 WORKFLOW_PAUSING工作流控制 收到暂停请求,工作流准备在检查点暂停 WORKFLOW_PAUSED工作流控制 工作流在检查点已暂停 WORKFLOW_RESUMED工作流控制 工作流从暂停状态恢复 WORKFLOW_CANCELLING工作流控制 收到取消请求,工作流准备终止 WORKFLOW_CANCELLED工作流控制 工作流在检查点已取消 AGENT_STARTED智能体 智能体开始处理 AGENT_THINKING智能体 智能体推理/规划 AGENT_COMPLETED智能体 智能体成功完成 TOOL_INVOKED工具 调用工具 TOOL_OBSERVATION工具 智能体观察工具结果 TEAM_RECRUITED团队 组建多智能体团队 TEAM_RETIRED团队 解散团队 TEAM_STATUS团队 团队协调更新 DEPENDENCY_SATISFIED团队 依赖关系已解决 MESSAGE_SENT消息 智能体发送消息 MESSAGE_RECEIVED消息 智能体接收消息 LLM_PROMPTLLM 发送至 LLM 的提示 LLM_PARTIALLLM 流式 LLM 输出 LLM_OUTPUTLLM 最终 LLM 输出 PROGRESS进度 通用进度更新 DATA_PROCESSING进度 处理/分析数据 WAITING进度 等待资源 ERROR_OCCURRED系统 错误发生 ERROR_RECOVERY系统 错误恢复尝试 APPROVAL_REQUESTED系统 需要人工批准 APPROVAL_DECISION系统 批准决策已做出 WORKSPACE_UPDATED系统 内存/上下文已更新 ROLE_ASSIGNED系统 智能体角色已分配 STATUS_UPDATE系统 通用状态更新 BUDGET_THRESHOLD系统/进度 任务预算达到预警阈值 THREAD_MESSAGE_DELTA流式 增量消息内容块 THREAD_MESSAGE_COMPLETED流式 消息内容已完整传递 STREAM_END流式 显式的流结束信号(该工作流不会再有新事件)
总计 : 35 种事件类型
注意:WORKFLOW_FAILED、TOOL_COMPLETED、TOOL_FAILED、BUDGET_UPDATE 等事件不会由流式 API 发出。失败通过 ERROR_OCCURRED 表示;完成由 WORKFLOW_COMPLETED 表示。STREAM_END 作为生命周期信号在完成/终止后发出,用于标记流式事件结束。
工作流事件
与整体任务工作流相关的事件。
WORKFLOW_STARTED
发出时机 : 任务开始执行时
数据 :
{
"type" : "WORKFLOW_STARTED" ,
"message" : "Workflow started" ,
"data" : {
"query" : "Analyze Q4 sales data" ,
"mode" : "STANDARD" ,
"session_id" : "sess-123" ,
"estimated_complexity" : 0.75
}
}
字段 :
query: 原始任务查询
mode: 执行模式(SIMPLE、STANDARD、COMPLEX)
session_id: 会话标识符
estimated_complexity: 复杂度分数(0.0-1.0)
WORKFLOW_COMPLETED
发出时机 : 任务成功完成时
数据 :
{
"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
}
}
字段 :
result: 最终任务结果
duration_ms: 总执行时间
total_tokens: 累计 token 使用量
total_cost_usd: 总成本
agents_used: 调用的智能体数量
tools_invoked: 工具调用次数
精选示例
AGENT_THINKING
{
"type" : "AGENT_THINKING" ,
"agent_id" : "researcher" ,
"message" : "Analyzing data structure..." ,
"timestamp" : "2025-01-20T10:00:02Z"
}
{ "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" }
}
常见错误类型 :
BUDGET_EXCEEDED - 达到成本/token 限制
TIMEOUT - 执行超时
TOOL_EXECUTION_FAILED - 工具错误
LLM_ERROR - LLM 提供商错误
INVALID_INPUT - 格式错误的请求
智能体事件
与单个智能体执行相关的事件。
AGENT_STARTED
发出时机 : 智能体开始处理时
数据 :
{
"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
发出时机 : 智能体正在推理/处理(最频繁的事件)
数据 :
{
"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
}
}
用途 : 作为进度指示器显示给用户
AGENT_COMPLETED
发出时机 : 智能体完成其子任务时
数据 :
{
"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
发出时机 : 智能体遇到错误时
数据 :
{
"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
}
}
工具事件
与工具调用相关的事件。
发出时机 : 调用工具时
数据 :
{
"type" : "TOOL_INVOKED" ,
"message" : "Invoking tool: csv_loader" ,
"data" : {
"tool_name" : "csv_loader" ,
"tool_args" : {
"file_path" : "sales_q4.csv"
},
"timeout_seconds" : 30
}
}
发出时机 : 智能体观察工具结果时
数据 :
{
"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
}
}
字段 :
tool_name: 被调用的工具名称
result: 工具输出(结构化数据或文本)
duration_ms: 工具执行时间
truncated: 结果是否被截断(如果 > 2000 字符则为 true)
注意 : 大型工具结果会自动截断至 2000 字符(带 UTF-8 安全处理),以防止流式连接过载。truncated 字段指示是否发生截断。完整结果始终在任务完成响应中可用。
模式事件
模式选择与任务拆解事件不属于对外公开的流式事件架构,省略不表。
团队事件
多智能体团队协调和管理。
TEAM_RECRUITED
发出时机 : 组建智能体团队进行执行时
数据 :
{
"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
发出时机 : 任务完成后解散团队时
数据 :
{
"type" : "TEAM_RETIRED" ,
"message" : "Team retired after task completion" ,
"data" : {
"team_size" : 3 ,
"duration_ms" : 45000 ,
"total_tokens" : 8000 ,
"reason" : "task_completed"
}
}
TEAM_STATUS
发出时机 : 多智能体团队协调的定期更新
数据 :
{
"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
发出时机 : 任务依赖关系已解决且可以继续执行时
数据 :
{
"type" : "DEPENDENCY_SATISFIED" ,
"message" : "Dependencies satisfied for subtask-3" ,
"data" : {
"subtask_id" : "subtask-3" ,
"satisfied_dependencies" : [ "subtask-1" , "subtask-2" ],
"can_proceed" : true
}
}
消息事件
智能体之间的通信。
MESSAGE_SENT
发出时机 : 智能体向另一个智能体发送消息时
数据 :
{
"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
发出时机 : 智能体接收消息时
数据 :
{
"type" : "MESSAGE_RECEIVED" ,
"agent_id" : "data-analyst" ,
"message" : "Message received from supervisor" ,
"data" : {
"from" : "supervisor" ,
"content" : "Please analyze revenue trends" ,
"acknowledged" : true
}
}
LLM 事件
用于调试和监控的语言模型交互事件。
LLM_PROMPT
发出时机 : 提示词发送到 LLM 时(为保护隐私已脱敏)
数据 :
{
"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
发出时机 : 流式传输期间的增量 LLM 输出块
数据 :
{
"type" : "LLM_PARTIAL" ,
"message" : "Received partial LLM output" ,
"data" : {
"chunk" : "Based on the analysis" ,
"chunk_index" : 5 ,
"total_tokens_so_far" : 50
}
}
LLM_OUTPUT
发出时机 : 某个步骤的最终 LLM 输出
数据 :
{
"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
}
}
字段 :
output: 完整的 LLM 响应文本
model: 使用的模型(规范名称)
provider: LLM 提供商(openai、anthropic、google、xai 等)
usage: OpenAI 兼容的使用对象,包含:
total_tokens: 总 token 数(输入 + 输出)
input_tokens: 输入/提示 token 数
output_tokens: 生成的 token 数
cost_usd: 估计成本(美元)
duration_ms: 请求持续时间(毫秒)
注意 : 使用元数据遵循 OpenAI 的标准格式,现在可用于所有提供商,包括 OpenAI、Anthropic、Google、Groq、xAI 和 OpenAI 兼容端点。usage 对象结构与 OpenAI 的流式响应格式匹配,实现无缝集成。有关使用 OpenAI SDK 与 Shannon 交互的详细信息,请参阅 OpenAI 兼容 API 。
发出时机 : 智能体观察工具结果时
数据 :
{
"type" : "TOOL_OBSERVATION" ,
"message" : "Agent observed tool result" ,
"data" : {
"tool_name" : "web_search" ,
"observation" : "Found 10 relevant results about AI trends" ,
"relevance_score" : 0.85
}
}
进度事件
用于用户反馈的任务进度和状态更新。
PROGRESS
发出时机 : 执行期间的通用进度更新
数据 :
{
"type" : "PROGRESS" ,
"message" : "Progress: 60% complete" ,
"data" : {
"percentage" : 60 ,
"current_step" : 3 ,
"total_steps" : 5 ,
"current_task" : "Generating visualizations"
}
}
DATA_PROCESSING
发出时机 : 智能体正在处理或分析数据时
数据 :
{
"type" : "DATA_PROCESSING" ,
"message" : "Processing sales data" ,
"data" : {
"operation" : "data_analysis" ,
"records_processed" : 15000 ,
"total_records" : 15000 ,
"processing_stage" : "aggregation"
}
}
WAITING
发出时机 : 智能体正在等待资源或响应时
数据 :
{
"type" : "WAITING" ,
"message" : "Waiting for dependencies" ,
"data" : {
"waiting_for" : "subtask-2" ,
"wait_reason" : "dependency_not_satisfied" ,
"estimated_wait_seconds" : 10
}
}
系统事件
系统级事件和错误。
ERROR_OCCURRED
发出时机 : 执行期间发生系统错误时
数据 :
{
"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
发出时机 : 系统正在从错误中恢复时
数据 :
{
"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
发出时机 : 需要人工批准才能继续时
数据 :
{
"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
发出时机 : 人工做出批准决策时
数据 :
{
"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"
}
}
决策值 :
approved - 允许操作继续
denied - 阻止操作
timeout - 超时期间内未做决策
WORKSPACE_UPDATED
发出时机 : 工作内存/上下文更新时
数据 :
{
"type" : "WORKSPACE_UPDATED" ,
"message" : "Workspace updated" ,
"data" : {
"key" : "loaded_datasets" ,
"value" : [ "sales_q4.csv" ],
"action" : "ADD"
}
}
ROLE_ASSIGNED
发出时机 : 执行期间分配智能体角色时
数据 :
{
"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
发出时机 : 任务或工作流的通用状态更新
数据 :
{
"type" : "STATUS_UPDATE" ,
"message" : "Task processing update" ,
"data" : {
"status" : "string" ,
"details" : "string"
}
}
THREAD_MESSAGE_DELTA
发出时机 : 流式响应生成期间的增量内容块
数据 :
{
"type" : "THREAD_MESSAGE_DELTA" ,
"message" : "Content chunk" ,
"data" : {
"delta" : "string" ,
"index" : 0
}
}
THREAD_MESSAGE_COMPLETED
发出时机 : 完整消息内容已传递
数据 :
{
"type" : "THREAD_MESSAGE_COMPLETED" ,
"message" : "Message complete" ,
"data" : {
"content" : "string" ,
"total_tokens" : 0
}
}
BUDGET_THRESHOLD
发出时机 : Token 预算达到警告阈值(通常为限制的 80%)
数据 :
{
"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"
}
}
字段 :
usage_percent: 当前使用百分比(例如 85.0)
threshold_percent: 警告阈值百分比(例如 80.0)
tokens_used: 目前累计消耗的 token 数
tokens_budget: 任务允许的最大 token 数
level: 严重级别("warning")
budget_type: 触发事件的预算类型("task")
用途 : 监控此事件可在触发硬性预算限制之前警告用户,允许优雅降级或提前终止决策。
事件排序
事件按序列号(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" }
特性 :
序列号单调递增
序列中无间隙(从 1 到 N 的每个数字)
来自同一工作流的事件始终正确排序
典型事件流程(简化)
1. WORKFLOW_STARTED
2. AGENT_STARTED
3. AGENT_THINKING
4. TOOL_INVOKED(可选)
5. LLM_OUTPUT(最终答案)
6. WORKFLOW_COMPLETED
事件持久化
事件存储在:
PostgreSQL : 永久事件日志
Redis : 最近的事件(热缓存)
实时 : SSE 流
检索历史事件 :
# 获取任务的所有事件
GET /api/v1/tasks/{task_id}/events?limit= 1000
事件可靠性和保证
排序保证
Shannon 在单个工作流内提供严格排序 :
事件按顺序编号(seq 字段)
序列号无间隙(1、2、3、…)
来自同一工作流的事件始终按顺序到达
来自不同工作流的事件可能会交错
交付保证
至少一次交付 : 事件可能会被多次交付(使用 seq 进行去重)
事件持久化 : 所有事件存储在 PostgreSQL event_logs 表中
热缓存 : 最近的事件缓存在 Redis 中以便快速检索
历史访问 : 通过 REST API 查询过去的事件
流重连
如果 SSE 连接断开:
# 重连并从最后一个序列号恢复
last_seq = 42 # 最后接收的事件
for event in client.stream_events(workflow_id, from_seq =last_seq + 1 ):
process_event(event)
事件保留期
存储 保留期 用途 事件类型 Redis 24 小时 实时流式传输 所有事件 PostgreSQL 90 天(默认) 历史查询 仅关键事件* 归档 1 年以上(可选) 长期审计 可配置
PostgreSQL 选择性持久化 : 为优化数据库性能,仅关键事件会持久化到 PostgreSQL,包括:WORKFLOW_COMPLETED、AGENT_COMPLETED、TOOL_INVOKED、LLM_OUTPUT 和 ERROR_OCCURRED。临时事件如 LLM_PARTIAL、HEARTBEAT 和 AGENT_THINKING 会从数据库写入中排除(减少约 92% 的写入负载),但仍可通过实时 SSE 流式传输和 Redis 缓存完全获取。
有关事件存储详情,请参见数据库模式 。
相关主题
流式传输 API SSE 和 WebSocket 流式传输
Python SDK 流式传输 SDK 流式传输指南