--- title: 검색 결과 url: https://platform.claude.com/docs/ko/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-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/ko/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` boolean 필드가 있는 인용 구성입니다. 인용은 기본적으로 비활성화되어 있으며, 이 페이지의 모든 예제는 `"enabled": true`를 명시적으로 설정합니다. 요청 내의 모든 검색 결과는 동일한 설정을 사용해야 합니다([인용 제어](https://platform.claude.com/docs/ko/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/ko/agents-and-tools/tool-use/define-tools#forcing-tool-use)로 도구 호출을 강제하므로 검색 단계가 매번 실행됩니다. ### 예제: 지식 베이스 도구 도구 호출 흐름에는 애플리케이션 내의 검색 로직이 필요하며, 이는 단일 셸 명령 이상을 필요로 합니다. 전체 흐름에는 Claude SDK를 사용하세요. 검색 결과가 포함된 도구 대화의 원시 요청 형태는 [두 방법 결합하기](https://platform.claude.com/docs/ko/build-with-claude/search-results#combining-both-methods)를 참조하세요. 사용자 메시지에 검색 결과를 직접 제공하려면 [방법 2: 최상위 콘텐츠로서의 검색 결과](https://platform.claude.com/docs/ko/build-with-claude/search-results#method-2-search-results-as-top-level-content)를 참조하세요. 도구 호출 흐름에는 애플리케이션 내의 검색 로직이 필요하며, 이는 단일 셸 명령 이상을 필요로 합니다. 전체 흐름에는 Claude SDK를 사용하세요. 검색 결과가 포함된 도구 대화의 원시 요청 형태는 [두 방법 결합하기](https://platform.claude.com/docs/ko/build-with-claude/search-results#combining-both-methods)를 참조하세요. 사용자 메시지에 검색 결과를 직접 제공하려면 [방법 2: 최상위 콘텐츠로서의 검색 결과](https://platform.claude.com/docs/ko/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"}, }, }, } // 사용자의 질문부터 시작하여 슬라이스에 대화를 구성합니다 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]`의 내용을 합친 것과 같습니다. 출력 토큰에 포함되지 않습니다. | | `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/ko/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/ko/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"] } }; // 검색 결과를 두 가지 방식으로 제공하는 대화를 재현합니다: 첫 번째 // 사용자 메시지는 미리 가져온 결과를 담고, 도구 결과는 또 다른 결과를 반환합니다 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"}, }, }, } // 검색 결과를 두 방식으로 제공하는 대화를 재현합니다: 첫 번째 // 사용자 메시지는 미리 가져온 결과를 담고, 도구 결과는 또 다른 결과를 반환합니다 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(); // 검색 결과를 두 가지 방식으로 모두 제공하는 대화를 재현합니다: 첫 번째 // user 메시지는 미리 가져온 결과를 담고, 도구 결과는 또 다른 결과를 반환합니다 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/ko/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/ko/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/ko/build-with-claude/working-with-messages) * 제공 여부: 사용 가능 * 사용법: 도구 결과 또는 사용자 메시지에 직접 `search_result` 블록을 보내세요. | 상태 | 클라우드 플랫폼 | | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 사용 가능 | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws), [Amazon Bedrock](https://platform.claude.com/docs/ko/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (InvokeModel)](https://platform.claude.com/docs/ko/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/ko/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry) | #### [Managed Agents](https://platform.claude.com/docs/ko/managed-agents/overview) * 제공 여부: 사용 가능 * 사용법: `user.custom_tool_result` 이벤트와 같은 도구 결과에서만 허용되며, `user.message` 이벤트에서는 허용되지 않습니다. | 상태 | 클라우드 플랫폼 | | ----- | ------------------------------------------------------------------------------------------------------------------ | | 사용 가능 | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws) | ### 데이터 처리 [데이터 처리 개요](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention#feature-eligibility) | 항목 | 제로 데이터 보존 | HIPAA | | -- | ----------------------------------------------------------------------------------------------------------------------------------- | ----- | | 상태 | 적격([적용 모델](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention#model-specific-data-retention-requirements) 제외) | 적격 | 적용 엔드포인트: * `/v1/messages` `search_results` 소스 사용 시