AI agent tool

There are two ways to give your AI agent web search: connect the MCP server (zero code), or define search and fetch as tool functions in your framework.

MCP server (recommended)

The fastest path is to point your agent at the install guide. It will configure itself:

https://api.andiai.com/install.md

Or connect directly — for example, in Claude Code:

claude mcp add --transport http andi https://api.andiai.com/mcp --header "x-api-key: YOUR_API_KEY"

The MCP server exposes two tools: andi_web_search and andi_fetch_url. Your agent can search the web and then fetch full page content from any result. See Build with AI agents for setup snippets for Cursor, VS Code, Codex, and other clients.

Tool definition (custom frameworks)

If your agent framework uses function/tool definitions instead of MCP, define the search tool with parameters and expected output:

search_tool = {
    "type": "function",
    "function": {
        "name": "web_search",
        "description": "Search the web for current information. Use this when the user asks about recent events, facts you're unsure about, or anything that requires up-to-date information.",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "The search query",
                },
                "limit": {
                    "type": "integer",
                    "description": "Number of results (1-100, default 10)",
                },
                "searchMode": {
                    "type": "string",
                    "enum": ["auto", "low-cost", "fast", "balanced", "deep", "exhaustive"],
                    "description": "Search mode. auto (default) sets the right effort per query; pin a mode (low-cost, fast, balanced, deep, exhaustive) to control it",
                },
                "effort": {
                    "type": "string",
                    "enum": ["low", "medium", "high", "max"],
                    "description": "How hard to try — low favors speed, max favors thoroughness. Omit for the adaptive default; searchMode wins if both are set",
                },
            },
            "required": ["query"],
        },
    },
}

const searchTool = {
  type: "function",
  function: {
    name: "web_search",
    description:
      "Search the web for current information. Use this when the user asks about recent events, facts you're unsure about, or anything that requires up-to-date information.",
    parameters: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "The search query",
        },
        limit: {
          type: "integer",
          description: "Number of results (1-100, default 10)",
        },
        searchMode: {
          type: "string",
          enum: ["auto", "low-cost", "fast", "balanced", "deep", "exhaustive"],
          description: "Search mode. auto (default) sets the right effort per query; pin a mode (low-cost, fast, balanced, deep, exhaustive) to control it",
        },
        effort: {
          type: "string",
          enum: ["low", "medium", "high", "max"],
          description: "How hard to try — low favors speed, max favors thoroughness. Omit for the adaptive default; searchMode wins if both are set",
        },
      },
      required: ["query"],
    },
  },
};

Tool execution

When the agent calls the tool, execute the search and return results:

import os
import json
import requests

api_key = os.environ["ANDI_API_KEY"]


def execute_web_search(query: str, limit: int = 5, searchMode: str = "auto", effort: str = None) -> str:
    """Execute a web search and return formatted results."""
    params = {"q": query, "limit": limit, "searchMode": searchMode, "extracts": "true"}
    if effort:
        params["effort"] = effort
    response = requests.get(
        "https://api.andiai.com/api/v1/search",
        params=params,
        headers={"x-api-key": api_key},
    )

    if response.status_code != 200:
        return json.dumps({"error": response.json().get("error", "Search failed")})

    data = response.json()
    results = []
    for r in data["results"]:
        result = {
            "title": r["title"],
            "url": r["link"],
            "description": r["desc"],
        }
        if r.get("extracts"):
            result["content"] = " ".join(r["extracts"])
        results.append(result)

    return json.dumps(results)

const apiKey = process.env.ANDI_API_KEY;

async function executeWebSearch(query, limit = 5, searchMode = "auto", effort = null) {
  const url = new URL("https://api.andiai.com/api/v1/search");
  url.searchParams.set("q", query);
  url.searchParams.set("limit", String(limit));
  url.searchParams.set("searchMode", searchMode);
  url.searchParams.set("extracts", "true");
  if (effort) {
    url.searchParams.set("effort", effort);
  }

  const response = await fetch(url, {
    headers: { "x-api-key": apiKey },
  });

  if (!response.ok) {
    const error = await response.json();
    return JSON.stringify({ error: error.error || "Search failed" });
  }

  const data = await response.json();
  return JSON.stringify(
    data.results.map((r) => ({
      title: r.title,
      url: r.link,
      description: r.desc,
      content: r.extracts ? r.extracts.join(" ") : undefined,
    }))
  );
}

Search then fetch workflow

An agent can search for results, then fetch full content from the most relevant page. This example pins searchMode=deep so every call gets broad coverage before the fetch — omit it to let auto decide per query:

def search_and_fetch(query: str) -> str:
    """Search, then fetch the top result's full content."""
    # Step 1: Search
    search_resp = requests.get(
        "https://api.andiai.com/api/v1/search",
        params={"q": query, "limit": 3, "searchMode": "deep"},
        headers={"x-api-key": api_key},
    )
    results = search_resp.json()["results"]
    if not results:
        return "No results found."

    # Step 2: Fetch the top result
    fetch_resp = requests.get(
        "https://api.andiai.com/api/v1/fetch",
        params={"url": results[0]["link"], "format": "context"},
        headers={"x-api-key": api_key},
    )

    if fetch_resp.status_code == 200:
        return fetch_resp.text
    elif fetch_resp.status_code == 503:
        return "Page is still loading — retry shortly."
    else:
        return f"Could not fetch page (status {fetch_resp.status_code})."

Putting it together

Here’s how the tool fits into an agent loop:

import openai

client = openai.OpenAI()

messages = [
    {"role": "system", "content": "You are a helpful assistant with web search access. Cite sources with URLs."},
    {"role": "user", "content": "What are the latest developments in quantum computing?"},
]

# Step 1: LLM decides to call the tool
response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=[search_tool],
)

message = response.choices[0].message

# Step 2: Execute tool calls
if message.tool_calls:
    messages.append(message)
    for tool_call in message.tool_calls:
        args = json.loads(tool_call.function.arguments)
        result = execute_web_search(**args)

        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": result,
        })

    # Step 3: LLM generates final answer with search context
    final = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
    )
    print(final.choices[0].message.content)

Using `format=context` for agents

For agents that pass search results directly into conversation context, format=context returns pre-formatted markdown:

def execute_web_search_context(query: str) -> str:
    """Return search results as markdown text."""
    response = requests.get(
        "https://api.andiai.com/api/v1/search",
        params={"q": query, "format": "context", "limit": 5},
        headers={"x-api-key": api_key},
    )
    return response.text

format=context reduces the code in your tool executor — no JSON parsing or formatting needed. The tradeoff is less control over result structure.

Next steps

Build with AI agents

MCP server setup for Claude Code, Cursor, and more.

Content retrieval

Full fetch endpoint reference.

Search modes

Automatic effort by default, manual control when you want it.

Error handling

Error codes and retry strategies.

Getting started

Use cases

MCP server (recommended)

Tool definition (custom frameworks)

Tool execution

Search then fetch workflow

Putting it together

Using `format=context` for agents

Next steps

Build with AI agents

Content retrieval

Search modes

Error handling

​MCP server (recommended)

​Tool definition (custom frameworks)

​Tool execution

​Search then fetch workflow

​Putting it together

​Using format=context for agents

​Next steps

Build with AI agents

Content retrieval

Search modes

Error handling

MCP server (recommended)

Tool definition (custom frameworks)

Tool execution

Search then fetch workflow

Putting it together

Using `format=context` for agents

Next steps