Anthropic Web Search (#4906)

Author: colegottdank

bifrost/lib/clients/jawnTypes/private.ts

@@ -1602,6 +1602,13 @@ Json: JsonObject;
       ending_event_id?: string;
       trigger_event_id?: string;
       start_timestamp?: string;
+      annotations?: {
+          content?: string;
+          title: string;
+          url: string;
+          /** @enum {string} */
+          type: "url_citation";
+        }[];
       reasoning?: string;
       deleted?: boolean;
       contentArray?: components["schemas"]["Message"][];

bifrost/lib/clients/jawnTypes/public.ts

@@ -1588,6 +1588,13 @@ export interface components {
       ending_event_id?: string;
       trigger_event_id?: string;
       start_timestamp?: string;
+      annotations?: {
+          content?: string;
+          title: string;
+          url: string;
+          /** @enum {string} */
+          type: "url_citation";
+        }[];
       reasoning?: string;
       deleted?: boolean;
       contentArray?: components["schemas"]["Message"][];
@@ -2960,6 +2967,8 @@ Json: JsonObject;
     AuthorName: "anthropic" | "openai" | "perplexity" | "deepseek" | "cohere" | "xai" | "google" | "meta-llama" | "mistralai" | "amazon" | "microsoft" | "nvidia" | "qwen" | "moonshotai" | "alibaba" | "passthrough";
     /** @enum {string} */
     StandardParameter: "max_tokens" | "max_completion_tokens" | "temperature" | "top_p" | "top_k" | "stop" | "stream" | "frequency_penalty" | "presence_penalty" | "repetition_penalty" | "seed" | "tools" | "tool_choice" | "functions" | "function_call" | "reasoning" | "include_reasoning" | "thinking" | "response_format" | "json_mode" | "truncate" | "min_p" | "logit_bias" | "logprobs" | "top_logprobs" | "structured_outputs" | "verbosity";
+    /** @enum {string} */
+    PluginId: "web";
     RateLimits: {
       /** Format: double */
       rpm?: number;
@@ -3040,6 +3049,7 @@ Json: JsonObject;
       provider: components["schemas"]["ModelProviderName"];
       author: components["schemas"]["AuthorName"];
       supportedParameters: components["schemas"]["StandardParameter"][];
+      supportedPlugins?: components["schemas"]["PluginId"][];
       rateLimits?: components["schemas"]["RateLimits"];
       endpointConfigs: components["schemas"]["Record_string.EndpointConfig_"];
       crossRegion?: boolean;

docs/docs.json

@@ -27,6 +27,7 @@
             "pages": [
               "gateway/overview",
               "gateway/provider-routing",
+
               {
                 "group": "Features",
                 "pages": [
@@ -40,7 +41,10 @@
               },
               {
                 "group": "Concepts",
-                "pages": ["gateway/concepts/prompt-caching"]
+                "pages": [
+                  "gateway/concepts/prompt-caching",
+                  "gateway/web-search"
+                ]
               }
             ]
           },

docs/gateway/web-search.mdx

@@ -0,0 +1,189 @@
+---
+title: "Web Search with Helicone Gateway"
+description: "Enable web search capabilities for Anthropic models through Helicone's Gateway using the :online suffix"
+---
+
+# Web Search Overview
+
+Helicone Gateway supports web search for Anthropic models, allowing Claude to search the internet and provide up-to-date information with citations. This feature is enabled by appending `:online` to the model name, following the same pattern as OpenRouter.
+
+## How it Works
+
+When you append `:online` to an Anthropic model name (e.g., `claude-3-5-sonnet-20241022:online`), Helicone automatically:
+
+1. Enables the web search tool for the request
+2. Routes the request to Anthropic with the appropriate web search configuration
+3. Returns the response with citations formatted as annotations
+
+## Quick Start
+
+<Tabs>
+  <Tab title="Python">
+    ```python
+    import openai
+
+    client = openai.OpenAI(
+        api_key="YOUR_ANTHROPIC_API_KEY",
+        base_url="https://gateway.helicone.ai/v1",
+        default_headers={
+            "Helicone-Auth": "Bearer YOUR_HELICONE_API_KEY",
+            "Helicone-Target-Url": "https://api.anthropic.com",
+        }
+    )
+
+    response = client.chat.completions.create(
+        model="claude-3-5-sonnet-20241022:online",  # Note the :online suffix
+        messages=[
+            {"role": "user", "content": "What are the latest developments in AI?"}
+        ]
+    )
+
+    # Access citations if available
+    if response.choices[0].message.annotations:
+        for annotation in response.choices[0].message.annotations:
+            print(f"Source: {annotation['url_citation']['title']}")
+            print(f"URL: {annotation['url_citation']['url']}")
+    ```
+  </Tab>
+
+  <Tab title="Node.js">
+    ```javascript
+    import OpenAI from 'openai';
+
+    const openai = new OpenAI({
+      apiKey: 'YOUR_ANTHROPIC_API_KEY',
+      baseURL: 'https://gateway.helicone.ai/v1',
+      defaultHeaders: {
+        'Helicone-Auth': 'Bearer YOUR_HELICONE_API_KEY',
+        'Helicone-Target-Url': 'https://api.anthropic.com',
+      }
+    });
+
+    const response = await openai.chat.completions.create({
+      model: 'claude-3-5-sonnet-20241022:online',  // Note the :online suffix
+      messages: [
+        { role: 'user', content: 'What are the latest developments in AI?' }
+      ]
+    });
+
+    // Access citations if available
+    if (response.choices[0].message.annotations) {
+      response.choices[0].message.annotations.forEach(annotation => {
+        console.log(`Source: ${annotation.url_citation.title}`);
+        console.log(`URL: ${annotation.url_citation.url}`);
+      });
+    }
+    ```
+  </Tab>
+
+  <Tab title="cURL">
+    ```bash
+    curl https://gateway.helicone.ai/v1/chat/completions \
+      -H "Content-Type: application/json" \
+      -H "Authorization: Bearer YOUR_ANTHROPIC_API_KEY" \
+      -H "Helicone-Auth: Bearer YOUR_HELICONE_API_KEY" \
+      -H "Helicone-Target-Url: https://api.anthropic.com" \
+      -d '{
+        "model": "claude-3-5-sonnet-20241022:online",
+        "messages": [
+          {
+            "role": "user",
+            "content": "What are the latest developments in AI?"
+          }
+        ]
+      }'
+    ```
+  </Tab>
+</Tabs>
+
+## Advanced Configuration
+
+You can customize the web search behavior by including a `plugins` parameter in your request body:
+
+```json
+{
+  "model": "claude-3-5-sonnet-20241022:online",
+  "messages": [...],
+  "plugins": [
+    {
+      "id": "web",
+      "max_uses": 5,
+      "allowed_domains": ["wikipedia.org", "arxiv.org"],
+      "blocked_domains": ["example.com"],
+      "user_location": {
+        "type": "approximate",
+        "country": "US"
+      }
+    }
+  ]
+}
+```
+
+### Plugin Options
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `max_uses` | integer | Maximum number of web searches allowed per request (default: unlimited) |
+| `allowed_domains` | array | Restrict searches to specific domains |
+| `blocked_domains` | array | Exclude specific domains from search results |
+| `user_location` | object | Provide approximate user location for localized results |
+
+## Response Format
+
+When web search is used, the response includes annotations with citation information:
+
+```json
+{
+  "choices": [
+    {
+      "message": {
+        "role": "assistant",
+        "content": "Based on recent developments, AI has made significant progress in...",
+        "annotations": [
+          {
+            "type": "url_citation",
+            "url_citation": {
+              "url": "https://example.com/article",
+              "title": "Recent AI Breakthroughs",
+              "content": "The source text that was cited...",
+              "start_index": 0,
+              "end_index": 67
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### Understanding Annotations
+
+- **`url`**: The source URL of the cited information
+- **`title`**: The title of the source page
+- **`content`**: The relevant excerpt from the source
+- **`start_index`**: Character position where the citation begins in the response
+- **`end_index`**: Character position where the citation ends in the response
+
+## Pricing
+
+Web search requests are billed at standard Anthropic rates plus any additional costs for web search usage. The usage statistics include:
+
+```json
+{
+  "usage": {
+    "input_tokens": 1000,
+    "output_tokens": 500,
+    "server_tool_use": {
+      "web_search_requests": 1
+    }
+  }
+}
+```
+
+## Related Features
+
+- [Gateway Integration](/getting-started/integration-method/gateway)
+- [Gateway Fallbacks](/getting-started/integration-method/gateway-fallbacks)
+- [Caching](/features/advanced-usage/caching)
+- [Custom Headers](/helicone-headers/helicone-auth)

docs/swagger.json

@@ -3311,6 +3311,35 @@
 					"start_timestamp": {
 						"type": "string"
 					},
+					"annotations": {
+						"items": {
+							"properties": {
+								"content": {
+									"type": "string"
+								},
+								"title": {
+									"type": "string"
+								},
+								"url": {
+									"type": "string"
+								},
+								"type": {
+									"type": "string",
+									"enum": [
+										"url_citation"
+									],
+									"nullable": false
+								}
+							},
+							"required": [
+								"title",
+								"url",
+								"type"
+							],
+							"type": "object"
+						},
+						"type": "array"
+					},
 					"reasoning": {
 						"type": "string"
 					},
@@ -8158,6 +8187,13 @@
 					"verbosity"
 				]
 			},
+			"PluginId": {
+				"type": "string",
+				"enum": [
+					"web"
+				],
+				"nullable": false
+			},
 			"RateLimits": {
 				"properties": {
 					"rpm": {
@@ -8369,6 +8405,12 @@
 						},
 						"type": "array"
 					},
+					"supportedPlugins": {
+						"items": {
+							"$ref": "#/components/schemas/PluginId"
+						},
+						"type": "array"
+					},
 					"rateLimits": {
 						"$ref": "#/components/schemas/RateLimits"
 					},