trat-multi-agent — Transaction Tokens for multi-agent AI workflows

Reference implementation of IETF Transaction Tokens (TraT, draft-ietf-oauth-transaction-tokens) applied to multi-agent AI systems. TxTS + Gateway + agent pipeline, end-to-end.

Status: Research / demo. Auto-generates RSA keys on first run — not for production.

---

Why this exists

The dominant trust pattern in multi-agent systems today is "give every agent a long-lived bearer API key and hope." That breaks the moment one agent delegates to another, because the downstream agent now holds credentials with the full scope of the upstream one — no transaction context, no audience binding, no natural revocation story.

IETF Transaction Tokens (TraTs) were designed for exactly this shape of problem in microservices: short-lived, transaction-scoped, audience-bound tokens that carry the immutable context of a specific request as it flows through a call chain. This repo applies them to AI agents. A user's request becomes a transaction. Each agent in the pipeline (planner → booking → payment → notification) gets a freshly-minted token scoped to that transaction, audience-bound to the next hop, with a 5-minute lifetime. Where AgentGuard answers "who is this agent?", this repo answers "what transaction is this agent acting inside, and is it still allowed to?"

---

Architecture

                          ┌──────────────────────┐
                          │   Frontend (:3400)   │
                          │   Dashboard UI       │
                          └──────────┬───────────┘
                                     │
                                     ▼
                          ┌──────────────────────┐
                          │  API Gateway (:3200) │
                          │  Login → mint JWT    │
                          │  Exchange for TraT   │
                          └──────────┬───────────┘
                                     │ (TraT)
                                     ▼
         ┌──────────────────────────────────────────────────────┐
         │  Planner (:3301)                                     │
         │   │                                                  │
         │   ▼ replace TraT (audience=booking)                  │
         │  Booking (:3302)                                     │
         │   │                                                  │
         │   ▼ replace TraT (audience=payment)                  │
         │  Payment (:3303)                                     │
         │   │                                                  │
         │   ▼ replace TraT (audience=notification)             │
         │  Notification (:3304)                                │
         └──────────────────────────────────────────────────────┘
                                     │
                                     ▼
                          ┌──────────────────────┐
                          │   TxTS (:3100)       │
                          │   Issue / replace    │
                          │   JWKS, audit log    │
                          └──────────────────────┘

Every hop calls TxTS /replace to get a new TraT scoped to the next audience; TxTS logs every issue/replace/deny to an audit stream.

---

Quick Start

bash start.sh

On first run, keys.json is auto-generated (RSA-2048 signing keypair for TxTS) — it is gitignored, treat it as local secret material. The script brings up:

• Dashboard — http://localhost:3400
• API Gateway — http://localhost:3200
• TxTS — http://localhost:3100 (JWKS at /.well-known/jwks.json, audit at /audit)
• Planner / Booking / Payment / Notification agents on :3301–:3304

Trigger an end-to-end transaction:

make demo

Or inspect the audit log:

make audit

---

Components

Path	Purpose
txts/	Transaction Token Service (TypeScript, :3100) — RFC 8693 token exchange, RS256 signing, JWKS endpoint, issue / replace / deny flows, audit log.
gateway/	API Gateway (TypeScript, :3200) — authenticates users, mints a self-signed JWT, exchanges it for a TraT via TxTS, forwards to the planner.
agents/	Agent pipeline (TypeScript, :3301–:3304) — planner, booking, payment, notification. Each agent calls TxTS /replace before invoking the next hop.
frontend/	Dashboard (TypeScript, :3400) — UI for inspecting transactions and token flow.
txts_service.py	Python port of the Transaction Token Service (FastAPI) — mirror of txts/ for Python-native deployments.
gateway_service.py	Python port of the API Gateway.
agents_service.py	Python port of all four agents (each on its own thread).
dashboard_service.py	Python port of the dashboard (FastAPI static + proxy).
trat_client.py	Shared Python helper — exchange_for_trat, replace_trat, payload decode.
start.sh	Launches the TypeScript stack (TxTS → Agents → Gateway → Dashboard).
start_all.py	Launches the Python stack as independent subprocesses.
scripts/generate_arch_diagram.py	Regenerates the architecture diagram image.
Makefile	install, start, demo, audit, clean.

---

Related work

Part of a four-part effort on the trust layer for AI agents:

• rockerritesh/agentguard — Zero-trust identity + policy enforcement for AI agents.
• rockerritesh/spiffe-core — SPIFFE identity primitives — the substrate underneath AgentGuard.
• rockerritesh/sumit-server — Federated, audited memory MCP server.
• rockerritesh/trat-multi-agent (this repo) — Transaction Tokens for multi-agent pipelines.

---

License

MIT