Claude Web Search

Claude Web Search lets supported Claude models retrieve web information while answering and return search result blocks and citations when the protocol allows it. It is useful for tasks that require recent facts, source verification, or searches restricted to specific sites.

AGTCloud can provide Claude capabilities through a Chat-compatible endpoint or the Anthropic Messages structure. Their enabling fields and response structures differ, so choose the endpoint listed for the current model.

Enable search through the Chat-compatible endpoint

Earlier AGTCloud documentation records the primary path as adding web_search_options to a Chat request:

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": "Find the most important news about AI regulation today and list the sources."
      }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'

The main text is usually read from the Assistant Message. Whether citations are returned as structured annotations, links, or plain text depends on the current model and endpoint. Do not create citations without evidence in the response.

Understand the native Anthropic tool structure

When using a Messages endpoint that supports native Claude Web Search, the search tool appears in tools. The following example shows only the protocol structure; replace the tool type with the version provided by the current model documentation:

{
  "model": "MODEL_ID",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Find the most important news about AI regulation today and list the sources."
    }
  ],
  "tools": [
    {
      "type": "WEB_SEARCH_TOOL_VERSION",
      "name": "web_search",
      "max_uses": 5
    }
  ]
}

Use max_uses, domain filters, user location, and dynamic filtering only when the corresponding tool version supports them. See the Anthropic Messages Reference for the complete Messages container and Content Block structure.

Read search results and citations

A native Messages response can contain several Content Block types:

• server_tool_use: Indicates that the model initiated a server-side search tool call.
• web_search_tool_result: Contains search results or a tool error.
• text: Contains the model's final answer to the user.
• citations: Associates answer segments with web sources when provided in the response.

The client should branch on type instead of concatenating every Content Block as a plain string.

{
  "content": [
    {
      "type": "text",
      "text": "According to the search results...",
      "citations": [
        {
          "type": "web_search_result_location",
          "url": "https://example.com/article",
          "title": "Source title"
        }
      ]
    }
  ]
}

This example shows that citations and text belong to the same response structure. Use the current response and Messages Reference for the actual fields.

Domains, location, and dynamic filtering

When supported by the tool version, you can use:

• allowed_domains: Allow only the specified domains.
• blocked_domains: Exclude specified domains; do not combine it with an allowlist.
• user_location: Provide localized information such as city, region, country, and time zone.
• Dynamic filtering: Let supported tool combinations further filter search results.

These options affect the source scope but cannot guarantee that web content is correct. High-risk use cases should still verify sources, dates, and consistency across multiple sources.

Distinguish search tool errors from HTTP errors

A search tool failure does not necessarily mean that the entire HTTP request failed. A native response can still return a success status while including an error object in web_search_tool_result.

Native search versus custom tools

Claude Web Search is executed by the model or a server-side search tool. Custom Tool Calling is executed by your application through its own search service. When you need control over the index, access permissions, or internal data, Tool Calling is more appropriate.

Pre-production checklist

• The current model and protocol explicitly support the Web Search fields in use.
• The tool type version comes from current documentation rather than an older model example.
• Content Blocks, search results, text, and citations are parsed separately.
• Tool errors are never treated as normal search results.
• Domain and location data is sent only when the business requires it.
• Search content cannot directly trigger high-risk tools or bypass authorization.

See the Chat Completions Reference for Chat fields. If a request fails, see Errors and troubleshooting.