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

POST /workflows/{workflowId}/run lance 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/{run_id} pour connaître 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 associés à l’exécution directement ou via des liaisons d’entrée.

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

Champs du corps de la requête

Tous les champs, sauf l’ID du workflow, sont facultatifs. Les champs que vous omettez reviennent à la configuration enregistrée de l’agent.

Champ	Ce que cela fait
`projectId`	Projet dans lequel exécuter. La valeur par défaut est `"personal"`.
`file_ids`, `folder_ids`	Fichiers et dossiers associés à l’exécution.
`tabular_review_ids`	Revues tabulaires associées à l’exécution.
`playbook_ids`	Playbooks associés à l’exécution.
`skill_ids`	Compétences associées à l’exécution.
`email_ids`	E-mails associés à l’exécution.
`workflow_ids`	Workflows associés à l’exécution.
`workflow_ids_override`	Remplace les workflows associés par défaut à l’agent.
`run_context`	Contexte de l’exécution.
`inputs`	Carte 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 se mettre en 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 carte 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écuter sans intervention humaine

Définissez allow_human_input sur false pour rendre l’exécution non interactive. 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, et la définition de l’agent. Les valeurs ambiguës ou manquantes sont traitées comme des hypothèses et signalées au lieu de bloquer l’exécution.

Si l’exécution ne peut réellement pas continuer sans intervention humaine, elle échoue avec une erreur de la forme Run requires human input that cannot be provided: ... au lieu de rester en pause.

Les exécutions lancées depuis le portail d’August utilisent toujours ce comportement non interactif et se terminent par une issue de réussite, d’avertissement ou d’échec au lieu de rester en pause. Le parcours interactif désactivé par allow_human_input: false est décrit dans Reprendre une exécution d’agent en attente d’une intervention humaine.

Résultats de l’exécution

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

Réussie. Le contrat de sortie a été respecté sans problème.
Terminée avec avertissements. L’exécution a 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 était manquant, ou une étape a avancé sur la base d’une hypothèse. Les écrans de l’exécution affichent l’état « Completed with warnings », et l’explication de l’avertissement apparaît dans les détails de l’exécution. Vérifiez les hypothèses ou les entrées manquantes avant de vous fier à la sortie.
Échouée. Réservé aux véritables défaillances de la plateforme ou du contrôle d’exécution, y compris une exécution non interactive qui avait besoin d’une intervention humaine qu’elle n’a pas pu obtenir.