Rihpig

Posted on May 14 • Originally published at apidog.com

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

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

지금 Apidog 사용해보기

배포 봇, 연구 보조원, 분류 도구 같은 맞춤형 에이전트를 만들고 싶었지만 프로토타입을 위해 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로 인증하면 기존 API 과금 모델을 따릅니다.

크레딧으로 사용할 수 있는 작업

Agent SDK 크레딧은 일반 Claude 사용량과 다르게 적용됩니다. 자동화, 스크립트, 비대화형 워크플로에만 해당한다고 보면 됩니다.

Agent SDK 크레딧 적용 대상:

Python 또는 TypeScript 프로젝트에서 Claude Agent SDK 호출
Claude Code의 claude -p 명령어
Claude Code GitHub Actions 통합
Agent SDK 방식으로 인증하는 타사 애플리케이션

적용되지 않는 대상:

대화형 Claude Code 세션
Claude 웹 앱 또는 모바일 앱 대화
Claude Cowork 세션

즉, Agent SDK 크레딧은 프로그래밍 방식의 자동화 작업에 특화되어 있습니다. 일반 Claude Code 사용량은 기존 플랜 제한에 속하며, Anthropic은 최근 7월 13일까지 이를 50% 인상했습니다.

정리하면 두 예산이 분리됩니다.

대화형 Claude Code: 기존 Claude 플랜 사용량
Agent SDK / claude -p / GitHub Actions: Agent SDK 크레딧

이 구조 덕분에 일상적인 코딩 한도를 소진하지 않고도 SDK 기반 에이전트를 실험할 수 있습니다.

크레딧이 소진되면 어떻게 되나요?

월별 크레딧을 모두 사용한 뒤의 동작은 추가 사용 설정에 따라 달라집니다.

추가 사용 활성화: 초과분이 표준 API 요율로 종량제 청구됩니다.
추가 사용 비활성화: 크레딧 한도에 도달하면 다음 결제 주기까지 요청이 중단됩니다.

권장 설정은 다음과 같습니다.

프로토타입, 개인 실험: 추가 사용 비활성화
운영 자동화, CI/CD, 지속 실행 작업: 추가 사용 활성화

크레딧은 항상 먼저 차감됩니다. 월별 할당량을 모두 사용하기 전까지는 초과 요금이 발생하지 않습니다.

참여 방법

Agent SDK 크레딧은 기본적으로 활성화되어 있지 않습니다. 한 번 직접 Claim해야 합니다.

구독을 보유한 Claude 계정에 로그인합니다.
- Pro/Max: 개인 사용자 계정
- Team/Enterprise: 해당 시트 계정
Claude Agent SDK 플랜 설정 페이지로 이동합니다. 링크는 Anthropic의 공식 지원 문서에서 확인할 수 있습니다.
Agent SDK 크레딧을 Claim합니다.
이후 매달 크레딧이 자동 갱신됩니다.

Team 플랜에서는 각 사용자가 직접 Claim해야 합니다. 관리자가 시트 구성원을 대신해 Claim할 수 없습니다.

Python 또는 TypeScript에서 SDK 설정하기

Agent SDK는 Python과 TypeScript를 지원합니다. 두 방식 모두 원시 API 키 대신 Claude Code CLI 로그인을 통해 플랜 인증을 사용할 수 있습니다.

Python

설치합니다.

pip install claude-agent-sdk

Claude Code에 로그인합니다.

claude login

이 명령은 Claude 플랜에 연결된 자격 증명을 로컬에 저장합니다. 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);

CI 러너, Docker 컨테이너, 원격 개발 환경처럼 SDK가 Claude Code 자격 증명을 자동으로 찾지 못하는 환경에서는 환경 변수로 인증 정보를 설정할 수 있습니다. 정확한 변수 이름은 Anthropic의 Agent SDK 문서를 확인하세요.

SDK 설정 전에 Claude Code 로그인 오류가 발생한다면 유효하지 않은 custom3p 엔터프라이즈 구성 수정 가이드를 먼저 확인하세요.

`claude -p`로 비대화형 워크플로 만들기

코드를 직접 작성하지 않고도 Agent SDK 크레딧을 사용할 수 있습니다. Claude Code의 claude -p 명령어를 사용하면 됩니다.

-p는 Claude Code를 비대화형 모드로 실행합니다. 프롬프트를 전달하면 레포지토리에서 작업을 수행한 뒤 종료됩니다. 따라서 다음 작업에 적합합니다.

CI 파이프라인
cron 작업
Git 훅
릴리스 노트 생성
PR 검사 자동화

예를 들어, 보안 이슈와 breaking change를 검사하는 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 크레딧에서 차감됩니다. 따라서 자동화 워크플로를 연결해도 일상적인 Claude Code 사용 한도와 분리됩니다.

이 방식은 자율 루프를 위한 /goal 명령어, 에이전트 실행 컨텍스트를 고정하기 위한 AGENTS.md 컨텍스트 파일과 함께 사용하기 좋습니다.

GitHub Actions 통합

Claude Code GitHub Actions 통합도 SDK 크레딧 적용 대상입니다.

예를 들어 Claude를 다음 작업에 연결했다면 해당 워크플로 실행은 GitHub 앱을 설치한 사용자에게 연결된 Agent SDK 크레딧에서 차감됩니다.

PR 리뷰
이슈 분류
릴리스 노트 생성
변경 사항 요약

이는 자동화가 계속 실행되고 비용이 앱에 연결된 API 키로 부과되던 Claude Code 기반 GitHub 분류 봇 Clawsweeper 같은 프로젝트에 특히 유용합니다.

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

Agent SDK의 가치는 단순 텍스트 응답보다 실제 작업을 수행할 때 커집니다. 예를 들면 다음과 같습니다.

내부 API 호출
데이터베이스 조회
배포 파이프라인 트리거
이슈 또는 PR 자동 분류
테스트 결과 분석

이때 중요한 것은 에이전트가 호출하는 API의 계약입니다. 계약이 없으면 에이전트는 요청 형식과 응답 구조를 추측하게 됩니다. 그러면 개발자는 잘못된 페이로드, 누락된 필드, 스키마 불일치를 디버깅해야 합니다.

Apidog을 사용하면 다음 흐름으로 에이전트용 API 계약을 관리할 수 있습니다.

Apidog에서 API 계약을 먼저 정의합니다.

엔드포인트, 요청 스키마, 응답 스키마, 예시 페이로드를 작성합니다.
OpenAPI 스펙을 내보냅니다.

이 스펙을 에이전트 컨텍스트로 전달합니다.
SDK 에이전트가 실제 엔드포인트를 호출하게 합니다.

에이전트는 추측 대신 명시된 스키마를 기준으로 요청을 구성합니다.
Apidog CLI로 검증합니다.

에이전트 실행 후 API가 계약대로 응답하는지 자동 확인할 수 있습니다.

MCP 서버를 통해 여러 도구를 오케스트레이션하는 에이전트라면 Apidog을 사용한 MCP 서버 테스트 워크플로도 참고할 수 있습니다. 에이전트가 호출하는 도구에 대한 end-to-end 테스트 커버리지를 확보하는 데 도움이 됩니다.

더 큰 설계 흐름은 디자인 우선 API 워크플로 가이드에서 확인할 수 있습니다. 에이전트가 검증 가능한 계약을 갖고 있으면, 개발자는 JSON 스키마 버그를 추적하는 대신 더 좋은 제약과 계약을 설계하는 데 집중할 수 있습니다.

Agent SDK 프로젝트를 위한 계약 계층이 필요하다면 Apidog을 무료로 다운로드하세요.

별도 API 키가 여전히 필요한 경우

플랜 기반 크레딧은 대부분의 개발자에게 좋은 기본값입니다. 하지만 다음 경우에는 별도 API 키가 더 적합할 수 있습니다.

예측 가능한 운영 예산이 필요한 프로덕션 에이전트

플랜 크레딧은 월별 고정 금액입니다. 대규모 자동화를 운영한다면 사용량 기반 API 키가 재무 및 운영팀에 더 명확한 청구 구조를 제공합니다.
다중 조직 또는 공유 청구 소스가 필요한 경우

플랜 크레딧은 사용자별로 제공됩니다. 팀 전체가 하나의 청구 소스를 공유해야 한다면 API 키가 필요합니다.
Enterprise Standard 시트 사용

Enterprise Standard 시트는 Agent SDK 크레딧을 받지 못합니다. 이 시트에서 SDK 접근이 필요하다면 API 키를 사용해야 합니다.

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

시작 전 체크리스트

[ ] 현재 플랜이 자격 목록에 포함되는지 확인합니다.
- Pro
- Max 5x
- Max 20x
- Team Standard
- Team Premium
- Enterprise 사용량 기반
- Enterprise Premium 시트
[ ] Agent SDK 크레딧을 한 번 Claim합니다.
[ ] 추가 사용을 활성화할지 결정합니다.
- 프로토타입: 비활성화
- 프로덕션 자동화: 활성화
[ ] claude login을 실행해 플랜 인증을 설정합니다.
[ ] Python 또는 TypeScript SDK 패키지를 설치합니다.
[ ] 최소 에이전트를 실행합니다.
[ ] ANTHROPIC_API_KEY 없이 플랜 인증으로 실행되는지 확인합니다.
[ ] 처음 몇 번 실행한 뒤 계정 설정에서 크레딧 잔액을 확인합니다.

자주 묻는 질문

플랜 크레딧을 사용하려면 기존 ANTHROPIC_API_KEY를 제거해야 하나요?

반드시 제거할 필요는 없습니다. SDK는 Claude Code의 로컬 자격 증명이 있으면 이를 사용할 수 있습니다. 일반적으로 claude login만으로 플랜 기반 청구를 사용할 수 있습니다. 다른 도구를 위해 ANTHROPIC_API_KEY를 유지해야 한다면 그대로 둘 수 있습니다.

크레딧에서 하나의 요청은 어떻게 계산되나요?

크레딧은 요청 수가 아니라 달러 기준으로 차감됩니다. 각 SDK 호출은 Anthropic의 API 사용 요율에 따라 비용이 계산됩니다. 모델 호출, 컨텍스트 토큰, 도구 사용 비용이 크레딧 잔액에서 차감됩니다.

팀원과 크레딧을 공유할 수 있나요?

아니요. 크레딧은 사용자별로 제공되며 양도할 수 없습니다. 각 Team 또는 Enterprise 시트에는 자체 크레딧 풀이 있습니다.

기존 Anthropic API 콘솔 잔액은 어떻게 되나요?

그대로 유지됩니다. 플랜 크레딧은 별도 결제 메커니즘입니다. API 콘솔에 선불 잔액이 있다면 API 키를 사용하는 작업에 계속 적용됩니다.

Agent SDK는 Claude Code와 같은가요?

아니요. Claude Code는 Anthropic의 공식 CLI 및 IDE 확장입니다. Agent SDK는 맞춤형 에이전트를 만들기 위한 Python 또는 TypeScript 라이브러리입니다. 크레딧은 Agent SDK와 Claude Code의 비대화형 claude -p 명령어에 적용됩니다. 대화형 Claude Code는 일반 플랜 사용량에 포함됩니다.

GitHub Actions 청구 방식도 바뀌나요?

공식 Claude Code GitHub Actions 통합을 사용하고, 설치 사용자 계정에서 크레딧을 Claim했다면 해당 실행은 API 키 청구 대신 SDK 크레딧에서 차감됩니다.

크레딧은 Agent SDK와 claude -p 외부에서도 사용할 수 있나요?

적용 대상은 Python/TypeScript Agent SDK, claude -p, Claude Code GitHub Actions, 타사 Agent SDK 앱입니다. 그 외 Claude 사용량은 실행 위치에 따라 일반 Claude 플랜 제한 또는 API 키 청구로 처리됩니다.

DEV Community

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

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

크레딧으로 사용할 수 있는 작업

크레딧이 소진되면 어떻게 되나요?

참여 방법

Python 또는 TypeScript에서 SDK 설정하기

Python

TypeScript

`claude -p`로 비대화형 워크플로 만들기

GitHub Actions 통합

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

별도 API 키가 여전히 필요한 경우

시작 전 체크리스트

자주 묻는 질문

Top comments (0)

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

크레딧으로 사용할 수 있는 작업

크레딧이 소진되면 어떻게 되나요?

참여 방법

Python 또는 TypeScript에서 SDK 설정하기

Python

TypeScript

claude -p로 비대화형 워크플로 만들기

GitHub Actions 통합

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

별도 API 키가 여전히 필요한 경우

시작 전 체크리스트

자주 묻는 질문

`claude -p`로 비대화형 워크플로 만들기