Messages使用 Claude 進行建構

使用 Messages API

有效使用 Messages API 的實用模式與範例

Anthropic 提供兩種使用 Claude 進行建構的方式，各自適用於不同的使用情境：

	Messages API	Claude Managed Agents
說明	直接存取模型提示功能	預先建構、可配置的代理框架，在託管基礎架構中執行
最適合	自訂代理迴圈與細粒度控制	長時間執行的任務與非同步工作
了解更多	Messages API 文件	Claude Managed Agents 文件

本指南涵蓋使用 Messages API 的常見模式，包括基本請求、多輪對話、預填技巧以及視覺功能。如需完整的 API 規格，請參閱 Messages 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
  }
}

拒絕回應（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
  }
}

訊息中的系統角色

在 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 取得單一的選擇題答案。

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://platform.claude.com/docs/images/vision-example.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://platform.claude.com/docs/images/vision-example.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url)

Output

{
  "id": "msg_011CdKmWtV3oFx1C5yUbf5CY",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image is a beautiful minimalist/flat-design illustration of a sunset landscape. Here's what it contains:\n\n**Sky & Sun:**\n- A warm gradient sky transitioning from golden-yellow at the top to deep orange toward the horizon\n- A large pale yellow sun positioned in the upper-right area\n\n**Birds:**\n- Three small silhouetted birds flying in the upper-left portion of the sky, depicted as simple \"M\" or \"v\" shapes\n\n**Mountains:**\n- Multiple layered mountain peaks in purple and maroon tones\n- The mountains overlap to create depth, with varying shades of dusty purple and deep burgundy\n\n**Water:**\n- A dark purple body of water at the bottom of the image\n- A reflection of the sun shown as horizontal cream/peach colored lines in the center-bottom area\n\nThe overall style is clean, geometric, and uses a warm sunset color palette (oranges, yellows, purples, and maroons), giving it a peaceful, serene aesthetic typical of modern vector/flat design artwork."
    }
  ],
  "model": "claude-opus-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1030,
    "output_tokens": 350
  }
}

後續步驟

停止原因與備援

處理每個 stop_reason 值，並決定當回應結束時該採取什麼行動。

搭配 Claude 使用工具

為 Claude 提供工具，以便在 Messages API 中呼叫外部服務和 API。

電腦使用工具

使用 Messages API 控制桌面電腦環境。

結構化輸出

從 Claude 取得保證符合結構描述驗證的 JSON 輸出。

任務預算

使用 output_config.task_budget 為完整的代理迴圈設定建議性的 token 預算。

Was this page helpful?

Messages使用 Claude 進行建構

使用 Messages API

有效使用 Messages API 的實用模式與範例

Anthropic 提供兩種使用 Claude 進行建構的方式，各自適用於不同的使用情境：

	Messages API	Claude Managed Agents
說明	直接存取模型提示功能	預先建構、可配置的代理框架，在託管基礎架構中執行
最適合	自訂代理迴圈與細粒度控制	長時間執行的任務與非同步工作
了解更多	Messages API 文件	Claude Managed Agents 文件

本指南涵蓋使用 Messages API 的常見模式，包括基本請求、多輪對話、預填技巧以及視覺功能。如需完整的 API 規格，請參閱 Messages 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
  }
}

訊息中的系統角色

請參閱對話中途的系統訊息以取得完整指南，包括如何將其與提示快取結合使用。

預填 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://platform.claude.com/docs/images/vision-example.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://platform.claude.com/docs/images/vision-example.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url)

Output

{
  "id": "msg_011CdKmWtV3oFx1C5yUbf5CY",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image is a beautiful minimalist/flat-design illustration of a sunset landscape. Here's what it contains:\n\n**Sky & Sun:**\n- A warm gradient sky transitioning from golden-yellow at the top to deep orange toward the horizon\n- A large pale yellow sun positioned in the upper-right area\n\n**Birds:**\n- Three small silhouetted birds flying in the upper-left portion of the sky, depicted as simple \"M\" or \"v\" shapes\n\n**Mountains:**\n- Multiple layered mountain peaks in purple and maroon tones\n- The mountains overlap to create depth, with varying shades of dusty purple and deep burgundy\n\n**Water:**\n- A dark purple body of water at the bottom of the image\n- A reflection of the sun shown as horizontal cream/peach colored lines in the center-bottom area\n\nThe overall style is clean, geometric, and uses a warm sunset color palette (oranges, yellows, purples, and maroons), giving it a peaceful, serene aesthetic typical of modern vector/flat design artwork."
    }
  ],
  "model": "claude-opus-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1030,
    "output_tokens": 350
  }
}

後續步驟

停止原因與備援

處理每個 stop_reason 值，並決定當回應結束時該採取什麼行動。

搭配 Claude 使用工具

為 Claude 提供工具，以便在 Messages API 中呼叫外部服務和 API。

電腦使用工具

使用 Messages API 控制桌面電腦環境。

結構化輸出

從 Claude 取得保證符合結構描述驗證的 JSON 輸出。

任務預算

使用 output_config.task_budget 為完整的代理迴圈設定建議性的 token 預算。

Was this page helpful?

基本請求與回應

多輪對話

訊息中的系統角色

預填 Claude 的回應

視覺

後續步驟

基本請求與回應

多輪對話

訊息中的系統角色

預填 Claude 的回應

視覺

後續步驟

基本請求與回應

多輪對話

訊息中的系統角色

預填 Claude 的回應

視覺

後續步驟

基本請求與回應

多輪對話

訊息中的系統角色

預填 Claude 的回應

視覺

後續步驟