Fehlerbehandlungs-Hook

Der onErrorOccurred Hook wird aufgerufen, wenn Während der Sitzungsausführung Fehler auftreten. Verwenden Sie es zu folgenden Zwecken:

• Implementieren der benutzerdefinierten Fehlerprotokollierung
• Nachverfolgen von Fehlermustern
• Bereitstellen von benutzerfreundlichen Fehlermeldungen
• Auslösen von Warnungen für kritische Fehler

Hook-Signatur

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

Die Hook-Signaturen in Python, Go und .NET finden Sie im github/copilot-sdk Repository.

Eingabe

Feld	Typ	Beschreibung
timestamp	Zahl	Unix-Zeitstempel, wenn der Fehler aufgetreten ist
cwd	Schnur	Aktuelles Arbeitsverzeichnis
error	Schnur	Fehlermeldung
errorContext	Schnur	Wo der Fehler aufgetreten ist: "model_call", , "tool_execution", , "system"oder "user_input"
recoverable	boolean	Gibt an, ob der Fehler möglicherweise wiederhergestellt werden kann.

Output

Geben Sie null oder undefined zurück, um die standardmäßige Fehlerbehandlung zu verwenden. Geben Sie andernfalls ein Objekt mit einem der folgenden Felder zurück.

Feld	Typ	Beschreibung
suppressOutput	boolean	Wenn "true" ist, wird die Fehlerausgabe für den Benutzer nicht angezeigt.
errorHandling	Schnur	Behandeln von: "retry", "skip", oder "abort"
retryCount	Zahl	Anzahl der Wiederholungsversuche (wenn errorHandling``"retry" ist)
userNotification	Schnur	Benutzerdefinierte Nachricht für den Benutzer anzeigen

Beispiele

Grundlegende Fehlerprotokollierung

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

Beispiele in Python, Go und .NET finden Sie im github/copilot-sdk Repository.

Fehler an den Überwachungsdienst senden

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

Benutzerfreundliche Fehlermeldungen

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

Unterdrücken nicht kritischer Fehler

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

Hinzufügen des Wiederherstellungskontexts

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

Nachverfolgen von Fehlermustern

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

Warnung bei kritischen Fehlern

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

Bewährte Methoden

•         **Protokollieren Sie immer Fehler.** Auch wenn Sie sie von Benutzern unterdrücken, behalten Sie Protokolle für das Debuggen bei.
  

•         **Kategorisieren sie Fehler.** Verwenden Sie `errorContext`, um unterschiedliche Fehler angemessen zu behandeln.
  

•         **Schlucken Sie keine kritischen Fehler.** Nur Fehler unterdrücken, von denen Sie sicher sind, dass sie nicht kritisch sind.
  

•         **Halten Sie Haken fest.** Fehlerbehandlung sollte die Wiederherstellung nicht verlangsamen.
  

•         **Überwachen von Fehlermustern.** Verfolgen Sie wiederkehrende Fehler, um systemische Probleme zu identifizieren.
  

Weiterführende Lektüre

•         [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)