Skip to main content

@elizaos/plugin-web-search

A plugin for powerful web search capabilities, providing efficient search query handling and result processing through a customizable API interface.

Overview​

This plugin provides functionality to:

  • Execute web search queries with customizable parameters
  • Process and format search results
  • Handle search API authentication
  • Manage token limits and response sizes
  • Optimize query performance

Installation​

bun install @elizaos/plugin-web-search

Configuration​

The plugin requires the following environment variables:

TAVILY_API_KEY=your_api_key    # Required: API key for search service

Usage​

Import and register the plugin in your Eliza configuration.

import { webSearchPlugin } from '@elizaos/plugin-web-search';

export default {
  plugins: [webSearchPlugin],
  // ... other configuration
};

Custom Usage If you want custom usage, for example, twitter-client to search the web before posting a tweet, you can also import the webSearchService and use it directly. Here's how you can do it:

// packages/client-twitter/src/post.ts
const webSearchService = new WebSearchService();
await webSearchService.initialize(runtime);
const latestNews = await webSearchService.search(
    "latest news on AI Agents",
    // searchOptions
);

const state = await this.runtime.composeState(
    {  } // memory,
    { // additional keys
        latestNews: latestNews,
    }
);

// Then modify the tweet template to include the {{latestNews}} and however you need

Features​

The plugin provides comprehensive web search capabilities:

import { webSearch } from '@elizaos/plugin-web-search';

// Execute a search query
const result = await webSearch.handler(
  runtime,
  {
    content: { text: 'What is the latest news about AI?' },
  },
  state,
  {},
  callback
);

Token Management​

// The plugin automatically handles token limits
const DEFAULT_MAX_WEB_SEARCH_TOKENS = 4000;

// Example of token-limited response
const response = MaxTokens(searchResult, DEFAULT_MAX_WEB_SEARCH_TOKENS);

Development​

Building​

bun run build

Testing​

bun run test

Development Mode​

bun run dev

Dependencies​

  • @elizaos/core: Core Eliza functionality
  • js-tiktoken: Token counting and management
  • tsup: Build tool
  • Other standard dependencies listed in package.json

API Reference​

Core Interfaces​

interface Action {
  name: 'WEB_SEARCH';
  similes: string[];
  description: string;
  validate: (runtime: IAgentRuntime, message: Memory) => Promise<boolean>;
  handler: (
    runtime: IAgentRuntime,
    message: Memory,
    state: State,
    options: any,
    callback: HandlerCallback
  ) => Promise<void>;
  examples: Array<Array<any>>;
}

interface SearchResult {
  title: string;
  url: string;
  answer?: string;
  results?: Array<{
    title: string;
    url: string;
  }>;
}

Plugin Methods​

  • webSearch.handler: Main method for executing searches
  • generateWebSearch: Core search generation function
  • MaxTokens: Token limit management function
  • getTotalTokensFromString: Token counting utility

Common Issues/Troubleshooting​

Issue: API Authentication Failures​

  • Cause: Invalid or missing Tavily API key
  • Solution: Verify TAVILY_API_KEY environment variable

Issue: Token Limit Exceeded​

  • Cause: Search results exceeding maximum token limit
  • Solution: Results are automatically truncated to fit within limits

Issue: Search Rate Limiting​

  • Cause: Too many requests in short time
  • Solution: Implement proper request throttling

Security Best Practices​

  • Store API keys securely using environment variables
  • Validate all search inputs
  • Implement proper error handling
  • Keep dependencies updated
  • Monitor API usage and rate limits
  • Use HTTPS for API communication

Example Usage​

// Basic search
const searchQuery = 'Latest developments in quantum computing';
const results = await generateWebSearch(searchQuery, runtime);

// With formatted response
if (results && results.results.length) {
  const formattedResponse = `${results.answer}\n\nFor more details, check out:\n${results.results
    .map((result, index) => `${index + 1}. [${result.title}](${result.url})`)
    .join('\n')}`;
}

Configuration Options​

Token Management​

const DEFAULT_MODEL_ENCODING = 'gpt-3.5-turbo';
const DEFAULT_MAX_WEB_SEARCH_TOKENS = 4000;

Search Actions​

The plugin includes multiple search action similes:

  • SEARCH_WEB
  • INTERNET_SEARCH
  • LOOKUP
  • QUERY_WEB
  • FIND_ONLINE
  • And more...

Contributing​

Contributions are welcome! Please see the CONTRIBUTING.md file for more information.

Credits​

This plugin integrates with and builds upon several key technologies:

  • Tavily API: Advanced search and content analysis API
  • js-tiktoken: Token counting for API responses
  • Zod: TypeScript-first schema validation

Special thanks to:

  • The Eliza community for their contributions and feedback

For more information about the search capabilities and tools:

License​

This plugin is part of the Eliza project. See the main project repository for license information.