Inicio rápido para enlaces

Nota:

          SDK de Copilot actualmente está en versión preliminar pública. La funcionalidad y la disponibilidad están sujetas a cambios.

Los enlaces permiten interceptar y personalizar el comportamiento de las sesiones de SDK de Copilot en puntos clave del ciclo de vida de la conversación. 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. Para Java, consulte el github/copilot-sdk-java repositorio.

Contexto de invocación del enlace

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