Architecture
Capability Discovery
Publishing what your product can do so agents can find it.
An agent arriving at your product needs to answer one question before anything else: what can I do here? Capability discovery is how your product answers it. This page covers where to publish capabilities, what to include, and how to keep the description honest.
AX proposalDiscovery entry points
Agents arrive in different ways, so publish more than one path to the same information:
| Entry point | Who uses it | What to provide |
|---|---|---|
HTML head | Agents that browse pages | A link element pointing to the manifest |
| Well-known path | Agents that know the convention | The manifest itself, e.g. /ax.json |
llms.txt | Language models reading a site summary | A short Markdown overview that links onward |
| MCP server | Agents in MCP-capable clients | The same capabilities as MCP tools |
| OpenAPI document | Agents and developer tools calling HTTP | Operations, schemas, auth |
llms.txt is a community proposal and MCP is an open protocol; the /ax.json manifest is an AX Framework proposal. None is required, and none replaces the others.
<link rel="alternate" type="application/json" href="/ax.json" title="Agent capability manifest" />
<link rel="alternate" type="text/plain" href="/llms.txt" title="Site summary for language models" />Manifest anatomy
A manifest is a product-level index. Keep it small enough to read in one request, and link to detailed schemas rather than inlining them.
{
"ax": "0.1",
"name": "Northwind Outfitters",
"description": "Outdoor apparel and footwear store shipping within the EU.",
"version": "2026-10-01",
"docs": "https://northwind.example/developers",
"auth": {
"type": "oauth2",
"authorizationUrl": "https://northwind.example/oauth/authorize",
"scopesUrl": "https://northwind.example/oauth/scopes"
},
"channels": {
"http": "https://northwind.example/api/ax",
"openapi": "https://northwind.example/openapi.json",
"mcp": "https://northwind.example/mcp"
},
"capabilities": [
{
"name": "search_products",
"description": "Search the catalog by keyword, category, size, and price range.",
"risk": "read",
"auth": "none",
"input": "https://northwind.example/schemas/search_products.input.json"
},
{
"name": "place_order",
"description": "Place an order for the current cart using a saved payment method.",
"risk": "high",
"auth": "user",
"scopes": ["orders:create"],
"requiresApproval": true,
"idempotent": true
}
],
"deprecated": [
{ "name": "checkout", "replacedBy": "place_order", "removalDate": "2027-01-01" }
]
}Field guidance
- description — one sentence, plain language, written so it can be relayed to a person unchanged.
- risk —
read,low,medium, orhigh. See the Sensitive Actions pattern. - auth —
none,session, oruser(requires a delegated grant). - requiresApproval — tells the agent to expect an approval step before it plans.
- deprecated — announce removals in-band, with a replacement and a date.
Describing capabilities well
The quality of a description decides whether an agent picks the right capability. Compare:
| Weak | Strong |
|---|---|
| "Cart endpoint" | "Add a product variant to the active cart." |
| "Process order" | "Place an order for the current cart using a saved payment method." |
| "Search" | "Search the catalog by keyword, category, size, and price range. Returns at most 50 results." |
Name capabilities with a verb and an object (start_return, list_orders). Avoid names that only make sense inside your codebase.
Keeping it honest
A manifest that lists capabilities that no longer work is worse than none. Generate it from the same definitions your handlers use, and add a test that every listed capability resolves to a handler.
import { buildManifest } from "@/lib/ax/manifest";
import { handlers } from "@/lib/ax/handlers";
test("every manifest capability has a handler", () => {
for (const c of buildManifest().capabilities) {
expect(handlers).toHaveProperty(c.name);
}
});Related
Last updated 2026-10-06. AX Framework documentation describes proposals unless a section is marked as an established standard.