Claude Platform Docs
SDK、CLI、ライブラリクライアントSDK

Python SDK

同期および非同期クライアントをサポートするAnthropic Python SDKのインストールと設定

Anthropic Python SDKは、PythonアプリケーションからClaude APIへの便利なアクセスを提供します。同期および非同期の操作、ストリーミング、そしてAmazon Bedrock、Claude Platform on AWS、Claude Models on Google Cloud (Anthropic managed)、Claude Models on Google Cloud (Google managed)、Microsoft Foundryとの統合をサポートしています。

インストール

pip install anthropic

プラットフォーム固有の統合や非同期パフォーマンスの向上のためには、extrasを指定してインストールします：

# Amazon Bedrock のサポート用
pip install "anthropic[bedrock]"

# Google Cloud のサポート用
pip install "anthropic[vertex]"

# Claude Platform on AWS のサポート用
pip install "anthropic[aws]"

# Microsoft Foundry のサポートは基本パッケージに含まれています

# aiohttp による非同期パフォーマンス向上用
pip install "anthropic[aiohttp]"

Claude Models on Google Cloud (Anthropic managed)を使用するには、pip install "anthropic[google_cloud]"を実行してください。

要件

Python 3.10以降が必要です。SDKの0.xリリースからアップグレードする場合は、破壊的変更の一覧についてv1移行ガイドを参照してください。

使用方法

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

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

Workload Identity Federationを含む認証オプションについては、認証を参照してください。APIキーがワークスペースにスコープされていない個人キーまたはサービスアカウントキーである場合は、anthropic-workspace-idリクエストヘッダーにワークスペースIDを設定してください。このSDKでのリクエストごとのオプションについては、ワークスペースを選択するで説明しています。

非同期での使用

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


asyncio.run(main())

並行性を高めるためのaiohttpの使用

非同期パフォーマンスを向上させるために、デフォルトのhttpx2の代わりに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-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-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-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-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-5",
    messages=[{"role": "user", "content": "Hello, world"}],
)
print(count.input_tokens)  # 10

ツール使用

このSDKは、「function calling」（関数呼び出し）とも呼ばれる「tool use」（ツール使用）をサポートしています。詳細については、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-5-5",
    tools=[get_weather],
    messages=[
        {"role": "user", "content": "What is the weather in SF?"},
    ],
)
for message in runner:
    print(message)

各イテレーションでAPIリクエストが行われます。レスポンスに指定されたツールのいずれかへの呼び出しが含まれている場合、そのツールが自動的に呼び出され、結果は次のイテレーションでモデルに直接返されます。

このSDKでブラウザ使用ツールまたはコンピューター使用ツールを実行するには、SDKツールセットを使用したブラウザおよびコンピューター使用を参照してください。

メッセージバッチ

このSDKは、client.messages.batchesの下でバッチ処理をサポートしています。

バッチの作成

Message Batchesはリクエストの配列を受け取ります。各オブジェクトにはcustom_id識別子と、標準のMessages APIと同じリクエストparamsが含まれます：

client.messages.batches.create(
    requests=[
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-5-5",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Hello, world"}],
            },
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-5-5",
                "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.files.upload(
    file=Path("/path/to/file"),
)

# バイト列を使用してアップロードします
client.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-5",
    )
except anthropic.APIConnectionError as e:
    print("The server could not be reached")
    print(e.__cause__)  # an underlying Exception, likely raised within httpx2
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)

エラーコードは次のとおりです：

ステータスコードエラータイプ
400BadRequestError
401AuthenticationError
403PermissionDeniedError
404NotFoundError
409ConflictError
422UnprocessableEntityError
429RateLimitError
>=500InternalServerError
N/AAPIConnectionError

リクエスト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-5",
)
print(message._request_id)  # e.g., req_018EeWyXxfu5pfWkrYcMdjWG

リトライ

特定のエラーは、デフォルトで短い指数バックオフを伴って自動的に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-5",
)

タイムアウト

デフォルトでは、リクエストは10分後にタイムアウトします。これはtimeoutオプションで設定でき、floatまたはhttpx2.Timeoutオブジェクトを受け付けます：

import httpx2
from anthropic import Anthropic

# すべてのリクエストのデフォルトを設定します:
client = Anthropic(
    timeout=20.0,  # 20 seconds (default is 10 minutes)
)

# より細かく制御します:
client = Anthropic(
    timeout=httpx2.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-5",
)

タイムアウト時、SDKはAPITimeoutErrorをスローします。

タイムアウトしたリクエストはデフォルトで2回リトライされることに注意してください。

長時間のリクエスト

ストリーミングを使用せずに大きなmax_tokens値を設定することは避けてください。一部のネットワークでは、一定時間後にアイドル状態の接続が切断される場合があり、その結果、Anthropicからレスポンスを受信せずにリクエストが失敗したりタイムアウトしたりする可能性があります。

非ストリーミングリクエストが約10分以上かかると予想される場合、SDKはValueErrorをスローします。stream=Trueを渡すか、クライアントまたはリクエストレベルでtimeoutオプションを上書きすると、このエラーは無効になります。

非ストリーミングリクエストの予想されるリクエストレイテンシがタイムアウトより長い場合、クライアントはレスポンスを受信せずに接続を終了し、リトライします。

SDKは、一部のネットワークにおけるアイドル接続タイムアウトの影響を軽減するために、TCPソケットキープアライブオプションを設定します。これは、カスタムの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は、SDKのこのメジャーバージョンに対応するAPIバージョン（セマンティックバージョニングを参照）に設定されたanthropic-versionヘッダーを自動的に送信します。

必要に応じて、クライアントオブジェクトまたはリクエストごとにデフォルトヘッダーを設定することで、これを上書きできます。

# クライアントのすべてのリクエストに対するデフォルトヘッダーを設定します
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-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-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")

高度な使用方法

生のレスポンスデータへのアクセス（例：ヘッダー）

httpx2によって返される「生の」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-5",
)

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

これらのメソッドはAPIResponseオブジェクトを返します。非同期クライアントではAsyncAPIResponseを返し、.parse()、.read()、.text()、.json()はawaitする必要があります。

レスポンスボディのストリーミング

.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-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

OpenTelemetryトレーシング

アプリケーションがOpenTelemetryトレーサープロバイダーを登録すると、SDKは送信する各リクエストについてスパンを出力します。スパンをオブザーバビリティプラットフォームに送信するには、Claude SDKでOpenTelemetryを設定するを参照してください。

カスタム/ドキュメント化されていないリクエストの作成

このライブラリは、ドキュメント化されたAPIへの便利なアクセスのために型付けされています。ドキュメント化されていないエンドポイント、パラメータ、またはレスポンスプロパティにアクセスする必要がある場合でも、ライブラリを使用できます。

ドキュメント化されていないエンドポイント

ドキュメント化されていないエンドポイントにリクエストを行うには、client.get、client.post、およびその他のHTTP動詞を使用できます。これらのリクエストを行う際には、リトライなどのクライアントのオプションが適用されます。

import httpx2

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

print(response.json())

ドキュメント化されていないリクエストパラメータ

追加のパラメータを明示的に送信したい場合は、extra_query、extra_body、extra_headersリクエストオプションを使用できます。

ドキュメント化されていないレスポンスプロパティ

ドキュメント化されていないレスポンスプロパティにアクセスするには、response.unknown_propのように追加フィールドにアクセスできます。また、response.model_extraを使用して、Pydanticモデル上のすべての追加フィールドを辞書として取得することもできます。

HTTPクライアントの設定

SDKは、httpxのAPI互換フォークであるhttpx2を使用してリクエストを送信します。プロキシやトランスポートを含めてHTTPクライアントをカスタマイズするには、独自のhttpx2クライアントをhttp_clientとして渡します：

import httpx2
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=httpx2.HTTPTransport(local_address="0.0.0.0"),
    ),
)

with_options()を使用して、リクエストごとにクライアントをカスタマイズすることもできます：

client.with_options(http_client=DefaultHttpxClient(...))

OpenTelemetryのHTTPXClientInstrumentor、Sentryのhttpx統合、respx、pytest-httpxなど、httpx自体にパッチを適用するトレーシングツールやモックツールは、デフォルトではSDKのリクエストを認識しません。これらを使用するには、何かがhttpxをインポートする前に、起動時に一度httpx2.alias_httpx()を呼び出してください。これにより、プロセス全体でimport httpxがhttpx2に解決されるようになります。

HTTPリソースの管理

デフォルトでは、ライブラリはクライアントがガベージコレクションされるたびに、基盤となるHTTP接続をクローズします。必要に応じて、.close()メソッドを使用するか、終了時にクローズするコンテキストマネージャーを使用して、クライアントを手動でクローズできます。

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

# HTTPクライアントは自動的にクローズされます

ベータ機能

ベータ機能は、早期のフィードバックを得て新しい機能をテストするために、正式リリース前に利用可能になります。Claudeのすべての機能とツールの利用可能状況は、機能の概要で確認できます。

ほとんどのベータAPI機能には、クライアントのbetaプロパティを通じてアクセスできます。特定のベータ機能を有効にするには、メッセージを作成する際に適切なベータヘッダーをbetasフィールドに追加する必要があります。

たとえば、コンテキスト編集を有効にするには：

client = Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    betas=["context-management-2025-06-27"],
)

プラットフォーム統合

6つのクライアントクラスはすべて、ベースのanthropicパッケージに含まれています：

プロバイダークライアント追加の依存関係
Agent Platformfrom anthropic import AnthropicVertexpip install "anthropic[vertex]"
Bedrockfrom anthropic import AnthropicBedrockMantlepip install "anthropic[bedrock]"
Bedrock（bedrock-runtimeパス）from anthropic import AnthropicBedrockpip install "anthropic[bedrock]"
Claude Platform on AWSfrom anthropic import AnthropicAWSpip install "anthropic[aws]"
Claude Models on Google Cloud (Anthropic managed)from anthropic import AnthropicGoogleCloudpip install "anthropic[google_cloud]"
Foundryfrom anthropic import AnthropicFoundryなし

AnthropicAWSクライアントはベータ版です。コンストラクターにworkspace_idを渡すか、ANTHROPIC_AWS_WORKSPACE_ID環境変数を設定してください。AnthropicGoogleCloudクライアントもベータ版です。コンストラクターにworkspace_idを渡すか、ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID環境変数を設定してください。クライアントがワークスペースIDを解決する方法については、プロジェクト、ロケーション、およびワークスペースの解決を参照してください。

新しいプロジェクトにはAnthropicBedrockMantleを使用してください。AnthropicBedrockは、BedrockのInvokeModel APIを使用する既存のアプリケーション向けに引き続き提供されます。

セマンティックバージョニング

このSDKの各メジャーバージョンは、デフォルトでanthropic-versionヘッダーに1つのAPIバージョンを送信し、新しいAPIバージョンごとに新しいメジャーバージョンがリリースされます。2026-10-21を送信する最初のメジャーバージョンは2.0.0です。APIバージョン2026-10-21への移行を参照してください。

このパッケージは一般的にSemVerの規約に従いますが、特定の後方互換性のない変更がマイナーバージョンとしてリリースされる場合があります：

  1. ランタイムの動作を壊さず、静的型のみに影響する変更。
  2. 技術的にはパブリックであるものの、外部での使用を意図していない、またはドキュメント化されていないライブラリ内部の変更。
  3. 実際には大多数のユーザーに影響を与えないと予想される変更。

インストールされているバージョンの確認

最新バージョンにアップグレードしたにもかかわらず、期待していた新機能が表示されない場合は、Python環境がまだ古いバージョンを使用している可能性があります。実行時に使用されているバージョンは、次の方法で確認できます：

print(anthropic.__version__)

その他のリソース

Was this page helpful?