Add Tavily web search and content extraction to Convex apps via a stateless component that keeps your API key in typed environment config.
npm install @tavily/convex-tavilyconvex-tavily installs Tavily web search and content extraction as an isolated Convex component. It exposes a typed `TavilyClient` that wraps Tavily's search and extract APIs, routing calls through component actions so the `TAVILY_API_KEY` stays in Convex environment configuration rather than scattered across application code. The component is stateless and owns no database tables.
The @tavily/convex-tavily component exposes a TavilyClient that you instantiate with components.tavily and call from your own Convex action. The tavily.search method accepts a query string plus options like searchDepth, maxResults, timeRange, and includeFavicon, then delegates the HTTP call to the component action so your API key never touches application code.
The tavily.extract method accepts an array of up to 20 URLs and an optional query string, returning chunked content per source in markdown format. Setting chunksPerSource alongside the query enables query-focused extraction, making it straightforward to feed retrieved content into an embedding or LLM pipeline hosted in Convex.
Install @tavily/convex-tavily, wire it into convex.config.ts, and call tavily.search from an action that your agent invokes. The component is stateless and owns no database tables, so it adds no schema overhead while giving the agent access to live search results and extracted page content.
The convex-tavily component uses typed Convex environment configuration to hold TAVILY_API_KEY. You set it with npx convex env set TAVILY_API_KEY and pass it to the component via app.env in convex.config.ts, keeping the key scoped to the component rather than exposed in application environment variables.
The @tavily/convex-tavily component currently exposes two methods on TavilyClient: search, which supports basic and advanced depth, timeRange, images, favicon, and usage options; and extract, which accepts up to 20 URLs with optional query-focused chunking, image extraction, format selection, and a timeout parameter.
No. The @tavily/convex-tavily component is entirely stateless and owns no database tables. It acts as a typed proxy between your application actions and the Tavily HTTP API, adding no schema overhead to your deployment.
Your application action calls TavilyClient.search or TavilyClient.extract, which uses ctx.runAction to invoke the component action inside the isolated component. The component action then makes a POST request to api.tavily.com/search or /extract. Your app code never calls the Tavily API directly.
Yes. The recommended pattern is to keep TavilyClient calls inside your own application-owned Convex actions rather than exposing the component directly. This gives you a single place to add authentication checks, authorization logic, and rate limiting before the search or extract call reaches the component.
In convex.config.ts, declare TAVILY_API_KEY as a typed environment variable using v.string(), then pass it to the component via app.env when calling app.use(tavily, ...). Set the actual key value by running npx convex env set TAVILY_API_KEY tvly-your-key from your project root.