[Claude]Claude Code Deep Dive Workshop 6주차 - Agent SDK: SDK로 나만의 에이전트 만들기

안녕하세요, Claude Code Deep Dive Workshop 내용을 학습하며 정리하였습니다. 

 

CLAUDE CODE DEEP DIVE WORKSHOP · 시리즈 6/6

⑥ Agent SDK — 코드로 Claude 앱 만들기

Messages API·Tool Use·Streaming·MCP·프로덕션 운영·멀티에이전트를 Python/TypeScript 병행으로 다루는 개발자 챕터.

이 글의 결론 — Messages API → Tool Use → Streaming → MCP까지 기능을 쌓고, Retry·Rate Limit·관측성으로 프로덕션화하며, Orchestrator-Worker 멀티에이전트와 Prompt Caching·모델 캐스케이딩으로 확장·비용 최적화합니다.

핵심 8영역

영역	핵심 내용
1. SDK 기초	Python/TS 설치·첫 호출, 비동기 클라이언트, 인증·모델 선택, 에러 처리
2. Messages API	role·시스템 프롬프트, 멀티턴, max_tokens/stop_reason, Prompt Caching, Vision/PDF 입력
3. Tool Use	도구 정의→호출 사이클→tool_result, tool_choice, DB/API/파일시스템 봇, 검증·로깅
4. Streaming	스트림 이벤트, FastAPI SSE 서버, React 클라이언트, WebSocket, 백프레셔
5. MCP 통합	mcp_servers 매개변수, 권한 통제, GitHub/Slack/Database MCP, 통합 비서
6. Production	에러 분류, Retry, Rate Limiting, Circuit Breaker, 구조화 로깅·트레이싱, 부하 테스트
7. Advanced	Orchestrator-Worker 멀티에이전트, 큐 비동기, Semantic 캐시, 모델 캐스케이딩, 자가 비평
8. Recap & Labs	첫 SDK 호출 / Tool Use 봇 / Streaming 챗봇 / 프로덕션 운영

실습 체크리스트

☐ SDK 설치 후 첫 호출 (Python 또는 TS)
☐ Prompt Caching으로 반복 컨텍스트 비용 절감
☐ Tool Use 봇 구현 (호출 사이클 완성)
☐ 스트리밍 챗봇 (SSE 또는 WebSocket)
☐ 프로덕션 안전장치(Retry + Rate Limiter + 구조화 로깅)
☐ (심화) Orchestrator-Worker 멀티에이전트
☐ Lab 1~4 중 최소 2개 완주

🧪 핸즈온 랩 — Claude Code를 코드에서 부른다

Task	내용
사전 준비	SDK 설치와 인증 상속(CLI 인증을 SDK가 상속)
첫 query	CLI의 프로그래매틱 쌍둥이 호출
대화 메모리	resume으로 기억 유지
커스텀 도구	내 함수가 에이전트의 손(Tool Use)
미니 상주 점검원	프로세스를 넘는 상태 유지
캡스톤 이식 지도	SDK 지식을 캡스톤으로 연결

산출물 — 커스텀 도구를 가진 SDK 에이전트 + 대화 메모리 유지 앱

---

🧪 핸즈온 상세 실습 기록

0. 사전 준비 — SDK 설치 & 인증 상속

mkdir -p ~/agentlab && cd ~/agentlab
npm init -y > /dev/null
npm install @anthropic-ai/claude-agent-sdk zod
claude /status                 # CLI 인증을 SDK가 그대로 상속

1. 첫 query — CLI의 프로그래매틱 쌍둥이

// hello.mjs
import { query } from "@anthropic-ai/claude-agent-sdk";
const q = query({
  prompt: "이 디렉토리의 파일 목록을 보고 한 줄 소감을 말해줘",
  options: { allowedTools: ["Bash","Read","Glob"] }
});
for await (const m of q) { /* 스트림 이벤트 처리 */ }
// → "package.json과 node_modules뿐인 갓 태어난 프로젝트네요."
// --- session=ab12cd34 turns=2 cost=$0.0031

2. 대화 메모리 — resume이 기억을 만든다

// chat.mjs — session_id를 resume으로 이어붙임
나> 내 이름은 우형이야      → 반갑습니다, 우형님.
나> 내 이름이 뭐라고 했지?  → 우형님이라고 하셨죠.   # 기억 유지

3. 커스텀 도구 — 내 함수가 에이전트의 손

// notes-agent.mjs — in-process MCP
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";
// tool()로 노트 조회 함수를 정의 → 에이전트가 호출
// → "다음 회식은 7월 24일 목요일 19시, 을지로 골뱅이집입니다."
// → "노트 원칙상 금요일 오후 프로덕션 배포는 하지 않습니다."

tool() + createSdkMcpServer()로 내 함수를 에이전트의 도구로 등록(Tool Use). zod로 입력 스키마 검증.

4. 미니 상주 점검원 — 프로세스를 넘는 기억

echo "service: OK" > status.txt   → node medic-lite.mjs
echo "service: DOWN" > status.txt  → node medic-lite.mjs
// → "직전 점검에서는 OK였는데 지금은 DOWN으로 바뀌었습니다."

상태를 파일로 저장해 프로세스를 재시작해도 이전 관측을 기억하는 에이전트. 캡스톤으로 가는 다리.

🔑 교훈 — SDK query()는 CLI의 프로그래매틱 쌍둥이 · resume으로 대화 메모리 · tool()로 내 함수를 에이전트의 손으로 · 상태 파일로 프로세스를 넘는 기억.

---

📚 심화 · 비교 · 트러블슈팅 · FAQ

🐍 Python vs 🟦 TypeScript, 뭘 고를까

상황	추천
데이터·ML 파이프라인, 백엔드 스크립트	Python
웹 프런트/풀스택, Node 서비스	TypeScript
둘 다 익숙	스트리밍 UI면 TS, 그 외 Python

🗺️ SDK 핵심 개념 맵

요소	역할
query()	CLI의 프로그래매틱 쌍둥이(호출 진입점)
resume(session_id)	대화 메모리 유지
tool()	내 함수를 에이전트 도구로 등록
createSdkMcpServer()	in-process MCP 서버 구성

✅ 프로덕션 배포 전 체크리스트

☐ Retry + 지수 백오프 (일시적 오류 대응)
☐ Rate Limiter + Circuit Breaker (과호출 방어)
☐ 구조화 로깅 + 분산 트레이싱 (문제 추적)
☐ Prompt Caching (반복 컨텍스트 비용 절감)
☐ 헬스체크/readiness + 부하 테스트
☐ API key는 시크릿 매니저로 (하드코딩 금지)

🧠 한 단계 위 — Orchestrator-Worker 패턴

하나의 오케스트레이터가 작업을 쪼개 여러 워커 에이전트에 분배하고 결과를 종합합니다. 큐 기반 비동기 처리, 모델 캐스케이딩(쉬운 건 haiku·어려운 건 상위 모델), Semantic 캐시로 확장·비용 최적화까지 이어집니다.

🧯 자주 막히는 지점

증상	처방
SDK 인증 실패	SDK는 CLI 인증을 상속 → claude /status로 CLI 로그인 확인
429 Rate limit	Retry+백오프, Rate Limiter로 동시성 제어
스트리밍이 끊김	백프레셔·에러 이벤트 처리, 재연결 로직

❓ FAQ

Q. Agent SDK와 Anthropic API의 차이는?
A. SDK는 Claude Code의 도구·권한·MCP·세션을 그대로 코드에서 쓰는 상위 계층입니다. 단순 메시지 호출만 필요하면 API로도 충분합니다.

Q. 커스텀 도구는 별도 서버가 필요한가요?
A. 아니요. createSdkMcpServer()로 같은 프로세스 안(in-process)에서 함수를 도구로 등록할 수 있습니다.

🎉 시리즈 완결
개념(PDF) + 실습(핸즈온) + 심화(보완)까지 6주 여정 끝. 이제 캡스톤으로 직접 작품을 "개장"해 보세요.