후크에 대한 빠른 시작

후크를 사용하면 대화 수명 주기의 주요 지점에서 세션 동작 코필로트 SDK 을 가로채고 사용자 지정할 수 있습니다. 후크를 사용하여 다음을 수행합니다.

•         **제어 도구 실행** - 도구 호출 승인, 거부 또는 수정
  

•         **결과 변환** - 처리하기 전에 도구 출력 수정
  

•         **컨텍스트 추가** - 세션 시작 시 추가 정보 삽입
  

•         **오류 처리** - 사용자 지정 오류 처리 구현
  

•         **감사 및 로그** - 규정 준수를 위한 모든 상호 작용 추적
  

사용 가능한 후크

후크	Trigger	사용 사례
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)