waiting_for_human) ou une condition d’arrêt (stopped) n’est pas une erreur : les deux renvoient un résultat normal. Les échecs qui envoient aussi un événement run.failed diffèrent selon le langage ; ne vous fiez donc pas au seul événement pour détecter un échec.
Comment se manifeste une exécution qui échoue
Événements émis en cas d’échec
Hooks de cycle de vie liste tous les événements.
Trouver la cause d’une erreur
Types d’erreurs TypeScript
AgentGatewayError contient status, statusText, headers, body, requestId, generationId, reason, errorType, errorOrigin, failedProviders, failedStatuses et des diagnostics de routage. Les exécutions et étapes échouées conservent les mêmes détails dans errorDetails. Un échec au milieu d’une réponse diffusée est une AgentStreamError, une sous-classe avec code et retryable.
AgentSchemaValidationError a un target parmi tool_input, tool_output, tool_event ou agent_output, et des details contenant l’erreur du validateur. Traitez-les comme des violations de contrat, et non comme des échecs passagers du modèle.
Pour classer n’importe quelle erreur, par exemple dans modelRetry.retryOn, utilisez agentErrorIsRetryable(error), agentRetryAfterMs(error) et agentErrorIsContextOverflow(error).
Type d’erreur Rust
Tout échec à l’exécution est uneAgentError ; lisez-la avec message(). Les valeurs PhaseoError du gateway sont converties en AgentError ; si vous avez besoin du statut et du corps d’origine du gateway, appelez directement le client phaseo ou implémentez un ModelClient personnalisé qui les conserve.
Se remettre des erreurs d’outil
Par défaut, une erreur d’outil fait échouer l’exécution. Définissez la politique d’erreur de l’outil surreturn-to-model quand le modèle peut raisonnablement essayer autre chose : l’erreur devient le résultat de l’outil {"error": "..."} et l’exécution continue. Gardez la valeur par défaut, fail-run, pour les échecs dangereux ou irrécupérables.
Gérer l’annulation et les dépassements de délai
Un dépassement de délai ou une annulation n’arrête pas toujours le travail propre à l’outil. Donnez leurs propres échéances aux appels HTTP, base de données et processus à l’intérieur des outils, et considérez une exécution annulée ou expirée comme terminée, sauf si votre application en démarre une nouvelle.Reprendre une exécution TypeScript interrompue
Si une exécution a planté ou a été annulée au milieu d’une étape, son historique peut contenir des appels d’outils sans résultat, que les fournisseurs rejettent. LecontinueRun() de TypeScript y répond comme non exécutés et envoie history.repaired. Appelez vous-même repairToolHistory(messages) si vous réutilisez les messages ailleurs.
Vérifier d’abord ces points
PHASEO_API_KEYparvient au processus et est passé au client gateway.- Chaque outil a un ID unique et stable.
- Les approbations, les rejets et les sorties d’outils utilisent les ID d’appel d’outil exacts, et un message de saisie humaine ne remplace jamais une sortie d’outil.
- Le résultat d’exécution complet est enregistré avant d’afficher une interface d’approbation ou de passer la main à une autre requête ou à un autre worker.
- Les validateurs sont déterministes et sans effets de bord, pour qu’une vérification échouée puisse être réessayée sans risque.
- Les nouvelles tentatives du modèle sont bornées ; les échecs de validation et d’approbation ne doivent pas être réessayés aveuglément.
step.started, model.requested et tool.failed avec les hooks de cycle de vie, et consultez Observabilité pour les ID qui relient une étape aux journaux du gateway.