运行决策
POST /v1/decisions/{slug}——路径、查询参数、请求头、请求体、每个响应字段以及错误,附带 cURL、JavaScript 和 Python 示例。
POST https://api.dcision.io/v1/decisions/{slug}在一个 state 上运行决策 slug 的当前生效版本,并返回:每个问题一个带类型的回答、每个回答的置信度、加权等级和复合指标、由决策策略选定的行动,以及——对于带有目的地的决策——接下来会发生什么。所有问题都在一次引擎调用中回答。
已经拿到回答的 GPT-Live 语音会话则改为将回答发送到 POST /v1/decisions/{slug}/openai-live/answers:相同的策略、目的地和响应,无需调用引擎。
请求
路径参数
| 参数 | 说明 |
|---|---|
slug | 决策的 slug,显示在编辑器和部署标签页中——例如 lead-qualification。 |
查询参数
| 参数 | 说明 |
|---|---|
include | 可选。probabilities 会在响应中加入每个问题的完整分布。以逗号分隔;其他值会被忽略。 |
请求头
| 请求头 | 必需 | 说明 |
|---|---|---|
Authorization | 是 | Bearer dcs_live_… 或 Bearer dcs_test_…——参见认证。 |
Content-Type | 是 | application/json。 |
Idempotency-Key | 否 | 1–128 个字符,取自 A–Z a–z 0–9 . _ : -。在 24 小时内重放成功调用的存储响应——参见幂等性。 |
X-Request-ID | 否 | 你的关联 ID(字符集相同)。会在响应中回显,并与执行记录一起存储。 |
请求体
{ "state": { "message": "We need pricing for 500 users and want to start next month.", "company_size": 500 } }| 字段 | 类型 | 说明 |
|---|---|---|
state | object、string 或 array | 决策的输入:对象 state 为对象,文本 state 为非空字符串,列表 state 为非空数组(最多 500 项)。会按照决策的 state schema 进行校验;对象中未声明的字段会被接受并转发给引擎。image、audio 和 file 字段接受文件——参见输入。 |
其他顶层字段会被忽略。整个请求体必须在 32 MB 以内(可容纳每个最大 20 MB、合计 24 MB 的文件);不含文件的 state 必须在 128 KB 以内,并且在读取文件之后,与问题一起不超过引擎的 token 预算。
示例
curl -X POST https://api.dcision.io/v1/decisions/lead-qualification \
-H "Authorization: Bearer $DCISION_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: lead-8421" \
-d '{
"state": {
"message": "We need pricing for 500 users and want to start next month.",
"company_size": 500,
"source": "website"
}
}'使用文本 state 的决策接受一个字符串:
curl -X POST https://api.dcision.io/v1/decisions/spam-detection \
-H "Authorization: Bearer $DCISION_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "state": "Congratulations! You won a $1000 gift card, click here to claim now." }'使用列表 state 的决策接受一个数组——这里是一段聊天记录,用于一个名为 chat-triage、state 为字符串列表的决策:
curl -X POST https://api.dcision.io/v1/decisions/chat-triage \
-H "Authorization: Bearer $DCISION_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "state": ["Hi!", "Can I get a quote for 50 seats?"] }'响应
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Request-ID: req_Qm8vT2kLx9Pw4Rz7Nc1B
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1791195060{
"decision_id": "dec_3fKq9ZtW1mXcV7bN2pLa",
"execution_id": "exec_8HsT2kQw9ZyR4vMn1cXe",
"schema": "lead-qualification",
"version": 1,
"result": {
"purchase_intent": 0.9412,
"priority": "high",
"route": "sales"
},
"confidence": {
"purchase_intent": 0.8824,
"priority": 0.69,
"route": 0.85
},
"scores": { "priority": 2.81 },
"composites": { "lead_score": 0.8414 },
"action": "continue",
"action_reason": { "type": "default" },
"metrics": {
"latency_ms": 412,
"engine": "jev",
"model": "jev-1.13.0",
"estimated_cost_usd": 0.00001575,
"input_tokens": 375,
"output_tokens": 36
}
}| 字段 | 类型 | 说明 |
|---|---|---|
decision_id | string | 决策的 ID(dec_…)。 |
execution_id | string | 本次运行的 ID(exec_…),可在执行记录和 GET /v1/executions 中搜索。 |
schema | string | 决策的 slug。 |
version | integer | 作答的已部署版本。 |
result | object | 每个问题一个回答,按问题顺序排列:一个选项(choice)、最可能等级的标签(score),或 yes 的概率,取值 0 到 1(probability)。引擎错误 fallback 之后为空。 |
confidence | object | 每个问题一个 0 到 1 之间的数字——参见置信度。 |
scores | object | 仅针对带有 score 问题的决策:每个 score 问题的加权等级,从 1 开始计——参见加权等级。 |
composites | object | 仅针对带有复合指标的决策:每个复合指标的值。 |
action | string | continue、block、escalate 或 fallback——参见策略与行动。 |
action_reason | object | 选择该行动的原因(见下文)。 |
probabilities | object | 仅在 ?include=probabilities 时出现:每个问题的分布。 |
output | object 或 null | 仅当结构化输出目的地触发时出现:第一个完成的结构化输出的对象,已按其字段校验——没有完成的则为 null。 |
destinations | array | 仅针对带有目的地的决策:每个触发的目的地一个条目,按 schema 顺序排列——没有触发时为 []。参见下文。 |
metrics.latency_ms | integer | 本次运行在 Dcision 内部花费的时间——state 校验、引擎调用、复合指标和策略。不包括在其之后运行的 LLM 和智能体目的地。 |
metrics.engine | string | 运行的引擎:jev、laya 或 openai。 |
metrics.model | string | 作答的确切模型版本,例如 jev-1.13.0——即使工作区使用 jev-latest 这样的别名也是如此。 |
metrics.estimated_cost_usd | number | 调用的估算成本:引擎输入 token × 模型价格,若状态包含文件,再加上读取文件的成本。 |
metrics.input_tokens | integer | 引擎调用的输入 token——这是 Jev 和 OpenAI Decisions 计费的依据。 |
metrics.output_tokens | integer | 引擎调用的输出 token,用于可观测性:Jev 和 OpenAI Decisions 都不对其计费。 |
metrics.input_files | integer | 仅当状态包含文件时:读取的文件数量。 |
metrics.input_processing_ms | integer | 仅含文件时:下载和读取文件所用的时间,包含在 latency_ms 中。 |
metrics.input_cost_usd | number | 仅含文件时:通过 OpenAI 读取文件(音频转写、图片描述、文件读取)的估算成本——由 Dcision 自行读取时为 0。包含在 estimated_cost_usd 中。 |
action_reason
type | 附加字段 | 含义 |
|---|---|---|
policy | rule | 编号为 rule 的策略规则匹配(从 0 开始)。 |
other_option | question | 该 choice 问题回答了 other;适用 fallback 行动。 |
refusal | question | 引擎(OpenAI Decisions)拒绝回答该问题;它不会出现在 result 中,适用 fallback 行动。 |
low_confidence | question、confidence、minConfidence | 该问题的置信度低于其最低值;适用 fallback 行动。 |
engine_error | code | 引擎以错误 code 失败,且决策的 onEngineError 为 fallback:适用 fallback 行动,result 为空,且本次调用不计费。 |
default | — | 没有任何匹配:continue。 |
问题的键由你定义
result、confidence、scores 和 probabilities 以你的问题键为键,composites 以你的复合指标键为键,因此它们永远不会与顶层字段冲突:垃圾信息检测模板的 result.action(其 action 问题:allow、review 或 block)与由其策略选定的顶层 action 是不同的。
destinations
当决策带有目的地时出现。每个条目描述一个触发的目的地——它返回了什么,或 Dcision 将什么放入了队列——而目的地永远不会导致调用失败:问题会显示在相应的条目上。
[
{
"key": "sales_reply",
"type": "reply",
"text": "Thanks! Someone from our sales team will contact you today.",
"buttons": ["Book a demo", "See pricing"]
},
{
"key": "lead",
"type": "json",
"mode": "template",
"status": "completed",
"output": { "company_size": 500, "route": "sales", "start": "next month" }
},
{
"key": "sales_llm",
"type": "llm",
"status": "completed",
"text": "Thanks for reaching out! Someone from our sales team will contact you today to talk about your 500 users.",
"model": "openai/gpt-5-mini",
"usage": { "input_tokens": 61, "output_tokens": 27 }
},
{
"key": "sales_agent",
"type": "agent",
"status": "completed",
"reply": "I booked a demo for tomorrow at 10:00. You'll get an invitation by e-mail.",
"response": { "reply": "I booked a demo for tomorrow at 10:00. You'll get an invitation by e-mail.", "booking_id": "bk_5521" }
},
{ "key": "sales_summary", "type": "llm", "status": "failed", "error": "No answer from OpenRouter within 20 s." },
{ "key": "sales_crm", "type": "workflow", "status": "queued", "delivery_id": "dlv_8kJx2mQp4LzN7vR1tY6w" },
{ "key": "notify_sales", "type": "webhook", "status": "queued", "delivery_id": "dlv_Q2w9Lm4Xc7Rv1Tz8Wn3B" },
{ "key": "handoff", "type": "agent", "status": "queued", "delivery_id": "dlv_Hq2Lm9Xc4Rv1Tz8Wn3Bk" },
{ "key": "assign_owner", "type": "function", "function": "assignToSales", "params": { "email": "ana@acme.com", "route": "sales" } },
{ "key": "create_ticket", "type": "http", "status": "skipped", "reason": "missing_param", "param": "ticket_id" }
]| 字段 | 类型 | 说明 |
|---|---|---|
key | string | 目的地在决策中的键。 |
type | string | reply、json、llm、agent、workflow、webhook、http 或 function。 |
mode | string | json:template(由结果构建)或 extract(由 LLM 填写)。 |
format | string | json:当 output 是 json-render 界面时为 ui;数据则不出现。 |
output | object | 已完成的 json:该对象,已按其字段校验。 |
issues | array | 校验失败的 json:每个问题一个 { path, message },path 为 JSON Pointer。 |
status | string | 发生了什么(见下文)。已触发的固定回复和函数没有 status。 |
text | string | reply:消息内容。llm:模型的回答。 |
buttons | array | reply:按钮标签。 |
model | string | llm 以及 extract 模式的 json:作答的模型,以提供商报告的为准。 |
usage.input_tokens | integer | llm 以及 extract 模式的 json:提供商统计的输入 token——由提供商计费,而不是 Dcision。 |
usage.output_tokens | integer | llm:提供商统计的输出 token。 |
reply | string 或 null | sync 模式的 agent:智能体的回复,回答中没有回复字段时为 null。 |
response | any | sync 模式的 agent:智能体的完整回答,超过 16,000 个字符时为 null。 |
error | string | failed 条目:LLM 或智能体调用——或结构化输出——失败的原因。 |
delivery_id | string | queued 条目:每次尝试都会发送的 dlv_… ID——请据此去重。 |
function | string | function:你的代码应调用的处理函数。 |
params | object | function:调用的参数。 |
reason | string | skipped 条目:目的地未运行的原因(见下文)。 |
param | string | 带 missing_param 的 skipped:没有值的必需 param。 |
status | 类型 | 含义 |
|---|---|---|
completed | json、llm、agent | 输出已构建,或者模型或智能体已作答——调用方等待了它。 |
failed | json、llm、agent | 调用失败或输出与其字段不符;决策仍然有效。参见 error(以及 issues)。 |
queued | webhook、http、workflow、agent | Dcision 在后台投递,带有重试——参见投递与重试。 |
skipped | 全部 | 目的地匹配了,但没有运行。 |
reason | 含义 |
|---|---|
missing_param | 标记为 required 的 param 没有值。 |
limit | 匹配的目的地超过 10 个,或者需要调用方等待的目的地(LLM 回答、sync 智能体以及 extract 模式的结构化输出)超过 3 个。 |
unavailable | 投递无法进入队列。 |
在 Playground 中,条目都是预览——"status": "preview",附带将要发送的请求或提示——除非你真实执行目的地。参见测试目的地。
错误
错误使用标准格式。此端点返回的错误:
| 状态 | 代码 |
|---|---|
| 400 | INVALID_REQUEST——JSON 格式错误、请求体不是对象、无效的 Idempotency-Key |
| 401 | INVALID_API_KEY |
| 402 | CREDITS_EXHAUSTED——包含的额度已用完且没有剩余额度;SPEND_CAP_REACHED——已达到本周期的支出上限;QUOTA_EXCEEDED——设有硬性上限的套餐的包含额度已用完 |
| 404 | DECISION_NOT_FOUND |
| 409 | DECISION_NOT_DEPLOYED、DECISION_DISABLED、IDEMPOTENCY_CONFLICT——在使用相同键的请求仍在运行时带有 Retry-After: 1 |
| 413 | PAYLOAD_TOO_LARGE——请求体超过 32 MB |
| 422 | INVALID_STATE——包括超出引擎 token 预算的 state——以及 INVALID_SCHEMA |
| 424 | ENGINE_NOT_CONFIGURED |
| 429 | RATE_LIMITED |
| 500 | INTERNAL_ERROR |
| 502 | ENGINE_AUTH_FAILED、ENGINE_INVALID_REQUEST、ENGINE_ERROR |
| 503 | ENGINE_RATE_LIMITED、ENGINE_UNAVAILABLE |
| 504 | ENGINE_TIMEOUT |
引擎错误出现在 Dcision 自己的重试之后,且都在决策的 timeoutMs 之内。当决策的 onEngineError 为 fallback 时,502、503 和 504 引擎错误会变为带 fallback 行动和 action_reason.type = "engine_error" 的 200——参见决策设置。
检查顺序
当有多处出错时,由第一个失败的步骤决定返回的错误:
- API 密钥 →
401 INVALID_API_KEY。 - 工作区的速率限制 →
429 RATE_LIMITED。从这一步起,响应会带有X-RateLimit-*请求头。 - slug 格式 →
404 DECISION_NOT_FOUND;请求体 →400 INVALID_REQUEST。 - 幂等性:此时会重放相同键和相同请求的存储响应;相同的键配不同的请求 →
409 IDEMPOTENCY_CONFLICT;相同的请求仍在运行 → 带Retry-After: 1的409 IDEMPOTENCY_CONFLICT。否则该键会为此请求预留——如果之后任何步骤失败,则再次释放。 - 决策存在、已启用且有已部署的版本 →
404/409。 - 包含额度和额度余额:超出套餐包含的决策后,检查可用额度 →
402 CREDITS_EXHAUSTED,然后检查支出上限 →402 SPEND_CAP_REACHED;设有硬性上限的套餐 →402 QUOTA_EXCEEDED。 - state 校验,然后检查 state 和问题的引擎 token 预算 →
422 INVALID_STATE。 - 引擎调用,在
timeoutMs内重试 → 失败时返回424/502/503/504,或在onEngineError: "fallback"时返回 fallback 行动。 - 复合指标和策略 →
action和action_reason。 - 目的地 → 返回回复和函数,等待 LLM 和
sync智能体调用,将投递放入队列——然后返回200 OK。
第 7 到第 10 步会被记录为执行记录,包括失败的情况。只有第 10 步新产生的 200 才会计费——错误、重放和引擎错误时的 fallback 都不计费。参见套餐、配额与计费。