Agent Experience · Part of uxuiprinciples
Design your product for the agents that now use it.
25 system-facing Agent Experience principles, each with a copy-paste artifact, a verifiable citation, and code. The reference for building agent-ready products.
Comprehensible
Expose your purpose in clean, machine-readable form so agents can use and cite it.
Accessible
Let agents authenticate with scoped identities and self-correcting errors, no human-only gates.
Actionable
Ship well-described, scoped tools with structured results agents can act on safely.
Accountable
Make agent activity visible, bound autonomy, and recover from failure gracefully.
Categories
Nine ways to handle agents
Context and comprehension
3 principlesMake what your product does parseable by a machine, in clean, token-efficient form.
Access and identity
5 principlesLet agents authenticate with scoped, least-privilege identities and self-correcting errors.
Discovery and navigation
3 principlesExpose machine-readable capability and resource maps agents can find and traverse.
Tools and capabilities
4 principlesDesign scoped, well-described tools and treat their metadata as a trust boundary.
Recovery and reliability
2 principlesFail gracefully and idempotently so agents can retry without duplicate side effects.
Memory and state
1 principlesPersist durable, resumable state across long, multi-step agent workflows.
Notifications and change
1 principlesTell agents when things change through webhooks, change feeds, and versioning.
Orchestration and handoff
2 principlesBe triggerable by other agents and define clear roles and handoff contracts.
Observability and governance
4 principlesMake agent activity visible, bound autonomy with limits, and render agent output safely.
Artifacts
Copy-paste, not theory
# Acme
> One-line description of what Acme does.
## Docs
- [Quickstart](https://acme.com/docs/quickstart.md): get running in 5 minutes
- [API reference](https://acme.com/docs/api.md): endpoints and schemas<script type="application/ld+json">
{"@context":"https://schema.org","@type":"SoftwareApplication","name":"Acme",
"description":"Acme helps teams do X.","url":"https://acme.com",
"offers":{"@type":"Offer","price":"29","priceCurrency":"USD"}}
</script>GET /docs/quickstart HTTP/1.1
Accept: text/markdown<link rel="alternate" type="text/markdown" href="/docs/quickstart.md">How to use this
Read the principle
Each principle states what to do, why, and what to avoid, with a primary citation.
Copy the artifact
Grab the manifest, schema, error shape, or header and adapt it to your stack.
Ship and verify
Dogfood it: expose llms.txt, a capability manifest, and markdown twins like this site does.