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

# Live web context for agents

> Give an AI agent two tools, search the web and read a page, so it answers from live pages and cites a source URL for each claim. About $0.003 a question.

Your agent should answer from pages it read today, not from what a model remembers. You build two small tools: one finds pages, one reads a page. The agent chooses which to call, and every answer can point to a URL.

You need an API key in `STOPHY_API_KEY`. See the [Quickstart](https://docs.stophy.dev/quickstart). A question that takes one search and two page reads costs about \$0.003.

## 1. Find pages

Search returns a short list of pages for a query. This request asks for 3 results.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "bun release notes", "limit": 3 }'
```

`data.web` holds the results. Each has a `url`, a `title` and usually a `description`. This is the real answer.

```json theme={null}
{
  "success": true,
  "data": {
    "web": [
      {
        "url": "https://bun.com/",
        "title": "Blog | Bun",
        "description": "Fixes issue with bundling imported .wasm files in `bun build`. Fixes regression with `bun build` from v1.1.28. … This release fixes 40 bugs (addressing 51 👍).",
        "position": 1
      },
      {
        "url": "https://bun.com/blog",
        "title": "Blog | Bun",
        "description": "Release notes, engineering deep-dives and announcements from the team building Bun.",
        "position": 2
      },
      {
        "url": "https://www.youtube.com/watch?v=0tvA6yKP0ww",
        "title": "Bun 1.3 Can Now Replace Your Entire JavaScript Stack - YouTube",
        "position": 3
      }
    ]
  },
  "id": "029f4260-1c63-4977-af7e-c16a0d58d92f",
  "costUsd": 0.001,
  "requestId": "029f4260-1c63-4977-af7e-c16a0d58d92f"
}
```

The search cost \$0.001. The tool gives the agent titles, URLs and snippets only, so a result is a lead, not evidence. See [Search](https://docs.stophy.dev/search/overview) for sources and filters.

## 2. Read one page

Scrape reads a page the agent picked. `maxChars` keeps each answer short, so a long page does not fill the agent's context.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/scrape \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://bun.com/blog", "maxChars": 1500 }'
```

This real answer is cut. The middle of the Markdown and most of `metadata` are left out.

```json theme={null}
{
  "success": true,
  "data": {
    "markdown": "# Blog\n\n[RSS](https://bun.com/rss.xml)\n\nLatestOct 22, 2026\n\n## [Bun v1.4.4](https://bun.com/blog/bun-v1.4.4)\n\nFixes 271 issues, addressing 544 👍. bun fmt, a Prettier-compatible formatter built into Bun … 180 posts\n\n",
    "nextOffset": 1493,
    "warning": "The page text was cut short. Send offset 1493 to read on.",
    "metadata": {
      "title": "Blog | Bun",
      "sourceURL": "https://bun.com/blog",
      "statusCode": 200,
      "contentType": "text/html",
      "costUsd": 0.001
    }
  },
  "id": "b62ee998-15d6-425b-9693-9992945bb95b",
  "costUsd": 0.001,
  "requestId": "b62ee998-15d6-425b-9693-9992945bb95b"
}
```

`nextOffset` says where the next part starts. Send the same request with `"offset": 1493` to read on. The read cost \$0.001. See [Content filtering](https://docs.stophy.dev/scrape/content-filtering.md).

## 3. Wrap both as tools

Each tool takes a string and returns a string. A failed call returns the error as text, so the model can try something else instead of the loop crashing.

```typescript TypeScript theme={null}
interface SearchAnswer {
  data: { web?: { url: string; title: string; description?: string }[] };
}

interface ScrapeAnswer {
  data: { markdown?: string; nextOffset?: number };
}

async function post<Answer>(path: string, body: object): Promise<Answer> {
  const response = await fetch(`https://api.stophy.dev${path}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  const answer = await response.json();
  if (!response.ok) throw new Error(answer.error);
  return answer;
}

export async function searchWeb(query: string): Promise<string> {
  try {
    const { data } = await post<SearchAnswer>("/v1/search", { query, limit: 3 });
    const rows = (data.web ?? []).map(
      (row) => `${row.title}\n${row.url}\n${row.description ?? ""}`,
    );
    return rows.length > 0 ? rows.join("\n\n") : "No results.";
  } catch (error) {
    return `Search failed: ${error instanceof Error ? error.message : "unknown error"}`;
  }
}

export async function readPage(url: string, offset?: number): Promise<string> {
  try {
    const { data } = await post<ScrapeAnswer>("/v1/scrape", { url, maxChars: 1500, offset });
    const more = data.nextOffset === undefined ? "" : `\n\n[Cut here. Call again with offset ${data.nextOffset} to read on.]`;
    return `Source: ${url}\n\n${data.markdown ?? ""}${more}`;
  } catch (error) {
    return `Read failed: ${error instanceof Error ? error.message : "unknown error"}`;
  }
}
```

```python Python theme={null}
import os

import requests


def post(path: str, body: dict) -> dict:
    response = requests.post(
        f"https://api.stophy.dev{path}",
        headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
        json=body,
    )
    answer = response.json()
    if not response.ok:
        raise RuntimeError(answer["error"])
    return answer


def search_web(query: str) -> str:
    try:
        data = post("/v1/search", {"query": query, "limit": 3})["data"]
    except RuntimeError as error:
        return f"Search failed: {error}"
    rows = [
        f"{row['title']}\n{row['url']}\n{row.get('description', '')}"
        for row in data.get("web", [])
    ]
    return "\n\n".join(rows) or "No results."


def read_page(url: str, offset: int | None = None) -> str:
    body = {"url": url, "maxChars": 1500}
    if offset is not None:
        body["offset"] = offset
    try:
        data = post("/v1/scrape", body)["data"]
    except RuntimeError as error:
        return f"Read failed: {error}"
    more = ""
    if "nextOffset" in data:
        more = f"\n\n[Cut here. Call again with offset {data['nextOffset']} to read on.]"
    return f"Source: {url}\n\n{data.get('markdown', '')}{more}"
```

`readPage` puts `Source: <url>` at the top of everything it returns. That line is what lets the agent cite.

## 4. Describe the tools to the model

Give the model one definition for each tool. The shape below works with the [Anthropic](https://docs.stophy.dev/integrations/anthropic.md), [OpenAI](https://docs.stophy.dev/integrations/openai.md) and [Vercel AI SDK](https://docs.stophy.dev/integrations/vercel-ai-sdk.md) tool calls, with the field names each one uses.

```json theme={null}
[
  {
    "name": "search_web",
    "description": "Search the web. Returns up to 3 results with a title, URL and snippet. It finds pages and does not read them.",
    "input_schema": {
      "type": "object",
      "properties": { "query": { "type": "string" } },
      "required": ["query"]
    }
  },
  {
    "name": "read_page",
    "description": "Read one page as markdown, 1,500 characters at a time. When the text says it was cut, call again with the offset it gives.",
    "input_schema": {
      "type": "object",
      "properties": { "url": { "type": "string" }, "offset": { "type": "integer" } },
      "required": ["url"]
    }
  }
]
```

Add one rule to the system prompt: answer only from text the tools returned, and end each claim with the `Source:` URL it came from.

## 5. Try the failures first

Before you connect a model, call each tool with input that fails. A page that is not public returns `400 invalidRequest`, and the tool turns it into text. This is the real error for `http://localhost/admin`.

```json theme={null}
{
  "success": false,
  "error": "url: Expected a public website URL",
  "code": "invalidRequest",
  "retryable": false,
  "requestId": "50e4b010-0a17-4760-a7c3-c73b457847cb"
}
```

`readPage("http://localhost/admin")` returned `Read failed: url: Expected a public website URL`. A failed call costs nothing.

## What to check

* The agent calls `search_web` first and `read_page` on one or two of the URLs it got back.
* Every URL in the answer appeared in a tool result. Open two of them and check the claim.
* A long page is read in parts with `offset`, not guessed from the first 1,500 characters.
* A failing tool leaves the loop running.

## What it costs

| Step | Price |
| - | - |
| Search of up to 10 results | \$0.001 |
| One page read | \$0.001 |
| A question with one search and two reads | \$0.003 |

A search with no results, and a page that cannot be read, cost nothing. See [Pricing](https://docs.stophy.dev/account/pricing.md).

## Related

* [Search](https://docs.stophy.dev/search/overview) for sources, filters and page text in the same call.
* [Scrape](https://docs.stophy.dev/scrape/overview) for formats such as `highlights`, which returns only the passages that match a query.
* [Rate limits](https://docs.stophy.dev/production/rate-limits.md) to keep a busy agent under its limits.
* [Research papers](https://docs.stophy.dev/recipes/research-papers.md) for an agent that reads scholarly papers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.