Decisions API 文档与接入指南

landing.docs.overview.eyebrow

面向应用决策的 API 契约

向 System One 接口提交一份 state 和一组类型化问题。Decisions API 按问题 ID 返回答案，并为支持的答案类型提供概率信息，方便服务端校验和处理。

landing.docs.overview.typed

landing.docs.overview.parallel

landing.docs.overview.confidence

快速开始

端到端完成一次决策请求

从 Playground 开始最容易理解 Decisions API 的输入与输出。确认问题定义合理后，再创建 API key 接入产品。

1
landing.docs.quickstart.one.title
打开 Playground，选择接近真实需求的客服、运维或规则判断场景。
2
landing.docs.quickstart.two.title
只提供判断所需的上下文。简短消息可用文本；需要结合账户和规则时使用 JSON。
3
landing.docs.quickstart.three.title
为每个问题设置 ID，并选择 Choice、Score 或 Noul；同一请求中的问题共用一份 state。
4
landing.docs.quickstart.four.title
创建 API key，从服务端发送请求。将返回结果用于应用动作前，先检查字段和类型。

输入

围绕判断需求整理 state

State 是一次请求中所有问题共享的上下文。仅保留完成判断所需的事件、记录和规则信息，避免传入无关的个人或账户数据。

text

一段自然语言、工单或消息

object

结构化记录与嵌套字段

array

多段文本组成的上下文

当前输入边界：Decisions API 接受文本、JSON 对象和文本数组，暂不支持图片、音频和视频。

问题类型

定义代码可处理的答案范围

每个问题对应应用需要的一项判断。有限动作选项使用 Choice，有序评分标准使用 Score，真假判断使用 Noul；多个问题可以共用一份 state。

类型适用场景返回字段

Choice

从选项中分类或路由choice · probabilities · confidence

Score

按量表对状态评分score · legend · probabilities · confidence

Noul

判断一个陈述是否为真noul（yes 概率）

通用字段与结构

Question 是三种问题类型之一，所有类型都包含 type 和 instructions，并根据类型添加 criteria。instructions 可以是字符串、对象或数组；当问题需要额外上下文时，可以把问题和数据放进结构化对象中，并用字段名引用数据。

type

必填：noul、choice 或 score。

instructions

必填：字符串、对象或数组，描述模型需要做的判断。

criteria

按问题类型决定格式：Noul 可选对象；Choice 必填 map；Score 必填数组。

{
  "type": "noul",
  "instructions": "这个消息是否表达了紧迫性？",
  "criteria": {
    "true": "明确表示需要立即处理",
    "false": "没有表达紧迫性"
  }
}

结构化 instructions 适合较长的问题或需要引用额外数据的场景：把问题放在一个字段，把上下文放在其他字段，并使用字段名引用它们。

"instructions": {
  "potential_duplicate": {
    "name": "John Smith",
    "location": "Oakland, California",
    "last_employer": "Google"
  },
  "question": "这份简历是否属于与 `potential_duplicate` 相同的人？"
}

Choice

Choice 用于从预先定义的选项中选择一个答案。type 必须是 choice，instructions 是要做出的判断，criteria 必须是选项到说明的 map；选项最多 255 个，说明可以是字符串、对象、数组或 null。

{
  "state": "4.8.1 版本发布后，us-east-1 区域的结账错误明显增加，剩余错误预算已接近耗尽。",
  "model": "jev-latest",
  "questions": {
    "rollout_action": {
      "type": "choice",
      "instructions": "What should the on-call team do next?",
      "criteria": {
        "pause_rollout": "Stop additional traffic",
        "rollback": "Return to the previous version",
        "monitor": "Continue while watching metrics"
      }
    }
  }
}

Score

Score 用于有序的描述性等级，例如严重程度或满意度。type 必须是 score，instructions 描述要评分的内容，criteria 是按从低到高排列的数组，每项可以是字符串、对象或数组，至少 2 个、最多 10 个等级；返回值是概率加权后的分数，因此可能落在两个等级之间。

{
  "state": "4.8.1 版本发布后，us-east-1 区域的结账错误明显增加，剩余错误预算已接近耗尽。",
  "model": "jev-latest",
  "questions": {
    "impact": {
      "type": "score",
      "instructions": "How severe is the customer impact?",
      "criteria": [
        "Limited",
        "Elevated",
        "Critical"
      ]
    }
  }
}

Noul

Noul 用于 yes / no 判断。type 必须是 noul，instructions 是待评估的问题；criteria 可选，用 true 和 false 分别描述 yes 与 no 的含义，每个值可以是字符串、对象或数组。返回的 noul 是答案为 yes 的概率，不是另一个 confidence 字段。

{
  "state": "4.8.1 版本发布后，us-east-1 区域的结账错误明显增加，剩余错误预算已接近耗尽。",
  "model": "jev-latest",
  "questions": {
    "pause_rollout": {
      "type": "noul",
      "instructions": "是否应暂停本次发布并升级复核？",
      "criteria": {
        "true": "The release is causing material customer impact and should stop",
        "false": "Evidence does not support stopping the rollout"
      }
    }
  }
}

输出

执行动作前校验响应

按问题 ID 对照响应条目和预期类型。概率和置信度可帮助分流不确定案例，但不是保证；请根据自己的阈值和复核规则处理。

answers： Choice 返回选择、概率和 confidence；Score 返回 score、legend、各等级概率和 confidence；Noul 返回 noul。
usage： 包含 input_tokens 和 output_tokens，部分响应还会提供美元计价的 cost。
elapsedMs： 从发送请求到收到结果的耗时，包含校验，不等同于纯模型推理时间。

概率与置信度是自动化决策的信号，不是业务正确率的保证。高风险动作应设置更高阈值或转人工。

响应字段

model执行本次评估的模型；本项目响应会在 result 中返回答案和用量。

answers按请求中的同名 question ID 返回一个 Answer。

usage包含 input_tokens 和 output_tokens。

elapsed本项目接口额外返回的请求耗时，单位为毫秒。

响应示例

{
  "model": "jev-1.13.0",
  "answers": {
    "pause_rollout": {
      "type": "noul",
      "noul": 0.91
    }
  },
  "usage": {
    "input_tokens": 183,
    "output_tokens": 24
  }
}

答案类型

每个答案的 type 都与对应问题一致。Choice 和 Score 还会返回 0 到 1 之间的 confidence，它来自答案的概率分布。

Choice

返回概率最高的 choice、所有选项的 probabilities，以及由概率分布计算出的 confidence。

type

必填，值为 choice。

choice

必填，string；概率最高的选项。

probabilities

必填，map<string, number>；所有选项的概率之和为 1。

confidence

必填，number；根据概率分布计算出的确定程度。

{
  "model": "jev-1.13.0",
  "answers": {
    "rollout_action": {
      "type": "choice",
      "choice": "pause_rollout",
      "probabilities": {
        "pause_rollout": 0.91,
        "rollback": 0.07,
        "monitor": 0.02
      },
      "confidence": 0.84
    }
  },
  "usage": {
    "input_tokens": 221,
    "output_tokens": 31
  }
}

Score

返回概率加权后的 score、等级说明 legend、各等级 probabilities，以及 confidence。score 可以落在两个等级之间。

type

必填，值为 score。

score

必填，number；按各等级概率加权后的分数。

legend

必填，map<string, string>；把等级编号映射回等级说明。

probabilities

必填，map<string, number>；每个等级编号及其概率之和为 1。

confidence

必填，number；根据概率分布计算出的确定程度。

{
  "model": "jev-1.13.0",
  "answers": {
    "impact": {
      "type": "score",
      "score": 1.16,
      "legend": {
        "0": "轻微",
        "1": "明显",
        "2": "严重"
      },
      "probabilities": {
        "0": 0.02,
        "1": 0.8,
        "2": 0.18
      },
      "confidence": 0.79
    }
  },
  "usage": {
    "input_tokens": 214,
    "output_tokens": 28
  }
}

Noul

返回 noul，范围是 0 到 1，表示 yes 的概率。

type

必填，值为 noul。

noul

必填，number；0 表示 no，1 表示 yes。

{
  "model": "jev-1.13.0",
  "answers": {
    "pause_rollout": {
      "type": "noul",
      "noul": 0.91
    }
  },
  "usage": {
    "input_tokens": 183,
    "output_tokens": 24
  }
}

usage 详细字段

input_tokens

integer · 本次请求消耗的输入 token 数量。

output_tokens

integer · 本次请求生成的输出 token 数量。

API 参考

从服务端发送 API 请求

在后端使用 Bearer API key 调用 Decisions API System One 接口。密钥不要放入浏览器代码；接入生产动作前应校验输入并处理非成功 HTTP 响应。

评估接口

POST https://decisions-api.pro/v1/systemone

请求需要携带 Authorization Bearer API key，以及 application/json 内容类型。

Authorization: Bearer <API_KEY>
Content-Type: application/json

请求体

每次请求都需要以下三个顶层字段。questions 是一个 map，键名由你定义，返回答案时会沿用这些键名。

statestring | object | array · 必填：要评估的文本或结构化数据。

modelstring · 必填：处理请求的模型。使用已配置的模型别名 jev-latest。

questionsmap<string, Question> · 必填：要并行评估的问题集合。

questions 中的每个键由你选择；对应的 Answer 会使用同一个 ID 返回。这个键不会发送给底层模型，也不会参与推理。

请求示例

curl -X POST https://decisions-api.pro/v1/systemone \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "state": "4.8.1 版本发布后，us-east-1 区域的结账错误明显增加，剩余错误预算已接近耗尽。",
  "model": "jev-latest",
  "questions": {
    "pause_rollout": {
      "type": "noul",
      "instructions": "是否应暂停本次发布并升级复核？",
      "criteria": {
        "true": "The release is causing material customer impact and should stop",
        "false": "Evidence does not support stopping the rollout"
      }
    }
  }
}'

请求体示例

{
  "state": "4.8.1 版本发布后，us-east-1 区域的结账错误明显增加，剩余错误预算已接近耗尽。",
  "model": "jev-latest",
  "questions": {
    "pause_rollout": {
      "type": "noul",
      "instructions": "是否应暂停本次发布并升级复核？",
      "criteria": {
        "true": "The release is causing material customer impact and should stop",
        "false": "Evidence does not support stopping the rollout"
      }
    }
  }
}

请把 API key 保存在服务端环境变量中，不要写入浏览器代码或提交到版本库。请求字段、问题类型、响应结构、错误码和重试方式已在本页列出。

创建 API key

Agent 使用

在编码 Agent 中使用 Decisions API

在兼容的编程 Agent 中调用 Decisions API，为边界清晰的判断获取结构化结果；执行与权限仍由应用控制。

配置 API

创建 API key，并在服务端环境中配置 Decisions API 接口地址。

一次配置

将密钥放在服务端环境变量中，仅注入负责发送请求的服务。

提出边界清晰的问题

告诉 Agent 需要判断什么；它应该选择 Choice、Score 或 Noul，并只发送完成判断所需的最小 state。

配置 API

export DECISIONS_API_KEY="sk_your_key_here"
export DECISIONS_API_BASE_URL="https://decisions-api.pro"

仅在服务端保存 key。不要将密钥放入浏览器代码、版本库或公开的 Agent 提示词。

五个实用起点

将这些提示词用于自己的 API 集成。每个问题都有明确边界，执行权限仍由应用控制。

路由客服工单

使用 Choice 选择一个允许的处理团队，再由业务代码路由工单，并把不确定的情况交给人工复核。

使用 Decisions API。请把这张客服工单准确分类到 billing、technical、account 或 sales 其中一个团队。返回选择结果、概率和 confidence。暂时不要联系客户，也不要修改工单。

工单：我的年度套餐被重复扣款了，我需要退款。

保护工具调用

使用 Noul 判断一个待执行动作是否需要人工批准，同时仍由确定性权限和业务政策负责最终放行。

使用 Decisions API，在执行下面的工具调用前判断是否可以不经过人工批准。考虑副作用、可逆性、范围和政策。如果有风险或不确定，不要执行。

工具：delete_customer_records
参数：{where: last_login < 2023-01-01}
政策：破坏性数据库操作必须先备份并获得人工批准。

选择允许的模型

对允许列表中的候选模型使用 Choice；如果没有合适候选，再用单独的 Noul 判断是否升级。

通过 Decisions API 判断为这个任务选择一个已批准的模型。优先考虑质量，再考虑上下文容量和成本。返回选择结果、概率，以及是否需要升级。暂时不要调用任何模型。

任务：审查一份 100k token 的客户争议。
候选：fast-model（32k、低成本）、reasoning-model（200k、高成本）、fallback-model（128k、中等成本）。

验证研究证据

在 Agent 发布或引用结论前，使用 Noul 判断现有证据是否足够支持该主张。

通过 Decisions API 判断判断下面的证据是否足以发布这个主张。考虑来源质量、时效性、直接支持程度和矛盾证据。返回 yes 概率以及还缺少的验证工作。暂时不要发布。

主张：我们的 API 将处理耗时中位数降低了 40%。
证据：上月对 120 个案例做的内部基准测试；没有生产流量数据；一份旧报告显示提升了 12%。

检查任务是否完成

在向用户报告成功前，使用 Choice 或 Score 判断工作是已完成、需要继续验证，还是仍未完成。

通过 Decisions API 判断检查这个任务是否真的完成。返回 complete、verify_more 或 incomplete 之一。考虑目标、修改的文件、运行的测试、已知缺口，以及是否在目标环境验证过。

目标：为生产接口增加 API key 鉴权。
已完成：增加了 Authorization 检查和 API key 查询。
验证：单元测试通过；生产请求和限流行为尚未测试。

Agent 可以在需要结构化判断时调用 Decisions API。接口不会创建工具、授予权限、拦截 Shell 调用，也不会替代你的权限系统、确定性规则或人工审批。

错误处理

错误码与重试

无效请求按客户端错误处理，缺少或错误密钥按鉴权失败处理；遇到速率限制或暂时过载时，使用有上限的指数退避重试。

状态码含义

401未授权：缺少或无效的 API key，请检查 Authorization header。

422无法处理：请求体校验失败，例如缺少必填字段或问题格式错误，响应内容会指出出错字段。

429请求过多：超过速率限制，请等待后重试。

529服务过载：服务暂时繁忙，请等待后重试。

收到 429 或 529 时，请使用指数退避重试，不要立即连续发送相同请求。使用 SDK 默认重试策略时，这些重试通常会由 SDK 自动处理。

下一步

先用一个低风险、边界清晰的判断验证输出，再逐步接入路由、队列、guardrail 或 agent 工作流。

查看方案与用量联系支持

Decisions API 文档与接入指南

面向应用决策的 API 契约

端到端完成一次决策请求

landing.docs.quickstart.one.title

landing.docs.quickstart.two.title

landing.docs.quickstart.three.title

landing.docs.quickstart.four.title

围绕判断需求整理 state

定义代码可处理的答案范围

通用字段与结构

Choice

Score

Noul

执行动作前校验响应

响应字段

响应示例

答案类型

Choice

Score

Noul

usage 详细字段

从服务端发送 API 请求

评估接口

请求体

请求示例

请求体示例

在编码 Agent 中使用 Decisions API

配置 API

一次配置

提出边界清晰的问题

配置 API

五个实用起点

路由客服工单

保护工具调用

选择允许的模型

验证研究证据

检查任务是否完成

错误码与重试

下一步