Claude Web Search

Claude Web Search 讓支援該能力的 Claude 模型在回答時檢索網路，並在協議允許時回傳搜尋結果區塊和引用。它適合需要近期事實、來源核對或限定站點檢索的任務。

AGTCloud 可能透過 Chat 相容入口或 Anthropic Messages 結構提供 Claude 能力。二者的啟用欄位和回傳結構不同，應按目前模型詳情選擇入口。

不要把搜尋工具版本寫成永久設定

Anthropic 原生搜尋工具使用帶版本的類型名稱。可用版本和模型支援範圍可能變化，請使用目前模型詳情和對應 Reference 登記的值，不要從舊專案複製固定模型或工具版本。

透過 Chat 相容入口啟用搜尋

舊版文件記錄的 AGTCloud 主路徑是在 Chat 請求中新增 web_search_options：

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "尋找今天與人工智慧監管有關的重要訊息，並列出來源。"
      }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'

正文通常從 Assistant Message 讀取；引用是否以結構化 Annotation、連結或文字形式回傳，取決於目前模型和入口。不要在沒有回應依據時自行生成引用。

理解 Anthropic 原生工具結構

使用支援原生 Claude Web Search 的 Messages 入口時，搜尋工具位於 tools 中。下面只說明協議結構，工具類型應替換為目前模型文件提供的版本：

{
  "model": "MODEL_ID",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "尋找今天與人工智慧監管有關的重要訊息，並列出來源。"
    }
  ],
  "tools": [
    {
      "type": "WEB_SEARCH_TOOL_VERSION",
      "name": "web_search",
      "max_uses": 5
    }
  ]
}

max_uses、網域過濾、使用者位置和動態過濾只在對應工具版本支援時使用。完整 Messages 容器和 Content Block 結構見 Anthropic Messages Reference。

讀取搜尋結果和引用

原生 Messages 回應可能包含以下不同類型的 Content Block：

server_tool_use：表示模型送出了伺服器端搜尋工具呼叫。
web_search_tool_result：包含搜尋結果或工具錯誤。
text：模型給使用者的最終回答。
citations：在回應提供時，將回答片段與網頁來源關聯。

用戶端應按 type 分支處理，不能把所有 Content Blocks 當作一般字串串接。

{
  "content": [
    {
      "type": "text",
      "text": "根據檢索結果……",
      "citations": [
        {
          "type": "web_search_result_location",
          "url": "https://example.com/article",
          "title": "來源標題"
        }
      ]
    }
  ]
}

範例用於說明引用與文字屬於同一回應結構；實際欄位以目前回應和 Messages Reference 為準。

網域、位置和動態過濾

在工具版本支援時，可以使用：

allowed_domains：只允許指定網域。
blocked_domains：排除指定網域；不要與允許清單同時設定。
user_location：提供城市、地區、國家和時區等本地化資訊。
動態過濾：讓支援的工具組合進一步篩選搜尋結果。

這些選項會影響來源範圍，但不能保證網頁內容正確。高風險業務仍應驗證來源、時間和多方一致性。

區分搜尋工具錯誤和 HTTP 錯誤

搜尋工具失敗不一定意味著整個 HTTP 請求失敗。原生回應可能仍回傳成功狀態，但在 web_search_tool_result 中包含錯誤物件。

情況	處理方式
HTTP 認證或參數錯誤	按狀態碼處理，不進入正常 Content Block 解析
搜尋工具回傳錯誤塊	記錄錯誤類型，決定改寫問題、減少搜尋範圍或降級為非搜尋回答
搜尋成功但沒有引用	顯示回答時明確沒有可核對來源，不生成虛假連結
達到搜尋次數限制	停止繼續搜尋，向使用者說明結果可能不完整

原生搜尋與自訂工具的區別

Claude Web Search 由模型或伺服器端搜尋工具執行。自訂 Tool Calling 則由你的應用呼叫自有搜尋服務並回傳結果。需要控制索引、存取權限或內部資料時，使用Tool Calling更合適。

上線前檢查

目前模型和協議明確支援所用 Web Search 欄位。
工具類型版本來自目前文件，而不是舊模型範例。
Content Block、搜尋結果、文字和引用分別解析。
工具錯誤不會被當作正常搜尋結果。
網域和位置資料只在業務需要時傳送。
搜尋內容不能直接觸發高風險工具或繞過授權。

Chat 欄位見 Chat Completions Reference，請求失敗時參閱錯誤與疑難排解。