Aller au contenu principal

Webhooks d'agents

Les webhooks d'agents permettent à un système externe de démarrer un agent configuré. Créez un agent déclenché par webhook, envoyez-lui une requête et Almirant créera un unique travail canonique pour celle-ci.

Parcours rapide​

  1. Ouvrez Agents et sélectionnez Create agent.
  2. Renseignez les étapes Base, Prompt et, le cas échéant, MCP.
  3. Dans Trigger, choisissez Webhook et enregistrez l'agent. Almirant affichera une URL de production et une URL de test.
  4. Conservez l'URL de production comme secret dans le système appelant et envoyez une requête POST avec Idempotency-Key.

L'URL de production a la forme suivante :

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

Le token fait partie de l'identifiant. Ne l'incluez pas dans le contrôle de version, les journaux ou les tickets publics.

Envoyer une requête POST​

POST démarre un travail d'agent avec le prompt système enregistré, ainsi qu'un prompt et des métadonnées optionnels fournis par l'appelant.

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": "Importez la commande et signalez toute erreur de validation.",
    "metadata": {
      "orderId": "9182",
      "source": "warehouse"
    }
  }'

La première livraison réussie renvoie le travail créé :

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

Renvoyez la même Idempotency-Key si une panne réseau laisse un doute sur la réception de la requête par Almirant. Une répétition renvoie le même travail canonique au lieu d'en démarrer un autre :

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

Contrat de requête​

ÉlémentExigence
URLagent-id et le paramètre de requête token sont requis. Des identifiants absents ou non valides renvoient 401.
Idempotency-KeyFacultative pour POST ; utilisez une valeur opaque et stable par événement logique. Elle doit faire entre 1 et 255 octets UTF-8, ne peut pas être vide et ne peut pas contenir de caractères de contrôle. Les valeurs non valides renvoient 400 avec invalid_idempotency_key.
promptChaîne optionnelle ajoutée comme entrée de l'appelant pour cette exécution.
metadataObjet optionnel. Les prompts enregistrés de l'agent peuvent interpoler des valeurs de métadonnées telles que {{metadata.orderId}}.
outputBindingValeurs facultatives de chaîne à chaîne pour une destination de sortie déjà configurée sur l'agent. Ne peut pas sélectionner une nouvelle URL de livraison.

Le corps n'accepte que prompt, metadata et outputBinding. Un deliveryUrl contrôlé par l'appelant est rejeté.

Comportement des tests, GET et POST​

L'endpoint de test vérifie que l'URL est joignable. Il ne met aucun travail en file d'attente :

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

L'endpoint de production GET démarre un travail avec le prompt système enregistré. GET n'accepte pas d'entrée de l'appelant et ne fournit pas la sémantique de réponse idempotente de POST. Utilisez POST pour les intégrations susceptibles de réessayer.

Les agents déclenchés par webhook utilisent une planification manuelle, car des requêtes entrantes les démarrent et non le planificateur. Un agent webhook doit rester activé et configuré pour ce déclencheur ; sinon, l'endpoint renvoie 409.

Résolution des problèmes​

RéponseSignificationAction
400 invalid_idempotency_keyLa clé POST est vide, trop longue ou contient un caractère de contrôle.Générez un identifiant d'événement court et stable.
400 invalid_output_bindingLa liaison fournie ne correspond pas à la configuration de sortie de l'agent.Vérifiez la destination de sortie configurée et les noms des champs de liaison.
401 invalid_webhook_credentialsLe token de l'URL est absent, incorrect ou n'est plus valide.Copiez l'URL actuelle de l'agent et remplacez le secret enregistré.
409L'agent ne peut pas s'exécuter en tant qu'agent webhook.Réactivez-le et confirmez que son déclencheur est Webhook.

Pages associées​