Skip to main content

概述

Shannon 通过服务器发送事件(Server-Sent Events, SSE)发出实时事件。本文档记录平台实际发出的 35 种事件类型、它们的结构以及发生时机。 事件提供:
  • 实时进度 - 实时跟踪任务执行
  • 调试洞察 - LLM 提示词、工具调用、智能体推理
  • 成本监控 - 实时跟踪 token 使用量和成本
  • 多智能体协调 - 观察团队组建和协作
  • 错误恢复 - 监控错误处理和恢复尝试

事件结构

所有事件遵循以下基础结构:

基础字段


事件分类

事件被组织为逻辑分类:
  1. 工作流事件 - 任务生命周期
  2. 智能体事件 - 智能体执行
  3. 工具事件 - 工具调用
  4. 模式事件 - 认知模式执行
  5. 团队事件 - 多智能体协调
  6. LLM 事件 - 语言模型交互
  7. 进度事件 - 任务进度和状态
  8. 系统事件 - 错误和系统状态

事件类型快速参考(权威)

总计: 35 种事件类型 注意:WORKFLOW_FAILEDTOOL_COMPLETEDTOOL_FAILEDBUDGET_UPDATE 等事件不会由流式 API 发出。失败通过 ERROR_OCCURRED 表示;完成由 WORKFLOW_COMPLETED 表示。STREAM_END 作为生命周期信号在完成/终止后发出,用于标记流式事件结束。

工作流事件

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

WORKFLOW_STARTED

发出时机: 任务开始执行时 数据:
字段:
  • query: 原始任务查询
  • mode: 执行模式(SIMPLE、STANDARD、COMPLEX)
  • session_id: 会话标识符
  • estimated_complexity: 复杂度分数(0.0-1.0)

WORKFLOW_COMPLETED

发出时机: 任务成功完成时 数据:
字段:
  • result: 最终任务结果
  • duration_ms: 总执行时间
  • total_tokens: 累计 token 使用量
  • total_cost_usd: 总成本
  • agents_used: 调用的智能体数量
  • tools_invoked: 工具调用次数

精选示例

AGENT_THINKING

TOOL_INVOKED / TOOL_OBSERVATION

LLM_OUTPUT

ERROR_OCCURRED

APPROVAL_REQUESTED

常见错误类型:
  • BUDGET_EXCEEDED - 达到成本/token 限制
  • TIMEOUT - 执行超时
  • TOOL_EXECUTION_FAILED - 工具错误
  • LLM_ERROR - LLM 提供商错误
  • INVALID_INPUT - 格式错误的请求

智能体事件

与单个智能体执行相关的事件。

AGENT_STARTED

发出时机: 智能体开始处理时 数据:

AGENT_THINKING

发出时机: 智能体正在推理/处理(最频繁的事件) 数据:
用途: 作为进度指示器显示给用户

AGENT_COMPLETED

发出时机: 智能体完成其子任务时 数据:

AGENT_FAILED

发出时机: 智能体遇到错误时 数据:

工具事件

与工具调用相关的事件。

TOOL_INVOKED

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

TOOL_OBSERVATION

发出时机: 智能体观察工具结果时 数据:
字段:
  • tool_name: 被调用的工具名称
  • result: 工具输出(结构化数据或文本)
  • duration_ms: 工具执行时间
  • truncated: 结果是否被截断(如果 > 2000 字符则为 true)
注意: 大型工具结果会自动截断至 2000 字符(带 UTF-8 安全处理),以防止流式连接过载。truncated 字段指示是否发生截断。完整结果始终在任务完成响应中可用。

模式事件

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

团队事件

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

TEAM_RECRUITED

发出时机: 组建智能体团队进行执行时 数据:

TEAM_RETIRED

发出时机: 任务完成后解散团队时 数据:

TEAM_STATUS

发出时机: 多智能体团队协调的定期更新 数据:

DEPENDENCY_SATISFIED

发出时机: 任务依赖关系已解决且可以继续执行时 数据:

消息事件

智能体之间的通信。

MESSAGE_SENT

发出时机: 智能体向另一个智能体发送消息时 数据:

MESSAGE_RECEIVED

发出时机: 智能体接收消息时 数据:

LLM 事件

用于调试和监控的语言模型交互事件。

LLM_PROMPT

发出时机: 提示词发送到 LLM 时(为保护隐私已脱敏) 数据:

LLM_PARTIAL

发出时机: 流式传输期间的增量 LLM 输出块 数据:

LLM_OUTPUT

发出时机: 某个步骤的最终 LLM 输出 数据:
字段:
  • 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

TOOL_OBSERVATION

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

进度事件

用于用户反馈的任务进度和状态更新。

PROGRESS

发出时机: 执行期间的通用进度更新 数据:

DATA_PROCESSING

发出时机: 智能体正在处理或分析数据时 数据:

WAITING

发出时机: 智能体正在等待资源或响应时 数据:

系统事件

系统级事件和错误。

ERROR_OCCURRED

发出时机: 执行期间发生系统错误时 数据:


ERROR_RECOVERY

发出时机: 系统正在从错误中恢复时 数据:

APPROVAL_REQUESTED

发出时机: 需要人工批准才能继续时 数据:

APPROVAL_DECISION

发出时机: 人工做出批准决策时 数据:
决策值:
  • approved - 允许操作继续
  • denied - 阻止操作
  • timeout - 超时期间内未做决策

WORKSPACE_UPDATED

发出时机: 工作内存/上下文更新时 数据:

ROLE_ASSIGNED

发出时机: 执行期间分配智能体角色时 数据:

STATUS_UPDATE

发出时机: 任务或工作流的通用状态更新 数据:

THREAD_MESSAGE_DELTA

发出时机: 流式响应生成期间的增量内容块 数据:

THREAD_MESSAGE_COMPLETED

发出时机: 完整消息内容已传递 数据:

BUDGET_THRESHOLD

发出时机: Token 预算达到警告阈值(通常为限制的 80%) 数据:
字段:
  • usage_percent: 当前使用百分比(例如 85.0)
  • threshold_percent: 警告阈值百分比(例如 80.0)
  • tokens_used: 目前累计消耗的 token 数
  • tokens_budget: 任务允许的最大 token 数
  • level: 严重级别("warning"
  • budget_type: 触发事件的预算类型("task"
用途: 监控此事件可在触发硬性预算限制之前警告用户,允许优雅降级或提前终止决策。

事件排序

事件按序列号(seq)严格排序:
特性:
  • 序列号单调递增
  • 序列中无间隙(从 1 到 N 的每个数字)
  • 来自同一工作流的事件始终正确排序

典型事件流程(简化)

事件持久化

事件存储在:
  • PostgreSQL: 永久事件日志
  • Redis: 最近的事件(热缓存)
  • 实时: SSE 流
检索历史事件:

事件可靠性和保证

排序保证

Shannon 在单个工作流内提供严格排序:
  • 事件按顺序编号(seq 字段)
  • 序列号无间隙(1、2、3、…)
  • 来自同一工作流的事件始终按顺序到达
  • 来自不同工作流的事件可能会交错

交付保证

  • 至少一次交付: 事件可能会被多次交付(使用 seq 进行去重)
  • 事件持久化: 所有事件存储在 PostgreSQL event_logs 表中
  • 热缓存: 最近的事件缓存在 Redis 中以便快速检索
  • 历史访问: 通过 REST API 查询过去的事件

流重连

如果 SSE 连接断开:

事件保留期

PostgreSQL 选择性持久化: 为优化数据库性能,仅关键事件会持久化到 PostgreSQL,包括:WORKFLOW_COMPLETEDAGENT_COMPLETEDTOOL_INVOKEDLLM_OUTPUTERROR_OCCURRED。临时事件如 LLM_PARTIALHEARTBEATAGENT_THINKING 会从数据库写入中排除(减少约 92% 的写入负载),但仍可通过实时 SSE 流式传输和 Redis 缓存完全获取。 有关事件存储详情,请参见数据库模式

相关主题

流式传输 API

SSE 和 WebSocket 流式传输

Python SDK 流式传输

SDK 流式传输指南

列出任务

查看任务历史

故障排除

调试流式传输问题