Agentes

Acionar uma execução de agente pela API

POST /workflows/{workflowId}/run inicia uma execução de agente pela API pública do August. A chamada é assíncrona: ela retorna um run_id imediatamente, e você consulta GET /workflows/{workflowId}/runs/{run_id} para obter o status e a saída.

Antes de começar

A operação de execução é protegida. O August verifica se o chamador pode acessar o workflow do agente, incluindo o projeto ao qual ele pertence e quaisquer workflows anexados diretamente à execução ou por meio de associações de entrada.

Enviar a solicitação de execução

A operação é POST /workflows/{workflowId}/run, descrita na API como "Executar um agente".

  1. Envie POST /workflows/{workflowId}/run com os campos necessários no corpo da solicitação (consulte a tabela abaixo).

  2. Leia a resposta. Ela retorna run_id, workflow_id, chat_id (ou null) e uma mensagem de Execução do agente iniciada ou A execução do agente já existia.

  3. Consulte GET /workflows/{workflowId}/runs/{run_id} com o run_id retornado até a execução ser concluída.

Campos do corpo da solicitação

Todos os campos, exceto o ID do workflow, são opcionais. Os campos omitidos usam a configuração salva do agente.

Campo

O que ele faz

projectId

Projeto no qual a execução será realizada. O padrão é "personal".

file_ids, folder_ids

Arquivos e pastas anexados à execução.

tabular_review_ids

Revisões tabulares anexadas à execução.

playbook_ids

Playbooks anexados à execução.

skill_ids

Habilidades anexadas à execução.

email_ids

E-mails anexados à execução.

workflow_ids

Workflows anexados à execução.

workflow_ids_override

Substitui os workflows anexados padrão do agente.

run_context

Contexto da execução.

inputs

Mapa de nomes de entrada para valores de string.

input_bindings

Associações de entradas do workflow.

allow_human_input

Indica se a execução pode ser pausada para aguardar uma entrada humana. Booleano opcional; o padrão é true.

Usar padrões salvos ou substituí-los

Os anexos e o mapa inputs substituem os padrões salvos do agente. Se você os omitir, a execução usará os padrões retornados por GET /workflows/{workflowId}/run-inputs.

Executar sem entrada humana

Defina allow_human_input como false para tornar a execução não interativa. A execução não poderá fazer perguntas a uma pessoa: nenhum cartão de aprovação será emitido, e as ferramentas ask-the-user e wait-for-human-input ficarão indisponíveis. O agente continuará usando os documentos anexados, as entradas fornecidas ou padrão e a definição do agente. Valores ambíguos ou ausentes serão tratados como suposições e relatados, em vez de bloquearem a execução.

Se a execução realmente não puder prosseguir sem entrada humana, ela falhará com um erro no formato Run requires human input that cannot be provided: ..., em vez de permanecer pausada.

As execuções iniciadas dentro do portal do August sempre usam esse comportamento não interativo e terminam com um resultado de conclusão, aviso ou falha, em vez de permanecerem pausadas. O caminho interativo desativado por allow_human_input: false está descrito em Retomar uma execução de agente aguardando entrada humana.

Resultados da execução

Uma execução termina com um de três resultados:

  • Concluída com sucesso. O contrato de saída foi cumprido sem problemas.

  • Concluída com avisos. A execução entregou a saída, mas algo não ocorreu conforme o planejado: por exemplo, não foi possível identificar uma entrada, um item obrigatório estava ausente ou uma etapa prosseguiu com base em uma suposição. As telas de execução mostram o status "Concluída com avisos", e a explicação do aviso aparece nos detalhes da execução. Revise as suposições ou as entradas ausentes antes de confiar na saída.

  • Falha. Reservado para falhas genuínas da plataforma ou do controle da execução, incluindo uma execução não interativa que precisou de uma entrada humana que não pôde obter.

O que ler em seguida

Isso foi útil?
Isso foi útil?