--- title: "Agent Surface" description: "A dense guide to agent-readable software, production agent systems, protocols, tooling, retrieval, evaluation, and the surface skill." url: "https://agentsurface.dev/" --- # Agent Surface A dense guide to agent-readable software, production agent systems, protocols, tooling, retrieval, evaluation, and the surface skill. For agents: start at [llms.txt](https://agentsurface.dev/llms.txt), add `.md` to any docs URL for Markdown, or connect an MCP client to https://agentsurface.dev/mcp to search and read the docs. ## Discoverability: Can agents find you? Help agents find your website, documentation, and integrations through the channels your customers use. #### Crawler access & content use: Let agents reach your public content Set crawler access rules and check your firewall. Use Content Signals to separately declare whether retrieved content may be used for search, AI answers, or training. Why it matters: Agents need access to read a page. Your content-use policy explains what they may do with it afterward. Applies: Start here. Read more: https://agentsurface.dev/docs/discovery/robots-txt #### Sitemaps & URLs: Give important pages stable URLs Maintain working links and a sitemap. Update its dates when content changes, and redirect moved pages to their replacements. Why it matters: Agents can return to the right information and give customers a source link that works. Applies: Start here. Read more: https://agentsurface.dev/docs/discovery/aeo-checklist #### Business identity: Identify the business behind your product Use consistent company names, domains, and contact details. Publish About, Contact, and Privacy pages, and connect official profiles through structured data. Why it matters: Agents can distinguish your business from similarly named products and identify who published the information. Applies: Start here. Read more: https://agentsurface.dev/docs/discovery/commercial-and-entity-discovery #### Public documentation: Make your documentation easy to find Link to product guidance, API docs, and integrations from your website. Explain setup requirements before asking someone to sign in. Why it matters: Agents can check whether your product can do the job before creating an account or starting an integration. Applies: Start here. Read more: https://agentsurface.dev/docs/api-surface/openapi-for-agents #### llms.txt: Give agents a documentation index Use llms.txt to introduce your product and link to your documentation. For large sites, link to separate indexes for each product area. Why it matters: Agents that read llms.txt can find relevant pages without fetching the whole manual. Publishing it does not guarantee search visibility or citations. Applies: For documentation sites. Read more: https://agentsurface.dev/docs/discovery/llms-txt #### API & tool discovery: Publish where agents can connect Use discovery metadata and catalogs to link to your API specification, MCP server, and other agent resources. Check that each address works and matches its description. Why it matters: Agents can find the right connection details without guessing URLs. Applies: If you offer integrations. Read more: https://agentsurface.dev/docs/discovery/well-known-endpoints #### Catalogs & feeds: Publish your product and content feeds Offer structured feeds, including NLWeb schema feeds, for clients that use them. Validate ARD or AI Catalog entries against the format you publish, and check every linked resource. Why it matters: Agents can discover individual items and update their information as your catalog changes. Applies: If you publish a collection. Read more: https://agentsurface.dev/docs/discovery/catalogs-and-feeds #### Publisher verification: Provide evidence for publisher claims A catalog's trust manifest can include publisher details, signatures, or attestations. Publish claims that the receiving client can verify, including who issued them and whether they remain valid. Why it matters: Clients can check the evidence behind a publisher's claims before trusting a resource. Applies: If your catalog includes trust claims. Read more: https://agentsurface.dev/docs/discovery/catalogs-and-feeds #### Official listings: List your official integrations List your SDKs, skills, plugins, and apps in the directories customers use. Link each listing to your domain and keep installation instructions and publisher details current. Why it matters: Customers and agents can find your integration and distinguish it from unofficial alternatives. Applies: If you distribute integrations. Read more: https://agentsurface.dev/docs/discovery/commercial-and-entity-discovery #### Agent plugins: Package a plugin for each supported platform Bundle related skills, tools, or MCP connections into an installable plugin. Include the platform's required manifest, setup instructions, and publisher details, then test installation in that host. Why it matters: Customers can install the integration as a package. Testing each host catches differences between plugin formats. Applies: If you distribute an agent plugin. Read more: https://agentsurface.dev/docs/discovery/commercial-and-entity-discovery #### DNS-AID: Advertise agent services through DNS Publish DNS records that point to your agent services, so compatible clients can find their connection details. DNS-AID is an emerging proposal; use it when your clients support it. Why it matters: A client that knows your domain can locate your agent services without searching the website for connection details. Applies: Optional · for compatible agent clients. Read more: https://agentsurface.dev/docs/discovery/dns-discovery ## Understandability: Can agents understand what you offer? Explain what your product does and what its data means. Give agents the prices, terms, and limits they need to make a decision. #### Product use cases: Explain when to use your product Describe the tasks your product supports, who it is for, and its limits. Include examples of the work a customer can complete. Why it matters: Agents can recommend your product for suitable tasks without promising features you do not offer. Applies: Start here. Read more: https://agentsurface.dev/docs/discovery/commercial-and-entity-discovery #### Readable content: Make key information readable as text Serve the important content in HTML, with clear headings and focused sections. Include text descriptions of essential visuals and make key facts available without JavaScript. Why it matters: Agents use different reading tools. Information stored only in images or scripts may be missed. Applies: Start here. Read more: https://agentsurface.dev/docs/discovery/content-structure #### Page metadata: Set each page's identity and preferred URL Set the page title, language, and canonical URL—the preferred address for that page. Add relevant Open Graph image and type metadata, and link alternate formats to the same source. Why it matters: Search results and shared previews can point to the correct page, even when duplicates or regional versions exist. Applies: For public pages. Read more: https://agentsurface.dev/docs/discovery/structured-data #### Structured data: Label your information consistently Use JSON-LD to identify organizations, products, offers, FAQs, and breadcrumbs and their relationships. Include accurate contact details and only genuine reviews or ratings. Why it matters: Agents can tell which product a price belongs to and how the information on a page relates to your business. Applies: For public content. Read more: https://agentsurface.dev/docs/discovery/structured-data #### Prices & terms: Publish prices and purchase terms State the currency, billing unit, taxes, shipping costs, and usage limits. Include cancellation and return terms. Keep any pricing.md version consistent with the prices customers see. Why it matters: Agents can compare the full cost and conditions before recommending a plan or preparing a purchase. Applies: If you charge for products or services. Read more: https://agentsurface.dev/docs/discovery/commercial-and-entity-discovery #### Current availability: Keep availability and eligibility up to date Publish current stock, service availability, and regional or customer restrictions. Identify the source of these facts and check them again before an order or booking is confirmed. Why it matters: Agents can avoid recommending something the customer cannot buy or use on the stated terms. Applies: If availability can change. Read more: https://agentsurface.dev/docs/discovery/commercial-and-entity-discovery #### Markdown views: Provide Markdown versions of your pages Publish links to Markdown pages and let clients request Markdown through content negotiation where supported. Preserve page metadata, formatting, and facts. Check that caches return the requested format. Why it matters: Agents can read the content with less navigation and interface markup taking up space in their context. Applies: For substantial documentation. Read more: https://agentsurface.dev/docs/discovery/content-negotiation #### OpenAPI: Document your API with OpenAPI Publish an OpenAPI specification describing operations, inputs, responses, authentication, and errors. Update it when the API changes. Why it matters: Agents and integration tools can build valid requests and know what results to expect. Applies: If you offer an HTTP API. Read more: https://agentsurface.dev/docs/api-surface/openapi-for-agents #### GraphQL schemas: Document your GraphQL schema Describe types, fields, arguments, and limits. Explain pagination, typed errors, background jobs, and bulk mutations where applicable, along with field deprecation and removal. Why it matters: Agents can construct queries and detect failures in the response. An HTTP success status alone does not establish that a GraphQL operation succeeded. Applies: If you offer GraphQL. Read more: https://agentsurface.dev/docs/api-surface/retrieval-and-job-contracts #### Tool names & schemas: Describe what each tool accepts and returns Give tools clear names and descriptions, typed inputs and results, and unique operation identifiers. Explain constraints and test the schemas with the clients you support. Why it matters: Agents can choose the right tool and supply valid arguments with fewer failed attempts. Applies: If you provide agent tools. Read more: https://agentsurface.dev/docs/tool-design/schemas #### Tool behavior: Describe what each action can change Use metadata such as MCP annotations to identify read-only actions, destructive changes, safe retries, and calls to outside systems. Keep these hints accurate; enforce permissions and approvals on the server. Why it matters: Clients can warn users about consequences and decide how to handle a tool call. The hints themselves grant no permission. Applies: If agents call your tools. Read more: https://agentsurface.dev/docs/mcp-servers/annotations #### Agent skills & examples: Show how to complete a real task Provide working examples and focused agent skills. In the skills index, explain when to use each skill, link to its files, and include digests that match those files. Why it matters: Agents get the prerequisites, steps, and expected result for a task, rather than a list of features they must piece together. Applies: If tasks need several steps. Read more: https://agentsurface.dev/docs/discovery/agent-skills #### Repository instructions: Document how to work on your codebase Use AGENTS.md to describe the repository layout, essential commands, coding conventions, and permission boundaries. Keep instructions with the code they describe. Why it matters: Coding agents can follow your team's practices and run the right checks without rediscovering the project setup. Applies: If agents work on your code. Read more: https://agentsurface.dev/docs/discovery/agents-md #### Source references: Show where an answer comes from Return source links, stable identifiers, relevant context, and update dates with retrieved information. Preserve access permissions when indexing private documents. Why it matters: Agents can check the source and age of a claim before using it in an answer. Applies: If you offer search or answers. Read more: https://agentsurface.dev/docs/retrievability/freshness-and-provenance ## Connections: Can agents plug into your product? Offer the direct ways agents work with your product: APIs, MCP servers, command-line tools, and SDKs. Start with the ones your customers' agents already support. #### Product APIs: Make product actions available through an API Provide API operations for the tasks customers need to automate. Enforce the same business rules and permissions as your website or app. Why it matters: Agents can perform tasks through documented requests without having to operate each screen. Applies: If agents need direct integration. Read more: https://agentsurface.dev/docs/api-surface #### MCP servers: Connect your product through MCP Use an MCP server to offer product tools to compatible agent clients. Describe its identity and capabilities, use a supported transport such as Streamable HTTP, and test authentication and error handling. Why it matters: Customers can use your product from an agent client they already work in, with defined inputs and results. Applies: If customers use MCP clients. Read more: https://agentsurface.dev/docs/mcp-servers #### MCP resources: Provide reference material through MCP Publish documentation and reference data as MCP resources for clients that read them. Specify the content type and check that every listed resource returns content with working links. Why it matters: Agents can read your documentation while using your tools, without needing a separate way to fetch it. Applies: If your MCP clients read resources. Read more: https://agentsurface.dev/docs/mcp-servers/resources-prompts #### Command-line tools: Provide a CLI for automated tasks Maintain a command-line tool that takes explicit inputs, returns structured output, and can run without interactive prompts. Why it matters: Coding agents can use your product in scripts and terminal workflows. Applies: For developer products. Read more: https://agentsurface.dev/docs/cli-design/machine-readable-output #### Official SDKs: Provide maintained client libraries Publish SDKs for the languages customers use, with working examples and links to your domain and repository. Keep each library compatible with the API versions it supports. Why it matters: Developers and coding agents get tested client code and can identify the packages your team maintains. Applies: If customers integrate through code. Read more: https://agentsurface.dev/docs/discovery/commercial-and-entity-discovery #### WebMCP: Add browser tools with WebMCP WebMCP lets compatible browser agents discover and call tools within a page. Check support in the browsers you target and keep accessible controls available. Why it matters: Agents can call a defined action directly, reducing the guesswork involved in clicking through the interface. Applies: Emerging · for browser agents. Read more: https://agentsurface.dev/docs/protocols/webmcp #### MCP Apps: Show interactive results in the conversation Use MCP Apps or a supported generative UI integration to show interactive views in chat. Check loading, accessibility, and host themes. Keep secrets out of the HTML and restrict content security policies to required hosts and connections. Why it matters: Customers can inspect and adjust results when a text response does not give them enough control. Applies: If customers need interactive results. Read more: https://agentsurface.dev/docs/agentic-ui/mcp-apps #### Agent delegation: Define tasks that other agents can delegate For an agent service, describe the tasks it accepts and how callers track progress and retrieve results. Use a supported delegation protocol such as A2A. Why it matters: Another agent can hand over a defined task and follow it through to completion, including work that takes more than one tool call. Applies: If other agents delegate to yours. Read more: https://agentsurface.dev/docs/protocols/a2a ## Permissions & control: Can agents act safely for a customer? Explain how agents sign in, keep their access to the minimum a task needs, and let customers see and revoke that access at any time. #### Authentication: Provide a supported way for agents to sign in Explain which actions are public and how to obtain credentials for protected actions. For access on a user's behalf, provide a delegated flow such as OAuth. Why it matters: Agents can connect with the user's consent without asking for their password. Applies: If customers sign in. Read more: https://agentsurface.dev/docs/authentication/oauth-for-agents #### Authentication discovery: Publish your authentication requirements For OAuth-protected APIs, publish resource and authorization-server metadata with supported scopes and working endpoints. Link authentication challenges to that metadata. Why it matters: An agent can find the right authorization service and learn which permissions to request. Applies: If your API requires authorization. Read more: https://agentsurface.dev/docs/authentication/protected-resource-metadata #### auth.md & registration: Document agent registration with auth.md Publish the registration steps, accepted identity methods, and endpoints for registration, account claiming, and token exchange. Explain errors and how access can be revoked. Why it matters: Agents can follow the setup process and involve a person at the right step, without guessing how your sign-up forms work. Applies: If agents register for your service. Read more: https://agentsurface.dev/docs/authentication/auth-md #### Signed bot identity: Verify who is sending automated requests Use signed HTTP requests, such as Web Bot Auth, when both sides support them. Senders publish verification keys; receivers check signatures and apply their access rules. Why it matters: A signature helps verify the sender behind a bot name. Access to a customer's account still requires that customer's permission. Applies: If you use signed bot traffic. Read more: https://agentsurface.dev/docs/authentication/agent-identity#web-bot-auth #### Scoped permissions: Give agents only the access they need Define machine-readable scopes for reading and changing data. Enforce user and account boundaries on every protected request, and let customers revoke access. Why it matters: Agents stay within the access the customer granted, including when they call the API directly. Applies: If agents access private data or make changes. Read more: https://agentsurface.dev/docs/authentication/agent-identity #### Untrusted content: Keep external content separate from instructions Treat retrieved pages, documents, and user submissions as data. Keep permission and approval rules separate, and test attempts to redirect the agent through that content. Why it matters: Instructions hidden in a search result or document should not let an attacker read private data or trigger an action. Applies: If agents read external or user content. Read more: https://agentsurface.dev/docs/testing/red-teaming #### Approvals & handoff: Let customers review actions and take over Let agents prepare changes and show the details for approval when required. Keep the task history and current state available when a person takes over. Why it matters: Customers can correct a misunderstanding before committing and continue the task without starting again. Applies: If actions need review or human help. Read more: https://agentsurface.dev/docs/agentic-ui/session-control ## Usability: Can agents get things done? Give agents controls they can identify, ways to search your content, and a confirmed result once a task is done. #### Accessible interfaces: Make controls easy to identify and use Use native buttons, links, and form fields with meaningful labels. Provide logical keyboard focus, clear validation, and visible changes of state. Why it matters: Browser agents can identify the right controls and check what happened after using them. People using assistive technology benefit too. Applies: Start here. Read more: https://agentsurface.dev/docs/agentic-ui/browser-agent-accessibility #### Search & pagination: Make large collections searchable Provide search, filters, stable item identifiers, and predictable pagination. Return source links when results include generated answers. Why it matters: Agents can narrow the results and work through each page without missing items or downloading the entire collection. Applies: If you have a large collection. Read more: https://agentsurface.dev/docs/api-surface/retrieval-and-job-contracts #### Natural-language search: Support searches phrased as questions Offer a documented query interface, such as NLWeb, with structured results and source links. If results stream back, define how the stream reports completion and errors. Why it matters: Agents can search using the customer's question and tell when they have received a complete answer. Applies: If question-based search suits your content. Read more: https://agentsurface.dev/docs/discovery/catalogs-and-feeds #### Confirming results: Return a result the agent can check Return the saved result, its identifier, and its status. Distinguish a request being accepted from work finishing, a payment clearing, or an order being fulfilled. Why it matters: Agents can tell the customer what actually happened and link to the result. Applies: If agents perform actions. Read more: https://agentsurface.dev/docs/scoring/product-journeys ## Reliability: Can agents recover when something goes wrong? Explain what went wrong, when it's safe to try again, and how your API changes without breaking existing integrations. #### Error responses: Explain what failed and how to recover Return stable error codes, clear messages, and recovery hints in the documented format: JSON for HTTP APIs and structured protocol errors for MCP. Why it matters: Agents can decide whether to fix an input, ask for permission, try later, or stop. Applies: If you provide an API or tools. Read more: https://agentsurface.dev/docs/error-handling/errors-for-agents #### Missing pages: Help agents recover from a missing page Return 404 or 410 when content is missing, with an explanation and links to search, a sitemap, or the docs index. Redirect moved pages to their replacements. Why it matters: Agents can recognize a missing page and find another source, instead of treating your app's empty shell as the requested content. Applies: For websites and documentation. Read more: https://agentsurface.dev/docs/discovery/content-negotiation #### Limits & retries: Tell agents when they can retry Document quotas and timeouts, return rate-limit headers, and explain when to retry. Limit repeated attempts and distinguish temporary failures from permanent ones. Why it matters: Agents can wait when the service is busy and stop retrying requests that cannot succeed. Applies: If agents call your service. Read more: https://agentsurface.dev/docs/error-handling/retry-patterns #### Safe retries: Make repeated requests safe Use idempotency keys or equivalent safeguards for requests that create or change data. After an interrupted request, let the caller check whether it completed. Why it matters: Retrying after a network failure should not place a second order or charge the customer again. Applies: If agents make changes. Read more: https://agentsurface.dev/docs/error-handling/idempotency #### Background & batch jobs: Report progress and failures for longer tasks Give background jobs an identifier and a way to check their status. Support progress updates and cancellation where possible. For batch operations, report which items succeeded or failed. Why it matters: Agents can resume after an interruption and identify the work that still needs attention. Applies: If work takes time or runs in batches. Read more: https://agentsurface.dev/docs/api-surface/retrieval-and-job-contracts #### Versioning: Plan for API and tool changes Version public APIs and tool contracts. Announce retiring features with migration instructions, and check changes to API, GraphQL, and tool schemas against supported clients. Why it matters: Customers have time to update their integrations before a change breaks an automated task. Applies: If you offer integrations. Read more: https://agentsurface.dev/docs/api-surface/api-versioning ## Payments: Can agents pay within agreed limits? Support the purchase from offer to confirmed payment and delivery. Choose checkout and payment methods your customers and providers can use. #### Agent checkout: Let agents prepare and complete purchases Provide offers, totals, purchase terms, and checkout operations through a supported integration such as UCP or ACP. Include order status and cancellation behavior. Why it matters: Agents can prepare a purchase for approval, complete it when authorized, and check the resulting order. Applies: If agents prepare or complete purchases. Read more: https://agentsurface.dev/docs/agentic-commerce/checkout-protocols #### Spending permissions: Set limits on what agents can spend Set the amount, currency, merchant, and expiry of spending permission. Use supported payment credentials or signed mandates, such as AP2, and verify permission before payment. Why it matters: Agents can pay within the customer's approved limits. Preparing a cart alone grants no spending permission. Applies: If agents pay on a customer’s behalf. Read more: https://agentsurface.dev/docs/agentic-commerce/payments #### Pay-per-use access: Accept payment for individual resources For paid API calls, content, or compute, use a supported HTTP payment protocol such as MPP or x402. Publish the price and terms, verify payment credentials, and return a receipt. Why it matters: Agents can buy access within their budget and check what they paid for if delivery fails or a request is retried. Applies: If you charge per resource or request. Read more: https://agentsurface.dev/docs/agentic-commerce/payments ## Measurement: Do you know it's working? Test in a safe environment, run real tasks end to end, and track whether agents find and use your product correctly. #### Test environments: Provide a test environment Offer a documented sandbox or test mode with sample data and credentials. Clearly label it and explain how it differs from production. Why it matters: Agents and developers can test setup, changes, payments, and failure recovery without affecting customers. Applies: If tests could affect real data or payments. Read more: https://agentsurface.dev/docs/testing/evaluation-framework #### Task testing: Test complete tasks with a real agent Run representative tasks in the agent client customers use. Test failures and denied permissions as well as success. Use a sandbox for risky actions and inspect the final result. Why it matters: A valid schema or high scanner score can still leave a customer unable to complete a task. End-to-end tests reveal those failures. Applies: For every task you support. Read more: https://agentsurface.dev/docs/testing/evaluation-framework #### Monitoring: Find out where agent tasks fail Track results, errors, response times, and usage, with enough detail to trace a failed operation. Keep sensitive data out of logs. Why it matters: You can locate the failed step and check whether a fix helps customers complete the task. Applies: When agents use your product. Read more: https://agentsurface.dev/docs/testing/observability #### Search visibility: Check how agents find and describe you Test searches for your brand, customer use cases, and developer docs. Publish content that answers those queries and seek independent coverage. Link Wikipedia or Wikidata entries only when your business qualifies. Why it matters: You can see where agents miss your product or describe it incorrectly, then address the missing or misleading information. Applies: For public products. Read more: https://agentsurface.dev/docs/discovery/commercial-and-entity-discovery ## Read more - [Documentation](https://agentsurface.dev/docs) - [llms.txt](https://agentsurface.dev/llms.txt) - [llms-full.txt](https://agentsurface.dev/llms-full.txt) - [MCP endpoint](https://agentsurface.dev/mcp) - [Glossary](https://agentsurface.dev/glossary)