--- title: 搜尋結果 url: https://platform.claude.com/docs/zh-TW/build-with-claude/search-results description: 透過提供附帶來源歸屬的搜尋結果，為 RAG 應用程式啟用自然的引用功能 --- 若要了解「zero data retention」（零資料保留），即 ZDR 如何適用於此功能，請參閱 [API 與資料保留](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention)。 搜尋結果內容區塊讓 Claude 能夠以引用網頁搜尋結果的相同方式引用您自己的內容：每個引用都帶有您所提供的來源與標題。請在「Retrieval-Augmented Generation」（檢索增強生成），即 RAG 應用程式中使用它們，讓 Claude 能將答案歸屬於您的文件。 所有[現行模型](https://platform.claude.com/docs/zh-TW/models/overview)皆支援附帶引用的搜尋結果，Claude Haiku 3 除外。不需要 beta 標頭：搜尋結果是標準 Messages API 的一部分。 ## 運作方式 搜尋結果可以透過兩種方式提供： 1. **來自工具呼叫：** 您的自訂工具回傳搜尋結果，實現動態 RAG 應用程式 2. **作為頂層內容：** 您直接在使用者訊息中提供搜尋結果，用於預先擷取或已快取的內容 在這兩種情況下，只要啟用引用，Claude 就會自動引用搜尋結果。不需要特殊的提示：提出您的問題，引用便會出現在取材自您內容的文字區塊上。 ### 搜尋結果結構描述 搜尋結果使用以下結構： ```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 = [ 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"}, 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(MessageParam(role="assistant", content=response.content)) messages.append( MessageParam( 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" }, messages }); // 處理工具使用並提供結果。 // tool_use 區塊不一定在最前面：請在 content 陣列中尋找它。 const toolUse = response.content.find( (block): block is Anthropic.ToolUseBlock => 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() { Role = Role.User, 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" }, Messages = messages, }); // 當 Claude 呼叫工具時，提供搜尋結果。 // 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() { Role = Role.Assistant, Content = response.Content.Select(contentBlock => new ContentBlockParam(contentBlock.Json)).ToList() }); messages.Add(new() { Role = Role.User, Content = new MessageParamContent( [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"}}, 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.builder() .role(MessageParam.Role.USER) .content("How do I configure the timeout settings?") .build()); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5) .maxTokens(1024L) .addTool(knowledgeBaseTool) .toolChoice(ToolChoice.ofTool(ToolChoiceTool.builder() .name("search_knowledge_base") .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(MessageParam.builder() .role(MessageParam.Role.ASSISTANT) .contentOfBlockParams( response.content().stream() .map(block -> block.toParam()) .toList() ) .build()); messages.add(MessageParam.builder() .role(MessageParam.Role.USER) .contentOfBlockParams(List.of( ContentBlockParam.ofToolResult( ToolResultBlockParam.builder() .toolUseId(toolUse.id()) .contentOfBlocks(toolResult) .build() ) )) .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'], 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" }, 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: 2023-06-01" \ -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 MessageParam, TextBlockParam, SearchResultBlockParam client = Anthropic() # 直接在使用者訊息中提供搜尋結果 response = client.messages.create( model="claude-opus-5-5", max_tokens=1024, messages=[ MessageParam( 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() { Role = Role.User, Content = new MessageParamContent( [ 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) .addUserMessageOfBlockParams(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: 'claude-opus-5-5', ); echo json_encode($message, JSON_PRETTY_PRINT); ``` ```ruby Ruby client = Anthropic::Client.new message = client.messages.create( 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: 2023-06-01" \ -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 ( MessageParam, 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=[ MessageParam( 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?", ), ], ), MessageParam( 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"}, ), ], ), MessageParam( 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"] } }; // 重播一段以兩種方式提供搜尋結果的對話：第一則 // 使用者訊息附帶預先擷取的結果，工具結果則回傳另一個 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() { Role = Role.User, Content = new MessageParamContent( [ 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() { Role = Role.Assistant, Content = new MessageParamContent( [ 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() { Role = Role.User, Content = new MessageParamContent( [ 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"}, }, }, } // 重播一段以兩種方式提供搜尋結果的對話：第一則 // 使用者訊息附帶預先擷取的結果，工具結果則回傳另一個 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) .addUserMessageOfBlockParams(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()) )) .addAssistantMessageOfBlockParams(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()) )) .addUserMessageOfBlockParams(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'] ] ]; // 重播一段以兩種方式提供搜尋結果的對話：第一則 // 使用者訊息附帶預先擷取的結果，tool result（工具結果）則回傳另一個 $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: '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: "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 會向使用者說明空結果，對話得以繼續。 ## 限制 * 搜尋結果內容區塊可在 Claude API、Amazon Bedrock 及 Google Cloud 上使用。 * 搜尋結果內僅支援文字內容（不支援圖片或其他媒體）。 * `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` 快取搜尋結果，以降低重複請求的成本與延遲。