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

# Web research

> Enable optional web search, page reading, and multi-source research tools.

Agents can search and read the public web when an
[Agentic Web Research](https://github.com/ricsam/agentic-web-research) service is
configured. The integration is entirely optional and disabled by default.

## Enable it

The tools appear only when **both** variables are present in the control-plane
environment:

```dotenv theme={null}
AWR_BASE_URL=https://research.example.com
AWR_API_KEY=awr_...
```

Add both keys to your existing Secret and restart the control plane:

```bash theme={null}
kubectl -n r5d-chat patch secret r5d-chat-secrets \
  --type merge -p "$(jq -n \
    --arg url "$(printf 'https://research.example.com' | base64 -w0)" \
    --arg key "$(printf 'awr_your_key' | base64 -w0)" \
    '{data: {AWR_BASE_URL: $url, AWR_API_KEY: $key}}')"

kubectl -n r5d-chat rollout restart deployment/r5d-chat-r5d-chat
kubectl -n r5d-chat rollout status deployment/r5d-chat-r5d-chat
```

Confirm the tools appear in a new chat run. Removing either variable disables
them cleanly.

## The tools

<ResponseField name="web_search" type="tool">
  Searches the public web and returns concise result metadata.

  | Parameter | Type            | Default  |
  | --------- | --------------- | -------- |
  | `query`   | string          | required |
  | `limit`   | integer, max 10 | 5        |
</ResponseField>

<ResponseField name="web_read" type="tool">
  Renders one public URL and returns clean Markdown.

  | Parameter | Type   | Default  |
  | --------- | ------ | -------- |
  | `url`     | string | required |
</ResponseField>

<ResponseField name="web_research" type="tool">
  Delegates a broad multi-source research task and returns cited results.

  | Parameter  | Type            | Default         |
  | ---------- | --------------- | --------------- |
  | `query`    | string          | required        |
  | `maxDepth` | integer, max 5  | service default |
  | `maxPages` | integer, max 20 | service default |
</ResponseField>

## How requests flow

The **control plane** calls the research service, not the browser and not the
workspace pod. Requests carry the API key as a bearer token, pass through the
standard outbound URL guard, and have a 180-second timeout. Streaming responses
are collected and truncated to a bounded size before reaching the model.

```mermaid theme={null}
flowchart LR
    A[Browser] --> B[Control plane]
    B --> C[Research service]
    B --> D[Workspace pod]
```

This means workspace pods never need the research credential, and disabling
workspace internet egress does not disable these tools.

<Note>
  The agent can also reach the web from inside the workspace with `curl` when
  `networkPolicy.workspaceInternetEgress` is enabled. These tools are for clean,
  structured retrieval; the workspace shell is for arbitrary network work.
</Note>

## Security notes

<AccordionGroup>
  <Accordion title="Treat retrieved content as untrusted" icon="triangle-exclamation">
    Web pages can contain prompt-injection text aimed at the agent. Content
    returned by these tools reaches the model, so avoid pairing broad web access
    with high-privilege MCP tools unless you have reviewed that risk.
  </Accordion>

  <Accordion title="Keep the API key in the Secret" icon="key">
    The key grants use of your research quota. Store it in the Kubernetes Secret,
    never in a values file committed to Git.
  </Accordion>

  <Accordion title="Costs scale with depth" icon="coins">
    `web_research` fetches many pages per call. Constrain `maxDepth` and
    `maxPages` at the service if usage needs a ceiling.
  </Accordion>
</AccordionGroup>