Claude Agent SDK 6/15 정책 + 가이드: Pro $20·Max $100·$200 별도 풀 [2026-06]

TL;DR — 정확히 16시간 뒤 무엇이 바뀌나

내일 2026년 6월 15일 00:00 UTC부로 Claude Agent SDK 호출과 claude -p 비대화형 실행이 새 풀에서 빠집니다. 기존엔 대화형 사용량 한도와 같은 통에 섞여 있었는데, 이제 별도 통으로 분리:

좋은 점은 대화형 한도가 회복된다는 것 — 이전엔 cron 자동화 한 번에 인터랙티브 한도까지 잠식했는데 이제 분리. 나쁜 점은 SDK 사용량을 따로 관리해야 한다는 것. 6/4 Cursor 6월 업데이트 글에서 본 풀 분리와 정확히 같은 패턴 — AI 코딩 도구 산업이 한꺼번에 사용량 풀을 갈라치고 있습니다.

이 글에서 다루는 것:

1. 6/15 정책 변경 — 어떤 호출이 새 풀에서 빠지나
2. SDK 설치 + 첫 에이전트 (Python·TypeScript)
3. 고급 기능 — Hooks·Subagents·MCP·Sessions
4. 6/15 이후 비용 통제 전략
5. 자주 발생하는 에러 + 해결법

Photo by Florian Olivo on Unsplash | 한 줄 호출 뒤에 숨은 비용 구조가 6/15에 갈라진다

Step 1 — 6/15 정책 변경: 어떤 호출이 새 풀에서 빠지나

Anthropic 공식 안내에 박힌 두 가지 호출 분류:

핵심 — CI/CD 파이프라인이나 cron 스케줄에 들어간 claude -p 호출이 인터랙티브 한도에 닿지 않습니다. 평소 대화 작업하다 한도 부딪히던 문제 해소.

다만 별도 풀이 다 떨어지면? 답은 명확합니다 — 사용량 크레딧 결제로 보충하거나 다음 달까지 멈춤. Anthropic 측은 "충분한 여유"를 약속했지만 헤비유저는 첫 1주가 한도 테스트 구간.

Step 2 — 사전 준비: SDK 설치 + 환경

Python (3.10+)

pip install claude-agent-sdk

Python 버전 확인:

python3 --version  # macOS/Linux
py --version       # Windows

3.10 미만이면 pip이 "No matching distribution found"으로 거부합니다.

TypeScript

npm install @anthropic-ai/claude-agent-sdk

특이 사항 — TypeScript SDK는 네이티브 Claude Code 바이너리를 옵셔널 의존성으로 번들합니다. 즉 Claude Code 별도 설치 불필요.

API 키 설정

세 가지 옵션 — 가장 단순한 건 환경변수:

export ANTHROPIC_API_KEY=your-api-key

엔터프라이즈는 클라우드 라우팅:

# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1

# Microsoft Azure
export CLAUDE_CODE_USE_FOUNDRY=1

Step 3 — 첫 에이전트 30초 만에

Python

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Find and fix the bug in auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)


asyncio.run(main())

TypeScript

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

for await (const message of query({
  prompt: "Find and fix the bug in auth.ts",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  console.log(message);
}

이게 끝입니다. allowed_tools에 명시한 도구는 승인 프롬프트 없이 즉시 실행. Cursor 6월의 Auto-Review와 같은 패턴 — Claude Code의 권한 모드를 SDK가 그대로 가져옵니다.

Step 4 — 빌트인 도구 9가지

호출만 하면 곧바로 쓸 수 있는 도구들:

Monitor 도구가 흥미롭습니다 — npm test --watch 같은 장기 실행 스크립트를 띄워두고 출력 라인 변화를 트리거로 활용. Claude가 빌드 실패 라인을 보면 자동으로 수정 들어가는 구조.

Step 5 — 고급: Hooks로 감사 로그

PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, UserPromptSubmit 등이 콜백으로 노출.

import asyncio
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher


async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now()}: modified {file_path}\n")
    return {}


async def main():
    async for message in query(
        prompt="Refactor utils.py to improve readability",
        options=ClaudeAgentOptions(
            permission_mode="acceptEdits",
            hooks={
                "PostToolUse": [
                    HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
                ]
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

HookMatcher의 matcher="Edit|Write"로 편집/생성 도구 사용 시에만 콜백 실행. 컴플라이언스가 필요한 회사라면 이걸로 모든 파일 변경 감사 로그 즉시 확보.

Photo by Chris Ried on Unsplash | 6/15 이후엔 풀 두 개를 동시에 봐야 한다

Step 6 — 서브에이전트로 작업 분할

큰 작업을 전문화된 에이전트에 위임:

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
    async for message in query(
        prompt="Use the code-reviewer agent to review this codebase",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Expert code reviewer for quality and security.",
                    prompt="Analyze code quality and suggest improvements.",
                    tools=["Read", "Glob", "Grep"],
                )
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

서브에이전트 메시지는 parent_tool_use_id로 추적 가능. 5/31 Opus 4.8 글에서 본 Dynamic Workflows의 SDK 버전이라 보면 됩니다.

Step 7 — MCP 통합 한 줄 추가

async for message in query(
    prompt="Open example.com and describe what you see",
    options=ClaudeAgentOptions(
        mcp_servers={
            "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
        }
    ),
):
    ...

mcp_servers 한 줄로 Playwright MCP, Postgres MCP, Slack MCP 등 수천 개 MCP 서버에 즉시 접근. 5/7 Claude Code 5월 업데이트 글에서 짚었던 MCP 메모리 누수도 SDK 0.x에서 해결.

Step 8 — 세션 이어가기

session_id = None

# 첫 호출 — 세션 ID 캡처
async for message in query(
    prompt="Read the authentication module",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]),
):
    if isinstance(message, SystemMessage) and message.subtype == "init":
        session_id = message.data["session_id"]

# 두 번째 호출 — 같은 컨텍스트 이어가기
async for message in query(
    prompt="Now find all places that call it",
    options=ClaudeAgentOptions(resume=session_id),
):
    if isinstance(message, ResultMessage):
        print(message.result)

resume에 세션 ID 넘기면 이전 컨텍스트 그대로 — "it"이 무엇인지 묻지 않고 인증 모듈을 가리킨다 알아차림.

Step 9 — 6/15 이후 비용 통제 5가지 패턴

패턴 1: SDK 호출은 짧게, 인터랙티브는 자유롭게

분리된 두 풀의 의미를 살리려면 자동화 호출을 최소 토큰으로 끊기. 한 번에 큰 작업 던지지 말고 작은 단위로.

패턴 2: 모델 선택을 명시적으로

ClaudeAgentOptions(model="claude-haiku-4-5-20251001")

Haiku 4.5로 일상 cron 자동화 처리하고, Fable 5(6/10 글)는 진짜 큰 작업에만.

패턴 3: setting_sources로 컨텍스트 제한

ClaudeAgentOptions(setting_sources=[])  # CLAUDE.md 안 불러오기

대형 모노레포에서 CLAUDE.md가 토큰 잡아먹는 경우 비활성화.

패턴 4: Hooks로 토큰 사용량 추적

PostToolUse 콜백에서 사용량 메트릭 수집 → 일일 슬랙 알림.

패턴 5: Managed Agents로 일부 이전

대형 비동기 작업(수시간짜리)은 Managed Agents로. SDK 풀 잠식 안 함.

자주 발생하는 에러 + 해결법

에러 1: No matching distribution found for claude-agent-sdk

원인: Python 3.10 미만. 해결: pyenv install 3.11 && pyenv local 3.11 후 재설치.

에러 2: SDK가 인터랙티브 한도를 잡아먹는다 (6/15 이전)

원인: 6/15 시행 전이라 여전히 합산. 해결: 6/15 이후 자동 분리 — 별도 조치 불필요.

에러 3: claude -p 호출이 별도 풀에서 빠지지 않음

원인: Claude Code 버전이 6/15 패치 이전. 해결: npm install -g @anthropic-ai/claude-code@latest로 업데이트.

에러 4: 6/15 첫날 풀 빨리 소진

원인: cron 자동화가 의외로 토큰 많이 씀. 해결: model="claude-haiku-4-5-20251001"로 다운그레이드 + 패턴 1·3 적용.

에러 5: 서브에이전트가 메인 에이전트와 같은 토큰 사용량을 보고함

원인: parent_tool_use_id 추적 누락. 해결: Hooks에서 parent_tool_use_id 별로 집계 분리.

Photo by Ilya Pavlov on Unsplash | Agent SDK·Client SDK·CLI·Managed Agents 중 어디로?

Agent SDK vs Client SDK vs Claude Code CLI vs Managed Agents

흔한 경로: Agent SDK로 로컬 프로토타입 → Managed Agents로 프로덕션 이전.

핵심 수치 한 페이지

다른 AI Tutorial 카테고리에서도 6월 AI 코딩 도구 가이드를 누적 정리하고 있으니 본인 워크플로에 맞게 비교 참고하세요.

---

참고 자료

• Agent SDK overview — Claude Code Docs — Anthropic 공식, 2026년 6월 기준
• Use the Claude Agent SDK with your Claude plan — Anthropic 공식 6/15 정책 안내
• Building agents with the Claude Agent SDK — Anthropic Engineering, 2026년
• Claude Code Updates by Anthropic — June 2026 — Releasebot, 2026년 6월
• TypeScript SDK CHANGELOG — Anthropic GitHub
• Python SDK CHANGELOG — Anthropic GitHub
• AI Agent Frameworks (2026 Update): 8 SDKs Compared — MorphLLM, 2026년

함께 읽으면 좋은 글:

• Cursor 6월 업데이트 완전 정리: Auto-Review·Bugbot 사용량 과금·Premium Seat - 6월 4일 — 같은 풀 분리 패턴, Cursor 사례
• Claude Opus 4.8 완전 정리: 코드 결함 4배 감소·Fast Mode 3배 저렴 - 5월 31일 — Agent SDK 기본 모델 + Dynamic Workflows 원리
• Claude Fable 5 완전 정리: Mythos 첫 공개·6/22까지 무료 - 6월 10일 — Agent SDK로 호출 가능한 최강 모델
• Claude Code 5월 업데이트 총정리: 플러그인 URL 설치·세션 ID·MCP 메모리 누수 수정 - 5월 7일 — Agent SDK의 모태 + 인터랙티브 한도 구조