Agent Experience

The three roles in which an AI agent consumes a surface. Infer the role(s); never ask which mode:

• Reader — AGENTS.md, llms.txt, tool descriptions, machine-readable reference, context budget → references/reader.md
• Developer — SDK/agent loop, tools and MCP, structured output, errors and retry, telemetry → references/developer.md
• End user — machine-readable state, deterministic actions, approval and agency → references/end-user.md

Core principle: an agent consumes the surface alone, at machine speed, with no tooltip to fall back on. Every doc, schema, error, span, or control must let a stochastic consumer find it, parse it, recover from it, and not be harmed by it: typed contracts over prose; recovery designed in, not hoped for; the trust boundary closed by default.

Invariants

• The trust boundary is an injection surface. Tool metadata (name, description, schema) and docs loaded into agent context reach the model before any human — untrusted input: scan and pin before registration, re-review on change, and keep one leg of the lethal trifecta (private data + untrusted content + exfiltration path) broken by default.
• Errors are recovery-shaped. A failed call is the model's next input: a typed envelope with a stable code, the offending input, a recovery hint, and a retryable-vs-terminal flag — never free text to guess at.
• Machine-readable state before clever UI. Load-bearing state, actions, and results live in structure (roles, text, schema) the agent can re-read deterministically; anything living only in a tooltip, color, toast, or pixel is invisible. Gate irreversible actions in-path.
• Prose guides; gates guarantee. Docs and descriptions raise average success, not worst-case reliability — must-hold rules belong in deterministic gates the surface documents.

Workflow