Bedrock Python入門｜Converse APIでClaudeを呼ぶ

Python から Amazon Bedrock のモデルを呼ぶには、boto3 の bedrock-runtime クライアントで converse() を使います。 Converse API は、モデルが違っても同じ形のリクエストで呼べる API です。モデルを変えるときは、modelId を書き換えるだけで済みます。

import boto3

client = boto3.client("bedrock-runtime", region_name="ap-northeast-1")
response = client.converse(
    modelId="jp.anthropic.claude-haiku-5-5",
    messages=[{"role": "user", "content": [{"text": "Amazon Bedrockを一言で説明して"}]}],
)
print(response["output"]["message"]["content"][0]["text"])

つまずきやすいのは「モデルID」と「権限」です。 新しい Claude は、anthropic. から始まる素のモデルIDではなく、jp. や global. から始まる推論プロファイルIDで呼びます。

確認環境：boto3 / botocore 1.43.111・Python 3.11（Linux）。AWS には接続していません。boto3 が送るリクエストの形は、botocore の Stubber（ParamValidationError の再現）と、手元に立てた擬似エンドポイント（Bedrock の応答の形を返す小さな HTTP サーバー）で確かめました。モデルIDや権限、エラーの意味は AWS の公式ドキュメントで確かめました（確認日 2026年10月12日）。

最初に用意するもの

権限の対応は、AWS のドキュメント「Inference using Converse API」に書かれています。converse を呼ぶのに bedrock:Converse という権限は無く、bedrock:InvokeModel で許可します。

モデルの有効化について、ドキュメントでは「サードパーティのモデルを初めて呼ぶと、Bedrock が裏で自動的にサブスクリプションを始める」とされています。このとき、IAM に aws-marketplace:Subscribe などの権限が要ります。足りないと AccessDeniedException になります。IAM ポリシーの書き方は、関連記事「IAMポリシーの書き方｜JSONの読み方と最小権限の作り方【例文つき】」で扱っています。

モデルIDと推論プロファイルID

推論プロファイルは、リクエストを複数のリージョンに振り分けて処理する仕組みです。モデルIDの前に jp. us. global. などが付きます。AWS のモデルカードで確かめた ID です。

• モデルカードには、Claude Haiku 4.5 について「素のモデルID（anthropic.…）は、bedrock-runtime のオンデマンド利用では使えない」と書かれています。Haiku 5.5・Sonnet 5.5 も、モデルカードの In-Region（そのリージョンだけで処理）の欄は、すべて「not supported」でした。
• jp. などの Geo プロファイルはその地域の中で、global. は世界のリージョンで処理されます。ドキュメントでは、どちらも「元のリージョンの外に送られることがあり、1リージョンでのデータ保管にはならない」と注意しています。
• modelId には、推論プロファイルの ID か ARN を渡します。システム定義の（AWS が用意した）推論プロファイルは、どちらでも呼べます。

推論プロファイルを使うときの IAM ポリシーは、プロファイルと、振り分け先の各リージョンのモデルの両方を Resource に入れる決まりです。ドキュメントの例から、呼び出しの権限だけを抜き出すと次の形です。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["bedrock:InvokeModel*"],
      "Resource": [
        "arn:aws:bedrock:*:*:inference-profile/*",
        "arn:aws:bedrock:*::foundation-model/*"
      ]
    }
  ]
}

ARN の読み方は、関連記事「AWS ARNとは？形式の読み方とサービス別の書き方一覧」で扱っています。

最小コード

返答は response["output"]["message"]["content"] のリストに入っています。 先頭が文字とは限らないので、text を持つ要素だけをつなげると安全です。

import boto3

MODEL_ID = "jp.anthropic.claude-haiku-5-5"
client = boto3.client("bedrock-runtime", region_name="ap-northeast-1")

response = client.converse(
    modelId=MODEL_ID,
    messages=[{"role": "user", "content": [{"text": "こんにちは"}]}],
)

message = response["output"]["message"]
text = "".join(block["text"] for block in message["content"] if "text" in block)
print(text)
print(response["stopReason"])   # end_turn
print(response["usage"])        # {'inputTokens': ..., 'outputTokens': ..., 'totalTokens': ...}

手元の擬似エンドポイントで受けたとき、boto3 は次の URL と JSON を送っていました。modelId は URL の中に入ります。

POST /model/jp.anthropic.claude-haiku-5-5/converse
{"messages": [{"role": "user", "content": [{"text": "こんにちは"}]}]}

レスポンスの中身

stopReason の値は、API リファレンスでは次の9つです。

system と inferenceConfig

system は文字列ではなく、[{"text": "..."}] のリストで渡します。 messages の中に入れるのではなく、別の引数です。

response = client.converse(
    modelId=MODEL_ID,
    system=[{"text": "あなたは社内ヘルプデスクです。100文字以内で答えます。"}],
    messages=[{"role": "user", "content": [{"text": "VPNにつながりません"}]}],
    inferenceConfig={
        "maxTokens": 512,          # 出力の上限（トークン）
        "temperature": 0.2,        # 0〜1。小さいほど答えがぶれにくい
        "topP": 0.9,
        "stopSequences": ["###"],  # この文字が出たら止める
    },
)

キーは camelCase です。 Anthropic SDK の max_tokens の書き方のまま渡すと、送る前に止まりました。

ParamValidationError: Parameter validation failed:
Unknown parameter in inferenceConfig: "max_tokens", must be one of: maxTokens, temperature, topP, stopSequences

inferenceConfig に無い、モデル独自のパラメータは additionalModelRequestFields（dict）で渡します。Anthropic SDK で直接 Claude API を呼ぶ書き方は、関連記事「Claude API Python入門｜Anthropic SDKコピペレシピ集」で扱っています。

会話の履歴

Bedrock は会話を覚えていません。 前の返答（output.message）と次の質問を messages に足して、毎回全部送り直します。

import boto3

MODEL_ID = "jp.anthropic.claude-haiku-5-5"
client = boto3.client("bedrock-runtime", region_name="ap-northeast-1")
messages = []

def chat(prompt: str) -> str:
    messages.append({"role": "user", "content": [{"text": prompt}]})
    response = client.converse(
        modelId=MODEL_ID,
        system=[{"text": "簡潔に答えてください。"}],
        messages=messages,
        inferenceConfig={"maxTokens": 1024},
    )
    reply = response["output"]["message"]
    messages.append(reply)               # assistant の返答をそのまま足す
    return "".join(b["text"] for b in reply["content"] if "text" in b)

print(chat("私の名前は山田です。"))
print(chat("私の名前は？"))

2回目のリクエストでは、messages が「user → assistant → user」の3件で送られていました。履歴が長いほど inputTokens が増えるので、前半のやり取りを要約して短くする方法もあります。トークンの数え方は、関連記事「トークンとは｜生成AIの数え方・日本語の文字数目安と節約方法」で扱っています。

converse_stream：少しずつ受け取る

converse_stream() は、返り値の stream を for で回すと、イベント（dict）が順に届きます。 引数は converse() と同じです。converse(..., stream=True) という書き方はできず、送る前に Unknown parameter in input: "stream" で止まりました。

擬似エンドポイントからイベントストリームの形式で返すと、boto3 は次の順で dict を返しました。

{'messageStart': {'role': 'assistant'}}
{'contentBlockDelta': {'delta': {'text': 'Bedrockは'}, 'contentBlockIndex': 0}}
{'contentBlockDelta': {'delta': {'text': 'AWSの生成AIサービスです。'}, 'contentBlockIndex': 0}}
{'contentBlockStop': {'contentBlockIndex': 0}}
{'messageStop': {'stopReason': 'end_turn'}}
{'metadata': {'usage': {'inputTokens': 12, 'outputTokens': 9, 'totalTokens': 21}, 'metrics': {'latencyMs': 300}}}

ツール引数は、JSON の文字列が分かれて届きます。つなげてから json.loads します。文字もツールも扱える完成形です。

import json

def stream_converse(client, **kwargs):
    resp = client.converse_stream(**kwargs)
    text, tools, cur, stop, usage = [], [], None, None, None
    for ev in resp["stream"]:
        if "contentBlockStart" in ev and "toolUse" in ev["contentBlockStart"]["start"]:
            s = ev["contentBlockStart"]["start"]["toolUse"]
            cur = {"toolUseId": s["toolUseId"], "name": s["name"], "input": ""}
        elif "contentBlockDelta" in ev:
            d = ev["contentBlockDelta"]["delta"]
            if "text" in d:
                print(d["text"], end="", flush=True)
                text.append(d["text"])
            elif "toolUse" in d:
                cur["input"] += d["toolUse"]["input"]
        elif "contentBlockStop" in ev and cur:
            cur["input"] = json.loads(cur["input"] or "{}")
            tools.append(cur)
            cur = None
        elif "messageStop" in ev:
            stop = ev["messageStop"]["stopReason"]
        elif "metadata" in ev:
            usage = ev["metadata"]["usage"]
    print()
    return "".join(text), tools, stop, usage

text, tools, stop, usage = stream_converse(
    client, modelId=MODEL_ID,
    messages=[{"role": "user", "content": [{"text": "東京の天気は？"}]}],
)

ツール引数を {"city": と "東京"} の2つに分けて返したときも、[{'toolUseId': 'tooluse_s1', 'name': 'get_weather', 'input': {'city': '東京'}}] と tool_use が得られました。

ストリームの途中でも、エラーがイベントとして届くことがあります。botocore の定義では、throttlingException・validationException・modelStreamErrorException・internalServerException・serviceUnavailableException の5つです。

ツール利用（toolConfig）

モデルは関数を自分で実行しません。 「この関数をこの引数で呼びたい」と返すので、自分のコードで実行し、結果を toolResult として送り返します。流れは次の3段です。

1. toolConfig に関数の名前・説明・引数の JSON Schema を書いて converse
2. stopReason が tool_use なら、content の toolUse（toolUseId・name・input）を見て関数を実行
3. 返答（assistant）と、toolResult を入れた user のメッセージを履歴に足して、もう一度 converse

import boto3

MODEL_ID = "jp.anthropic.claude-haiku-5-5"
client = boto3.client("bedrock-runtime", region_name="ap-northeast-1")

def get_weather(city: str) -> dict:
    return {"city": city, "weather": "晴れ"}   # 本当は天気APIを呼ぶ

TOOLS = {"get_weather": get_weather}
tool_config = {
    "tools": [{
        "toolSpec": {
            "name": "get_weather",
            "description": "都市名を受け取り、今日の天気を返す",
            "inputSchema": {"json": {
                "type": "object",
                "properties": {"city": {"type": "string", "description": "都市名"}},
                "required": ["city"],
            }},
        }
    }],
    # "toolChoice": {"auto": {}}  # {"any": {}} や {"tool": {"name": "get_weather"}} も書ける
}

messages = [{"role": "user", "content": [{"text": "東京の天気は？"}]}]
while True:
    response = client.converse(modelId=MODEL_ID, messages=messages, toolConfig=tool_config)
    reply = response["output"]["message"]
    messages.append(reply)
    if response["stopReason"] != "tool_use":
        break
    results = []
    for block in reply["content"]:
        if "toolUse" not in block:
            continue
        tu = block["toolUse"]
        try:
            out = TOOLS[tu["name"]](**tu["input"])
            results.append({"toolResult": {"toolUseId": tu["toolUseId"], "content": [{"json": out}]}})
        except Exception as e:
            results.append({"toolResult": {"toolUseId": tu["toolUseId"],
                                           "content": [{"text": str(e)}], "status": "error"}})
    messages.append({"role": "user", "content": results})

print("".join(b["text"] for b in reply["content"] if "text" in b))

擬似エンドポイントで tool_use を返したとき、toolUse は次の dict で取り出せました。input は JSON 文字列ではなく、dict です（ストリームのときとの違い）。

{'toolUseId': 'tooluse_abc123', 'name': 'get_weather', 'input': {'city': '東京'}}

ツール利用の考え方は、関連記事「Function Calling（tool use）の仕組みとPython実装」で扱っています。

画像入力

画像は image ブロックで、ファイルのバイト列をそのまま渡します。 ドキュメントには「AWS SDK を使うなら base64 にしなくてよい」とあり、実際に boto3 が base64 に変えて送っていました。

from pathlib import Path

png = Path("screen.png").read_bytes()
response = client.converse(
    modelId=MODEL_ID,
    messages=[{"role": "user", "content": [
        {"image": {"format": "png", "source": {"bytes": png}}},
        {"text": "この画面のエラーの原因を推測して"},
    ]}],
)

{"messages": [{"role": "user", "content": [{"image": {"format": "png", "source": {"bytes": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"}}}, ...

format は jpg ではなく jpeg です。 "jpg" は boto3 では止まらずに送られるので、Bedrock 側で弾かれる形になります。Claude Haiku 5.5・Sonnet 5.5 のモデルカードでは、入力は Text と Image に対応しています。

よく出るエラー

boto3 が送る前に止まるもの（ParamValidationError）

Stubber で再現した、送る前に止まる書き方です。AWS に届かないので、課金も CloudWatch のログもありません。

一方、temperature: 1.5 や画像の format: "jpg" は、boto3 では止まりませんでした。値の範囲や種類は、Bedrock 側で調べられます。

Bedrock から返るもの（ClientError）

エラー名と HTTP ステータスは、Converse API のリファレンスとトラブルシューティングのページに基づきます。

モデルIDの指定ミスの見分け方です。

エラーの取り出し方と、再試行の回数

from botocore.exceptions import ClientError

try:
    response = client.converse(modelId=MODEL_ID, messages=messages)
except client.exceptions.ThrottlingException as e:
    print("混雑:", e.response["ResponseMetadata"].get("RetryAttempts"))
except ClientError as e:
    print(e.response["Error"]["Code"], e.response["Error"]["Message"])

擬似エンドポイントで 429（ThrottlingException）を返し続けたとき、boto3 の再試行は次のとおりでした。

boto3 1.43.111 の既定の read_timeout は 60秒でした。長い出力を converse で待つと、先に読み取りのタイムアウトになることがあります。Config(read_timeout=...) で延ばすか、converse_stream を使います。

from botocore.config import Config

client = boto3.client(
    "bedrock-runtime", region_name="ap-northeast-1",
    config=Config(read_timeout=300, retries={"max_attempts": 6, "mode": "adaptive"}),
)

ClientError の扱い全般は、関連記事「boto3のエラーハンドリング｜ClientErrorのコード取得とリトライ設定」で扱っています。再試行の待ち時間の決め方は、関連記事「指数バックオフとは？リトライ間隔の決め方とジッターの実装」で扱っています。

テストは Stubber で書ける

AWS につながない単体テストでは、botocore の Stubber で「送るはずのリクエスト」と「返すレスポンス」を決められます。expected_params と違う形で呼ぶと、テストが失敗します。

import boto3
from botocore.stub import Stubber

client = boto3.client("bedrock-runtime", region_name="ap-northeast-1")
stubber = Stubber(client)
stubber.add_response(
    "converse",
    {"output": {"message": {"role": "assistant", "content": [{"text": "回答です。"}]}},
     "stopReason": "end_turn",
     "usage": {"inputTokens": 25, "outputTokens": 5, "totalTokens": 30},
     "metrics": {"latencyMs": 420}},
    expected_params={"modelId": "jp.anthropic.claude-haiku-5-5",
                     "messages": [{"role": "user", "content": [{"text": "質問"}]}]},
)
stubber.add_client_error("converse", service_error_code="ThrottlingException", http_status_code=429)

with stubber:
    r = client.converse(modelId="jp.anthropic.claude-haiku-5-5",
                        messages=[{"role": "user", "content": [{"text": "質問"}]}])
    assert r["output"]["message"]["content"][0]["text"] == "回答です。"

手元では、1回目が 回答です。、2回目が client.exceptions.ThrottlingException で受け取れました。

よくある質問

Q. InvokeModel と Converse はどちらを使いますか。 A. AWS の入門ページでは、対応しているモデルなら Converse を勧めています。InvokeModel はモデルごとのリクエスト形式（JSON 文字列）を自分で組み立てます。Converse はモデルが変わっても同じ形で、会話の履歴も扱いやすくなっています。

Q. Lambda から呼ぶときに気をつけることは？ A. 実行ロールに bedrock:InvokeModel を付けます。Lambda のタイムアウトの既定は 3秒なので、生成にかかる時間に合わせて延ばします。Lambda の基本は、関連記事「AWS Lambda Python入門｜3.14対応handler例とローカルテスト」で扱っています。

Q. 使えるモデルの一覧をコードで取れますか。 A. boto3.client("bedrock").list_foundation_models() で取れます。推論に使う bedrock-runtime とは別のクライアントです。

Q. 料金はどこを見ればよいですか。 A. レスポンスの usage に、入力と出力のトークン数が入っています。課金はこの数が元になります。

まとめ

• Python からは boto3.client("bedrock-runtime").converse()。権限は bedrock:InvokeModel
• 新しい Claude は jp. や global. の推論プロファイルIDで呼ぶ。東京から使える ID はモデルカードで確かめる
• system は リスト、inferenceConfig は camelCase（maxTokens）
• 会話は 毎回全部送り直す。返答の output.message をそのまま履歴に足す
• ストリームは converse_stream() の stream を for で回す。ツール引数は文字列の断片で届く
• ツールは tool_use → 自分で実行 → user の toolResult で返す
• ThrottlingException は既定で4回まで再試行された。Config で回数と read_timeout を変えられる

参考・出典

確認日はいずれも 2026年10月12日です。

• Amazon Bedrock ユーザーガイド「Inference using Converse API」：https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html
• Amazon Bedrock API リファレンス「Converse」：https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html
• Amazon Bedrock API リファレンス「ImageBlock」：https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ImageBlock.html
• Amazon Bedrock ユーザーガイド「Run Amazon Bedrock API examples with Boto3」：https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started-api-ex-python.html
• Amazon Bedrock ユーザーガイド「Models at a glance」：https://docs.aws.amazon.com/bedrock/latest/userguide/model-cards.html
• Amazon Bedrock モデルカード「Claude Haiku 5.5」：https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-haiku-5-5.html
• Amazon Bedrock モデルカード「Claude Sonnet 5.5」：https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-sonnet-5-5.html
• Amazon Bedrock モデルカード「Claude Haiku 4.5」：https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-haiku-4-5.html
• Amazon Bedrock ユーザーガイド「Use an inference profile in model invocation」：https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-use.html
• Amazon Bedrock ユーザーガイド「Prerequisites for inference profiles」：https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-prereq.html
• Amazon Bedrock ユーザーガイド「Access Amazon Bedrock foundation models」：https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html
• Amazon Bedrock ユーザーガイド「Use a tool to complete an Amazon Bedrock model response」（client-side）：https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use-client-side.html
• Amazon Bedrock ユーザーガイド「Troubleshooting Amazon Bedrock API Error Codes」：https://docs.aws.amazon.com/bedrock/latest/userguide/troubleshooting-api-error-codes.html

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。