Pular para o conteúdo principal
Uma execução com falha lança ou retorna um erro a partir da chamada de run ou de continuação. Uma pausa (waiting_for_human) ou uma condição de parada (stopped) não é um erro: as duas retornam um resultado normal. Quais falhas também enviam um evento run.failed varia por linguagem, então não dependa só do evento para detectar uma falha.

Como uma execução com falha aparece

Quais eventos são disparados quando algo falha

Hooks do ciclo de vida lista todos os eventos.

Encontre a causa de um erro

Tipos de erro do TypeScript

AgentGatewayError tem status, statusText, headers, body, requestId, generationId, reason, errorType, errorOrigin, failedProviders, failedStatuses e diagnósticos de roteamento. Execuções e etapas com falha guardam os mesmos detalhes em errorDetails. Uma falha no meio de uma resposta transmitida é um AgentStreamError, uma subclasse com code e retryable. AgentSchemaValidationError tem um target igual a tool_input, tool_output, tool_event ou agent_output, e details com o erro do validador. Trate esses casos como falhas de contrato, não como falhas transitórias do modelo. Para classificar qualquer erro, por exemplo em modelRetry.retryOn, use agentErrorIsRetryable(error), agentRetryAfterMs(error) e agentErrorIsContextOverflow(error).

Tipo de erro do Rust

Toda falha do runtime é um AgentError; leia-o com message(). Os valores PhaseoError do gateway são convertidos em AgentError, então, se você precisar do status e do corpo originais do gateway, chame o cliente phaseo diretamente ou implemente um ModelClient personalizado que os preserve.

Recupere-se de erros de ferramenta

Por padrão, um erro de ferramenta faz a execução falhar. Defina a política de erro da ferramenta como return-to-model quando o modelo puder razoavelmente tentar outra coisa: o erro vira o resultado da ferramenta {"error": "..."} e a execução continua. Mantenha o padrão, fail-run, para falhas inseguras ou irrecuperáveis.

Trate cancelamentos e timeouts

Um timeout ou cancelamento de ferramenta nem sempre interrompe o trabalho da própria ferramenta. Dê prazos próprios às chamadas HTTP, de banco de dados e de processos dentro das ferramentas, e trate uma execução cancelada ou com timeout como encerrada, a menos que seu aplicativo inicie uma nova.

Recupere uma execução do TypeScript interrompida

Se uma execução travou ou foi cancelada no meio de uma etapa, o histórico dela pode conter chamadas de ferramenta sem resultado, que os provedores rejeitam. O continueRun() do TypeScript as responde como não executadas e envia history.repaired. Chame repairToolHistory(messages) você mesmo se reutilizar as mensagens em outro lugar.

Verifique isto primeiro

  • PHASEO_API_KEY chega ao processo e é passada ao cliente de gateway.
  • Cada ferramenta tem um ID único e estável.
  • Aprovações, rejeições e saídas de ferramentas usam os IDs exatos das chamadas de ferramenta, e uma mensagem de entrada humana nunca substitui uma saída de ferramenta.
  • O resultado inteiro da execução é salvo antes de você mostrar uma interface de aprovação ou passar o controle para outra requisição ou worker.
  • Os validadores são determinísticos e sem efeitos colaterais, então uma verificação que falhou pode ser repetida com segurança.
  • As novas tentativas do modelo são limitadas; falhas de validação e de aprovação não devem ser repetidas às cegas.
Para ver qual etapa falhou, registre step.started, model.requested e tool.failed com os hooks do ciclo de vida, e veja em Observabilidade os IDs que ligam uma etapa aos logs do gateway.
Última modificação em 5 de novembro de 2026