Amazon Bedrock Converse APIの使い方｜boto3実装・ConverseStream・Tool Use・IAM権限【2026年10月】

Amazon Bedrock の Converse API は、Claude・Nova・Llama など Bedrock 上のチャット系モデルを同じリクエスト形式で呼び出せる統一インターフェースです。boto3 では bedrock-runtime クライアントの converse と converse_stream を使います。この記事では、東京リージョンで今使えるモデルIDを使った最小実装、Claude 5 世代で 400 エラーになる指定、ConverseStream、Tool Use のループ、推論と構造化出力、IAM 権限までを、botocore 1.43.118（2026-10-22 公開）のサービス定義に照らしたコードで説明します。

まとめ：Converse APIの要点

• 呼び出し方：boto3.client("bedrock-runtime") の converse（一括応答）と converse_stream（逐次応答）。リクエスト本文は共通です。
• 東京から Claude を呼ぶID：国内で処理を完結させるなら jp.anthropic.claude-opus-5-5 か jp.anthropic.claude-haiku-5-5。Sonnet 5.5 には jp. が無く、東京からは global. だけです。
• Claude 5 世代の注意：temperature・topP・top_k は付けない。Opus 5.5・Sonnet 5.5 では toolChoice の any・tool も拒否されます。
• IAM：bedrock:Converse というアクションは存在しません。converse は bedrock:InvokeModel、converse_stream は bedrock:InvokeModelWithResponseStream で認可されます。
• 会話状態はアプリ側：Bedrock は履歴を保存しません。返ってきた output.message を加工せずに messages へ積み直します。

Converse APIの仕組みとInvokeModelとの違い

Converse は bedrock-runtime エンドポイントの Converse と ConverseStream の2操作です。InvokeModel がモデル提供元ごとのJSON（Anthropic なら anthropic_version と max_tokens 等）をそのまま渡すのに対し、Converse は共通の項目へ正規化し、応答も output・stopReason・usage・metrics の形で返します。AWS のユーザーガイドは、メッセージに対応するすべての Bedrock モデルで動く API と位置づけています。

リクエストに指定できる項目

botocore 1.43.118 の ConverseRequest が持つ項目は次の13個です（API定義上の必須項目は modelId のみで、通常の会話入力には messages を使います）。

プロンプト管理のプロンプトARNを modelId に渡す場合は、additionalModelRequestFields・inferenceConfig・system・toolConfig を指定できません（Converse の API リファレンス）。

InvokeModelとConverseの使い分け

新しくチャットやエージェントを書くなら、既定は Converse です。モデルを差し替えても modelId 以外をほぼ触らずに済み、ツール利用やガードレールも同じ書き方で付けられます。InvokeModel を選ぶのは、埋め込みや画像生成のように会話形式でないモデルを呼ぶとき、または提供元APIの新機能を Converse の対応を待たずに生で使いたいときです。Claude だけを使うと決めているなら、Anthropic の Messages API 形式で呼ぶ経路もあり、その比較はBedrock Claudeの使い方：Messages API・InvokeModel・Claude Codeの設定にまとめています。Bedrock の始め方そのものはAmazon Bedrockの使い方｜料金・モデル・APIの始め方を4ステップで解説【2026年版】を参照してください。

boto3でConverseを呼び出す手順

クライアント名は bedrock-runtime です。boto3.client("converse") というサービスは存在せず、bedrock（管理系API）のクライアントにも converse メソッドはありません。client の作り方やリトライ設定はboto3とは｜clientとresourceの違い・認証・リトライを実装で解説【2026年最新】で扱っています。

東京リージョンで指定するモデルID

新しい Claude は、東京で素のモデルID（anthropic.claude-…）を指定しても呼べず、推論プロファイルIDが必要です。2026-10-26 時点の AWS モデルカード（Claude Opus 5.5 ほか）では次のとおりです。

jp. の振り分け先は東京と大阪だけです。Claude 5.5 の3モデルから国内処理の要件に合わせて選ぶなら、Sonnet 5.5 は対象外で、jp.プロファイルを使える Opus 5.5 か Haiku 5.5 が候補です。経路ごとの国内処理の違いはAWSでClaudeを使う方法｜BedrockとClaude Platform on AWSの違いと選び方【2026年9月】で比べています。

最小のconverse呼び出し

実行前に boto3 をインストールし、AWS認証情報またはBedrock APIキーと、対象モデルを呼び出す権限を設定してください。以降の例は、ここで作成する bedrock と MODEL_ID を共通で使います。

import boto3

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

response = bedrock.converse(
    modelId=MODEL_ID,
    system=[{"text": "あなたは簡潔に答える技術サポートです。"}],
    messages=[
        {"role": "user", "content": [{"text": "Converse APIとInvokeModelの違いを一言で。"}]}
    ],
    inferenceConfig={"maxTokens": 2048},
)

content = response["output"]["message"]["content"]
print("".join(b["text"] for b in content if "text" in b))
print(response["stopReason"], response["usage"]["totalTokens"])

本文を content[0]["text"] で取り出す古い書き方は避けます。Haiku 5.5 は推論（adaptive thinking）が既定で有効で、Opus 5.5 は常に有効です。推論が走ると content の先頭に reasoningContent ブロックが入り、content[0] には text キーがありません。text を持つブロックだけを連結すれば、どのモデルでも動きます。

Claude 5世代で400エラーになる指定

Claude 4.5 世代までの例をそのまま Opus 5.5 や Haiku 5.5 に向けると、ValidationException で止まることがあります。Anthropic のClaude Opus 5.5 移行ガイドは、次の指定を拒否（400）または省略すべきものとして挙げています。

Haiku 5.5 もモデル概要で temperature・top_p・top_k を省くよう求めています。一方 Haiku 5.5 は推論をオフにできます。モデルを差し替えても動くのが Converse の利点ですが、モデル固有の制約までは吸収しません。差し替えのたびに、モデルカードの対応機能欄を確かめる工程を残してください。Sonnet 5.5 の変更点はClaude Sonnet 5.5とは？料金・破壊的変更5点・Bedrockでの使い方とSonnet 5からの移行手順【2026年10月】で詳しく扱っています。

マルチターン会話の履歴の積み方

Bedrock は送られた内容を保存せず、その応答の生成にだけ使います。会話を続けるのはアプリ側の責任です。前のターンの output.message をそのまま messages へ追記し、次のユーザー発話を足して送り直します。

messages = [{"role": "user", "content": [{"text": "AWSの生成AIサービスは？"}]}]
resp = bedrock.converse(modelId=MODEL_ID, messages=messages)

# 応答は推論ブロックと署名ごと無加工で積む
messages.append(resp["output"]["message"])
messages.append({"role": "user", "content": [{"text": "その中でチャット向けはどれ？"}]})
resp = bedrock.converse(modelId=MODEL_ID, messages=messages)

無加工で積む理由は2つあります。reasoningContent の署名（signature）は、テキストごと改変せずに返すことが求められます。もう1つはツール利用で、toolUse の ID と次のターンの toolResult が対応していないと弾かれます。履歴が伸びると毎回の入力トークンも増えるため、長い system プロンプトやツール定義を繰り返し送るならAmazon Bedrockのプロンプトキャッシュとは｜仕組み・対応モデル・料金・実装方法【2026年最新】の cachePoint で入力コストを下げられます。

stopReasonの値と分岐

応答の stopReason が取り得る値は、botocore のサービス定義で9つです。処理を分ける必要があるのは主に次の5つです。

残りの4つは stop_sequence（停止文字列に一致）、content_filtered、malformed_model_output、malformed_tool_use です。後ろの2つは出力やツール呼び出しの形が崩れたことを示し、同じ要求を再送すれば通ることがあります。推論が走るモデルでは思考にもトークンを使うため、maxTokens を小さくしすぎると本文が出る前に max_tokens で止まります。

IAM権限：bedrock:Converseではなくbedrock:InvokeModelでの認可

bedrock:converse は実際に検索される表記ですが、Converse 専用の IAM アクションはありません。AWS のポリシージェネレーターが持つ Amazon Bedrock のアクション269個にも、Converse を名前に含むものはありません（2026-10-26 にポリシージェネレーターの policies.js を取得し、Amazon Bedrock の Actions 配列を数えた結果）。認可は既存の推論アクションで行われます。

ポリシーに bedrock:Converse と書いても何も許可されず、bedrock:InvokeModel を付け忘れると AccessDeniedException になります。推論プロファイル経由で呼ぶときは、プロファイルのARNと、振り分け先リージョンの基盤モデルARNの両方を許可します。次の例は対象を広く許可する説明用です。123456789012を自分のアカウントIDに置き換え、本番では利用するプロファイル・モデル・リージョンにResourceを絞ります。

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

画像・ドキュメント・動画を S3 URI で渡す場合は、呼び出し元のロールに対象オブジェクトへの s3:GetObject も要ります。逆に特定モデルを使わせたくないときは、この2アクションを Deny します。ConverseStream の API リファレンスにあるとおり、基盤の2アクションを塞げば Converse と ConverseStream も同時に止まります。なお Messages API 形式の経路（bedrock-mantle）は名前空間が別で、bedrock-mantle:CreateInference で認可されます。

ConverseStreamのストリーミング応答と実装例

チャット画面で生成中の文字を順に出したいなら converse_stream を使います。基本的なリクエスト項目は converse と共通ですが、guardrailConfig.streamProcessingMode などストリーミング専用の設定があります。応答はイベント列として受け取ります。AWS CLI はストリーミング操作に対応していないため、動作確認も SDK で行います。

converse_streamのイベント列とテキスト抽出

応答の stream には、messageStart →（ブロックごとに contentBlockStart・contentBlockDelta・contentBlockStop）→ messageStop（stopReason を持つ）→ metadata（usage と metrics）の順でイベントが届きます。本文は contentBlockDelta の delta.text に少しずつ入り、推論は delta.reasoningContent に入ります。

resp = bedrock.converse_stream(
    modelId=MODEL_ID,
    messages=[{"role": "user", "content": [{"text": "Bedrockを3行で紹介して。"}]}],
)

for event in resp["stream"]:
    if "contentBlockDelta" in event:
        delta = event["contentBlockDelta"]["delta"]
        if "text" in delta:
            print(delta["text"], end="", flush=True)
    elif "messageStop" in event:
        print("\n停止理由:", event["messageStop"]["stopReason"])
    elif "metadata" in event:
        print("トークン:", event["metadata"]["usage"]["totalTokens"])

Streamlit の st.write_stream にはこのイベント列を直接渡せないため、テキストだけを返すジェネレーターで包みます。画面側はStreamlitでチャットボットのUIを作る手順｜st.chat_input・session_stateで会話履歴を保持する実装で扱っています。

ストリーム途中のエラーとTool Useの部分JSON

呼び出し自体が成功しても、生成の途中でエラーが起きることがあります。API の定義では、stream の中に throttlingException（429）・modelStreamErrorException（424）・validationException（400）・internalServerException（500）・serviceUnavailableException（503）が届きます（ConverseStreamOutput）。ただし boto3 では、これらはイベントの辞書のキーとしては見えません。botocore がループの途中で botocore.exceptions.EventStreamError（ClientError のサブクラス）として送出し、e.response["Error"]["Code"] に throttlingException などの名前が入ります。converse_stream の呼び出しだけを try で囲んでも捕まらないので、for ループごと囲みます。

ツール呼び出しの入力（toolUse の input）は、完成した JSON ではなく delta.toolUse.input に分割された文字列で届きます。ブロックごとに連結し、contentBlockStop を受けてから json.loads します。

import json
from botocore.exceptions import EventStreamError

# 前節の表示ループに代えて使う。ツール定義は後節の tool_config を使用する。
resp = bedrock.converse_stream(
    modelId=MODEL_ID,
    messages=[{"role": "user", "content": [{"text": "Tokyoの現在の天気を調べて。"}]}],
    toolConfig=tool_config,
)
buffers = {}
try:
    for event in resp["stream"]:
        if "contentBlockDelta" in event:
            idx = event["contentBlockDelta"]["contentBlockIndex"]
            delta = event["contentBlockDelta"]["delta"]
            if "toolUse" in delta:
                buffers[idx] = buffers.get(idx, "") + delta["toolUse"]["input"]
        elif "contentBlockStop" in event:
            idx = event["contentBlockStop"]["contentBlockIndex"]
            if idx in buffers:
                args = json.loads(buffers.pop(idx))   # ブロック確定後にパース
except EventStreamError as e:
    code = e.response["Error"]["Code"]   # 例: throttlingException
    print("生成途中で失敗:", code)

逐次表示が要らないなら、ツール利用は非ストリーミングの converse で書く方が、次章のループが単純になります。

ConverseのTool Use（外部ツール連携）と実行ループ

Converse の Tool Use はクライアント側で実行する方式です。モデルは「このツールをこの引数で呼びたい」と返すだけで、実行するのはアプリです。

toolConfigのツール定義と入力スキーマ

ツールは toolConfig.tools[].toolSpec に、名前・説明・入力スキーマ（inputSchema.json）で定義します。"strict": True を付けると、ツール名と入力がスキーマどおりになるよう Bedrock 側で強制されます（構造化出力のユーザーガイド）。その場合、スキーマには "additionalProperties": False を書きます。

tool_config = {
    "tools": [{
        "toolSpec": {
            "name": "get_weather",
            "description": "指定都市の現在の天気を返す",
            "strict": True,
            "inputSchema": {"json": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "都市名。例: Tokyo"}
                },
                "required": ["city"],
                "additionalProperties": False
            }}
        }
    }],
    "toolChoice": {"auto": {}}
}

toolChoice には auto・any・tool の3種がありますが、Opus 5.5 と Sonnet 5.5 のモデルカードは、クライアント側のツール呼び出しを auto と none だけ対応としています。system プロンプトで促してもツールが呼ばれる保証は無いため、業務上必ず実行すべき処理はモデルの判断に任せず、アプリ側から呼びます。出力の形を固定したいだけなら、後述の outputConfig を使います。

stopReason=tool_useを起点にした実行ループ

stopReason が tool_use なら、content の toolUse ブロック（toolUseId・name・input）を取り出して実行し、同じ toolUseId を付けた toolResult を返して再度呼びます。1回の応答に複数の toolUse が入ることがあり、その結果は1つの user メッセージにまとめて返します。別々の user メッセージに分けると role の交互が崩れて ValidationException になります。

def run(bedrock, user_text):
    messages = [{"role": "user", "content": [{"text": user_text}]}]
    resp = bedrock.converse(modelId=MODEL_ID, messages=messages, toolConfig=tool_config)
    messages.append(resp["output"]["message"])

    # tool_use が続く限り、実行して結果を返す
    tool_rounds = 0
    while resp["stopReason"] == "tool_use":
        if tool_rounds >= 5:   # 上限は業務に合わせて調整
            raise RuntimeError("ツール実行が上限の5ラウンドに達しました")
        tool_rounds += 1
        tool_results = []
        for block in resp["output"]["message"]["content"]:
            if "toolUse" not in block:
                continue
            tu = block["toolUse"]
            try:
                data = get_weather(tu["input"]["city"])   # 事前に実装が必要。都市名を受け取り、JSON化可能な値を返す
                tool_results.append({"toolUseId": tu["toolUseId"],
                                     "content": [{"json": data}]})
            except Exception as e:
                tool_results.append({"toolUseId": tu["toolUseId"],
                                     "content": [{"text": str(e)}], "status": "error"})

        # 複数ツールの結果は1つのuserメッセージにまとめる
        messages.append({"role": "user",
                         "content": [{"toolResult": r} for r in tool_results]})
        resp = bedrock.converse(modelId=MODEL_ID, messages=messages, toolConfig=tool_config)
        messages.append(resp["output"]["message"])

    return "".join(b["text"] for b in resp["output"]["message"]["content"] if "text" in b)

失敗した結果に "status": "error" を付けると、モデルが引数を変えて再試行するか、ユーザーへ説明するかを判断できます。コードの while に5ラウンドの上限を付けているのは、ツールが同じ失敗を返し続けたときに呼び出しと課金が止まらなくなるのを防ぐためです。ツールの実行と認証を Bedrock 側に寄せて集中管理したい場合は、AgentCore Gatewayと AgentCore APIの使い方：InvokeModel対応・フォールバック設定とSDK・CLIでの本番デプロイの構成が候補になります。

Converseの推論設定と構造化出力

Converse には推論（adaptive thinking）の専用項目がなく、Claude では additionalModelRequestFields に Anthropic 形式のまま渡します。出力をJSONに固定する方は outputConfig という共通項目があります。

additionalModelRequestFieldsのthinking・effort設定

AWS のadaptive thinking のユーザーガイドは、Converse では thinking と output_config.effort を additionalModelRequestFields の中に置く書き方を示しています。effort は low・medium・high・xhigh・max の5段階で、Opus 5.5 と Haiku 5.5 の既定は medium です。

response = bedrock.converse(
    modelId="jp.anthropic.claude-opus-5-5",
    messages=[{"role": "user", "content": [{"text": "この障害ログから原因の候補を3つ挙げて。"}]}],
    inferenceConfig={"maxTokens": 8000},
    additionalModelRequestFields={
        "thinking": {"type": "adaptive", "display": "summarized"},
        "output_config": {"effort": "high"},
    },
)

for block in response["output"]["message"]["content"]:
    if "reasoningContent" in block:
        print("[推論]", block["reasoningContent"].get("reasoningText", {}).get("text", ""))
    elif "text" in block:
        print(block["text"])

display を省くと、推論ブロックは返っても本文は空で、署名だけが入ります。推論の要約を画面やログに残したいときだけ summarized を指定します。botocore 1.43.118 のサービス定義では outputConfig 自体にも effort が定義されていますが、2026-10-26 時点の API リファレンスの OutputConfig ページには textFormat しか載っていないため、本記事ではユーザーガイドの書き方に合わせています。

outputConfig.textFormatのJSONスキーマ指定

応答をそのまま json.loads したいなら、プロンプトで「JSONで返して」と頼むより outputConfig.textFormat を使います。スキーマは辞書ではなくJSON文字列で渡す点に注意してください。

import json

schema = {
    "type": "object",
    "properties": {
        "title": {"type": "string"},
        "severity": {"type": "string", "enum": ["low", "medium", "high"]},
        "next_steps": {"type": "array", "items": {"type": "string"}}
    },
    "required": ["title", "severity", "next_steps"],
    "additionalProperties": False
}

response = bedrock.converse(
    modelId=MODEL_ID,
    messages=[{"role": "user", "content": [{"text": "次の障害報告を要約して: ..."}]}],
    outputConfig={"textFormat": {
        "type": "json_schema",
        "structure": {"jsonSchema": {
            "schema": json.dumps(schema),
            "name": "incident_summary",
            "description": "障害報告の要約"
        }}
    }},
)

text = "".join(b["text"] for b in response["output"]["message"]["content"] if "text" in b)
if response["stopReason"] != "end_turn":
    raise RuntimeError(f"JSON応答が正常完了していません: {response['stopReason']}")
data = json.loads(text)

stopReason を先に見ているのは、構造化出力でも maxTokens に達すると途中までのJSONが返るためです（構造化出力のユーザーガイド）。同じガイドによると、新しいスキーマは初回に文法へ変換され、最大で約90秒かかります。変換結果は初回アクセスから24時間キャッシュされ、同じアカウントで同じスキーマなら2回目以降は速く返ります。スキーマが対応外の書き方を含むと即座に400になるため、本番投入前に一度通しておくと初回の遅延も避けられます。

画像・ドキュメントを送るときの制約

content には text のほか image・document・video・audio などのブロックを入れられます。Message の API リファレンスにある上限は次のとおりです。

画像とドキュメントは user のメッセージにしか入れられず、ドキュメントを入れるときは同じ content に text ブロックも必要です。document の name はモデルが指示として読んでしまうおそれがあるため、ファイル名をそのまま入れず「report」のような中立な名前にするよう API リファレンスが注意しています。

with open("invoice.pdf", "rb") as f:
    pdf_bytes = f.read()

response = bedrock.converse(
    modelId=MODEL_ID,
    messages=[{"role": "user", "content": [
        {"document": {"format": "pdf", "name": "invoice", "source": {"bytes": pdf_bytes}}},
        {"text": "この請求書の合計金額と支払期限を答えて。"}
    ]}],
)

実装時の判断と失敗パターン

エラー名から原因を引けるよう、ここまでの注意点を並べ直します。

• ValidationException：東京で素のモデルIDを指定した、または Claude 5 世代に temperature・top_k・強制ツールを渡した。
• AccessDeniedException：bedrock:InvokeModel 系が無い。推論プロファイルだけ許可して基盤モデルARNを許可していない場合も、確認対象です。
• KeyError: ‘text’：content[0]["text"] で本文を取っている。先頭が推論ブロックになっている。
• 2ターン目で弾かれる：応答を整形してから履歴に積み、推論の署名やツールIDの対応が崩れた。

Converse を使わない方がよい場面もあります。埋め込みや画像生成は Converse の対象外なので InvokeModel で呼びます。Claude 固有の新機能を使い続けたいチームで、モデルを他社へ差し替える予定が無いなら、Converse の正規化は利点が薄く、Messages API 形式の方が提供元のドキュメントをそのまま読めます。モデルの選び方はAWS Bedrockのモデル選定｜Claude・Nova・OpenAI・Gemmaの選び分けと切替判断で整理しています。Bedrock を使った社内チャットや業務アプリを、モデル選定や権限設計から進めたい場合は生成AI導入支援でご相談を受けています。

よくある質問

bedrock:converse というIAMアクションはありますか？

ありません。Converse は bedrock:InvokeModel、ConverseStream は bedrock:InvokeModelWithResponseStream で認可されます。推論プロファイル経由なら、プロファイルと基盤モデルの両方のARNを許可してください。

ConverseとConverseStreamの違いは何ですか？

基本的なリクエスト項目は共通ですが、ConverseStreamにはガードレールのストリーム処理方式などの専用設定があります。converse は生成が終わってから一括で返し、converse_stream は contentBlockDelta などのイベント列で順に返します。ストリーミングでは、生成途中のエラーが for ループの中で EventStreamError として送出されます。

ConverseとInvokeModelはどちらを使えばよいですか？

会話やツール利用を含む新規実装なら Converse です。モデルを差し替えてもリクエストの形が変わりません。埋め込み・画像生成のように会話形式でないモデルを呼ぶとき、または提供元APIの新機能を生で使いたいときは InvokeModel を使います。

additionalModelRequestFields には何を入れますか？

Converse の共通項目に無い、モデル固有のパラメータを入れます。Claude なら thinking や output_config.effort がこれに当たります。Claude 5 世代では top_k を入れると拒否されるため、古い例のように {"top_k": 200} を入れないでください。

stopReason が guardrail_intervened になるのはなぜですか？

guardrailConfig で指定したガードレールが入力か出力をブロックしたときの値です。guardrailConfig.trace を enabled にすると、応答の trace でブロック内容を確認できるので、ログに残してからユーザーには定型の案内文を返します。

関連記事

• Amazon Bedrockの使い方｜料金・モデル・APIの始め方を4ステップで解説【2026年版】
• Bedrock Claudeの使い方：Messages API・InvokeModel・Claude Codeの設定
• Amazon Bedrockのプロンプトキャッシュとは｜仕組み・対応モデル・料金・実装方法【2026年最新】
• AWSでClaudeを使う方法｜BedrockとClaude Platform on AWSの違いと選び方【2026年9月】
• AgentCore Gatewayと AgentCore APIの使い方：InvokeModel対応・フォールバック設定とSDK・CLIでの本番デプロイ