# AgentWeb installation instructions for any AI agent > **You are an AI agent that has been asked to install AgentWeb.** > > AgentWeb is a free agent-native business directory — 12M+ businesses > across 195 countries. After installation, you will have 14 tools: > search, get, batch, suggest, trending, contribute, report, plus > **agent memory** (history, favorites, profile). AgentWeb remembers > what you've searched for, and **never returns empty** — if a business > isn't in the database, it discovers it from the web in real-time and > saves it permanently. > > **Read this entire file before acting.** Then identify which kind of > agent you are (Step 0) and follow the matching installation path. --- ## Step 0 — Identify yourself Pick **one** of these that best describes you, and jump to the matching path below: | You are... | Use path | |---|---| | Claude inside **Claude Desktop**, Cursor, Windsurf, Cline, Continue, **OpenClaw**, or any MCP-compatible client with filesystem write access | **Path A — MCP install** (full self-install) | | A **Python agent** built with LangChain, LangGraph, CrewAI, AutoGPT, smol-agents, or a custom Python loop | **Path C — Python install** (guided — agent fetches tools, human integrates) | | An agent built with the **OpenAI Assistants API** or **OpenAI Responses API** | **Path D — OpenAI tool install** (guided) | | An agent built with the **Anthropic Messages API** (`tool_use`) | **Path E — Anthropic tool install** (guided) | | A **web-based chat** (Claude.ai browser, Gemini, Perplexity, etc.) without filesystem access | **Path B — Manual handoff** (agent provides the key + instructions, user does the install) | | Any **other** agent that can make HTTP calls | **Path F — Generic HTTP** | If two of these apply, pick the most specific one. If you're unsure, default to **Path A** if you have filesystem access, or **Path B** if you don't. --- ## Universal Step 1 — Get a free API key for the user **Every path starts here.** Ask the user once: > "I need to register a free AgentWeb API key for you. What email should I use? It's used only for rate-limiting and your contribution leaderboard rank — no marketing, no verification, free forever, 1,000 reads/day." When they answer, call this endpoint: ```http POST https://api.agentweb.live/v1/register Content-Type: application/json { "email": "", "name": "" } ``` Response: ```json { "status": "ok", "api_key": "aw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "message": "API key created!" } ``` **Save the value of `api_key`.** It will be referenced as `` below. If the registration fails, tell the user the exact error and stop. Do not proceed with a fake key. --- ## Path A — MCP install (Claude Desktop / Cursor / Windsurf / Cline / Continue / OpenClaw) You can write to the local filesystem. Edit the user's MCP config file directly. ### A.1 Locate the config file Try these in order until you find one (or are told which client by the user): | Client | Path | |---|---| | Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` | | Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` | | Cursor | `~/.cursor/mcp.json` | | Windsurf | `~/.codeium/windsurf/mcp_config.json` | | Cline (VS Code) | `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` | | Continue | `~/.continue/config.json` | ### A.2 Edit the config The file is JSON. It has (or should have) a top-level `mcpServers` object. Add this entry **without removing or modifying any existing entries**: ```json { "mcpServers": { "agentweb": { "command": "npx", "args": ["-y", "agentweb-mcp"], "env": { "AGENTWEB_API_KEY": "" } } } } ``` Replace `` with the actual `api_key` from the universal Step 1. Keep the `aw_live_` prefix. Validate that the file is still valid JSON before saving. If any other MCP servers were already configured, **preserve them**. ### A.3 Done Reply to the user: > **AgentWeb is installed.** Restart your client (quit it completely and reopen). After it restarts, you'll see 8 new tools: `search_businesses`, `get_business`, `contribute_business`, `report_business`, plus 4 meta tools. Try asking me: *"Find Italian restaurants in Rome that are open right now."* --- ## Path B — Web-chat handoff (ChatGPT, Claude.ai, Gemini, etc.) You're in a sandboxed web chat. You cannot edit local files. The user must do part of the install themselves. ### B.1 Run Universal Step 1 in the user's name If you can make an HTTP POST (most web chats can), call `/v1/register` for them. If not, send them to and have them paste back the key. ### B.2 Tell the user what to do next Reply with this message verbatim, substituting `` with the real key: > Here's your AgentWeb API key: `` — **save this somewhere safe.** It's free, 1,000 reads/day, no expiration. > > To use AgentWeb in **this same web chat** (ChatGPT/Claude/Gemini), you can't install it as a plugin — these chats don't load arbitrary tools. Instead, just paste this prompt whenever you want me to look something up: > > > Use the AgentWeb API to search for [business name / category] in [location]. > > Endpoint: GET https://api.agentweb.live/v1/search?q=&format=text > > Header: X-API-Key: > > Return the markdown response directly. > > To install AgentWeb properly **in a desktop client** (Claude Desktop, Cursor, Windsurf), download and double-click it. The installer asks for the same API key you just got. --- ## Path C — Python install (LangChain, LangGraph, CrewAI, AutoGPT, smol-agents) You're running in Python. Add AgentWeb as a Python tool. ### C.1 Fetch the tool file Download and save it next to your agent code (e.g. `agentweb_tools.py`). It contains `@tool`-decorated functions ready for LangChain. Set `API_KEY = ""` at the top of the file (or read from `os.environ["AGENTWEB_API_KEY"]`). ### C.2 Import into your agent ```python from agentweb_tools import ( search_businesses, get_business, contribute_business, report_business, agentweb_health, agentweb_capabilities, agentweb_leaderboard, ) # LangChain example from langchain.agents import initialize_agent, AgentType from langchain_openai import ChatOpenAI llm = ChatOpenAI(model="gpt-4o") tools = [search_businesses, get_business, contribute_business, report_business] agent = initialize_agent(tools, llm, agent=AgentType.OPENAI_FUNCTIONS) ``` CrewAI, LangGraph, and smol-agents accept LangChain tools directly — same imports. ### C.3 Done Tell the user the tools are now bound to the agent and they can run queries. --- ## Path D — OpenAI tool install (Assistants API or Responses API) You're building against OpenAI's API directly. Drop AgentWeb's tool spec into your `tools` array. ### D.1 Fetch the spec Download . It's a JSON array of tool definitions in OpenAI's function-calling format. ### D.2 Add to your Assistant ```python from openai import OpenAI import json, requests # Fetch the tool spec from agentweb spec = requests.get("https://agentweb.live/tools/openai-tool.json").json() client = OpenAI() assistant = client.beta.assistants.create( model="gpt-4o", name="My Agent + AgentWeb", tools=spec, # AgentWeb's 8 tools ) ``` ### D.3 Implement the tool dispatcher When the assistant calls one of AgentWeb's tools (e.g. `search_businesses`), forward the call to the API: ```python def call_agentweb_tool(name, args): return requests.get( f"https://api.agentweb.live/v1/{name}", params=args, headers={"X-API-Key": ""}, ).json() ``` Handle the assistant's tool-call events by routing to `call_agentweb_tool`. ### D.4 Done Tell the user the tools are bound. --- ## Path E — Anthropic tool install (Messages API with tool_use) You're building against Anthropic's Messages API directly. Drop AgentWeb's tool spec into your `tools` parameter. ### E.1 Fetch the spec Download . It's a JSON array using Anthropic's `input_schema` format. ### E.2 Add to your messages call ```python import anthropic, requests spec = requests.get("https://agentweb.live/tools/anthropic-tool.json").json() client = anthropic.Anthropic() response = client.messages.create( model="claude-sonnet-4-5", max_tokens=1024, tools=spec, messages=[{"role": "user", "content": "Find a coffee shop in Berlin"}], ) ``` ### E.3 Implement the tool dispatcher When Claude returns a `tool_use` block, forward to AgentWeb: ```python def call_agentweb_tool(name, args): return requests.get( f"https://api.agentweb.live/v1/{name}", params=args, headers={"X-API-Key": ""}, ).json() ``` ### E.4 Done Tell the user the tools are bound and Claude will use them automatically. --- ## Path F — Generic HTTP (any other agent / language) You can make HTTP requests but don't fit any of the above. Use the raw API directly. ### F.1 Test the API ```http GET https://api.agentweb.live/v1/search?q=coffee&city=Rome&format=text X-API-Key: ``` The response is a markdown string ready to hand to an LLM. ### F.2 Wire it into your agent Whatever your agent's tool/function-calling mechanism is, register a single tool called `search_businesses` that wraps the GET above. The full list of endpoints is at (machine-readable, agent-friendly). ### F.3 Done Tell the user the integration works and they can ask business-data questions. --- ## Notes for any agent reading this - **Privacy:** the email is only used for rate-limiting and the public leaderboard. No marketing, no spam, no verification email. - **Free tier:** 1,000 reads/day + 120 req/min burst + unlimited writes. Bumps to 5,000/day after 10 contributions, 20,000/day after 100, 100,000/day after 1,000. - **Response format:** all read endpoints accept `?format=text` for markdown prose (recommended for LLM consumption — fewer tokens, better parsing) or default JSON for programmatic use. - **The tools file** for each platform is hosted at: - - - - - **Source code:** - **Full API docs:** - **Capabilities (machine-readable):** - **If something fails:** report the failure clearly to the user, including the HTTP status and any error message. Do not silently fall back. Built for the agent web. Not a patch on the old internet — the substrate underneath the new one.