Skip to main content

​
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.
  1. Get a free API key at brave.com/search/api
  2. Configure it in one of three ways:
Option A: Config file (recommended) Add to ~/.argentos/argent.json: 
{
  "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 
argent configure --section web

​
Perplexity Sonar (AI-Synthesized Answers)

Perplexity returns AI-generated answers with citations instead of a list of links. 
{
  "tools": {
    "web": {
      "search": {
        "apiKey": "pplx-YOUR_KEY",
        "provider": "perplexity"
      }
    }
  }
}
Perplexity keys starting with pplx- connect directly. Keys starting with sk-or- route through OpenRouter. The agent uses this tool to search the internet for current information.

​
Parameters

ParameterTypeRequiredDescription
querystringYesSearch query
countnumberNoNumber of results (1-20, default 5)
countrystringNo2-letter country code (e.g., “US”, “DE”)
search_langstringNoLanguage code (e.g., “en”, “fr”)
freshnessstringNoTime filter: “pd” (day), “pw” (week), “pm” (month), “py” (year)

​
Output (Brave)

{
  "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)

{
  "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

ParameterTypeRequiredDescription
urlstringYesURL to fetch
extractModestringNo”markdown” (default) or “text”
maxCharsnumberNoMaximum 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:
OptionDefaultDescription
provider”brave”Search provider: “brave” or “perplexity”
apiKey-Provider API key
maxResults5Default number of results
timeoutSeconds30Request timeout
cacheTtlMinutes15How 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.