Loading components
You.com Search
Convex component that adds cached You.com web search to your backend, with reactive query support and a built-in agent tool for @convex-dev/agent.
Installation
npm install @youdotcom-oss/convex-searchBenefits
- Search the live web from Convex actions without an API key, using You.com's free profile for up to 100 searches per day
- Cache search results in your Convex deployment with a configurable TTL so repeated queries are served from your database instead of hitting the network
- Subscribe to cached results from a Convex query so your UI updates reactively when new search results land
- Plug a ready-made webSearch tool into @convex-dev/agent to give any agent access to current web results with no extra wiring
Use cases
how to add web search to a Convex AI agent
The @youdotcom-oss/convex-search component exports a youSearchTool function that wraps a YouSearch client and returns a tool compatible with @convex-dev/agent. Pass it to the tools option when constructing an Agent and the agent can call webSearch with a query, optional count, and optional freshness filter. Results use the same TTL cache as direct searches.
how to cache web search results in Convex
YouSearch automatically stores every successful search result in the component's searches table, keyed by a hash of the normalized parameters. Subsequent calls with the same parameters return cached: true and skip the network request until the TTL expires. You can read cached results from a Convex query using getCached so a subscribed UI updates reactively when new results arrive.
how to do RAG with live web search in Convex
Use the YouSearch.search action to retrieve current web results, then pass the returned snippets or full page content from YouSearch.contents into your LLM context. The component integrates directly with @convex-dev/agent via youSearchTool, making it straightforward to build retrieval-augmented generation pipelines that ground answers in up-to-date web data.
how to read full page content from search results in Convex
The YouSearch.contents method accepts an array of up to 10 URLs and returns their full content as markdown, HTML, or metadata. It calls the You.com Contents API and requires a YDC_API_KEY environment variable. Results are returned in request order with url, title, and markdown fields, or an error field if a URL could not be fetched.
Frequently asked questions
Do I need a You.com API key to use this component?
No. The @youdotcom-oss/convex-search component works without an API key by calling the You.com free MCP profile, which allows 100 searches per day. For higher volume, set the YDC_API_KEY environment variable on your Convex deployment to use the keyed API, which supports up to 100 results per search. The contents method for fetching full page content always requires a key.
How does caching work in the You.com Search component?
Every successful search is stored in the component's searches table, keyed by a hash of the normalized query parameters including whether the call was keyless or keyed. The default TTL is one hour and the maximum is 30 days. Pass force: true to skip the cache and fetch fresh results, or call invalidate to remove a specific entry. A built-in cron deletes expired rows every hour.
How do I make my UI update reactively when search results change?
Define a Convex query that calls youSearch.getCached with the query parameters and subscribe to it on the client using useQuery. When a search action writes new results to the cache, Convex automatically re-runs the query and pushes the update to subscribed clients. This means your UI reflects new results without polling.
How do I add this component to my Convex project?
Install the package with npm install @youdotcom-oss/convex-search, then add app.use(youSearch) in your convex/convex.config.ts file after importing youSearch from @youdotcom-oss/convex-search/convex.config.js. Run npx convex dev to generate the components.youSearch binding, then instantiate new YouSearch(components.youSearch) in your function files. Convex 1.43 or later is required.
Can I test code that uses this component without making live network requests?
Yes. The package exports a helper for convex-test from @youdotcom-oss/convex-search/test. Import it, call youSearch.register(t) on your convexTest instance, and then stub global fetch to prevent live calls to the You.com API during unit tests.
Links
Components
Open-source building blocks for your Convex app
Browse components in this category.