Быстрый старт для крючков

Крючки позволяют перехватывать и настраивать поведение Второй пилот SDK сессий в ключевые моменты жизненного цикла разговора. Используйте крючки, чтобы:

•         **Выполнение инструментов управления** — одобрение, отклонение или изменение вызовов инструментов
  

•         **Трансформируйте результаты** — модифицируйте выходы инструментов до их обработки
  

•         **Добавить контекст** — добавить дополнительную информацию при начале сессии
  

•         **Обработка ошибок — реализация** пользовательской обработки ошибок
  

•         **Ведите аудит и лог** — отслеживайте все взаимодействия для соответствия требованиям
  

Доступные крючки

Обработчик	Триггер	Сценарий использования
onPreToolUse	До запуска инструмента	Контроль разрешений, проверка аргументов
onPostToolUse	После запуска инструмента	Преобразование результата, логирование
onUserPromptSubmitted	Когда пользователь отправляет сообщение	Изменение подсказок, фильтрация
onSessionStart	Начало сессии	Добавьте контекст, настройте сессию
onSessionEnd	Сессия завершена	Очистка, аналитика
onErrorOccurred	Ошибка возникает	Обработка пользовательских ошибок

Быстрый старт

Следующий пример демонстрирует, как регистрировать хуки при создании сессии в 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.",
      };
    },
  },
});

Примеры в Python, Go и .NET см. репозиторийgithub/copilot-sdk.

Контекст вызова крюка

Каждый крючок получает invocation параметр с контекстом текущей сессии.

Поле	Тип	Описание
sessionId	струна	ID текущей сессии

Это позволяет хукам сохранять состояние или выполнять логику, специфичную для сессии.

Распространенные шаблоны

Логирование всех вызовов инструментов

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

Блокировка опасных инструментов

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

Добавление пользовательского контекста

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

Дальнейшие действия

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