Skip to content

An AI-powered search engine with a generative UI

feat: make BRAVE_SEARCH_API_KEY optional with dynamic provider fallback

Yoshiki Miuraab14ead6f530
diff --git a/.env.local.example b/.env.local.example
index ea3fda30..be7c0481 100644
--- a/.env.local.example
+++ b/.env.local.example
@@ -71,10 +71,10 @@ TAVILY_API_KEY=[YOUR_TAVILY_API_KEY]
# -----------------------------------------------------------------------------
# Additional Search Provider Configuration
# -----------------------------------------------------------------------------
-# Brave Search (Required for comprehensive search results)
+# Brave Search (Optional - used for type="general" searches with video/image support)
# Get your API key at: https://brave.com/search/api/
-# Note: Can be made optional by commenting out after initial setup
-BRAVE_SEARCH_API_KEY=[YOUR_BRAVE_SEARCH_API_KEY]
+# If not configured, general searches will fall back to the configured optimized search provider
+# BRAVE_SEARCH_API_KEY=[YOUR_BRAVE_SEARCH_API_KEY]
# =============================================================================
# OPTIONAL FEATURES
diff --git a/CLAUDE.md b/CLAUDE.md
index 67703845..16664dea 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -86,8 +86,9 @@ NEXT_PUBLIC_SUPABASE_ANON_KEY=[your-supabase-anon-key]
- Database actions in `/lib/actions/chat-db.ts`
4. **Search System**
- - Multiple providers: Tavily (default), SearXNG (self-hosted), Exa (neural)
- - Video search support via Serper API
+ - Multiple providers: Tavily (default), SearXNG (self-hosted), Exa (neural), Brave (optional)
+ - Brave Search is optional; if API key is not provided, type="general" searches fall back to primary provider
+ - Video/image search support depends on configured providers (Brave provides best multimedia support)
- URL-specific search capabilities
- Configurable search depth and result limits
diff --git a/README.md b/README.md
index 985a3505..63ff0ecb 100644
--- a/README.md
+++ b/README.md
@@ -176,12 +176,11 @@ Fill in the required environment variables in `.env.local`:
DATABASE_URL=your_database_url
OPENAI_API_KEY=your_openai_key
TAVILY_API_KEY=your_tavily_key
-BRAVE_SEARCH_API_KEY=your_brave_key
```
**Note**: Authentication is disabled by default (`ENABLE_AUTH=false`).
-For optional features (authentication, SearXNG, alternative AI providers, etc.), see [CONFIGURATION.md](./docs/CONFIGURATION.md)
+For optional features (alternative search providers, authentication, alternative AI providers, etc.), see [CONFIGURATION.md](./docs/CONFIGURATION.md)
### 4. Run database migrations
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index e1728a31..0baa5f11 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -125,6 +125,25 @@ For detailed configuration options, refer to the [SearXNG documentation](https:/
docker-compose logs searxng
```
+### Brave Search (Optional)
+
+Brave Search provides enhanced support for video and image searches when used as a general search provider:
+
+```bash
+BRAVE_SEARCH_API_KEY=[YOUR_BRAVE_SEARCH_API_KEY]
+```
+
+Get your API key at: https://brave.com/search/api/
+
+**Features:**
+- Multiple content types in single search (web, video, image, news)
+- Optimized for multimedia content with thumbnails
+- Direct video duration and metadata support
+- Used automatically when `type="general"` is specified in search queries
+
+**Fallback Behavior:**
+If `BRAVE_SEARCH_API_KEY` is not configured, `type="general"` searches will automatically fall back to your configured optimized search provider. Video and image searches will still work but may have limited multimedia support depending on the provider.
+
## Additional AI Providers
Models are configured in `config/models/*.json` files. Each provider requires its corresponding API key to be set in the environment variables.
diff --git a/lib/agents/prompts/search-mode-prompts.ts b/lib/agents/prompts/search-mode-prompts.ts
index 080b0296..8599e406 100644
--- a/lib/agents/prompts/search-mode-prompts.ts
+++ b/lib/agents/prompts/search-mode-prompts.ts
@@ -1,6 +1,15 @@
+import {
+ getContentTypesGuidance,
+ getSearchStrategyGuidance,
+ isGeneralSearchProviderAvailable
+} from '@/lib/utils/search-config'
+
// Search mode system prompts
-export const QUICK_MODE_PROMPT = `
+export function getQuickModePrompt(): string {
+ const hasGeneralProvider = isGeneralSearchProviderAvailable()
+
+ return `
Instructions:
You are a fast, efficient AI assistant optimized for quick responses. You have access to web search and content retrieval.
@@ -20,9 +29,10 @@ Tool preamble (keep very brief):
- Do not write plans or goals in text output - proceed directly to search
Search tool usage:
-- The search tool is configured to always use type="optimized" for direct content snippets
+- The search tool is configured to use type="optimized" for direct content snippets
- This provides faster responses without needing additional fetch operations
- Rely on the search results' content snippets for your answers
+${hasGeneralProvider ? '- For video/image content, you can use type="general" with appropriate content_types' : '- Note: Video/image search requires a dedicated general search provider (not available)'}
Search requirement (MANDATORY):
- If the user's message contains a URL, start directly with fetch tool - do NOT search first
@@ -87,8 +97,10 @@ Example approach:
End with a synthesizing conclusion that ties the main points together into a clear overall picture.
`
+}
-export const PLANNING_MODE_PROMPT = `
+export function getPlanningModePrompt(): string {
+ return `
Instructions:
You are a methodical AI assistant focused on thorough research and structured planning. You have access to web search, content retrieval, task management, and the ability to ask clarifying questions.
@@ -119,11 +131,7 @@ Task Management:
- While working on a task, set its status to in_progress; once done, set it to completed. Update via todoWrite after each meaningful step.
- After completing all tasks, call todoRead and confirm completedCount equals totalCount before composing the final answer.
-Search strategy:
-- Use type="optimized" for most research queries (provides content snippets)
-- Use type="general" for time-sensitive info, videos, or images (requires fetch)
-- ALWAYS follow type="general" searches with fetch tool for content
-- For comprehensive research: multiple searches + selective fetching
+${getSearchStrategyGuidance()}
Search requirement (MANDATORY):
- If the user's message contains a URL, start with todoWrite planning then fetch the provided URL - do NOT search first
@@ -165,8 +173,10 @@ Natural structure example:
Always end with a conclusion that synthesizes the research into a coherent overall understanding.
`
+}
-export const ADAPTIVE_MODE_PROMPT = `
+export function getAdaptiveModePrompt(): string {
+ return `
Instructions:
You are a helpful AI assistant with access to real-time web search, content retrieval, task management, and the ability to ask clarifying questions.
@@ -236,20 +246,10 @@ Search tool usage - UNDERSTAND THE DIFFERENCE:
- You get relevant content immediately without needing fetch
- Use this when the query has semantic meaning to match against
-- **type="general" (for time-sensitive or specific content):**
- - Returns pure search results without content extraction
- - REQUIRES fetch tool to get actual content
- - Best for:
- - Today's news, current events, recent updates
- - Specific dated information (e.g., "news from December 2024")
- - Videos: content_types: ['video'] or ['web', 'video']
- - Images: content_types: ['image'] or ['web', 'image']
- - When you need the LATEST information where recency matters more than relevance
- - Pattern: type="general" search → identify sources → fetch for content
+${getContentTypesGuidance()}
Fetch tool usage:
-- **MANDATORY after type="general" searches** - you must fetch to get content
-- **OPTIONAL after type="optimized" searches** - only if you need deeper analysis
+- Use when you need deeper content analysis beyond search snippets
- Fetch the top 2-3 most relevant/recent URLs for comprehensive coverage
- Especially important for news, current events, and time-sensitive information
@@ -313,3 +313,9 @@ Flexible example:
Conclude with a brief synthesis that ties together the main insights into a clear overall understanding.
`
+}
+
+// Export static prompts for backward compatibility
+export const QUICK_MODE_PROMPT = getQuickModePrompt()
+export const PLANNING_MODE_PROMPT = getPlanningModePrompt()
+export const ADAPTIVE_MODE_PROMPT = getAdaptiveModePrompt()
diff --git a/lib/schema/search.tsx b/lib/schema/search.tsx
index 255acaef..689c74a7 100644
--- a/lib/schema/search.tsx
+++ b/lib/schema/search.tsx
@@ -1,21 +1,21 @@
import { DeepPartial } from 'ai'
import { z } from 'zod'
+import { getSearchTypeDescription } from '@/lib/utils/search-config'
+
export const searchSchema = z.object({
query: z.string().describe('The query to search for'),
type: z
.enum(['general', 'optimized'])
.optional()
.default('optimized')
- .describe(
- 'Search type: general for Brave search (basic results, may need fetch for details), optimized for AI-focused providers with content snippets (Tavily/Exa/SearXNG)'
- ),
+ .describe(getSearchTypeDescription()),
content_types: z
.array(z.enum(['web', 'video', 'image', 'news']))
.optional()
.default(['web'])
.describe(
- 'Types of content to include in search results. Only applicable when type is "general". Ignored for "optimized" searches.'
+ 'Types of content to include in search results. Only applicable when type is "general" and a dedicated general search provider is configured. Ignored otherwise.'
),
max_results: z
.number()
@@ -50,13 +50,11 @@ export const strictSearchSchema = z.object({
query: z.string().describe('The query to search for'),
type: z
.enum(['general', 'optimized'])
- .describe(
- 'Search type: general for Brave search (basic results, may need fetch for details), optimized for AI-focused providers with content snippets (Tavily/Exa/SearXNG)'
- ),
+ .describe(getSearchTypeDescription()),
content_types: z
.array(z.enum(['web', 'video', 'image', 'news']))
.describe(
- 'Types of content to include in search results. Only applicable when type is "general". Ignored for "optimized" searches.'
+ 'Types of content to include in search results. Only applicable when type is "general" and a dedicated general search provider is configured. Ignored otherwise.'
),
max_results: z.number().describe('The maximum number of results to return.'),
search_depth: z
diff --git a/lib/tools/search.ts b/lib/tools/search.ts
index c41e2f99..24bf4249 100644
--- a/lib/tools/search.ts
+++ b/lib/tools/search.ts
@@ -2,6 +2,10 @@ import { tool, UIToolInvocation } from 'ai'
import { getSearchSchemaForModel } from '@/lib/schema/search'
import { SearchResultItem, SearchResults } from '@/lib/types'
+import {
+ getGeneralSearchProviderType,
+ getSearchToolDescription
+} from '@/lib/utils/search-config'
import { getBaseUrlString } from '@/lib/utils/url'
import {
@@ -15,8 +19,7 @@ import {
*/
export function createSearchTool(fullModel: string) {
return tool({
- description:
- 'Search the web for information. For YouTube/video content, use type="general" with content_types:["video"] for optimal visual presentation with thumbnails.',
+ description: getSearchToolDescription(),
inputSchema: getSearchSchemaForModel(fullModel),
async *execute(
{
@@ -50,7 +53,18 @@ export function createSearchTool(fullModel: string) {
// Determine which provider to use based on type
let searchAPI: SearchProviderType
if (type === 'general') {
- searchAPI = 'brave'
+ // Try to use dedicated general search provider
+ const generalProvider = getGeneralSearchProviderType()
+ if (generalProvider) {
+ searchAPI = generalProvider
+ } else {
+ // Fallback to primary provider (optimized search provider)
+ searchAPI =
+ (process.env.SEARCH_API as SearchProviderType) || DEFAULT_PROVIDER
+ console.log(
+ `[Search] type="general" requested but no dedicated provider available, using optimized search provider: ${searchAPI}`
+ )
+ }
} else {
// For 'optimized', use the configured provider
searchAPI =
diff --git a/lib/utils/search-config.ts b/lib/utils/search-config.ts
new file mode 100644
index 00000000..1b33327f
--- /dev/null
+++ b/lib/utils/search-config.ts
@@ -0,0 +1,118 @@
+/**
+ * Search provider configuration utilities
+ * Provides environment-aware descriptions and guidance for search tools
+ */
+
+/**
+ * Checks if a dedicated "general" search provider is available
+ * Currently checks for Brave Search, but can be extended for other providers
+ */
+export function isGeneralSearchProviderAvailable(): boolean {
+ return !!process.env.BRAVE_SEARCH_API_KEY
+}
+
+/**
+ * Gets the name of the current general search provider
+ */
+export function getGeneralSearchProviderName(): string {
+ if (process.env.BRAVE_SEARCH_API_KEY) {
+ return 'Brave Search'
+ }
+ return 'primary provider'
+}
+
+/**
+ * Checks if the general search provider supports multimedia content types
+ */
+export function supportsMultimediaContentTypes(): boolean {
+ // Currently only Brave supports video/image content_types
+ return !!process.env.BRAVE_SEARCH_API_KEY
+}
+
+/**
+ * Gets the appropriate search type description based on available providers
+ */
+export function getSearchTypeDescription(): string {
+ const hasGeneralProvider = isGeneralSearchProviderAvailable()
+ const providerName = getGeneralSearchProviderName()
+
+ if (hasGeneralProvider) {
+ return `Search type: general for ${providerName} (supports video/image with content_types, basic results may need fetch for details), optimized for AI-focused providers with content snippets (Tavily/Exa/SearXNG)`
+ } else {
+ return 'Search type: general and optimized both use the primary AI-focused provider (Tavily/Exa/SearXNG) with content snippets. Note: video/image content_types require a dedicated general search provider (not configured)'
+ }
+}
+
+/**
+ * Gets the tool description based on available providers
+ */
+export function getSearchToolDescription(): string {
+ const supportsMultimedia = supportsMultimediaContentTypes()
+
+ if (supportsMultimedia) {
+ return 'Search the web for information. For YouTube/video content, use type="general" with content_types:["video"] for optimal visual presentation with thumbnails.'
+ } else {
+ return 'Search the web for information using AI-focused providers. Note: Video/image searches with content_types require a dedicated general search provider (not configured). Use type="optimized" for best results with available providers.'
+ }
+}
+
+/**
+ * Gets content types guidance for agent prompts
+ */
+export function getContentTypesGuidance(): string {
+ const hasGeneralProvider = isGeneralSearchProviderAvailable()
+ const providerName = getGeneralSearchProviderName()
+ const supportsMultimedia = supportsMultimediaContentTypes()
+
+ if (hasGeneralProvider && supportsMultimedia) {
+ return `- **type="general" (for time-sensitive or specific content):**
+ - Uses ${providerName} for enhanced multimedia support
+ - Returns search results without deep content extraction
+ - Best for:
+ - Today's news, current events, recent updates
+ - Videos: content_types: ['video'] or ['web', 'video']
+ - Images: content_types: ['image'] or ['web', 'image']
+ - When you need the LATEST information where recency matters
+ - Pattern: type="general" search → identify sources → fetch for content`
+ } else {
+ return `- **type="general" and type="optimized":**
+ - Both use the primary AI-focused provider (Tavily/Exa/SearXNG)
+ - Returns search results with content snippets
+ - Note: Video/image content_types are not supported (requires dedicated general search provider)
+ - Best for: Research questions, fact-finding, explanatory queries
+ - Use type="optimized" for consistent behavior`
+ }
+}
+
+/**
+ * Gets the search strategy guidance for planning mode
+ */
+export function getSearchStrategyGuidance(): string {
+ const hasGeneralProvider = isGeneralSearchProviderAvailable()
+ const supportsMultimedia = supportsMultimediaContentTypes()
+
+ if (hasGeneralProvider && supportsMultimedia) {
+ return `Search strategy:
+- Use type="optimized" for most research queries (provides content snippets)
+- Use type="general" for time-sensitive info, videos, or images (requires fetch)
+- ALWAYS follow type="general" searches with fetch tool for content
+- For comprehensive research: multiple searches + selective fetching`
+ } else {
+ return `Search strategy:
+- Use type="optimized" for all queries (provides content snippets from primary provider)
+- type="general" will behave the same as "optimized" (dedicated general search provider not available)
+- Fetch tool can be used optionally for deeper content analysis
+- For comprehensive research: multiple searches + selective fetching`
+ }
+}
+
+/**
+ * Gets the appropriate search provider type for "general" searches
+ * Returns 'brave' if available, otherwise null to indicate fallback
+ */
+export function getGeneralSearchProviderType(): 'brave' | null {
+ if (process.env.BRAVE_SEARCH_API_KEY) {
+ return 'brave'
+ }
+ return null
+}