--- title: 搜尋結果 url: https://platform.claude.com/docs/zh-TW/build-with-claude/search-results description: 透過提供具有來源歸屬的搜尋結果，為 RAG 應用程式取得自然的引用 featureMetadata: status: stable zdr: eligibility: eligible note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). supportedModels: - claude-fable-5-2 - claude-mythos-5-2 - claude-fable-5-1 - claude-mythos-5-1 - claude-fable-5 - claude-mythos-5 - claude-mythos-preview - claude-opus-5-5 - claude-opus-5 - claude-sonnet-5-5 - claude-sonnet-5 - claude-haiku-5-5 - claude-haiku-4-5-20251001 - claude-opus-4-8 - claude-opus-4-7 - claude-opus-4-6 - claude-sonnet-4-6 - claude-opus-4-5-20251101 - claude-sonnet-4-5-20250929 supportedPlatforms: Claude API: stable Claude Platform on AWS: stable Amazon Bedrock: stable Amazon Bedrock (InvokeModel): stable Claude Models on Google Cloud (Google managed): stable Microsoft Foundry: stable --- **API 支援**：用法因產品而異。 * **Messages API**：在工具結果中或直接在使用者訊息中傳送 `search_result` 區塊。 * **Managed Agents**：僅在工具結果中接受（例如 `user.custom_tool_result` 事件），不接受於 `user.message` 事件中。 搜尋結果內容區塊讓 Claude 能以引用網路搜尋結果的相同方式引用您自己的內容：每個引用都會帶有您提供的來源和標題。請在 Claude 需要將答案歸屬於您的文件的「Retrieval-Augmented Generation」（檢索增強生成），即 RAG 應用程式中使用它們。 ## 運作方式 搜尋結果可以透過兩種方式提供： 1. **來自工具呼叫：** 您的自訂工具回傳搜尋結果，讓您能夠建構動態 RAG 應用程式。 2. **作為頂層內容：** 您直接在使用者訊息中提供搜尋結果，適用於預先擷取或快取的內容。 在這兩種情況下，啟用引用時 Claude 都會自動引用搜尋結果。不需要特殊的提示：只需提出您的問題，引用就會出現在使用您內容的文字區塊上。不過，如果您的提示只要求 JSON，回應可能只包含少量引用或完全沒有引用。若要擷取每個值都附有引用的結構化資料，請參閱[取得附帶引用的結構化資料](https://platform.claude.com/docs/zh-TW/build-with-claude/citations#get-structured-data-with-citations)。 ### 搜尋結果結構描述 搜尋結果使用以下結構： ```json { "type": "search_result", "source": "https://example.com/article", // Required: Source URL or identifier "title": "Article Title", // Required: Title of the result "content": [ // Required: Array of text blocks { "type": "text", "text": "The actual content of the search result..." } ], "citations": { // Optional: Citation configuration "enabled": true // Enable/disable citations for this result } } ``` ### 必要欄位 | 欄位 | 類型 | 說明 | | --------- | ------ | --------------------------------------------------- | | `type` | string | 必須是 `"search_result"` | | `source` | string | 內容的來源。任何穩定的字串都可以：URL，或是內部識別碼，例如 `kb://article-1234` | | `title` | string | 搜尋結果的描述性標題 | | `content` | array | 包含實際內容的文字區塊陣列 | ### 選用欄位 | 欄位 | 類型 | 說明 | | --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `citations` | object | 具有 `enabled` 布林欄位的引用設定。引用預設為停用；本頁的每個範例都明確設定了 `"enabled": true`。請求中的所有搜尋結果必須使用相同的設定（請參閱[引用控制](https://platform.claude.com/docs/zh-TW/build-with-claude/search-results#citation-control)） | | `cache_control` | object | 快取控制設定（例如 `{"type": "ephemeral"}`） | `content` 陣列中的每個項目都必須是具有以下內容的文字區塊： * `type`：必須是 `"text"` * `text`：實際的文字內容（非空字串） 搜尋結果僅包含文字。`content` 陣列中不支援圖片和其他媒體。 ## 方法 1：來自工具呼叫的搜尋結果 從您的自訂工具回傳搜尋結果，讓您能夠建構動態 RAG 應用程式：工具在執行時擷取內容，而 Claude 在回應中引用它。以下範例使用 [`tool_choice`](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/define-tools#forcing-tool-use) 強制進行工具呼叫，因此每次都會執行檢索步驟。 ### 範例：知識庫工具 工具呼叫流程需要在您的應用程式中加入搜尋邏輯，這不是單一 shell 命令能完成的。請使用 Claude SDK 來實作完整流程。如需包含搜尋結果的工具對話的原始請求格式，請參閱[結合兩種方法](https://platform.claude.com/docs/zh-TW/build-with-claude/search-results#combining-both-methods)。若要直接在使用者訊息中提供搜尋結果，請參閱[方法 2：作為頂層內容的搜尋結果](https://platform.claude.com/docs/zh-TW/build-with-claude/search-results#method-2-search-results-as-top-level-content)。 工具呼叫流程需要在您的應用程式中加入搜尋邏輯，這不是單一 shell 命令能完成的。請使用 Claude SDK 來實作完整流程。如需包含搜尋結果的工具對話的原始請求格式，請參閱[結合兩種方法](https://platform.claude.com/docs/zh-TW/build-with-claude/search-results#combining-both-methods)。若要直接在使用者訊息中提供搜尋結果，請參閱[方法 2：作為頂層內容的搜尋結果](https://platform.claude.com/docs/zh-TW/build-with-claude/search-results#method-2-search-results-as-top-level-content)。 ```python Python from anthropic.types import ( MessageParam, TextBlockParam, SearchResultBlockParam, ToolResultBlockParam, ) client = Anthropic() # 定義知識庫搜尋工具 knowledge_base_tool = { "name": "search_knowledge_base", "description": "Search the company knowledge base for information", "input_schema": { "type": "object", "properties": {"query": {"type": "string", "description": "The search query"}}, "required": ["query"], }, } # 處理工具呼叫的函式 def search_knowledge_base(query): # 在此撰寫您的搜尋邏輯 # 以正確格式傳回搜尋結果 return [ SearchResultBlockParam( type="search_result", source="https://docs.company.com/product-guide", title="Product Configuration Guide", content=[ TextBlockParam( type="text", text="To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs.", ) ], citations={"enabled": True}, ), SearchResultBlockParam( type="search_result", source="https://docs.company.com/troubleshooting", title="Troubleshooting Guide", content=[ TextBlockParam( type="text", text="If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values.", ) ], citations={"enabled": True}, ), ] # 以清單建立對話，從使用者的問題開始 messages: list[MessageParam] = [ {"role": "user", "content": "How do I configure the timeout settings?"} ] # 建立附帶該工具的訊息 response = client.messages.create( model="claude-opus-5", max_tokens=1024, tools=[knowledge_base_tool], tool_choice={ "type": "tool", "name": "search_knowledge_base", "disable_parallel_tool_use": True, }, messages=messages, ) # 當 Claude 呼叫工具時，提供搜尋結果。 # tool_use 區塊不一定是第一個：請逐一迭代找出它。 tool_use = next((block for block in response.content if block.type == "tool_use"), None) if tool_use is not None: tool_result = search_knowledge_base(tool_use.input["query"]) # 將 Claude 的回合及工具結果附加到進行中的對話 messages.append({"role": "assistant", "content": response.content}) messages.append( { "role": "user", "content": [ ToolResultBlockParam( type="tool_result", tool_use_id=tool_use.id, content=tool_result, # Search results go here ) ], } ) # 將工具結果傳回 final_response = client.messages.create( model="claude-opus-5", max_tokens=1024, messages=messages, ) print(final_response) ``` ```typescript TypeScript const client = new Anthropic(); // 定義知識庫搜尋工具 const knowledgeBaseTool: Anthropic.Tool = { name: "search_knowledge_base", description: "Search the company knowledge base for information", input_schema: { type: "object" as const, properties: { query: { type: "string", description: "The search query" } }, required: ["query"] } }; // 處理工具呼叫的函式 function searchKnowledgeBase(query: string) { // 在此撰寫您的搜尋邏輯 // 以正確格式傳回搜尋結果 return [ { type: "search_result" as const, source: "https://docs.company.com/product-guide", title: "Product Configuration Guide", content: [ { type: "text" as const, text: "To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs." } ], citations: { enabled: true } }, { type: "search_result" as const, source: "https://docs.company.com/troubleshooting", title: "Troubleshooting Guide", content: [ { type: "text" as const, text: "If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values." } ], citations: { enabled: true } } ]; } // 以清單建立對話，從使用者的問題開始 const messages: Anthropic.MessageParam[] = [ { role: "user", content: "How do I configure the timeout settings?" } ]; // 建立附帶工具的訊息 const response = await client.messages.create({ model: "claude-opus-5", max_tokens: 1024, tools: [knowledgeBaseTool], tool_choice: { type: "tool", name: "search_knowledge_base", disable_parallel_tool_use: true }, messages }); // 處理工具使用並提供結果。 // tool_use 區塊不一定位於第一個：請在 content 陣列中尋找。 const toolUse = response.content.find((block) => block.type === "tool_use"); if (toolUse) { const input = toolUse.input as { query: string }; const toolResult = searchKnowledgeBase(input.query); // 將 Claude 的回合及工具結果附加至進行中的對話 messages.push({ role: "assistant", content: response.content }); messages.push({ role: "user", content: [ { type: "tool_result" as const, tool_use_id: toolUse.id, content: toolResult // Search results go here } ] }); // 將工具結果傳回 const finalResponse = await client.messages.create({ model: "claude-opus-5", max_tokens: 1024, messages }); console.log(finalResponse); } ``` ```csharp C# AnthropicClient client = new(); var tools = new List { new ToolUnion(new Tool() { Name = "search_knowledge_base", Description = "Search the company knowledge base for information", InputSchema = new InputSchema() { Properties = new Dictionary { ["query"] = JsonSerializer.SerializeToElement(new { type = "string", description = "The search query" }), }, Required = ["query"], }, }), }; // 處理工具呼叫的函式 static List SearchKnowledgeBase(string query) { // 在此撰寫您的搜尋邏輯 // 以正確格式傳回搜尋結果 return [ new SearchResultBlockParam { Source = "https://docs.company.com/product-guide", Title = "Product Configuration Guide", Content = [new() { Text = "To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs." }], Citations = new() { Enabled = true }, }, new SearchResultBlockParam { Source = "https://docs.company.com/troubleshooting", Title = "Troubleshooting Guide", Content = [new() { Text = "If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values." }], Citations = new() { Enabled = true }, }, ]; } // 以清單建構對話，從使用者的問題開始 List messages = [new UserMessageParam { Content = "How do I configure the timeout settings?" }]; // 建立使用該工具的訊息 var response = await client.Messages.Create(new() { Model = Model.ClaudeOpus5, MaxTokens = 1024, Tools = tools, ToolChoice = new ToolChoiceTool { Name = "search_knowledge_base", DisableParallelToolUse = true, }, Messages = messages, }); // 當 Claude 呼叫工具時，提供搜尋結果。 // tool_use 區塊不一定是第一個：請找出第一個 tool_use 區塊。 foreach (var block in response.Content) { if (block.TryPickToolUse(out var toolUse)) { var query = toolUse.Input["query"].GetString() ?? ""; var toolResults = SearchKnowledgeBase(query); // 將 Claude 的回合及工具結果依序附加到進行中的對話 messages.Add(new AssistantMessageParam { Content = response.Content.Select(contentBlock => new ContentBlockParam(contentBlock.Json)).ToList() }); messages.Add(new UserMessageParam { Content = new MessageContentParam( [new ContentBlockParam(new ToolResultBlockParam() { ToolUseID = toolUse.ID, Content = new ToolResultBlockParamContent(toolResults) })] ), }); // 將工具結果傳回 var finalResponse = await client.Messages.Create(new() { Model = Model.ClaudeOpus5, MaxTokens = 1024, Messages = messages, }); Console.WriteLine(finalResponse); break; } } ``` ```go Go client := anthropic.NewClient() knowledgeBaseTool := anthropic.ToolUnionParam{ OfTool: &anthropic.ToolParam{ Name: "search_knowledge_base", Description: anthropic.String("Search the company knowledge base for information"), InputSchema: anthropic.ToolInputSchemaParam{ Properties: map[string]any{ "query": map[string]any{ "type": "string", "description": "The search query", }, }, Required: []string{"query"}, }, }, } // 在 slice 中逐步建立對話，從使用者的問題開始 messages := []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("How do I configure the timeout settings?")), } response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5, MaxTokens: 1024, Tools: []anthropic.ToolUnionParam{knowledgeBaseTool}, ToolChoice: anthropic.ToolChoiceUnionParam{ OfTool: &anthropic.ToolChoiceToolParam{ Name: "search_knowledge_base", DisableParallelToolUse: anthropic.Bool(true), }, }, Messages: messages, }) if err != nil { log.Fatal(err) } // tool_use 區塊不一定在第一個：請在 content 清單中尋找 var toolUse *anthropic.ToolUseBlock for _, block := range response.Content { if variant, ok := block.AsAny().(anthropic.ToolUseBlock); ok { toolUse = &variant break } } if toolUse != nil { var input struct { Query string `json:"query"` } if err := json.Unmarshal(toolUse.Input, &input); err != nil { log.Fatal(err) } toolResults := searchKnowledgeBase(input.Query) // 將 Claude 的回合與工具結果依序附加到進行中的對話 messages = append(messages, response.ToParam()) messages = append(messages, anthropic.NewUserMessage(anthropic.ContentBlockParamUnion{ OfToolResult: &anthropic.ToolResultBlockParam{ ToolUseID: toolUse.ID, Content: toolResults, }, })) // 將工具結果傳回 finalResponse, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5, MaxTokens: 1024, Messages: messages, }) if err != nil { log.Fatal(err) } fmt.Println(finalResponse) } // ... func searchKnowledgeBase(query string) []anthropic.ToolResultBlockParamContentUnion { return []anthropic.ToolResultBlockParamContentUnion{ {OfSearchResult: &anthropic.SearchResultBlockParam{ Content: []anthropic.TextBlockParam{ {Text: "To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs."}, }, Source: "https://docs.company.com/product-guide", Title: "Product Configuration Guide", Citations: anthropic.CitationsConfigParam{Enabled: anthropic.Bool(true)}, }}, {OfSearchResult: &anthropic.SearchResultBlockParam{ Content: []anthropic.TextBlockParam{ {Text: "If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values."}, }, Source: "https://docs.company.com/troubleshooting", Title: "Troubleshooting Guide", Citations: anthropic.CitationsConfigParam{Enabled: anthropic.Bool(true)}, }}, } } ``` ```java Java import com.anthropic.models.messages.ContentBlockParam; import com.anthropic.models.messages.CitationsConfigParam; // ... import com.anthropic.models.messages.MessageParam; import com.anthropic.models.messages.Model; import com.anthropic.models.messages.SearchResultBlockParam; import com.anthropic.models.messages.TextBlockParam; import com.anthropic.models.messages.Tool; import com.anthropic.models.messages.ToolChoice; import com.anthropic.models.messages.ToolChoiceTool; import com.anthropic.models.messages.ToolResultBlockParam; import com.anthropic.core.JsonValue; // ... void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); Tool knowledgeBaseTool = Tool.builder() .name("search_knowledge_base") .description("Search the company knowledge base for information") .inputSchema(Tool.InputSchema.builder() .properties(JsonValue.from(Map.of( "query", Map.of( "type", "string", "description", "The search query" ) ))) .putAdditionalProperty("required", JsonValue.from(List.of("query"))) .build()) .build(); // 在清單中逐步建立對話，從使用者的問題開始 List messages = new ArrayList<>(); messages.add(MessageParam.ofUser("How do I configure the timeout settings?")); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5) .maxTokens(1024L) .addTool(knowledgeBaseTool) .toolChoice(ToolChoice.ofTool(ToolChoiceTool.builder() .name("search_knowledge_base") .disableParallelToolUse(true) .build())) .messages(messages) .build(); Message response = client.messages().create(params); // tool_use 區塊不一定是第一個：請在 content 清單中尋找它 response.content().stream() .flatMap(contentBlock -> contentBlock.toolUse().stream()) .findFirst() .ifPresent(toolUse -> { Map input = (Map) toolUse._input().asObject().get(); List toolResult = searchKnowledgeBase( input.get("query").asStringOrThrow() ); // 將 Claude 的回合與工具結果依序附加到進行中的對話。 // 若只重建 tool_use 區塊，將會遺失 Claude 傳回的其他內容區塊， // 例如在未強制工具呼叫時位於前方的文字。 messages.add(response.toParam()); messages.add(MessageParam.ofUserOfContentBlockParams(List.of( ContentBlockParam.ofToolResult( ToolResultBlockParam.builder() .toolUseId(toolUse.id()) .contentOfBlocks(toolResult) .build() ) ))); // 將工具結果傳回 MessageCreateParams finalParams = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5) .maxTokens(1024L) .messages(messages) .build(); Message finalResponse = client.messages().create(finalParams); System.out.println(finalResponse); }); } static List searchKnowledgeBase(String query) { return List.of( ToolResultBlockParam.Content.Block.ofSearchResult( SearchResultBlockParam.builder() .source("https://docs.company.com/product-guide") .title("Product Configuration Guide") .content(List.of( TextBlockParam.builder() .text("To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs.") .build() )) .citations(CitationsConfigParam.builder() .enabled(true) .build()) .build() ), ToolResultBlockParam.Content.Block.ofSearchResult( SearchResultBlockParam.builder() .source("https://docs.company.com/troubleshooting") .title("Troubleshooting Guide") .content(List.of( TextBlockParam.builder() .text("If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values.") .build() )) .citations(CitationsConfigParam.builder() .enabled(true) .build()) .build() ) ); } ``` ```php PHP $client = new Client(); $knowledgeBaseTool = [ 'name' => 'search_knowledge_base', 'description' => 'Search the company knowledge base for information', 'input_schema' => [ 'type' => 'object', 'properties' => [ 'query' => [ 'type' => 'string', 'description' => 'The search query' ] ], 'required' => ['query'] ] ]; function searchKnowledgeBase($query) { return [ [ 'type' => 'search_result', 'source' => 'https://docs.company.com/product-guide', 'title' => 'Product Configuration Guide', 'content' => [ [ 'type' => 'text', 'text' => 'To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs.' ] ], 'citations' => ['enabled' => true] ], [ 'type' => 'search_result', 'source' => 'https://docs.company.com/troubleshooting', 'title' => 'Troubleshooting Guide', 'content' => [ [ 'type' => 'text', 'text' => 'If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values.' ] ], 'citations' => ['enabled' => true] ] ]; } // 以清單逐步建立對話，從使用者的問題開始 $messages = [ ['role' => 'user', 'content' => 'How do I configure the timeout settings?'] ]; $response = $client->messages->create( maxTokens: 1024, messages: $messages, model: 'claude-opus-5', toolChoice: [ 'type' => 'tool', 'name' => 'search_knowledge_base', 'disableParallelToolUse' => true, ], tools: [$knowledgeBaseTool], ); $toolUseBlock = null; foreach ($response->content as $block) { if ($block->type === 'tool_use') { $toolUseBlock = $block; break; } } if ($toolUseBlock !== null) { $toolResult = searchKnowledgeBase($toolUseBlock->input['query']); // 將 Claude 的回合及工具結果依序附加至進行中的對話 $messages[] = ['role' => 'assistant', 'content' => $response->content]; $messages[] = [ 'role' => 'user', 'content' => [ [ 'type' => 'tool_result', 'tool_use_id' => $toolUseBlock->id, 'content' => $toolResult ] ] ]; // 將工具結果傳回 $finalResponse = $client->messages->create( maxTokens: 1024, messages: $messages, model: 'claude-opus-5', ); echo $finalResponse; } else { echo $response; } ``` ```ruby Ruby client = Anthropic::Client.new knowledge_base_tool = { name: "search_knowledge_base", description: "Search the company knowledge base for information", input_schema: { type: "object", properties: { query: { type: "string", description: "The search query" } }, required: ["query"] } } def search_knowledge_base(query) [ { type: "search_result", source: "https://docs.company.com/product-guide", title: "Product Configuration Guide", content: [ { type: "text", text: "To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs." } ], citations: { enabled: true } }, { type: "search_result", source: "https://docs.company.com/troubleshooting", title: "Troubleshooting Guide", content: [ { type: "text", text: "If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values." } ], citations: { enabled: true } } ] end # 以清單逐步建構對話，從使用者的問題開始 messages = [ { role: "user", content: "How do I configure the timeout settings?" } ] response = client.messages.create( model: "claude-opus-5", max_tokens: 1024, tools: [knowledge_base_tool], tool_choice: { type: "tool", name: "search_knowledge_base", disable_parallel_tool_use: true }, messages: messages ) # tool_use 區塊不一定位於第一個：請在 content 陣列中尋找 tool_use = response.content.find { |block| block.type == :tool_use } if tool_use tool_result = search_knowledge_base(tool_use.input[:query]) # 將 Claude 的回合及工具結果依序附加到進行中的對話 messages << { role: "assistant", content: response.content } messages << { role: "user", content: [ { type: "tool_result", tool_use_id: tool_use.id, content: tool_result } ] } # 將工具結果傳回 final_response = client.messages.create( model: "claude-opus-5", max_tokens: 1024, messages: messages ) puts final_response end ``` ## 方法 2：作為頂層內容的搜尋結果 您也可以直接在使用者訊息中提供搜尋結果。這適用於： * 從您的搜尋基礎架構預先擷取的內容 * 來自先前查詢的快取搜尋結果 * 來自外部搜尋服務的內容 * 測試與開發 ### 範例：直接提供搜尋結果 ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2026-10-21" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 1024, "messages": [ { "role": "user", "content": [ { "type": "search_result", "source": "https://docs.company.com/api-reference", "title": "API Reference - Authentication", "content": [ { "type": "text", "text": "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium." } ], "citations": { "enabled": true } }, { "type": "search_result", "source": "https://docs.company.com/quickstart", "title": "Getting Started Guide", "content": [ { "type": "text", "text": "To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key." } ], "citations": { "enabled": true } }, { "type": "text", "text": "Based on these search results, how do I authenticate API requests and what are the rate limits?" } ] } ] }' ``` ```bash CLI ant messages create <<'YAML' model: claude-opus-5-5 max_tokens: 1024 messages: - role: user content: - type: search_result source: https://docs.company.com/api-reference title: API Reference - Authentication content: - type: text text: >- All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium. citations: enabled: true - type: search_result source: https://docs.company.com/quickstart title: Getting Started Guide content: - type: text text: >- To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key. citations: enabled: true - type: text text: >- Based on these search results, how do I authenticate API requests and what are the rate limits? YAML ``` ```python Python from anthropic.types import TextBlockParam, SearchResultBlockParam client = Anthropic() # 直接在使用者訊息中提供搜尋結果 response = client.messages.create( model="claude-opus-5-5", max_tokens=1024, messages=[ { "role": "user", "content": [ SearchResultBlockParam( type="search_result", source="https://docs.company.com/api-reference", title="API Reference - Authentication", content=[ TextBlockParam( type="text", text="All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium.", ) ], citations={"enabled": True}, ), SearchResultBlockParam( type="search_result", source="https://docs.company.com/quickstart", title="Getting Started Guide", content=[ TextBlockParam( type="text", text="To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key.", ) ], citations={"enabled": True}, ), TextBlockParam( type="text", text="Based on these search results, how do I authenticate API requests and what are the rate limits?", ), ], } ], ) print(response) ``` ```typescript TypeScript const client = new Anthropic(); // 直接在使用者訊息中提供搜尋結果 const response = await client.messages.create({ model: "claude-opus-5-5", max_tokens: 1024, messages: [ { role: "user", content: [ { type: "search_result" as const, source: "https://docs.company.com/api-reference", title: "API Reference - Authentication", content: [ { type: "text" as const, text: "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium." } ], citations: { enabled: true } }, { type: "search_result" as const, source: "https://docs.company.com/quickstart", title: "Getting Started Guide", content: [ { type: "text" as const, text: "To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key." } ], citations: { enabled: true } }, { type: "text" as const, text: "Based on these search results, how do I authenticate API requests and what are the rate limits?" } ] } ] }); console.log(response); ``` ```csharp C# AnthropicClient client = new(); // 直接在使用者訊息中提供搜尋結果 var response = await client.Messages.Create(new() { Model = Model.ClaudeOpus5_5, MaxTokens = 1024, Messages = [ new UserMessageParam { Content = new MessageContentParam( [ new ContentBlockParam(new SearchResultBlockParam { Source = "https://docs.company.com/api-reference", Title = "API Reference - Authentication", Content = [new() { Text = "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium." }], Citations = new() { Enabled = true }, }), new ContentBlockParam(new SearchResultBlockParam { Source = "https://docs.company.com/quickstart", Title = "Getting Started Guide", Content = [new() { Text = "To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key." }], Citations = new() { Enabled = true }, }), new ContentBlockParam(new TextBlockParam { Text = "Based on these search results, how do I authenticate API requests and what are the rate limits?" }), ]), }, ], }); Console.WriteLine(response); ``` ```go Go client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage( anthropic.ContentBlockParamUnion{OfSearchResult: &anthropic.SearchResultBlockParam{ Content: []anthropic.TextBlockParam{ {Text: "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium."}, }, Source: "https://docs.company.com/api-reference", Title: "API Reference - Authentication", Citations: anthropic.CitationsConfigParam{Enabled: anthropic.Bool(true)}, }}, anthropic.ContentBlockParamUnion{OfSearchResult: &anthropic.SearchResultBlockParam{ Content: []anthropic.TextBlockParam{ {Text: "To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key."}, }, Source: "https://docs.company.com/quickstart", Title: "Getting Started Guide", Citations: anthropic.CitationsConfigParam{Enabled: anthropic.Bool(true)}, }}, anthropic.NewTextBlock("Based on these search results, how do I authenticate API requests and what are the rate limits?"), ), }, }) if err != nil { log.Fatal(err) } fmt.Println(response) ``` ```java Java import com.anthropic.models.messages.ContentBlockParam; import com.anthropic.models.messages.CitationsConfigParam; // ... import com.anthropic.models.messages.SearchResultBlockParam; import com.anthropic.models.messages.TextBlockParam; // ... void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(1024L) .addUserMessageOfContentBlockParams(List.of( ContentBlockParam.ofSearchResult( SearchResultBlockParam.builder() .source("https://docs.company.com/api-reference") .title("API Reference - Authentication") .content(List.of( TextBlockParam.builder() .text("All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium.") .build() )) .citations(CitationsConfigParam.builder() .enabled(true) .build()) .build() ), ContentBlockParam.ofSearchResult( SearchResultBlockParam.builder() .source("https://docs.company.com/quickstart") .title("Getting Started Guide") .content(List.of( TextBlockParam.builder() .text("To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key.") .build() )) .citations(CitationsConfigParam.builder() .enabled(true) .build()) .build() ), ContentBlockParam.ofText( TextBlockParam.builder() .text("Based on these search results, how do I authenticate API requests and what are the rate limits?") .build() ) )) .build(); Message response = client.messages().create(params); System.out.println(response); } ``` ```php PHP $client = new Client(); $message = $client->messages->create( maxTokens: 1024, messages: [ [ 'role' => 'user', 'content' => [ [ 'type' => 'search_result', 'source' => 'https://docs.company.com/api-reference', 'title' => 'API Reference - Authentication', 'content' => [ [ 'type' => 'text', 'text' => 'All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium.' ] ], 'citations' => ['enabled' => true] ], [ 'type' => 'search_result', 'source' => 'https://docs.company.com/quickstart', 'title' => 'Getting Started Guide', 'content' => [ [ 'type' => 'text', 'text' => 'To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key.' ] ], 'citations' => ['enabled' => true] ], [ 'type' => 'text', 'text' => 'Based on these search results, how do I authenticate API requests and what are the rate limits?' ] ] ] ], model: Model::CLAUDE_OPUS_5_5, ); echo json_encode($message, JSON_PRETTY_PRINT); ``` ```ruby Ruby client = Anthropic::Client.new message = client.messages.create( model: Anthropic::Model::CLAUDE_OPUS_5_5, max_tokens: 1024, messages: [ { role: "user", content: [ { type: "search_result", source: "https://docs.company.com/api-reference", title: "API Reference - Authentication", content: [ { type: "text", text: "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium." } ], citations: { enabled: true } }, { type: "search_result", source: "https://docs.company.com/quickstart", title: "Getting Started Guide", content: [ { type: "text", text: "To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key." } ], citations: { enabled: true } }, { type: "text", text: "Based on these search results, how do I authenticate API requests and what are the rate limits?" } ] } ] ) puts message ``` ## Claude 帶有引用的回應 無論搜尋結果如何提供，Claude 在使用其中的資訊時都會自動包含引用： ```json { "role": "assistant", "content": [ { "type": "text", "text": "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard.", "citations": [ { "type": "search_result_location", "cited_text": "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium.", "source": "https://docs.company.com/api-reference", "title": "API Reference - Authentication", "search_result_index": 0, "start_block_index": 0, "end_block_index": 1 } ] }, { "type": "text", "text": "\n\nTo set this up from scratch, you'll need to " }, { "type": "text", "text": "sign up for an account, generate an API key from the dashboard, install the SDK using `pip install company-sdk`, and initialize the client with your API key.", "citations": [ { "type": "search_result_location", "cited_text": "To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key.", "source": "https://docs.company.com/quickstart", "title": "Getting Started Guide", "search_result_index": 1, "start_block_index": 0, "end_block_index": 1 } ] } ] } ``` ### 引用欄位 每個引用包含： | 欄位 | 類型 | 說明 | | --------------------- | ------------- | --------------------------------------------------------------------------------------- | | `type` | string | 對於搜尋結果引用，一律為 `"search_result_location"` | | `source` | string | 來自原始搜尋結果的來源 | | `title` | string 或 null | 來自原始搜尋結果的標題 | | `cited_text` | string | 被引用區塊的完整文字，串接在一起。等於 `content[start_block_index:end_block_index]` 的內容合併後的結果。不計入輸出 token。 | | `search_result_index` | integer | 被引用的搜尋結果在請求中所有 `search_result` 區塊之間的索引（從 0 開始），依其出現順序排列（跨所有訊息和工具結果）。 | | `start_block_index` | integer | 第一個被引用區塊在搜尋結果 `content` 陣列中的索引（從 0 開始）。 | | `end_block_index` | integer | 被引用區塊範圍在搜尋結果 `content` 陣列中的結束索引（不包含）。一律大於 `start_block_index`。 | 區塊索引標識出搜尋結果 `content` 陣列的一個切片，而 `cited_text` 是該切片的完整文字。文字區塊是最小的可引用單位：Claude 引用的是整個區塊，而不是區塊內的子字串。若要取得更細緻的引用，請將您的搜尋結果內容拆分為較小的區塊（請參閱[多個內容區塊](https://platform.claude.com/docs/zh-TW/build-with-claude/search-results#multiple-content-blocks)）。 ## 多個內容區塊 搜尋結果可以在 `content` 陣列中包含多個文字區塊： ```json { "type": "search_result", "source": "https://docs.company.com/api-guide", "title": "API Documentation", "content": [ { "type": "text", "text": "Authentication: All API requests require an API key." }, { "type": "text", "text": "Rate Limits: The API allows 1000 requests per hour per key." }, { "type": "text", "text": "Error Handling: The API returns standard HTTP status codes." } ], "citations": { "enabled": true } } ``` 引用速率限制區塊的引用如下所示： ```json { "type": "search_result_location", "cited_text": "Rate Limits: The API allows 1000 requests per hour per key.", "source": "https://docs.company.com/api-guide", "title": "API Documentation", "search_result_index": 0, "start_block_index": 1, "end_block_index": 2 } ``` 當此搜尋結果被引用時，`start_block_index` 和 `end_block_index` 會標識該引用涵蓋哪些區塊，而 `cited_text` 恰好包含這些區塊的文字。將內容拆分為較小、聚焦的區塊可讓 Claude 有更細緻的引用邊界；將內容合併為一個區塊則表示每個引用都會回傳完整文字。這與引用功能中的[自訂內容文件](https://platform.claude.com/docs/zh-TW/build-with-claude/citations#custom-content-documents)所使用的模型相同。 ## 進階用法 ### 結合兩種方法 您可以在同一個對話中混合使用兩種方法。Claude 會從任一來源進行引用，而 `search_result_index` 會依請求順序計算所有 `search_result` 區塊，無論其來源為何。 以下範例重現一個完整的對話。第一則使用者訊息帶有預先擷取的搜尋結果，助理回合呼叫知識庫工具，而工具結果回傳第二個搜尋結果。Claude 的答案引用了兩個來源： ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2026-10-21" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 1024, "tools": [ { "name": "search_knowledge_base", "description": "Search the company knowledge base for information", "input_schema": { "type": "object", "properties": { "query": {"type": "string", "description": "The search query"} }, "required": ["query"] } } ], "messages": [ { "role": "user", "content": [ { "type": "search_result", "source": "https://docs.company.com/overview", "title": "Product Overview", "content": [ { "type": "text", "text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards." } ], "citations": {"enabled": true} }, { "type": "text", "text": "What does Acme Dashboard do, and what plans is it available on?" } ] }, { "role": "assistant", "content": [ { "type": "text", "text": "Let me check the pricing information." }, { "type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "search_knowledge_base", "input": {"query": "Acme Dashboard pricing plans"} } ] }, { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": [ { "type": "search_result", "source": "https://docs.company.com/pricing", "title": "Pricing Plans", "content": [ { "type": "text", "text": "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing." } ], "citations": {"enabled": true} } ] } ] } ] }' ``` ```bash CLI ant messages create <<'YAML' model: claude-opus-5-5 max_tokens: 1024 tools: - name: search_knowledge_base description: Search the company knowledge base for information input_schema: type: object properties: query: type: string description: The search query required: [query] messages: - role: user content: - type: search_result source: https://docs.company.com/overview title: Product Overview content: - type: text text: >- Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards. citations: enabled: true - type: text text: What does Acme Dashboard do, and what plans is it available on? - role: assistant content: - type: text text: Let me check the pricing information. - type: tool_use id: toolu_01A09q90qw90lq917835lq9 name: search_knowledge_base input: query: Acme Dashboard pricing plans - role: user content: - type: tool_result tool_use_id: toolu_01A09q90qw90lq917835lq9 content: - type: search_result source: https://docs.company.com/pricing title: Pricing Plans content: - type: text text: >- Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing. citations: enabled: true YAML ``` ```python Python from anthropic.types import ( SearchResultBlockParam, TextBlockParam, ToolResultBlockParam, ToolUseBlockParam, ) client = Anthropic() knowledge_base_tool = { "name": "search_knowledge_base", "description": "Search the company knowledge base for information", "input_schema": { "type": "object", "properties": {"query": {"type": "string", "description": "The search query"}}, "required": ["query"], }, } # 重播一段以兩種方式提供搜尋結果的對話：第一則 # 使用者訊息攜帶預先擷取的結果，而工具結果則回傳另一個 response = client.messages.create( model="claude-opus-5-5", max_tokens=1024, tools=[knowledge_base_tool], messages=[ { "role": "user", "content": [ SearchResultBlockParam( type="search_result", source="https://docs.company.com/overview", title="Product Overview", content=[ TextBlockParam( type="text", text="Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.", ) ], citations={"enabled": True}, ), TextBlockParam( type="text", text="What does Acme Dashboard do, and what plans is it available on?", ), ], }, { "role": "assistant", "content": [ TextBlockParam( type="text", text="Let me check the pricing information." ), ToolUseBlockParam( type="tool_use", id="toolu_01A09q90qw90lq917835lq9", name="search_knowledge_base", input={"query": "Acme Dashboard pricing plans"}, ), ], }, { "role": "user", "content": [ ToolResultBlockParam( type="tool_result", tool_use_id="toolu_01A09q90qw90lq917835lq9", content=[ SearchResultBlockParam( type="search_result", source="https://docs.company.com/pricing", title="Pricing Plans", content=[ TextBlockParam( type="text", text="Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.", ) ], citations={"enabled": True}, ) ], ) ], }, ], ) print(response) ``` ```typescript TypeScript const client = new Anthropic(); const knowledgeBaseTool: Anthropic.Tool = { name: "search_knowledge_base", description: "Search the company knowledge base for information", input_schema: { type: "object" as const, properties: { query: { type: "string", description: "The search query" } }, required: ["query"] } }; // 重播一段以兩種方式提供搜尋結果的對話：第一則 // 使用者訊息攜帶預先擷取的結果，而 tool result（工具結果）則回傳另一個結果 const response = await client.messages.create({ model: "claude-opus-5-5", max_tokens: 1024, tools: [knowledgeBaseTool], messages: [ { role: "user", content: [ { type: "search_result" as const, source: "https://docs.company.com/overview", title: "Product Overview", content: [ { type: "text" as const, text: "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards." } ], citations: { enabled: true } }, { type: "text" as const, text: "What does Acme Dashboard do, and what plans is it available on?" } ] }, { role: "assistant", content: [ { type: "text" as const, text: "Let me check the pricing information." }, { type: "tool_use" as const, id: "toolu_01A09q90qw90lq917835lq9", name: "search_knowledge_base", input: { query: "Acme Dashboard pricing plans" } } ] }, { role: "user", content: [ { type: "tool_result" as const, tool_use_id: "toolu_01A09q90qw90lq917835lq9", content: [ { type: "search_result" as const, source: "https://docs.company.com/pricing", title: "Pricing Plans", content: [ { type: "text" as const, text: "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing." } ], citations: { enabled: true } } ] } ] } ] }); console.log(response); ``` ```csharp C# AnthropicClient client = new(); // 重播一段以兩種方式提供搜尋結果的對話：第一則 // 使用者訊息帶有預先擷取的結果，而工具結果則傳回另一個 var response = await client.Messages.Create(new() { Model = Model.ClaudeOpus5_5, MaxTokens = 1024, Tools = [ new ToolUnion(new Tool() { Name = "search_knowledge_base", Description = "Search the company knowledge base for information", InputSchema = new InputSchema() { Properties = new Dictionary { ["query"] = JsonSerializer.SerializeToElement(new { type = "string", description = "The search query" }), }, Required = ["query"], }, }), ], Messages = [ new UserMessageParam { Content = new MessageContentParam( [ new ContentBlockParam(new SearchResultBlockParam { Source = "https://docs.company.com/overview", Title = "Product Overview", Content = [new() { Text = "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards." }], Citations = new() { Enabled = true }, }), new ContentBlockParam(new TextBlockParam { Text = "What does Acme Dashboard do, and what plans is it available on?" }), ]), }, new AssistantMessageParam { Content = new MessageContentParam( [ new ContentBlockParam(new TextBlockParam { Text = "Let me check the pricing information." }), new ContentBlockParam(new ToolUseBlockParam { ID = "toolu_01A09q90qw90lq917835lq9", Name = "search_knowledge_base", Input = new Dictionary { ["query"] = JsonSerializer.SerializeToElement("Acme Dashboard pricing plans"), }, }), ]), }, new UserMessageParam { Content = new MessageContentParam( [ new ContentBlockParam(new ToolResultBlockParam() { ToolUseID = "toolu_01A09q90qw90lq917835lq9", Content = new ToolResultBlockParamContent( [ new SearchResultBlockParam { Source = "https://docs.company.com/pricing", Title = "Pricing Plans", Content = [new() { Text = "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing." }], Citations = new() { Enabled = true }, }, ]), }), ]), }, ], }); Console.WriteLine(response); ``` ```go Go client := anthropic.NewClient() knowledgeBaseTool := anthropic.ToolUnionParam{ OfTool: &anthropic.ToolParam{ Name: "search_knowledge_base", Description: anthropic.String("Search the company knowledge base for information"), InputSchema: anthropic.ToolInputSchemaParam{ Properties: map[string]any{ "query": map[string]any{"type": "string", "description": "The search query"}, }, Required: []string{"query"}, }, }, } // 重播一段以兩種方式提供搜尋結果的對話：第一則 // 使用者訊息攜帶預先擷取的結果，而 tool result（工具結果）則回傳另一個 response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 1024, Tools: []anthropic.ToolUnionParam{knowledgeBaseTool}, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage( anthropic.ContentBlockParamUnion{OfSearchResult: &anthropic.SearchResultBlockParam{ Content: []anthropic.TextBlockParam{ {Text: "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards."}, }, Source: "https://docs.company.com/overview", Title: "Product Overview", Citations: anthropic.CitationsConfigParam{Enabled: anthropic.Bool(true)}, }}, anthropic.NewTextBlock("What does Acme Dashboard do, and what plans is it available on?"), ), anthropic.NewAssistantMessage( anthropic.NewTextBlock("Let me check the pricing information."), anthropic.ContentBlockParamUnion{OfToolUse: &anthropic.ToolUseBlockParam{ ID: "toolu_01A09q90qw90lq917835lq9", Name: "search_knowledge_base", Input: map[string]any{"query": "Acme Dashboard pricing plans"}, }}, ), anthropic.NewUserMessage( anthropic.ContentBlockParamUnion{OfToolResult: &anthropic.ToolResultBlockParam{ ToolUseID: "toolu_01A09q90qw90lq917835lq9", Content: []anthropic.ToolResultBlockParamContentUnion{ {OfSearchResult: &anthropic.SearchResultBlockParam{ Content: []anthropic.TextBlockParam{ {Text: "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing."}, }, Source: "https://docs.company.com/pricing", Title: "Pricing Plans", Citations: anthropic.CitationsConfigParam{Enabled: anthropic.Bool(true)}, }}, }, }}, ), }, }) if err != nil { log.Fatal(err) } fmt.Println(response) ``` ```java Java import com.anthropic.core.JsonValue; import com.anthropic.models.messages.CitationsConfigParam; import com.anthropic.models.messages.ContentBlockParam; // ... import com.anthropic.models.messages.SearchResultBlockParam; import com.anthropic.models.messages.TextBlockParam; import com.anthropic.models.messages.Tool; import com.anthropic.models.messages.ToolResultBlockParam; import com.anthropic.models.messages.ToolUseBlockParam; // ... void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); Tool knowledgeBaseTool = Tool.builder() .name("search_knowledge_base") .description("Search the company knowledge base for information") .inputSchema(Tool.InputSchema.builder() .properties(JsonValue.from(Map.of( "query", Map.of("type", "string", "description", "The search query") ))) .putAdditionalProperty("required", JsonValue.from(List.of("query"))) .build()) .build(); // 重播一段以兩種方式提供搜尋結果的對話：第一則 // 使用者訊息附帶預先擷取的結果，而工具結果則傳回另一個 MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(1024L) .addTool(knowledgeBaseTool) .addUserMessageOfContentBlockParams(List.of( ContentBlockParam.ofSearchResult(SearchResultBlockParam.builder() .source("https://docs.company.com/overview") .title("Product Overview") .content(List.of(TextBlockParam.builder() .text("Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.") .build())) .citations(CitationsConfigParam.builder() .enabled(true) .build()) .build()), ContentBlockParam.ofText(TextBlockParam.builder() .text("What does Acme Dashboard do, and what plans is it available on?") .build()) )) .addAssistantMessageOfContentBlockParams(List.of( ContentBlockParam.ofText(TextBlockParam.builder() .text("Let me check the pricing information.") .build()), ContentBlockParam.ofToolUse(ToolUseBlockParam.builder() .id("toolu_01A09q90qw90lq917835lq9") .name("search_knowledge_base") .input(JsonValue.from(Map.of("query", "Acme Dashboard pricing plans"))) .build()) )) .addUserMessageOfContentBlockParams(List.of( ContentBlockParam.ofToolResult(ToolResultBlockParam.builder() .toolUseId("toolu_01A09q90qw90lq917835lq9") .contentOfBlocks(List.of( ToolResultBlockParam.Content.Block.ofSearchResult(SearchResultBlockParam.builder() .source("https://docs.company.com/pricing") .title("Pricing Plans") .content(List.of(TextBlockParam.builder() .text("Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.") .build())) .citations(CitationsConfigParam.builder() .enabled(true) .build()) .build()) )) .build()) )) .build(); Message response = client.messages().create(params); System.out.println(response); } ``` ```php PHP $client = new Client(); $knowledgeBaseTool = [ 'name' => 'search_knowledge_base', 'description' => 'Search the company knowledge base for information', 'input_schema' => [ 'type' => 'object', 'properties' => [ 'query' => ['type' => 'string', 'description' => 'The search query'] ], 'required' => ['query'] ] ]; // 重播一段以兩種方式提供搜尋結果的對話：第一則 // 使用者訊息帶有預先擷取的結果，而工具結果則傳回另一個 $response = $client->messages->create( maxTokens: 1024, tools: [$knowledgeBaseTool], messages: [ [ 'role' => 'user', 'content' => [ [ 'type' => 'search_result', 'source' => 'https://docs.company.com/overview', 'title' => 'Product Overview', 'content' => [ [ 'type' => 'text', 'text' => 'Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.' ] ], 'citations' => ['enabled' => true] ], [ 'type' => 'text', 'text' => 'What does Acme Dashboard do, and what plans is it available on?' ] ] ], [ 'role' => 'assistant', 'content' => [ ['type' => 'text', 'text' => 'Let me check the pricing information.'], [ 'type' => 'tool_use', 'id' => 'toolu_01A09q90qw90lq917835lq9', 'name' => 'search_knowledge_base', 'input' => ['query' => 'Acme Dashboard pricing plans'] ] ] ], [ 'role' => 'user', 'content' => [ [ 'type' => 'tool_result', 'tool_use_id' => 'toolu_01A09q90qw90lq917835lq9', 'content' => [ [ 'type' => 'search_result', 'source' => 'https://docs.company.com/pricing', 'title' => 'Pricing Plans', 'content' => [ [ 'type' => 'text', 'text' => 'Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.' ] ], 'citations' => ['enabled' => true] ] ] ] ] ] ], model: Model::CLAUDE_OPUS_5_5, ); echo json_encode($response, JSON_PRETTY_PRINT); ``` ```ruby Ruby client = Anthropic::Client.new knowledge_base_tool = { name: "search_knowledge_base", description: "Search the company knowledge base for information", input_schema: { type: "object", properties: { query: { type: "string", description: "The search query" } }, required: ["query"] } } # 重播一段以兩種方式提供搜尋結果的對話：第一則 # 使用者訊息攜帶預先擷取的結果，而工具結果則回傳另一個 response = client.messages.create( model: Anthropic::Model::CLAUDE_OPUS_5_5, max_tokens: 1024, tools: [knowledge_base_tool], messages: [ { role: "user", content: [ { type: "search_result", source: "https://docs.company.com/overview", title: "Product Overview", content: [ { type: "text", text: "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards." } ], citations: { enabled: true } }, { type: "text", text: "What does Acme Dashboard do, and what plans is it available on?" } ] }, { role: "assistant", content: [ { type: "text", text: "Let me check the pricing information." }, { type: "tool_use", id: "toolu_01A09q90qw90lq917835lq9", name: "search_knowledge_base", input: { query: "Acme Dashboard pricing plans" } } ] }, { role: "user", content: [ { type: "tool_result", tool_use_id: "toolu_01A09q90qw90lq917835lq9", content: [ { type: "search_result", source: "https://docs.company.com/pricing", title: "Pricing Plans", content: [ { type: "text", text: "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing." } ], citations: { enabled: true } } ] } ] } ] ) puts response ``` 回應引用了兩個來源。預先擷取的結果是 `search_result_index: 0`，而工具回傳的結果是 `search_result_index: 1`，符合 `search_result` 區塊在對話中出現的順序： ```json { "role": "assistant", "content": [ { "type": "text", "text": "Here's what I found about Acme Dashboard:\n\n**What it does:** " }, { "type": "text", "text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.", "citations": [ { "type": "search_result_location", "cited_text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.", "source": "https://docs.company.com/overview", "title": "Product Overview", "search_result_index": 0, "start_block_index": 0, "end_block_index": 1 } ] }, { "type": "text", "text": "\n\n**Available plans:** " }, { "type": "text", "text": "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.", "citations": [ { "type": "search_result_location", "cited_text": "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.", "source": "https://docs.company.com/pricing", "title": "Pricing Plans", "search_result_index": 1, "start_block_index": 0, "end_block_index": 1 } ] } ] } ``` ### 與其他內容類型混合 在使用者訊息中，`search_result` 區塊可以與任何其他內容區塊並存。方法 2 的範例將搜尋結果與 `text` 問題搭配使用，而圖片或文件區塊也可以用相同方式加入。 工具結果則較為嚴格：如果 `tool_result` 內容陣列中有任何區塊是 `search_result`，則其所有區塊都必須是 `search_result`。在同一個工具結果中將搜尋結果與其他區塊類型混合會回傳驗證錯誤。若要在來自工具的搜尋結果旁回傳輔助文字，請將其作為文字區塊包含在其中一個搜尋結果的 `content` 陣列內，如此它也會成為可引用的內容。 ### 快取控制 在搜尋結果區塊上新增 `cache_control`，即可快取它以便在多個請求之間重複使用。它與 `citations` 位於同一個區塊上： ```json { "type": "search_result", "source": "https://docs.company.com/guide", "title": "User Guide", "content": [{ "type": "text", "text": "..." }], "citations": { "enabled": true }, "cache_control": { "type": "ephemeral" } } ``` 如需最小可快取長度和其他要求，請參閱[提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching)。 ### 引用控制 預設情況下，搜尋結果的引用為停用狀態。您可以透過明確設定 `citations` 設定來啟用引用： ```json { "type": "search_result", "source": "https://docs.company.com/guide", "title": "User Guide", "content": [{ "type": "text", "text": "Important documentation..." }], "citations": { "enabled": true // Enable citations for this result } } ``` 當 `citations.enabled` 設定為 `true` 時，Claude 會將引用參照附加到使用該搜尋結果的文字區塊上。 引用是全有或全無的：請求中的所有搜尋結果必須全部啟用引用，或全部停用引用。混合使用具有不同引用設定的搜尋結果會導致錯誤。 ## 最佳實踐 ### 針對基於工具的搜尋（方法 1） * **動態內容：** 用於即時搜尋和動態 RAG 應用程式 * **錯誤處理：** 搜尋失敗時回傳適當的訊息 * **結果限制：** 僅回傳最相關的結果，以避免上下文溢位 ### 針對頂層搜尋（方法 2） * **預先擷取的內容：** 在您已經擁有搜尋結果時使用 * **批次處理：** 用於一次處理多個搜尋結果 * **測試：** 用於以已知內容測試引用行為 ### 一般最佳實踐 1. **有效地組織結果：** * 使用清晰、永久的來源 URL * 提供描述性標題 * 將長內容拆分為合乎邏輯的文字區塊，讓 Claude 有更細緻的引用邊界 2. **保持一致性：** * 在您的應用程式中使用一致的來源格式 * 確保標題準確反映內容 * 保持格式一致 3. **妥善處理錯誤：** 當搜尋失敗或沒有回傳任何結果時，請回傳描述結果的純文字區塊（例如 `{"type": "text", "text": "No results found."}`），而不是引發錯誤：Claude 會向使用者說明空白結果，對話也會繼續進行。 ## 限制 * 搜尋結果中僅支援文字內容（不支援圖片或其他媒體）。 * `search_result` 區塊只能出現在使用者訊息中（包括工具結果內）。包含搜尋結果的助理訊息會被拒絕。 * 當在同一個請求中啟用[網路搜尋工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/web-search-tool)時，所有 `search_result` 區塊都必須啟用引用。 ## 後續步驟 在串流回應中偵測並處理拒絕的停止原因，並在備援模型上重試被拒絕的請求。 讓 Claude 的回應以您的來源文件為依據。引用會回傳支持每項陳述的確切段落，讓您可以驗證答案並向使用者呈現來源。 讓 Claude 存取最新的網路內容，並提供引用來源、選用的動態篩選和網域控制。 查看完整的 Messages API 文件，包括內容區塊類型。 使用 `cache_control` 快取搜尋結果，以降低重複請求的成本和延遲。 ## 可用性 搜尋結果在所有模型上可供使用，且具備零資料保留和HIPAA 就緒資格。 ### API 支援 #### [Messages API](https://platform.claude.com/docs/zh-TW/build-with-claude/working-with-messages) * 可用性：可用 * 用法：在工具結果中或直接在使用者訊息中傳送 `search_result` 區塊。 | 狀態 | 雲端平台 | | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 可用 | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws), [Amazon Bedrock](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (InvokeModel)](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-microsoft-foundry) | #### [Managed Agents](https://platform.claude.com/docs/zh-TW/managed-agents/overview) * 可用性：可用 * 用法：僅在工具結果中接受（例如 `user.custom_tool_result` 事件），不接受於 `user.message` 事件中。 | 狀態 | 雲端平台 | | -- | --------------------------------------------------------------------------------------------------------------------- | | 可用 | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws) | ### 資料處理 [資料處理概覽](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention#feature-eligibility) | 項目 | 零資料保留 | HIPAA | | -- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----- | | 狀態 | 符合資格（不含 [涵蓋的模型](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)） | 符合資格 | 適用端點： * `/v1/messages` 搭配 `search_results` 來源