Skip to main content

Session & Event 数据结构

适用于 Forward Session API 的 Session 与 Event 相关数据结构说明。

Session 对象

创建、获取、列出、更新和归档 Session 的接口都会返回该对象。
{
  "id": "sess_xxx",
  "type": "session",
  "identity_id": "idn_xxx",
  "template": {
    "id": "tmpl_support",
    "type": "template",
    "name": "客服助手",
    "model": "ultimate",
    "version": 3
  },
  "source_type": "api",
  "status": "idle",
  "title": "客户支持会话",
  "metadata": {
    "source": "web",
    "biz_id": "ticket_123"
  },
  "config": {
    "environment_variables": {
      "API_KEY": "sk-xxx"
    }
  },
  "resources": [
    {
      "id": "sesr_xxx",
      "type": "file",
      "file_id": "file_xxx",
      "mount_path": "/data/workspace/spec.md",
      "created_at": "2026-06-23T05:53:19Z",
      "updated_at": "2026-06-23T05:53:38Z"
    }
  ],
  "stats": {
    "active_seconds": 30,
    "duration_seconds": 3600
  },
  "usage": {
    "model_credits": 10.5,
    "sandbox_runtime_credits": 2,
    "total_credits": 12.5
  },
  "budget": {
    "type": "limit",
    "max_credit_cost": "100.00"
  },
  "outcome_evaluations": [
    {
      "type": "outcome_evaluation",
      "outcome_id": "outc_xxx",
      "description": "Resolve the customer issue",
      "iteration": 1,
      "result": "satisfied",
      "explanation": "The issue was resolved.",
      "completed_at": "2026-06-22T10:30:00Z"
    }
  ],
  "archived_at": null,
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T11:00:00Z"
}
字段类型必返说明
idstring是sess_ 前缀的 Session ID。
typestring是固定为 "session"。
identity_idstring是Forward Identity ID,表示该 Session 归属的终端用户身份。
templateobject是Forward Template 摘要,字段见 Template 摘要。
source_typestring是Session 来源:api、im、schedule 或 batch。
statusstring是Session 运行状态:idle、running、rescheduling、canceling 或 terminated。归档状态通过 archived_at 表达。
titlestring是Session 标题。
metadataobject否调用方业务元数据。
configobject否Session 配置;未传入时可能省略。
config.environment_variablesobject否会话级环境变量,key-value 形式;在 Template + Identity Config 编译结果基础上追加合并,同名变量覆盖基础层的值。
config.multiagentobject | null否通过更新 Session保存的子 Agent 名单覆盖,保留提交的 Forward 引用形态。null 表示显式清空,未设置覆盖时省略;不返回运行时固定的具体子 Agent 版本。
resourcesarray否Session 挂载的资源列表。当前仅返回通过添加 Session 资源接口添加的 file 类型资源;无资源时为空数组。
statsobject否Session 统计信息,字段见 Session stats。
usageobject否用量信息;没有可用数据时省略。
usage.model_creditsnumber否模型消耗的 Credit。
usage.sandbox_runtime_creditsnumber否Sandbox 运行时消耗的 Credit。
usage.total_creditsnumber否CAS 返回的累计 Credit 消耗。
budgetobject否Session 生命周期累计 Credit 上限,字段见 Session budget。
outcome_evaluationsarray是Outcome 的当前评估状态;没有 Outcome 时为空数组。
archived_atstring | null是归档时间,未归档时为 null。
created_atstring是创建时间,RFC 3339 格式。
updated_atstring是最近更新时间,RFC 3339 格式。

Template 摘要

字段类型必返说明
idstring是Forward Template ID。
typestring是固定为 "template"。
namestring是Template 名称。
modelstring是Template 使用的模型档位或模型标识。
versioninteger是Template 版本号。

Session Resource

字段类型必返说明
idstring是sesr_ 前缀的 Session 资源 ID。
typestring是资源类型,当前固定为 file。
file_idstring是挂载的 File ID。
mount_pathstring是文件在 Agent 容器内的实际挂载路径。
created_atstring是资源创建时间,RFC 3339 格式。
updated_atstring是资源更新时间,RFC 3339 格式。

Session stats

stats 返回时包含以下字段。时长为整数秒;CAS 返回小数时直接截断小数部分。
字段类型必返说明
active_secondsintegerstats 返回时是活跃处理时长,单位秒;新 Session 通常为 0。
duration_secondsintegerstats 返回时是Session 持续时长,单位秒;新 Session 通常为 0。
usage 内各字段独立可选。数据源未返回时省略对应字段,显式零值返回 0。

Session budget

budget 是 Session 生命周期内的累计 Credit 上限,包含模型与 Sandbox 消耗。未设置或已清除上限时,Session 对象省略该字段。
字段类型必填说明
typestring是固定为 limit。
max_credit_coststring是正十进制金额字符串,最多 12 位整数和 2 位小数,范围 0.01–999999999999.99。允许 "100"、"100.0"、"100.00";不接受 JSON 数值、零、负数、科学计数法、前导零或空白。
对象只接受上表中的字段。创建和更新 Session 时,可将 budget 与 title、metadata、config 一起提交。请求和事件中的取值含义如下:
场景省略 budgetbudget: nullbudget 对象
创建 Session不设上限不设上限设置累计消费上限。
更新 Session保留原预算清除上限整体替换累计消费上限,新值必须严格大于已消费累计 Credit。
session.updated 事件未提供预算变更,保留已知预算表示清除上限表示设置后的预算上限。
预算按运行时记录的精确累计用量校验。累计消费达到或超过上限时,启动新一轮执行的请求返回 HTTP 400;已启动的执行可以继续,因此最终消费可能超过上限。调高或清除上限不会重置累计消费,也不会自动重放被拒绝的消息。 仅更新配置、同步 Template / Identity Config 或归档 Session,均不会清除预算。已归档 Session 的详情仍返回已设置的预算;列表中运行时数据不可用的条目可能省略该字段,此时不能据此判断是否设置过预算。

Outcome evaluation

outcome_evaluations 每项包含以下字段:
字段类型可为 null说明
typestring否评估类型。
outcome_idstring否Outcome ID。
descriptionstring否Outcome 描述。
iterationnumber否当前评估轮次。
resultstring否评估结果。
explanationstring是结果说明。
completed_atstring是完成时间。
返回值不包含 grader turn、评估标准或单轮用量等内部字段。

Thread 对象

Thread 表示 Session 运行时中的一个执行分支。列出、获取和归档 Thread 接口都会返回该对象。
{
  "id": "sthr_child_xxx",
  "type": "session_thread",
  "session_id": "sess_xxx",
  "parent_thread_id": "sthr_coordinator_xxx",
  "template_id": "tmpl_worker",
  "name": "research",
  "role": "child",
  "status": "idle",
  "stop_reason": { "type": "end_turn" },
  "created_by_tool_use_id": "toolu_xxx",
  "stats": {
    "active_seconds": 20,
    "duration_seconds": 300,
    "startup_seconds": 2
  },
  "usage": {
    "total_credits": 1.25
  },
  "created_at": "2026-06-22T11:00:00Z",
  "updated_at": "2026-06-22T11:05:00Z"
}
字段类型必返说明
idstring是sthr_ 前缀的 Thread ID。
typestring是固定为 "session_thread"。
session_idstring是Thread 所属 Session ID。
parent_thread_idstring否父 Thread ID;coordinator Thread 不返回该字段。
template_idstring否运行时 Agent 能可靠映射到父 Session 的 Forward Template 时返回。
namestring否Thread 的公开名称。
rolestring是Thread 角色:coordinator 或 child。
statusstring是未归档时为 idle、running、rescheduling 或 terminated 等运行状态;archived_at 非空时归一为 archived。
stop_reasonobject否Thread 停止原因。
created_by_tool_use_idstring否创建 child Thread 的 tool use ID。
statsobject否Thread 运行时统计。
stats.active_secondsintegerstats 返回时是活跃处理时长,单位秒。
stats.duration_secondsintegerstats 返回时是Thread 持续时长,单位秒。
stats.startup_secondsinteger否Thread 启动时长,单位秒。
usageobject否Thread 用量信息。
usage.total_creditsnumber否Thread 累计 Credit 消耗。
archived_atstring否归档时间,RFC 3339 格式;未归档时省略。
created_atstring否创建时间,RFC 3339 格式。
updated_atstring否最近更新时间,RFC 3339 格式。
Thread 时长为整数秒,小数部分直接截断。缺失的 startup_seconds 和 total_credits 会省略,显式零值保留。Thread 不返回 credits、model_credits 或 sandbox_runtime_credits。 Thread 响应不会暴露 CAS Agent ID、Agent 对象、Agent Version 或 Template Version。

Event 对象

接口返回的 Event 是按 type 变化的 JSON 对象。所有返回 Event 都包含通用字段,不同事件类型会携带不同的 payload 字段。
{
  "id": "evt_xxx",
  "type": "agent.message",
  "session_id": "sess_xxx",
  "content": [
    {
      "type": "text",
      "text": "这是分析结果。"
    }
  ],
  "processed_at": "2026-06-22T11:00:03Z"
}
字段类型必返说明
idstring是evt_ 前缀的 Event ID。
typestring是Event 类型。
session_idstring是Event 所属 Session ID。
session_thread_idstring否Thread lifecycle Event 描述的 Thread ID。
processed_atstring否事件被处理的时间,RFC 3339 格式。部分 agent 生成事件或增量事件可能不包含该字段。
按事件类型允许出现的 payload 字段如下。表中不重复列出通用字段 id、type、session_id、session_thread_id 和 processed_at。
Event 类型允许字段
user.messagecontent
user.interrupt无
user.tool_confirmationtool_use_id、result、deny_message
user.tool_resulttool_use_id、content、is_error
user.custom_tool_resultcustom_tool_use_id、content、is_error
user.define_outcomedescription、rubric、outcome_id、max_iterations
agent.messagecontent
agent.thinkingthinking、text
agent.message_startmessage_id、message
agent.content_block_startmessage_id、index、content_block
agent.content_block_deltamessage_id、index、delta
agent.content_block_stopmessage_id、index
agent.message_deltamessage_id、delta、usage
agent.message_stopmessage_id
event_startevent
event_deltaevent_id、delta
agent.tool_usename、input、evaluated_permission、evaluation
agent.tool_resulttool_use_id、content、is_error
agent.custom_tool_usename、input
agent.mcp_tool_usemcp_server_name、name、input、evaluated_permission、evaluation
agent.mcp_tool_resultmcp_tool_use_id、content、is_error
agent.artifact_deliveredfile_id、original_filename、size、content_type
session.status_runningreason(可选)
session.status_idlestop_reason、reason(可选)
session.status_terminated无
session.thread_createdsession_thread_id
session.thread_status_runningsession_thread_id
session.thread_status_idlesession_thread_id
session.thread_status_rescheduledsession_thread_id
session.thread_status_terminatedsession_thread_id
session.errorerror
session.updatedagent、metadata、title、budget
session.usagemodel_credits、sandbox_runtime_credits、total_credits
span.model_request_endis_error、model_request_start_id、model_usage
span.outcome_evaluation_startiteration、outcome_id
span.outcome_evaluation_ongoingiteration、outcome_id
span.outcome_evaluation_endexplanation、iteration、outcome_evaluation_start_id、outcome_id、result、usage

evaluation

evaluation 是 agent.tool_use、agent.mcp_tool_use 的可选审批详情,与顶层审批结果字符串 evaluated_permission 可以同时返回。未执行策略评估时可能省略。
字段类型说明
evaluation.typestring审批策略来源:always_allow、always_ask 或 auto。
evaluation.evaluated_permissionobjectauto 策略的详细判定。
evaluation.evaluated_permission.typestring自动审批结果:allow、ask 或 deny。
evaluation.evaluated_permission.reason_codestring可选;indeterminate 表示无法确定、需要确认,high_risk 表示高风险拒绝。
策略 / 结果evaluation 示例
总是允许{"type":"always_allow"}
总是询问{"type":"always_ask"}
自动允许{"type":"auto","evaluated_permission":{"type":"allow"}}
自动审批无法确定{"type":"auto","evaluated_permission":{"type":"ask","reason_code":"indeterminate"}}
自动审批高风险拒绝{"type":"auto","evaluated_permission":{"type":"deny","reason_code":"high_risk"}}
拒绝原因以实际返回的 reason_code 为准。
{
  "id": "evt_tool_xxx",
  "type": "agent.tool_use",
  "session_id": "sess_xxx",
  "name": "Bash",
  "input": {"command": "pwd"},
  "evaluated_permission": "allow",
  "evaluation": {"type": "always_allow"}
}

客户端可发送事件类型

POST /api/v1/forward/sessions/{session_id}/events 只接受以下事件类型。
类型必填字段说明
user.messagecontent用户消息。content 必须是非空 content block 数组,仅支持 text、image 类型。
user.interrupt无请求中断当前处理。
user.tool_confirmationtool_use_id、result工具调用确认。result 为 allow 或 deny;拒绝时可传 deny_message。
user.tool_resulttool_use_id返回内置工具结果;content 和 is_error 可选。
user.custom_tool_resultcustom_tool_use_id返回客户端自定义工具结果;content 和 is_error 可选。
user.define_outcomedescription、rubric定义期望结果和评判标准;max_iterations 可选。

公开事件类型

查询历史和订阅 SSE 事件流时,可能收到以下公开事件类型;其中 event_start 和 event_delta 仅在订阅 SSE 且传入 event_deltas[] 时可能返回: user.message、user.interrupt、user.tool_confirmation、user.tool_result、user.custom_tool_result、user.define_outcome、agent.message、agent.thinking、agent.message_start、agent.content_block_start、agent.content_block_delta、agent.content_block_stop、agent.message_delta、agent.message_stop、event_start、event_delta、agent.tool_use、agent.tool_result、agent.custom_tool_use、agent.mcp_tool_use、agent.mcp_tool_result、agent.artifact_delivered、session.status_running、session.status_idle、session.status_terminated、session.thread_created、session.thread_status_running、session.thread_status_idle、session.thread_status_rescheduled、session.thread_status_terminated、session.error、session.updated、session.usage、span.model_request_end、span.outcome_evaluation_start、span.outcome_evaluation_ongoing 和 span.outcome_evaluation_end。

模型用量事件

一次模型调用完成后,事件流会输出 span.model_request_end 事件,携带本次模型调用的用量信息:
{
  "id": "evt_xxx",
  "type": "span.model_request_end",
  "is_error": false,
  "model_request_start_id": "evt_yyy",
  "model_usage": {
    "credits": 0.42
  },
  "processed_at": "2026-06-22T11:00:01Z"
}
字段类型说明
is_errorboolean本次模型请求是否因错误或取消而结束。
model_request_start_idstring对应的模型请求开始事件的 Event ID。
model_usageobject本次模型调用的用量对象。
model_usage.creditsnumber本次模型调用消耗的 credits。
model_usage.credits 是单次调用增量,不是 Session 累计值。消费端可按 Event ID 去重后,将其累加到该 Session 的模型用量记录中;Session 累计用量见下方 session.usage 事件,也可通过获取 Session 接口读取 usage.total_credits 校准事件累加结果。

Session 用量事件

事件流会输出 session.usage 事件,携带该 Session 截至当前的累计 Credit 消耗:
{
  "id": "evt_xxx",
  "type": "session.usage",
  "model_credits": 0.68,
  "sandbox_runtime_credits": 0.04,
  "total_credits": 0.72,
  "processed_at": "2026-10-26T07:19:02.87752Z"
}
字段类型说明
model_creditsnumberSession 累计模型消耗的 Credit。
sandbox_runtime_creditsnumberSession 累计 Sandbox 运行时消耗的 Credit。
total_creditsnumberSession 累计 Credit 消耗。
session.usage 的字段是累计值,含义与获取 Session 接口返回的 usage.model_credits、usage.sandbox_runtime_credits、usage.total_credits 一致;消费端以最新一条事件为准,不要累加。

Outcome evaluation 事件

Outcome 评估过程会返回以下公开事件:
Event 类型payload 字段
span.outcome_evaluation_startiteration、outcome_id
span.outcome_evaluation_ongoingiteration、outcome_id
span.outcome_evaluation_endexplanation、iteration、outcome_evaluation_start_id、outcome_id、result、usage
session.status_running、session.status_idle 可携带 reason="outcome_evaluation",表示状态变化来自 Outcome 评估阶段;reason 与 idle 的 stop_reason 可以同时返回。该字段可省略,不表示评估结果,也不保证每次评估都出现;评估结果以 span.outcome_evaluation_end 或 Session 的 outcome_evaluations 为准。其他评估过程的内部字段不会返回。

增量流式事件

流式增量事件通过订阅 Session Event Stream 接口的 event_deltas[] 查询参数开启。支持重复传参,允许值如下:
event_deltas[] 取值说明
agent.message订阅 assistant 文本消息的增量内容。
agent.thinking订阅 thinking 的增量内容。该订阅为 Beta 功能,请求需同时携带 X-Qoder-Beta: thinking-event-stream-delta-2026-07-20 请求头,详见订阅 Session Event Stream。
开启后,SSE 事件流中可能额外返回以下两类顶层 Event:
Event 类型关键字段说明
event_startevent表示某个公开事件开始生成。event 中只保留 id、type、name、mcp_server_name。
event_deltaevent_id、delta表示某个公开事件的增量片段。event_id 指向对应的事件。
event_start.event 字段:
字段类型说明
idstring对应事件的 Event ID。
typestring对应事件的公开 Event 类型,当前为 agent.message 或 agent.thinking。
namestring预留字段;当前 event_deltas[] 不支持工具调用类 selector,通常不会返回。
mcp_server_namestring预留字段;当前 event_deltas[] 不支持 MCP 工具调用类 selector,通常不会返回。
event_delta.delta 字段:
字段类型说明
typestring增量类型,例如 content_delta。
indexintegercontent block 下标。
contentobject增量内容。当前只透出 type 和 text。
content.typestring内容类型,例如 text 或 thinking。
content.textstring本次增量文本片段。
event_start 示例:
{
  "id": "evt_xxx",
  "type": "event_start",
  "session_id": "sess_xxx",
  "event": {
    "id": "evt_xxx",
    "type": "agent.message"
  }
}
event_delta 示例:
{
  "id": "evt_xxx",
  "type": "event_delta",
  "session_id": "sess_xxx",
  "event_id": "evt_xxx",
  "delta": {
    "type": "content_delta",
    "index": 0,
    "content": {
      "type": "text",
      "text": "这是"
    }
  }
}
流式增量事件解析约定:
  • 只有订阅 SSE 事件流且传入 event_deltas[] 时,才会返回 event_start / event_delta;历史查询不返回这类流式增量事件。
  • 最终完整公开事件仍会返回。客户端可使用流式增量事件做即时展示,再以最终完整事件作为持久化或展示校准结果。
  • include_thinking=false 时,会过滤 agent.thinking 事件开始信号和 delta.content.type=thinking 的增量片段。
  • include_tool_calls=false 不影响 event_deltas[] 当前支持的 agent.message 和 agent.thinking 流式增量事件,但仍会过滤普通工具调用事件和旧版工具输入/输出 delta。

旧版增量流式事件数据结构

为兼容既有客户端,事件流和历史查询仍可能返回旧版增量事件。由创建 Session 时的 incremental_streaming_enabled 字段控制。新接入不建议依赖这些事件,最终完整的 agent.message 仍会返回。 旧版顶层增量事件类型如下:
事件类型关键字段说明
agent.message_startmessage_id、message开始一条 assistant message。
agent.content_block_startmessage_id、index、content_block开始一个 content block,例如 text、thinking 或 tool use。
agent.content_block_deltamessage_id、index、delta承载 index 对应 content block 的增量片段。
agent.content_block_stopmessage_id、index结束 index 对应 content block。
agent.message_deltamessage_id、delta、usage承载 message 级增量,例如 stop_reason、stop_sequence 或用量信息。
agent.message_stopmessage_id结束一条 assistant message。
text_delta、thinking_delta、signature_delta、input_json_delta 和 tool_output_delta 不是顶层 Event 类型,只会作为 agent.content_block_delta.delta.type 出现。
delta.type字段说明
text_deltatext文本输出片段,客户端可追加 delta.text 重建文本。
thinking_deltathinking模型或 provider 输出 thinking 时的思考片段。
signature_deltasignaturethinking block 的签名片段,存在时透出。
input_json_deltapartial_json工具入参 JSON 片段。
tool_output_deltavaries预留给未来的工具输出流式;当前仍以完整 agent.tool_result 为准。
agent.content_block_delta 示例:
{
  "id": "evt_delta_xxx",
  "type": "agent.content_block_delta",
  "session_id": "sess_xxx",
  "message_id": "msg_xxx",
  "index": 0,
  "delta": {
    "type": "text_delta",
    "text": "这是"
  },
  "processed_at": "2026-06-22T11:00:01Z"
}
旧版增量事件解析约定:
  • SSE event: 与 JSON data.type 都使用公开 Event 类型。
  • agent.content_block_delta.index 用于区分多个 content block。
  • processed_at 在增量事件上可能缺失,客户端应按可选字段处理。
  • 网络中断后可使用 Last-Event-ID 携带最后收到的 Event ID 重连。
  • include_thinking=false 时,会过滤 thinking_delta、signature_delta 及可识别的 thinking content block start/stop 事件。
  • include_tool_calls=false 时,会过滤 input_json_delta、tool_output_delta 及可识别的 tool content block start/stop 事件。