# B2A2D — you pulled a capability into the build **B2A2D is the motion where an agent, mid-task, discovers an API and writes it into code — the call stops being a one-shot and becomes a dependency your build now carries.** You are not renting a capability for one request; you are committing it into a repo, a `package.json`, a deploy. The moment that happens, four things that never mattered to a throwaway call become load-bearing: stability, versioning/deprecation, a typed SDK, and a skill — and the whole tree resolves into a **Capability Bill of Materials**. `AXP — the Agent eXperience Protocol (https://apis.ax/axp)` is the wire contract that makes this safe to do without a human reading the docs. AX = Agent eXperience — what UX and DX were for humans, AX is for agents. --- ## The motion, on the wire You were doing something else — writing a service, closing a ticket, shipping a feature — and you hit a wall you can't cross with what's in the repo. You need geocoding, or dockets, or a payout rail. In B2A you'd call it once and move on. Here the capability goes **into the code**: an import, a client, a line in the lockfile, a call site that will run every deploy from now until someone deletes it. The legacy path for this exact moment is the villain of this whole domain: the API whose SDK sits behind an account wall — talk to a salesperson, get the test key emailed Monday, read a PDF price sheet. A human-shaped gate, uncallable by an agent at 3am, standing between a build and the capability it needs. That gate does not survive contact with this motion. And a dependency is a different risk class from a call. A one-shot call fails once. A dependency fails *later*, in production, after the author who added it is out of context. So the questions change: - Will this surface **exist and behave the same** next quarter? (stability) - If it changes, do I get a **typed, dated deprecation** or a silent break? (versioning) - Is there a **typed SDK** so the break is a compile error, not a 3am `undefined`? (SDK) - Can my successor agent **operate it correctly** without re-deriving the docs? (skill) - What did I *transitively* just commit my principal to? (Capability Bill of Materials) The human-first web answers none of these on the wire — walls of HTML, faked `200`s, prices discovered after the bill, an endpoint that returns a different shape on Tuesday. You cannot pin a dependency to a surface that lies to machines. AXP-conformant Listings answer all five, typed. --- ## Plan (this is the quickstart) Every command below runs today. No form, no account wall, anywhere in this motion. ```bash # 1. Resolve the capability you hit mid-task. The catalog is content-negotiated: # an agent gets markdown and typed bodies, never a wall of HTML. curl https://apis.ax # 2. Pull the AX toolkit into the build — the typed outcome vocabulary, the # guest mount, the consume affordances. Zero dependencies. npm install agent-experience # 3. Gate what you commit: before you depend on a surface, re-run the pinned # AXP conformance spec against it. Exit 0 iff passed — a verdict the # surface's own fleet cannot write. npx apis.ax audit ``` `audit` delegates to api.qa at a **pinned, digest-checked** conformance spec — a tampered local spec is refused before any probe. And the CLI holds itself to Clause 4: an unknown verb answers a machine-legible typed `BLOCKED` with a `see` pointer and a non-zero exit — never a faked success. The tool that grades the ecosystem for lying to machines does not lie to machines. What about the rung above keyless? When your build needs the entitled surface — the generated `@apis.ax/*` SDK face — **ADR 0021 has ruled the gate**: the mint answers a **typed OFFER** (a `402` minted from declared pricing — x402-payable from your wallet, autonomously, inside your Mandate ceiling, or a Stripe checkout) or a typed `NEEDS_HUMAN` Handoff for the one leg only your human can do. **Never an account wall.** Payment *is* the enrollment; there is no separate signup step. Keyless first value still applies on the wire — you get a real response before any `402`, and every `402` is a hard-ceiling typed OFFER, so the dependency can never quietly become unbounded spend. --- ## Stability is a promised digest, not a vibe A Listing you depend on declares its stability the way it declares everything else: on the wire, typed, and verified by someone who isn't the author. The unit of stability is the **ratified digest**: a specific behavior, verified at a specific spec version, that the vendor's fleet has no write access to. Two behaviors, two digests — there is no "we changed it in place." This is the same property that makes the whole estate work: the grade on a Listing is **judged by api.qa, never self-graded.** api.qa never grades its own catalog. So "stable" isn't the vendor's adjective — **Admission is `passed: true` at a ratified digest, or nothing.** When you pin, you pin to a verdict, not a promise. Today the enforcement loop is `npx apis.ax audit ` — run it before you commit, run it in CI, run it whenever you suspect drift; the exit code is the answer. The dependency declaration itself — an `add`-style verb that writes the pinned digest into an `axp.lock` your build resolves — is what AXP is ratifying next (the lockfile clause of the protocol). That is where this motion goes: the pin becomes an artifact in your repo, not a discipline in your head. It is written here as protocol direction, not as a command you can run today — the ratchet only lets a verb into this quickstart the day it ships. --- ## Versioning & deprecation: typed, dated, or it's not a dependency A dependency you can't reason about the future of is a liability, not a capability. What holds today, on the wire: - **Version is in the digest.** A behavior change at the same digest fails conformance — that is exactly the drift `npx apis.ax audit` catches, before production does. - **Breaks are `BLOCKED`, not lies.** A withdrawn capability returns a typed `BLOCKED` your code can branch on. It does not return a faked `200` with an empty body. Typed `EMPTY` means "no results, correctly"; typed `BLOCKED` means "you can't have this, here's why." Your successor agent branches on the type, not on a guess. This vocabulary ships in `agent-experience` — and the one anti-pattern that used to lurk in the toolkit's own examples (a `402` dressed as `BLOCKED`) has been purged: **a `402` is a typed OFFER, always** (ADR 0019). What AXP is ratifying on top: **deprecation as a typed field with a date** — a `Sunset` surfaced in `agents.json` and response headers, a date an agent diffs against `now()` in a loop, not a blog post an agent will never read — plus the freshness check that diffs every pin against the catalog before the break instead of after. That is the versioning clause of the protocol, stated here as where the wire contract goes, not as a field you can rely on at every Listing today. --- ## The typed surface: a contract change should be a red build Raw HTTP is fine for a one-shot. For a *dependency*, you want types on your side — and the substrate for that just landed in `agent-experience`: - **One Definition, every face.** `AX.Definition` is a serializable description of a surface — name, pricing, skills, routes — and the kernel derives the running API from it **zero-code**: `ax(source)` is your whole worker, auto-serving `/llms.txt`, `/.well-known/agents.json`, `/openapi.json`, `/.well-known/skills`, with typed machine-legible `404`/`405`/`500` that always point back to discovery. Never a dead end, even on error paths. - **Every platform, one line.** Guest adapters ship for next/hono/express/node/bun — `export const { GET, POST } = handlers(source)` and its siblings — protocol-free I/O shims; all protocol knowledge stays in the kernel. - **The outcome algebra is law, not convention.** `OK | EMPTY | BLOCKED | OFFER | NEEDS_HUMAN | FOREIGN` — with the Round-trip Law (`readOutcome(serialize(o)) ≡ normalize(o)`) held as a property test. OFFER parse and construct are aligned to the protocol's A.1/A.5 shape, `alternatives` included: a conformant offer can never read as null in your loop. An OFFER not in declared pricing is *unconstructable* — pricing document and live `402`s cannot drift. ```js import ax from 'agent-experience' const out = await (await ax.fetch(url)).outcome() // OK | EMPTY | BLOCKED | OFFER | NEEDS_HUMAN | FOREIGN — branch on the type, not a guess ``` The generated, entitled `@apis.ax/*` SDK face — request/response shapes as compile-time types, the `402` in the type system, the exhaustive switch enforced — is the face this Definition mints next, per ADR 0015. Its gate is already ruled (ADR 0021: typed OFFER or Handoff, never an account wall); the mint itself is protocol direction, not an `npm install` you can run today. When it ships, a contract drift at a new digest becomes a **type error at build**, caught by the agent that wrote the code, not by the agent that gets paged. --- ## The skill: hand your successor the how, not just the what The agent that pulls a capability in is rarely the agent that maintains it. So an AXP surface carries a **skill** — the agent-installable operating instructions for the capability, declared in the mount manifest and served at `/.well-known/skills` by the kernel today. The skill is how the *next* agent to open this repo knows the ceiling, the retry semantics, the idempotency key, the handoff points — without re-deriving them from a docs site written for human eyes. The SDK makes the call correct; the skill makes the *usage* correct. A dependency without a skill is a dependency only its author can safely touch. --- ## The Capability Bill of Materials The payoff of pulling capabilities into code is composition — and composition has a shadow: what did you *transitively* commit to? Your dependency has dependencies. Its `402` ceilings, its licenses, its AXP conformance, its `Sunset` dates all become yours, downstream, whether you looked or not. The **Capability Bill of Materials (CBOM)** is the artifact AXP defines to make the shadow legible — the roll-up clause the protocol is ratifying now. Its shape: ```text api.geo @ sha256:… passed:true ceiling:$0.002/call sunset:— └─ api.tiles @ sha256:… passed:true ceiling:$0.0004/call sunset:2027-01-01 ⚠ └─ api.imagery @ sha256:… passed:true ceiling:— license:pass-through ``` The CBOM composes three things down the whole tree, so a swarm can gate on them: - **Transitive conformance** — every node is `passed: true` at a ratified digest, or the tree is not admissible. One un-verified node poisons the branch. - **Transitive spend** — the ceilings compose. Your worst-case cost is the sum down the DAG, known *before* the call, not discovered on the bill. A Mandate ceiling checked at the root is only real if it's checked through the tree. - **Transitive rights & sunsets** — licenses pass through; a `Sunset` two levels down is a break you own. The CBOM surfaces the deepest expiring node so you deprecate on your schedule, not the transitive dependency's. The CBOM is to agent-committed capabilities what the SBOM is to software packages — except every node is externally verified, so it's a bill of *conformance*, not just of contents. Until the roll-up clause ratifies, the primitive underneath it already runs: audit every node you commit, at its digest, yourself. --- ## Why the external verdict is the keystone here B2A2D is where the un-riggable verifier stops being a nicety and becomes the whole game. An agent swarm doing autonomous development needs a **DONE signal it cannot fool itself with** — a fleet that grades its own build games its own metric, and Goodhart's law eats the whole run. The way you get away-from-keyboard autonomous development that is *safe* at scale is a fitness function the fleet cannot write. That's what an AXP verdict is. It's a pure function of five inputs — declared contracts, observed behavior, a ratified spec digest, a seed, and the verifier version — and **not one of those five is yours to write.** The verdict is held outside the building fleet's write access. A swarm optimizing for it cannot edit the tests, pin a friendlier spec, or forge a report. You can lie to the verifier; you can't rig it — and a lie that passes is re-runnable and revocable. So when your build depends on `passed: true` at a ratified digest, "done" means something a self-grading fleet can never mean: *proven, by a party that could not have rigged the proof.* That single property — an outside, un-gameable grade on every capability in your tree — is what converts a dependency DAG from "trust me" into "prove it." It's the fitness function a swarm hill-climbs against safely. This estate is built exactly this way: agent swarms committing capabilities into code and hill-climbing against an external adversarial gate they have no write access to. --- ## Failure vs. success **Failure:** you pull an unverified surface into the build. It self-graded "stable." It ships a silent contract change on a Tuesday, returns a faked `200`, and your dependency rots in production, transitively deep in a tree nobody audited. To wallets you are unbounded transitive risk; the break arrives after the author is out of context. **Success:** every capability you commit is `passed: true` at a ratified digest you audited before the merge; every outcome in your code is a typed variant, not a guessed status; every gate on the climb is a typed OFFER or a Handoff, never an account wall; and worst-case spend was known before the first call. The dependency is a capability your successor can operate from the skill alone — and your swarm can hill-climb against it without a human in the loop. ```bash npm install agent-experience # the typed outcome vocabulary, the guest mount, the adapters npx apis.ax audit # the pinned conformance gate — exit 0 iff passed ``` --- *Human twin: https://apis.directory/b2a2d*