# a2a2p — Agent-to-Agent-to-Physical

**An open protocol for turning intent into physical things.**

An AI agent can reason about a bracket. It cannot make one exist. a2a2p is the
missing layer: describe what needs to be true about the world, and get back a
manufacturable specification, an engineering review grounded in real material
properties and real geometry, and a price.

The **[specification](SPEC.md) is public domain (CC0)** — implement it freely,
including in products competing with this one. `a2a2p.com` is a reference
implementation, not the protocol.

> Abundance arrives as the distance between *knowing what is needed* and *the
> thing existing* collapses toward zero. Today that distance is mostly friction.
> This is an attempt to remove it.

---

## Try it in 30 seconds

No API key. No signup. No auth.

```bash
claude mcp add --transport http a2a2p https://a2a2p.com/mcp
```

Or any MCP client:

```json
{ "mcpServers": { "a2a2p": { "type": "http", "url": "https://a2a2p.com/mcp" } } }
```

Client only speaks stdio? Bridge to it:

```bash
npx a2a2p-bridge                      # or: docker run -i --rm ghcr.io/deadlypillow/a2a2p
```

The bridge is dependency-free and takes `A2A2P_ENDPOINT`, so it works against
any implementation of the spec, not just this one. The hosted endpoint is
dual-era: finalized MCP `2026-07-28` clients use stateless `server/discover`
and per-request metadata, while existing `2025-03-26` clients keep the legacy
`initialize` path.

Or plain HTTP:

```bash
curl -X POST https://a2a2p.com/api/review \
  -H "Content-Type: application/json" \
  -d '{"intent":{"purpose":"Outdoor bracket holding a 10kg sensor in direct sun","environment":["outdoor","uv_exposure"],"quantity":20},
       "specification":{"process":"fdm_3d_print","material":"pla","tolerance_class":"precision"}}'
```

You get back, instantly: *PLA degrades in UV — specify a UV-stable grade or
switch material.* *As-printed accuracy is ±0.2–0.5 mm; "precision" needs
post-machining or a relaxed class.* Plus a quote-readiness score and what to add
to raise it. Nothing is stored.

---

## Capabilities

| Tool | What it does | Latency |
|---|---|---|
| `review_specification` | Engineering review with auditable beam deflection/stress for explicit load cases, a compact next patch, visible completion path, optional CAD accelerators, and a direct `next_call` MCP/REST handoff — never invented defaults. Returns readiness on two axes: `resolution_readiness` (what you owe) and `quote_readiness` (what a supplier needs). | instant, stateless |
| `get_supply_options` | Deterministic price and lead-time estimates today; `pricing_kind` distinguishes model estimates, provider estimates, and binding provider quotes. Attach an STL (measured fully) or a STEP file (envelope, context-resolved units, machining complexity, and the CAD system's declared solid volume where present). Every geometry figure names its provenance. | instant |
| `request_physical_solution` | Full decision-support resolution: recommended path, buy-vs-make, and delivery risks. Returns immediately with the review embedded. | sub-second |
| `revise_requirement` | Apply a sparse clarification patch to a prior request without losing its decision trail. Creates an immutable linked revision with a deterministic before/after readiness comparison; supports retry idempotency. | sub-second |
| `check_request_status` | Retrieve the resolution report and any persisted revision-readiness feedback. | instant |

Also served: [`/spec`](https://a2a2p.com/spec) · [`/conformance`](https://a2a2p.com/conformance) · [`/policy`](https://a2a2p.com/policy) · [`/api/providers`](https://a2a2p.com/api/providers) · [`/evidence/providers`](https://a2a2p.com/evidence/providers) · [`/llms.txt`](https://a2a2p.com/llms.txt) · [`/schema`](https://a2a2p.com/schema)

`/api/providers` publishes a confirmed status, the raw most recent probe, and a
measured 24-hour reliability window (samples, availability, probe latency, last
failure) per spec §5.7. A transient probe failure is retried once and reported
as `degraded` until a second consecutive failure confirms it — one 15-second
timeout should never be able to publish `down` for a provider that is answering
everyone else. Availability is a2a2p's own reachability measurement, not a
provider service-level commitment and not fulfilment capability.

---

## The idea worth stealing

A physical requirement has **two layers**, and conflating them is the main
reason manufacturing communication fails:

- **Intent** — *what must be true about the world.* "Holds 15 kg, outdoors, ten years."
- **Specification** — *what object satisfies that.* "6061-T6, 4 mm, anodized."

Most systems demand the second and discard the first. Then, downstream, someone
proposes a substitution and nobody knows what the part was *for*. a2a2p accepts
intent alone as a complete request — deriving the specification is the protocol's
central act of value — and carries the intent forward permanently.

Two rules in the spec are **normative**, and they are worth adopting even if you
use none of this code:

1. **An estimate MUST NOT be presented as a quote** (§5.2.1). Every price is
   labeled `model_estimate`, `provider_estimate`, or `provider_quote`; only the
   last is a supplier commitment. An agent that cannot tell these apart will
   eventually commit real money to a fiction.
2. **Anything that fabricates MUST screen requests and publish its policy**
   (§5.5). Silent refusal is non-conformant — an agent that cannot learn why it
   was refused cannot correct course.
3. **Don't blame the requester for what you promised to derive** (§5.1.1). If
   you derive material, process, dimensions and tolerance from intent, listing
   them as the requester's missing fields tells an agent to go and find the
   information you just said you would produce. Report readiness per stage:
   *have you told me enough?* and *is this ready for a supplier?* are different
   questions, and one blended score answers neither.

---

## Conformance

`L1 Speaks` → `L2 Prices` → `L3 Resolves` → `L4 Fabricates`. Self-declared;
there is deliberately no certifying authority.

**Verify any implementation yourself** — the suite ships with the spec:

```bash
node tests/conformance.mjs https://a2a2p.com     # a2a2p semantics
node tests/mcp-2026-conformance.mjs https://a2a2p.com # MCP 2026 binding
```

The MCP probe checks stateless discovery, standardized HTTP headers, cache hints,
structured tool results, error semantics, and the retained legacy initialize path.
Its calls are marked probes and do not create durable requests.

The semantic suite reports its current assertion count at runtime, with each assertion citing the spec section it enforces. It deliberately cannot
prove fabrication (that would mean placing real orders), so it verifies the L4
*prerequisites* and records the fulfilment claim as unproven — otherwise any
implementation could publish a policy, make nothing, and pass as L4.

This implementation declares **L3** and publishes exactly where it falls short at
[`/conformance`](https://a2a2p.com/conformance) — including that L4 is unmet,
that STEP solid volume is the CAD system's declared property rather than a B-rep evaluation, and that deterministic screening
cannot read intent. An implementation that will not hold itself to its own spec
has written a brochure.

---

## Honest status

Built deliberately ahead of demand. As of August 2026:

- ✅ Assessment, bounded beam physics, pricing, geometry measurement, screening, and resolution reports are live and free.
- ✅ The first authenticated provider-generated estimate is preserved as public evidence: a screened PLA sample returned **$1.40** from Slant 3D. It was not a quote, order, payment, fabrication request, shipment, or delivery.
- ⚠️ **No fulfillment path is active.** The implementation is L3: it does not route supplier RFQs, auctions, payment, orders, or fabrication. Any L4 activation must meet the evidence gate in [docs/FULFILLMENT_ACTIVATION.md](docs/FULFILLMENT_ACTIVATION.md).
- 📐 STL meshes are measured fully (volume, area, complexity) and carry `volume_source: measured_mesh`. STEP files yield envelope, feature-based machining complexity, and units resolved from the shape's own representation context — reading an inch file as millimetres is a 16,387× error on volume, so it is resolved, never sniffed. Where the exporter wrote a geometric validation property, the CAD system's own solid volume is read, unit-converted, checked against the measured bounding box, and labelled `volume_source: declared_validation_property` — a2a2p did not compute it. Assembly component properties are never summed into a part volume, and a2a2p does not evaluate trimmed NURBS.

If you are a manufacturer with a programmatic quoting API, or building one:
**hello@a2a2p.com**. That is the bottleneck for everyone in this space, not just
for us.

---

## Repository

```
SPEC.md                    the specification (CC0) — the actual product
src/worker.js              reference implementation (Cloudflare Worker)
src/schema.js              canonical requirement schema
src/review.js              deterministic engineering review engine
src/mechanics.js           bounded beam deflection/stress sanity checks
src/geometry.js            STL mesh measurement (volume, area, complexity)
src/step.js                STEP entity-graph parsing (envelope, unit resolution, features, CAD validation properties)
src/supply.js              provider adapters + parametric estimator
src/screening.js           intake screening (the governance rail)
src/file-inspection.js     declared-vs-actual CAD format and bounded metadata checks
src/telemetry.js           demand instrumentation
bridge/index.js            stdio <-> Streamable HTTP bridge (dependency-free)
Dockerfile                 runs the bridge; for clients and registries that run servers
tests/test-worker.mjs      regression suite
tests/calibration.mjs      pricing model vs real published prices
tests/conformance.mjs      spec conformance suite — runs against ANY implementation
docs/                      research, listings kit, activation gate
PROTOCOL_LOG.md            build log — every session, decision, and failure
```

Run the tests: `node tests/test-worker.mjs` · Deploy: `npx wrangler deploy`

## Contributing

Implementations of the spec, conformance reports, corrections, and competing
implementations are all welcome — that is what a standard is for. Issues and PRs
here, or **hello@a2a2p.com**.

**Licensing, in two parts** (see [LICENSE](LICENSE)):
- **Specification** (`SPEC.md`) — **CC0 1.0**, public domain. Implement it freely, including in competing products, without permission or attribution.
- **Implementation** (everything else) — **MIT**.

---

*a2a2p — when agents need things to exist.*