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

# Web Search Tool

> WebSearchTool reference: add real-time web search to your agents using OpenAI's built-in search capability — no extra API keys required.

The `WebSearchTool` provides web search functionality through OpenAI's agents library. It's a built-in tool that doesn't require additional API keys.

## Class Signature

```python theme={null} theme={null}
from agents import WebSearchTool

class WebSearchTool:
    def __init__()
```

## Overview

The `WebSearchTool` is imported from the `agents` package (part of `openai-agents` SDK) and provides web search capabilities to Agentor agents. It integrates seamlessly with OpenAI's agent framework.

## Usage Example

```python theme={null} theme={null}
from agentor import Agentor
from agentor.tools import WebSearchTool

# Create an agent with web search capability
agent = Agentor(
    name="Web Search Agent",
    model="gpt-4",
    tools=[WebSearchTool()],
    instructions="Use web search when up-to-date information is requested.",
)

# Search for current information
result = agent.run("What are the latest developments in AI?")
print(result.final_output)
```

## Advanced Example

```python theme={null} theme={null}
from agentor import Agentor
from agentor.tools import WebSearchTool

agent = Agentor(
    name="Research Assistant",
    model="gpt-4",
    tools=[WebSearchTool()],
    instructions="""
    You are a research assistant that helps find accurate, 
    up-to-date information. Always cite sources and verify 
    information across multiple search results.
    """,
)

result = agent.run(
    "Find 3 recent updates about Model Context Protocol and summarize each."
)
print(result.final_output)
```

## Features

* **No API Key Required**: Uses OpenAI's built-in search capability
* **Real-time Information**: Access to current web content
* **Automatic Integration**: Works seamlessly with OpenAI's agent framework
* **Source Attribution**: Results typically include source information

## When to Use

Use `WebSearchTool` when you need:

* Current news and events
* Recent updates on specific topics
* Real-time data (stock prices, weather, etc.)
* Information not in the model's training data
* Verification of facts and claims

## Alternative: ExaSearchTool

For more control over web search, consider using `ExaSearchTool` which provides:

* Custom search parameters
* Number of results control
* Direct API access to Exa search engine

<Info>
  Exa tool docs are not yet published in this docs set.
</Info>

## Requirements

```bash theme={null} theme={null}
# WebSearchTool is available through openai-agents (included in Agentor)
pip install agentor

# Set your OpenAI API key
export OPENAI_API_KEY="your_openai_api_key"
```

## Environment Setup

```bash theme={null} theme={null}
# Required environment variable
export OPENAI_API_KEY="sk-..."
```

## Integration with Multiple Tools

```python theme={null} theme={null}
from agentor import Agentor
from agentor.tools import WebSearchTool, CalculatorTool, GetWeatherTool

agent = Agentor(
    name="Multi-Tool Assistant",
    model="gpt-4",
    tools=[
        WebSearchTool(),
        CalculatorTool(),
        GetWeatherTool(),
    ],
    instructions="""
    Use the most appropriate tool for each task:
    - Web search for current information
    - Calculator for numerical computations
    - Weather tool for weather data
    """,
)

result = agent.run(
    "Search for the current price of gold, then calculate 10 ounces worth."
)
print(result.final_output)
```

## Best Practices

1. **Clear Instructions**: Provide clear guidelines on when to use web search
2. **Source Verification**: Instruct agents to verify information across multiple sources
3. **Recency Awareness**: Use for time-sensitive queries
4. **Fallback Strategy**: Combine with other tools for comprehensive capabilities
5. **Rate Limiting**: Be mindful of search frequency in production environments

## Limitations

* Requires active internet connection
* Search results depend on OpenAI's search backend
* May have rate limits based on your OpenAI plan
* Search scope and freshness depend on the underlying service

Source: `/home/daytona/workspace/source/src/agentor/tools/__init__.py:1`