Inicio rápido para ganchos

Los hooks permiten interceptar y personalizar el funcionamiento de las sesiones en puntos clave del ciclo de vida de la conversación de SDK de Copilot. Usa ganchos para:

•         **Ejecución de herramientas de control**: llamadas a herramientas de aprobación, denegación o modificación
  

•         **Transformación de resultados**: modifique las salidas de la herramienta antes de que se procesen.
  

•         **Adición de contexto**: inserción de información adicional al inicio de la sesión
  

•         **Control de errores**: implementación del control de errores personalizado
  

•         **Auditoría y registro**: realizar un seguimiento de todas las interacciones para el cumplimiento
  

Enlaces disponibles

Enlace	Trigger	Caso de uso
onPreToolUse	Antes de que se ejecute una herramienta	Control de permisos, validación de argumentos
onPostToolUse	Después de ejecutar una herramienta	Transformación de resultados, registro
onUserPromptSubmitted	Cuando el usuario envía un mensaje	Modificación rápida, filtrado
onSessionStart	Inicio de la sesión	Agregar contexto, configurar sesión
onSessionEnd	Finaliza la sesión	Limpieza, análisis
onErrorOccurred	Se produce un error	Control de errores personalizado

Inicio rápido

En el ejemplo siguiente se muestra cómo registrar enlaces al crear una sesión en Node.js/TypeScript.

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      console.log(`Tool called: ${input.toolName}`);
      // Allow all tools
      return { permissionDecision: "allow" };
    },
    onPostToolUse: async (input) => {
      console.log(
        `Tool result: ${JSON.stringify(input.toolResult)}`
      );
      return null; // No modifications
    },
    onSessionStart: async (input) => {
      return {
        additionalContext:
          "User prefers concise answers.",
      };
    },
  },
});

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

Contexto de invocación de gancho

Cada hook recibe un parámetro invocation con información sobre el contexto de la sesión actual.

Campo	Tipo	Descripción
sessionId	cuerda / cadena	Identificador de la sesión actual

Esto permite que los hooks conserven el estado o realicen lógica específica de la sesión.

Patrones comunes

Registro de todas las llamadas a herramientas

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      console.log(
        `[${new Date().toISOString()}] Tool: `
        + `${input.toolName}, `
        + `Args: ${JSON.stringify(input.toolArgs)}`
      );
      return { permissionDecision: "allow" };
    },
    onPostToolUse: async (input) => {
      console.log(
        `[${new Date().toISOString()}] `
        + `Result: ${JSON.stringify(input.toolResult)}`
      );
      return null;
    },
  },
});

Bloqueo de herramientas peligrosas

const BLOCKED_TOOLS = ["shell", "bash", "exec"];

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      if (BLOCKED_TOOLS.includes(input.toolName)) {
        return {
          permissionDecision: "deny",
          permissionDecisionReason:
            "Shell access is not permitted",
        };
      }
      return { permissionDecision: "allow" };
    },
  },
});

Agregar contexto de usuario

const session = await client.createSession({
  hooks: {
    onSessionStart: async () => {
      const userPrefs = await loadUserPreferences();
      return {
        additionalContext:
          `User preferences: `
          + `${JSON.stringify(userPrefs)}`,
      };
    },
  },
});

Pasos siguientes

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

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

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/user-prompt-submitted)
  

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

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