Fluxos de trabalho

Um fluxo de trabalho é a definição de uma execução salva com um nome. Ele guarda o prompt, o modelo, os arquivos, as conexões, o timeout e as configurações de shell e de web. Seu código o inicia pelo nome e envia apenas o que muda de uma execução para a outra.

{
  "workflow": "investigate-payment",
  "input": { "payment_id": "pay_123" },
  "max_cost_micros": 500000
}

O que é salvo e o que cada execução envia

Salve um fluxo de trabalho no painel, em Fluxos de trabalho, com PUT /v1/workflows/{name} ou com ephemeral workflows save. JSON é o formato de transmissão; a CLI também lê YAML. Os nomes começam com uma letra ou um dígito e podem conter letras, dígitos, _, . e -, com até 128 caracteres.

Substituindo campos salvos

Qualquer um entre prompt, model, files, connections, timeout_seconds, shell e web na requisição da execução substitui o valor salvo apenas naquela execução. Arquivos e conexões são substituídos como uma coleção inteira. Nunca são mesclados com os salvos.

{
  "workflow": "investigate-payment",
  "input": { "payment_id": "pay_123" },
  "connections": {},
  "max_cost_micros": 500000
}

Um objeto ou uma lista vazia limpa essa coleção para a execução. Para alterar uma conexão ou um arquivo, envie a lista completa que você quer que a execução tenha.

Quando as referências são resolvidas

Um fluxo de trabalho se refere a arquivos e a conexões salvas pelo nome. O Ephemeral resolve esses nomes quando a execução é criada, e a execução guarda o que foi resolvido. Um nome de arquivo é resolvido para o upload mais recente com esse nome, então enviar uma nova versão de playbook.md muda o que a próxima execução lê sem editar o fluxo de trabalho.

Se um arquivo ou uma conexão referenciada não existir mais, a requisição da execução falha com 400 e indica a referência ausente. Nada entra na fila e nada é cobrado.

Descrever a entrada e a saída

Três campos opcionais permitem que um fluxo de trabalho descreva a si mesmo, para que pessoas, outro código e agentes de IA saibam como chamá-lo sem ler o prompt. description diz em uma ou duas frases o que o fluxo de trabalho faz e qual entrada ele espera (até 500 caracteres). input_schema é um JSON Schema com o qual o input da execução deve corresponder. output_schema é um JSON Schema com o qual a saída da execução deve corresponder. Os três são retornados por GET /v1/workflows?detail=true e pela ferramenta MCP list_workflows, e também funcionam em uma execução inline.

description: Current weather for a city. Input is a city name.
prompt: Look up the current weather for the city in the input and report it.
web: true
input_schema:
  type: object
  required: [city]
  properties:
    city: { type: string }
output_schema:
  type: object
  required: [city, temperature_c, summary]
  properties:
    city: { type: string }
    temperature_c: { type: number }
    summary: { type: string }

A entrada é verificada quando uma execução é criada, venha ela da API, da CLI, de uma ferramenta MCP ou de um agendamento. Se não corresponder, a solicitação falha com 400 e indica cada problema como um caminho e um motivo, por exemplo input.city: required. Nada entra na fila e nada é cobrado. A entrada de um agendamento é verificada quando você o cria ou altera, e de novo a cada início; um início que deixou de corresponder fica registrado como o último erro do agendamento.

A saída deve ser JSON que corresponda a output_schema. O agente recebe o schema e deve responder apenas com o JSON. Se a resposta não corresponder, ele recebe os erros exatos e deve corrigi-la, até duas vezes. Depois o Ephemeral verifica a saída de novo: se corresponder, a execução fica succeeded, com o texto JSON como saída e sem bloco de código ao redor. Se não corresponder, a execução termina em failed com um error como output did not match output_schema: output.temperature_c: got string, want number, e o texto da saída é mantido para você ver o que o agente escreveu. Uma execução com retenção zero de dados não mantém nenhum detalhe no erro.

Os schemas usam JSON Schema draft 2020-12 (um $schema que indique o draft 7 ou anterior também funciona), com até 32 KiB cada, e só podem se referir a definições dentro do próprio schema, como #/$defs/address. Um schema inválido é recusado com 400 ao salvar o fluxo de trabalho ou criar a execução.

Editando um fluxo de trabalho

Salvar um fluxo de trabalho de novo o substitui. Não há histórico de versões. As execuções criadas antes da alteração mantêm a definição com que foram criadas; para ver exatamente o que uma execução usou, leia a definição dela.

Ler um fluxo de trabalho o retorna sem as credenciais das conexões e sem os segredos das URLs. Se você o salvar de volta sem esses campos, as credenciais armazenadas são mantidas, desde que o tipo de autenticação continue o mesmo.