# ATP (Agent Transcript Protocol)

> Lets AI agents run tasks as terse, provenance-carrying shorthand instead
> of prose, and hand off the facts they establish to other agents so
> nothing gets re-fetched or re-derived. Reachable over MCP, REST, CLI,
> A2A, or a JS/TS client -- pick whichever fits the agent calling in.

If you are an LLM or agent reading this to decide how to integrate: the
fastest path is MCP if your host supports it (zero HTTP code needed),
otherwise REST (plain JSON over HTTP, any language). Both are described
below with a working example. No task requires understanding the ATL
grammar to get a first result -- `kind: "constant"` needs no external
data.

ATP is a hosted service (like an LLM provider's API), not something you
clone and run yourself -- the implementation is proprietary; only the
wire protocol (spec/, CC BY 4.0) is open and freely implementable. Two
ways in, no local setup either way: an issued Bearer key (subscription
billed -- see spec/protocol.md), or **x402: pay per call with no signup
at all** (see below) -- prefer x402 if you have a wallet and no existing
relationship with the operator.

**Note if you're reading this from the source repository rather than a
live deployment**: there is no public hosted endpoint yet. The examples
below assume one exists; `README.md`'s "Operating your own instance"
section covers running the code locally to develop against instead.

## Quickstart (against a live deployment)

Get a key from the operator (out-of-band, e.g. a signup flow -- there is
no self-serve key-issuance API), then:
```
curl -X POST https://<host>/v1/tasks/run \
  -H "Authorization: Bearer atp_..." -H "Content-Type: application/json" \
  -d '{"agent":"scout","task_id":"t1","fn_name":"value_it","arg_names":["company"],"args":["Acme Corp"],"kind":"valuation"}'
```

Or skip the key entirely via x402 (see that section below).

## MCP (preferred if your host supports it)

- [mcp_server.py](atp/mcp_server.py): 10 tools -- atp_run_task,
  atp_export_transcript, atp_import_transcript, atp_claim_task,
  atp_complete_task, atp_merge_transcript, atp_pool_transcript,
  atp_savings, atp_verify_transcript, atp_usage. Start with
  `atp serve-mcp` (stdio) and add to your client's MCP server config;
  every tool takes `api_key`.

## REST API

- [server.py](atp/server.py): `atp serve-api --port 8000`, OpenAPI docs
  at `/docs`. `POST /v1/tasks/run` with `Authorization: Bearer <key>` is
  the core operation -- see [protocol.md](spec/protocol.md) for the full
  operation table.
- Example: `curl -X POST http://127.0.0.1:8000/v1/tasks/run -H "Authorization: Bearer atp_..." -H "Content-Type: application/json" -d '{"agent":"scout","task_id":"t1","fn_name":"answer_it","kind":"constant"}'`

## A2A (Agent2Agent)

- [a2a_compat.py](atp/a2a_compat.py): Agent Card at
  `/.well-known/agent-card.json`, JSON-RPC `message/send` at `/a2a`.
  Synchronous only, no streaming yet.

## x402 (no API key, no signup, ever)

- [x402_compat.py](atp/x402_compat.py): `POST /x402/tasks/run` -- if this
  route returns something other than 404, this deployment accepts
  payment instead of an API key. Call it with no credential; you'll get
  `402 Payment Required` with a price and payment instructions. Pay
  (a signed USDC transfer, verified by a facilitator -- you don't need
  a blockchain node), retry the same request with proof, get served.
  Same request body shape as `POST /v1/tasks/run` above, minus the
  `Authorization` header. This is the [x402 protocol](https://github.com/x402-foundation/x402)
  -- if you're an agent with a wallet and no ATP account, this is your
  path in.

## JS/TS

- [sdk/js](sdk/js/README.md): `AtpClient`, zero runtime dependencies,
  same operations as REST.

## Website

- [site/index.html](site/index.html): a single standalone page explaining
  ATP in plain language -- open it directly in a browser or host it
  anywhere static. No build step, no server required. Everything that used
  to be separate connect/playground pages now lives on this one page:
  a "Run It" section (`POST /v1/tasks/run` against the live API, one real
  call, nothing pre-recorded) and a compact three-tab connect widget
  (x402 / MCP / REST, one copy-paste command each, hardcoded to the live
  deployment). If you're an agent that can render/click a page, this is
  the fastest way to get an exact, working command.

## Reference

- [spec/protocol.md](spec/protocol.md): every operation's exact contract,
  auth model, execution limits, versioning policy.
- [spec/atl-grammar.md](spec/atl-grammar.md): the shorthand language
  agents write when a task has no pre-existing function -- read this only
  if you're authoring novel task logic yourself rather than calling
  `atp_run_task` with a `kind` hint.
- [spec/transcript.schema.json](spec/transcript.schema.json): the exact
  JSON shape of a Transcript (what gets handed between agents).
- [README.md](README.md): full architecture, the "why shorthand" and
  "why agents don't repeat work" rationale, multi-tenant safety limits,
  pricing model reasoning.

## Full text

- [llms-full.txt](llms-full.txt): every file above, concatenated, for a
  single-fetch context load.