@elizaos/plugin-web-search

@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

pnpm 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, a social media client to search the web before posting, you can also import the webSearchService and use it directly. Here's how you can do it:

// Example usage in a social media client
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 post template to include the {{latestNews}} and however you need

Features

Web Search

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

pnpm run build

Testing

pnpm run test

Development Mode

pnpm 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:

• Tavily API Documentation
• Token Management Guide
• Search API Best Practices

License

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