Skip to content

Events And Audit

SSE 事件流

客户端通过 GET /sessions/{id}/events 监听 session 实时输出，单向流式推送。

事件类型

事件 触发时机 关键字段
run.queued run 入队 runId
run.started run 开始执行 runId, agentName
run.progress 进度更新 runId, step
message.delta 流式文本增量 runId, content
agent.switch.requested 请求切换 agent runId, fromAgent, toAgent
agent.switched 切换完成 runId, agentName
agent.delegate.started subagent 开始 runId, childRunId, agentName
agent.delegate.completed subagent 完成 runId, childRunId
agent.delegate.failed subagent 失败 runId, childRunId, error
tool.started tool 开始 runId, toolName, toolCallId
tool.completed tool 成功 runId, toolName, toolCallId
tool.failed tool 失败 runId, toolName, error
history.mirror.* 镜像同步状态 workspaceId
run.completed 正常完成 runId
run.failed 执行失败 runId, errorCode
run.cancelled 被取消 runId

事件格式示例

{ "event": "message.delta",
  "data": { "sessionId": "ses_abc", "runId": "run_123", "content": "让我先看看这个文件" } }

{ "event": "tool.completed",
  "data": { "sessionId": "ses_abc", "runId": "run_123", "toolName": "Read", "toolCallId": "tc_456", "durationMs": 42 } }

{ "event": "run.completed",
  "data": { "sessionId": "ses_abc", "runId": "run_123", "agentName": "builder", "switchCount": 1, "durationMs": 15420 } }

客户端消费建议

  • cursor 支持断线重连
  • message.delta 需客户端拼接完整文本
  • 监听 run.completed / run.failed / run.cancelled 判断结束
  • 不依赖事件顺序推断状态，以 GET /runs/{id} 为准

结构化日志与审计

审计范围

节点 内容
API 请求入口 方法、路径、caller context
run 状态变更 queued → running → completed 等
model call model_ref、token 用量、延迟
tool call tool_name、执行状态、耗时
action run action 名、输入、结果
hook run hook 名、事件、决策
backend shell 命令、exit code、耗时
history mirror 同步进度、最后事件 ID

日志字段

字段 说明
subject_ref 调用方标识
workspace_id / session_id / run_id 关联标识
agent_name / effective_agent_name agent 标识
tool_name tool 名称
duration_ms 耗时
status 结果状态
history_event_id / mirror_last_event_id 事件序号

存储

  • 审计记录持久化在 PostgreSQL（tool_calls、hook_runs 等表）
  • 结构化日志输出到 stdout，可对接外部系统
  • SSE 事件写入 session_events 表，支持回放和断线重连