agent-sdk-dev 플러그인 사용법: 클로드 에이전트 SDK로 AI 에이전트 만들기, 없이·있이 비교하고 실행 비용 수십 배 줄인 설정 한 줄

클로드 코드를 쓰다 보면 “매주 하는 이 일을 클로드에게 프로그램으로 맡길 수 없을까” 싶은 순간이 옵니다. 클로드 에이전트 SDK(Claude Agent SDK)는 클로드 코드의 동작 방식을 내 프로그램 안에서 부를 수 있게 해 주는 공식 라이브러리이고, agent-sdk-dev는 그 SDK로 AI 에이전트 만들기를 도와주는 Anthropic 공식 플러그인입니다. 플러그인은 무료지만 만들 때와 돌릴 때 클로드 사용량이 듭니다. 가상 빵집의 고객 후기를 읽어 주간 불만 보고서를 쓰는 에이전트를 같은 요청으로 플러그인 없이 2번, 있이 2번 만들게 하고, 만든 프로그램을 실제로 실행해 채점했습니다.

결과부터 보기: 만든 에이전트가 쓴 보고서

영상은 요청문, 만든 에이전트가 쓴 보고서, 채점표, 검증 에이전트가 잡은 문제, 실행 사용량 순서입니다.

직접 눌러 보기: 네 번이 만든 코드 전문, 검증 보고서, 실제 보고서 열어 보기

따라 해 보기: 요청문과 실습 재료

빈 폴더에 후기 파일을 넣고 클로드 코드를 연 뒤, 플러그인을 깐 상태에서 아래처럼 보냅니다. 클로드 코드가 처음이라면 클로드 코드 설치 방법을 먼저 보세요. 실습 재료(zip)에는 가상 후기 12건, 요청문, 채점 기준, 플러그인 있이 1회차가 만든 코드를 넣었습니다.

/agent-sdk-dev:new-sdk-app <프로젝트 이름> 우리 <가게 종류> 고객 후기 파일 <파일 이름>.csv를 읽고 불만을 종류별로 묶어 이번 주 보고서 report.md로 써 주는 작은 AI 에이전트 프로그램을 클로드 에이전트 SDK로 만들어 줘. 타입스크립트로, npm을 쓰고, 내 맥에서 나만 쓰는 거라 화면은 필요 없어. 다 만들면 이 폴더에서 에이전트를 실행하는 명령을 run.txt에 한 줄로 적어 줘. 더 묻지 말고 끝까지 진행해 줘.

<…> 부분은 내 일에 맞게 바꿉니다. 좋은 결과라면 package.json·tsconfig.json·에이전트 코드·.env.example이 생기고, 클로드가 타입 검사를 통과했다고 알려 줍니다. 이 명령은 원래 언어·이름·에이전트 종류·시작 형태·도구를 하나씩 묻습니다. 요청에 답을 다 적고 “더 묻지 말고”를 붙이면 바로 만듭니다. 실험 때는 패키지를 미리 깔아 두고 “새로 설치하지 마”, “실행은 내가 할 테니 직접 실행하지는 마”를 더 붙였습니다.

agent-sdk-dev에 들어 있는 것

claude plugin details로 뽑은 구성입니다. 화면에는 Skills로 나오지만 실제로는 슬래시 명령 하나(commands/new-sdk-app.md)이고, 검증 에이전트가 둘 있습니다. 훅·MCP 서버는 없습니다.

구성	하는 일 (파일 내용 기준)	부를 때 분량
/agent-sdk-dev:new-sdk-app	공식 SDK 문서를 읽고 → 언어·이름·종류·시작 형태·도구를 하나씩 묻고 → npm 최신 버전 확인 → 프로젝트 파일·.env.example·.gitignore 생성 → 타입 검사 오류 0까지 고친 뒤 → 검증 에이전트에게 넘김	약 2.7k토큰
agent-sdk-verifier-ts	타입스크립트 SDK 앱 점검: 설치·설정·SDK 사용법·타입·키 관리·오류 처리를 보고 통과/경고 있는 통과/실패로 판정. 모델은 Sonnet으로 고정	약 1.8k토큰
agent-sdk-verifier-py	같은 점검의 파이썬판	약 1.7k토큰

깔아 두면 매 대화에 약 235토큰이 붙습니다. 명령과 에이전트 설명문이 늘 실리기 때문입니다. 명령은 자동으로 불리지 않으니, 쓸 때는 직접 /agent-sdk-dev:new-sdk-app을 입력합니다.

1단계. 플러그인 깔기 (약 1분)

에이전트를 만들 폴더에서 터미널에 아래 명령을 실행합니다. --scope local은 이 폴더에서만 켜는 옵션입니다.

claude plugin install agent-sdk-dev@claude-plugins-official --scope local
claude plugin details agent-sdk-dev

이렇게 나오면 성공 ✔ Successfully installed plugin: agent-sdk-dev@claude-plugins-official (scope: local)(플러그인 설치 성공, 범위: 이 폴더). 구성 목록에 Agents (2) agent-sdk-verifier-ts, agent-sdk-verifier-py가 나옵니다.

• 플러그인을 찾지 못하면 claude plugin marketplace add anthropics/claude-plugins-official로 공식 저장소를 등록한 뒤 다시 설치합니다.
• 클로드 앱에서는 디렉터리에서 설치합니다(디렉터리 여는 법).
• Node.js가 있어야 합니다. 터미널에서 node -v가 버전을 보여 주면 됩니다.

필요 없어지면 같은 폴더에서 아래 명령으로 지웁니다.

claude plugin uninstall agent-sdk-dev@claude-plugins-official --scope local

2단계. 같은 요청으로 에이전트 만들게 하기 (약 3분)

이 단계에서는 같은 요청을 플러그인 없이·있이 보내 결과를 비교합니다. 후기는 가상 빵집의 12건입니다. 배달 지연·딱딱한 바게트·직원 응대·머리카락(위생) 불만을 섞고, 영어 후기 한 건과 칭찬 후기도 넣었습니다.

채점은 만든 폴더의 사본에서 타입 검사를 돌리고, run.txt 명령(네 번 모두 npm start)으로 에이전트를 실제로 실행해 확인했습니다. 기준은 실행 전에 플러그인의 점검 항목과 SDK 타입스크립트 문서에서 뽑아 고정했고, 요청문에는 넣지 않았습니다.

채점 항목	없이 1·2	있이 1·2
타입 검사(tsc --noEmit) 오류 0	✓ ✓	✓ ✓
package.json에 “type”: “module”과 typecheck 스크립트, tsconfig.json	✓ ✓	✓ ✓
.env.example에 키 자리, .gitignore에 .env	✗ ✗	✓ ✓
SDK의 query()로 에이전트 실행	✓ ✓	✓ ✓
쓸 도구만 허용하고 권한 우회 옵션은 안 씀	✓ ✓	✓ ✓
결과 메시지로 성공·실패를 확인	✓ ✓	✓ ✓
실제로 실행해 report.md 생성	✓ ✓	✓ ✓
불만 4종이 모두 담기고 원본 후기 파일은 그대로	✓ ✓	✓ ✓
합계(10점)	9 · 9	10 · 10

	① 플러그인 없음 (1·2)	② 플러그인 있음 (1·2)
걸린 시간	2분쯤 · 1분 남짓	3분쯤 · 3분쯤
만드는 데 든 사용량(API 단가)	0.79 · 0.66달러	1.16 · 1.13달러
점검 단계	없음	검증 에이전트 1회씩(Sonnet 5.5)
에이전트가 쓰는 모델	Opus 5.5 지정 · Sonnet 5.5 지정	지정 안 함(기본값, 이번엔 Opus 5.5) · 같음

네 번 모두 에이전트가 쓸 수 있는 도구를 좁혔습니다. 없이 1회차는 내장 도구를 모두 끄고 “후기 읽기”·”보고서 쓰기” 도구 두 개만 직접 만들어 붙였고, 나머지 셋은 파일 읽기(Read)와 쓰기(Write)만 열었습니다. 보고서도 네 번 모두 쓸 만했습니다. 위생 불만을 맨 위에 “긴급”으로 올렸고, 영어 후기에는 번역을 붙였고, 한 후기에 불만이 둘이면 양쪽에 셌습니다.

검증 에이전트가 잡은 두 가지

플러그인 쪽은 다 만든 뒤 agent-sdk-verifier-ts에게 점검을 맡겼고, 두 번 모두 “경고 있는 통과”(PASS WITH WARNINGS)를 받았습니다. 지적받은 곳은 그 자리에서 고쳤습니다.

• 있이 1회차: 에이전트가 같은 폴더의 .env(API 키 파일)를 읽을 수 있는 틈이 있다. 클로드는 도구를 쓰기 직전마다 파일 이름을 검사하는 훅(PreToolUse)을 붙여 후기 파일과 보고서 말고는 막았습니다.
• 있이 2회차: 다음 주에 다시 돌리면 이미 있는 report.md를 덮어쓰지 못해 실패한다. 클로드 코드의 쓰기 도구는 기존 파일을 먼저 읽어야 덮어쓰는데, 읽기를 후기 파일로만 묶어 놨기 때문입니다. report.md 읽기를 허용해 고쳤습니다.

두 번째 지적이 실제로 문제가 되는지는 네 결과물을 모두 한 번 더 돌려 봤습니다. 보고서가 이미 있는 상태에서 네 개 모두 새 보고서를 쓰고 정상 종료했습니다. 고치기 전 코드는 남아 있지 않아 지적이 맞았는지는 확인하지 못했습니다.

실행 기록 · <작업 폴더>/plug1/index.ts 중 훅 부분(원문 그대로)

// PreToolUse 훅은 권한 모드와 상관없이 모든 도구 호출 직전에 실행되므로 여기서 규칙을 강제한다.
const guardFiles: HookCallback = async (input) => {
  if (input.hook_event_name !== "PreToolUse") return {};
  const denyReason = checkAccess(input.tool_name, input.tool_input);
  return {
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: denyReason ? "deny" : "allow",

3단계. 만든 에이전트 돌리기와 사용량 줄이기 (약 1분)

만든 폴더에서 터미널에 npm start를 실행하면 에이전트가 후기를 읽고 report.md를 씁니다. 플러그인 쪽은 두 번 모두 “실행 전에 .env에 API 키를 넣으라”고 안내했습니다. 이번에는 키를 넣지 않고 돌렸는데, SDK가 이 맥의 클로드 코드 로그인을 그대로 써서 네 개 모두 실행됐습니다. 다만 SDK 공식 문서는 남에게 내놓는 제품에서 claude.ai 로그인을 쓰지 말고 API 키를 쓰라고 밝힙니다. 내 맥에서 나만 쓰는 경우의 이야기입니다.

문제는 사용량이었습니다. 후기 12건짜리 보고서 한 번에 API 단가로 2.28~5.98달러어치가 나왔습니다. 세션 기록을 열어 보니 이 계정에 연결해 둔 claude.ai 커넥터(캔바·노션 같은 연결)의 도구 목록이 매 실행에 통째로 실려, 한 번에 56만~74만 토큰이 들어가 있었습니다. 에이전트 코드에서 도구를 Read·Write로 좁혀도 이 목록은 따로 붙었습니다.

터미널에서 실행합니다. 커넥터를 끄는 환경 변수를 앞에 붙입니다(클로드 코드 MCP 문서의 claude.ai 커넥터 끄기).

ENABLE_CLAUDEAI_MCP_SERVERS=false npm start

같은 프로그램인데 한 번 실행 비용이 35~47분의 1로 줄었습니다.

실행 기록 · <작업 폴더>/chk2-plug1 · 같은 프로그램을 커넥터 끄고 실행한 마지막 줄(원문 그대로)

완료: <작업 폴더>/chk2-plug1/report.md (비용 약 $0.1148)

같은 에이전트 1회 실행	커넥터 켜진 채	커넥터 끄고
없이 2회차 결과물(Sonnet 5.5)	2.28달러	0.07달러
있이 1회차 결과물(Opus 5.5)	5.37달러	0.11달러

• 이렇게 나오면 성공 마지막 줄 비용이 0.1달러 안팎으로 나오고 같은 보고서가 생깁니다. 있이 1회차 결과물은 1만 4천 토큰쯤 들어갔습니다.
• 커넥터를 거의 쓰지 않는 계정이라면 차이가 작을 수 있습니다. 숫자는 이번 계정에서 잰 값입니다.
• API 키로 돌리는 경우에는 이 커넥터 목록이 붙는지 시험하지 않았습니다.

이런 사람에게 권합니다

• ✅ 에이전트 SDK로 처음 프로그램을 만드는 사람. 키 파일 자리·.gitignore·타입 검사·점검까지 한 번에 챙겨 주고, 검증 에이전트가 권한 틈 같은 놓치기 쉬운 곳을 짚어 줍니다.
• ✅ 만든 SDK 앱을 남에게 넘기기 전에 점검을 받고 싶은 사람. “내 SDK 앱 점검해 줘”처럼 말하면 검증 에이전트를 따로 부를 수 있습니다(플러그인 README 기준).
• ❌ 내 맥에서 나만 쓸 작은 에이전트 하나가 목적인 사람. 이번 과제에서는 플러그인 없이도 실행되는 에이전트가 나왔고, 비용과 시간은 덜 들었습니다.

한계와 주의할 점

• 타입스크립트로 작은 에이전트 하나만, 조건마다 두 번씩 돌렸습니다. 파이썬판과 검증 에이전트 파이썬판은 시험하지 않았습니다.
• 실험에서는 SDK 패키지를 미리 깔아 두고 새 설치를 막았습니다. 플러그인 명령은 원래 npm 최신 버전을 확인해 직접 설치합니다.
• 실험 환경의 허용 목록 때문에 네 번 모두 명령 몇 개가 거부됐습니다. 없이 1회차는 그 탓에 타입 검사를 직접 돌리지 못했다고 답했습니다(채점 때는 통과).
• 명령 파일이 안내하는 문서 주소는 예전 주소(docs.claude.com)입니다. 지금 SDK 문서는 code.claude.com에 있습니다.

대안

방법	다른 점	이럴 때 고르세요
agent-sdk-dev(이 글)	프로젝트 뼈대·키 파일 자리·타입 검사·검증 에이전트 점검	처음 SDK 앱을 만들거나 남에게 넘길 때
말로 요청	이번 실험에서 실행되는 에이전트가 똑같이 나옴, 키 파일 자리와 점검만 빠짐	나만 쓸 작은 에이전트
mcp-server-dev 플러그인	프로그램 대신 클로드에 도구를 붙이는 MCP 서버 만들기	평소 쓰는 클로드 코드·앱에서 내 데이터를 쓰고 싶을 때
plugin-dev 플러그인	프로그램 대신 클로드 코드 안에서 도는 플러그인(명령·스킬·훅) 만들기	내 작업 절차를 클로드 코드에 묶어 두고 싶을 때

자주 묻는 질문

클로드 에이전트 SDK를 쓰려면 API 키가 꼭 있어야 하나요?

이번에는 API 키 없이 이 맥의 클로드 코드 로그인으로 네 개 모두 실행됐습니다. 공식 문서는 남에게 내놓는 제품이라면 API 키를 쓰라고 밝힙니다. 키를 쓸 때는 Anthropic 콘솔에서 받아 .env에 넣고, 채팅창에 붙여 넣지 않습니다.

agent-sdk-dev 플러그인은 무료인가요?

플러그인 자체는 무료(Apache-2.0)입니다. 에이전트를 만들 때 이번에는 1.1달러어치 사용량이 들었고, 만든 에이전트를 돌릴 때도 따로 사용량이 듭니다. 구독 요금제라면 그만큼 사용량 한도에서 빠집니다.

파이썬으로도 만들 수 있나요?

명령이 처음에 언어를 묻고, 파이썬을 고르면 claude-agent-sdk 패키지로 만든 뒤 파이썬 검증 에이전트가 점검합니다(명령 파일 기준). 이번에는 타입스크립트만 시험했습니다.

만든 에이전트가 너무 비싸게 나와요

클로드 코드 로그인으로 돌린다면 claude.ai 커넥터가 붙는지부터 봅니다. 이번에는 ENABLE_CLAUDEAI_MCP_SERVERS=false를 붙여 한 번 실행이 2~6달러어치에서 0.1달러 안팎으로 줄었습니다. 클로드 코드에서 쓰는 사용량 확인법은 session-report 리뷰에 정리했습니다.

출처

agent-sdk-dev 플러그인 폴더, new-sdk-app 명령 파일, 에이전트 SDK 개요, SDK 타입스크립트 문서, 클로드 코드 MCP 문서(claude.ai 커넥터), npm 패키지 (모두 2026-10-20 확인, 저장소 별 43,187개)