CLI, SDK 및 라이브러리클라이언트 SDK

Python SDK

동기 및 비동기 클라이언트를 지원하는 Anthropic Python SDK 설치 및 구성

Anthropic Python SDK는 Python 애플리케이션에서 Anthropic REST API에 편리하게 접근할 수 있도록 해줍니다. 동기 및 비동기 작업, 스트리밍, 그리고 Amazon Bedrock, Claude Platform on AWS, Google Cloud, Microsoft Foundry와의 통합을 지원합니다.

코드 예제가 포함된 API 기능 문서는 API 레퍼런스를 참조하세요. 이 페이지는 Python 전용 SDK 기능과 구성을 다룹니다.

설치

pip install anthropic

플랫폼별 통합 또는 향상된 비동기 성능을 위해 extras와 함께 설치하세요:

# Amazon Bedrock 지원용
pip install "anthropic[bedrock]"

# Google Cloud 지원용
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-5",
)

for block in message.content:
    if block.type == "text":
        print(block.text)

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-5",
    )
    print(message.content)


asyncio.run(main())

더 나은 동시성을 위한 aiohttp 사용

향상된 비동기 성능을 위해 기본값인 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-5",
        )
        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-5",
    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-5",
    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-5",
    ) 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-5", messages=[{"role": "user", "content": "Hello, world"}]
)
print(count.input_tokens)  # 10

도구 사용

이 SDK는 함수 호출(function calling)이라고도 하는 도구 사용을 지원합니다. 자세한 내용은 Claude와 함께하는 도구 사용을 참조하세요.

도구 헬퍼

SDK는 순수 Python 함수로 도구를 정의하고 실행하기 위한 헬퍼를 제공합니다. @beta_tool 데코레이터는 함수 시그니처와 독스트링으로부터 도구 스키마를 생성합니다:

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-5",
    tools=[get_weather],
    messages=[
        {"role": "user", "content": "What is the weather in SF?"},
    ],
)
for message in runner:
    print(message)

매 반복마다 API 요청이 이루어집니다. 응답에 주어진 도구 중 하나에 대한 호출이 포함되어 있으면, 해당 도구가 자동으로 호출되고 그 결과가 다음 반복에서 모델에 직접 반환됩니다.

메시지 배치

이 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-5",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Hello, world"}],
            },
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-5",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Hi again, friend"}],
            },
        },
    ]
)

배치에서 결과 가져오기

.processing_status == 'ended'로 표시되는 Message Batch 처리가 완료되면, .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-5",
    )
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`
N/A	`APIConnectionError`

요청 ID

요청 디버깅에 대한 자세한 내용은 요청 ID를 참조하세요.

SDK의 모든 객체 응답은 request-id 응답 헤더에서 추가된 _request_id 속성을 제공하므로, 실패한 요청을 빠르게 로깅하고 Anthropic에 보고할 수 있습니다.

message = client.messages.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-5",
)
print(message._request_id)  # e.g., req_018EeWyXxfu5pfWkrYcMdjWG

_ 접두사를 사용하는 다른 속성과 달리 _request_id 속성은 공개(public)입니다. 별도로 문서화되지 않은 한, 다른 모든 _ 접두사 속성, 메서드, 모듈은 비공개(private)입니다.

재시도

특정 오류는 기본적으로 짧은 지수 백오프와 함께 2회 자동으로 재시도됩니다. 연결 오류(예: 네트워크 연결 문제로 인한), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal 오류는 모두 기본적으로 재시도됩니다.

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-5",
)

타임아웃

기본적으로 요청은 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-5",
)

타임아웃 시 SDK는 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는 anthropic-version 헤더를 2023-06-01로 설정하여 자동으로 전송합니다.

필요한 경우 클라이언트 객체 또는 요청별로 기본 헤더를 설정하여 재정의할 수 있습니다.

기본 헤더를 재정의하면 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-5",
    extra_headers={"anthropic-version": "My-Custom-Value"},
)

타입 시스템

요청 매개변수

중첩된 요청 매개변수는 TypedDicts입니다. 응답은 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과 누락된 필드 처리

응답에서 명시적으로 null인 필드와 반환되지 않은(누락된) 필드를 구분할 수 있습니다:

response = client.messages.create(
    model="claude-opus-5",
    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-5",
)

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-5",
) 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 모델의 모든 추가 필드를 딕셔너리로 가져올 수 있습니다.

HTTP 클라이언트 구성

프록시 및 전송(transport) 지원을 포함하여 사용 사례에 맞게 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 리소스 관리

기본적으로 라이브러리는 클라이언트가 가비지 컬렉션될 때마다 기본 HTTP 연결을 닫습니다. 원하는 경우 .close() 메서드를 사용하여 클라이언트를 수동으로 닫거나, 종료 시 닫히는 컨텍스트 매니저를 사용할 수 있습니다.

with Anthropic() as client:
    message = client.messages.create(...)

# HTTP 클라이언트가 자동으로 닫힙니다

베타 기능

베타 기능은 정식 출시 전에 조기 피드백을 받고 새로운 기능을 테스트하기 위해 제공됩니다. Claude의 모든 기능과 도구의 가용성은 Claude로 구축하기 개요에서 확인할 수 있습니다.

대부분의 베타 API 기능은 클라이언트의 beta 속성을 통해 접근할 수 있습니다. 특정 베타 기능을 활성화하려면 메시지를 생성할 때 betas 필드에 적절한 베타 헤더를 추가해야 합니다.

예를 들어, Files API를 사용하려면:

client = Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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 패키지에 포함되어 있습니다:

제공자	클라이언트	추가 의존성
Agent Platform	`from anthropic import AnthropicVertex`	`pip install "anthropic[vertex]"`
Bedrock	`from anthropic import AnthropicBedrockMantle`	`pip install "anthropic[bedrock]"`
Bedrock (`bedrock-runtime` 경로)	`from anthropic import AnthropicBedrock`	`pip install "anthropic[bedrock]"`
Claude Platform on AWS	`from anthropic import AnthropicAWS`	`pip install "anthropic[aws]"`
Foundry	`from anthropic import AnthropicFoundry`	없음

AnthropicAWS 클라이언트는 베타 상태입니다. 생성자에 workspace_id를 전달하거나 ANTHROPIC_AWS_WORKSPACE_ID 환경 변수를 설정하세요.

새 프로젝트에는 AnthropicBedrockMantle을 사용하세요. AnthropicBedrock은 Bedrock InvokeModel API를 사용하는 기존 애플리케이션을 위해 유지됩니다.

시맨틱 버저닝

이 패키지는 일반적으로 SemVer 규칙을 따르지만, 특정 하위 호환성이 없는 변경 사항이 마이너 버전으로 릴리스될 수 있습니다:

런타임 동작을 깨뜨리지 않고 정적 타입에만 영향을 미치는 변경 사항.
기술적으로는 공개되어 있지만 외부 사용을 의도하거나 문서화하지 않은 라이브러리 내부에 대한 변경 사항.
실제로 대다수의 사용자에게 영향을 미치지 않을 것으로 예상되는 변경 사항.

설치된 버전 확인

최신 버전으로 업그레이드했지만 기대했던 새 기능이 보이지 않는다면, Python 환경이 여전히 이전 버전을 사용하고 있을 가능성이 높습니다. 런타임에 사용 중인 버전은 다음과 같이 확인할 수 있습니다:

print(anthropic.__version__)

추가 리소스

Was this page helpful?

CLI, SDK 및 라이브러리클라이언트 SDK

Python SDK

동기 및 비동기 클라이언트를 지원하는 Anthropic Python SDK 설치 및 구성

코드 예제가 포함된 API 기능 문서는 API 레퍼런스를 참조하세요. 이 페이지는 Python 전용 SDK 기능과 구성을 다룹니다.

설치

pip install anthropic

플랫폼별 통합 또는 향상된 비동기 성능을 위해 extras와 함께 설치하세요:

# Amazon Bedrock 지원용
pip install "anthropic[bedrock]"

# Google Cloud 지원용
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-5",
)

for block in message.content:
    if block.type == "text":
        print(block.text)

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-5",
    )
    print(message.content)


asyncio.run(main())

더 나은 동시성을 위한 aiohttp 사용

향상된 비동기 성능을 위해 기본값인 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-5",
        )
        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-5",
    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-5",
    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-5",
    ) 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 전용 이벤트를 포함한 다양한 헬퍼를 제공합니다.

토큰 계산

usage 응답 속성을 통해 특정 요청의 정확한 사용량을 확인할 수 있습니다:

message = client.messages.create(...)
print(message.usage)
# Usage(input_tokens=25, output_tokens=13)

요청을 보내기 전에 토큰을 계산할 수도 있습니다:

count = client.messages.count_tokens(
    model="claude-opus-5", messages=[{"role": "user", "content": "Hello, world"}]
)
print(count.input_tokens)  # 10

도구 사용

이 SDK는 함수 호출(function calling)이라고도 하는 도구 사용을 지원합니다. 자세한 내용은 Claude와 함께하는 도구 사용을 참조하세요.

도구 헬퍼

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-5",
    tools=[get_weather],
    messages=[
        {"role": "user", "content": "What is the weather in SF?"},
    ],
)
for message in runner:
    print(message)

메시지 배치

이 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-5",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Hello, world"}],
            },
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-5",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Hi again, friend"}],
            },
        },
    ]
)

배치에서 결과 가져오기

.processing_status == 'ended'로 표시되는 Message Batch 처리가 완료되면, .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-5",
    )
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`
N/A	`APIConnectionError`

요청 ID

요청 디버깅에 대한 자세한 내용은 요청 ID를 참조하세요.

SDK의 모든 객체 응답은 request-id 응답 헤더에서 추가된 _request_id 속성을 제공하므로, 실패한 요청을 빠르게 로깅하고 Anthropic에 보고할 수 있습니다.

message = client.messages.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-5",
)
print(message._request_id)  # e.g., req_018EeWyXxfu5pfWkrYcMdjWG

재시도

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-5",
)

타임아웃

기본적으로 요청은 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-5",
)

타임아웃 시 SDK는 APITimeoutError를 발생시킵니다.

타임아웃된 요청은 기본적으로 두 번 재시도됩니다.

긴 요청

오래 실행되는 요청에는 스트리밍 Messages API 사용을 고려하세요.

비스트리밍 요청에서 예상 요청 latency(지연 시간)가 타임아웃보다 길면 클라이언트가 응답을 받지 못한 채 연결을 종료하고 재시도하게 됩니다.

자동 페이지네이션

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는 anthropic-version 헤더를 2023-06-01로 설정하여 자동으로 전송합니다.

필요한 경우 클라이언트 객체 또는 요청별로 기본 헤더를 설정하여 재정의할 수 있습니다.

기본 헤더를 재정의하면 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-5",
    extra_headers={"anthropic-version": "My-Custom-Value"},
)

타입 시스템

요청 매개변수

중첩된 요청 매개변수는 TypedDicts입니다. 응답은 Pydantic 모델이며, JSON으로 다시 직렬화하는 등의 작업을 위한 헬퍼 메서드도 제공합니다(v1, v2).

응답 모델

Pydantic 모델을 딕셔너리로 변환하려면 헬퍼 메서드를 사용하세요:

message = client.messages.create(...)

# JSON 문자열로 변환
json_str = message.to_json()

# 딕셔너리로 변환
data = message.to_dict()

null과 누락된 필드 처리

응답에서 명시적으로 null인 필드와 반환되지 않은(누락된) 필드를 구분할 수 있습니다:

response = client.messages.create(
    model="claude-opus-5",
    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")

고급 사용법

원시 응답 데이터 접근(예: 헤더)

client = Anthropic()

response = client.messages.with_raw_response.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-5",
)

print(response.headers.get("request-id"))
message = (
    response.parse()
)  # get the object that `messages.create()` would have returned
print(message.content)

이러한 메서드는 APIResponse 객체를 반환합니다.

응답 본문 스트리밍

with client.messages.with_streaming_response.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-5",
) 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

사용자 정의/문서화되지 않은 요청 보내기

문서화되지 않은 엔드포인트

import httpx

response = client.post(
    "/foo",
    cast_to=httpx.Response,
    body={"my_param": True},
)

print(response.json())

문서화되지 않은 요청 매개변수

추가 매개변수를 명시적으로 보내려면 extra_query, extra_body, extra_headers 요청 옵션을 사용할 수 있습니다.

문서화되지 않은 응답 속성

HTTP 클라이언트 구성

프록시 및 전송(transport) 지원을 포함하여 사용 사례에 맞게 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 리소스 관리

with Anthropic() as client:
    message = client.messages.create(...)

# HTTP 클라이언트가 자동으로 닫힙니다

베타 기능

예를 들어, Files API를 사용하려면:

client = Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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 패키지에 포함되어 있습니다:

제공자	클라이언트	추가 의존성
Agent Platform	`from anthropic import AnthropicVertex`	`pip install "anthropic[vertex]"`
Bedrock	`from anthropic import AnthropicBedrockMantle`	`pip install "anthropic[bedrock]"`
Bedrock (`bedrock-runtime` 경로)	`from anthropic import AnthropicBedrock`	`pip install "anthropic[bedrock]"`
Claude Platform on AWS	`from anthropic import AnthropicAWS`	`pip install "anthropic[aws]"`
Foundry	`from anthropic import AnthropicFoundry`	없음

AnthropicAWS 클라이언트는 베타 상태입니다. 생성자에 workspace_id를 전달하거나 ANTHROPIC_AWS_WORKSPACE_ID 환경 변수를 설정하세요.

새 프로젝트에는 AnthropicBedrockMantle을 사용하세요. AnthropicBedrock은 Bedrock InvokeModel API를 사용하는 기존 애플리케이션을 위해 유지됩니다.

시맨틱 버저닝

이 패키지는 일반적으로 SemVer 규칙을 따르지만, 특정 하위 호환성이 없는 변경 사항이 마이너 버전으로 릴리스될 수 있습니다:

런타임 동작을 깨뜨리지 않고 정적 타입에만 영향을 미치는 변경 사항.
기술적으로는 공개되어 있지만 외부 사용을 의도하거나 문서화하지 않은 라이브러리 내부에 대한 변경 사항.
실제로 대다수의 사용자에게 영향을 미치지 않을 것으로 예상되는 변경 사항.

설치된 버전 확인

print(anthropic.__version__)

추가 리소스

Was this page helpful?

설치

요구 사항

사용법

비동기 사용법

더 나은 동시성을 위한 aiohttp 사용

스트리밍 응답

스트리밍 헬퍼

토큰 계산

도구 사용

도구 헬퍼

메시지 배치

배치 생성

배치에서 결과 가져오기

파일 업로드

오류 처리

요청 ID

재시도

타임아웃

긴 요청

자동 페이지네이션

기본 헤더

타입 시스템

요청 매개변수

응답 모델

null과 누락된 필드 처리

고급 사용법

원시 응답 데이터 접근(예: 헤더)

응답 본문 스트리밍

로깅

사용자 정의/문서화되지 않은 요청 보내기

문서화되지 않은 엔드포인트

문서화되지 않은 요청 매개변수

문서화되지 않은 응답 속성

HTTP 클라이언트 구성

HTTP 리소스 관리

베타 기능

플랫폼 통합

시맨틱 버저닝

설치된 버전 확인

추가 리소스

설치

요구 사항

사용법

비동기 사용법

더 나은 동시성을 위한 aiohttp 사용

스트리밍 응답

스트리밍 헬퍼

토큰 계산

도구 사용

도구 헬퍼

메시지 배치

배치 생성

배치에서 결과 가져오기

파일 업로드

오류 처리

요청 ID

재시도

타임아웃

긴 요청

자동 페이지네이션

기본 헤더

타입 시스템

요청 매개변수

응답 모델

null과 누락된 필드 처리

고급 사용법

원시 응답 데이터 접근(예: 헤더)

응답 본문 스트리밍

로깅

사용자 정의/문서화되지 않은 요청 보내기

문서화되지 않은 엔드포인트

문서화되지 않은 요청 매개변수

문서화되지 않은 응답 속성

HTTP 클라이언트 구성

HTTP 리소스 관리

베타 기능

플랫폼 통합

시맨틱 버저닝

설치된 버전 확인

추가 리소스

설치

요구 사항

사용법

비동기 사용법

더 나은 동시성을 위한 aiohttp 사용

스트리밍 응답

스트리밍 헬퍼

토큰 계산

도구 사용

도구 헬퍼

메시지 배치

배치 생성

배치에서 결과 가져오기

파일 업로드

오류 처리

요청 ID

재시도

타임아웃

긴 요청

자동 페이지네이션

기본 헤더

타입 시스템

요청 매개변수

응답 모델

null과 누락된 필드 처리

고급 사용법

원시 응답 데이터 접근(예: 헤더)

응답 본문 스트리밍

로깅

사용자 정의/문서화되지 않은 요청 보내기

문서화되지 않은 엔드포인트

문서화되지 않은 요청 매개변수

문서화되지 않은 응답 속성

HTTP 클라이언트 구성

HTTP 리소스 관리

베타 기능

플랫폼 통합

시맨틱 버저닝

설치된 버전 확인

추가 리소스

설치

요구 사항

사용법

비동기 사용법

더 나은 동시성을 위한 aiohttp 사용

스트리밍 응답

스트리밍 헬퍼

토큰 계산

도구 사용

도구 헬퍼

메시지 배치

배치 생성

배치에서 결과 가져오기

파일 업로드

오류 처리

요청 ID

재시도

타임아웃

긴 요청

자동 페이지네이션

기본 헤더

타입 시스템

요청 매개변수

응답 모델

null과 누락된 필드 처리

고급 사용법

원시 응답 데이터 접근(예: 헤더)

응답 본문 스트리밍

로깅

사용자 정의/문서화되지 않은 요청 보내기

문서화되지 않은 엔드포인트

문서화되지 않은 요청 매개변수

문서화되지 않은 응답 속성

HTTP 클라이언트 구성

HTTP 리소스 관리

베타 기능

플랫폼 통합

시맨틱 버저닝

설치된 버전 확인

추가 리소스