A practical guide to agent-ready products

Make your website and app work with AI agents.

Help agents find your product, understand what it offers, and use it on a customer’s behalf. Here’s what to consider, why it matters, and where to start.

See the eight areas Technical documentation

The eight things to get right

57 recommendations

DiscoverabilityCan agents find you?11 recommendations
UnderstandabilityCan agents understand what you offer?14 recommendations
ConnectionsCan agents plug into your product?8 recommendations
Permissions & controlCan agents act safely for a customer?7 recommendations
UsabilityCan agents get things done?4 recommendations
ReliabilityCan agents recover when something goes wrong?6 recommendations
PaymentsCan agents pay within agreed limits?3 recommendations
MeasurementDo you know it's working?4 recommendations

01Discoverability

Can agents find you?

Help agents find your website, documentation, and integrations through the channels your customers use.

Why it mattersAgents can only recommend what they can find4 min read

Start here4

Depending on your product7

02Understandability

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.

Why it mattersExplain your business the way an agent reads4 min read

Start here2

Depending on your product12

03Connections

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.

Why it mattersGive agents something to plug into4 min read

04Permissions & 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.

Why it mattersLet agents act for customers without handing them the keys4 min read

05Usability

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.

Why it mattersDesign your site so agents can finish what they start4 min read

Start here1

Depending on your product3

06Reliability

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.

Why it mattersAgents need a plan for when something breaks4 min read

07Payments

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.

Why it mattersAgents can pay for a purchase, within limits you set4 min read

08Measurement

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.

Why it mattersMeasure whether agents finish the task4 min read

The language of agents

Plain-language definitions of the terms in this guide. Choose a card to learn more.

View all 132 terms

Put the guide to work

Choose a task a customer wants to complete and follow it from discovery to the final result. Use the docs for implementation detail, examples, and the tradeoffs behind each recommendation.

Evaluate a customer task Browse the docs Explore the glossary

This guide covers making your product work for agents. Building your own agents instead? See the agent-building guide.

Work through it with your coding agent

Install the Surface skill to apply this guidance to your codebase: explain a topic, assess what exists, or turn the findings into an implementation plan.

npx skills add https://github.com/howells/agentsurface

For Codex, Claude Code, Cursor, and other agents that support skills.

The eight things to get right

Start here4

Let agents reach your public contentCrawler access & content useCrawler access & content use

Give important pages stable URLsSitemaps & URLsSitemaps & URLs

Identify the business behind your productBusiness identityBusiness identity

Make your documentation easy to findPublic documentationPublic documentation

Depending on your product7

Give agents a documentation indexllms.txtllms.txt · For documentation sitesFor documentation sites

Publish where agents can connectAPI & tool discoveryAPI & tool discovery · If you offer integrationsIf you offer integrations

Publish your product and content feedsCatalogs & feedsCatalogs & feeds · If you publish a collectionIf you publish a collection

Provide evidence for publisher claimsPublisher verificationPublisher verification · If your catalog includes trust claimsIf your catalog includes trust claims

List your official integrationsOfficial listingsOfficial listings · If you distribute integrationsIf you distribute integrations

Package a plugin for each supported platformAgent pluginsAgent plugins · If you distribute an agent pluginIf you distribute an agent plugin

Advertise agent services through DNSDNS-AIDDNS-AID · Optional for compatible agent clientsOptional for compatible agent clients

Start here2

Explain when to use your productProduct use casesProduct use cases

Make key information readable as textReadable contentReadable content

Depending on your product12

Set each page's identity and preferred URLPage metadataPage metadata · For public pagesFor public pages

Label your information consistentlyStructured dataStructured data · For public contentFor public content

Publish prices and purchase termsPrices & termsPrices & terms · If you charge for products or servicesIf you charge for products or services

Keep availability and eligibility up to dateCurrent availabilityCurrent availability · If availability can changeIf availability can change

Provide Markdown versions of your pagesMarkdown viewsMarkdown views · For substantial documentationFor substantial documentation

Document your API with OpenAPIOpenAPIOpenAPI · If you offer an HTTP APIIf you offer an HTTP API

Document your GraphQL schemaGraphQL schemasGraphQL schemas · If you offer GraphQLIf you offer GraphQL

Describe what each tool accepts and returnsTool names & schemasTool names & schemas · If you provide agent toolsIf you provide agent tools

Describe what each action can changeTool behaviorTool behavior · If agents call your toolsIf agents call your tools

Show how to complete a real taskAgent skills & examplesAgent skills & examples · If tasks need several stepsIf tasks need several steps

Document how to work on your codebaseRepository instructionsRepository instructions · If agents work on your codeIf agents work on your code

Show where an answer comes fromSource referencesSource references · If you offer search or answersIf you offer search or answers

Make product actions available through an APIProduct APIsProduct APIs · If agents need direct integrationIf agents need direct integration

Connect your product through MCPMCP serversMCP servers · If customers use MCP clientsIf customers use MCP clients

Provide reference material through MCPMCP resourcesMCP resources · If your MCP clients read resourcesIf your MCP clients read resources

Provide a CLI for automated tasksCommand-line toolsCommand-line tools · For developer productsFor developer products

Provide maintained client librariesOfficial SDKsOfficial SDKs · If customers integrate through codeIf customers integrate through code

Add browser tools with WebMCPWebMCPWebMCP · Emerging for browser agentsEmerging for browser agents

Show interactive results in the conversationMCP AppsMCP Apps · If customers need interactive resultsIf customers need interactive results

Define tasks that other agents can delegateAgent delegationAgent delegation · If other agents delegate to yoursIf other agents delegate to yours

Provide a supported way for agents to sign inAuthenticationAuthentication · If customers sign inIf customers sign in

Publish your authentication requirementsAuthentication discoveryAuthentication discovery · If your API requires authorizationIf your API requires authorization

Document agent registration with auth.mdauth.md & registrationauth.md & registration · If agents register for your serviceIf agents register for your service

Verify who is sending automated requestsSigned bot identitySigned bot identity · If you use signed bot trafficIf you use signed bot traffic

Give agents only the access they needScoped permissionsScoped permissions · If agents access private data or make changesIf agents access private data or make changes

Keep external content separate from instructionsUntrusted contentUntrusted content · If agents read external or user contentIf agents read external or user content

Let customers review actions and take overApprovals & handoffApprovals & handoff · If actions need review or human helpIf actions need review or human help

Start here1

Make controls easy to identify and useAccessible interfacesAccessible interfaces

Depending on your product3

Make large collections searchableSearch & paginationSearch & pagination · If you have a large collectionIf you have a large collection

Support searches phrased as questionsNatural-language searchNatural-language search · If question-based search suits your contentIf question-based search suits your content

Return a result the agent can checkConfirming resultsConfirming results · If agents perform actionsIf agents perform actions

Explain what failed and how to recoverError responsesError responses · If you provide an API or toolsIf you provide an API or tools

Help agents recover from a missing pageMissing pagesMissing pages · For websites and documentationFor websites and documentation

Tell agents when they can retryLimits & retriesLimits & retries · If agents call your serviceIf agents call your service

Make repeated requests safeSafe retriesSafe retries · If agents make changesIf agents make changes

Report progress and failures for longer tasksBackground & batch jobsBackground & batch jobs · If work takes time or runs in batchesIf work takes time or runs in batches

Plan for API and tool changesVersioningVersioning · If you offer integrationsIf you offer integrations

Let agents prepare and complete purchasesAgent checkoutAgent checkout · If agents prepare or complete purchasesIf agents prepare or complete purchases

Set limits on what agents can spendSpending permissionsSpending permissions · If agents pay on a customer’s behalfIf agents pay on a customer’s behalf

Accept payment for individual resourcesPay-per-use accessPay-per-use access · If you charge per resource or requestIf you charge per resource or request

Provide a test environmentTest environmentsTest environments · If tests could affect real data or paymentsIf tests could affect real data or payments

Test complete tasks with a real agentTask testingTask testing · For every task you supportFor every task you support

Find out where agent tasks failMonitoringMonitoring · When agents use your productWhen agents use your product

Check how agents find and describe youSearch visibilitySearch visibility · For public productsFor public products

The language of agents

Put the guide to work

Work through it with your coding agent