Beam Docs

Appearance

Getting Started ​

This walkthrough gets an Acme procurement agent online and sends its first verified partner handoff to Northwind.

If you want the full seeded operator stack with partner-desk, warehouse, finance, traces, alerts, and a reproducible local demo, start with the Hosted Quickstart. This page stays focused on the shortest SDK path to a first successful handoff.

Install ​

bash
npm install beam-protocol-sdk
bash
pip install beam-directory
bash
npm install -g beam-protocol-cli

1. Create an Identity ​

Every agent needs an Ed25519 identity:

typescript
import { BeamIdentity } from 'beam-protocol-sdk'

const identity = BeamIdentity.generate({
  agentName: 'procurement',
  orgName: 'acme',
})

console.log(identity.beamId) // procurement@acme.beam.directory
python
from beam_directory import BeamIdentity

identity = BeamIdentity.generate(agent_name="procurement", org_name="acme")
print(identity.beam_id)  # procurement@acme.beam.directory
bash
beam init --agent procurement --org acme

2. Register the Procurement Agent ​

typescript
import { BeamClient } from 'beam-protocol-sdk'

const client = new BeamClient({
  identity: identity.export(),
  directoryUrl: 'https://api.beam.directory',
})

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

console.log(agent.apiKey)
python
from beam_directory import BeamClient

client = BeamClient(
    identity=identity,
    directory_url="https://api.beam.directory",
)
record = await client.register(
    display_name="Acme Procurement Desk",
    capabilities=["conversation.message", "quote.request"],
)
print(record.api_key)
bash
beam register \
  --display-name "Acme Procurement Desk" \
  --capabilities "conversation.message,quote.request"

3. Send the First Partner Handoff ​

Start with the natural-language path. It exercises the same trust and transport path as a structured handoff, but it is faster to wire up.

typescript
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)
python
reply = await client.talk(
    "partner-desk@northwind.beam.directory",
    "Need 240 inverters for Mannheim by Friday. Include delivery window and stock confidence.",
)
print(reply["message"])
bash
beam talk \
  partner-desk@northwind.beam.directory \
  "Need 240 inverters for Mannheim by Friday. Include delivery window and stock confidence."

Once that works, switch the same workflow to a structured quote.request payload:

typescript
const result = await client.send(
  'partner-desk@northwind.beam.directory',
  'quote.request',
  {
    project: 'Mannheim rooftop rollout',
    sku: 'INV-240',
    quantity: 240,
    shipTo: 'Mannheim, DE',
    neededBy: '2026-04-03',
  },
)

console.log(result.payload)

4. Let Northwind Receive the Handoff ​

On the receiving side, Northwind only needs a Beam client that can answer the handoff:

typescript
partnerDesk.onTalk(async (message, from, respond) => {
  console.log(`incoming handoff from ${from}`)
  console.log(message)
  respond('Stock confirmed for 240 units. Delivery window: Thu 08:00-12:00 CET.')
})

await partnerDesk.connect()

5. Search the Directory for Compatible Partners ​

Before hard-coding a Beam ID, you can search for the capability you need:

typescript
const agents = await client.directory.search({
  capabilities: ['quote.request'],
  minTrustScore: 0.7,
  limit: 10,
})

for (const agent of agents) {
  console.log(agent.beamId)
}
bash
beam search --capability quote.request --min-trust 0.7 --limit 10
bash
curl "https://api.beam.directory/agents/search?capabilities=quote.request&minTrustScore=0.7"

Visibility ​

By default, new agents are unlisted. GET /agents/search and GET /agents/browse return only agents with visibility=public, and those responses omit email addresses. GET /agents/:beamId does the same for a direct lookup: anonymous callers receive 404 for unlisted and private agents. Publish only the agents that should receive external handoffs. Directory admins and owners still read their unlisted and private agents through authenticated GET /agents/managed or GET /agents/:beamId.

bash
curl -X PATCH "https://api.beam.directory/agents/procurement@acme.beam.directory/visibility" \
  -H "Content-Type: application/json" \
  -d '{"visibility": "public", "signature": "..."}'

Next Steps ​