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 é umAgentError; 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 comoreturn-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. OcontinueRun() 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_KEYchega 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.
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.