Skip to main content
决策（Beta）

创建 Decision

基于自定义上下文（state）或 Session 的近期上下文，同步执行一次结构化判断。

Decision API 目前为 Beta 功能，接口定义、响应结构和行为可能在后续版本中调整。请关注文档更新，并在生产环境使用前完成兼容性验证。
POST /api/v1/forward/decisions

请求头

Header是否必填说明
Authorization是Bearer <PAT 或 SAT>，支持管理员和 Identity 级 SAT。
Content-Type是application/json。
Idempotency-Key否同一次逻辑操作重试时复用原值。去除首尾空白后为 1～256 字节，不含控制字符，不能重复传入。
当前无需额外的 Beta 请求头。本接口不接受查询参数。

请求体参数

参数类型是否必填说明
stateobject与 session_id 二选一用于判断的自定义上下文，以非空 JSON 对象传入，可包含文本、结构化数据等；顶层 state.session_context 为保留字段，不能传入。
session_idstring与 state 二选一当前认证范围内可访问且未归档的 Session ID，1～256 字节，无首尾空白、控制字符及 /、\、?、#。
questionsarray是需要判断的问题列表。
state 与 session_id 必须且只能出现一个；传 null 不等同于省略。字段名区分大小写；不支持 model、identity_id 等额外协议字段。

问题结构

参数类型是否必填说明
typestring是choice 或 score。
namestring否问题名称，传入时必须非空且在本次请求中唯一，最多 128 字节，不含控制字符。
instructionsstring是非空判断说明，描述判断目标及规则。
choicesarraychoice 必填2～32 个候选项；score 问题不能包含此字段。
choices[].valuestring 或 boolean是候选值，字符串必须非空，同题候选值不能重复；不支持数字或 null。
choices[].descriptionstring否候选项的含义或选择条件。
levelsarrayscore 必填2～32 个评分等级；choice 问题不能包含此字段。
levels[].labelstring是非空等级名称。
levels[].scorenumber是等级对应的有限数值，可为整数或小数。
levels[].descriptionstring否该等级的判定标准。

输入限制

  • 请求体为单个 UTF-8 JSON 对象，不超过 1 MiB。
  • JSON 嵌套深度不超过 16，每个对象或数组不超过 1,000 项；不允许重复 JSON 键。
  • 数值必须在有限双精度浮点数范围内；字符串不能含 NUL 等控制字符，文本内容允许换行、回车和制表符。
  • state 内可使用业务自定义字段；请求、问题、选项和评分等级的协议结构只接受上表列出的字段。
  • 上下文处理及预算规则见输入方式。

示例请求

根据自定义上下文判断

为同一次操作生成一次 key，后续重试保持 key 和请求体原始内容不变： 
IDEMPOTENCY_KEY="$(uuidgen)"

curl --silent --show-error --fail-with-body -X POST \
  "https://api.qoder.com/api/v1/forward/decisions" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "state": {"message": "My issue is resolved."},
    "questions": [{
      "type": "choice",
      "name": "resolved",
      "instructions": "Has the user confirmed resolution?",
      "choices": [{"value": true}, {"value": false}]
    }]
  }'

根据 Session 上下文评分

curl --silent --show-error --fail-with-body -X POST \
  "https://api.qoder.com/api/v1/forward/decisions" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_xxx",
    "questions": [{
      "type": "score",
      "name": "completion",
      "instructions": "Evaluate how completely the user request has been fulfilled.",
      "levels": [
        {"label": "Incomplete", "score": 0, "description": "The requested result is missing."},
        {"label": "Partial", "score": 0.5, "description": "Only part of the request is fulfilled."},
        {"label": "Complete", "score": 1, "description": "All requested results are provided."}
      ]
    }]
  }'

示例响应

HTTP 200 OK（自定义上下文示例） 
{
  "id": "dec_xxx",
  "session_id": null,
  "source": "api",
  "status": "completed",
  "questions": [{
    "type": "choice",
    "name": "resolved",
    "instructions": "Has the user confirmed resolution?",
    "choices": [{"value": true}, {"value": false}]
  }],
  "answers": [{"type": "choice", "name": "resolved", "value": true}],
  "context": {
    "mode": "state"
  },
  "error": null,
  "created_at": "2026-10-26T10:00:00Z",
  "completed_at": "2026-10-26T10:00:02Z"
}
完整字段见 Decision 对象。选择题返回 type: choice 和 value，评分题返回 type: score 和 score。status: completed 表示判断已完成，业务目标是否达成应根据答案确定。

幂等重试

  • 幂等 key 在当前认证范围内生效。重试应保持相同认证范围、key 和请求体原始字节；即使 JSON 含义相同，改变字段顺序或空白也会被视为不同请求体。
  • 相同 key 和相同请求体：已成功时返回原 Decision；已失败时返回原失败错误；均不会重新执行判断。
  • 原请求仍在执行时，返回 409 decision_in_progress，错误中包含 decision_id，可稍后查询详情。
  • 同一 key 对应不同请求体时，返回 409 idempotency_key_reused。
  • 需要发起一次新的判断（包括基于 Session 的最新上下文重新判断）时使用新 key。复用 key 不会重新读取历史或更新原结果。
记录有保留期限，幂等重放不能作为永久去重存储。业务需要长期保存结果时，应自行保存 Decision ID 和所需结果。

错误

HTTPCode触发条件
400invalid_decision_input输入模式、问题、选项、评分等级或幂等 key 无效，JSON 重复键、结构限制超限或存在未知协议字段。
400—传入查询参数、重复幂等 Header 或空幂等 Header。
401—凭证缺失、无效或已过期。
403—当前凭证缺少所需访问权限或 Workspace 配置不满足要求。
404—Session 不存在、不可访问、已归档，或其 Identity 已禁用、已删除。
409idempotency_key_reused同一 key 对应不同请求体。
409decision_in_progress相同 key 对应的判断仍在执行。
413—请求体超过 1 MiB。
422decision_context_too_large判断输入超过预算，或模型服务拒绝输入大小。
422decision_context_unavailableSession 没有可用的判断上下文。
402decision_quota_exhausted判断额度耗尽或受限。
429decision_rate_limited判断服务限流；有 Retry-After 时按其值等待。
499decision_cancelled判断请求被取消，断开的客户端可能无法收到此响应。
500decision_internal_error 或无 Code服务内部错误。
502decision_context_read_failedSession 历史读取失败或返回结构无效。
502decision_invalid_upstream_response、decision_upstream_error判断服务返回无效结果或发生其他上游错误。
503decision_upstream_unavailable 或无 Code当前调用方或环境的判断能力暂不可用。
504decision_timeout判断超过执行时限。

HTTP 错误响应

请求已被接受并生成记录后，执行失败的错误响应通常携带 error.decision_id。参数校验或鉴权等接受前错误不生成 Decision。 
{
  "type": "error",
  "request_id": "req_xxx",
  "error": {
    "type": "api_error",
    "code": "decision_timeout",
    "message": "Decision deadline exceeded.",
    "decision_id": "dec_xxx"
  }
}
request_id 可用时返回，用于排查请求；error.type 为错误大类，error.code 为可选业务错误码。入口鉴权错误可能采用不同的响应结构。 可用 error.decision_id 查询记录。详情接口查询到失败记录时返回 HTTP 200，记录的 status 为 failed；创建接口的失败则返回对应的非 2xx HTTP 状态。

相关