智能体

把结果连同路由的指令和工具交给你自己的智能体端点——在响应中等待它的回复,或在后台移交并自动重试。

智能体目的地会调用你运行的端点——你的客服智能体、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
  }
}
字段类型默认值说明
urlstring—你的端点:https://…,或保存完整 URL 的 {{secrets.NAME}}。最多 2,048 个字符,可包含变量。
headersarray[]最多 20 个 { "name", "value" } 对;值最多 2,048 个字符,可包含变量和密钥。
instructionsstring—路由的提示词,作为 instructions 发送:最多 32,000 个字符——足以容纳一整套操作手册——可包含变量,不能包含密钥。
toolsarray[]最多 50 个你的智能体认识的工具名称——字母、数字和 _ . : -,每个最多 64 个字符。
modestringsyncsync 或 async。
replyPathstring—仅 sync:回复在智能体 JSON 回答中的位置,以点路径表示,例如 data.answer。
timeoutMsinteger200001,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
Body
{
  "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 从以下位置获取回复:

  1. 设置了 replyPath 时,取该处的字段;
  2. 否则取以下顶层字段中第一个存在的:reply、output_text、output、text、message、content;
  3. 回答不是 JSON 时,取整个响应体。

字符串原样使用;其他值以 JSON 文本返回。

In the response
{
  "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 中,预览会显示确切的请求——密钥已遮蔽——而不会调用你的智能体。

本页内容