AX Anti-Patterns: What Breaks Agent Experience

Patterns

What breaks agent experience and how to fix it

Anti-Patterns

The Invisible Product

Your product does not appear in AI answers about your category because AI platforms have incomplete context about what you do.

The Silent Error

Your API returns 'something went wrong' with no code, no classification, and no recovery path. Agents are stuck.

The Browser Wall

Authentication requires visual browser interaction. Agents can navigate browsers but it is slow, fragile, and often blocked.

The Missing Retry

Your API returns 429 Too Many Requests but provides no guidance on when to retry. Agents either hammer the endpoint or stop.

The Category Mismatch

AI platforms place your product in the wrong category or compare it to products it does not compete with.

The Overclaim

AI platforms describe your product as capable of things it cannot do, often because your marketing copy overstates features.

The Stale Signal

Your product changes frequently but AI platforms continue to describe the old version. Agents recommend deprecated features.

The Permission Ambiguity

Your API does not distinguish between read, write, and destructive operations. Agents cannot know what is safe.

The Flat Capability Dump

Your API documentation lists hundreds of endpoints in alphabetical order with no grouping or task-based organisation.

The One-Way Door

Your product triggers irreversible actions with no confirmation, no preview, and no rollback. Mistakes cannot be undone.

Best Practices

1. Publish a clear llms.txt

Your llms.txt is the first thing an agent reads about your product. It should describe what you do, what agents can do, and what you do not support. Update it when your product changes.

Implementation

Place at your root URL. Follow the llms.txt spec. Include a limitations section. Add a changelog with ISO dates.

2. Return typed errors with recovery guidance

Every error is an opportunity to keep the agent moving. Typed codes, plain descriptions, and next-action guidance turn failures into recoverable events rather than dead ends.

Implementation

Define a shared error schema across all endpoints. Include: code (string), message (string), retry (boolean), suggested_action (string). Document it as a public contract.

3. Offer scoped API token authentication

Browser-only OAuth is the single most common cause of agent abandonment. Tokens with explicit permission scopes let agents authenticate without visual browser interaction.

Implementation

Add a token management screen to your dashboard. Support read-only, write, and admin scopes at minimum. Document the token endpoint in your llms.txt.

4. Declare your product category in structured data

Schema.org markup gives AI platforms a reliable, structured source of truth about what your product is and who it serves.

Implementation

Add SoftwareApplication or Product schema to your homepage. Include applicationCategory, description, and featureList properties. Validate with Google's Rich Results Test.

5. Version your API and document breaking changes

Agents build plans around your API's behaviour. Breaking changes without notice destroy those plans and erode trust.

Implementation

Use semantic versioning. Include a version field in every response. Publish a public changelog. Provide a deprecation period of at minimum 90 days for breaking changes.