Skip to content
AX Framework

Evaluation

Best Practices

A condensed checklist drawn from the principles and patterns.

A condensed checklist drawn from the principles and patterns. Use it for reviews; follow the links for the reasoning.

Discoverability

  • Publish a capability manifest and link to it from every page. — Capability Manifest
  • Describe every capability in one plain-language sentence.
  • Include available actions on resources. — Action Discovery
  • Version capabilities and announce deprecations in-band.

Comprehension

  • Use semantic HTML and labelled controls. — Structured Metadata
  • Embed schema.org JSON-LD generated from source data.
  • State units, currencies, and time zones every time.
  • Express constraints and policies as data.
  • Use one vocabulary across UI, data, and docs.

Actionability

  • Define actions as typed contracts shared by UI and agents. — Action Contracts
  • Validate input and preconditions server-side.
  • Accept idempotency keys on every mutation.
  • Model multi-step tasks as resumable workflows. — Multi-step Workflows

Feedback & Observability

  • Return an explicit status from every action.
  • Return a receipt for every state change. — Action Receipts
  • Give long-running work a status resource. — Execution Status
  • Report partial success per item.

Trust & Control

  • Never require a person's credentials; use scoped grants. — Permission Requests
  • Label actions by risk. — Sensitive Actions
  • Require approval for consequential actions through a product-controlled channel. — Human Approval
  • Label agent activity in logs people can see.
  • Make revocation one step.

Recovery & Resilience

  • Use a consistent error envelope with stable codes. — Error Handling
  • Mark every error as retryable or not.
  • Suggest next actions in errors.
  • Provide compensating actions for reversible steps. — Rollback
  • Support resuming tasks from an identifier. — Context Restoration

Process

  • Evaluate against tasks, not the product in general.
  • Test with real agents in staging, repeatedly.
  • Fix critical issues first; then the highest-value task.
  • Never trade accessibility for agent support.

Last updated 2026-10-06. AX Framework documentation describes proposals unless a section is marked as an established standard.