Déclencher l’exécution d’un agent depuis l’API

POST /workflows/{workflowId}/run démarre une exécution d’agent via l’API publique August. L’appel est asynchrone : il renvoie immédiatement un run_id, puis vous interrogez GET /workflows/{workflowId}/runs/{runId} pour obtenir l’état et la sortie.

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 attachés à l’exécution directement ou via des liaisons d’entrée.

Envoyez la requête d’exécution

L’opération est POST /workflows/{workflowId}/run, décrite dans l’API comme « Run an agent ».

Envoyez POST /workflows/{workflowId}/run avec les champs du corps de 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), ainsi qu’un message Agent run started ou Agent run already existed.
Interrogez GET /workflows/{workflowId}/runs/{runId} avec le run_id renvoyé jusqu’à la fin de l’exécution.

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 omis reviennent à la configuration enregistrée de l’agent.

Champ	Ce qu’il fait
`projectId`	Projet dans lequel exécuter. La valeur par défaut est `"personal"`.
`file_ids`, `folder_ids`	Fichiers et dossiers attachés à l’exécution.
`tabular_review_ids`	Revues tabulaires attachées à l’exécution.
`playbook_ids`	Playbooks attachés à l’exécution.
`skill_ids`	Skills attachées à l’exécution.
`email_ids`	Emails attachés à l’exécution.
`workflow_ids`	Workflows attachés à l’exécution.
`workflow_ids_override`	Remplace les workflows attachés par défaut à l’agent.
`run_context`	Contexte de l’exécution.
`inputs`	Table de correspondance des noms d’entrée vers des valeurs de chaîne.
`input_bindings`	Liaisons d’entrée du workflow.
`allow_human_input`	Indique si l’exécution peut faire une pause pour demander une intervention humaine. Booléen facultatif, valeur par défaut `true`.

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

Les pièces jointes et la table inputs remplacent les valeurs par défaut enregistrées de l’agent. Omettez-les et l’exécution utilisera les valeurs par défaut renvoyées par GET /workflows/{workflowId}/run-inputs.

Exécutions qui s’interrompent pour demander 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 qu’il lui manque une entrée dont elle ne peut pas se passer, elle se met en pause avec le statut waiting. L’API publique ne propose aucune opération pour répondre ; c’est donc l’utilisateur qui possède la clé API qui répond à l’exécution dans l’application web August, comme expliqué dans Reprendre une exécution d’agent en attente d’une intervention humaine.

Exécuter sans intervention humaine

Définissez allow_human_input sur false lorsqu’il n’y aura personne pour répondre, par exemple lorsque votre propre portail client lance l’exécution. L’exécution ne peut rien demander à une personne : aucune carte d’approbation n’est émise, et les outils ask-the-user et wait-for-human-input ne sont pas disponibles. L’agent poursuit avec les documents joints, les entrées fournies ou par défaut, ainsi que la définition de l’agent.

Les valeurs ambiguës ou manquantes sont traitées comme des hypothèses et signalées comme des avertissements, de sorte que l’exécution se termine normalement Completed with warnings au lieu de bloquer. Ce n’est que si l’exécution atteint malgré tout un point où elle devrait s’interrompre qu’elle échoue avec une erreur de la forme Run requires human input that cannot be provided: ....

Un agent peut aussi être enregistré comme non interactif ; dans ce cas, chaque exécution se comporte ainsi, quel que soit ce que vous envoyez dans allow_human_input.

Résultats d’exécution

Une exécution se termine avec l’un des trois résultats suivants :

Succeeded. Le contrat de sortie a été respecté sans problème.
Completed with warnings. L’exécution a bien fourni sa sortie, mais quelque chose ne s’est pas passé comme prévu : par exemple, une entrée n’a pas pu être identifiée, un élément requis manquait, ou une étape s’est poursuivie sur la base d’une hypothèse. Les interfaces d’exécution affichent le statut "Completed with warnings", et l’explication de l’avertissement apparaît dans les détails de l’exécution. Passez en revue les hypothèses ou les entrées manquantes avant de vous fier à la sortie.
Failed. Réservé aux véritables échecs de la plateforme ou du contrôle d’exécution, y compris une exécution non interactive qui avait besoin d’une intervention humaine mais n’a pas pu l’obtenir.