Skip to main content

Webhooks de agentes

Los webhooks de agentes permiten que un sistema externo inicie un agente configurado. Crea un agente activado por webhook, envíale una solicitud y Almirant creará un único trabajo canónico para ella.

Ruta rápida​

  1. Abre Agents y selecciona Create agent.
  2. Completa los pasos Base, Prompt y, si corresponde, MCP.
  3. En Trigger, elige Webhook y guarda el agente. Almirant mostrará una URL de producción y otra de prueba.
  4. Guarda la URL de producción como secreto en el sistema que llama y envía una solicitud POST con Idempotency-Key.

La URL de producción tiene esta forma:

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

El token forma parte de la credencial. No lo incluyas en el control de versiones, registros ni tickets públicos.

Enviar una solicitud POST​

POST inicia un trabajo del agente con el prompt de sistema guardado, además de un prompt y metadatos opcionales de quien llama.

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": "Importa el pedido e informa de cualquier error de validación.",
    "metadata": {
      "orderId": "9182",
      "source": "warehouse"
    }
  }'

La primera entrega correcta devuelve el trabajo creado:

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

Envía de nuevo la misma Idempotency-Key si un fallo de red deja dudas sobre si Almirant recibió la solicitud. Una repetición devuelve el mismo trabajo canónico en lugar de iniciar otro:

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

Contrato de la solicitud​

ParteRequisito
URLSe requieren agent-id y el parámetro de consulta token. Las credenciales no válidas o ausentes devuelven 401.
Idempotency-KeyOpcional en POST; usa un valor opaco y estable por evento lógico. Debe tener entre 1 y 255 bytes UTF-8, no puede estar vacío ni contener caracteres de control. Los valores no válidos devuelven 400 con invalid_idempotency_key.
promptCadena opcional que se añade como entrada de quien llama en esta ejecución.
metadataObjeto opcional. Los prompts guardados del agente pueden interpolar valores de metadatos como {{metadata.orderId}}.
outputBindingValores opcionales de cadena a cadena para un destino de salida ya configurado en el agente. No puede seleccionar una URL de entrega nueva.

El cuerpo solo acepta prompt, metadata y outputBinding. Se rechaza un deliveryUrl controlado por quien llama.

Comportamiento de prueba, GET y POST​

El endpoint de prueba comprueba que se puede alcanzar la URL. No pone ningún trabajo en cola:

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

El endpoint GET de producción inicia un trabajo con el prompt de sistema guardado. GET no acepta entrada de quien llama ni proporciona la semántica de respuesta idempotente de POST. Usa POST en integraciones que puedan reintentar.

Los agentes activados por webhook usan una programación manual porque los inician solicitudes entrantes, no el planificador. Un agente de webhook debe permanecer habilitado y configurado para ese activador; de lo contrario, el endpoint devuelve 409.

Resolución de problemas​

RespuestaSignificadoAcción
400 invalid_idempotency_keyLa clave POST está vacía, es demasiado larga o contiene un carácter de control.Genera un identificador de evento breve y estable.
400 invalid_output_bindingLa vinculación proporcionada no coincide con la configuración de salida del agente.Comprueba el destino de salida configurado y los nombres de los campos de vinculación.
401 invalid_webhook_credentialsEl token de la URL falta, es incorrecto o ya no es válido.Copia la URL actual del agente y sustituye el secreto guardado.
409El agente no se puede ejecutar como agente de webhook.Vuelve a habilitarlo y confirma que su activador es Webhook.

Páginas relacionadas​