후크에 대한 빠른 시작

참고

코필로트 SDK가 현재 기술 미리 보기에 있습니다. 기능 및 가용성은 변경될 수 있습니다.

후크를 사용하면 대화 수명 주기의 주요 지점에서 세션 동작 코필로트 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)

누가 이 기능을 사용할 수 있나요?

이 기사에서