Iniciar 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 run_id de inmediato, y luego consultas GET /workflows/{workflowId}/runs/{runId} para obtener el estado y la salida.

Antes de empezar

La operación de ejecución está protegida. August verifica que quien llama pueda acceder al flujo de trabajo del agente, incluido el proyecto al que pertenece y cualquier flujo de trabajo adjunto a la ejecución directamente o a través de enlaces de entrada.

Enviar la solicitud de ejecución

La operación es POST /workflows/{workflowId}/run, descrita en la API como "Run an agent".

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

Para listar ejecuciones anteriores de un agente, llama a GET /workflows/{workflowId}/runs.

Campos del cuerpo de la solicitud

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

Campo	Qué hace
`projectId`	Proyecto en el que se ejecutará. El valor predeterminado es `"personal"`.
`file_ids`, `folder_ids`	Archivos y carpetas adjuntos a la ejecución.
`tabular_review_ids`	Revisiones tabulares adjuntas a la ejecución.
`playbook_ids`	Playbooks adjuntos a la ejecución.
`skill_ids`	Skills adjuntas a la ejecución.
`email_ids`	Emails adjuntos a la ejecución.
`workflow_ids`	Flujos de trabajo adjuntos a la ejecución.
`workflow_ids_override`	Reemplaza los flujos de trabajo adjuntos predeterminados del agente.
`run_context`	Contexto para la ejecución.
`inputs`	Mapa de nombres de entrada a valores de texto.
`input_bindings`	Enlaces de entrada del flujo de trabajo.
`allow_human_input`	Indica si la ejecución puede pausar para solicitar entrada humana. Booleano opcional; el valor predeterminado es `true`.

Usar los valores predeterminados guardados o reemplazarlos

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

Ejecuciones que se pausan para solicitar entrada humana

De forma predeterminada, una ejecución mediante la API se comporta como una ejecución programada: si llega a un paso de Question o le falta una entrada sin la que no puede funcionar, se pausa con el estado waiting. La API pública no tiene ninguna operación para responder, así que el usuario propietario de la clave de API responde a la ejecución en la aplicación web de August, como se describe en Reanudar una ejecución de agente en espera de entrada humana.

Ejecutar sin entrada humana

Establece allow_human_input en false cuando no habrá nadie disponible para responder, por ejemplo, cuando tu propio portal de cliente inicie la ejecución. La ejecución no puede pedirle nada a una persona: no se emiten 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.

Las valores ambiguos o faltantes se tratan como suposiciones y se notifican como advertencias, por lo que la ejecución normalmente termina como Completed with warnings en lugar de bloquearse. Solo si la ejecución aún llega a un punto en el que tendría que pausar, falla con un error del tipo Run requires human input that cannot be provided: ....

Un agente también puede guardarse como no interactivo; en ese caso, todas sus ejecuciones se comportan así, sin importar lo que envíes en allow_human_input.

Resultados de la ejecución

Una ejecución termina con uno de tres resultados:

Succeeded. Se satisfizo correctamente el contrato de salida.
Completed with warnings. La ejecución entregó su salida, pero algo no salió como estaba previsto: por ejemplo, no se pudo identificar una entrada, faltaba un elemento requerido o un paso continuó basándose en una suposición. En las pantallas de ejecución aparece 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 faltantes antes de confiar en la salida.
Failed. Reservado para fallos reales de la plataforma o del control de la ejecución, incluida una ejecución no interactiva que necesitaba entrada humana y no pudo obtenerla.

Qué leer a continuación

Run an agent para iniciar ejecuciones en la interfaz de usuario del producto
Agent Triggers para automatizaciones programadas y activadas por carga
Resume an agent run waiting on human input para el flujo interactivo

¿Te fue útil?