Tavily
Tavily web search and content extraction for Bijection applications
git clone https://github.com/bijectionhq/tavily.git
cd tavily
git checkout 09a5a5feeb54da1dc1d1534a275cfaa93e32644eBijection repository access is required. Request access.
Description
Tavily web search and content extraction for Bijection applications
Explore the package README for API concepts, configuration, and examples. Check the Bijection source for adaptation-specific setup.
Review the source and its dependencies before adopting this package. Source availability does not establish npm publication or runtime qualification.
Getting started
- Get the source at the revision above and read its package documentation.
- Check the required Bijection SDK version, dependencies, and external service credentials.
- Follow the package setup instructions and the guide to using components.
- Exercise the component in your deployment according to your project’s verification rules.
Open source
Maintained source: bijectionhq/tavily. Based on tavily-ai/convex-tavily. License: Apache-2.0. Consult the repository for license terms, notices, and contributor attribution.
From the upstream publisher
Tavily web search and content extraction for Convex applications
Explore the demo ↗Upstream overview
From the upstream package documentation.
convex-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.
Use cases
From the upstream package documentation.
- Adding real-time web search to an AI agent or chatbot that needs up-to-date information beyond its training data
- Extracting structured content from a known list of URLs for ingestion into a Convex-backed RAG pipeline
- Building a research tool that needs both discovery (search) and content retrieval (extract) in the same Convex action
- Centralizing Tavily API key management across a team so individual developers do not handle credentials directly
- Wrapping search or extraction calls in application-owned actions to enforce authentication, authorization, or rate limiting before hitting the Tavily API
How it works
From the upstream package documentation.
The component is registered in convex/convex.config.ts using app.use(tavily, ...), which scopes the TAVILY_API_KEY environment variable to the component rather than the top-level app. This keeps credential handling isolated and typed via Convex's environment configuration system.
Application code instantiates a TavilyClient with new TavilyClient(components.tavily) and calls it from within application-owned Convex actions. The client provides two methods: search(ctx, args) for web search with options like searchDepth (basic or advanced), maxResults, timeRange, and image/favicon toggles, and extract(ctx, args) for fetching and processing up to 20 URLs with query-focused chunking, image extraction, and markdown formatting.
The request flow goes from the application action through TavilyClient to ctx.runAction(components.tavily.lib.search) or .extract, which then makes the outbound POST request to api.tavily.com. Keeping the wrapper action in the application layer gives developers a natural place to add auth checks or rate limiting before the external call is made.
The component is stateless and does not write to any Convex tables, so there is no schema migration or data lifecycle to manage.
Upstream package FAQ
What Tavily API methods does @tavily/convex-tavily expose?
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.
Does @tavily/convex-tavily create any database tables in my Convex deployment?
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.
How does the request flow work between my Convex app and Tavily?
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.
Can I add authentication or rate limiting to the Tavily integration?
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.
How do I configure the Tavily API key in a Convex project?
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.
Use with agents and CLI
Give your coding agent the component’s source identity and setup guidance.
Help me integrate Tavily with Bijection.
Read: https://bijection.com/components/tavily/SKILL.md
Check SDK compatibility and dependency availability.
Follow this project's execution and verification rules.Upstream README.md
View repository ↗Documentation from tavily-ai/convex-tavily, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.
convex-tavily
Tavily web search and content extraction for Convex applications.
This package installs Tavily as an isolated Convex component. Application actions call a typed TavilyClient, which delegates to component actions and keeps TAVILY_API_KEY in typed Convex environment configuration.
Install
npm install @tavily/convex-tavily
Configure Convex
Add the component to convex/convex.config.ts:
import { defineApp } from "convex/server";
import { v } from "convex/values";
import tavily from "@tavily/convex-tavily/convex.config";
const app = defineApp({
env: {
TAVILY_API_KEY: v.string(),
},
});
app.use(tavily, {
name: "tavily",
env: {
TAVILY_API_KEY: app.env.TAVILY_API_KEY,
},
});
export default app;
Set your key:
npx convex env set TAVILY_API_KEY tvly-your-key
Search the web
Call the component from an application-owned action. Keeping this wrapper in the app gives you a place to add authentication, authorization, and rate limiting.
import { action } from "./_generated/server";
import { components } from "./_generated/api";
import { TavilyClient } from "@tavily/convex-tavily";
import { v } from "convex/values";
const tavily = new TavilyClient(components.tavily);
export const searchWeb = action({
args: { query: v.string() },
handler: async (ctx, args) => {
return await tavily.search(ctx, {
query: args.query,
searchDepth: "advanced",
maxResults: 5,
includeAnswer: false,
includeFavicon: true,
});
},
});
Extract known pages
export const extractPages = action({
args: {
urls: v.array(v.string()),
query: v.optional(v.string()),
},
handler: async (ctx, args) => {
return await tavily.extract(ctx, {
urls: args.urls,
query: args.query,
chunksPerSource: args.query ? 3 : undefined,
extractDepth: "advanced",
format: "markdown",
});
},
});
Request flow
App client
-> application Convex action
-> TavilyClient.search/extract
-> ctx.runAction(components.tavily.lib.search/extract)
-> POST https://api.tavily.com/search or /extract
Current API
search(ctx, args)— Search (basic/advanceddepth,timeRange, images/favicon/usage knobs).extract(ctx, args)— Extract up to 20 URLs, including query-focused chunks, images, timeout.
The component is stateless and owns no database tables.
Development
npm install
cd example && npm install && cd ..
npm run build:codegen
npm test
npm run lint
npm run typecheck
Component code generation may require a configured Convex development deployment.