智能体
把结果连同路由的指令和工具交给你自己的智能体端点——在响应中等待它的回复,或在后台移交并自动重试。
智能体目的地会调用你运行的端点——你的客服智能体、LangGraph 或 Agents SDK 服务、内部助手——并传入 state、路由的指令以及它在该路由上可以使用的工具。Dcision 决定交给哪个智能体、附带什么任务说明;由你的智能体完成工作。
mode | 发生什么 | 在响应中 |
|---|---|---|
sync(默认) | Dcision 在调用方等待期间调用智能体,并提取其回复。 | "status": "completed" 并带有 reply,或 "status": "failed" 并带有 error。 |
async | 移交:请求进入队列并在后台投递,带有重试。 | "status": "queued" 并带有 delivery_id。 |
配置
{
"key": "shipping_agent",
"type": "agent",
"when": { "conditions": [{ "field": "department", "on": "output", "operator": "eq", "value": "shipping" }] },
"params": { "awb": { "from": "state.awb", "required": true } },
"agent": {
"url": "https://agents.example.com/support",
"headers": [{ "name": "Authorization", "value": "Bearer {{secrets.AGENT_TOKEN}}" }],
"instructions": "Help with the shipment {{params.awb}}. Confirm the address before rescheduling.",
"tools": ["track_package", "reschedule_delivery"],
"mode": "sync",
"replyPath": "data.answer",
"timeoutMs": 20000
}
}| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
url | string | — | 你的端点:https://…,或保存完整 URL 的 {{secrets.NAME}}。最多 2,048 个字符,可包含变量。 |
headers | array | [] | 最多 20 个 { "name", "value" } 对;值最多 2,048 个字符,可包含变量和密钥。 |
instructions | string | — | 路由的提示词,作为 instructions 发送:最多 32,000 个字符——足以容纳一整套操作手册——可包含变量,不能包含密钥。 |
tools | array | [] | 最多 50 个你的智能体认识的工具名称——字母、数字和 _ . : -,每个最多 64 个字符。 |
mode | string | sync | sync 或 async。 |
replyPath | string | — | 仅 sync:回复在智能体 JSON 回答中的位置,以点路径表示,例如 data.answer。 |
timeoutMs | integer | 20000 | 1,000 到 25,000——仅 sync。 |
你的智能体收到的请求
POST /support HTTP/1.1
Host: agents.example.com
Content-Type: application/json
Authorization: Bearer agt_live_51Hq…
User-Agent: Dcision-Destinations/1.0 (+https://docs.dcision.io/destinations)
Dcision-Delivery: dlv_Hq2Lm9Xc4Rv1Tz8Wn3Bk
Dcision-Attempt: 1
Dcision-Event: decision.completed
Dcision-Signature: t=1759658400,v1=6f1c2b…
Idempotency-Key: dlv_Hq2Lm9Xc4Rv1Tz8Wn3Bk{
"input": { "message": "Where is my package? It was due yesterday.", "awb": "4471-2210" },
"instructions": "Help with the shipment 4471-2210. Confirm the address before rescheduling.",
"tools": ["track_package", "reschedule_delivery"],
"params": { "awb": "4471-2210" },
"decision": {
"decision": "support-desk",
"decision_id": "dec_7Wq2Lm9Xc4Rv1Tz8Wn3B",
"version": 2,
"execution_id": "exec_Vn4Kp8Wd2Lq6Tz1Xc9Bs",
"result": { "department": "shipping", "urgency": "medium" },
"confidence": { "department": 0.92, "urgency": 0.71 },
"action": "continue",
"action_reason": { "type": "default" },
"destination": "shipping_agent",
"delivery_id": "dlv_Hq2Lm9Xc4Rv1Tz8Wn3Bk",
"livemode": true
}
}| 字段 | 说明 |
|---|---|
input | 整个 state,与调用方发送的一致。 |
instructions | 填入变量后的路由提示词;目的地没有提示词时为 null。 |
tools | 路由的工具名称。 |
params | 目的地的 params。 |
decision | 决策的回答——slug 和各种 ID、version(在 Playground 中为 null)、result、confidence、action、action_reason——以及目的地的键、delivery_id 和 livemode(测试密钥和 Playground 为 false)。 |
该请求与 webhook 一样经过签名:用 verifySignature 基于原始请求体验证 Dcision-Signature——请求体是智能体请求,而不是 webhook 事件。在 async 模式下,按 Idempotency-Key(即投递 ID,每次尝试都保持不变)去重。
Dcision 期望的回答
在 sync 模式下,请在 timeoutMs 内返回 2xx。Dcision 从以下位置获取回复:
- 设置了
replyPath时,取该处的字段; - 否则取以下顶层字段中第一个存在的:
reply、output_text、output、text、message、content; - 回答不是 JSON 时,取整个响应体。
字符串原样使用;其他值以 JSON 文本返回。
{
"key": "shipping_agent",
"type": "agent",
"status": "completed",
"reply": "Your package is at the local depot. I can deliver it tomorrow between 9 and 12 — shall I book it?",
"response": { "data": { "answer": "Your package is at the local depot. I can deliver it tomorrow between 9 and 12 — shall I book it?", "session": "s_9f2c" } }
}response 是智能体的完整回答,是 JSON 时会被解析,超过 16,000 个字符时为 null。未找到回复字段时 reply 为 null——请在目的地中设置回复字段(replyPath)。
sync 调用只进行一次:不重试、不跟随重定向,回答最多读取 64 KB。其他任何情况都会变成失败的条目,而决策仍会作答:
{ "key": "shipping_agent", "type": "agent", "status": "failed", "error": "The agent answered 503. upstream overloaded" }失败包括非 2xx 的回答(附带其响应体的开头)、超时、网络错误、非公网地址以及缺失的密钥。
调用方会等待 sync 智能体,它们与 LLM 回答并行运行;每次执行最多运行 3 个。
移交(async)
设置 "mode": "async" 时,同样经过签名的请求会进入队列,并按照 webhook 的重试计划投递——在约七小时内尝试六次,每次 10 秒。只有你回答的状态码有意义:在接受任务后返回 2xx,然后在你这一侧继续工作。
最小的智能体端点
import express from "express";
import { DcisionError, verifySignature } from "@dcision/sdk";
const app = express();
// The raw body: the signature covers the exact bytes Dcision sent.
app.post("/support", express.raw({ type: "application/json" }), async (req, res) => {
try {
await verifySignature(req.body, req.header("dcision-signature"), process.env.DCISION_WEBHOOK_SECRET!);
} catch (error) {
return res.sendStatus(error instanceof DcisionError ? 400 : 500);
}
const task = JSON.parse(req.body.toString("utf8"));
const reply = await supportAgent.run({
input: task.input,
instructions: task.instructions,
tools: task.tools,
conversationId: task.decision.execution_id,
});
res.json({ reply });
});示例使用了 SDK,在发布之前它们需要从源码构建。
数据
智能体会以 input 收到整个 state,以及你映射的 params。在 Playground 中,预览会显示确切的请求——密钥已遮蔽——而不会调用你的智能体。