Pi Coding Agent: Web Search Tool Patterns

Coding agents need web search to look up documentation, check API changes, and verify library versions, but integration patterns vary wildly across frameworks. Pi Coding Agent uses SKILL.md files with bash scripts. Claude uses MCP servers. Hermes uses tool definitions. The universal solution that works across all of them is an HTTP-based search endpoint that any agent can call as a shell command or HTTP request.

The Pi Coding Agent pattern: SKILL.md

A Pi user struggled to register web search as a tool because Pi does not have a native plugin system. The solution: create a SKILL.md file that teaches the agent how to call a bash script. The agent reads the skill definition and executes the script when it needs search results.

# skills/web_search/SKILL.md
# Web Search Skill
# Usage: Call this when you need current information about APIs, libraries, or docs.

# Execute:
# ./skills/web_search/search.sh "your query here"

# Returns: JSON with title, snippet, link for top results

#!/bin/bash
# skills/web_search/search.sh
QUERY="$1"
curl -s -X POST "https://api.scavio.dev/api/v1/search" \
  -H "x-api-key: $SCAVIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{"platform": "google", "query": "$QUERY"}" | \
  jq '.organic[:5] | .[] | {title, snippet, link}'

The Claude MCP pattern

Claude Code and Claude Desktop use MCP servers. You define the search tool as an MCP server and Claude can call it natively. This is the most integrated approach but only works within the Claude ecosystem.

// mcp-search-server/index.js
import { Server } from "@modelcontextprotocol/sdk/server/index.js";

const server = new Server({ name: "web-search", version: "1.0.0" });

server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "web_search") {
    const resp = await fetch("https://api.scavio.dev/api/v1/search", {
      method: "POST",
      headers: {
        "x-api-key": process.env.SCAVIO_API_KEY,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        platform: "google",
        query: request.params.arguments.query
      })
    });
    const data = await resp.json();
    return { content: [{ type: "text", text: JSON.stringify(data.organic?.slice(0, 5)) }] };
  }
});

The Hermes tool definition pattern

Hermes and similar open-source agent frameworks use tool definitions in the system prompt. The agent generates a tool call, the runtime executes it and returns results.

# Hermes tool definition
tools = [{
    "type": "function",
    "function": {
        "name": "web_search",
        "description": "Search the web for current information",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "Search query"}
            },
            "required": ["query"]
        }
    }
}]

def execute_web_search(query: str) -> str:
    import requests
    resp = requests.post("https://api.scavio.dev/api/v1/search",
        headers={"x-api-key": os.environ["SCAVIO_API_KEY"]},
        json={"platform": "google", "query": query}, timeout=10)
    results = resp.json().get("organic", [])[:5]
    return "\n".join(f"- {r['title']}: {r['snippet']}" for r in results)

The universal pattern: HTTP endpoint

Regardless of the framework, the underlying mechanism is the same: an HTTP POST to a search API. This means you can support any coding agent with a single integration. If the agent can run curl, it can search. If it can make HTTP requests, it can search. The framework differences are just wrappers around this core operation.

Cost comparison for coding agents

A typical coding session makes 5-20 search queries (checking docs, verifying package versions, looking up error messages). At $0.005 per credit, that is $0.025-$0.10 per session. Compare to the time saved by not having the agent hallucinate an outdated API signature and debugging for 20 minutes. The 250 free credits on signup cover roughly 50 coding sessions of moderate search usage.

Implementation advice

Start with the bash script approach. It works everywhere because every coding agent can execute shell commands. Once you confirm it works, upgrade to native integration (MCP for Claude, tool definitions for Hermes). Cache results locally for repeated queries in the same session. Rate limit to 1 request per 2 seconds to avoid burning through credits on runaway loops.