Déclencher l'exécution d'un agent via l'API

POST /workflows/{workflowId}/run lance l'exécution d'un agent via l'API publique d'August. L'appel est asynchrone : il renvoie immédiatement un run_id, et vous devez interroger GET /workflows/{workflowId}/runs/{runId} pour obtenir l'état et les résultats.

Avant de commencer

L'opération d'exécution est protégée. August vérifie que l'appelant peut accéder au workflow de l'agent, y compris au projet auquel il appartient, ainsi qu'à tous les workflows rattachés à l'exécution directement ou via des liaisons d'entrée (input bindings).

Envoyer la demande d'exécution

L'opération est POST /workflows/{workflowId}/run, décrite dans l'API par "Run an agent".

Envoyez POST /workflows/{workflowId}/run avec les champs du corps de la requête dont vous avez besoin (voir le tableau ci-dessous).
Lisez la réponse. Elle renvoie run_id, workflow_id, chat_id (ou null), question_id (ou null), et un message indiquant Agent run started ou Agent run already existed.
Interrogez GET /workflows/{workflowId}/runs/{runId} avec le run_id renvoyé jusqu'à ce que l'exécution soit terminée.

Pour lister les exécutions passées d'un agent, appelez GET /workflows/{workflowId}/runs.

Champs du corps de la requête

Tous les champs, à l'exception de l'ID du workflow, sont facultatifs. Les champs que vous omettez utilisent par défaut la configuration enregistrée de l'agent.

Champ	Description
`projectId`	Projet dans lequel lancer l'exécution. Valeur par défaut : `"personal"`.
`file_ids`, `folder_ids`	Fichiers et dossiers joints à l'exécution.
`tabular_review_ids`	Revues tabulaires (tabular reviews) jointes à l'exécution.
`playbook_ids`	Playbooks joints à l'exécution.
`skill_ids`	Skills joints à l'exécution.
`email_ids`	E-mails joints à l'exécution.
`workflow_ids`	Workflows joints à l'exécution.
`workflow_ids_override`	Remplace les workflows joints par défaut de l'agent.
`run_context`	Contexte de l'exécution.
`inputs`	Mappage des noms d'entrée (inputs) sur des valeurs de type chaîne.
`input_bindings`	Liaisons d'entrée (input bindings) du workflow.
`allow_human_input`	Indique si l'exécution peut s'interrompre pour demander une intervention humaine. Booléen facultatif, `true` par défaut.
`notify_email`	Envoie par e-mail les résultats du document August de l'exécution à cette adresse depuis la boîte aux lettres August, lorsque l'e-mail de plateforme est activé pour le compte.

Utiliser les valeurs par défaut enregistrées ou les remplacer

Les pièces jointes et le mappage inputs remplacent les valeurs par défaut enregistrées de l'agent. Si vous les omettez, l'exécution utilise les valeurs par défaut renvoyées par GET /workflows/{workflowId}/run-inputs.

Envoyer les résultats par e-mail

Définissez notify_email pour que les résultats du document August de l'exécution soient envoyés par e-mail depuis la boîte aux lettres August à un destinataire de votre choix. La distribution des e-mails fonctionne lorsque l'e-mail de plateforme est activé pour le compte ; si ce n'est pas le cas, l'exécution démarre et se termine normalement, mais aucun e-mail n'est envoyé.

Exécutions s'interrompant pour une intervention humaine

Par défaut, une exécution via l'API se comporte comme une exécution planifiée : si elle atteint une étape Question ou s'il lui manque une entrée indispensable à son fonctionnement, elle s'interrompt avec l'état waiting. L'API publique ne disposant d'aucune opération de réponse, l'utilisateur propriétaire de la clé API doit répondre à l'exécution dans l'application web August, comme décrit dans Reprendre l'exécution d'un agent en attente d'une intervention humaine.

Exécuter sans intervention humaine

Définissez allow_human_input sur false lorsque personne ne sera disponible pour répondre, par exemple lorsque votre propre portail client lance l'exécution. L'agent ne pourra rien demander à une personne : aucune carte d'approbation n'est émise, et les outils ask-the-user et wait-for-human-input sont indisponibles. L'agent poursuit son exécution avec les documents joints, les entrées fournies ou par défaut, et la définition de l'agent.

Les valeurs ambiguës ou manquantes sont traitées comme des suppositions et signalées comme des avertissements, de sorte que l'exécution se termine normalement par Terminé avec des avertissements plutôt que d'être bloquée. L'exécution n'échoue avec une erreur de type Run requires human input that cannot be provided: ... que si elle atteint un point où elle devrait obligatoirement s'interrompre.

Un agent peut également être enregistré comme non interactif, auquel cas chaque exécution se comportera de cette manière, peu importe la valeur envoyée dans allow_human_input.

Résultats de l'exécution

Une exécution se termine par l'un des trois résultats suivants :

Réussi. Le contrat de sortie a été respecté sans erreur.
Terminé avec des avertissements. L'exécution a produit ses résultats, mais quelque chose ne s'est pas déroulé comme prévu : par exemple, une entrée n'a pas pu être identifiée, un élément requis était manquant ou une étape a été effectuée sur la base d'une supposition. Les interfaces d'exécution affichent l'état "Terminé avec des avertissements", et l'explication de l'avertissement apparaît dans les détails de l'exécution. Vérifiez les suppositions ou les entrées manquantes avant de vous fier aux résultats.
Échec. Réservé aux pannes réelles de la plateforme ou aux échecs de contrôle de l'exécution, y compris une exécution non interactive nécessitant une intervention humaine qu'elle n'a pas pu obtenir.

Lectures complémentaires

Exécuter un agent pour lancer des exécutions dans l'interface produit
Déclencheurs d'agent pour l'automatisation planifiée et déclenchée par téléchargement
Reprendre l'exécution d'un agent en attente d'une intervention humaine pour le parcours interactif

Cela vous a-t-il été utile ?