> ## 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 the source URL of each claim.

Give your agent a search tool and a page reader so it cites what it read instead of answering from memory. You need `STOPHY_API_KEY`. See the [Quickstart](https://docs.stophy.dev/quickstart.md).

## 1. Find pages

```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 results with a `url`, `title`, `description` and `position`. These are leads, not evidence. See [Search](https://docs.stophy.dev/search/overview) for sources and filters.

## 2. Read one page

`maxChars` keeps a long page from filling 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 }'
```

The text is in `data.markdown`. When it was cut, `data.nextOffset` says where the next part starts, and `data.warning` says so. Send the same request with `"offset": <nextOffset>` to read on. See [Content filtering](https://docs.stophy.dev/scrape/content-filtering.md).

## 3. Wrap both as tools

Return text the model can read, and turn an error into text so it can try another input. `Source: <url>` at the top of each page is what lets the agent cite.

```typescript theme={null}
import { Stophy, StophyError } from "stophy";

const stophy = new Stophy();

const failure = (action: string, error: unknown) =>
  `${action} failed: ${error instanceof StophyError ? error.message : "unknown error"}`;

export async function searchWeb(query: string): Promise<string> {
  try {
    const { data } = await stophy.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 failure("Search", error);
  }
}

export async function readPage(url: string, offset?: number): Promise<string> {
  try {
    const { data } = await stophy.scrape({ url, maxChars: 1500, offset });
    const more = data.nextOffset === undefined ? "" : `\n\n[Cut here. Call again with offset ${data.nextOffset}.]`;
    return `Source: ${url}\n\n${data.markdown ?? ""}${more}`;
  } catch (error) {
    return failure("Read", error);
  }
}
```

## 4. Describe the tools to the model

Register `search_web` with a required string `query`, and say it returns titles, URLs and snippets without reading pages. Register `read_page` with a required string `url` and an optional integer `offset`. Use your provider's schema, as in [LLM SDKs](https://docs.stophy.dev/integrations/llm-sdks.md).

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.

## Check it

* A non-public URL such as `http://localhost/admin` fails with `invalidRequest`, and the loop keeps running.
* The agent calls `search_web` first, then `read_page` on one or two results.
* Every URL in the answer appeared in a tool result. Open two and check the claim.
* A long page is read in parts with `offset`, not guessed from the first 1,500 characters.

See [Pricing](https://docs.stophy.dev/account/pricing.md) and [Rate limits](https://docs.stophy.dev/production/rate-limits.md) for a busy agent. For scholarly sources, see [Research papers](https://docs.stophy.dev/recipes/research-papers.md).


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