Claude 플랜으로 Claude Agent SDK 사용하는 방법

Anthropic은 2026년 6월 15일부터 기존 Claude 구독으로 Claude Agent SDK를 실행할 수 있도록 허용합니다. 이전에는 Agent SDK로 무언가를 구축하려면 Claude Pro 또는 Max에 대해 이미 지불하고 있는 비용 외에 종량제 요금이 부과되는 별도의 API 키가 필요했습니다. 6월 15일부터는 매월 Claude 플랜에 Agent SDK 사용을 위한 크레딧 잔액이 포함됩니다. API 키가 필요하지 않습니다.

배포 봇, 연구 보조원, 분류 도구와 같은 맞춤형 에이전트를 구축하고 싶었지만, 단순히 프로토타입을 만들기 위해 Anthropic에 별도의 결제 카드를 등록하고 싶지 않았다면, 이번 변경 사항이 중요합니다. 이제 Pro 구독에는 월 $20 상당의 Agent SDK 사용량이 포함됩니다. Max 20x는 $200를, Team Premium 시트에는 $100가 제공됩니다.

버튼

2026년 6월 15일, 무엇이 달라졌나요?

간단히 말해: 이제 Agent SDK 사용량은 Claude 플랜에 연결된 월별 크레딧에서 차감됩니다. 이전에는 별도의 콘솔 잔액을 통해 Anthropic API로 청구되었습니다.

다음은 Anthropic의 발표에서 직접 가져온 플랜별 크레딧입니다:

플랜	월별 Agent SDK 크레딧
Pro	$20
Max 5x	$100
Max 20x	$200
Team Standard (시트당)	$20
Team Premium (시트당)	$100
Enterprise (사용량 기반)	$20
Enterprise Premium 시트	$200

몇 가지 중요한 규칙:

Enterprise Standard 시트 사용자는 크레딧을 받지 못합니다. API 키를 사용하거나 Premium 시트로 업그레이드해야 합니다.
크레딧은 사용자별로 제공되며 양도할 수 없습니다. 본인의 시트 크레딧은 팀원의 크레딧과 합칠 수 없습니다.
사용되지 않은 크레딧은 이월되지 않습니다. 결제 주기가 끝나면 남은 크레딧은 모두 초기화됩니다.
일회성 동의가 필요합니다. 계정에서 한 번 클레임(Claim)해야만 크레딧이 활성화됩니다. 그 후에는 매달 자동으로 갱신됩니다.
API 키 사용자는 크레딧을 받지 못합니다. 이는 플랜별 정책입니다. ANTHROPIC_API_KEY를 통해 인증해왔다면, 기존 결제 모델을 따르고 있는 것입니다.

크레딧으로 무엇을 이용할 수 있으며, 무엇을 이용할 수 없는가

Anthropic은 이를 신중하게 구분했습니다. 자세히 읽어보세요. '포함됨'과 '포함되지 않음'의 경계가 실제 청구서 변경 여부를 결정합니다.

Agent SDK 크레딧으로 이용 가능한 항목:

자체 Python 또는 TypeScript 프로젝트에서 Claude Agent SDK 호출
Claude Code의 claude -p 명령어 (스크립트 에이전트 실행에 사용되는 비대화형 모드)
Claude Code GitHub Actions 통합
Agent SDK를 사용하여 인증하는 타사 애플리케이션

포함되지 않는 항목 (이들은 여전히 일반 Claude 플랜에서 차감되거나 별도로 유지됩니다):

대화형 Claude Code 세션 (매일 사용하는 일반적인 CLI)
Claude 웹 앱 또는 모바일 앱에서의 대화
Claude Cowork 세션

다시 말해, Agent SDK 크레딧은 프로그래밍 방식, 자동화 또는 비대화형 작업량에 특화되어 있습니다. 일반적인 Claude Code 작업은 플랜의 기존 사용 제한에 속하며, Anthropic은 최근 7월 13일까지 이를 50% 인상했습니다. 두 개의 별도 예산, 두 개의 별도 목적입니다.

이는 의미 있는 설계 선택입니다. 즉, Claude Code를 통해 일상적인 코딩에 사용하는 예산을 침해하지 않고 SDK를 기반으로 구축된 맞춤형 에이전트를 실험할 수 있습니다.

크레딧이 소진되었을 때

크레딧은 매월 고정된 금액을 제공합니다. 이를 초과했을 때 어떤 일이 발생하는지는 한 가지 설정에 따라 달라집니다.

추가 사용 활성화: 초과분은 플랜의 결제 수단을 통해 표준 API 요율로 종량제로 청구됩니다.
추가 사용 비활성화: 요청은 크레딧 한도에 도달하면 주기가 재설정될 때까지 중단됩니다.

프로토타입 작업의 경우, 추가 사용을 비활성화해 두세요. 명확한 중지 신호를 받고 예상치 못한 청구서를 피할 수 있습니다. 계속 실행되어야 하는 프로덕션 수준의 자동화 작업에는 이를 활성화하세요.

크레딧은 항상 먼저 소진됩니다. 월별 할당량이 모두 소진될 때까지 초과 요금을 지불하지 않습니다.

참여 방법

크레딧은 기본적으로 활성화되어 있지 않습니다. 참여는 일회성이며 결제 주기를 넘어 지속되지만, 한 번은 직접 활성화해야 합니다.

구독을 소유한 Claude 계정에 로그인합니다 (Pro/Max의 사용자 계정 또는 Team/Enterprise의 시트 계정).
Claude Agent SDK 플랜 설정 (Anthropic의 공식 지원 문서에서 링크됨)을 방문합니다.
크레딧을 클레임합니다. 이후에는 매달 크레딧이 자동으로 갱신됩니다.

Team 플랜에 여러 시트가 있는 경우, 모든 사용자가 개별적으로 클레임해야 합니다. 관리자는 시트 회원을 대신하여 클레임할 수 없습니다.

Python 또는 TypeScript에서 SDK 설정하기

Agent SDK는 Python과 TypeScript 모두로 제공됩니다. 둘 다 원시 API 키가 아닌 Claude Code CLI를 통해 플랜에 대해 동일한 방식으로 인증합니다.

Python

설치:

pip install claude-agent-sdk

먼저 Claude Code에 로그인하여 인증합니다:

claude login

이렇게 하면 플랜에 연결된 자격 증명이 로컬에 저장됩니다. Python SDK는 이를 자동으로 인식하므로, 플랜 기반 사용을 위해 ANTHROPIC_API_KEY를 설정할 필요가 없습니다.

최소한의 에이전트는 다음과 같습니다:

from claude_agent_sdk import Agent

agent = Agent(
    system_prompt="You are a code review assistant.",
)

response = agent.run("Review the diff in /tmp/patch.diff and flag concerns.")
print(response.text)

이전에는 동일한 호출에 ANTHROPIC_API_KEY와 종량제 API 청구가 필요했습니다. 이제는 플랜 크레딧에서 차감됩니다.

TypeScript

설치:

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

동일한 Claude Code 로그인으로 인증합니다:

claude login

TypeScript의 최소 에이전트:

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

const agent = new Agent({
  systemPrompt: "You are a code review assistant.",
});

const response = await agent.run(
  "Review the diff in /tmp/patch.diff and flag concerns."
);
console.log(response.text);

SDK가 Claude Code 자격 증명을 자동으로 찾을 수 없는 환경 (CI 러너, Docker 컨테이너, 원격 개발 상자)에서는 환경 변수로 설정할 수 있습니다. Anthropic은 Agent SDK 문서에 정확한 변수 이름을 게시합니다.

SDK 설정에 도달하기도 전에 Claude Code 로그인이 구성 오류를 발생시키는 경우, 유효하지 않은 custom3p 엔터프라이즈 구성 수정이 가장 일반적인 원인을 해결합니다.

`claude -p` 워크플로

코드를 작성하지 않고 Agent SDK 크레딧을 사용하는 두 번째 방법이 있습니다: Claude Code의 claude -p 명령어입니다.

-p는 Claude Code를 비대화형 모드로 전환합니다. 프롬프트를 넘겨주면, 레포지토리에서 실행하고 종료됩니다. 양방향 세션이 없습니다. 이것이 Claude Code를 CI 파이프라인, cron 작업 및 Git 훅에 스크립트화하는 방법입니다.

간단한 예시: 위험한 변경 사항을 Claude에게 알려달라고 요청하는 pre-commit 훅입니다.

#!/usr/bin/env bash
# .git/hooks/pre-commit

DIFF=$(git diff --cached)
claude -p "Review this diff for security issues, secret leaks, and breaking changes. Return PASS or FAIL with reasoning:\n\n$DIFF"

6월 15일 이후의 모든 claude -p 호출은 대화형 Claude Code 예산이 아닌 Agent SDK 크레딧에서 차감됩니다. 이는 일상적인 코딩에 필요한 제한을 소진할 걱정 없이 자동화된 워크플로에 연결할 수 있음을 의미합니다.

이것은 자율 루프를 위한 /goal 명령어와 에이전트를 실행 전반에 걸쳐 안정적으로 조종하기 위한 AGENTS.md 컨텍스트 파일과 잘 어울립니다.

GitHub Actions 통합

Claude Code GitHub Actions 통합은 SDK 크레딧으로 보장되는 세 번째 작업량입니다. Claude를 PR 검토, 이슈 분류 또는 릴리스 노트 생성에 연결했다면, 이제 해당 워크플로 실행은 GitHub 앱을 설치한 사용자에게 해당하는 Agent SDK 크레딧으로 청구됩니다.

이는 자동화가 지속적으로 실행되고 청구서가 앱에 연결된 API 키로 부과되던 Claude Code 기반 GitHub 분류 봇인 Clawsweeper와 같은 프로젝트에 유용합니다.

실제 에이전트 구축: SDK와 Apidog 연결

Agent SDK의 진정한 가치는 텍스트 응답 이상의 작업을 수행하는 에이전트, 즉 실제 API를 호출하고, 데이터베이스를 쿼리하고, 코드를 배포하는 에이전트에 있습니다. 이를 안정적으로 작동시키려면 에이전트가 접근하는 모든 외부 API에 대해 정의된 계약이 필요합니다. 계약이 없으면 에이전트는 요청 형태를 추측하게 되고, 개발자는 잘못된 페이로드를 수정하는 데 디버깅 시간을 보내게 됩니다.

Apidog이 워크플로에 적합한 부분은 다음과 같습니다:

Apidog에서 먼저 API 계약을 정의합니다. 엔드포인트, 요청/응답 스키마 및 예시 페이로드를 명시합니다. 이것이 진실의 원천이 됩니다.
OpenAPI를 내보내기하여 컨텍스트로 에이전트에 전달합니다.
SDK를 사용하여 실제 엔드포인트에 에이전트를 연결합니다. 에이전트는 정확하다고 알고 있는 스키마를 사용하여 API를 호출합니다.
Apidog CLI로 검증합니다. 모든 에이전트 실행은 API가 여전히 계약에서 약속한 것을 반환하는지 확인할 수 있습니다.

MCP 서버를 통해 다른 도구를 오케스트레이션하는 에이전트의 경우, Apidog을 사용한 MCP 서버 테스트 워크플로가 적합한 가이드입니다. 에이전트가 호출하는 도구에 대한 종단 간 테스트 커버리지를 확보할 수 있습니다.

더 큰 그림은 디자인 우선 API 워크플로 가이드에 있습니다. 에이전트가 검증할 계약을 가지고 있다면, 개발자로서의 시간은 에이전트 출력에서 JSON 스키마 버그를 쫓는 대신 더 나은 계약과 제약을 작성하는 데 집중될 수 있습니다.

Agent SDK 프로젝트를 지원하는 계약 계층을 원하시면 Apidog을 무료로 다운로드하세요.

별도의 API 키를 여전히 원하는 경우

플랜 기반 크레딧은 대부분의 개발자에게 적합한 기본값입니다. 하지만 별도의 API 키가 합리적인 경우도 있습니다:

예측 가능한 예산이 필요한 프로덕션 에이전트. 플랜 크레딧은 고정된 금액으로 제한됩니다. 무제한 확장이 필요한 에이전트를 운영하는 경우, 사용량 기반 API 키는 재무 및 운영팀에 더 명확한 청구 내역을 제공합니다.
다중 조직 접근. API 키는 단일 사용자에게 묶여 있지 않습니다. 팀이 하나의 청구 소스에 대한 공유 접근을 원한다면, 여전히 API 키를 사용해야 합니다.
Enterprise Standard 시트. 이 시트는 Agent SDK 크레딧을 받지 못합니다. Enterprise Standard 시트를 사용 중이고 SDK 접근이 필요하다면, API 키가 유일한 방법입니다.

무료 Claude API 접근 가이드는 Pro 플랜이나 유료 API 키 없이 Claude를 사용하는 방법을 다룹니다.

시작하기 전에 깔끔한 체크리스트

[ ] 귀하의 플랜이 자격 목록(Pro, Max 5x, Max 20x, Team Standard, Team Premium, Enterprise 사용량 기반, Enterprise Premium 시트)에 포함되어 있는지 확인하십시오.
[ ] Agent SDK 크레딧에 대한 일회성 동의를 클레임하십시오.
[ ] 추가 사용을 활성화할지 여부를 결정하십시오 (프로토타입은 비활성화, 프로덕션은 활성화).
[ ] claude login을 실행하여 플랜에 대해 SDK를 인증하십시오.
[ ] Python 또는 TypeScript SDK 패키지를 설치하십시오.
[ ] 최소한의 에이전트를 구축하고 ANTHROPIC_API_KEY 설정 없이 실행되는지 확인하십시오.
[ ] 처음 몇 번 실행 후 계정 설정에서 크레딧 잔액을 확인하십시오.

자주 묻는 질문

플랜 크레딧이 작동하려면 기존 ANTHROPIC_API_KEY를 제거해야 하나요? SDK는 Claude Code의 로컬 자격 증명이 있는 경우 이를 사용합니다. 즉, claude login만으로도 SDK를 플랜 기반 청구로 전환하기에 충분합니다. 다른 도구를 위해 환경에 ANTHROPIC_API_KEY를 설정해 두었다면 그대로 두세요. SDK는 플랜 인증이 있을 경우 이를 우선합니다.

크레딧에서 하나의 '요청'으로 간주되는 것은 무엇인가요? 크레딧은 요청 수가 아닌 달러로 책정됩니다. 각 SDK 호출은 Anthropic이 API 사용에 대해 게시하는 동일한 요율로 청구됩니다. 도구 사용 및 컨텍스트 토큰을 포함한 모든 모델 호출 비용만큼 크레딧 잔액이 줄어듭니다. 요청당 추가 요금은 없습니다.

크레딧을 팀원과 공유할 수 있나요? 아니요. 크레딧은 사용자별로 제공되며 양도할 수 없습니다. 각 팀 또는 엔터프라이즈 시트에는 자체 크레딧 풀이 있습니다.

기존 Anthropic API 콘솔 잔액은 어떻게 되나요? 그대로 유지됩니다. 플랜 크레딧은 별도의 결제 메커니즘입니다. API 콘솔에 선불 잔액이 있었다면, 이는 API 키를 사용하는 모든 작업에 여전히 작동합니다.

Agent SDK는 Claude Code와 동일한가요? 아닙니다. Claude Code는 Anthropic이 제공하는 공식 CLI 및 IDE 확장입니다. Agent SDK는 맞춤형 에이전트를 구축하기 위한 프로그래밍 라이브러리(Python 또는 TypeScript)입니다. 크레딧은 SDK와 Claude Code의 비대화형 claude -p 명령어를 포함하며, 대화형 Claude Code는 일반 플랜 사용량에 따라 적용됩니다.

GitHub Actions 청구서가 변경되나요? 귀하의 Action이 공식 Claude Code GitHub Actions 통합을 사용하고 설치 사용자 계정에서 크레딧이 클레임되었다면, 해당 실행은 이제 API 키 청구 대신 SDK 크레딧에서 차감됩니다.

크레딧이 Agent SDK 및 claude -p 외부에서도 작동하나요? 네 가지 적용 영역(Python/TS의 SDK, claude -p, GitHub Actions, 타사 Agent SDK 앱) 외에서는 작동하지 않습니다. 다른 Claude 사용은 요청이 시작된 위치에 따라 플랜의 일반 제한 또는 API 키로 돌아갑니다.

버튼