> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Search

> Give your agents the ability to search the internet for real-time information

**Web Search** lets your agents search the internet for up-to-date information. It works as both a **programmatic function** and an **agent tool** that the LLM can invoke automatically.

## Supported Providers

| Provider   | Strengths                                    | Free Tier       |
| ---------- | -------------------------------------------- | --------------- |
| **Tavily** | AI-native, returns clean content + AI answer | 1,000 req/month |
| **Exa**    | Semantic/neural search, find similar pages   | 1,000 req/month |
| **Serper** | Real Google results, very affordable         | 2,500 credits   |

## Quick Start: Agent with Search

The simplest way to give your agent search capabilities:

```typescript theme={null}
import { Agent, openai, createWebSearchTool } from '@runflow-ai/sdk';

const agent = new Agent({
  name: 'Research Agent',
  instructions: 'You help users research topics using the internet.',
  model: openai('gpt-4o'),
  tools: {
    search: createWebSearchTool({
      provider: 'tavily',
      apiKey: process.env.TAVILY_API_KEY,
    }),
  },
});

const result = await agent.process({
  message: 'What are the latest developments in AI agents?',
});
```

The agent will automatically decide when to search the internet based on the user's question.

## Programmatic Search

Use `webSearch()` directly in your code, workflows, or custom tools:

```typescript theme={null}
import { webSearch } from '@runflow-ai/sdk';

const results = await webSearch('Runflow AI platform', {
  provider: 'tavily',
  apiKey: process.env.TAVILY_API_KEY,
  maxResults: 5,
  searchDepth: 'advanced',
});

console.log(results.answer);   // AI-generated answer (Tavily)
console.log(results.results);  // Array of WebSearchResult
```

### Response Format

```typescript theme={null}
{
  query: "Runflow AI platform",
  answer: "Runflow is an AI agent platform...",  // Tavily only
  results: [
    {
      title: "Runflow - Build AI Agents",
      url: "https://runflow.ai",
      snippet: "Platform for building and deploying AI agents...",
      content: "Full page content...",  // When includeContent is true
      score: 0.95,
      publishedDate: "2026-03-01"
    }
  ]
}
```

## Two Modes: Standalone and Platform

### Standalone Mode (API key in code)

Pass the API key directly. No platform connection needed:

```typescript theme={null}
createWebSearchTool({
  provider: 'tavily',
  apiKey: 'tvly-your-key',
})
```

### Platform Mode (credential managed in portal)

Configure the search provider credential in the Runflow portal (Connectors > Search category), then use without an API key:

```typescript theme={null}
createWebSearchTool({
  provider: 'tavily',
  connector: 'tavily-default',  // Connector instance slug
})
```

The platform manages the API key securely via the connector credential system.

## Provider Examples

### Tavily (recommended for AI agents)

```typescript theme={null}
const results = await webSearch('latest news about AI', {
  provider: 'tavily',
  apiKey: process.env.TAVILY_API_KEY,
  maxResults: 5,
  searchDepth: 'basic',     // 'basic' or 'advanced'
  includeContent: false,    // Include full page content
});
```

### Exa (semantic search)

```typescript theme={null}
const results = await webSearch('articles about building AI agents', {
  provider: 'exa',
  apiKey: process.env.EXA_API_KEY,
  maxResults: 5,
});
```

Exa uses neural search — describe what you're looking for in natural language for best results.

### Serper (Google results)

```typescript theme={null}
const results = await webSearch('Runflow AI', {
  provider: 'serper',
  apiKey: process.env.SERPER_API_KEY,
  maxResults: 5,
});
```

## Configuration Options

| Parameter        | Type                            | Default    | Description                             |
| ---------------- | ------------------------------- | ---------- | --------------------------------------- |
| `provider`       | `'tavily' \| 'exa' \| 'serper'` | `'tavily'` | Search provider                         |
| `apiKey`         | `string`                        | —          | Provider API key (standalone mode)      |
| `connector`      | `string`                        | —          | Connector instance slug (platform mode) |
| `maxResults`     | `number`                        | `5`        | Maximum number of results               |
| `searchDepth`    | `'basic' \| 'advanced'`         | `'basic'`  | Search depth (Tavily only)              |
| `includeContent` | `boolean`                       | `false`    | Include full page content in results    |

## Using in Workflows

```typescript theme={null}
import { flow, webSearch } from '@runflow-ai/sdk';

const researchFlow = flow('research')
  .step('search', async ({ input }) => {
    const results = await webSearch(input.query, {
      provider: 'tavily',
      apiKey: process.env.TAVILY_API_KEY,
    });
    return { results: results.results };
  })
  .step('summarize', {
    agent: summaryAgent,
    prompt: ({ results }) =>
      `Summarize these search results:\n${JSON.stringify(results.search.results)}`,
  })
  .build();
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Schedule" icon="clock" href="/core-concepts/schedule">
    Create scheduled executions programmatically
  </Card>

  <Card title="Tools" icon="wrench" href="/core-concepts/tools">
    Create custom tools for agents
  </Card>
</CardGroup>