事件类型目录

概述

Shannon 通过服务器发送事件(Server-Sent Events, SSE)发出实时事件。本文档记录平台实际发出的 26 种事件类型、它们的结构以及发生时机。事件提供:

实时进度 - 实时跟踪任务执行
调试洞察 - 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",
  "data": {}
}

基础字段

字段	类型	描述
`workflow_id`	string	唯一的任务/工作流标识符
`type`	string	事件类型(参见下面的目录)
`agent_id`	string	发出事件的智能体
`message`	string	人类可读的事件描述
`timestamp`	ISO 8601	事件发生时间
`seq`	integer	用于排序的序列号
`stream_id`	string	用于重连的流标识符
`data`	object	事件特定的载荷(可选)

事件分类

事件被组织为逻辑分类:

工作流事件 - 任务生命周期
智能体事件 - 智能体执行
工具事件 - 工具调用
模式事件 - 认知模式执行
团队事件 - 多智能体协调
LLM 事件 - 语言模型交互
进度事件 - 任务进度和状态
系统事件 - 错误和系统状态

事件类型快速参考（权威）

事件类型	分类	描述
`WORKFLOW_STARTED`	工作流	任务开始执行
`WORKFLOW_COMPLETED`	工作流	任务成功完成
`AGENT_STARTED`	智能体	智能体开始处理
`AGENT_THINKING`	智能体	智能体推理/规划
`AGENT_COMPLETED`	智能体	智能体成功完成
`TOOL_INVOKED`	工具	调用工具
`TOOL_OBSERVATION`	工具	智能体观察工具结果
`TEAM_RECRUITED`	团队	组建多智能体团队
`TEAM_RETIRED`	团队	解散团队
`TEAM_STATUS`	团队	团队协调更新
`DEPENDENCY_SATISFIED`	团队	依赖关系已解决
`MESSAGE_SENT`	消息	智能体发送消息
`MESSAGE_RECEIVED`	消息	智能体接收消息
`LLM_PROMPT`	LLM	发送至 LLM 的提示
`LLM_PARTIAL`	LLM	流式 LLM 输出
`LLM_OUTPUT`	LLM	最终 LLM 输出
`PROGRESS`	进度	通用进度更新
`DATA_PROCESSING`	进度	处理/分析数据
`WAITING`	进度	等待资源
`ERROR_OCCURRED`	系统	错误发生
`ERROR_RECOVERY`	系统	错误恢复尝试
`APPROVAL_REQUESTED`	系统	需要人工批准
`APPROVAL_DECISION`	系统	批准决策已做出
`WORKSPACE_UPDATED`	系统	内存/上下文已更新
`ROLE_ASSIGNED`	系统	智能体角色已分配
`DELEGATION`	系统	任务已委托

总计: 26 种事件类型注意：WORKFLOW_FAILED、TOOL_COMPLETED、TOOL_FAILED、BUDGET_UPDATE 等事件不会由流式 API 发出。失败通过 ERROR_OCCURRED 表示；完成由 WORKFLOW_COMPLETED 表示。

工作流事件

与整体任务工作流相关的事件。

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

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

常见错误类型:

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
  }
}

工具事件

与工具调用相关的事件。

TOOL_INVOKED

发出时机: 调用工具时数据:

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

发出时机: 智能体观察工具结果时数据:

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

模式事件

模式选择与任务拆解事件不属于对外公开的流式事件架构，省略不表。

团队事件

多智能体团队协调和管理。

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",
    "tokens_used": 350,
    "cost_usd": 0.0105,
    "duration_ms": 2000
  }
}

TOOL_OBSERVATION

发出时机: 智能体观察工具结果时数据:

{
  "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": 7200,
    "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"]
  }
}

DELEGATION

发出时机: 任务委托给另一个智能体时数据:

{
  "type": "DELEGATION",
  "agent_id": "supervisor",
  "message": "Delegated to data-analyst",
  "data": {
    "to_agent": "data-analyst",
    "task": "Analyze revenue trends",
    "priority": "HIGH"
  }
}

事件排序

事件按序列号(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 的每个数字)
来自同一工作流的事件始终正确排序

典型事件流程（简化）

WORKFLOW_STARTED
AGENT_STARTED
AGENT_THINKING
TOOL_INVOKED（可选）
LLM_OUTPUT（最终答案）
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	1 小时	实时流式传输
PostgreSQL	90 天(默认)	历史查询
归档	1 年以上(可选)	长期审计

有关事件存储详情,请参见数据库模式。

流式传输 API

SSE 和 WebSocket 流式传输

Python SDK 流式传输

SDK 流式传输指南

列出任务

查看任务历史

故障排除

调试流式传输问题

概览

认证与请求头

任务

会话

流式

模型

​概述

​事件结构

​基础字段

​事件分类

​事件类型快速参考（权威）

​工作流事件

​WORKFLOW_STARTED

​WORKFLOW_COMPLETED

​精选示例

​AGENT_THINKING

​TOOL_INVOKED / TOOL_OBSERVATION

​LLM_OUTPUT

​ERROR_OCCURRED

​APPROVAL_REQUESTED

​智能体事件

​AGENT_STARTED

​AGENT_THINKING

​AGENT_COMPLETED

​AGENT_FAILED

​工具事件

​TOOL_INVOKED

​TOOL_OBSERVATION

​模式事件

​团队事件

​TEAM_RECRUITED

​TEAM_RETIRED

​TEAM_STATUS

​DEPENDENCY_SATISFIED

​消息事件

​MESSAGE_SENT

​MESSAGE_RECEIVED

​LLM 事件

​LLM_PROMPT

​LLM_PARTIAL

​LLM_OUTPUT

​TOOL_OBSERVATION

​进度事件

​PROGRESS

​DATA_PROCESSING

​WAITING

​系统事件

​ERROR_OCCURRED

​ERROR_RECOVERY

​APPROVAL_REQUESTED

​APPROVAL_DECISION

​WORKSPACE_UPDATED

​ROLE_ASSIGNED

​DELEGATION

​事件排序

​典型事件流程（简化）

​事件持久化

​事件可靠性和保证

​排序保证

​交付保证

​流重连

​事件保留期

​相关主题

流式传输 API

Python SDK 流式传输

列出任务

故障排除

概述

事件结构

基础字段

事件分类

事件类型快速参考（权威）

工作流事件

WORKFLOW_STARTED

WORKFLOW_COMPLETED

精选示例

AGENT_THINKING

TOOL_INVOKED / TOOL_OBSERVATION

LLM_OUTPUT

ERROR_OCCURRED

APPROVAL_REQUESTED

智能体事件

AGENT_STARTED

AGENT_THINKING

AGENT_COMPLETED

AGENT_FAILED

工具事件

TOOL_INVOKED

TOOL_OBSERVATION

模式事件

团队事件

TEAM_RECRUITED

TEAM_RETIRED

TEAM_STATUS

DEPENDENCY_SATISFIED

消息事件

MESSAGE_SENT

MESSAGE_RECEIVED

LLM 事件

LLM_PROMPT

LLM_PARTIAL

LLM_OUTPUT

TOOL_OBSERVATION

进度事件

PROGRESS

DATA_PROCESSING

WAITING

系统事件

ERROR_OCCURRED

ERROR_RECOVERY

APPROVAL_REQUESTED

APPROVAL_DECISION

WORKSPACE_UPDATED

ROLE_ASSIGNED

DELEGATION

事件排序

典型事件流程（简化）

事件持久化

事件可靠性和保证

排序保证

交付保证

流重连

事件保留期

相关主题