Skip to content

armgit / letta

Public Imported from GitHub
0

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.yml
index 1668be00e..b53b61ed6 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -151,8 +151,17 @@ navigation:
contents:
- page: Overview
path: pages/agents/tools.mdx
- - page: Pre-built Tools
+ - page: Base Tools
+ path: pages/agents/base_tools.mdx
+ - section: Utilities
path: 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 Tools
path: pages/agents/custom_tools.mdx
- page: Tool Rules
diff --git a/fern/pages/agents/base_tools.mdx b/fern/pages/agents/base_tools.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
index 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 fetching
slug: 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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)