@ellie-ai/agent-web-tools-plugin

Web search and fetch tools for Ellie agents.

Overview

This plugin provides agents with the ability to:

• Search the web - Query search engines for current information
• Fetch web pages - Download and parse web page content

Installation

bun add @ellie-ai/agent-web-tools-plugin

Usage

import { createRuntime } from "@ellie-ai/runtime";
import { agentPlugin } from "@ellie-ai/agent-plugin";
import { webToolsPlugin } from "@ellie-ai/agent-web-tools-plugin";
import { openAI } from "@ellie-ai/model-providers";

const runtime = createRuntime({
  plugins: [
    agentPlugin({
      model: openAI(),
      toolPlugins: [
        webToolsPlugin({
          search: {
            provider: "brave",
            apiKey: process.env.BRAVE_API_KEY,
          },
        }),
      ],
    }),
  ],
});

Tools

web_search

Search the web for current information.

Parameters:

• query (string, required): Search query
• num_results (number, optional): Number of results (default: 5)

Example:

{
  "query": "Ellie agent framework",
  "num_results": 10
}

Returns: Markdown-formatted search results with titles, URLs, and snippets

Note: Requires API key configuration (see Configuration section)

web_fetch

Fetch and parse web page content.

Parameters:

• url (string, required): URL to fetch
• format (string, optional): "text" (markdown), "html" (raw), or "json" (parsed)

Example:

{
  "url": "https://example.com/page",
  "format": "text"
}

Returns: Page content in the requested format (defaults to markdown for HTML pages)

Configuration

Enable/Disable Tools

webToolsPlugin({
  tools: {
    webSearch: true,
    webFetch: true,
  },
});

Search Provider Configuration

The web_search tool requires an API key from a supported provider.

Brave Search

webToolsPlugin({
  search: {
    provider: "brave",
    apiKey: process.env.BRAVE_API_KEY,
  },
});

Get your Brave Search API key at: https://brave.com/search/api/

Serper (Google Search)

webToolsPlugin({
  search: {
    provider: "serper",
    apiKey: process.env.SERPER_API_KEY,
  },
});

Get your Serper API key at: https://serper.dev/

Web Fetch Configuration

Restrict which domains agents can access:

webToolsPlugin({
  fetch: {
    // Allow only specific domains
    allowedDomains: ["example.com", "docs.example.com"],

    // Block specific domains (takes precedence)
    deniedDomains: ["127.0.0.1", "localhost", "internal.company.com"],

    // Request timeout in milliseconds
    timeout: 10000,

    // Maximum response size in bytes
    maxSize: 1024 * 1024, // 1MB
  },
});

Configuration Examples

Block internal networks:

webToolsPlugin({
  fetch: {
    deniedDomains: [
      "127.0.0.1",
      "localhost",
      "0.0.0.0",
      "10.*.*.*",
      "192.168.*.*",
      "172.16.*.*",
    ],
  },
});

Allow only documentation sites:

webToolsPlugin({
  fetch: {
    allowedDomains: [
      "docs.anthropic.com",
      "developer.mozilla.org",
      "nodejs.org",
      "bun.sh",
    ],
  },
});

Strict timeout and size limits:

webToolsPlugin({
  fetch: {
    timeout: 5000, // 5 seconds
    maxSize: 512 * 1024, // 512KB
  },
});

Security Considerations

⚠️ SSRF Attacks: Without domain restrictions, agents can make requests to internal networks. Always configure deniedDomains in production.

⚠️ API Costs: Web search requires API calls that cost money. Monitor usage and consider rate limiting.

⚠️ Response Size: Large responses can consume memory. Use maxSize to limit download size.

⚠️ Timeout: Set appropriate timeouts to prevent agents from hanging on slow requests.

Recommended Production Config

webToolsPlugin({
  search: {
    provider: "brave",
    apiKey: process.env.BRAVE_API_KEY,
  },
  fetch: {
    // Block private networks
    deniedDomains: [
      "127.0.0.1",
      "localhost",
      "0.0.0.0",
      "10.*.*.*",
      "192.168.*.*",
      "172.16.*.*",
      "169.254.*.*", // Link-local
      "*.local",
    ],
    timeout: 10000, // 10 seconds
    maxSize: 2 * 1024 * 1024, // 2MB
  },
});

Supported Search Providers

| Provider | API Docs | Pricing | |----------|----------|---------| | Brave Search | https://brave.com/search/api/ | $5/1000 queries (free tier: 2000/month) | | Serper | https://serper.dev/ | $50/1000 queries (free tier: 2500/month) |

License

MIT