Hook de gestion des erreurs

Le onErrorOccurred hook est appelé lorsque des erreurs se produisent pendant l’exécution de la session. Utilisez-le pour :

Dans cet article

  • Implémenter la journalisation des erreurs personnalisées
  • Suivre les modèles d’erreur
  • Fournir des messages d’erreur conviviaux
  • Déclencher des alertes pour les erreurs critiques

Signature du hook

Langages de code navigation

TypeScript
import type { ErrorOccurredHookInput, HookInvocation, ErrorOccurredHookOutput } from "@github/copilot-sdk";
type ErrorOccurredHandler = (
  input: ErrorOccurredHookInput,
  invocation: HookInvocation
) => Promise<ErrorOccurredHookOutput | null | undefined>;

type ErrorOccurredHandler = (
  input: ErrorOccurredHookInput,
  invocation: HookInvocation
) => Promise<ErrorOccurredHookOutput | null | undefined>;

Input

ChampCatégorieDescription
timestampNuméroHorodatage Unix lorsque l’erreur s’est produite
cwdstringRépertoire de travail actuel
errorstringMessage d’erreur
errorContextstringOù l’erreur s’est produite : "model_call", "tool_execution", "system"ou "user_input"
recoverablebooléenIndique si l’erreur peut potentiellement être récupérée à partir de

Sortie

Retournez null ou undefined pour utiliser la gestion des erreurs par défaut. Sinon, retournez un objet avec :

ChampCatégorieDescription
suppressOutputbooléenSi la valeur est true, n’affichez pas la sortie d’erreur à l’utilisateur
errorHandlingstringGuide pratique pour gérer : "retry", "skip"ou "abort"
retryCountNuméroNombre de nouvelles tentatives (si errorHandling est "retry")
userNotificationstring"Message personnalisé à montrer à l'utilisateur"

Exemples

Journalisation des erreurs de base

Langages de code navigation

TypeScript
const session = await client.createSession({
  hooks: {
    onErrorOccurred: async (input, invocation) => {
      console.error(`[${invocation.sessionId}] Error: ${input.error}`);
      console.error(`  Context: ${input.errorContext}`);
      console.error(`  Recoverable: ${input.recoverable}`);
      return null;
    },
  },
});

Envoyer des erreurs au service de surveillance

import { captureException } from "@sentry/node"; // or your monitoring service

const session = await client.createSession({
  hooks: {
    onErrorOccurred: async (input, invocation) => {
      captureException(new Error(input.error), {
        tags: {
          sessionId: invocation.sessionId,
          errorContext: input.errorContext,
        },
        extra: {
          error: input.error,
          recoverable: input.recoverable,
          cwd: input.cwd,
        },
      });
      
      return null;
    },
  },
});

Messages d’erreur conviviaux

const ERROR_MESSAGES: Record<string, string> = {
  "model_call": "There was an issue communicating with the AI model. Please try again.",
  "tool_execution": "A tool failed to execute. Please check your inputs and try again.",
  "system": "A system error occurred. Please try again later.",
  "user_input": "There was an issue with your input. Please check and try again.",
};

const session = await client.createSession({
  hooks: {
    onErrorOccurred: async (input) => {
      const friendlyMessage = ERROR_MESSAGES[input.errorContext];
      
      if (friendlyMessage) {
        return {
          userNotification: friendlyMessage,
        };
      }
      
      return null;
    },
  },
});

Supprimer les erreurs non critiques

const session = await client.createSession({
  hooks: {
    onErrorOccurred: async (input) => {
      // Suppress tool execution errors that are recoverable
      if (input.errorContext === "tool_execution" && input.recoverable) {
        console.log(`Suppressed recoverable error: ${input.error}`);
        return { suppressOutput: true };
      }
      return null;
    },
  },
});

Ajouter un contexte de récupération

const session = await client.createSession({
  hooks: {
    onErrorOccurred: async (input) => {
      if (input.errorContext === "tool_execution") {
        return {
          userNotification: `
The tool failed. Here are some recovery suggestions:
- Check if required dependencies are installed
- Verify file paths are correct
- Try a simpler approach
          `.trim(),
        };
      }
      
      if (input.errorContext === "model_call" && input.error.includes("rate")) {
        return {
          errorHandling: "retry",
          retryCount: 3,
          userNotification: "Rate limit hit. Retrying...",
        };
      }
      
      return null;
    },
  },
});

Suivre les modèles d’erreur

interface ErrorStats {
  count: number;
  lastOccurred: number;
  contexts: string[];
}

const errorStats = new Map<string, ErrorStats>();

const session = await client.createSession({
  hooks: {
    onErrorOccurred: async (input, invocation) => {
      const key = `${input.errorContext}:${input.error.substring(0, 50)}`;
      
      const existing = errorStats.get(key) || {
        count: 0,
        lastOccurred: 0,
        contexts: [],
      };
      
      existing.count++;
      existing.lastOccurred = input.timestamp;
      existing.contexts.push(invocation.sessionId);
      
      errorStats.set(key, existing);
      
      // Alert if error is recurring
      if (existing.count >= 5) {
        console.warn(`Recurring error detected: ${key} (${existing.count} times)`);
      }
      
      return null;
    },
  },
});

Alerte sur les erreurs critiques

const CRITICAL_CONTEXTS = ["system", "model_call"];

const session = await client.createSession({
  hooks: {
    onErrorOccurred: async (input, invocation) => {
      if (CRITICAL_CONTEXTS.includes(input.errorContext) && !input.recoverable) {
        await sendAlert({
          level: "critical",
          message: `Critical error in session ${invocation.sessionId}`,
          error: input.error,
          context: input.errorContext,
          timestamp: new Date(input.timestamp).toISOString(),
        });
      }
      
      return null;
    },
  },
});

Combiner avec d’autres hooks pour le contexte

const sessionContext = new Map<string, { lastTool?: string; lastPrompt?: string }>();

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input, invocation) => {
      const ctx = sessionContext.get(invocation.sessionId) || {};
      ctx.lastTool = input.toolName;
      sessionContext.set(invocation.sessionId, ctx);
      return { permissionDecision: "allow" };
    },
    
    onUserPromptSubmitted: async (input, invocation) => {
      const ctx = sessionContext.get(invocation.sessionId) || {};
      ctx.lastPrompt = input.prompt.substring(0, 100);
      sessionContext.set(invocation.sessionId, ctx);
      return null;
    },
    
    onErrorOccurred: async (input, invocation) => {
      const ctx = sessionContext.get(invocation.sessionId);
      
      console.error(`Error in session ${invocation.sessionId}:`);
      console.error(`  Error: ${input.error}`);
      console.error(`  Context: ${input.errorContext}`);
      if (ctx?.lastTool) {
        console.error(`  Last tool: ${ctx.lastTool}`);
      }
      if (ctx?.lastPrompt) {
        console.error(`  Last prompt: ${ctx.lastPrompt}...`);
      }
      
      return null;
    },
  },
});

Bonnes pratiques

  1. Consignez toujours les erreurs - Même si vous les masquez aux utilisateurs, conservez des journaux pour le débogage.

  2. Catégoriser les erreurs : permet errorType de gérer les différentes erreurs de manière appropriée.

  3. Ne masquez pas les erreurs critiques - Ne masquez que les erreurs dont vous êtes certain qu’elles ne sont pas critiques.

  4.           **Veillez à ce que les hooks restent rapides** : la gestion des erreurs ne doit pas ralentir la récupération.

  5. Fournir un contexte utile : lorsque des erreurs se produisent, additionalContext peut aider le modèle à récupérer.

  6. Surveiller les modèles d’erreurs : suivez les erreurs récurrentes pour identifier les problèmes systémiques.

Voir aussi