メッセージClaudeで構築する

Messages APIの使用

Messages APIを効果的に使用するための実践的なパターンと例

Anthropicは、Claudeを使って構築するための2つの方法を提供しており、それぞれ異なるユースケースに適しています。

	Messages API	Claude Managed Agents
概要	モデルへの直接的なプロンプトアクセス	マネージドインフラストラクチャ上で動作する、事前構築済みで設定可能なエージェントハーネス
最適な用途	カスタムエージェントループときめ細かな制御	長時間実行タスクと非同期処理
詳細情報	Messages APIドキュメント	Claude Managed Agentsドキュメント

このガイドでは、基本的なリクエスト、複数ターンの会話、プレフィル手法、ビジョン機能など、Messages APIを扱う際の一般的なパターンについて説明します。完全なAPI仕様については、Messages APIリファレンスを参照してください。

「zero data retention」（ゼロデータ保持）、すなわちZDRがこの機能にどのように適用されるかについては、APIとデータ保持を参照してください。

基本的なリクエストとレスポンス

temperature、top_p、top_kのサンプリングパラメータは、Claude 4.7以降のモデルおよびClaude Mythos Previewではサポートされていません。これらをデフォルト以外の値に設定すると400エラーが返されます。リクエストペイロードからこれらを省略し、代わりにプロンプトを使用してモデルの動作を誘導してください。移行ガイドを参照してください。

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)

Output

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

拒否レスポンス（stop_reason: "refusal"）には、すべてのモデルにおいて、拒否をトリガーしたポリシーカテゴリを識別するstop_detailsオブジェクトも含まれます。フィールドリファレンスと処理コードの例については、停止理由の処理を参照してください。

複数ターンの会話

Messages APIはステートレスです。つまり、常に完全な会話履歴をAPIに送信します。このパターンを使用して、時間をかけて会話を構築できます。以前の会話ターンは、必ずしも実際にClaudeから生成されたものである必要はありません。合成されたassistantメッセージを使用できます。

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)

Output

{
  "id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Sure, I'd be happy to provide..."
    }
  ],
  "model": "claude-opus-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 309
  }
}

メッセージ内のsystemロール

Claude Fable 5、Claude Mythos 5、Claude Opus 4.8、およびClaude Opus 5では、ユーザーターンの後に"role": "system"を持つメッセージを含めることができ（配置ルールに従います）、会話の途中で新しいシステム指示を追加できます。systemメッセージをmessagesの最初のエントリにすることはできません。最初から適用される指示には、トップレベルのsystemフィールドを使用してください。

会話途中のシステムメッセージは、トップレベルのsystemフィールドと同じ権限を持ちますが、メッセージ履歴の末尾に追加されるため、それより前のキャッシュされたプレフィックスを無効化しません。最初のターンから適用されるべき指示にはトップレベルのsystemフィールドを使用し、後になってから関連性が生じる指示には会話途中のシステムメッセージを使用してください。

プロンプトキャッシングとの組み合わせ方を含む完全なガイドについては、会話途中のシステムメッセージを参照してください。

Claudeの応答のプレフィル

入力メッセージリストの最後の位置に、Claudeの応答の一部を事前に入力できます。この手法を使用して、Claudeの応答を形作ることができます。次の例では、"max_tokens": 1を使用して、Claudeから単一の多肢選択式の回答を取得します。

プレフィルは、Claude 4.6以降のモデルおよびClaude Mythos Previewではサポートされていません。これらのモデルでプレフィルを使用したリクエストは400エラーを返します。代わりに、サポートされているモデルでは構造化出力を使用するか、システムプロンプトの指示を使用してください。移行パターンについては、移行ガイドを参照してください。

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message)

Output

{
  "id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "C"
    }
  ],
  "model": "claude-sonnet-4-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1
  }
}

ビジョン

Claudeはリクエスト内のテキストと画像の両方を読み取ることができます。画像はbase64、url、またはfileのソースタイプを使用して提供できます。fileソースタイプは、Files APIを通じてアップロードされた画像を参照します。サポートされているメディアタイプはimage/jpeg、image/png、image/gif、およびimage/webpです。詳細については、ビジョンガイドを参照してください。

import base64
import httpx

# オプション1: Base64エンコードされた画像
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message)

# オプション2: URL参照の画像
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url)

Output

{
  "id": "msg_01EcyWo6m4hyW8KHs2y2pei5",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an ant, specifically a close-up view of an ant. The ant is shown in detail, with its distinct head, antennae, and legs clearly visible. The image is focused on capturing the intricate details and features of the ant, likely taken with a macro lens to get an extreme close-up perspective."
    }
  ],
  "model": "claude-opus-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1551,
    "output_tokens": 71
  }
}

次のステップ

停止理由とフォールバック

各stop_reasonの値を処理し、レスポンスが終了したときに何をすべきかを決定します。

Claudeでのツール使用

Messages API内から外部サービスやAPIを呼び出すためのツールをClaudeに提供します。

コンピュータ使用ツール

Messages APIでデスクトップコンピュータ環境を制御します。

構造化出力

Claudeから保証された、スキーマ検証済みのJSON出力を取得します。

タスクバジェット

output_config.task_budgetを使用して、エージェントループ全体にわたる助言的なトークンバジェットを設定します。

Was this page helpful?

メッセージClaudeで構築する

Messages APIの使用

Messages APIを効果的に使用するための実践的なパターンと例

Anthropicは、Claudeを使って構築するための2つの方法を提供しており、それぞれ異なるユースケースに適しています。

	Messages API	Claude Managed Agents
概要	モデルへの直接的なプロンプトアクセス	マネージドインフラストラクチャ上で動作する、事前構築済みで設定可能なエージェントハーネス
最適な用途	カスタムエージェントループときめ細かな制御	長時間実行タスクと非同期処理
詳細情報	Messages APIドキュメント	Claude Managed Agentsドキュメント

「zero data retention」（ゼロデータ保持）、すなわちZDRがこの機能にどのように適用されるかについては、APIとデータ保持を参照してください。

基本的なリクエストとレスポンス

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)

Output

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

複数ターンの会話

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)

Output

{
  "id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Sure, I'd be happy to provide..."
    }
  ],
  "model": "claude-opus-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 309
  }
}

メッセージ内のsystemロール

プロンプトキャッシングとの組み合わせ方を含む完全なガイドについては、会話途中のシステムメッセージを参照してください。

Claudeの応答のプレフィル

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message)

Output

{
  "id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "C"
    }
  ],
  "model": "claude-sonnet-4-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1
  }
}

ビジョン

import base64
import httpx

# オプション1: Base64エンコードされた画像
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message)

# オプション2: URL参照の画像
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url)

Output

{
  "id": "msg_01EcyWo6m4hyW8KHs2y2pei5",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an ant, specifically a close-up view of an ant. The ant is shown in detail, with its distinct head, antennae, and legs clearly visible. The image is focused on capturing the intricate details and features of the ant, likely taken with a macro lens to get an extreme close-up perspective."
    }
  ],
  "model": "claude-opus-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1551,
    "output_tokens": 71
  }
}

次のステップ

停止理由とフォールバック

各stop_reasonの値を処理し、レスポンスが終了したときに何をすべきかを決定します。

Claudeでのツール使用

Messages API内から外部サービスやAPIを呼び出すためのツールをClaudeに提供します。

コンピュータ使用ツール

Messages APIでデスクトップコンピュータ環境を制御します。

構造化出力

Claudeから保証された、スキーマ検証済みのJSON出力を取得します。

タスクバジェット

output_config.task_budgetを使用して、エージェントループ全体にわたる助言的なトークンバジェットを設定します。

Was this page helpful?

基本的なリクエストとレスポンス

複数ターンの会話

メッセージ内のsystemロール

Claudeの応答のプレフィル

ビジョン

次のステップ

基本的なリクエストとレスポンス

複数ターンの会話

メッセージ内のsystemロール

Claudeの応答のプレフィル

ビジョン

次のステップ

基本的なリクエストとレスポンス

複数ターンの会話

メッセージ内のsystemロール

Claudeの応答のプレフィル

ビジョン

次のステップ

基本的なリクエストとレスポンス

複数ターンの会話

メッセージ内のsystemロール

Claudeの応答のプレフィル

ビジョン

次のステップ