플러그인 만들기

플러그인 만들기 (Agent SDK)

Anthropic Agent SDK에서 애플리케이션을 위한 플러그인을 만드는 방법을 다루는 가이드예요. SDK(파이썬·타입스크립트)의 plugin(), decorator() API로 공개/비공개 플러그인을 정의하고, 슬래시 명령·MCP 도구·훅·리턴 컨트롤을 묶는 방법을 보여줘요. Claude Code 플러그인 시스템을 SDK 기반 애플리케이션에서 재사용하는 진입점이에요.

출처: 공식문서

본문

시작하기

플러그인은 명령(슬래시 명령), MCP 도구, 훅, 리턴 컨트롤을 앱에 묶는 재사용 가능한 구성 단위예요. SDK에서 plugin() 팩토리로 만들고, 실행 시 client.sdk.plugins 레지스트리에 등록해요.

TypeScript 예시

import { sdk } from "@anthropic-ai/sdk";

sdk.plugin("my-plugin", {
  name: "hello-world",
  description: "hello world 명령을 제공하는 데모 플러그인",
  commands: {
    hello: {
      description: "사용자에게 인사",
      code: (args, context) => {
        return context.sdk.plugins.command("hello", "안녕하세요!");
      },
    },
  },
});

플러그인의 name은 레지스트리 키가 되고, commands.code가 슬래시 명령의 실행 로직이에요. context.sdk.plugins.command()로 명령 턴을 재귀 실행할 수 있어요.

Python — plugin 데코레이터

Python에서는 plugin() 데코레이터로 플러그인을 정의해요. 데코레이터가 name을 플러그인 ID로, JSDoc/문서 문자열을 설명으로 사용해요.

from anthropic import plugin

@plugin("hello-world", description="hello world 명령을 제공하는 데모 플러그인")
def hello_plugin():
    # 앱 로직 정의
    pass

플러그인 컴포넌트

플러그인은 아래 컴포넌트를 하나 이상 포함할 수 있어요. 빈 플러그인(내용 없는)은 런타임 오류를 일으키니, 최소 하나의 명령·도구·훅이 있어야 해요.

  • 명령(slash commands): commands 맵의 키가 슬래시 명령 이름(/hello). code 또는 handler가 실행 로직.
  • MCP 도구: 플러그인이 표준 mcpServer/인프로세스 서버에서 정의한 도구를 노출.
  • 훅(hooks): 플러그인이 등록한 toolCall, message 등의 이벤트 훅.
  • 리턴 컨트롤: SDK가 App과 app.sdk.commands를 주입해 앱 차원의 명령·라우팅과 상호작용.

플러그인은 client.sdk.plugins 레지스트리에 등록된 뒤, 명령·도구가 실제 에이전트 실행에서 사용 가능해져요. 여러 SDK 세션/클라이언트에서 같은 플러그인을 재사용할 수 있어요.

공개·비공개 배포

플러그인은 앱 안에서 로컬로 정의하거나, npm/pip 패키지로 만들어 팀과 공유할 수 있어요. name 충돌을 피하고, description은 명령 목록에서 표시되므로 동작을 명확히 적어요. 플러그인 안에서 실행되는 코드는 앱과 같은 권한으로 실행되니, 입력 값을 검증하고 민감한 동작은 훅으로 가드하세요.

더 알아보기