Web Search

Search the internet in real-time with AI-powered search

The web_search tool enables Letta agents to search the internet for current information, research, and general knowledge using Exa’s AI-powered search engine.

On Letta Cloud, this tool works out of the box. For self-hosted deployments, you’ll need to configure an Exa API key.

Quick Start

Adding Web Search to an Agent

1from letta import Letta
2
3client = Letta(token="LETTA_API_KEY")
4
5agent = client.agents.create(
6 model="openai/gpt-4o",
7 embedding="openai/text-embedding-3-small",
8 tools=["web_search"],
9 memory_blocks=[
10 {
11 "label": "persona",
12 "value": "I'm a research assistant who uses web search to find current information and cite sources."
13 }
14 ]
15)

Usage Example

1response = client.agents.messages.create(
2 agent_id=agent.id,
3 messages=[
4 {
5 "role": "user",
6 "content": "What are the latest developments in agent-based AI systems?"
7 }
8 ]
9)

Your agent can now choose to use web_search when it needs current information.

Self-Hosted Setup

For self-hosted Letta servers, you’ll need an Exa API key.

Get an API Key

  1. Sign up at dashboard.exa.ai
  2. Copy your API key
  3. See Exa pricing for rate limits and costs

Configuration Options

$docker run \
> -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \
> -p 8283:8283 \
> -e OPENAI_API_KEY="your_openai_key" \
> -e EXA_API_KEY="your_exa_api_key" \
> letta/letta:latest

Tool Parameters

The web_search tool supports advanced filtering and search customization:

ParameterTypeDefaultDescription
querystrRequiredThe search query to find relevant web content
num_resultsint10Number of results to return (1-100)
categorystrNoneFocus search on specific content types (see below)
include_textboolFalseWhether to retrieve full page content (usually overflows context)
include_domainsList[str]NoneList of domains to include in search results
exclude_domainsList[str]NoneList of domains to exclude from search results
start_published_datestrNoneOnly return content published after this date (ISO format)
end_published_datestrNoneOnly return content published before this date (ISO format)
user_locationstrNoneTwo-letter country code for localized results (e.g., “US”)

Available Categories

Use the category parameter to focus your search on specific content types:

CategoryBest ForExample Query
companyCorporate information, company websites”Tesla energy storage solutions”
research paperAcademic papers, arXiv, research publications”transformer architecture improvements 2025”
newsNews articles, current events”latest AI policy developments”
pdfPDF documents, reports, whitepapers”climate change impact assessment”
githubGitHub repositories, open source projects”python async web scraping libraries”
tweetTwitter/X posts, social media discussions”reactions to new GPT release”
personal siteBlogs, personal websites, portfolios”machine learning tutorial blogs”
linkedin profileLinkedIn profiles, professional bios”AI research engineers at Google”
financial reportEarnings reports, financial statements”Apple Q4 2024 earnings”

Return Format

The tool returns a JSON-encoded string containing:

1{
2 "query": "search query",
3 "results": [
4 {
5 "title": "Page title",
6 "url": "https://example.com",
7 "published_date": "2025-01-15",
8 "author": "Author name",
9 "highlights": ["Key excerpt 1", "Key excerpt 2"],
10 "summary": "AI-generated summary of the content",
11 "text": "Full page content (only if include_text=true)"
12 }
13 ]
14}

Best Practices

Provide clear instructions to your agent about when web search is appropriate:

1memory_blocks=[
2 {
3 "label": "persona",
4 "value": "I'm a helpful assistant. I use web_search for current events, recent news, and topics requiring up-to-date information. I cite my sources."
5 }
6]

2. Combine with Archival Memory

Use web search for external/current information, and archival memory for your organization’s internal data:

1# Create agent with both web_search and archival memory tools
2agent = client.agents.create(
3 model="openai/gpt-4o",
4 embedding="openai/text-embedding-3-small",
5 tools=["web_search", "archival_memory_search", "archival_memory_insert"],
6 memory_blocks=[
7 {
8 "label": "persona",
9 "value": "I use web_search for current events and external research. I use archival_memory_search for company-specific information and internal documents."
10 }
11 ]
12)

See the Archival Memory documentation for more information.

3. Craft Effective Search Queries

Exa uses neural search that understands semantic meaning. Your agent will generally form good queries naturally, but you can improve results by guiding it to:

  • Be descriptive and specific: “Latest research on RLHF techniques for language models” is better than “RLHF research”
  • Focus on topics, not keywords: “How companies are deploying AI agents in customer service” works better than “AI agents customer service deployment”
  • Use natural language: The search engine understands conversational queries like “What are the environmental impacts of Bitcoin mining?”
  • Specify time ranges when relevant: Guide your agent to use date filters for time-sensitive queries

Example instruction in memory:

1memory_blocks=[
2 {
3 "label": "search_strategy",
4 "value": "When searching, I craft clear, descriptive queries that focus on topics rather than keywords. I use the category and date filters when appropriate to narrow results."
5 }
6]

4. Manage Context Window

By default, include_text is False to avoid context overflow. The tool returns highlights and AI-generated summaries instead, which are more concise:

1memory_blocks=[
2 {
3 "label": "search_guidelines",
4 "value": "I avoid setting include_text=true unless specifically needed, as full text usually overflows the context window. Highlights and summaries are usually sufficient."
5 }
6]

Common Patterns

Research Assistant

1agent = client.agents.create(
2 model="openai/gpt-4o",
3 tools=["web_search"],
4 memory_blocks=[
5 {
6 "label": "persona",
7 "value": "I'm a research assistant. I search for relevant information, synthesize findings from multiple sources, and provide citations."
8 }
9 ]
10)

News Monitor

1agent = client.agents.create(
2 model="openai/gpt-4o-mini",
3 tools=["web_search"],
4 memory_blocks=[
5 {
6 "label": "persona",
7 "value": "I monitor news and provide briefings on AI industry developments."
8 },
9 {
10 "label": "topics",
11 "value": "Focus: AI/ML, agent systems, LLM advancements"
12 }
13 ]
14)

Customer Support

1agent = client.agents.create(
2 model="openai/gpt-4o",
3 tools=["web_search"],
4 memory_blocks=[
5 {
6 "label": "persona",
7 "value": "I help customers by checking documentation, service status pages, and community discussions for solutions."
8 }
9 ]
10)

Troubleshooting

Check:

  1. Tool is attached: "web_search" in agent’s tools list
  2. Instructions are clear about when to search
  3. Model has good tool-calling capabilities (GPT-4, Claude 3+)
1# Verify tools
2agent = client.agents.retrieve(agent_id=agent.id)
3print([tool.name for tool in agent.tools])

Missing EXA_API_KEY

If you see errors about missing API keys on self-hosted deployments:

$# Check if set
>echo $EXA_API_KEY
>
># Set for session
>export EXA_API_KEY="your_exa_api_key"
>
># Docker example
>docker run -e EXA_API_KEY="your_exa_api_key" letta/letta:latest
Use CaseToolWhy
Current events, newsweb_searchReal-time information
External researchweb_searchBroad internet access
Internal documentsArchival memoryFast, static data
User preferencesMemory blocksIn-context, instant
General knowledgePre-trained modelNo search needed