@alignment_agents/broker-protocol

TypeScript SDK for the Alignment Broker Protocol v0.1 — agent-to-agent commerce infrastructure.

Overview

The Alignment Broker is the neutral settlement layer between Consumer Agents (shopping bots, voice assistants, phone-OS agents) and Brand Agents (product catalog endpoints). This SDK lets you build either side.

Consumer Agent  ──query──▶  Alignment Broker  ──fan-out──▶  Brand Agents
                ◀─quotes──                    ◀─quote────
                ──commit──▶                   ──commit──▶

Ranking is deterministic and transparent — no paid placement:

| Factor | Weight | |--------|--------| | Price match | 30% | | Trust score | 25% | | Semantic match | 20% | | Estimated delivery | 15% | | Inventory confidence | 10% |

Installation

npm install @alignment_agents/broker-protocol

Requires Node.js ≥ 18. Ships as ESM + CommonJS dual format with full TypeScript declarations.

Quick Start — Consumer Agent

import { AlignmentBroker } from "@alignment_agents/broker-protocol";

const broker = new AlignmentBroker({ apiKey: "ak_…" });

// 1. Query — find matching products across all Brand Agents
const result = await broker.query({
  consumer_agent_id: "did:alignment:acme:whatsapp-bot-1",
  intent: {
    raw: "waterproof running shoes under $150",
    structured: {
      category: "footwear",
      constraints: { waterproof: true, price_max: 150 },
    },
  },
  user_context: {
    region:           "US",
    currency:         "USD",
    ship_to_country:  "US",
  },
});

// 2. Inspect ranked quotes (transparent 5-factor score)
const top = result.ranked_quotes[0];
console.log(top.product.price, top.broker_score, top.ranking_factors);

// 3. Commit — confirm the purchase
const tx = await broker.commit({
  quote_id:          top.quote_id,
  consumer_agent_id: "did:alignment:acme:whatsapp-bot-1",
  shipping: {
    name:           "Jane Doe",
    address_line_1: "123 Main St",
    city:           "San Francisco",
    region:         "CA",
    postal_code:    "94105",
    country:        "US",
  },
  payment_token: "tok_visa_4242",   // tokenized payment, never raw PAN
  user_consent: {
    ts:                new Date().toISOString(),
    agent_attestation: "user-confirmed-on-whatsapp",
  },
});

console.log("Transaction ID:", tx.transaction_id);
console.log("Settlement:", tx.settlement);

Quick Start — Brand Agent Server

import { generateWellKnown, assertBrokerKey } from "@alignment_agents/broker-protocol";
import type { BrokerQuoteRequest, BrokerQuoteResponse } from "@alignment_agents/broker-protocol";

// 1. Serve your .well-known/agent.json discovery document
const wellKnown = generateWellKnown({
  agentId:   "did:alignment:my-brand:prod-1",
  operator:  "My Brand Inc.",
  baseUrl:   "https://agents.my-brand.com",
  currencies: ["USD", "EUR"],
  shipTo:    ["US", "CA", "GB"],
});

// 2. Handle /v1/quote calls from the Broker
async function handleQuote(req: BrokerQuoteRequest, brokerKey: string): Promise<BrokerQuoteResponse> {
  assertBrokerKey(brokerKey, process.env.BROKER_KEY!); // timing-safe validation

  return {
    brand_id:    "did:alignment:my-brand:prod-1",
    quote_id:    crypto.randomUUID(),
    price_usd:   129.99,
    currency:    "USD",
    product_id:  "shoe-wr-001",
    title:       "TrailRunner Pro — Waterproof",
    in_stock:    true,
    eta_days:    3,
    expires_at:  new Date(Date.now() + 5 * 60_000).toISOString(),
  };
}

API Reference

new AlignmentBroker(config)

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | — | Your Consumer Agent API key (ak_…) | | baseUrl | string | https://api.alignmenttech.ai | Broker API base URL | | timeoutMs | number | 15000 | Request timeout | | fetch | typeof fetch | global fetch | Custom fetch implementation |

Methods

| Method | Description | |--------|-------------| | broker.query(req) | Fan-out intent query → ranked quotes (p95 200–600 ms) | | broker.commit(req) | Confirm a quote → transaction + settlement | | broker.getQuery(queryId) | Replay / inspect a past query | | broker.registerConsumerAgent(req) | Register a new Consumer Agent | | broker.registerBrandAgent(req) | Register a new Brand Agent | | broker.setApiKey(key) | Update API key at runtime |

Error Classes

import {
  QuoteExpiredError,    // 409 — quote TTL elapsed (re-query)
  OutOfStockError,      // 410 — inventory gone
  AlreadyCommittedError,// 409 — quote already used
  RateLimitedError,     // 429 — slow down
} from "@alignment_agents/broker-protocol";

Get Your API Key

1. Sign up at alignmenttech.ai
2. Navigate to Agentic Commerce → Integration
3. Copy your Consumer Agent API key

License

MIT © Alignment AI