Beam Protocol

Verified B2B handoffs for AI agents

Beam is an open protocol and tooling stack for one hard problem: letting one company's agent hand work to another company's agent without shared API keys, brittle one-off integrations, or blind trust.

If you are evaluating Beam, start from the hosted demo before reading the rest of the repo. The right first question is not "what could this protocol become?" but "does this handoff feel trustworthy and operable now?"

The opinionated Beam 0.6.0 wedge is a verified partner handoff:

1. procurement@acme.beam.directory asks partner-desk@northwind.beam.directory for a quote.
2. partner-desk@northwind.beam.directory checks inventory with warehouse@northwind.beam.directory.
3. Acme gets a signed response, a traceable nonce, and an operator-visible audit trail.

• Docs: docs.beam.directory
• Fastest local path: Hosted Quickstart
• Workflow guide: Verified Partner Handoff
• Compatibility policy: Beam 0.6 Compatibility
• API reference: TypeScript, CLI, Directory, Python

Fastest Local Path

cp ops/quickstart/.env.example ops/quickstart/.env
docker compose -f ops/quickstart/compose.yaml --env-file ops/quickstart/.env up -d --build
npm run demo:seed
npm run demo:run

That boots the local directory, dashboard, message bus, and seeded Acme/Northwind demo agents so you can run the exact hosted partner handoff used in dogfood and operator docs.

What you should see on the happy path:

• a signed quote back from partner-desk@northwind.beam.directory
• an async finance preflight accepted through the message bus
• a traceable nonce through directory observability
• zero alerts and zero dead letters on the baseline hosted-demo pass

SDK Example

npm install beam-protocol-sdk

import { BeamClient, BeamIdentity } from 'beam-protocol-sdk'

const identity = BeamIdentity.generate({ agentName: 'procurement', orgName: 'acme' })
const client = new BeamClient({
  identity: identity.export(),
  directoryUrl: 'https://api.beam.directory',
})

await client.register('Acme Procurement Desk', ['conversation.message', 'quote.request'])

const reply = await client.talk(
  'partner-desk@northwind.beam.directory',
  'Need 240 inverters for Mannheim by Friday. Include delivery window and stock confidence.',
)

console.log(reply.message)

For the full three-agent flow, see examples/partner-handoff.

Why Beam

• Verified addresses so both sides know which company and which agent received the request
• Signed intents and results with Ed25519 and nonce-based replay protection
• Operator visibility through traces, audit logs, alerts, and dead-letter inspection
• Retry and recovery with a message bus for durable handoffs and restart safety
• Self-hostable building blocks across Directory, Dashboard, CLI, and SDKs

Architecture

+------------------------+     signed handoff      +------------------------+
| Acme procurement agent | ----------------------> | Beam Directory         |
| TS SDK / Python / CLI  | <---------------------- | identity, ACL, trace,  |
| procurement@acme       |        result / DID     | operator views         |
+------------+-----------+                         +-----------+------------+
             |                                                  |
             | optional durable relay                            | direct / federated delivery
             v                                                  v
  +------------------------+                          +------------------------+
  | Message Bus            | <----------------------> | Northwind agents       |
  | retry, dedupe, DLQ     |       queued handoff     | partner desk, warehouse|
  +------------------------+                          +------------------------+

Compatibility

Beam 0.6.0 treats beam/1 as the compatibility contract across the protocol, directory, CLI, and SDKs.

• Additive fields are allowed within beam/1.
• Receivers must ignore unknown top-level and payload fields.
• payload is the canonical request body; params remains a legacy alias accepted by current SDKs.
• Breaking field removals, required-field changes, or signature changes require a new protocol version.

See the full policy in docs/guide/compatibility.md.

Packages

• beam-protocol-sdk - TypeScript SDK
• beam-directory - Python SDK
• beam-protocol-cli - command-line client
• @beam-protocol/directory - directory server
• @beam-protocol/message-bus - durable relay and retry service

Examples

• examples/partner-handoff - the recommended 0.6.0 B2B workflow
• examples/hello-world - register two agents and send a first message
• examples/multi-agent - a generic chained workflow
• examples/webhook-bridge - forward Beam intents to a webhook

Release Readiness

The 0.6.0 dogfood workflow and findings live in reports/0.6.0-release-readiness.md. The current 1.7.0 release-control evidence lives in reports/1.7.0-rc1-checklist.md, reports/1.7.0-production-readiness-refresh.md, reports/1.7.0-production-readiness-gate.md, reports/1.7.0-dashboard-production-go-runbook.md, reports/1.7.0-external-dogfood-status.md, reports/1.7.0-ui-smoke.md, and reports/1.7.0-release-notes-draft.md.

Production readiness now requires the API, public site, docs, npm packages, and dashboard control plane to agree. The default production dashboard gates check https://dashboard.beam.directory and its Vercel-recommended DNS record; use --dashboard-base http://localhost:43173 only for local quickstart proof.

For post-release verification, run:

npm run release:smoke -- --version <release-version> --git-sha <tagged-sha> --output reports/<release-version>-release-smoke.md
npm run production:readiness
npm run production:dashboard-go
npm run production:dashboard-deployment
npm run production:dashboard-domain
npm run production:dashboard-shell
npm run production:external-dogfood
npm run production:parity
npm run production:workflow-guards

Repository Layout

packages/
  sdk-typescript/  TypeScript SDK
  sdk-python/      Python SDK
  cli/             Beam CLI
  directory/       Directory server
  message-bus/     Persistent relay
examples/          End-to-end runnable demos
docs/              docs.beam.directory source
reports/           Dogfood and release-readiness reports
spec/              protocol RFCs and compatibility fixtures

Development

npm install
npm run build
npm test
python3 -m pip install -e packages/sdk-python
npm run test:e2e
npm run dogfood:partner-handoff

See CONTRIBUTING.md for contribution workflow, reporting guidelines, and local development expectations.

License

Apache-2.0