Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
Add comprehensive documentation for built-in tools (#5519)
Cameron Pfifferabfddfe7b9aa
diff --git a/fern/docs.yml b/fern/docs.ymlindex 1668be00e..b53b61ed6 100644--- a/fern/docs.yml+++ b/fern/docs.yml@@ -151,8 +151,17 @@ navigation:contents:- page: Overviewpath: pages/agents/tools.mdx- - page: Pre-built Tools+ - page: Base Tools+ path: pages/agents/base_tools.mdx+ - section: Utilitiespath: pages/agents/prebuilt_tools.mdx+ contents:+ - page: Web Search+ path: pages/agents/web_search.mdx+ - page: Code Interpreter+ path: pages/agents/run_code.mdx+ - page: Fetch Webpage+ path: pages/agents/fetch_webpage.mdx- page: Custom Toolspath: pages/agents/custom_tools.mdx- page: Tool Rulesdiff --git a/fern/pages/agents/base_tools.mdx b/fern/pages/agents/base_tools.mdxnew file mode 100644index 000000000..e80295459--- /dev/null+++ b/fern/pages/agents/base_tools.mdx@@ -0,0 +1,165 @@+---+title: Base Tools+subtitle: Built-in tools for memory management and user communication+slug: guides/agents/base-tools+---++Base tools are built-in tools that enable memory management, user communication, and access to conversation history and archival storage.++## Available Base Tools++| Tool | Purpose |+|------|---------|+| `memory_insert` | Insert text into a memory block |+| `memory_replace` | Replace specific text in a memory block |+| `memory_rethink` | Completely rewrite a memory block |+| `memory_finish_edits` | Signal completion of memory editing |+| `conversation_search` | Search prior conversation history |+| `archival_memory_insert` | Add content to archival memory |+| `archival_memory_search` | Search archival memory |+| `send_message` | Send a message to the user (legacy architectures only) |++## Memory Block Editing++Memory blocks are editable sections in the agent's context window. These tools let agents update their own memory.++See the [Memory Blocks guide](/guides/agents/memory-blocks) for more about how memory blocks work.++### memory_insert++Insert text at a specific line in a memory block.++**Parameters:**+- `label`: Which memory block to edit+- `new_str`: Text to insert+- `insert_line`: Line number (0 for beginning, -1 for end)++**Common uses:**+- Add new information to the end of a block+- Insert context at the beginning+- Add items to a list++### memory_replace++Replace specific text in a memory block.++**Parameters:**+- `label`: Which memory block to edit+- `old_str`: Exact text to find and replace+- `new_str`: Replacement text++**Common uses:**+- Update outdated information+- Fix typos or errors+- Delete text (by replacing with empty string)++**Important:** The `old_str` must match exactly, including whitespace. If it appears multiple times, the tool will error.++### memory_rethink++Completely rewrite a memory block's contents.++**Parameters:**+- `label`: Which memory block to rewrite+- `new_memory`: Complete new contents++**When to use:**+- Condensing cluttered information+- Major reorganization+- Combining multiple pieces of information++**When not to use:**+- Adding one line (use `memory_insert`)+- Changing specific text (use `memory_replace`)++### memory_finish_edits++Signals that memory editing is complete.++**Parameters:** None++Some agent architectures use this to mark the end of a memory update cycle.++## Recall Memory++### conversation_search++Search prior conversation history using both text matching and semantic similarity.++**Parameters:**+- `query`: What to search for+- `roles`: Optional filter by message role (user, assistant, tool)+- `limit`: Maximum number of results+- `start_date`, `end_date`: ISO 8601 date/datetime filters (inclusive)++**Returns:**+Matching messages with role and content, ordered by relevance.++**Example queries:**+- "What did the user say about deployment?"+- "Find previous responses about error handling"+- "Search tool outputs from last week"++## Archival Memory++Archival memory stores information long-term outside the context window. See the [Archival Memory documentation](/guides/agents/archival-memory-overview) for details.++### archival_memory_insert++Add content to archival memory for long-term storage.++**Parameters:**+- `content`: Text to store+- `tags`: Optional tags for organization++**Common uses:**+- Storing reference information for later+- Saving important context that doesn't fit in memory blocks+- Building a knowledge base over time++### archival_memory_search++Search archival memory using semantic (embedding-based) search.++**Parameters:**+- `query`: What to search for semantically+- `tags`: Optional tag filters+- `tag_match_mode`: "any" or "all" for tag matching+- `top_k`: Maximum results+- `start_datetime`, `end_datetime`: ISO 8601 filters (inclusive)++**Returns:**+Matching passages with timestamps and content, ordered by semantic similarity.++## Legacy Tools++### send_message++<Info>+Only used by `memgpt_v1_agent` and `memgpt_v2_agent` architectures. The newer `letta_v1_agent` architecture does not use or need this tool.+</Info>++Sends a message to the user.++**Parameters:**+- `message`: The message text to send++**What it does:**+Displays a message to the user in the conversation.++## Deprecated Tools++These tools are still available but deprecated:++| Tool | Use Instead |+|------|-------------|+| `core_memory_append` | `memory_insert` with `insert_line=-1` |+| `core_memory_replace` | `memory_replace` |++## Related Documentation++- [Memory Blocks](/guides/agents/memory-blocks)+- [Archival Memory](/guides/agents/archival-memory-overview)+- [Utilities](/guides/agents/prebuilt-tools)+- [Multi-Agent Tools](/guides/agents/multiagent)+- [Custom Tools](/guides/agents/custom-tools)diff --git a/fern/pages/agents/fetch_webpage.mdx b/fern/pages/agents/fetch_webpage.mdxnew file mode 100644index 000000000..8c036c980--- /dev/null+++ b/fern/pages/agents/fetch_webpage.mdx@@ -0,0 +1,166 @@+---+title: Fetch Webpage+subtitle: Convert webpages to readable text/markdown+slug: guides/agents/fetch-webpage+---++The `fetch_webpage` tool enables Letta agents to fetch and convert webpages into readable text or markdown format. Useful for reading documentation, articles, and web content.++<Info>+On [Letta Cloud](/guides/cloud/overview), this tool works out of the box. For self-hosted deployments with an Exa API key, fetching is enhanced. Without a key, it falls back to open-source extraction tools.+</Info>++## Quick Start++<CodeGroup>+```python Python+from letta import Letta++client = Letta(token="LETTA_API_KEY")++agent = client.agents.create(+ model="openai/gpt-4o",+ tools=["fetch_webpage"],+ memory_blocks=[{+ "label": "persona",+ "value": "I can fetch and read webpages to answer questions about online content."+ }]+)+```++```typescript TypeScript+import { LettaClient } from '@letta-ai/letta-client';++const client = new LettaClient({ token: "LETTA_API_KEY" });++const agent = await client.agents.create({+ model: "openai/gpt-4o",+ tools: ["fetch_webpage"],+ memoryBlocks: [{+ label: "persona",+ value: "I can fetch and read webpages to answer questions about online content."+ }]+});+```+</CodeGroup>++## Tool Parameters++| Parameter | Type | Description |+|-----------|------|-------------|+| `url` | `str` | The URL of the webpage to fetch |++## Return Format++The tool returns webpage content as text/markdown.++**With Exa API (if configured):**+```json+{+ "title": "Page title",+ "published_date": "2025-01-15",+ "author": "Author name",+ "text": "Full page content in markdown"+}+```++**Fallback (without Exa):**+Returns markdown-formatted text extracted from the HTML.++## How It Works++The tool uses a multi-tier approach:++1. **Exa API** (if `EXA_API_KEY` is configured): Uses Exa's content extraction+2. **Trafilatura** (fallback): Open-source text extraction to markdown+3. **Readability + html2text** (final fallback): HTML cleaning and conversion++## Self-Hosted Setup++For enhanced fetching on self-hosted servers, optionally configure an Exa API key. Without it, the tool still works using open-source extraction.++### Optional: Configure Exa++<CodeGroup>+```bash Docker+docker run \+ -e EXA_API_KEY="your_exa_api_key" \+ letta/letta:latest+```++```yaml Docker Compose+services:+ letta:+ environment:+ - EXA_API_KEY=your_exa_api_key+```++```bash Server+export EXA_API_KEY="your_exa_api_key"+letta server+```++```python Per-Agent+agent = client.agents.create(+ tools=["fetch_webpage"],+ tool_env_vars={+ "EXA_API_KEY": "your_exa_api_key"+ }+)+```+</CodeGroup>++## Common Patterns++### Documentation Reader+```python+agent = client.agents.create(+ model="openai/gpt-4o",+ tools=["fetch_webpage", "web_search"],+ memory_blocks=[{+ "label": "persona",+ "value": "I search for documentation with web_search and read it with fetch_webpage."+ }]+)+```++### Research Assistant+```python+agent = client.agents.create(+ model="openai/gpt-4o",+ tools=["fetch_webpage", "archival_memory_insert"],+ memory_blocks=[{+ "label": "persona",+ "value": "I fetch articles and store key insights in archival memory for later reference."+ }]+)+```++### Content Summarizer+```python+agent = client.agents.create(+ model="openai/gpt-4o",+ tools=["fetch_webpage"],+ memory_blocks=[{+ "label": "persona",+ "value": "I fetch webpages and provide summaries of their content."+ }]+)+```++## When to Use++| Use Case | Tool | Why |+|----------|------|-----|+| Read specific webpage | `fetch_webpage` | Direct URL access |+| Find webpages to read | `web_search` | Discovery first |+| Read + search in one | `web_search` with `include_text=true` | Combined operation |+| Multiple pages | `fetch_webpage` | Iterate over URLs |++## Related Documentation++- [Utilities Overview](/guides/agents/prebuilt-tools)+- [Web Search](/guides/agents/web-search)+- [Run Code](/guides/agents/run-code)+- [Custom Tools](/guides/agents/custom-tools)+- [Tool Variables](/guides/agents/tool-variables)diff --git a/fern/pages/agents/prebuilt_tools.mdx b/fern/pages/agents/prebuilt_tools.mdxindex fd498f503..749c7ad87 100644--- a/fern/pages/agents/prebuilt_tools.mdx+++ b/fern/pages/agents/prebuilt_tools.mdx@@ -1,47 +1,94 @@----title: Pre-built Tools-subtitle: Understanding the pre-built tools in the Letta server+title: Utilities+subtitle: Pre-built tools for web access, code execution, and data fetchingslug: guides/agents/prebuilt-tools----Letta provides a set of pre-built tools that are available to all agents. These tools include memory management tools (for reading and writing to memory blocks), file editing tools, multi-agent tools, and general utility tools like web search and code execution.+Letta provides pre-built tools that enable agents to search the web, execute code, and fetch webpage content.-## Default Memory Tools+## Available Utilities-By default, agents in Letta are created with a set of default tools including `send_message` (which generates a message to send to the user), core memory tools (allowing the agent to edit its memory blocks), and external memory tools (to read/write from archival memory, and to access recall memory, aka the conversation history):+### [Web Search](/guides/agents/web-search)-| Tool | Description |-|--------------------------------------------|------------------------------------------------------|-| `send_message` | Sends a message to the human user. |-| `memory_insert` | Insert content into a block in core memory. |-| `memory_replace` | Replace content in a block in core memory. |-| `memory_rethink` | Reflect on and reorganize core memory contents. |-| `memory_finish_edits` | Finalize memory editing operations. |-| `core_memory_append` _(Deprecated)_ | Append to the contents of a block in core memory. |-| `core_memory_replace` _(Deprecated)_ | Replace the contents of a block in core memory. |-| `conversation_search` | Search prior conversation history (recall memory) |-| `archival_memory_insert` | Add a memory to archival memory |-| `archival_memory_search` | Search archival memory via embedding search |+Search the internet in real-time using [Exa](https://exa.ai)'s AI-powered search engine.-You can disable the default tools by setting `include_base_tools` to `false` during agent creation. Note that disabling the `send_message` tool may cause agent messages (intended for the user) to appear as "reasoning" messages in the API and ADE.+```python+agent = client.agents.create(+ tools=["web_search"],+ memory_blocks=[{+ "label": "persona",+ "value": "I use web_search for current events and external research."+ }]+)+```-## Multi-Agent Tools+**Key features:**+- AI-powered semantic search+- Category filtering (news, research papers, PDFs, etc.)+- Domain filtering+- Date range filtering+- Highlights and AI-generated summaries-Letta also includes a set of pre-made tools designed for multi-agent interaction.-See [our guide on multi-agent](/guides/agents/multi-agent) for more information.+**Setup:** Works out of the box on Letta Cloud. Self-hosted requires `EXA_API_KEY`.-## Web Search+[Read full documentation →](/guides/agents/web-search)-The `web_search` tool allows agents to search the web for information.+---++### [Code Interpreter](/guides/agents/run-code)++Execute code in a secure sandbox with full network access.++```python+agent = client.agents.create(+ tools=["run_code"],+ memory_blocks=[{+ "label": "persona",+ "value": "I use Python for data analysis and API calls."+ }]+)+```-<Info>-On [Letta Cloud](/guides/cloud/overview), this tool works out of the box, but when using this tool on a self-hosted Letta server, you must set a `EXA_API_KEY` environment variable either in during server startup or in your agent's [tool execution environment](/guides/agents/tool-variables).-</Info>+**Key features:**+- Python with 191+ pre-installed packages (numpy, pandas, scipy, etc.)+- JavaScript, TypeScript, R, and Java support+- Full network access for API calls+- Fresh environment per execution (no state persistence)++**Setup:** Works out of the box on Letta Cloud. Self-hosted requires `E2B_API_KEY`.++[Read full documentation →](/guides/agents/run-code)++----## Code Interpreter+### [Fetch Webpage](/guides/agents/fetch-webpage)++Fetch and convert webpages to readable text/markdown.++```python+agent = client.agents.create(+ tools=["fetch_webpage"],+ memory_blocks=[{+ "label": "persona",+ "value": "I fetch and read webpages to answer questions."+ }]+)+```++**Key features:**+- Converts HTML to clean markdown+- Extracts article content+- Multiple fallback extraction methods+- Optional Exa integration for enhanced extraction++**Setup:** Works out of the box everywhere. Optional `EXA_API_KEY` for enhanced extraction.++[Read full documentation →](/guides/agents/fetch-webpage)++----The `run_code` tool allows agents to run code (in a sandbox), for example to do data analysis or calculations. Supports Python, Javascript, Typescript, R, and Java.+## Related Documentation-<Info>-On [Letta Cloud](/guides/cloud/overview), this tool works out of the box, but when using this tool on a self-hosted Letta server, you must set a `E2B_API_KEY` environment variable either in during server startup or in your agent's [tool execution environment](/guides/agents/tool-variables).-</Info>+- [Custom Tools](/guides/agents/custom-tools)+- [Tool Variables](/guides/agents/tool-variables)+- [Model Context Protocol](/guides/mcp/overview)diff --git a/fern/pages/agents/run_code.mdx b/fern/pages/agents/run_code.mdxnew file mode 100644index 000000000..d387d2ad7--- /dev/null+++ b/fern/pages/agents/run_code.mdx@@ -0,0 +1,258 @@+---+title: Code Interpreter+subtitle: Execute code in a secure sandbox with full network access+slug: guides/agents/run-code+---++The `run_code` tool enables Letta agents to execute code in a secure sandboxed environment. Useful for data analysis, calculations, API calls, and programmatic computation.++<Info>+On [Letta Cloud](/guides/cloud/overview), this tool works out of the box. For self-hosted deployments, you'll need to [configure an E2B API key](#self-hosted-setup).+</Info>++<Warning>+Each execution runs in a **fresh environment** - variables, files, and state do not persist between runs.+</Warning>++## Quick Start++<CodeGroup>+```python Python+from letta import Letta++client = Letta(token="LETTA_API_KEY")++agent = client.agents.create(+ model="openai/gpt-4o",+ tools=["run_code"],+ memory_blocks=[{+ "label": "persona",+ "value": "I can run Python code for data analysis and API calls."+ }]+)+```++```typescript TypeScript+import { LettaClient } from '@letta-ai/letta-client';++const client = new LettaClient({ token: "LETTA_API_KEY" });++const agent = await client.agents.create({+ model: "openai/gpt-4o",+ tools: ["run_code"],+ memoryBlocks: [{+ label: "persona",+ value: "I can run Python code for data analysis and API calls."+ }]+});+```+</CodeGroup>++## Tool Parameters++| Parameter | Type | Options | Description |+|-----------|------|---------|-------------|+| `code` | `str` | Required | The code to execute |+| `language` | `str` | `python`, `js`, `ts`, `r`, `java` | Programming language |++## Return Format++```json+{+ "results": ["Last expression value"],+ "logs": {+ "stdout": ["Print statements"],+ "stderr": ["Error output"]+ },+ "error": "Error details if execution failed"+}+```++**Output types:**+- `results[]`: Last expression value (Jupyter-style)+- `logs.stdout`: Print statements and standard output+- `logs.stderr`: Error messages+- `error`: Present if execution failed++## Supported Languages++| Language | Key Limitations |+|----------|-----------------|+| **Python** | None - full ecosystem available |+| **JavaScript** | No npm packages - built-in Node modules only |+| **TypeScript** | No npm packages - built-in Node modules only |+| **R** | No tidyverse - base R only |+| **Java** | JShell-style execution - no traditional class definitions |++### Python++Full Python ecosystem with common packages pre-installed:++- **Data**: numpy, pandas, scipy, scikit-learn+- **Web**: requests, aiohttp, beautifulsoup4+- **Utilities**: matplotlib, PyYAML, Pillow++Check available packages:+```python+import pkg_resources+print([d.project_name for d in pkg_resources.working_set])+```++### JavaScript & TypeScript++No npm packages available - only built-in Node modules.++```javascript+// Works+const fs = require('fs');+const http = require('http');++// Fails+const axios = require('axios');+```++### R++Base R only - no tidyverse packages.++```r+# Works+mean(c(1, 2, 3))++# Fails+library(ggplot2)+```++### Java++JShell-style execution - statement-level only.++```java+// Works+System.out.println("Hello");+int x = 42;++// Fails+public class Main {+ public static void main(String[] args) { }+}+```++## Network Access++The sandbox has full network access for HTTP requests, API calls, and DNS resolution.++```python+import requests++response = requests.get('https://api.github.com/repos/letta-ai/letta')+data = response.json()+print(f"Stars: {data['stargazers_count']}")+```++## No State Persistence++Variables, files, and state do not carry over between executions. Each `run_code` call is completely isolated.++```python+# First execution+x = 42++# Second execution (separate run_code call)+print(x) # Error: NameError: name 'x' is not defined+```++**Implications:**+- Must re-import libraries each time+- Files written to disk are lost+- Cannot build up state across executions++## Self-Hosted Setup++For self-hosted servers, configure an E2B API key. [E2B](https://e2b.dev) provides the sandbox infrastructure.++<CodeGroup>+```bash Docker+docker run \+ -e E2B_API_KEY="your_e2b_api_key" \+ letta/letta:latest+```++```yaml Docker Compose+services:+ letta:+ environment:+ - E2B_API_KEY=your_e2b_api_key+```++```bash Server+export E2B_API_KEY="your_e2b_api_key"+letta server+```++```python Per-Agent+agent = client.agents.create(+ tools=["run_code"],+ tool_env_vars={+ "E2B_API_KEY": "your_e2b_api_key"+ }+)+```+</CodeGroup>++## Common Patterns++### Data Analysis+```python+agent = client.agents.create(+ model="openai/gpt-4o",+ tools=["run_code"],+ memory_blocks=[{+ "label": "persona",+ "value": "I use Python with pandas and numpy for data analysis."+ }]+)+```++### API Integration+```python+agent = client.agents.create(+ model="openai/gpt-4o",+ tools=["run_code", "web_search"],+ memory_blocks=[{+ "label": "persona",+ "value": "I fetch data from APIs using run_code and search docs with web_search."+ }]+)+```++### Statistical Analysis+```python+agent = client.agents.create(+ model="openai/gpt-4o",+ tools=["run_code"],+ memory_blocks=[{+ "label": "persona",+ "value": "I perform statistical analysis using scipy and numpy."+ }]+)+```++## When to Use++| Use Case | Tool | Why |+|----------|------|-----|+| Data analysis | `run_code` | Full Python data stack |+| Math calculations | `run_code` | Programmatic computation |+| Live API data | `run_code` | Network + processing |+| Web scraping | `run_code` | requests + BeautifulSoup |+| Simple search | `web_search` | Purpose-built |+| Persistent data | Archival memory | State persistence |++## Related Documentation++- [Utilities Overview](/guides/agents/prebuilt-tools)+- [Web Search](/guides/agents/web-search)+- [Fetch Webpage](/guides/agents/fetch-webpage)+- [Custom Tools](/guides/agents/custom-tools)+- [Tool Variables](/guides/agents/tool-variables)diff --git a/fern/pages/agents/web_search.mdx b/fern/pages/agents/web_search.mdxnew file mode 100644index 000000000..30dc9f005--- /dev/null+++ b/fern/pages/agents/web_search.mdx@@ -0,0 +1,342 @@+---+title: Web Search+subtitle: Search the internet in real-time with AI-powered search+slug: guides/agents/web-search+---++The `web_search` tool enables Letta agents to search the internet for current information, research, and general knowledge using [Exa](https://exa.ai)'s AI-powered search engine.++<Info>+On [Letta Cloud](/guides/cloud/overview), this tool works out of the box. For self-hosted deployments, you'll need to [configure an Exa API key](#self-hosted-setup).+</Info>++## Quick Start++### Adding Web Search to an Agent++<CodeGroup>+```python Python+from letta import Letta++client = Letta(token="LETTA_API_KEY")++agent = client.agents.create(+ model="openai/gpt-4o",+ embedding="openai/text-embedding-3-small",+ tools=["web_search"],+ memory_blocks=[+ {+ "label": "persona",+ "value": "I'm a research assistant who uses web search to find current information and cite sources."+ }+ ]+)+```++```typescript TypeScript+import { LettaClient } from '@letta-ai/letta-client';++const client = new LettaClient({ token: "LETTA_API_KEY" });++const agent = await client.agents.create({+ model: "openai/gpt-4o",+ embedding: "openai/text-embedding-3-small",+ tools: ["web_search"],+ memoryBlocks: [+ {+ label: "persona",+ value: "I'm a research assistant who uses web search to find current information and cite sources."+ }+ ]+});+```+</CodeGroup>++### Usage Example++```python+response = client.agents.messages.create(+ agent_id=agent.id,+ messages=[+ {+ "role": "user",+ "content": "What are the latest developments in agent-based AI systems?"+ }+ ]+)+```++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](https://dashboard.exa.ai/)+2. Copy your API key+3. See [Exa pricing](https://docs.exa.ai) for rate limits and costs++### Configuration Options++<CodeGroup>+```bash Docker+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+```++```yaml Docker Compose+version: '3.8'+services:+ letta:+ image: letta/letta:latest+ ports:+ - "8283:8283"+ environment:+ - OPENAI_API_KEY=your_openai_key+ - EXA_API_KEY=your_exa_api_key+ volumes:+ - ~/.letta/.persist/pgdata:/var/lib/postgresql/data+```++```bash Python Server+export EXA_API_KEY="your_exa_api_key"+letta server+```++```python Per-Agent Configuration+agent = client.agents.create(+ model="openai/gpt-4o",+ embedding="openai/text-embedding-3-small",+ tools=["web_search"],+ tool_env_vars={+ "EXA_API_KEY": "your_exa_api_key"+ }+)+```+</CodeGroup>++## Tool Parameters++The `web_search` tool supports advanced filtering and search customization:++| Parameter | Type | Default | Description |+|-----------|------|---------|-------------|+| `query` | `str` | Required | The search query to find relevant web content |+| `num_results` | `int` | 10 | Number of results to return (1-100) |+| `category` | `str` | None | Focus search on specific content types (see below) |+| `include_text` | `bool` | False | Whether to retrieve full page content (usually overflows context) |+| `include_domains` | `List[str]` | None | List of domains to include in search results |+| `exclude_domains` | `List[str]` | None | List of domains to exclude from search results |+| `start_published_date` | `str` | None | Only return content published after this date (ISO format) |+| `end_published_date` | `str` | None | Only return content published before this date (ISO format) |+| `user_location` | `str` | None | Two-letter country code for localized results (e.g., "US") |++### Available Categories++Use the `category` parameter to focus your search on specific content types:++| Category | Best For | Example Query |+|----------|----------|---------------|+| `company` | Corporate information, company websites | "Tesla energy storage solutions" |+| `research paper` | Academic papers, arXiv, research publications | "transformer architecture improvements 2025" |+| `news` | News articles, current events | "latest AI policy developments" |+| `pdf` | PDF documents, reports, whitepapers | "climate change impact assessment" |+| `github` | GitHub repositories, open source projects | "python async web scraping libraries" |+| `tweet` | Twitter/X posts, social media discussions | "reactions to new GPT release" |+| `personal site` | Blogs, personal websites, portfolios | "machine learning tutorial blogs" |+| `linkedin profile` | LinkedIn profiles, professional bios | "AI research engineers at Google" |+| `financial report` | Earnings reports, financial statements | "Apple Q4 2024 earnings" |++### Return Format++The tool returns a JSON-encoded string containing:++```json+{+ "query": "search query",+ "results": [+ {+ "title": "Page title",+ "url": "https://example.com",+ "published_date": "2025-01-15",+ "author": "Author name",+ "highlights": ["Key excerpt 1", "Key excerpt 2"],+ "summary": "AI-generated summary of the content",+ "text": "Full page content (only if include_text=true)"+ }+ ]+}+```++## Best Practices++### 1. Guide When to Search++Provide clear instructions to your agent about when web search is appropriate:++```python+memory_blocks=[+ {+ "label": "persona",+ "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."+ }+]+```++### 2. Combine with Archival Memory++Use web search for external/current information, and archival memory for your organization's internal data:++```python+# Create agent with both web_search and archival memory tools+agent = client.agents.create(+ model="openai/gpt-4o",+ embedding="openai/text-embedding-3-small",+ tools=["web_search", "archival_memory_search", "archival_memory_insert"],+ memory_blocks=[+ {+ "label": "persona",+ "value": "I use web_search for current events and external research. I use archival_memory_search for company-specific information and internal documents."+ }+ ]+)+```++See the [Archival Memory documentation](/guides/agents/archival-memory-overview) 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:++```python+memory_blocks=[+ {+ "label": "search_strategy",+ "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."+ }+]+```++### 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:++```python+memory_blocks=[+ {+ "label": "search_guidelines",+ "value": "I avoid setting include_text=true unless specifically needed, as full text usually overflows the context window. Highlights and summaries are usually sufficient."+ }+]+```++## Common Patterns++### Research Assistant++```python+agent = client.agents.create(+ model="openai/gpt-4o",+ tools=["web_search"],+ memory_blocks=[+ {+ "label": "persona",+ "value": "I'm a research assistant. I search for relevant information, synthesize findings from multiple sources, and provide citations."+ }+ ]+)+```++### News Monitor++```python+agent = client.agents.create(+ model="openai/gpt-4o-mini",+ tools=["web_search"],+ memory_blocks=[+ {+ "label": "persona",+ "value": "I monitor news and provide briefings on AI industry developments."+ },+ {+ "label": "topics",+ "value": "Focus: AI/ML, agent systems, LLM advancements"+ }+ ]+)+```++### Customer Support++```python+agent = client.agents.create(+ model="openai/gpt-4o",+ tools=["web_search"],+ memory_blocks=[+ {+ "label": "persona",+ "value": "I help customers by checking documentation, service status pages, and community discussions for solutions."+ }+ ]+)+```++## Troubleshooting++### Agent Not Using Web Search++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+)++```python+# Verify tools+agent = client.agents.retrieve(agent_id=agent.id)+print([tool.name for tool in agent.tools])+```++### Missing EXA_API_KEY++If you see errors about missing API keys on self-hosted deployments:++```bash+# 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+```++## When to Use Web Search++| Use Case | Tool | Why |+|----------|------|-----|+| Current events, news | `web_search` | Real-time information |+| External research | `web_search` | Broad internet access |+| Internal documents | Archival memory | Fast, static data |+| User preferences | Memory blocks | In-context, instant |+| General knowledge | Pre-trained model | No search needed |++## Related Documentation++- [Utilities Overview](/guides/agents/prebuilt-tools)+- [Custom Tools](/guides/agents/custom-tools)+- [Tool Variables](/guides/agents/tool-variables)+- [Archival Memory](/guides/agents/archival-memory-overview)