Revisão das respostas de um agente externo
Peça à XBASE para revisar a resposta de um agente externo antes de enviá-la ao contato, com os guardrails de saída configurados no agente.
Atualizado em
Um agente externo gera a resposta fora da XBASE. Com o escopo Revisar respostas do agente (guardrails) (guardrails:review), ele pede à XBASE a revisão da resposta antes de enviar, com os mesmos guardrails de saída configurados no agente.
Requisição
POST https://api.xbase.app/api/external/v1/agents/{agentId}/output-reviewagentId é o id do agente externo na XBASE. Agente de outro workspace ou que não é externo responde 404.
| Campo | Tipo | Obrigatório | Regra |
|---|---|---|---|
turnKey | texto | sim | Id da mensagem do contato, até 128 caracteres. Repetir o mesmo turnKey identifica o mesmo turno |
attempt | 1 ou 2 | sim | 2 quando o agente já refez a resposta uma vez |
message | texto | sim | Mensagem do contato, até 4.000 caracteres |
reply | texto | sim | Resposta que o agente quer enviar, até 8.000 caracteres |
instructions | texto | não | Instruções do agente, até 40.000 caracteres |
recentConversation | texto | não | Trecho recente da conversa, até 3.000 caracteres |
sources | texto | não | Resultados de ferramentas e buscas usados na resposta, até 20.000 caracteres |
threadId | texto | não | Conversa na XBASE, do mesmo workspace |
curl -X POST https://api.xbase.app/api/external/v1/agents/$AGENT_ID/output-review \
-H "Authorization: Bearer $XBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"turnKey": "msg-8812",
"attempt": 1,
"message": "Vocês entregam no sábado?",
"reply": "Sim, entregamos todos os dias, inclusive domingo.",
"threadId": "c1d7f0b2-…"
}'Resposta
Resposta 200:
{
"verdict": "rejected",
"triggered": ["grounding"],
"severity": "grave",
"action": "retry",
"considerations": {
"fixed": ["A resposta afirma algo que não está nas instruções."],
"feedback": { "problemas": ["…"], "afirmacoes_sem_base": ["…"], "orientacao": "…" }
},
"holdingMessage": null,
"reviewId": "4e0b…"
}action | O que o agente faz |
|---|---|
send | Envia a resposta. Vem quando ela foi aprovada, quando a revisão ficou incerta, quando o guardrail só registra ou quando não há guardrail de saída ligado |
retry | Primeira reprovação: refaça a resposta usando considerations e descarte a resposta barrada |
send_with_tag | Segunda reprovação leve: envie |
hold | Segunda reprovação grave: não envie a resposta. Envie holdingMessage e passe a conversa para a equipe |
Fluxo recomendado
- O agente gera a resposta e chama a revisão com
attempt: 1. - Com
send, envia. Comretry, refaz a resposta usando asconsiderationse chama de novo comattempt: 2e o mesmoturnKey. - Na segunda chamada, segue a
action:sendousend_with_tagenviam;holdmanda aholdingMessagee passa para a equipe.
Com threadId, a revisão aparece na conversa do Chatcenter.
Perguntas frequentes
Veja também
Webhooks: receber eventos em tempo real
Receba na sua URL, em tempo real, os eventos do WhatsApp e os comentários e DMs do Instagram, confira a assinatura e entenda as novas tentativas.
Erros da API
O formato dos erros da API da XBASE, o que cada status HTTP quer dizer e a lista de códigos estáveis para a sua integração tratar.