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

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Search the web and research topics with Tavily agents

> Connect Guild agents to Tavily to search the web, extract page content, crawl and map sites, and run multi-source research tasks with governed credentials.

Integrations · Tavily

Guild agents use Tavily to search the web, extract page content, crawl sites, and run multi-source research without leaving your platform. Guild stores the Tavily API key server-side and injects it through the credential proxy, so agent code never sees the secret. Credential policies let you restrict which Tavily operations each agent or workspace can call.

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Tavily.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Tavily to your first agent.

## What the Tavily integration exposes

The integration provides tools that cover web search, URL content extraction (single URL or batches of up to 20), graph-based site crawling, site mapping, and multi-source research that runs searches, analyzes sources, and returns a report. Tools for retrieving research task status, checking account usage, pulling per-request logs, and submitting result feedback are also included.

## How it works

**1. Open credentials settings**

In Guild, go to Access & setup > Credentials. The page lists connected credentials and shows a gallery of available integrations.

**2. Connect the Tavily API key**

Click Connect, select tavily-openapi, and paste your Tavily API key into the API Key field. Guild sends the key as a bearer token in the Authorization header on every request.

**3. Import tools into your agent**

Import TavilyOpenapiTools from the integration package and spread it into your agent's tools object. Use pick() to include only the specific tools your agent needs.

## Why Tavily access needs governing

Tavily credentials give an agent the ability to search the web, extract content from arbitrary URLs, crawl sites, and retrieve account-level usage and billing data. Guild stores the API key server-side and injects it through the credential proxy, so the key never enters agent code, containers, prompts, or state. See [Security architecture](https://docs.guild.ai/platform/security-architecture.md) for how the proxy works.

Credential policies let you write ALLOW and DENY rules that the proxy enforces before any request reaches Tavily. You can restrict specific operations, scope rules to individual agents or workspaces, and block mutating calls while permitting read operations. Scoping a credential to one workspace, one member, or one agent limits blast radius if something goes wrong. Without scoped rules the credential starts with an allow-all policy; delete that default once your rules cover everything agents should reach. See [Credential policies](https://docs.guild.ai/platform/credential-policies.md) and [Credentials](https://docs.guild.ai/platform/credentials.md).

## About the Tavily integration

This integration connects Guild agents to the Tavily REST API for web intelligence tasks. Agents can search the web, extract content from URLs, crawl and map websites, and conduct comprehensive multi-source research. Account and usage management tools are also available. The integration is `guildai~tavily-openapi`.

## Authentication

* **Type:** API key
* **Header:** Guild sends the key as a bearer token in the `Authorization` header

### Setup

**1. Connect Tavily**

In Guild, go to **Access & setup > Credentials**, click **Connect**, select **tavily-openapi**, and paste the key into **API Key**.

See [Credentials](https://docs.guild.ai/platform/credentials.md) for workspace, member, and agent-scoped credentials.

## Usage

```typescript theme={null}
import { TavilyOpenapiTools } from "@guildai-services/guildai~tavily-openapi"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  systemPrompt: "You work with Tavily.",
  tools: { ...TavilyOpenapiTools },
})
```

### Selecting specific tools

Tools are named with the `tavily_openapi_` prefix. Use [`pick()`](https://docs.guild.ai/sdk/tools#selecting-specific-tools) to include only what your agent needs.

## Tools

Tools in the latest published version of `guildai~tavily-openapi`:

| Tool | What it does |
| - | - |
| `tavily_openapi_crawl` | Tavily Crawl is a graph-based website traversal tool that can explore hundreds of paths in parallel with built-in extraction and intelligent discovery. |
| `tavily_openapi_create_research` | Tavily Research performs comprehensive research on a given topic by conducting multiple searches, analyzing sources, and generating a detailed research report. |
| `tavily_openapi_extract` | Extract content from one URL or batch up to 20 URLs in one request. |
| `tavily_openapi_get_research` | Retrieve the status and results of a research task using its request ID. |
| `tavily_openapi_get_usage` | Get API key and account usage details |
| `tavily_openapi_map` | Tavily Map traverses websites like a graph and can explore hundreds of paths in parallel with intelligent discovery to generate comprehensive site maps. |
| `tavily_openapi_post_feedback` | Submit feedback on how relevant and useful Tavily's results were for your task. |
| `tavily_openapi_post_logs` | Retrieve per-request usage logs for the API keys under your account or organization. |
| `tavily_openapi_post_org_usage` | Retrieve usage (credits), pay-as-you-go USD cost, and request counts for every API key under an organization you own, mirroring the platform's Usage analytics page. |
| `tavily_openapi_search` | Execute a search query using Tavily Search. |

## Frequently asked questions

> [accordion] Can I limit which Tavily operations a specific agent can call?
>
> Yes. Credential policies support ALLOW and DENY rules scoped to individual agents. You can permit operations like tavily\_openapi\_search and tavily\_openapi\_extract while denying tavily\_openapi\_post\_org\_usage for agents that have no reason to read billing data. See [Credential policies](https://docs.guild.ai/platform/credential-policies.md).

> [accordion] Does the agent code ever see the Tavily API key?
>
> No. Guild's credential proxy injects the key as a bearer token in the Authorization header server-side, after the policy check passes. The key never enters the agent's code, container, prompt, or state.

> [accordion] Can I use a different Tavily account in one workspace than the rest of my organization uses?
>
> Yes. Connect a workspace-scoped credential from the workspace's Credentials page and choose The whole workspace. Guild will use that credential for agents in that workspace ahead of the organization-wide default. See [Credentials](https://docs.guild.ai/platform/credentials.md).

> [accordion] Does Tavily send webhook events to Guild?
>
> Not yet. The catalog entry for guildai\~tavily-openapi lists no webhook events, so event-driven triggers from Tavily are not available through this integration.

## Put a governed agent on Tavily this week

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Tavily.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Tavily to your first agent.

## Related

**Also runs on Guild:** [Browserbase](https://docs.guild.ai/integrations/browserbase.md) · [Firecrawl](https://docs.guild.ai/integrations/firecrawl.md) · [Pinecone](https://docs.guild.ai/integrations/pinecone.md)

**Read:** Docs: [Credential policies](https://docs.guild.ai/platform/credential-policies.md) · [Credentials](https://docs.guild.ai/platform/credentials.md) · [Tools in agents](https://docs.guild.ai/sdk/tools.md)