运行决策

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 } }
字段类型说明
stateobject、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_idstring决策的 ID(dec_…)。
execution_idstring本次运行的 ID(exec_…),可在执行记录和 GET /v1/executions 中搜索。
schemastring决策的 slug。
versioninteger作答的已部署版本。
resultobject每个问题一个回答,按问题顺序排列:一个选项(choice)、最可能等级的标签(score),或 yes 的概率,取值 0 到 1(probability)。引擎错误 fallback 之后为空。
confidenceobject每个问题一个 0 到 1 之间的数字——参见置信度。
scoresobject仅针对带有 score 问题的决策:每个 score 问题的加权等级,从 1 开始计——参见加权等级。
compositesobject仅针对带有复合指标的决策:每个复合指标的值。
actionstringcontinue、block、escalate 或 fallback——参见策略与行动。
action_reasonobject选择该行动的原因(见下文)。
probabilitiesobject仅在 ?include=probabilities 时出现:每个问题的分布。
outputobject 或 null仅当结构化输出目的地触发时出现:第一个完成的结构化输出的对象,已按其字段校验——没有完成的则为 null。
destinationsarray仅针对带有目的地的决策:每个触发的目的地一个条目,按 schema 顺序排列——没有触发时为 []。参见下文。
metrics.latency_msinteger本次运行在 Dcision 内部花费的时间——state 校验、引擎调用、复合指标和策略。不包括在其之后运行的 LLM 和智能体目的地。
metrics.enginestring运行的引擎:jev、laya 或 openai。
metrics.modelstring作答的确切模型版本,例如 jev-1.13.0——即使工作区使用 jev-latest 这样的别名也是如此。
metrics.estimated_cost_usdnumber调用的估算成本:引擎输入 token × 模型价格,若状态包含文件,再加上读取文件的成本。
metrics.input_tokensinteger引擎调用的输入 token——这是 Jev 和 OpenAI Decisions 计费的依据。
metrics.output_tokensinteger引擎调用的输出 token,用于可观测性:Jev 和 OpenAI Decisions 都不对其计费。
metrics.input_filesinteger仅当状态包含文件时:读取的文件数量。
metrics.input_processing_msinteger仅含文件时:下载和读取文件所用的时间,包含在 latency_ms 中。
metrics.input_cost_usdnumber仅含文件时:通过 OpenAI 读取文件(音频转写、图片描述、文件读取)的估算成本——由 Dcision 自行读取时为 0。包含在 estimated_cost_usd 中。

action_reason

type附加字段含义
policyrule编号为 rule 的策略规则匹配(从 0 开始)。
other_optionquestion该 choice 问题回答了 other;适用 fallback 行动。
refusalquestion引擎(OpenAI Decisions)拒绝回答该问题;它不会出现在 result 中,适用 fallback 行动。
low_confidencequestion、confidence、minConfidence该问题的置信度低于其最低值;适用 fallback 行动。
engine_errorcode引擎以错误 code 失败,且决策的 onEngineError 为 fallback:适用 fallback 行动,result 为空,且本次调用不计费。
default—没有任何匹配:continue。

问题的键由你定义

result、confidence、scores 和 probabilities 以你的问题键为键,composites 以你的复合指标键为键,因此它们永远不会与顶层字段冲突:垃圾信息检测模板的 result.action(其 action 问题:allow、review 或 block)与由其策略选定的顶层 action 是不同的。

destinations

当决策带有目的地时出现。每个条目描述一个触发的目的地——它返回了什么,或 Dcision 将什么放入了队列——而目的地永远不会导致调用失败:问题会显示在相应的条目上。

Every kind of entry
[
  {
    "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" }
]
字段类型说明
keystring目的地在决策中的键。
typestringreply、json、llm、agent、workflow、webhook、http 或 function。
modestringjson:template(由结果构建)或 extract(由 LLM 填写)。
formatstringjson:当 output 是 json-render 界面时为 ui;数据则不出现。
outputobject已完成的 json:该对象,已按其字段校验。
issuesarray校验失败的 json:每个问题一个 { path, message },path 为 JSON Pointer。
statusstring发生了什么(见下文)。已触发的固定回复和函数没有 status。
textstringreply:消息内容。llm:模型的回答。
buttonsarrayreply:按钮标签。
modelstringllm 以及 extract 模式的 json:作答的模型,以提供商报告的为准。
usage.input_tokensintegerllm 以及 extract 模式的 json:提供商统计的输入 token——由提供商计费,而不是 Dcision。
usage.output_tokensintegerllm:提供商统计的输出 token。
replystring 或 nullsync 模式的 agent:智能体的回复,回答中没有回复字段时为 null。
responseanysync 模式的 agent:智能体的完整回答,超过 16,000 个字符时为 null。
errorstringfailed 条目:LLM 或智能体调用——或结构化输出——失败的原因。
delivery_idstringqueued 条目:每次尝试都会发送的 dlv_… ID——请据此去重。
functionstringfunction:你的代码应调用的处理函数。
paramsobjectfunction:调用的参数。
reasonstringskipped 条目:目的地未运行的原因(见下文)。
paramstring带 missing_param 的 skipped:没有值的必需 param。
status类型含义
completedjson、llm、agent输出已构建,或者模型或智能体已作答——调用方等待了它。
failedjson、llm、agent调用失败或输出与其字段不符;决策仍然有效。参见 error(以及 issues)。
queuedwebhook、http、workflow、agentDcision 在后台投递,带有重试——参见投递与重试。
skipped全部目的地匹配了,但没有运行。
reason含义
missing_param标记为 required 的 param 没有值。
limit匹配的目的地超过 10 个,或者需要调用方等待的目的地(LLM 回答、sync 智能体以及 extract 模式的结构化输出)超过 3 个。
unavailable投递无法进入队列。

在 Playground 中,条目都是预览——"status": "preview",附带将要发送的请求或提示——除非你真实执行目的地。参见测试目的地。

错误

错误使用标准格式。此端点返回的错误:

状态代码
400INVALID_REQUEST——JSON 格式错误、请求体不是对象、无效的 Idempotency-Key
401INVALID_API_KEY
402CREDITS_EXHAUSTED——包含的额度已用完且没有剩余额度;SPEND_CAP_REACHED——已达到本周期的支出上限;QUOTA_EXCEEDED——设有硬性上限的套餐的包含额度已用完
404DECISION_NOT_FOUND
409DECISION_NOT_DEPLOYED、DECISION_DISABLED、IDEMPOTENCY_CONFLICT——在使用相同键的请求仍在运行时带有 Retry-After: 1
413PAYLOAD_TOO_LARGE——请求体超过 32 MB
422INVALID_STATE——包括超出引擎 token 预算的 state——以及 INVALID_SCHEMA
424ENGINE_NOT_CONFIGURED
429RATE_LIMITED
500INTERNAL_ERROR
502ENGINE_AUTH_FAILED、ENGINE_INVALID_REQUEST、ENGINE_ERROR
503ENGINE_RATE_LIMITED、ENGINE_UNAVAILABLE
504ENGINE_TIMEOUT

引擎错误出现在 Dcision 自己的重试之后,且都在决策的 timeoutMs 之内。当决策的 onEngineError 为 fallback 时,502、503 和 504 引擎错误会变为带 fallback 行动和 action_reason.type = "engine_error" 的 200——参见决策设置。

检查顺序

当有多处出错时,由第一个失败的步骤决定返回的错误:

  1. API 密钥 → 401 INVALID_API_KEY。
  2. 工作区的速率限制 → 429 RATE_LIMITED。从这一步起,响应会带有 X-RateLimit-* 请求头。
  3. slug 格式 → 404 DECISION_NOT_FOUND;请求体 → 400 INVALID_REQUEST。
  4. 幂等性:此时会重放相同键和相同请求的存储响应;相同的键配不同的请求 → 409 IDEMPOTENCY_CONFLICT;相同的请求仍在运行 → 带 Retry-After: 1 的 409 IDEMPOTENCY_CONFLICT。否则该键会为此请求预留——如果之后任何步骤失败,则再次释放。
  5. 决策存在、已启用且有已部署的版本 → 404 / 409。
  6. 包含额度和额度余额:超出套餐包含的决策后,检查可用额度 → 402 CREDITS_EXHAUSTED,然后检查支出上限 → 402 SPEND_CAP_REACHED;设有硬性上限的套餐 → 402 QUOTA_EXCEEDED。
  7. state 校验,然后检查 state 和问题的引擎 token 预算 → 422 INVALID_STATE。
  8. 引擎调用,在 timeoutMs 内重试 → 失败时返回 424 / 502 / 503 / 504,或在 onEngineError: "fallback" 时返回 fallback 行动。
  9. 复合指标和策略 → action 和 action_reason。
  10. 目的地 → 返回回复和函数,等待 LLM 和 sync 智能体调用,将投递放入队列——然后返回 200 OK。

第 7 到第 10 步会被记录为执行记录,包括失败的情况。只有第 10 步新产生的 200 才会计费——错误、重放和引擎错误时的 fallback 都不计费。参见套餐、配额与计费。

本页内容