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

# Search Providers

> Pick a web-search backend (DuckDuckGo, Tavily, Serper) for your agent — or plug in your own

Pick a web-search backend (DuckDuckGo, Tavily, Serper) for your agent — or plug in your own.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Researcher",
    instructions="Search the web and summarise findings.",
    web=True,
)
agent.start("Latest news on renewable energy")
```

The user enables `web=True`; PraisonAI routes searches through DuckDuckGo, Tavily, Serper, or a custom provider.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    A[Agent] --> B[SearchProviderRegistry]
    B --> C{DuckDuckGo / Tavily / Serper}
    C --> D[Search results]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef registry fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef provider fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class A agent
    class B registry
    class C provider
    class D output
```

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as Search Providers

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result    Agent-->>User: Response
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    Give your agent web search with the default DuckDuckGo provider:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="Researcher",
        instructions="Search the web and summarise findings.",
        web=True,
    )
    agent.start("Latest news on renewable energy")
    ```
  </Step>

  <Step title="Switch providers via config">
    Select Tavily or Serper from the CLI or bot config:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai bot run telegram --web-search --web-provider tavily
    ```

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="Researcher",
        instructions="Use Tavily for deep web search.",
        web=True,
    )
    # Set WEB_SEARCH_PROVIDER=tavily in the environment, or pass via bot YAML
    ```
  </Step>

  <Step title="Register a custom search provider">
    Distribute a custom provider as a pip plugin:

    ```toml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # pyproject.toml
    [project.entry-points."praisonai.tools.search"]
    my-search = "my_pkg.tools:MySearchTool"
    ```

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonai.cli.features._search_registry import SearchProviderRegistry

    registry = SearchProviderRegistry.default()
    tool_cls = registry.resolve("my-search")
    tool = tool_cls()
    ```
  </Step>
</Steps>

***

## Built-in Providers

| Provider     | API key needed?        | Free tier | Best for                           |
| ------------ | ---------------------- | --------- | ---------------------------------- |
| `duckduckgo` | No                     | Yes       | Default, no setup, general queries |
| `tavily`     | Yes (`TAVILY_API_KEY`) | Limited   | Research-grade results, citations  |
| `serper`     | Yes (`SERPER_API_KEY`) | Limited   | Google SERP-style results          |

Entry-point group: `praisonai.tools.search`

***

## Which Provider Should I Pick?

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    A[Need web search?] --> B{Have an API key?}
    B -->|No| C[duckduckgo]
    B -->|Yes| D{Need citations / research?}
    D -->|Yes| E[tavily]
    D -->|No, SERP-style| F[serper]

    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef choice fill:#10B981,stroke:#7C90A0,color:#fff

    class A,B,D decision
    class C,E,F choice
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Store API keys in the environment">
    Set `TAVILY_API_KEY` or `SERPER_API_KEY` in your shell or deployment secrets — never hard-code keys in agent instructions.

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    export TAVILY_API_KEY=tvly-...
    praisonai bot run telegram --web-search --web-provider tavily
    ```
  </Accordion>

  <Accordion title="Fall back to DuckDuckGo">
    The registry falls back to `duckduckgo` when an unknown provider name is requested — useful for resilient bot configs.
  </Accordion>

  <Accordion title="Cache repeated queries">
    For high-volume agents, cache search results in Redis or session memory to avoid rate limits on paid providers.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Tool Search" icon="magnifying-glass" href="/docs/features/tool-search">
    Progressive disclosure when agents have many MCP tools
  </Card>

  <Card title="Endpoint Provider Registry" icon="plug" href="/docs/features/endpoint-provider-registry">
    Plug custom endpoint types into serve / discovery
  </Card>
</CardGroup>