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

# Web Search & Fetch

> Give your agent the ability to search the web and fetch content from URLs.

## Overview

ArgentOS includes two web tools: `web_search` for searching the internet and `web_fetch` for retrieving content from specific URLs. Both are available to your agent automatically once configured.

## Setup

Web search requires an API key from one of two supported providers.

### Brave Search (Recommended)

1. Get a free API key at [brave.com/search/api](https://brave.com/search/api/)
2. Configure it in one of three ways:

**Option A: Config file** (recommended)

Add to `~/.argentos/argent.json`:

```json theme={null}
{
  "tools": {
    "web": {
      "search": {
        "apiKey": "YOUR_BRAVE_API_KEY",
        "provider": "brave"
      }
    }
  }
}
```

**Option B: Environment variable**

Set `BRAVE_API_KEY` in the Gateway environment.

**Option C: Interactive setup**

```bash theme={null}
argent configure --section web
```

### Perplexity Sonar (AI-Synthesized Answers)

Perplexity returns AI-generated answers with citations instead of a list of links.

```json theme={null}
{
  "tools": {
    "web": {
      "search": {
        "apiKey": "pplx-YOUR_KEY",
        "provider": "perplexity"
      }
    }
  }
}
```

Perplexity keys starting with `pplx-` connect directly. Keys starting with `sk-or-` route through OpenRouter.

## web\_search

The agent uses this tool to search the internet for current information.

### Parameters

| Parameter     | Type   | Required | Description                                                     |
| ------------- | ------ | -------- | --------------------------------------------------------------- |
| `query`       | string | Yes      | Search query                                                    |
| `count`       | number | No       | Number of results (1-20, default 5)                             |
| `country`     | string | No       | 2-letter country code (e.g., "US", "DE")                        |
| `search_lang` | string | No       | Language code (e.g., "en", "fr")                                |
| `freshness`   | string | No       | Time filter: "pd" (day), "pw" (week), "pm" (month), "py" (year) |

### Output (Brave)

```json theme={null}
{
  "query": "argentos personal ai",
  "provider": "brave",
  "count": 3,
  "tookMs": 234,
  "results": [
    {
      "title": "ArgentOS - The Operating System for Personal AI",
      "url": "https://argentos.ai",
      "description": "Run your own AI agent on your hardware...",
      "published": "2 days ago",
      "siteName": "argentos.ai"
    }
  ]
}
```

### Output (Perplexity)

```json theme={null}
{
  "query": "argentos personal ai",
  "provider": "perplexity",
  "content": "ArgentOS is a personal AI operating system that runs on your hardware...",
  "citations": ["https://argentos.ai", "https://github.com/ArgentAIOS"]
}
```

## web\_fetch

Retrieves and extracts readable content from a URL. Useful when the agent needs to read a specific page.

### Parameters

| Parameter     | Type   | Required | Description                    |
| ------------- | ------ | -------- | ------------------------------ |
| `url`         | string | Yes      | URL to fetch                   |
| `extractMode` | string | No       | "markdown" (default) or "text" |
| `maxChars`    | number | No       | Maximum content length         |

### Security

* Private IPs, localhost, and cloud metadata endpoints are blocked (SSRF protection)
* Readability mode extracts article content, stripping navigation and ads
* Optional Firecrawl integration for JavaScript-heavy pages

## Configuration Options

All options in `~/.argentos/argent.json` under `tools.web.search`:

| Option            | Default | Description                              |
| ----------------- | ------- | ---------------------------------------- |
| `provider`        | "brave" | Search provider: "brave" or "perplexity" |
| `apiKey`          | -       | Provider API key                         |
| `maxResults`      | 5       | Default number of results                |
| `timeoutSeconds`  | 30      | Request timeout                          |
| `cacheTtlMinutes` | 15      | How long to cache results                |

## Rate Limits

* Brave free tier: 1 request per 1.1 seconds (enforced automatically)
* Perplexity: No client-side rate limit
* Results are cached for 15 minutes by default to reduce API calls

## Without an API Key

If no API key is configured, `web_search` returns a helpful error with setup instructions. The agent will tell you it can't search the web and suggest how to enable it.