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 :

• 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 de point d'interception

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

Pour obtenir les signatures de hook dans Python, Go et .NET, consultez le github/copilot-sdk référentiel.

Input

Champ	Type	Description
timestamp	nombre	Horodatage Unix lorsque l’erreur s’est produite
cwd	ficelle	Répertoire de travail actuel
error	ficelle	Message d'erreur
errorContext	ficelle	Où l’erreur s’est produite : "model_call", "tool_execution", "system"ou "user_input"
recoverable	booléen	Indique 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 l’un des champs suivants.

Champ	Type	Description
suppressOutput	booléen	Si la valeur est true, n’affichez pas la sortie d’erreur à l’utilisateur
errorHandling	ficelle	Guide pratique pour gérer : "retry", "skip"ou "abort"
retryCount	nombre	Nombre de tentatives à réessayer (si errorHandling est "retry")
userNotification	ficelle	"Message personnalisé à montrer à l'utilisateur"

Exemples

Journalisation des erreurs de base

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;
    },
  },
});

Pour obtenir des exemples dans Python, Go et .NET, consultez le github/copilot-sdk référentiel.

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:\n"
            + "- Check if required dependencies "
            + "are installed\n"
            + "- Verify file paths are correct\n"
            + "- Try a simpler approach",
        };
      }

      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;
    },
  },
});

Bonnes pratiques

•         **Consignez toujours les erreurs.** Même si vous les supprimez des utilisateurs, conservez les journaux d’activité pour le débogage.
  

•         **Catégoriser les erreurs.** Permet `errorContext` de gérer les différentes erreurs de manière appropriée.
  

•         **N’avalez pas les erreurs critiques.** Supprimez uniquement les erreurs dont vous êtes certain qu'elles ne sont pas critiques.
  

•         **Gardez les crochets bien serrés.** La gestion des erreurs ne doit pas ralentir la récupération.
  

•         **Surveillez les modèles d’erreur.** Suivez les erreurs récurrentes pour identifier les problèmes systémiques.
  

Lectures complémentaires

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/quickstart)
  

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/session-lifecycle)
  

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/pre-tool-use)