Agentes

Entregue um resultado ao endpoint do seu próprio agente com as instruções e ferramentas da rota — aguarde a resposta dele na resposta, ou repasse em segundo plano com novas tentativas.

Um destino de agente chama um endpoint que você roda — seu agente de suporte, um serviço LangGraph ou Agents SDK, um assistente interno — com o estado, as instruções da rota e as ferramentas que ele pode usar nessa rota. A Dcision decide qual agente e com qual briefing; o seu agente faz o trabalho.

modeO que aconteceNa resposta
sync (padrão)A Dcision chama o agente enquanto quem chamou espera e extrai a resposta dele."status": "completed" com reply, ou "status": "failed" com error.
asyncUm repasse: a requisição entra na fila e é entregue em segundo plano, com novas tentativas."status": "queued" com delivery_id.

Configure-o

{
  "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
  }
}
CampoTipoPadrãoDescrição
urlstring—O seu endpoint: https://…, ou {{secrets.NAME}} contendo a URL inteira. Até 2.048 caracteres, com variáveis.
headersarray[]Até 20 pares { "name", "value" }; valores de até 2.048 caracteres, com variáveis e segredos.
instructionsstring—O prompt da rota, enviado como instructions: até 32.000 caracteres — espaço para um playbook inteiro — com variáveis, sem segredos.
toolsarray[]Até 50 nomes de ferramentas que o seu agente conhece — letras, dígitos e _ . : -, até 64 caracteres cada.
modestringsyncsync ou async.
replyPathstring—Só sync: onde a resposta está no JSON devolvido pelo agente, como um caminho com pontos, por exemplo data.answer.
timeoutMsinteger200001.000 a 25.000 — só sync.

A requisição que o seu agente recebe

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
  }
}
CampoDescrição
inputO estado inteiro, como quem chamou o enviou.
instructionsO prompt da rota com as variáveis preenchidas; null quando o destino não tem um.
toolsOs nomes das ferramentas da rota.
paramsOs params do destino.
decisionO que a decisão respondeu — slug e IDs, version (null no Playground), result, confidence, action, action_reason — mais a chave do destino, o delivery_id e livemode (false para chaves de teste e no Playground).

A requisição é assinada como um webhook: verifique Dcision-Signature sobre o body bruto com verifySignature — o body é uma requisição de agente, não um evento de webhook. No modo async, deduplique pelo Idempotency-Key, o ID da entrega, que se mantém igual em todas as tentativas.

A resposta que a Dcision espera

No modo sync, responda 2xx dentro de timeoutMs. A Dcision pega a resposta de:

  1. o campo em replyPath, quando você define um;
  2. senão, o primeiro destes campos de nível superior que existir: reply, output_text, output, text, message, content;
  3. ou o body inteiro, quando a resposta não é JSON.

Uma string é usada como está; outros valores são devolvidos como texto JSON.

Na resposta
{
  "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 é a resposta inteira do agente, interpretada quando é JSON, e null quando passa de 16.000 caracteres. reply é null quando nenhum campo de resposta foi encontrado — defina Campo da resposta (replyPath) no destino.

Uma chamada sync é feita uma vez: sem novas tentativas, redirecionamentos não são seguidos, e a resposta é lida até 64 KB. Qualquer outra coisa vira uma entrada com falha, e a decisão continua respondendo:

{ "key": "shipping_agent", "type": "agent", "status": "failed", "error": "The agent answered 503. upstream overloaded" }

As falhas incluem uma resposta que não é 2xx (com o início do body), um timeout, um erro de rede, um endereço que não é público e um segredo faltando.

Quem chamou espera pelos agentes sync, em paralelo com as respostas de LLM; no máximo 3 deles rodam por execução.

Repasses (async)

Com "mode": "async", a mesma requisição assinada entra na fila e é entregue com o cronograma de novas tentativas dos webhooks — seis tentativas ao longo de cerca de sete horas, 10 segundos cada. Só o status da sua resposta importa: responda 2xx assim que tiver aceitado a tarefa, e continue o trabalho do seu lado.

Um endpoint de agente mínimo

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 });
});

Os exemplos usam os SDKs, que são compilados a partir do código-fonte até serem publicados.

Dados

Um agente recebe o estado inteiro como input, mais os params que você mapear. No Playground, as prévias mostram a requisição exata — com os segredos mascarados — sem chamar o seu agente.

Nesta página