Pular para o conteúdo principal

Webhooks de agentes

Os webhooks de agentes permitem que um sistema externo inicie um agente configurado. Crie um agente acionado por webhook, envie uma solicitação e o Almirant criará um único trabalho canônico para ela.

Caminho rápido​

  1. Abra Agents e selecione Create agent.
  2. Conclua as etapas Base, Prompt e, se aplicável, MCP.
  3. Em Trigger, escolha Webhook e salve o agente. O Almirant exibirá uma URL de produção e outra de teste.
  4. Armazene a URL de produção como segredo no sistema chamador e envie uma solicitação POST com Idempotency-Key.

A URL de produção tem este formato:

https://<your-almirant-host>/webhooks/agents/<agent-id>?token=<webhook-token>

O token faz parte da credencial. Não o inclua no controle de versão, em registros nem em tickets públicos.

Enviar uma solicitação POST​

POST inicia um trabalho do agente com o prompt de sistema salvo, além de um prompt e metadados opcionais da pessoa chamadora.

curl --request POST \
  --url 'https://almirant.example.com/webhooks/agents/agent_123?token=replace-with-secret-token' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-9182-import-v1' \
  --data '{
    "prompt": "Importe o pedido e informe qualquer erro de validação.",
    "metadata": {
      "orderId": "9182",
      "source": "warehouse"
    }
  }'

A primeira entrega bem-sucedida retorna o trabalho criado:

{
  "success": true,
  "data": {
    "jobId": "job_123",
    "status": "queued",
    "created": true,
    "replayed": false
  }
}

Envie novamente a mesma Idempotency-Key se uma falha de rede deixar dúvidas sobre o recebimento da solicitação pelo Almirant. Uma repetição retorna o mesmo trabalho canônico em vez de iniciar outro:

{
  "success": true,
  "data": {
    "jobId": "job_123",
    "status": "queued",
    "created": false,
    "replayed": true
  }
}

Contrato da solicitação​

ParteRequisito
URLagent-id e o parâmetro de consulta token são obrigatórios. Credenciais inválidas ou ausentes retornam 401.
Idempotency-KeyOpcional em POST; use um valor opaco e estável por evento lógico. Deve ter de 1 a 255 bytes UTF-8, não pode estar vazio nem conter caracteres de controle. Valores inválidos retornam 400 com invalid_idempotency_key.
promptString opcional adicionada como entrada da pessoa chamadora nesta execução.
metadataObjeto opcional. Os prompts salvos do agente podem interpolar valores de metadados como {{metadata.orderId}}.
outputBindingValores opcionais de string para string para um destino de saída já configurado no agente. Não pode selecionar uma nova URL de entrega.

O corpo aceita somente prompt, metadata e outputBinding. Um deliveryUrl controlado pela pessoa chamadora é rejeitado.

Comportamento de teste, GET e POST​

O endpoint de teste verifica se a URL pode ser alcançada. Ele não coloca nenhum trabalho na fila:

POST https://<your-almirant-host>/webhook-test/agents/<agent-id>?token=<webhook-token>

O endpoint GET de produção inicia um trabalho com o prompt de sistema salvo. GET não aceita entrada da pessoa chamadora nem fornece a semântica de resposta idempotente de POST. Use POST em integrações que possam tentar novamente.

Os agentes acionados por webhook usam agendamento manual porque são iniciados por solicitações recebidas, e não pelo agendador. Um agente de webhook precisa permanecer habilitado e configurado para esse acionador; caso contrário, o endpoint retorna 409.

Solução de problemas​

RespostaSignificadoAção
400 invalid_idempotency_keyA chave POST está vazia, é longa demais ou contém um caractere de controle.Gere um identificador de evento curto e estável.
400 invalid_output_bindingA vinculação fornecida não corresponde à configuração de saída do agente.Verifique o destino de saída configurado e os nomes dos campos de vinculação.
401 invalid_webhook_credentialsO token da URL está ausente, incorreto ou não é mais válido.Copie a URL atual do agente e substitua o segredo armazenado.
409O agente não pode ser executado como agente de webhook.Habilite-o novamente e confirme que o acionador é Webhook.

Páginas relacionadas​