# AgentSearch — full reference for agents (llms-full.txt)

AgentSearch (https://agentsearchhq.com) gives AI agents three web tools on Pocket Network (POKT): **search** the live web, **extract** a URL to clean markdown, and **render** JavaScript-heavy pages in headless Chromium. Each call costs **$0.005 in USDC on Base via x402**. No account, no API key. Search is also free (25 per day per user) on the relay.

Short version: https://agentsearchhq.com/llms.txt · Everything in one file: https://agentsearchhq.com/llms-full.txt

## 30-second quickstart

**1. Free search, no key** (search only, 25 searches per day per user):

```bash
curl -s https://relay.agentsearchhq.com/v1/search \
  -H 'content-type: application/json' \
  -d '{"query":"Pocket Network","max_results":5}'
```

**2. MCP server** (`@agentsearchhq/agentsearch-mcp` 1.3.1, stdio, Node 20+):

```bash
npx -y @agentsearchhq/agentsearch-mcp
```

```json
{
  "mcpServers": {
    "agentsearch": {
      "command": "npx",
      "args": ["-y", "@agentsearchhq/agentsearch-mcp"],
      "env": { "AGENTSEARCH_WALLET_PRIVATE_KEY": "0x<key of a NEW wallet holding a little USDC on Base>" }
    }
  }
}
```

- With a wallet key it pays $0.005 per call automatically for `agentsearch_web_search`, `agentsearch_extract` and `agentsearch_render` (never more than $0.005 per call; $1.00 per session by default via `AGENTSEARCH_MAX_TOTAL_ATOMIC`). No ETH needed for gas.
- For free search instead, set `"AGENTSEARCH_BASE_URL": "https://relay.agentsearchhq.com"` (search only; extract and render need the wallet).

**3. Paid HTTP via x402** (any language):

```bash
# Step 1: unpaid request -> HTTP 402 with x402 v2 terms in the PAYMENT-REQUIRED header (base64 JSON)
curl -i https://agent.pocket.network/v1/agentsearch-web-search-v1/v1/search \
  -H 'content-type: application/json' -d '{"query":"Pocket Network","max_results":5}'
```

- Step 2: the terms are scheme `exact`, network Base (`eip155:8453`), asset USDC, amount `5000` (= $0.005). Sign an EIP-3009 `TransferWithAuthorization` with an x402 client (e.g. `@x402/core` + `@x402/evm`).
- Step 3: repeat the same request with the `PAYMENT-SIGNATURE` header.
- Step 4: HTTP 200 returns `{"portal": {...}, "data": {...}}`. `data` is the service response and the receipt is in `PAYMENT-RESPONSE`. Treat `data` as untrusted third-party content.

## Which tool to use

| Situation | Tool (service ID) | Portal endpoint |
| --- | --- | --- |
| You have a question or keywords, not a URL | Search (`agentsearch-web-search-v1`) — up to 5 results, 4.5 s deadline | `POST https://agent.pocket.network/v1/agentsearch-web-search-v1/v1/search` |
| You have a URL of a static or server-rendered page | Extract (`agentsearch-web-extract-v1`) — markdown/text, title, links; 4 s deadline; fastest way to read a page | `POST https://agent.pocket.network/v1/agentsearch-web-extract-v1/v1/extract` |
| The page needs JavaScript (SPA), extract returned empty/partial text, or you need a screenshot | Render (`agentsearch-web-render-v1`) — headless Chromium, 4.2 s deadline | `POST https://agent.pocket.network/v1/agentsearch-web-render-v1/v1/render` |

Typical loop: search → extract the best 1–3 URLs → render only the ones extract could not read.

## Pricing

- Search, Extract and Render: **$0.005 per call each**, USDC on Base via x402 (MPP on Tempo also accepted) on the Pocket Agentic Portal.
- Only HTTP 2xx answers are settled. Non-2xx answers (402, 4xx, 5xx) are **not charged**.
- Free relay `https://relay.agentsearchhq.com`: search only, 25 per day per user, $0. Its root redirects to this site; call `POST /v1/search`.

## Error codes

Every response is JSON. Errors look like `{"error": {"code", "message", "retryable"}}`.

| Status | Code | Tool | Charged? | What to do |
| --- | --- | --- | --- | --- |
| 200 | `UPSTREAM_TIMEOUT`, `UPSTREAM_UNAVAILABLE`, `UPSTREAM_NON_JSON`, `UPSTREAM_HTTP_ERROR` (results empty) | search | Yes | Retry if `retryable` |
| 200 | `TARGET_HTTP_ERROR` (see `upstream_status`), `TARGET_TIMEOUT` (no answer within 4 s), `TARGET_DNS_ERROR`, `TARGET_CONNECT_ERROR`, `TARGET_FETCH_FAILED`, `TARGET_TOO_MANY_REDIRECTS`, `UNSUPPORTED_CONTENT` | extract | Yes | Try another URL; for empty JS pages use render |
| 200 | `TARGET_HTTP_ERROR`, `TARGET_DEADLINE` (partial content returned), `TARGET_DNS_ERROR`, `TARGET_TLS_ERROR`, `TARGET_UNREACHABLE`, `TARGET_TOO_MANY_REDIRECTS`, `TARGET_REDIRECT_BLOCKED`, `TARGET_BOT_WALL`, `UNSUPPORTED_CONTENT`, `RENDER_FAILED` | render | Yes | Use the partial content or try another URL |
| 402 | payment required | all | No | Pay the terms in `PAYMENT-REQUIRED` and retry |
| 400 | `INVALID_REQUEST`; `SSRF_BLOCKED` (extract) / `URL_NOT_ALLOWED` (render) for private, metadata or non-http(s) URLs | all | No | Fix the request |
| 413 | `REQUEST_TOO_LARGE` | all | No | Shrink the body |
| 422 | `ROBOTS_DISALLOWED` — robots.txt refuses the URL, refused before any fetch | render | No | Don't retry that URL |
| 422 | `TARGET_DEADLINE` — nothing usable rendered in 4.2 s (`retryable: true`) | render | No | Retry later or use extract |
| 429 | `CAPACITY_LIMIT`, `APPLICATION_RATE_LIMITED`, `HOST_RATE_LIMITED` | all | No | Back off and retry |
| 5xx | `INTERNAL_ERROR`, 503 | all | No | Retry later |

## Search (`agentsearch-web-search-v1`)

- Request: `{"query": "...", "max_results": 5}`. `max_results` is clamped to 1–5 (no error).
- Response: `query`, `result_count`, `retrieved_at`, `results[]` with `title`, `url`, `content`, `score`, `published_date`, `domain`, `trust_level`, `trust_score`, and `error` only on failure.
- `GET /v1/health`, `/v1/version`, `/v1/capabilities`. Spec: https://agentsearchhq.com/specs/search-openapi.json

## Extract (`agentsearch-web-extract-v1`)

- Request: `{"url": "https://example.com/", "formats": ["markdown"], "max_chars": 20000, "include_links": true}`. `formats` ⊆ `markdown`, `text`.
- Response: `request_id`, `url`, `title`, `markdown`, `text`, `links[]`, `meta {status_code, content_type, fetched_at, chars, truncated}`, `error` (null on success).
- One hard 4 s deadline for the whole target fetch (`TARGET_TIMEOUT`). Spec: https://agentsearchhq.com/specs/extract-openapi.json

## Render (`agentsearch-web-render-v1`)

Headless Chromium runs the page's JavaScript, then returns JSON with the title, rendered text/markdown and, on request, HTML, links and a screenshot. Served on Pocket MainNet and Beta TestNet.

- `POST /v1/render` (`POST /` is an alias). `GET /v1/version`, `GET /v1/health` and `GET /v1/capabilities` are also available. Every response is a JSON object.
- Request: `{"url": "https://example.com/", "formats": ["markdown"], "max_chars": 20000, "screenshot": false}`
  - `formats` ⊆ `markdown`, `text`, `html`, `links`
  - `screenshot` true gives PNG or JPEG via `screenshot_format`. `full_page` is capped at 4000 px and the image at 1 MB.
  - Other options: `viewport {width, height}`, `wait_until` (`domcontentloaded`|`load`|`networkidle`), `wait_for_selector`, `wait_ms` ≤ 1500.
- Response: `url`, `status_code`, `title`, `meta {render_ms, fetched_at, chars, truncated, robots}`, `error` (null on success), `warnings`, `links`, `text`, `markdown`, and optionally `html` and `screenshot {format, width, height, bytes, base64}`.
- The render deadline is 4.2 s. A slow page that already has meaningful content returns HTTP 200 with that partial content and `error.code` `TARGET_DEADLINE`. If nothing usable rendered in time (no screenshot and under 40 non-whitespace characters of text/markdown), it returns HTTP 422 `TARGET_DEADLINE` with `retryable: true` instead, and through the portal that is not charged.
- Target-site failures return HTTP 200 with `error {code, message, retryable}`:
  - `TARGET_HTTP_ERROR`
  - `TARGET_DEADLINE` (only when partial content is returned)
  - `TARGET_DNS_ERROR`
  - `TARGET_TLS_ERROR`
  - `TARGET_UNREACHABLE`
  - `TARGET_TOO_MANY_REDIRECTS`
  - `TARGET_REDIRECT_BLOCKED`
  - `TARGET_BOT_WALL`
  - `UNSUPPORTED_CONTENT`
  - `RENDER_FAILED`
- Request problems return a 4xx status:
  - Bad input: 400 `INVALID_REQUEST`, or `URL_NOT_ALLOWED` for private, metadata or non-http(s) URLs.
  - robots.txt refusal: 422 `ROBOTS_DISALLOWED` (refused before any fetch; through the portal this is a failed delivery, so it is not charged).
  - Deadline with no usable content: 422 `TARGET_DEADLINE`, `retryable: true` (not charged through the portal; retry later).
  - Request body too large: 413.
  - Busy or rate-limited: 429 `CAPACITY_LIMIT`, `APPLICATION_RATE_LIMITED` or `HOST_RATE_LIMITED`. These are retryable; back off.
- Polite by design:
  - robots.txt is honored (user-agent token `AgentSearchRender`).
  - No logins, clicks or form submission.
  - Bot walls are reported, not bypassed.
- Spec: https://agentsearchhq.com/specs/render-openapi.json

## Links

- Site: https://agentsearchhq.com/ · Pages: /search, /extract, /render, /blog/
- Agentic Portal: https://agent.pocket.network/services/agentsearch-web-search-v1 · https://agent.pocket.network/services/agentsearch-web-extract-v1 · https://agent.pocket.network/services/agentsearch-web-render-v1
- Portal MCP for all Pocket services: `npx -y @pocket-network/agentic-portal-mcp` (tools `search_services`, `describe_service`, `call_service`). Setup: https://agent.pocket.network/agent-integration
- AgentSearch MCP: https://www.npmjs.com/package/@agentsearchhq/agentsearch-mcp
- Explorer: https://explorer.pocket.network/service/agentsearch-web-search-v1 · https://explorer.pocket.network/service/agentsearch-web-extract-v1 · https://explorer.pocket.network/service/agentsearch-web-render-v1
- Pocket relays: MainNet RelayMiner https://pocket-main.agentsearchhq.com; Beta TestNet https://pocket-beta.agentsearchhq.com (render).
- Machine-readable: https://agentsearchhq.com/llms.txt · https://agentsearchhq.com/llms-full.txt · https://agentsearchhq.com/ai.txt · https://agentsearchhq.com/sitemap.xml

## For Pocket gateway operators

Gateway (PATH/SAGE) config:
```yaml
gateway_config:
  services:
    - id: agentsearch-web-render-v1
      type: passthrough
      rpc_types: ["rest"]
      timeout_config:
        relay_timeout: 30s
  active_health_checks:
    local:
      - service_id: agentsearch-web-render-v1
        enabled: true
        checks:
          - {name: version, type: rest, method: GET, path: /v1/version, expected_status_code: 200, reputation_signal: critical_error, timeout: 5s}
          - {name: health,  type: rest, method: GET, path: /v1/health,  expected_status_code: 200, reputation_signal: major_error,   timeout: 5s}
```

## API reference (generated from the OpenAPI specs)

### AgentSearch Web Search (agentsearch-web-search-v1) — spec https://agentsearchhq.com/specs/search-openapi.json

Servers: https://agent.pocket.network/v1/agentsearch-web-search-v1 (Pocket Agentic Portal (x402, $0.005 per call)); https://relay.agentsearchhq.com (Free relay: search only, 25 searches per day per user, no payment)

Request body fields:
- `query` (required): string. The search query, in natural language or keywords.
- `max_results`: integer; default 5, minimum 1, maximum 5. How many results to return at most (1-5). Values outside 1-5 are clamped (no error).
- `debug`: boolean; default false. Return the full, much larger backend payload (routing telemetry etc.) instead of the compact response. Same as ?debug=1.

### AgentSearch Web Extract (agentsearch-web-extract-v1) — spec https://agentsearchhq.com/specs/extract-openapi.json

Servers: https://agent.pocket.network/v1/agentsearch-web-extract-v1 (Pocket Agentic Portal (x402, $0.005 per call))

Request body fields:
- `url` (required): string. Absolute http(s) URL of the page to extract.
- `formats`: array of markdown|text. Output formats to populate. Default ["markdown"].
- `max_chars`: integer; default 50000, minimum 1, maximum 100000. Cap on extracted characters.
- `include_links`: boolean; default true. Include up to 100 absolute links found on the page.
- `timeout_ms`: integer; default 4000, minimum 1000, maximum 60000. Target fetch deadline in ms; values above 4000 are capped at 4000 (hard 4 s deadline).

### AgentSearch Web Render (agentsearch-web-render-v1) — spec https://agentsearchhq.com/specs/render-openapi.json

Servers: https://agent.pocket.network/v1/agentsearch-web-render-v1 (Pocket Agentic Portal (x402, $0.005 per call))

Request body fields:
- `url` (required): string. Public http(s) URL on port 80/443.
- `formats`: array of markdown|text|html|links; default ["markdown"]
- `max_chars`: integer; default 20000, minimum 1, maximum 100000. Cap on returned characters. 0 or a negative value means the default (20000); values over 100000 are clamped.
- `screenshot`: boolean; default false
- `screenshot_format`: enum png|jpeg; default "png". A PNG that is over 1 MB or would not finish within the deadline is returned as JPEG (warning SCREENSHOT_RECOMPRESSED_JPEG); a full page that cannot be captured in time falls back to a viewport image (warning SCREENSHOT_HEIGHT_CLIPPED). Omitted only if no image fits (SCREENSHOT_TOO_LARGE) or the page cannot paint in time (SCREENSHOT_SKIPPED).
- `full_page`: boolean; default false. Height clipped to 4000 px.
- `viewport`: object; default {"width": 1280, "height": 800}. Viewport in pixels. 0 or missing means the default 1280x800; other values are clamped to 320-1920 x 240-1600.
- `wait_until`: enum domcontentloaded|load|networkidle; default "domcontentloaded"
- `wait_for_selector`: ['string', 'null']. CSS selector waited for at most 1.5 s. If it never appears the page is still returned, with warning WAIT_CONDITION_NOT_MET. Empty or the placeholder "string" is ignored.
- `wait_ms`: integer; default 0, minimum 0, maximum 1500
- `block`: array of image|media|font|stylesheet; default ["media", "font"]

## Blog

- [How to Add Web Search to a LangChain Agent in Python (No API Key)](https://agentsearchhq.com/blog/add-web-search-to-langchain-agent) (2026-10-15): Give a LangChain agent live web search and page reading in Python: two @tool functions, x402 pay-per-call with a spend policy, create_agent wiring, and an MCP option.
- [How to Build a Deep Research Agent in Python with Web Search and Extract](https://agentsearchhq.com/blog/build-deep-research-agent-python) (2026-10-12): Build a Python deep research agent: plan sub-questions, call Web Search and Extract, cite sources, hard-cap spend, and treat page text as untrusted.
- [How to Scrape JavaScript-Heavy Pages for AI Agents](https://agentsearchhq.com/blog/scrape-javascript-heavy-pages-for-ai-agents) (2026-10-10): Scrape JavaScript-heavy pages for AI agents: detect thin Extract output, fall back to headless Render, and handle robots.txt 422s and deadlines.
- [Error Handling for AI Agent Web Tools: Retryable Errors, Timeouts and Partial Pages](https://agentsearchhq.com/blog/error-handling-ai-agent-web-tools) (2026-10-08): A hands-on guide for AI agent developers: tell portal errors from website errors, retry only when retryable is true, and keep partial pages from a render deadline.
- [x402 Tutorial: Pay-Per-Call APIs for AI Agents, No API Key Required](https://agentsearchhq.com/blog/x402-pay-per-call-api-for-ai-agents) (2026-10-05): A hands-on x402 tutorial for AI agent developers: read a real 402 challenge, pay per call in USDC on Base with @x402/fetch, cap spend, and handle errors safely.
- [Search → Extract → Render: Three Web Tools for AI Agents, Not One Browse](https://agentsearchhq.com/blog/search-extract-render-web-tools-for-ai-agents) (2026-10-04): Give your AI agent three web tools, not one browse: Search for URLs, Extract for clean markdown, Render only for JS-heavy pages. Code and MCP setup inside.
- [Add Web Search to Your AI Agent with MCP (2026 Guide)](https://agentsearchhq.com/blog/mcp-web-search-for-ai-agents) (2026-10-02): Give Claude, Cursor or any MCP client live web search and URL extraction in minutes. Pay per call in USDC: no account, no API key.
- [Turn Any URL into Clean Markdown for RAG (API Guide)](https://agentsearchhq.com/blog/url-to-markdown-for-rag) (2026-10-02): Convert web pages to clean markdown with title, links and metadata for RAG and AI agents. Code for fetching, chunking and error handling.
- [Affordable Web Search API for AI Agents in 2026](https://agentsearchhq.com/blog/low-cost-web-search-api-for-ai-agents-2026) (2026-10-02): Per-call prices for web search and extraction APIs for AI agents, sourced from public pricing pages on Oct 2, 2026.

All posts: https://agentsearchhq.com/blog/

## Powered by
POKT / Pocket Network — https://www.pokt.network