Gancho de manejo de errores

Se llama al onErrorOccurred gancho cuando ocurren errores durante la ejecución de la sesión. Utilícelo para:

• Implementación del registro de errores personalizado
• Seguimiento de patrones de error
• Proporcionar mensajes de error fáciles de entender
• Desencadenar alertas para errores críticos

Firma de hook

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

Para obtener firmas de enlace en Python, Go y .NET, consulte el github/copilot-sdk repositorio.

Entrada

Campo	Tipo	Descripción
timestamp	número	Marca de tiempo de Unix cuando se produjo el error
cwd	cuerda / cadena	Directorio de trabajo actual
error	cuerda / cadena	Mensaje de error
errorContext	cuerda / cadena	Donde se produjo el error: "model_call", "tool_execution", "system"o "user_input"
recoverable	boolean	Si es posible recuperarse del error

Salida

Devuelve null o undefined para usar el control de errores predeterminado. De lo contrario, devuelve un objeto con cualquiera de los campos siguientes.

Campo	Tipo	Descripción
suppressOutput	boolean	Si es true, no muestre la salida de error al usuario.
errorHandling	cuerda / cadena	Cómo controlar: "retry", "skip"o "abort"
retryCount	número	Número de veces que se reintenta (si errorHandling es "retry")
userNotification	cuerda / cadena	Mensaje personalizado para mostrar al usuario

Ejemplos

Registro de errores básico

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

Para obtener ejemplos en Python, Go y .NET, consulte el github/copilot-sdk repositorio.

Envío de errores al servicio de supervisión

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

Mensajes de error fáciles de usar

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

Suprimir errores no críticos

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

Agregar contexto de recuperación

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

Seguimiento de patrones de error

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

Alerta sobre errores críticos

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

procedimientos recomendados

•         **Registre siempre los errores.** Incluso si los suprime de los usuarios, mantenga los registros para la depuración.
  

•         **Clasificar los errores.** Use `errorContext` para controlar los distintos errores de forma adecuada.
  

•         **No trague errores críticos.** Solo suprime los errores que está seguro que no son críticos.
  

•         **Mantenga los ganchos seguros.** El control de errores no debe ralentizar la recuperación.
  

•         **Supervise los patrones de error.** Realice un seguimiento de los errores periódicos para identificar problemas sistémicos.
  

Lectura adicional

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