Web Search

Web Search allows the agent to retrieve real-time information from the internet when fresh or external information is needed. The feature is powered by Tavily API and integrated as a built-in agent tool.

Feature Flag

The web search tool is gated behind an admin feature flag. The web_search tool is only exposed to agents after the administrator enables web search in the admin settings.

• When disabled by admin: agents cannot see or call the web_search tool
• When enabled by admin: all agents across all projects can automatically invoke web search

This means that even if a Prompt Action declares web_search in its capabilities, the tool remains unavailable when the admin has not globally enabled the feature.

Overview

When enabled, the agent can automatically call the web_search tool during conversations to:

• Search for recent news, research papers, or documentation
• Find factual information not available in local context
• Retrieve up-to-date data for analysis and synthesis

Prerequisites

• Administrator: Must enable web search and configure a system API key
• User: Optionally configure a personal API key (if allowed by admin)

Administrator Configuration

Administrators can access web search settings at: Admin → Web Search.

Settings

Credential Priority

When a user triggers a search:

1. User API Key (if allow_user_keys=true and user has configured one)
2. System API Key (fallback)

Test Configuration

Click Test button to verify the configuration with a sample query ("latest AI research"). Audit events are recorded for both successful and failed tests.

Audit Events

All search requests are logged with:

• Query (sanitized: emails, tokens, secrets redacted)
• Status: success, error, or blocked (rate limited)
• Result count
• Duration (ms)
• User, project, and conversation context

Admins can view recent audit events on the settings page.

User Configuration

Users can configure personal API keys at: Settings → Web Search (if allowed by admin).

Benefits of Personal Key

• Independent rate limits from system quota
• Use your own Tavily subscription tier

Configure Your Key

1. Obtain a Tavily API key from tavily.com
2. Go to your personal settings
3. Enter the API key
4. Save changes

To remove your personal key, clear the field and save.

Usage in Conversations

Web search is invoked automatically by the agent when needed. You do not need to explicitly call it.

Example Prompts

• "What are the latest developments in quantum computing?"
• "Find recent papers about CRISPR gene editing"
• "Search for documentation on React 19 new features"
• "What's the current state of the AI agent ecosystem?"

Tool Parameters

The agent can customize searches with:

Result Structure

Each search returns:

{
  "provider": "tavily",
  "query": "...",
  "answer": "AI-generated answer summary",
  "results": [
    {
      "title": "...",
      "url": "...",
      "snippet": "...",
      "score": 0.95,
      "published_date": "2026-03-01"
    }
  ],
  "response_time": 1.25
}

Rate Limits

• Per-user: Configured by admin (default: 20 requests/hour)
• Exceeded: Search returns an error; audit logs blocked status
• Query sanitization: Sensitive data (emails, API tokens) is redacted before logging

Troubleshooting

"Web search is disabled by the administrator"

Contact your admin to enable the feature.

"No Tavily API key is configured"

Admin must configure a system API key, or you must add a personal key (if allowed).

"Web search rate limit exceeded"

Wait for the rate limit window to reset, or ask admin to increase your quota.

Search returns no results

• Check if your query is too specific or contains typos
• Try topic: news for recent events
• Verify API key validity at tavily.com

Security Notes

• API keys are stored encrypted in the database
• Search queries are sanitized before audit logging
• Credentials are scoped (system-level or user-specific)
• Rate limits prevent abuse