# Agent Surface

> Agent Surface is a practical guide and implementation kit for making software readable by AI agents and for building production-grade agent systems. It covers agent-readable surfaces, discovery, APIs, tools, MCP, auth, errors, retrieval, multi-agent orchestration, evaluation, runtime boundaries, UI, and current agent protocols.

## When to use this site

Reach for Agent Surface when you need to:

- Look up how to make a website, app, or API legible to AI agents: discovery files, content negotiation, structured data, auth and error contracts.
- Get the `surface` skill installed in a coding agent to audit, score, or scaffold an agent-readable surface directly in a repository.
- Search or read this documentation over MCP instead of fetching pages one at a time.

Fetch [/llms.txt](https://agentsurface.dev/llms.txt) for this index or [/llms-full.txt](https://agentsurface.dev/llms-full.txt) for every page in one file, request any docs page with `Accept: text/markdown` or its `.md` URL, or follow the [MCP connection guide](https://agentsurface.dev/docs/mcp-servers/transports.md) to connect to POST /mcp and call `search`, `list_pages`, or `get_page`.

## Agent-readable entry points

- [OpenAPI specification](https://agentsurface.dev/openapi.json): Public documentation search and Markdown retrieval; no authentication required.
- [Access policy](https://agentsurface.dev/auth.md): Public, read-only access without credentials.
- [AGENTS.md](https://agentsurface.dev/AGENTS.md): Project context and working conventions for coding agents.
- [surface skill](https://agentsurface.dev/skills/surface/SKILL.md): The operational workflow for guide, audit, scaffold, transform, and generate tasks. Install it with `npx skills add howells/agentsurface --skill surface` (add `-g -y` to install globally without prompts).
- [Docs index](https://agentsurface.dev/docs/llms.txt): The docs page tree on its own, without these entry points.
- [API index](https://agentsurface.dev/api/llms.txt): The documentation API's two operations, with examples.
- [Build agents index](https://agentsurface.dev/docs/agents/llms.txt): Only the pages for teams building agents of their own.
- [Full docs export](https://agentsurface.dev/llms-full.txt): Opt-in bulk export for offline indexing, roughly 1.9 MB and 470,000 estimated tokens (characters / 4). Prefer search or individual pages for normal reading.
- [Homepage as Markdown](https://agentsurface.dev/index.md): The homepage guide (also served for `Accept: text/markdown` or `/?mode=agent`).
- [Any docs page as Markdown](https://agentsurface.dev/docs.md): Append `.md` to a docs URL, e.g. `/docs/discovery/llms-txt.md`, or send `Accept: text/markdown`.
- [Markdown API](https://agentsurface.dev/api/md/index): Raw Markdown endpoint. Replace `index` with any docs slug, for example `discovery/llms-txt`.
- [MCP connection guide](https://agentsurface.dev/docs/mcp-servers/transports.md): Connect to POST /mcp to search and read documentation.
- [MCP Registry entry](https://registry.modelcontextprotocol.io/v0/servers/dev.agentsurface%2Fdocs/versions/latest): The MCP server's listing in the official registry, as `dev.agentsurface/docs`.
- [MCP server card](https://agentsurface.dev/mcp/server-card): Identity and transport of the MCP endpoint; the tools come from the live server.
- [Agent skills index](https://agentsurface.dev/.well-known/agent-skills/index.json): Discovery record for the surface skill.
- [API catalog](https://agentsurface.dev/.well-known/api-catalog): RFC 9727 linkset for the OpenAPI spec and docs.
- [ARD catalog](https://agentsurface.dev/.well-known/ard.json): Agentic Resource Discovery manifest listing the MCP server, API, and skill.

## Guide

- [Let agents act for customers without handing them the keys](https://agentsurface.dev/guide/auth-identity.md): Before an agent can change an order or touch an account, your systems need to know who it is, what it's allowed to do, and how to shut it off.
- [Give agents something to plug into](https://agentsurface.dev/guide/connections.md): An agent can only act on your product through a real connection point - an API, an MCP server, a CLI, or an SDK - and most products still don't have one.
- [Agents can only recommend what they can find](https://agentsurface.dev/guide/discoverability.md): Discoverability decides whether an AI agent evaluating your business on a customer's behalf ever gets past the front door.
- [Measure whether agents finish the task](https://agentsurface.dev/guide/measurement.md): A technical checklist tells you the page is well-formed; only a live agent trying to complete a real task tells you whether the customer actually got what they came for.
- [Agents can pay for a purchase, within limits you set](https://agentsurface.dev/guide/payments.md): Checkout, spending permission, and pay-per-use payment so an agent can complete a purchase a customer authorized.
- [Agents need a plan for when something breaks](https://agentsurface.dev/guide/reliability.md): Errors, retries, and rate limits decide whether a failed automated task costs you a customer or just a few seconds.
- [Explain your business the way an agent reads](https://agentsurface.dev/guide/understandability.md): An agent has to work out what you sell, what it costs, and who it is for before it can recommend you - and it won't ask.
- [Design your site so agents can finish what they start](https://agentsurface.dev/guide/usability.md): An agent that can read your page but not act on it leaves the task exactly where a stuck customer would.

- [Agent Retrieval](https://agentsurface.dev/docs/agent-retrieval.md): Condensed current best practice for vector databases, embeddings, RAG patterns, and knowledge graphs
- [Agentic Commerce](https://agentsurface.dev/docs/agentic-commerce.md): What a merchant or commerce platform needs so agents can find products, trust the listing, check out, pay, and follow up on an order
- [Agentic UI](https://agentsurface.dev/docs/agentic-ui.md): Interface patterns for chat, copilots, generative UI, tool progress, approvals, and resumable agent work.
- [Build Agents](https://agentsurface.dev/docs/agents.md): What this part covers, how it relates to the core guide, and the design defaults that apply across every topic below.
- [API Surface](https://agentsurface.dev/docs/api-surface.md): HTTP, OpenAPI, and service contracts that agents can discover and call reliably
- [Authentication](https://agentsurface.dev/docs/authentication.md): Machine-to-machine and delegated authorization for agents
- [CLI Design](https://agentsurface.dev/docs/cli-design.md): Building CLIs that AI agents can operate as effectively as human users
- [Context Files](https://agentsurface.dev/docs/context-files.md): AGENTS.md as the baseline, plus optional tool-specific overlays that define agent boundaries and conventions
- [Discovery & AEO](https://agentsurface.dev/docs/discovery.md): Making your capabilities findable by AI agents through structured discovery mechanisms
- [Error Handling](https://agentsurface.dev/docs/error-handling.md): Structured errors that enable agents to diagnose failures and recover autonomously
- [Getting Started](https://agentsurface.dev/docs/getting-started.md): Choose a route through Agent Surface by goal: make a product usable by agents, assess it, or build agents of your own.
- [Glossary](https://agentsurface.dev/docs/glossary.md): Every term used on this site, defined once, with a link to the page that covers it in depth
- [What is Agent Surface?](https://agentsurface.dev/docs.md): A guide to making websites, apps, APIs and CLIs usable by AI agents, plus a current inventory of tools and practice for building agents
- [MCP Servers](https://agentsurface.dev/docs/mcp-servers.md): Implementing Model Context Protocol servers that expose your capabilities to AI agents
- [Protocols & Standards](https://agentsurface.dev/docs/protocols.md): The protocol landscape for agent-to-service and agent-to-agent communication
- [Reference Links](https://agentsurface.dev/docs/reference-links.md): Canonical standards, docs, specs, and source links for agent-readable software surfaces.
- [Retrievability](https://agentsurface.dev/docs/retrievability.md): Making your product's data and search results genuinely retrievable by AI agents
- [Scoring Framework](https://agentsurface.dev/docs/scoring.md): Measure and track your codebase's agent-readiness across 10 dimensions
- [Testing](https://agentsurface.dev/docs/testing.md): Building evals, metrics, and red-team suites to measure agent reliability
- [Tool Design](https://agentsurface.dev/docs/tool-design.md): Principles for defining tools that agents select correctly and execute reliably
- [AI Tooling Catalog](https://agentsurface.dev/docs/tooling-catalog.md): High-signal router for AI and agent tooling categories