Claude API를 코드에서 호출할 때, HTTP 요청을 직접 손으로 짜는 대신 공식 SDK를 쓰면 인증·재시도·스트리밍·타입 처리를 라이브러리가 대신 해 줍니다. 이 글은 Claude의 공식 클라이언트 SDK를 처음 설치하고 첫 호출까지 해 보는 입문 가이드입니다. (기준 시점: 2026년 6월. 버전·모델은 변동될 수 있으니 공식 문서에서 최신 정보를 확인하세요.)
SDK란 무엇이고 왜 쓰나
Claude API는 https://api.anthropic.com에 요청을 보내는 REST API입니다. 직접 호출하려면 헤더·인증·JSON 본문·에러 처리를 모두 손으로 다뤄야 합니다. SDK(Software Development Kit)는 이 과정을 언어별로 감싼 공식 라이브러리로, Anthropic은 각 SDK가 관용적 인터페이스, 타입 안전성, 스트리밍·재시도·에러 처리 내장 지원을 제공한다고 안내합니다.
참고: 여기서 말하는 "클라이언트 SDK"는 Claude API를 호출하기 위한 것입니다. Claude Code를 구동하는 Agent SDK(claude-agent-sdk)는 이름이 비슷하지만 별개 제품입니다(글 마지막에서 구분).
공식 지원 언어
Anthropic은 Python, TypeScript, Java, Go, Ruby, C#, PHP 및 커맨드라인(CLI)용 공식 클라이언트 SDK를 제공합니다. 플랫폼 지원 범위는 언어마다 다르므로, 세부 설치는 각 언어별 문서를 확인하세요.
설치
가장 많이 쓰이는 두 언어 기준입니다.
- Python:
pip install anthropic— Python 3.9 이상이 필요합니다. - TypeScript / JavaScript:
npm install @anthropic-ai/sdk— Node.js 20 LTS 이상, TypeScript 4.9 이상을 지원합니다.
API 키는 코드에 직접 박지 말고 환경변수(ANTHROPIC_API_KEY)로 관리하는 것이 안전합니다. 공식 문서도 Python에서 python-dotenv로 .env 파일에 키를 넣어 소스 관리에 노출되지 않게 할 것을 권장합니다.
첫 호출 — Python
클라이언트를 만들고 messages.create로 메시지를 보내면, 응답의 content에 모델의 답이 담겨 옵니다.
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ.get("ANTHROPIC_API_KEY"),
)
message = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[
{"role": "user", "content": "안녕, Claude"}
],
)
print(message.content)첫 호출 — TypeScript
TypeScript SDK는 모든 요청 파라미터와 응답 필드에 대한 타입 정의를 포함합니다. 사용법은 Python과 거의 동일합니다.
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: process.env["ANTHROPIC_API_KEY"],
});
const message = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }],
});
console.log(message.content);위 코드의 모델 문자열 claude-opus-4-8은 공식 문서 예시 기준입니다. 사용 가능한 모델 목록은 바뀔 수 있으니 모델 개요 문서에서 확인하세요.
자주 쓰는 기능
- 토큰 사용량 확인: 응답의
usage속성으로 입력·출력 토큰 수를 볼 수 있습니다(예:{ input_tokens, output_tokens }). 과금은 토큰 단위이므로 비용 추적에 유용합니다. - 스트리밍: SDK는 서버 전송 이벤트(SSE)를 통한 스트리밍 응답을 지원합니다. 긴 답변을 토큰이 생성되는 대로 받아볼 수 있습니다.
- 재시도·에러 처리 내장: 일시적 오류에 대한 재시도와 에러 타입 처리가 SDK에 포함돼 있어, 직접 구현할 필요가 줄어듭니다.
- 베타 기능: 모든 SDK에서
beta네임스페이스로 베타 기능에 접근할 수 있습니다.
클라이언트 SDK vs Agent SDK
이름이 비슷해 혼동하기 쉬운 두 가지를 구분합니다.
- 클라이언트 SDK(이 글의 주제,
anthropic/@anthropic-ai/sdk): Claude API를 호출하는 얇은 래퍼. 메시지 생성, 스트리밍, 토큰 확인 등 API 기능을 그대로 노출합니다. - Agent SDK(
claude-agent-sdk/@anthropic-ai/claude-agent-sdk): Claude Code를 구동하는 에이전트 루프·도구·컨텍스트 관리를 프로그래밍 가능한 라이브러리로 제공합니다. 파일 읽기·편집, bash 실행, 웹 검색 같은 내장 도구와 커스텀 도구, MCP 연결을 지원합니다. (이전 명칭: Claude Code SDK)
단순히 "프롬프트를 보내고 답을 받는" 통합이면 클라이언트 SDK로 충분하고, "스스로 파일을 읽고 명령을 실행하는 에이전트"를 만들려면 Agent SDK가 적합합니다.
정리
핵심만 기억하세요: ① SDK는 raw HTTP를 대신 처리해 주는 공식 라이브러리다, ② 설치는 Python pip install anthropic(3.9+) / TypeScript npm install @anthropic-ai/sdk(Node 20+)다, ③ 클라이언트를 만들고 messages.create를 호출하면 content로 답이 온다, ④ 클라이언트 SDK와 Agent SDK는 별개다. 더 깊은 사용법은 Claude 공식 SDK 문서를 참고하세요.
관련 글: 도구 사용(Tool Use), API 비용 최적화(프롬프트 캐싱·Batch)도 함께 보세요.
이 글은 Anthropic 공식 문서를 토대로 작성한 입문 설명입니다. SDK 버전·필요 런타임·모델 목록은 업데이트될 수 있으므로, 실제 구현 전 공식 문서에서 최신 사양을 확인하세요. (공식 출처: docs.claude.com)