Web Search

Enable real-time web search for grounded responses with current information and citations.

Overview

Web search allows AI models to access real-time information from the internet, providing up-to-date answers with proper citations. Perfect for questions about current events, recent developments, or any information that changes frequently.

❌ Without Web Search

Model can only use training data (potentially outdated)

✅ With Web Search

Model searches the web and provides current information with sources

Quick Start: :online Modifier

The easiest way to enable web search is by adding :online to your model name.

web-search-basic.ts

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://www.superagentstack.com/api/v1',
  apiKey: process.env.OPENROUTER_KEY,
  defaultHeaders: { 'superAgentKey': process.env.SUPER_AGENT_KEY },
});

const response = await client.chat.completions.create({
  model: 'openai/gpt-4o:online',  // Add :online suffix
  messages: [{
    role: 'user',
    content: 'What are the latest developments in quantum computing?'
  }]
});

console.log(response.choices[0].message.content);

// Check for citations in annotations
const message = response.choices[0].message;
if (message.annotations) {
  console.log('\nSources:');
  message.annotations.forEach((annotation, index) => {
    if (annotation.type === 'url_citation') {
      console.log(`${index + 1}. ${annotation.url_citation.title}`);
      console.log(`   ${annotation.url_citation.url}`);
    }
  });
}

Advanced Configuration with Plugins

For more control over web search behavior, use the plugins parameter.

web-search-plugins.ts

const response = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [{
    role: 'user',
    content: 'Find recent research papers about machine learning interpretability'
  }],
  // @ts-expect-error - OpenRouter extension
  plugins: [{
    id: 'web',
    engine: 'exa',           // Use Exa search engine
    max_results: 10,         // Return up to 10 results
    search_prompt: 'machine learning interpretability research papers 2024'
  }],
  web_search_options: {
    search_context_size: 'high'  // Include more context from each result
  }
});

Search Engines

Engine	Description	Best For
`native`	Provider's built-in search	General queries
`exa`	Exa's neural search	Research, technical content

Citations and Annotations

When web search is enabled, responses include annotations with source citations.

handling-citations.ts

const response = await client.chat.completions.create({
  model: 'openai/gpt-4o:online',
  messages: [{ role: 'user', content: 'Latest SpaceX launches' }]
});

const message = response.choices[0].message;
console.log('Response:', message.content);

// Process annotations
if (message.annotations) {
  console.log('\n📚 Sources:');
  
  message.annotations.forEach((annotation, index) => {
    if (annotation.type === 'url_citation') {
      const citation = annotation.url_citation;
      
      console.log(`\n[${index + 1}] ${citation.title}`);
      console.log(`    URL: ${citation.url}`);
      
      // Show which part of the text this citation supports
      if (citation.start_index !== undefined && citation.end_index !== undefined) {
        const citedText = message.content!.slice(
          citation.start_index, 
          citation.end_index
        );
        console.log(`    Supports: "${citedText}"`);
      }
    }
  });
}

Web Search Options

Option	Values	Description
`search_context_size`	low, medium, high	Amount of context from each search result
`max_results`	number	Maximum number of search results to include
`search_prompt`	string	Custom search query (overrides auto-generated)

Combining with Memory & RAG

web-search-memory-rag.ts

import { v4 as uuidv4 } from 'uuid';

const sessionId = uuidv4();

const client = new OpenAI({
  baseURL: 'https://www.superagentstack.com/api/v1',
  apiKey: process.env.OPENROUTER_KEY,
  defaultHeaders: {
    'superAgentKey': process.env.SUPER_AGENT_KEY,
    'sessionId': sessionId,    // Enable memory
  }
});

// First query with web search
const response1 = await client.chat.completions.create({
  model: 'openai/gpt-4o:online',
  messages: [{ role: 'user', content: 'What are the latest AI research trends?' }],
  // @ts-expect-error - Super Agent Stack extension
  useRAG: true  // Also search uploaded documents
});

// Follow-up uses memory + RAG + web search
const response2 = await client.chat.completions.create({
  model: 'openai/gpt-4o:online',
  messages: [{ 
    role: 'user', 
    content: 'How do these trends relate to the research papers I uploaded?' 
  }]
});

// The AI will:
// 1. Remember the previous conversation about AI trends
// 2. Search your uploaded documents (RAG)
// 3. Search the web for additional context
// 4. Provide a comprehensive answer with citations

curl Examples

Basic Web Search

bash

curl -X POST https://www.superagentstack.com/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_KEY" \
  -H "superAgentKey: $SUPER_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o:online",
    "messages": [{"role": "user", "content": "Latest developments in renewable energy"}]
  }'

Advanced Plugin Configuration

bash

curl -X POST https://www.superagentstack.com/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_KEY" \
  -H "superAgentKey: $SUPER_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Find recent ML research papers"}],
    "plugins": [{"id": "web", "engine": "exa", "max_results": 8}],
    "web_search_options": {"search_context_size": "high"}
  }'

Best Practices

Be Specific

More specific queries yield better search results. Instead of "AI news", try "latest GPT-4 research papers December 2024".

Check Citations

Always verify important information by checking the provided citations. Web search results can sometimes be inaccurate.

Cost Awareness

Web search adds cost to your requests. Use it when you need current information, not for general knowledge questions.