Was this page helpful?
Anthropic Python SDK는 Python 애플리케이션에서 Anthropic REST API에 편리하게 접근할 수 있도록 합니다. 동기 및 비동기 작업, 스트리밍, 그리고 Amazon Bedrock, Vertex AI, Microsoft Foundry, AWS 기반 Claude Platform과의 통합을 지원합니다.
코드 예제가 포함된 API 기능 문서는 API 레퍼런스를 참조하세요. 이 페이지는 Python 전용 SDK 기능 및 구성을 다룹니다.
pip install anthropic플랫폼별 통합 또는 향상된 비동기 성능을 위해서는 extras와 함께 설치하세요:
# Amazon Bedrock 지원용
pip install "anthropic[bedrock]"
# Vertex AI 지원용
pip install "anthropic[vertex]"
# AWS 기반 Claude Platform 지원용
pip install "anthropic[aws]"
# Microsoft Foundry 지원은 기본 패키지에 포함되어 있습니다
# aiohttp를 통한 비동기 성능 향상용
pip install "anthropic[aiohttp]"Python 3.9 이상이 필요합니다.
import os
from anthropic import Anthropic
client = Anthropic(
# 이것은 기본값이며 생략할 수 있습니다
api_key=os.environ.get("ANTHROPIC_API_KEY"),
)
message = client.messages.create(
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hello, Claude",
}
],
model="claude-opus-4-8",
)
print(message.content)API 키가 소스 제어에 저장되지 않도록 python-dotenv를 사용하여 .env 파일에 ANTHROPIC_API_KEY="my-anthropic-api-key"를 추가하는 것을 고려하세요.
Workload Identity Federation을 포함한 인증 옵션에 대해서는 인증을 참조하세요.
import os
import asyncio
from anthropic import AsyncAnthropic
client = AsyncAnthropic(
api_key=os.environ.get("ANTHROPIC_API_KEY"),
)
async def main() -> None:
message = await client.messages.create(
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hello, Claude",
}
],
model="claude-opus-4-8",
)
print(message.content)
asyncio.run(main())향상된 비동기 성능을 위해 기본 httpx 대신 aiohttp HTTP 백엔드를 사용할 수 있습니다:
import os
import asyncio
from anthropic import AsyncAnthropic, DefaultAioHttpClient
async def main() -> None:
async with AsyncAnthropic(
api_key=os.environ.get("ANTHROPIC_API_KEY"),
http_client=DefaultAioHttpClient(),
) as client:
message = await client.messages.create(
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hello, Claude",
}
],
model="claude-opus-4-8",
)
print(message.content)
asyncio.run(main())SDK는 "Server-Sent Events"(서버 전송 이벤트), 즉 SSE를 사용한 스트리밍 응답을 지원합니다.
client = Anthropic()
stream = client.messages.create(
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hello, Claude",
}
],
model="claude-opus-4-8",
stream=True,
)
for event in stream:
print(event.type)비동기 클라이언트는 정확히 동일한 인터페이스를 사용합니다:
client = AsyncAnthropic()
stream = await client.messages.create(
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hello, Claude",
}
],
model="claude-opus-4-8",
stream=True,
)
async for event in stream:
print(event.type)SDK는 컨텍스트 매니저를 사용하고 누적된 텍스트와 최종 메시지에 접근할 수 있는 스트리밍 헬퍼도 제공합니다:
async def main() -> None:
async with client.messages.stream(
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Say hello there!",
}
],
model="claude-opus-4-8",
) as stream:
async for text in stream.text_stream:
print(text, end="", flush=True)
print()
message = await stream.get_final_message()
print(message.to_json())
asyncio.run(main())client.messages.stream(...)을 사용한 스트리밍은 누적 및 SDK 전용 이벤트를 포함한 다양한 헬퍼를 제공합니다.
또는 client.messages.create(..., stream=True)를 사용할 수 있으며, 이는 스트림의 이벤트에 대한 이터러블만 반환하고 메모리를 더 적게 사용합니다(최종 메시지 객체를 생성하지 않습니다).
usage 응답 속성을 통해 특정 요청의 정확한 사용량을 확인할 수 있습니다:
message = client.messages.create(...)
print(message.usage)
# Usage(input_tokens=25, output_tokens=13)요청을 보내기 전에 토큰을 계산할 수도 있습니다:
count = client.messages.count_tokens(
model="claude-opus-4-8", messages=[{"role": "user", "content": "Hello, world"}]
)
print(count.input_tokens) # 10이 SDK는 함수 호출이라고도 하는 도구 사용을 지원합니다. 자세한 내용은 Claude와 함께 도구 사용하기를 참조하세요.
SDK는 도구를 순수 Python 함수로 정의하고 실행하기 위한 헬퍼를 제공합니다. @beta_tool 데코레이터는 함수 시그니처와 docstring에서 도구 스키마를 생성합니다:
import json
from anthropic import Anthropic, beta_tool
client = Anthropic()
@beta_tool
def get_weather(location: str) -> str:
"""Get the weather for a given location.
Args:
location: The city and state, for example, San Francisco, CA
Returns:
A JSON-encoded string with the location, temperature, and weather condition.
"""
return json.dumps(
{
"location": location,
"temperature": "68°F",
"condition": "Sunny",
}
)
# tool_runner를 사용하여 도구 호출을 자동으로 처리합니다
runner = client.beta.messages.tool_runner(
max_tokens=1024,
model="claude-opus-4-8",
tools=[get_weather],
messages=[
{"role": "user", "content": "What is the weather in SF?"},
],
)
for message in runner:
print(message)각 반복마다 API 요청이 이루어집니다. Claude가 주어진 도구 중 하나를 호출하려고 하면 자동으로 호출되고, 결과는 다음 반복에서 모델에 직접 반환됩니다.
이 SDK는 client.messages.batches에서 Message Batches API를 지원합니다.
Message Batches는 요청 배열을 받으며, 각 객체는 custom_id 식별자와 표준 Messages API와 동일한 요청 params를 가집니다:
client.messages.batches.create(
requests=[
{
"custom_id": "my-first-request",
"params": {
"model": "claude-opus-4-8",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello, world"}],
},
},
{
"custom_id": "my-second-request",
"params": {
"model": "claude-opus-4-8",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hi again, friend"}],
},
},
]
)Message Batch가 처리되면(.processing_status == 'ended'로 표시됨) .batches.results()로 결과에 접근할 수 있습니다:
client = anthropic.Anthropic()
batch_id = "batch_abc123"
result_stream = client.messages.batches.results(batch_id)
for entry in result_stream:
if entry.result.type == "succeeded":
print(entry.result.message.content)파일 업로드에 해당하는 요청 매개변수는 다양한 형식으로 전달할 수 있습니다:
PathLike 객체(예: pathlib.Path)(filename, content, content_type) 튜플BinaryIO 파일 유사 객체from pathlib import Path
from anthropic import Anthropic
client = Anthropic()
# 파일 경로를 사용하여 업로드
client.beta.files.upload(
file=Path("/path/to/file"),
)
# 바이트를 사용하여 업로드
client.beta.files.upload(
file=("file.txt", b"my bytes", "text/plain"),
)비동기 클라이언트는 정확히 동일한 인터페이스를 사용합니다. PathLike 인스턴스를 전달하면 파일 내용이 자동으로 비동기적으로 읽힙니다.
라이브러리가 API에 연결할 수 없거나 API가 성공이 아닌 상태 코드(즉, 4xx 또는 5xx 응답)를 반환하면 APIError의 하위 클래스가 발생합니다:
import anthropic
try:
message = client.messages.create(
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hello, Claude",
}
],
model="claude-opus-4-8",
)
except anthropic.APIConnectionError as e:
print("The server could not be reached")
print(e.__cause__) # an underlying Exception, likely raised within httpx
except anthropic.RateLimitError as e:
print("A 429 status code was received; we should back off a bit.")
except anthropic.APIStatusError as e:
print("Another non-200-range status code was received")
print(e.status_code)
print(e.response)오류 코드는 다음과 같습니다:
| 상태 코드 | 오류 유형 |
|---|---|
| 400 | BadRequestError |
| 401 | AuthenticationError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 409 | ConflictError |
| 422 | UnprocessableEntityError |
| 429 | RateLimitError |
| >=500 | InternalServerError |
요청 디버깅에 대한 자세한 내용은 요청 ID를 참조하세요.
SDK의 모든 객체 응답은 request-id 응답 헤더에서 추가된 _request_id 속성을 제공하므로 실패한 요청을 빠르게 로깅하고 Anthropic에 보고할 수 있습니다.
message = client.messages.create(
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
model="claude-opus-4-8",
)
print(message._request_id) # e.g., req_018EeWyXxfu5pfWkrYcMdjWG_ 접두사를 사용하는 다른 속성과 달리 _request_id 속성은 공개 속성입니다. 별도로 문서화되지 않는 한, 다른 모든 _ 접두사 속성, 메서드 및 모듈은 비공개입니다.
특정 오류는 기본적으로 짧은 지수 백오프와 함께 2회 자동으로 재시도됩니다. 연결 오류(예: 네트워크 연결 문제로 인한), 408 Request Timeout, 409 Conflict, 429 Rate Limit 및 >=500 내부 오류는 모두 기본적으로 재시도됩니다.
max_retries 옵션을 사용하여 이를 구성하거나 비활성화할 수 있습니다:
# 모든 요청에 대한 기본값을 구성합니다:
client = Anthropic(
max_retries=0, # default is 2
)
# 또는 요청별로 구성합니다:
client.with_options(max_retries=5).messages.create(
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
model="claude-opus-4-8",
)기본적으로 요청은 10분 후에 타임아웃됩니다. float 또는 httpx.Timeout 객체를 허용하는 timeout 옵션으로 이를 구성할 수 있습니다:
import httpx
from anthropic import Anthropic
# 모든 요청에 대한 기본값 구성:
client = Anthropic(
timeout=20.0, # 20 seconds (default is 10 minutes)
)
# 더 세밀한 제어:
client = Anthropic(
timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)
# 요청별 재정의:
client.with_options(timeout=5.0).messages.create(
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
model="claude-opus-4-8",
)타임아웃 시 APITimeoutError가 발생합니다.
타임아웃된 요청은 기본적으로 두 번 재시도됩니다.
더 오래 실행되는 요청에는 스트리밍 Messages API를 사용하는 것을 고려하세요.
스트리밍을 사용하지 않고 큰 max_tokens 값을 설정하는 것은 피하세요. 일부 네트워크는 일정 시간이 지나면 유휴 연결을 끊을 수 있으며, 이로 인해 Anthropic으로부터 응답을 받지 못한 채 요청이 실패하거나 타임아웃될 수 있습니다.
스트리밍이 아닌 요청이 약 10분 이상 걸릴 것으로 예상되면 SDK는 ValueError를 발생시킵니다. stream=True를 전달하거나 클라이언트 또는 요청 수준에서 timeout 옵션을 재정의하면 이 오류가 비활성화됩니다.
스트리밍이 아닌 요청의 예상 "latency"(지연 시간)가 타임아웃보다 길면 클라이언트가 응답을 받지 못한 채 연결을 종료하고 재시도하게 됩니다.
SDK는 일부 네트워크에서 유휴 연결 타임아웃의 영향을 줄이기 위해 TCP 소켓 keep-alive 옵션을 설정합니다. 이는 클라이언트에 사용자 정의 http_client 옵션을 전달하여 재정의할 수 있습니다.
Claude API의 목록 메서드는 페이지네이션됩니다. for 구문을 사용하여 모든 페이지의 항목을 반복할 수 있습니다:
client = Anthropic()
all_batches = []
# 필요에 따라 추가 페이지를 자동으로 가져옵니다.
for batch in client.messages.batches.list(limit=20):
all_batches.append(batch)
print(all_batches)비동기 반복의 경우:
async def main() -> None:
all_batches = []
async for batch in client.messages.batches.list(limit=20):
all_batches.append(batch)
print(all_batches)
asyncio.run(main())또는 페이지 작업을 더 세밀하게 제어하기 위해 .has_next_page(), .next_page_info() 또는 .get_next_page() 메서드를 사용할 수 있습니다:
first_page = await client.messages.batches.list(limit=20)
if first_page.has_next_page():
print(f"will fetch next page using these details: {first_page.next_page_info()}")
next_page = await first_page.get_next_page()
print(f"number of items we just fetched: {len(next_page.data)}")
# 비동기 사용이 아닌 경우 `await`를 제거하세요.또는 반환된 데이터로 직접 작업할 수 있습니다:
first_page = await client.messages.batches.list(limit=20)
print(f"next page cursor: {first_page.last_id}")
for batch in first_page.data:
print(batch.id)
# 비동기 사용이 아닌 경우 `await`를 제거하세요.SDK는 2023-06-01로 설정된 anthropic-version 헤더를 자동으로 전송합니다.
필요한 경우 클라이언트 객체 또는 요청별로 기본 헤더를 설정하여 재정의할 수 있습니다.
기본 헤더를 재정의하면 SDK에서 잘못된 타입 및 기타 예기치 않거나 정의되지 않은 동작이 발생할 수 있습니다.
# 클라이언트의 모든 요청에 대한 기본 헤더 설정
client = Anthropic(
default_headers={"anthropic-version": "My-Custom-Value"},
)
# 또는 요청별로 재정의
client.messages.with_raw_response.create(
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
model="claude-opus-4-8",
extra_headers={"anthropic-version": "My-Custom-Value"},
)중첩된 요청 매개변수는 TypedDict입니다. 응답은 Pydantic 모델이며, JSON으로 다시 직렬화하는 것과 같은 작업을 위한 헬퍼 메서드도 제공합니다(v1, v2).
타입이 지정된 요청과 응답은 에디터 내에서 자동 완성 및 문서를 제공합니다. 버그를 더 일찍 발견하는 데 도움이 되도록 VS Code에서 타입 오류를 보려면 python.analysis.typeCheckingMode를 basic으로 설정하세요.
Pydantic 모델을 딕셔너리로 변환하려면 헬퍼 메서드를 사용하세요:
message = client.messages.create(...)
# JSON 문자열로 변환
json_str = message.to_json()
# 딕셔너리로 변환
data = message.to_dict()응답에서 명시적으로 null인 필드와 반환되지 않은(누락된) 필드를 구분할 수 있습니다:
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
)
if response.my_field is None:
if "my_field" not in response.model_fields_set:
print("field was not in the response")
else:
print("field was null")httpx가 반환하는 "원시" Response는 클라이언트의 .with_raw_response 속성을 통해 접근할 수 있습니다. 이는 응답 헤더 또는 기타 메타데이터에 접근하는 데 유용합니다:
client = Anthropic()
response = client.messages.with_raw_response.create(
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
model="claude-opus-4-8",
)
print(response.headers.get("request-id"))
message = (
response.parse()
) # get the object that `messages.create()` would have returned
print(message.content)이러한 메서드는 APIResponse 객체를 반환합니다.
.with_raw_response 방식은 요청을 할 때 전체 응답 본문을 즉시 읽습니다. 대신 응답 본문을 스트리밍하려면 .with_streaming_response를 사용하세요. 이는 컨텍스트 매니저가 필요하며 .read(), .text(), .json(), .iter_bytes(), .iter_text(), .iter_lines() 또는 .parse()를 호출할 때만 응답 본문을 읽습니다. 비동기 클라이언트에서는 이들이 비동기 메서드입니다.
with client.messages.with_streaming_response.create(
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
model="claude-opus-4-8",
) as response:
print(response.headers.get("request-id"))
for line in response.iter_lines():
print(line)응답이 안정적으로 닫히도록 하려면 컨텍스트 매니저가 필요합니다.
SDK는 표준 라이브러리 logging 모듈을 사용합니다.
환경 변수 ANTHROPIC_LOG를 debug 또는 info로 설정하여 로깅을 활성화할 수 있습니다:
export ANTHROPIC_LOG=debug이 라이브러리는 문서화된 API에 편리하게 접근할 수 있도록 타입이 지정되어 있습니다. 문서화되지 않은 엔드포인트, 매개변수 또는 응답 속성에 접근해야 하는 경우에도 라이브러리를 사용할 수 있습니다.
문서화되지 않은 엔드포인트에 요청하려면 client.get, client.post 및 기타 HTTP 동사를 사용할 수 있습니다. 재시도와 같은 클라이언트의 옵션은 이러한 요청을 할 때 적용됩니다.
import httpx
response = client.post(
"/foo",
cast_to=httpx.Response,
body={"my_param": True},
)
print(response.json())추가 매개변수를 명시적으로 보내려면 extra_query, extra_body 및 extra_headers 요청 옵션을 사용할 수 있습니다.
extra_ 매개변수는 동일한 이름의 문서화된 매개변수를 재정의합니다. 보안상의 이유로 이러한 메서드는 신뢰할 수 있는 입력 데이터에만 사용하세요.
문서화되지 않은 응답 속성에 접근하려면 response.unknown_prop과 같이 추가 필드에 접근할 수 있습니다. response.model_extra를 사용하여 Pydantic 모델의 모든 추가 필드를 dict로 가져올 수도 있습니다.
프록시 및 트랜스포트 지원을 포함하여 사용 사례에 맞게 httpx 클라이언트를 직접 재정의할 수 있습니다:
import httpx
from anthropic import Anthropic, DefaultHttpxClient
client = Anthropic(
# 또는 `ANTHROPIC_BASE_URL` 환경 변수를 사용하세요
base_url="http://my.test.server.example.com:8083",
http_client=DefaultHttpxClient(
proxy="http://my.test.proxy.example.com",
transport=httpx.HTTPTransport(local_address="0.0.0.0"),
),
)with_options()를 사용하여 요청별로 클라이언트를 사용자 정의할 수도 있습니다:
client.with_options(http_client=DefaultHttpxClient(...))SDK의 기본 구성(타임아웃, 연결 제한 등)이 유지되도록 원시 httpx.Client 및 httpx.AsyncClient 대신 DefaultHttpxClient 및 DefaultAsyncHttpxClient를 사용하세요.
기본적으로 라이브러리는 클라이언트가 가비지 컬렉션될 때마다 기본 HTTP 연결을 닫습니다. 원하는 경우 .close() 메서드를 사용하여 클라이언트를 수동으로 닫거나, 종료 시 닫히는 컨텍스트 매니저를 사용할 수 있습니다.
with Anthropic() as client:
message = client.messages.create(...)
# HTTP 클라이언트가 자동으로 닫힙니다베타 기능은 조기 피드백을 받고 새로운 기능을 테스트하기 위해 정식 출시 전에 제공됩니다. Claude의 모든 기능과 도구의 가용성은 Claude로 빌드하기 개요에서 확인할 수 있습니다.
클라이언트의 beta 속성을 통해 대부분의 베타 API 기능에 접근할 수 있습니다. 특정 베타 기능을 활성화하려면 메시지를 생성할 때 betas 필드에 적절한 베타 헤더를 추가해야 합니다.
예를 들어, Files API를 사용하려면:
client = Anthropic()
response = client.beta.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Please summarize this document for me."},
{
"type": "document",
"source": {
"type": "file",
"file_id": "file_abc123",
},
},
],
},
],
betas=["files-api-2025-04-14"],
)코드 예제가 포함된 자세한 플랫폼 설정 가이드는 다음을 참조하세요:
다섯 가지 클라이언트 클래스 모두 기본 anthropic 패키지에 포함되어 있습니다:
| 제공업체 | 클라이언트 | 추가 종속성 |
|---|---|---|
| Bedrock | from anthropic import AnthropicBedrockMantle | pip install "anthropic[bedrock]" |
Bedrock (bedrock-runtime 경로) | from anthropic import AnthropicBedrock | pip install "anthropic[bedrock]" |
| Vertex AI | from anthropic import AnthropicVertex | pip install "anthropic[vertex]" |
| Foundry | from anthropic import AnthropicFoundry | 없음 |
| AWS 기반 Claude Platform | from anthropic import AnthropicAWS |
AnthropicAWS 클라이언트는 베타 상태입니다. 생성자에 workspace_id를 전달하거나 ANTHROPIC_AWS_WORKSPACE_ID 환경 변수를 설정하세요.
새 프로젝트에는 AnthropicBedrockMantle을 사용하세요. AnthropicBedrock은 Bedrock InvokeModel API를 사용하는 기존 애플리케이션을 위해 유지됩니다.
이 패키지는 일반적으로 SemVer 규칙을 따르지만, 특정 하위 호환성이 없는 변경 사항이 마이너 버전으로 릴리스될 수 있습니다:
최신 버전으로 업그레이드했지만 기대했던 새 기능이 보이지 않는 경우, Python 환경이 여전히 이전 버전을 사용하고 있을 가능성이 높습니다. 런타임에 사용 중인 버전을 다음과 같이 확인할 수 있습니다:
print(anthropic.__version__)| N/A |
APIConnectionError |
pip install "anthropic[aws]" |