Activar una ejecución de un agente desde la API

POST /workflows/{workflowId}/run inicia una ejecución de un agente a través de la API pública de August. La llamada es asíncrona: devuelve un run_id inmediatamente y puedes consultar GET /workflows/{workflowId}/runs/{run_id} para obtener el estado y el resultado.

Antes de empezar

La operación de ejecución está protegida. August verifica que el autor de la llamada pueda acceder al flujo de trabajo del agente, incluido el proyecto al que pertenece y cualquier flujo de trabajo asociado directamente a la ejecución o mediante vinculaciones de entrada.

Enviar la solicitud de ejecución

La operación es POST /workflows/{workflowId}/run, descrita en la API como «Ejecutar un agente».

Envía POST /workflows/{workflowId}/run con los campos del cuerpo de la solicitud que necesites (consulta la tabla siguiente).
Lee la respuesta. Devuelve run_id, workflow_id, chat_id (o null) y un mensaje de Agent run started o Agent run already existed.
Consulta GET /workflows/{workflowId}/runs/{run_id} con el run_id devuelto hasta que finalice la ejecución.

Campos del cuerpo de la solicitud

Todos los campos, excepto el ID del flujo de trabajo, son opcionales. Los campos que omitas utilizarán la configuración guardada del agente.

Campo	Qué hace
`projectId`	Proyecto en el que se ejecutará. De forma predeterminada, es `"personal"`.
`file_ids`, `folder_ids`	Archivos y carpetas asociados a la ejecución.
`tabular_review_ids`	Revisiones tabulares asociadas a la ejecución.
`playbook_ids`	Playbooks asociados a la ejecución.
`skill_ids`	Habilidades asociadas a la ejecución.
`email_ids`	Correos electrónicos asociados a la ejecución.
`workflow_ids`	Flujos de trabajo asociados a la ejecución.
`workflow_ids_override`	Reemplaza los flujos de trabajo asociados predeterminados del agente.
`run_context`	Contexto de la ejecución.
`inputs`	Mapa de nombres de entrada a valores de cadena.
`input_bindings`	Vinculaciones de entrada del flujo de trabajo.
`allow_human_input`	Indica si la ejecución puede pausarse para solicitar la intervención de una persona. Booleano opcional; su valor predeterminado es `true`.

Usar los valores predeterminados guardados o reemplazarlos

Los archivos adjuntos y el mapa de inputs reemplazan los valores predeterminados guardados del agente. Si los omites, la ejecución utiliza los valores predeterminados que devuelve GET /workflows/{workflowId}/run-inputs.

Ejecutar sin intervención humana

Establece allow_human_input en false para que la ejecución no sea interactiva. La ejecución no puede pedir nada a una persona: no se generan tarjetas de aprobación y las herramientas ask-the-user y wait-for-human-input no están disponibles. El agente continúa con los documentos adjuntos, las entradas proporcionadas o predeterminadas y la definición del agente. Los valores ambiguos o ausentes se tratan como suposiciones y se informan en lugar de bloquear la ejecución.

Si la ejecución realmente no puede continuar sin intervención humana, falla con un error del tipo Run requires human input that cannot be provided: ... en lugar de quedarse pausada.

Las ejecuciones iniciadas desde el portal de August siempre utilizan este comportamiento no interactivo y terminan con un resultado de finalización, advertencia o error, en lugar de permanecer pausadas. La ruta interactiva que desactiva allow_human_input: false se describe en Reanudar una ejecución de agente en espera de intervención humana.

Resultados de la ejecución

Una ejecución termina con uno de tres resultados:

Completada correctamente. El contrato de salida se cumplió sin problemas.
Completada con advertencias. La ejecución entregó su resultado, pero algo no salió según lo previsto: por ejemplo, no se pudo identificar una entrada, faltaba un elemento obligatorio o un paso continuó basándose en una suposición. Las superficies de ejecución muestran el estado «Completed with warnings» y la explicación de la advertencia aparece en los detalles de la ejecución. Revisa las suposiciones o las entradas que faltan antes de confiar en el resultado.
Fallida. Se reserva para errores reales de la plataforma o del control de la ejecución, incluida una ejecución no interactiva que necesitaba una intervención humana que no pudo obtener.

Qué leer a continuación

Ejecutar un agente para iniciar ejecuciones en la interfaz de usuario del producto
Activadores de agentes para automatizaciones basadas en eventos y programaciones
Reanudar una ejecución de agente en espera de intervención humana para la ruta interactiva

¿Te fue útil?