Intenções

Intenções são "ações nomeadas" que o agente pode disparar quando detecta o pedido do cliente. Quando o LLM emite a tag <nome-da-intent campos="..."/>, o sistema:

1. Extrai os campos requeridos
2. Faz POST no webhook configurado
3. Substitui a tag pela resposta do webhook (ou continua a resposta normal)

Estrutura

{
  "id": "int_abc",
  "agentId": "agt_xyz",
  "name": "Atribuir entrega",
  "description": "Quando o entregador pede uma nova entrega",
  "triggerOnTypes": ["TEXT", "AUDIO"],
  "requiredFields": [
    { "name": "idEntregador", "type": "string", "description": "ID do entregador no BEE" },
    { "name": "cidade", "type": "string", "description": "Cidade da entrega" }
  ],
  "webhookUrl": "https://n8n.vulkania.cloud/webhook/atribuir-entrega",
  "webhookMethod": "POST"
}

Criar

POST /api/agents/{agentId}/intents
{
  "name": "Atribuir entrega",
  "description": "Quando o entregador pede uma nova entrega disponível",
  "triggerOnTypes": ["TEXT"],
  "requiredFields": [
    { "name": "idEntregador", "type": "string", "description": "ID do entregador no BEE" }
  ],
  "webhookUrl": "https://n8n.vulkania.cloud/webhook/atribuir-entrega"
}

Como o LLM detecta

O sistema injeta no systemPrompt:

Você tem acesso às seguintes intenções. Quando o usuário pedir uma delas,
emita a tag com os campos preenchidos:

<atribuir-entrega idEntregador="123" cidade="São Paulo"/>

Se o LLM emite a tag mas falta campo (ex: sem idEntregador), o worker loga Skipping intent — missing required field(s) e continua a conversa normalmente. Você pode ajustar o prompt para o agente perguntar antes de emitir a tag.

triggerOnTypes

Restringe em quais tipos de mensagem a intent pode ser detectada:

• TEXT — só mensagens de texto
• AUDIO — só áudios (após transcrição)
• IMAGE — só imagens (com Vision habilitada)
• DOCUMENT — só documentos (PDF, DOCX, etc)

Útil pra coleta de mídia (ex: intent "Enviar foto perfil" só dispara quando o cliente manda imagem).

Webhook contract

O AgentFlow faz POST com payload:

{
  "intentName": "Atribuir entrega",
  "fields": {
    "idEntregador": "123",
    "cidade": "São Paulo"
  },
  "context": {
    "agentId": "agt_xyz",
    "agentName": "Carlos",
    "conversationId": "conv_abc",
    "contactName": "João Silva",
    "contactId": "5511999999999"
  }
}

Resposta esperada do n8n:

{ "message": "Entrega #4521 atribuída pra você. Boa sorte!" }

Esse message substitui a tag na resposta do agente. Se a resposta for 200 sem message, a tag é removida silenciosamente.

Erros

• HTTP 0 (timeout/connection refused): worker loga Technical error on "X" (HTTP 0), escalating e converte em transferência humana
• HTTP 4xx/5xx com body: worker loga e escala
• Timeout default: 30s (configurável via env INTENT_WEBHOOK_TIMEOUT_MS)