根据自定义上下文（state）或 Session 的近期上下文回答结构化问题，用于判断任务是否完成、选择业务分支或按预设等级评分。
Decision API 目前为 Beta 功能，接口定义、响应结构和行为可能在后续版本中调整。请关注文档更新，并在生产环境使用前完成兼容性验证。
choice）和评分题（score）。创建接口同步执行判断并保存结果，之后可按 ID 查询或分页列出记录。
接口
| 方法 | 路径 | 说明 |
|---|---|---|
POST | /api/v1/forward/decisions | 创建 Decision |
GET | /api/v1/forward/decisions/{decision_id} | 获取 Decision |
GET | /api/v1/forward/decisions | 列出 Decisions |
选择输入方式
| 方式 | 适用场景 | 行为 |
|---|---|---|
state（自定义上下文） | 使用调用方提供的文本、结构化数据等作为判断依据。 | 传入非空 JSON 对象，不依赖 Session。 |
session_id | 判断某个 Session 的执行进展或结果。 | 服务端提取该 Session 的近期可用上下文。 |
user.message、agent.message、session.error 和 agent.artifact_delivered 事件中的相关信息，不会读取文件正文、工具调用过程或子线程历史。判断基于近期可用上下文，可能不包含完整会话历史。
输入过大时返回 422 decision_context_too_large，可精简上下文或问题后重试。Session 没有可用上下文时返回 422 decision_context_unavailable。
Decision 对象
创建成功、详情查询和列表中的记录共用以下结构。
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | Decision ID，前缀为 dec_。 |
| session_id | string 或 null | Session 输入时为关联的 Session ID；显式 state 输入时为 null。 |
| source | string | 当前固定为 api。 |
| status | string | running、completed 或 failed。 |
| questions | array | 此次判断的问题，结构见创建 Decision。 |
| answers | array | 按请求问题顺序返回的答案；尚未完成或失败时为 []。 |
| context | object | 输入模式和上下文范围，见下表。 |
| error | object 或 null | 失败时包含 code 和 message；其余情况为 null。 |
| created_at | string | 创建时间，RFC 3339。 |
| completed_at | string 或 null | 执行结束时间，RFC 3339；running 时为 null，成功或失败结束后返回时间。 |
state 或完整的 Session 输入快照。
答案结构
| type | 结果字段 | 说明 |
|---|---|---|
choice | value | 返回所选选项的原始字符串或布尔值，保留 JSON 类型。 |
score | score | 返回所选等级定义的数值分数，不是自由生成的连续分数。 |
name 时，对应答案也返回同名字段；省略时按数组位置对应。
Context 字段
以下字段按输入模式和执行进度返回；执行中或准备输入失败时，可能仅包含 mode。客户端应兼容可选字段缺失和后续新增字段。
| 字段 | 类型 | 说明 |
|---|---|---|
| mode | string | state 或 session。 |
| anchor_event_id | string | 本次读取时确定的最新候选事件 ID。 |
| first_event_id | string | 实际纳入判断的最早有效事件 ID。 |
| last_event_id | string | 实际纳入判断的最新有效事件 ID。 |
| included_segment_count | integer | 纳入的上下文片段数，仅 Session 模式返回。 |
| included_event_count | integer | 纳入的有效事件数，仅 Session 模式返回。 |
使用流程
- 准备
state或可访问的session_id，并定义问题和候选答案。 - 调用创建接口；建议为一次逻辑操作固定
Idempotency-Key，详见幂等重试。 - 按
answers[].type处理选择或评分结果。 - 保存 Decision ID，用详情或列表接口追踪结果。创建返回错误且携带
error.decision_id时，也可用该 ID 查询失败记录。