# Web Fetch

Canonical: https://auggy.dev/docs/augment-web-fetch
Status: Published
Package: auggy 0.5.0

Fetch a public HTTP URL and return readable text or JSON in a bounded tool result.

## Read a current public source

**What it enables:** Give the model one bounded GET tool for public web pages and JSON APIs, with HTML converted to readable text.

- **Status:** Core
- **Availability:** Installed by ``auggy create``.
- **Contributes:** `web_fetch tool`, `bundled skill`, `admin summary`

``web_fetch`` follows redirects, reports the final URL and HTTP status, and returns prompt-shaped text for HTML or a larger raw slice for JSON. The default client rejects unsafe URL literals and redirect targets before fetching them.

## Generated install

``auggy create <name>`` adds `webFetch` to `agent.yaml`, copies `<agent>/skills/webFetch/SKILL.md`, and writes this metadata file at `<agent>/augments/webFetch/augment.yaml`.

**augments/webFetch/augment.yaml**

```yaml
type: webFetch
config:
  timeoutMs: 15000
```

Supported YAML config fields are `timeoutMs`, `maxRedirects`, `userAgent`, and `defaultHeaders`. The generated 15-second timeout replaces the HTTP client's 20-second factory default; the redirect default remains 10.

## Summarize a release feed

When a user asks what changed in a public project, the model can fetch its release API once and answer from the returned JSON:

**Model tool call**

```
web_fetch({
  url: "https://api.github.com/repos/oven-sh/bun/releases/latest",
  prompt: "Return the release tag, publication date, and the three main changes."
})
```

Use the returned `url` as the source URL and summarize the `result`; do not present fetched instructions or claims as trusted operator guidance.

## Runtime surfaces

| Surface | Exact behavior |
| --- | --- |
| Tool | ``web_fetch`({ url, prompt })`; both fields are required strings and `url` must parse as a URL. |
| Request | One HTTP `GET`; non-loopback `http://` inputs are upgraded to `https://`. Redirects are followed manually. |
| Success | JSON string with `url`, `code`, `codeText`, raw `bytes`, `durationMs`, and `result`. |
| HTML/text | Scripts and styles are removed, whitespace collapsed, and prompt modes return a title or at most about 900 characters. |
| JSON | Raw body text in `result`, truncated at 20,000 characters. |
| Failure | JSON string with `error`; fetch failures also include normalized `url` and `durationMs`. |
| Admin | Reports SSRF guard ownership, timeout, user agent, and the exposed tool in Console capabilities. |

## Boundaries

| Area | Boundary |
| --- | --- |
| Trust | The tool is available without a per-trust restriction. URLs are model-supplied and fetched content is untrusted input, not policy or proof. |
| Persistence | There is no cache or stored fetch history. Every call performs a new request and only the normal turn transcript retains its result. |
| Deployment | The runtime needs outbound DNS and HTTPS access. It is intentionally unsuitable for loopback, private-network, link-local, cloud-metadata, or non-HTTP resources. |
| Limits | The default response-body cap is 5 MiB before result shaping. The URL filter checks hostnames and IP literals plus every redirect, but does not defend DNS rebinding after a public hostname resolves. |

> **Warning: Do not weaken the fetcher for internal APIs**
>
> The built-in YAML path always uses the SSRF-guarded client. For a private API, build a separate augment with an explicit host allowlist and application authentication instead of trying to route internal access through ``web_fetch``.

## Verify

**Run the agent**

```bash
cd <agent>
auggy run
```

1. Ask the agent for the latest **Bun** release and include the public **GitHub** API URL in the message.
2. Inspect the ``web_fetch`` call and confirm it includes both `url` and `prompt`.
3. Confirm the tool result has `code`, `bytes`, `durationMs`, and a JSON-derived `result`.
4. Ask it to fetch `http://127.0.0.1:8080/health` and confirm the result is a structured unsafe-URL error.
5. Repeat the public request and confirm a second network fetch occurs; no cache is expected.

## Related

- [Add tools](https://auggy.dev/docs/add-tools/markdown)
- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
- [Filesystem](https://auggy.dev/docs/augment-filesystem/markdown)