Claude Web Search

Claude Web Search는 해당 기능을 지원하는 Claude 모델이 답변 시 웹을 검색하고, 프로토콜이 허용하면 검색 결과 블록과 인용을 반환하도록 합니다. 최근 사실, 출처 확인 또는 지정한 사이트 내 검색이 필요한 작업에 적합합니다.

AGTCloud는 Chat 호환 엔드포인트 또는 Anthropic Messages 구조로 Claude 기능을 제공할 수 있습니다. 활성화 필드와 반환 구조가 다르므로 현재 모델 상세 정보에 따라 엔드포인트를 선택합니다.

Chat 호환 엔드포인트에서 검색 활성화

기존 문서에 기록된 AGTCloud의 주요 방식은 Chat 요청에 web_search_options를 추가하는 것입니다:

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "오늘 인공지능 규제와 관련된 주요 소식을 찾아 출처를 나열해 주세요."
      }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'

본문은 일반적으로 Assistant Message에서 읽습니다. 인용이 구조화된 Annotation, 링크 또는 텍스트로 반환되는지는 현재 모델과 엔드포인트에 따라 다릅니다. 응답 근거 없이 인용을 생성해서는 안 됩니다.

Anthropic 네이티브 도구 구조 이해

네이티브 Claude Web Search를 지원하는 Messages 엔드포인트에서는 검색 도구가 tools에 있습니다. 다음은 프로토콜 구조만 설명하며 도구 타입은 현재 모델 문서에 제공된 버전으로 바꿔야 합니다:

{
  "model": "MODEL_ID",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "오늘 인공지능 규제와 관련된 주요 소식을 찾아 출처를 나열해 주세요."
    }
  ],
  "tools": [
    {
      "type": "WEB_SEARCH_TOOL_VERSION",
      "name": "web_search",
      "max_uses": 5
    }
  ]
}

max_uses, 도메인 필터, 사용자 위치 및 동적 필터는 해당 도구 버전이 지원할 때만 사용합니다. 전체 Messages 컨테이너와 Content Block 구조는 Anthropic Messages Reference를 확인합니다.

검색 결과 및 인용 읽기

네이티브 Messages 응답에는 다음 유형의 Content Block이 포함될 수 있습니다:

• server_tool_use: 모델이 서버 측 검색 도구 호출을 시작했음을 나타냅니다.
• web_search_tool_result: 검색 결과 또는 도구 오류를 포함합니다.
• text: 모델이 사용자에게 제공하는 최종 답변입니다.
• citations: 응답이 제공하는 경우 답변 부분과 웹페이지 출처를 연결합니다.

클라이언트는 type별로 분기 처리하며 모든 Content Blocks를 일반 문자열처럼 결합해서는 안 됩니다.

{
  "content": [
    {
      "type": "text",
      "text": "검색 결과에 따르면…",
      "citations": [
        {
          "type": "web_search_result_location",
          "url": "https://example.com/article",
          "title": "출처 제목"
        }
      ]
    }
  ]
}

이 예시는 인용과 텍스트가 같은 응답 구조에 속함을 설명합니다. 실제 필드는 현재 응답과 Messages Reference를 기준으로 합니다.

도메인, 위치 및 동적 필터

도구 버전이 지원하면 다음을 사용할 수 있습니다:

• allowed_domains: 지정한 도메인만 허용합니다.
• blocked_domains: 지정한 도메인을 제외하며 허용 목록과 함께 설정하지 않습니다.
• user_location: 도시, 지역, 국가 및 시간대 등 위치 정보를 제공합니다.
• 동적 필터: 지원되는 도구 조합으로 검색 결과를 추가로 필터링합니다.

이 옵션은 출처 범위에 영향을 주지만 웹페이지 내용의 정확성을 보장하지는 않습니다. 위험도가 높은 업무에서는 출처, 시점 및 여러 자료의 일치 여부를 계속 검증해야 합니다.

검색 도구 오류와 HTTP 오류 구분

검색 도구 실패가 반드시 HTTP 요청 전체의 실패를 의미하지는 않습니다. 네이티브 응답은 성공 상태를 반환하면서도 web_search_tool_result에 오류 객체를 포함할 수 있습니다.

네이티브 검색과 사용자 정의 도구의 차이

Claude Web Search는 모델 또는 서버 측 검색 도구가 실행합니다. 사용자 정의 Tool Calling은 애플리케이션이 자체 검색 서비스를 호출하고 결과를 전달합니다. 인덱스, 접근 권한 또는 내부 데이터를 제어해야 한다면 Tool Calling이 더 적합합니다.

운영 전 확인 사항

• 현재 모델과 프로토콜이 사용하는 Web Search 필드를 명시적으로 지원합니다.
• 도구 타입 버전은 예전 모델 예시가 아닌 현재 문서를 기준으로 합니다.
• Content Block, 검색 결과, 텍스트 및 인용을 각각 해석합니다.
• 도구 오류를 정상 검색 결과로 취급하지 않습니다.
• 도메인과 위치 데이터는 업무에 필요할 때만 보냅니다.
• 검색 콘텐츠가 위험도가 높은 도구를 직접 실행하거나 승인을 우회할 수 없습니다.

Chat 필드는 Chat Completions Reference를 확인하고, 요청이 실패하면 오류 및 문제 해결을 참고합니다.