Execuções · Documentação da Ephemeral

Uma execução é um agente trabalhando em uma tarefa na própria microVM. Você envia um prompt, uma entrada em JSON e os arquivos e conexões que ele pode usar. O Ephemeral coloca a execução na fila, inicia uma máquina nova, registra cada etapa e destrói a máquina quando a execução termina.

Do que uma execução é feita

Toda execução tem um prompt e, opcionalmente, uma entrada. O restante da definição determina qual modelo ela usa, o que pode ler, o que pode chamar, quanto tempo pode levar e quanto pode gastar. Você pode enviar a definição completa em linha ou indicar o nome de um fluxo de trabalho salvo e enviar apenas a entrada.

POST /v1/runs

{
  "prompt": "Find out why this payment failed. Follow the playbook.",
  "input": { "payment_id": "pay_123" },
  "model": "anthropic/claude-haiku-5.5",
  "files": [{ "file": "playbook.md" }],
  "connections": { "payments": { "ref": "payments-api", "allowed_methods": ["GET"] } },
  "timeout_seconds": 120,
  "shell": false,
  "max_cost_micros": 500000
}

Dentro da microVM, o agente sempre pode ler os arquivos que você montou. Com shell ativado, que é o padrão, ele também pode executar comandos de shell e gravar arquivos no seu diretório de trabalho. Cada conexão concedida adiciona ferramentas que ele pode chamar e, com o acesso à web ativado, ele pode ler páginas, pesquisar e chamar APIs públicas. A própria máquina não tem acesso à internet. O diretório de trabalho é descartado junto com a máquina, então nada passa para a execução seguinte.

Ciclo de vida

Uma execução passa por estes status. Os cinco últimos são finais: quando a execução chega a um deles, ele não muda mais.

Status	Significado
`reserving`	Somente no serviço hospedado. Os créditos do orçamento da execução estão sendo reservados.
`queued`	Aguardando uma vaga livre de worker.
`starting`	Retirada da fila. A definição e os arquivos estão sendo carregados.
`running`	A microVM está iniciando ou o agente está trabalhando.
`succeeded`	O agente terminou e retornou uma saída.
`failed`	O worker falhou ou não foi possível reservar os créditos. O campo error indica qual dos dois.
`cancelled`	Alguém cancelou a execução.
`timed_out`	A execução atingiu o timeout antes de terminar.
`interrupted`	O mecanismo foi reiniciado durante a execução ou a admissão não foi concluída.

As execuções saem da fila na ordem em que foram criadas. Uma instalação auto-hospedada executa duas por vez por padrão; as demais aguardam em queued. O timeout conta a partir do momento em que a execução sai da fila, então o tempo de espera não o consome.

Limites

Limite	Valor
`timeout_seconds`	De 1 a 3.600. Padrão: 300.
Prompt	128 KiB
Entrada	1 MiB de JSON
Arquivos	32 por execução, 1 MiB cada, 4 MiB no total
Conexões	16 por execução
Chamadas ao modelo	100 por execução
Saída por resposta do modelo	O limite do próprio modelo, até 32.000 tokens, reduzido para caber no que resta do orçamento. Uma resposta cortada no limite é continuada automaticamente, no máximo duas vezes.
Requisições e pesquisas na web	50 por execução, quando o acesso à web está ativado
Saída	Até 1 MiB. Uma resposta maior é cortada nesse ponto, e a execução registra que isso aconteceu.
Eventos	O registro guarda até 256 KiB por evento e 10.000 eventos ou 16 MiB por execução. Resultados de ferramentas maiores são encurtados no registro e marcados; o agente ainda os recebe por completo. Quando o registro enche, os detalhes posteriores são descartados e contados. Nenhum dos dois casos faz a execução falhar.
`max_cost_micros`	De 1 a 100.000.000 (até $100)

Acompanhando uma execução

Há três maneiras de saber o que uma execução está fazendo e quando ela termina.

Consulte GET /v1/runs/{id} até que o status seja final.
Transmita GET /v1/runs/{id}/events. É um stream de eventos enviados pelo servidor que reproduz tudo o que foi registrado até então e continua ao vivo até a execução terminar.
Defina um callback na execução. O Ephemeral envia uma requisição assinada ao seu servidor quando a execução chega a um status final.

Fechar o stream de eventos não afeta a execução. Você pode se reconectar com o ID do último evento recebido e continuar a partir dele.

Tipos de evento

Tipo	Registrado quando
`status`	A execução começa a rodar ou chega a um status final.
`microvm_starting`	O Ephemeral solicita uma microVM.
`microvm_ready`	A microVM está no ar.
`worker_started`	O processo do agente é iniciado. Inclui se o shell está ativado.
`connection_ready`	Uma conexão MCP está pronta, com as ferramentas que a execução pode chamar.
`tool_start`	O agente chama uma ferramenta. Inclui os argumentos.
`tool_end`	Uma chamada de ferramenta retorna. Inclui o resultado e se houve erro. Um resultado acima de 256 KiB é encurtado aqui e traz trimmed_from_bytes.
`text_delta`	O modelo transmite texto, em lotes cerca de dez vezes por segundo.
`model_usage`	Uma resposta do modelo termina. Uso de tokens conforme informado pelo worker; não é usado para cobrança.
`usage`	O Ephemeral autoriza ou concilia o custo de uma chamada ao modelo.
`connection`	O mecanismo faz uma requisição HTTP ou uma chamada de ferramenta MCP em nome da execução.
`web_request`	O mecanismo envia uma requisição web para o agente. Inclui a URL, o status, o custo e a verificação de segurança.
`web_search`	O mecanismo faz uma pesquisa na web para o agente.
`web_refused`	Uma requisição ou pesquisa na web foi recusada antes de ser enviada. Inclui o motivo.
`result`	O agente retorna sua saída final. O campo output da execução contém tudo; este evento pode ser encurtado.
`model_call_refused`	Uma chamada ao modelo foi recusada, por exemplo porque seu custo no pior caso excede o que resta do orçamento. Inclui o motivo.
`output_limit`	Uma resposta atingiu o limite de saída do modelo e o agente foi instruído a continuar.
`output_truncated`	A saída final era maior que 1 MiB e foi cortada nesse ponto.
`events_skipped`	O registro da execução estava cheio, então os eventos posteriores não foram armazenados. Inclui quantos.
`worker_error`	O worker é interrompido por um erro.
`microvm_terminated`	Confirma-se que a microVM foi destruída.
`microvm_cleanup_pending`	Ainda não foi possível confirmar o encerramento; ele será tentado de novo.
`done`	Última mensagem do stream. Traz o objeto final da execução.

O Ephemeral remove valores de credenciais conhecidos, como tokens de conexão, dos eventos e da saída antes de armazená-los. A referência da API mostra o formato exato do stream.

Cancelando uma execução

POST /v1/runs/{id}/cancel interrompe uma execução em reserving, queued, starting ou running. O worker é interrompido e a microVM é encerrada. Cancelar uma execução que já terminou não muda nada.

O cancelamento não desfaz ações externas

Se o agente já chamou uma API que alterou algo, como emitir um reembolso, cancelar a execução não reverte a alteração. O mesmo vale para execuções que falham, atingem o timeout ou são interrompidas. O Ephemeral nunca tenta uma execução de novo automaticamente, então um efeito colateral também não se repete.

Retenção zero de dados

Defina zero_data_retention como true em uma execução, ou em um fluxo de trabalho salvo, quando a tarefa for sensível. A Ephemeral então não registra nada do conteúdo da execução: você recebe apenas a saída.

Mantido	Não mantido
ID da execução, organização, status, carimbos de data e hora, agendamento, valores de custo e uso, e uma categoria de erro genérica sem texto do worker.	Os eventos e a saída depois de entregue, o texto de erro do worker e a definição da execução: prompt, entrada, lista de arquivos e referências de conexões. A definição de uma execução assim não pode ser consultada nem executada de novo.

Os eventos continuam chegando em tempo real enquanto a execução trabalha, por GET /v1/runs/{id}/events em qualquer mecanismo. Ficam em um armazenamento transitório e são apagados alguns minutos depois do fim da execução.
A saída é devolvida uma vez. O primeiro GET /v1/runs/{id} depois do fim da execução a inclui e a apaga. Com um callback, ele entrega a saída e as leituras a deixam onde está até lá. De qualquer forma, ela é apagada em no máximo uma hora. output_available e output_expires_at mostram se ainda está guardada.
As chamadas ao modelo vão apenas a provedores que não retêm seus dados nem os usam para treinamento. Um modelo sem esse tipo de provedor é recusado com 400 antes de reservar qualquer coisa.
No serviço hospedado a execução custa 10% a mais: o acréscimo vale para computação, chamadas ao modelo e requisições web, conta para o orçamento e aparece no detalhamento do custo. Instalações auto-hospedadas não cobram nada a mais.
Os dados transitórios ficam em tabelas que todos os backups deixam de fora, então um banco restaurado nunca os contém.

Depois de uma execução

A execução mantém sua saída, mensagem de erro, carimbos de data e hora, eventos e custo. Considere o custo definitivo quando o status for final e billing_pending for false; veja orçamentos e faturamento.

As execuções concluídas são excluídas 30 dias depois de terminarem, junto com seus eventos. Uma execução é mantida por mais tempo enquanto o faturamento, a entrega do callback ou a limpeza da microVM ainda estiverem pendentes. As instalações auto-hospedadas podem alterar o período de retenção.

Para executar a mesma tarefa de novo, obtenha GET /v1/runs/{id}/definition. Ele retorna a definição que a execução realmente usou, sem as credenciais, para que você possa revisá-la, definir um novo orçamento e enviá-la.

A definição de uma execução guarda o prompt, a entrada e o conteúdo dos arquivos em linha que você enviou. Não coloque segredos neles; use uma conexão salva.