# Web search

> Give your agent real-time access to the web. The web search action pulls fresh results — with an optional generated answer and source links — for questions your indexed data can't cover.

Your indexed data is the agent's primary source of truth, but some questions need fresh, live information. The **Web search** action lets the agent look something up on the web in real time and ground its reply in the results.

> **POWERED BY TAVILY:** Web search runs through the Tavily search API. You provide a Tavily API key — either in the action config or via the `TAVILY_API_KEY` environment variable. Without a key, the action returns a clear "not configured" message instead of failing silently.

## Add the action

1. **Open Actions → Web search** — Add the web search action from your agent's Actions tab.
2. **Add your Tavily API key** — Paste a Tavily key into the action config, or set TAVILY_API_KEY for the workspace.
3. **Scope it (optional)** — Restrict results to specific domains, and choose whether to include images.
4. **Describe when to search** — Tell the agent to search only for things outside your knowledge — current events, live availability, third-party info.

## Configuration

Web search is a built-in of kind `web_search`. The action takes a `query` parameter from the model and supports these config options:

| Setting | Description | Default |
| --- | --- | --- |
| `api_key` | Your Tavily API key. Falls back to the `TAVILY_API_KEY` env var. | (env var) |
| `include_domains` | Limit results to these domains. Accepts an array or a comma-separated string. | (all domains) |
| `include_images` | Whether to return image results alongside text. | false |

Each search returns a short generated `answer`, up to five `results` (title, URL, and an excerpt), and optionally images. The agent uses these to compose a grounded reply with sources.

```json
{
  "kind": "web_search",
  "include_domains": ["yourbrand.com", "shippingcarrier.com"],
  "include_images": false
}
```

## When to use it

> **DON'T REPLACE YOUR KNOWLEDGE BASE WITH SEARCH:** Web search is a supplement, not a substitute. Your policies, products, and FAQs should live in your [data sources](/docs/agents/data-sources) so answers stay accurate and on-brand. Reserve web search for genuinely live or external questions.

- **Good fit** — current events, live third-party availability, public reference info not worth indexing.
- **Poor fit** — your return policy, your product catalog, your shipping times. Index those instead.

## FAQ

**Do I need my own Tavily account?**

Yes. Web search uses Tavily; supply a Tavily API key in the action config or as the TAVILY_API_KEY environment variable.

**Can I limit which sites it searches?**

Yes. Set include_domains to one or more domains to constrain results — useful for keeping the agent on trusted sources.

**What if no key is set?**

The action returns a "not configured" message telling you to add a key, rather than erroring or returning nothing.

## What's next

- [Data sources](/docs/agents/data-sources) — Index your own content as the agent's primary knowledge.
- [Response quality](/docs/getting-started/response-quality) — How grounding and citations keep answers trustworthy.
- [Custom action](/docs/actions/custom-action) — Call your own API when web search isn't enough.