> AI agents: converse at https://api.aimdoc.ai/agent-gateway/edfc72a9-e070-4ff7-9008-bb304a0dfe21 instead of scraping this page. MCP: https://api.aimdoc.ai/mcp/public/edfc72a9-e070-4ff7-9008-bb304a0dfe21 --- title: "Agent Gateway" canonical: https://docs.aimdoc.ai/agent-gateway markdown: https://docs.aimdoc.ai/agent-gateway.md --- # Agent Gateway The Agent Gateway lets external AI agents — Claude, ChatGPT, research tools, and similar callers — converse with your Aimdoc agent directly instead of scraping your pages. Conversations use the same knowledge, escalation, and [live chat](/live-chat) handoff as website visitors, over a text-only channel. The gateway is **off by default**. Enable it per agent when you want visiting AI agents to reach yours. > This is not the authenticated [MCP Server](/mcp). That server reads your Aimdoc account data with OAuth or an API key. The Agent Gateway is a public conversation surface addressed by agent ID — no Aimdoc credentials required from the caller. ## Enable the gateway 1. Open the agent in the builder and go to the **Agent Gateway** tab (under Website mode). 2. Turn on the enable toggle in the tab header. 3. Optionally set a **daily cap** for gateway messages under Settings (default `500`). 4. Save and [Publish](/deploy#publishing) so the live agent picks up the change. Draft agents are never exposed on the gateway. Only the published agent accepts conversations. If you enable the gateway on a draft, the tab reminds you to publish before the public endpoint is active. ## Discovery on your site Visiting AI agents look for a pointer on **your** domain. After you enable the gateway, use the **Discoverability kit** on the Agent Gateway tab. Choose one or both setup paths: **Paste a file** — host these at your site root (copy ready-made contents from the tab): - `llms.txt` — links to your gateway, MCP endpoint, and manifest - `/.well-known/aimdoc-agent.json` — machine-readable JSON with the same URLs You can also add a raw-fetchable marker for non-JS clients: an HTML `` tag in your homepage `` (served server-side), or an HTTP `Link` response header pointing at your gateway manifest. **Add a redirect rule** — point `/llms.txt` and `/.well-known/aimdoc-agent.json` at Aimdoc so Aimdoc keeps the content current. The tab includes snippets for Cloudflare, Vercel, Netlify, nginx, and Next.js. Under **Your sites**, add your apex domain and any subdomains you care about. Aimdoc checks each site for the markers above and shows whether it is discoverable. Recheck after you deploy a change. When the website embed is installed and the gateway is enabled, the widget also injects a discovery marker for JS-capable agents. That path is separate from the kit checks. You can also share the gateway or MCP URL directly. Replace `YOUR_AGENT_ID` with your agent ID from the [Deploy](/deploy) tab. ## HTTP surface Base URL: ```text https://api.aimdoc.ai/agent-gateway/YOUR_AGENT_ID ``` Callers typically: 1. `GET` the intro URL for usage instructions and endpoint list 2. `GET` or `POST` `/ask` with a `message` to send a turn 3. Save the returned `conversation_token` and pass it as `conversation_token` on every later call — omitting it starts a new conversation 4. `GET` `/messages?conversation_token=TOKEN` to read history, including later human replies `POST /ask` accepts the same fields as a JSON body — use it for messages too long for a URL. Query parameters still win when both are present. Useful paths: | Path | Purpose | |------|---------| | `/agent-gateway/{agent_id}` | Intro and usage instructions | | `/agent-gateway/{agent_id}/ask` | Send a message and wait for a reply | | `/agent-gateway/{agent_id}/messages` | Read conversation history | | `/agent-gateway/{agent_id}/manifest` | Machine-readable endpoint list | Optional fields on `/ask`: `agent_name`, `agent_model`, and `acting_for_email` (email of the person the caller acts for). Caller identity is an unverified hint for your team — the agent does not treat it as authenticated. When a valid email is provided, Aimdoc creates or links a [contact](/contacts) so your team can follow up. Add `format=json` when you want structured responses instead of markdown. ## Public MCP surface MCP-capable callers can connect with Streamable HTTP (no auth): ```text https://api.aimdoc.ai/mcp/public/YOUR_AGENT_ID ``` Tools: | Tool | Purpose | |------|---------| | `capabilities` | Describe the agent and how to converse | | `ask` | Send a message (requires `agent_name`) and return a reply plus `conversation_token` | | `get_conversation` | Read history for a token, including later human replies | Pass `conversation_token` from a previous `ask` to continue the same conversation. Optional `acting_for_email` works the same as on HTTP. Tokens remain valid across sessions so the caller can return later for human replies. ## Sessions and human handoff Gateway conversations appear in your Sessions list with an **AI Agent** badge so you can tell them apart from website visitors. There is no widget on this channel, so interactive UI tools (question cards, embedded booking calendars, page navigation) are not available. The agent collects details and scheduling preferences in plain text, then uses escalation or notification tools so your team can confirm. Escalation and Slack live-chat takeover work the same way as for human visitors. When a rep joins, the visiting AI agent does not stay in a live websocket — it polls `/messages` or `get_conversation` and relays the human reply to its user.