Build with Claude 完整指南：從功能總覽到 Messages API 的實戰解析

Build with Claude 是 Anthropic 平台的核心開發文件區塊，涵蓋了從功能總覽到具體 API 使用模式的完整開發基礎。本文將逐一解析四大核心主題，確保不遺漏任何知識點。

一、Features Overview：功能總覽

API 功能矩陣

Claude 的 API 功能分為五大區域：

  1. Model Capabilities：控制 Claude 的推理方式和回應格式
  2. Tools：讓 Claude 在網路上或環境中執行操作
  3. Tool Infrastructure：處理工具的發現和大規模編排
  4. Context Management：維持長時間運行的工作階段效率
  5. Files and Assets：管理提供給 Claude 的文件和資料

Model Capabilities

功能說明
1M token context window擴展的 context window，可處理更大的文件和更長的對話
Adaptive Thinking讓 Claude 動態決定何時及如何思考，Opus 4.6 推薦的思考模式
Batch Processing異步處理大量請求，節省 50% 成本
Citations將 Claude 的回應錨定在來源文件中，提供可驗證的引用
Data Residency透過 inference_geo 參數控制模型推論的地理位置
Effort控制回應深度與 token 效率的平衡
Extended Thinking增強推理能力，提供逐步思考過程的透明度
PDF Support處理和分析 PDF 文件中的文字和視覺內容
Search Results為 RAG 應用啟用自然引用和來源歸屬
Structured Outputs以 JSON Outputs 和 Strict Tool Use 保證 schema 一致性

Tools

分為 Server-side 和 Client-side 兩類：

Server-side Tools（由平台執行）：

  • Code Execution：在沙箱環境中執行程式碼
  • Memory：跨對話儲存和檢索資訊
  • Web Fetch：從網頁和 PDF 擷取完整內容
  • Web Search：以即時網路資料增強 Claude 的知識

Client-side Tools（由開發者實作和執行）：

  • Bash：執行 bash 命令和腳本
  • Computer Use：控制電腦介面（截圖、滑鼠、鍵盤）
  • Text Editor：建立和編輯文字檔案

Tool Infrastructure

功能說明
Agent Skills以預建或自訂 Skills 擴展 Claude 的能力
Fine-grained Tool Streaming不經緩衝/JSON 驗證即串流工具參數
MCP Connector直接從 Messages API 連接遠端 MCP 伺服器
Programmatic Tool Calling從程式碼執行容器中程式化呼叫工具
Tool Search透過 regex 搜尋動態發現和載入工具

Context Management

功能說明
Compaction伺服器端 context 摘要，自動壓縮長對話
Context Editing可配置策略自動管理對話 context
Automatic Prompt Caching以單一 API 參數簡化快取
Prompt Caching (5m)5 分鐘快取持續時間，降低成本和延遲
Prompt Caching (1hr)1 小時延長快取，適合較少存取但重要的 context
Token Counting在發送前確定訊息的 token 數

Files and Assets

  • Files API：上傳和管理檔案，支援 PDF、圖片和文字檔，避免每次請求都重新上傳

二、Using the Messages API：使用 Messages API

基本請求與回應

Messages API 是與 Claude 互動的核心介面。基本請求包含 model、max_tokens 和 messages 參數：

import anthropic

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

回應包含 id、content（含 text blocks）、stop_reason、usage（含 input_tokens 和 output_tokens）等欄位。

Messages API 是無狀態的

Messages API 是 stateless 設計，每次請求都需發送完整的對話歷史。這意味著：

  • 開發者自行管理對話狀態
  • 每次請求都需包含所有先前的訊息
  • 可以使用合成的 assistant 訊息來建構對話
messages = [
    {"role": "user", "content": "Hello, Claude"},
    {"role": "assistant", "content": "Hello!"},
    {"role": "user", "content": "Can you describe LLMs to me?"},
]

Prefilling（預填回應）

可以在 messages 列表的最後一個位置預填 Claude 的回應開頭，用於塑造回應格式：

messages = [
    {"role": "user", "content": "拉丁語中螞蟻是什麼？(A) Apoidea (B) Rhopalocera (C) Formicidae"},
    {"role": "assistant", "content": "答案是 ("},
]

注意：Prefilling 在 Claude Opus 4.6、Sonnet 4.6 和 Sonnet 4.5 上已棄用。建議改用 Structured Outputs 或 system prompt 指令。

Vision（視覺）

Messages API 支援在請求中包含圖片，支援 base64 和 url 兩種來源類型，以及 image/jpeg、image/png、image/gif、image/webp 媒體類型：

messages = [{
    "role": "user",
    "content": [
        {
            "type": "image",
            "source": {
                "type": "url",
                "url": "https://example.com/image.jpg",
            },
        },
        {"type": "text", "text": "這張圖片中有什麼？"},
    ],
}]

Content Types

Messages 中的 content 可以包含多種類型的區塊：

  • text：文字內容
  • image：圖片內容（base64 或 URL）
  • document：文件內容（PDF、純文字、自訂內容）
  • tool_use：工具呼叫
  • tool_result：工具結果
  • thinking：Extended Thinking 的思考區塊
  • search_result：搜尋結果

Zero Data Retention (ZDR)

Messages API 支援 ZDR。當組織有 ZDR 安排時，透過此功能發送的資料在 API 回應返回後不會被儲存。

三、Handling Stop Reasons：處理停止原因

stop_reason 概述

每個成功的 Messages API 回應都包含 stop_reason 欄位，指出 Claude 為何停止生成回應。這不同於 HTTP 錯誤——stop_reason 表示的是正常完成的原因。

Stop Reason 類型

end_turn

最常見的停止原因。表示 Claude 自然完成了回應。

空回應的 end_turn 情況：有時 Claude 會返回空回應（2-3 個 token 且無內容）搭配 end_turn。常見原因：

  • 在 tool_result 後立即添加 text blocks
  • 將 Claude 已完成的回應直接傳回且未添加任何內容

預防方式：不要在 tool_result 後立即添加 text blocks。若仍遇到空回應，在新的 user message 中添加延續提示。

max_tokens

Claude 因達到請求中指定的 max_tokens 限制而停止。回應被截斷，需考慮發起後續請求以繼續生成。

stop_sequence

Claude 遇到了開發者自訂的停止序列。可透過 response.stop_sequence 欄位確認觸發了哪個序列。

tool_use

Claude 正在呼叫工具，等待開發者執行工具並返回結果。需提取工具名稱和參數、執行工具、將結果傳回 Claude。

pause_turn

在執行 server tools（如 web search、web fetch）時，伺服器端取樣迴圈達到其迭代限制（預設 10 次）。處理方式是將回應原樣傳回以讓 Claude 繼續處理。

refusal

Claude 因安全考量拒絕生成回應。應考慮重新措辭或修改請求。

model_context_window_exceeded

Claude 因達到模型的 context window 限制而停止。這允許開發者在不知道確切輸入大小的情況下請求最大可能的 token 數。此功能在 Sonnet 4.5 及更新模型上預設可用。

最佳實踐

  1. 始終檢查 stop_reason：在回應處理邏輯中養成檢查 stop_reason 的習慣
  2. 優雅處理截斷回應：當回應因 token 限制被截斷時，可警告使用者或發起繼續請求
  3. 實作 pause_turn 的重試邏輯：使用 server tools 時，自動處理 pause_turn 以繼續對話

Stop Reasons vs Errors

面向Stop ReasonsErrors
性質回應本體的一部分HTTP 4xx/5xx 狀態碼
含義生成正常停止的原因請求處理失敗
內容回應包含有效內容回應包含錯誤詳情

Streaming 中的 stop_reason

串流時：

  • message_start 事件中為 null
  • 在 message_delta 事件中提供
  • 其他事件中不提供

四、Prompt Engineering Overview：提示工程概覽

前提條件

在進行 prompt engineering 之前，應先確立：

  1. 對用例成功標準的清晰定義
  2. 可以根據這些標準進行經驗性測試的方法
  3. 想要改進的初稿 prompt

Prompt Engineering vs Fine-tuning

Prompt engineering 相比 fine-tuning 有顯著優勢：

  • 資源效率：fine-tuning 需要高階 GPU 和大量記憶體，prompt engineering 只需文字輸入
  • 成本效益：fine-tuning 產生大量費用，prompt engineering 使用基礎模型通常更便宜
  • 維護模型更新：模型更新時 fine-tuned 版本可能需要重新訓練，prompt 通常跨版本有效
  • 節省時間：fine-tuning 可能需要數小時或數天，prompt engineering 幾乎即時
  • 最小資料需求：fine-tuning 需要大量任務特定的標註資料，prompt engineering 支援 few-shot 甚至 zero-shot
  • 靈活性與快速迭代：可快速嘗試各種方法並立即看到結果
  • 領域適應：無需重新訓練即可透過 prompt 中的領域特定上下文適應新領域
  • 理解力提升：prompt engineering 在幫助模型理解和利用外部內容方面遠比 fine-tuning 有效
  • 保留通用知識：fine-tuning 有災難性遺忘的風險，prompt engineering 維持模型的廣泛能力
  • 透明度：prompt 是人類可讀的，清楚顯示模型接收到的資訊

Prompt Engineering 技術清單

按照從最廣泛有效到更專業化的順序排列：

  1. Prompt Generator：使用 Claude Console 的 prompt 產生器
  2. Be Clear and Direct：清晰且直接
  3. Use Examples (Multishot)：使用範例（多次示範）
  4. Let Claude Think (Chain of Thought)：讓 Claude 思考（思維鏈）
  5. Use XML Tags：使用 XML 標籤
  6. Give Claude a Role (System Prompts)：給 Claude 一個角色（系統提示）
  7. Chain Complex Prompts：串連複雜提示
  8. Long Context Tips：長上下文技巧

何時使用 Prompt Engineering

並非所有成功標準或失敗的評估都最適合透過 prompt engineering 解決。例如，延遲和成本有時可以透過選擇不同的模型來更輕易地改善。Prompt engineering 專注於可透過提示控制的成功標準。

學習資源

Anthropic 提供了兩種互動式教學：

  • GitHub prompting tutorial：充滿範例的教學，涵蓋文件中的 prompt engineering 概念
  • Google Sheets prompting tutorial：透過互動式試算表的輕量版 prompt engineering 教學

總結

Build with Claude 的四大核心主題為開發者提供了從宏觀到微觀的完整開發基礎：Features Overview 提供了功能矩陣和選擇指引；Messages API 解析了核心互動模式（stateless 設計、多輪對話、prefilling、vision）；Stop Reasons 確保應用程式能正確處理各種回應終止情境；Prompt Engineering Overview 則為持續優化 Claude 表現提供了方法論框架。掌握這四個主題，是高效使用 Claude API 的重要基石。