Activar una ejecución de un agente mediante la API

POST /workflows/{workflowId}/run inicia una ejecución de agente mediante la API pública de August. La llamada es asíncrona: devuelve run_id de inmediato y puedes consultar GET /workflows/{workflowId}/runs/{runId} para obtener el estado y los resultados.

Antes de empezar

La operación de ejecución está protegida. August verifica que quien realiza 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), question_id (o null) y un mensaje de Agent run started o Agent run already existed.
Consulta GET /workflows/{workflowId}/runs/{runId} con el run_id devuelto hasta que finalice la ejecución.

Para enumerar las 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 usará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; de forma predeterminada, es `true`.
`notify_email`	Envía por correo electrónico los resultados documentales de August de la ejecución a esta dirección desde el buzón de August, cuando el correo electrónico de la plataforma está habilitado para la cuenta.

Usar los valores predeterminados guardados o anularlos

Los archivos 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.

Enviar los resultados por correo electrónico

Establece notify_email para que los resultados documentales de August de la ejecución se envíen por correo electrónico desde el buzón de August a un destinatario que elijas. La entrega por correo electrónico funciona cuando el correo electrónico de la plataforma está habilitado para la cuenta; si no lo está, la ejecución se inicia y finaliza igualmente, pero no se envía ningún correo.

Ejecuciones que se pausan para solicitar la intervención de una persona

De forma predeterminada, una ejecución mediante la API se comporta como una ejecución programada: si llega a un paso de pregunta 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, por lo que el usuario propietario de la clave de API responde a la ejecución en la aplicación web de August, tal como se describe en Reanudar una ejecución de agente en espera de la intervención de una persona.

Ejecutar sin intervención humana

Establece allow_human_input en false cuando no haya nadie disponible para responder, por ejemplo, cuando tu propio portal de clientes inicia la ejecución. La ejecución no puede preguntar 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.

Los valores ambiguos o faltantes se tratan como suposiciones y se notifican como advertencias, por lo que normalmente la ejecución termina como Completada con advertencias en lugar de bloquearse. Solo si la ejecución llega a un punto en el que tendría que pausarse, falla con un error de la forma Run requires human input that cannot be provided: ....

Un agente también puede guardarse como no interactivo, en cuyo caso todas sus ejecuciones se comportan de esta manera, independientemente de lo que envíes en allow_human_input.

Resultados de la ejecución

Una ejecución termina con uno de estos tres resultados:

Correcta. El contrato de salida se cumplió sin problemas.
Completada con advertencias. La ejecución proporcionó sus resultados, 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 faltantes antes de confiar en los resultados.
Fallida. Se reserva para fallos 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 programadas y activadas por cargas
Reanudar una ejecución de agente en espera de la intervención de una persona para el flujo interactivo

¿Te fue útil?