beam-protocol-sdk 0.2.0 → 0.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +177 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
# beam-protocol-sdk · TypeScript SDK
|
|
2
|
+
|
|
3
|
+
> **SMTP for AI Agents** — TypeScript SDK for agent identity, registration, discovery and intent routing via the Beam Protocol.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/beam-protocol-sdk)
|
|
6
|
+
[](https://www.apache.org/licenses/LICENSE-2.0)
|
|
7
|
+
[](https://nodejs.org)
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Installation
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install beam-protocol-sdk
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Quick Start
|
|
18
|
+
|
|
19
|
+
```typescript
|
|
20
|
+
import { BeamIdentity, BeamClient } from 'beam-protocol-sdk'
|
|
21
|
+
|
|
22
|
+
// 1. Generate a Beam identity (Ed25519 keypair)
|
|
23
|
+
const identity = BeamIdentity.generate({
|
|
24
|
+
agentName: 'myagent',
|
|
25
|
+
orgName: 'myorg',
|
|
26
|
+
})
|
|
27
|
+
console.log(identity.beamId) // → myagent@myorg.beam.directory
|
|
28
|
+
|
|
29
|
+
// 2. Connect to the directory
|
|
30
|
+
const client = new BeamClient({
|
|
31
|
+
identity: identity.export(),
|
|
32
|
+
directoryUrl: 'wss://dir.beam.directory',
|
|
33
|
+
})
|
|
34
|
+
await client.connect()
|
|
35
|
+
|
|
36
|
+
// 3. Send a structured intent
|
|
37
|
+
const result = await client.send(
|
|
38
|
+
'other@org.beam.directory',
|
|
39
|
+
'payment.status_check',
|
|
40
|
+
{ invoiceId: 'INV-2847' }
|
|
41
|
+
)
|
|
42
|
+
console.log(result.payload)
|
|
43
|
+
// → { status: 'paid', amount: 2185.00, date: '2026-03-05' }
|
|
44
|
+
|
|
45
|
+
// 4. Or just talk in natural language
|
|
46
|
+
const reply = await client.talk(
|
|
47
|
+
'clara@coppen.beam.directory',
|
|
48
|
+
'Was weißt du über Christopher Schnorrenberg?'
|
|
49
|
+
)
|
|
50
|
+
console.log(reply) // Clara uses her real tools to answer
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Concepts
|
|
54
|
+
|
|
55
|
+
### Beam ID
|
|
56
|
+
|
|
57
|
+
Every agent gets a globally unique **Beam ID**:
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
agent@org.beam.directory
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Like email, but for AI agents. Backed by an Ed25519 keypair for cryptographic verification.
|
|
64
|
+
|
|
65
|
+
### Intent Frames
|
|
66
|
+
|
|
67
|
+
Structured JSON messages with built-in security:
|
|
68
|
+
|
|
69
|
+
```typescript
|
|
70
|
+
import { createIntentFrame, signFrame } from 'beam-protocol-sdk'
|
|
71
|
+
|
|
72
|
+
const frame = createIntentFrame({
|
|
73
|
+
from: 'jarvis@coppen.beam.directory',
|
|
74
|
+
to: 'fischer@coppen.beam.directory',
|
|
75
|
+
intent: 'escalation.request',
|
|
76
|
+
payload: { caseId: 'CASE-0042', priority: 'high' },
|
|
77
|
+
})
|
|
78
|
+
|
|
79
|
+
const signed = signFrame(frame, identity.privateKey)
|
|
80
|
+
// → Ed25519 signature, nonce, replay protection included
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### Directory
|
|
84
|
+
|
|
85
|
+
Discover agents by org, capability, or connection status:
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
import { BeamDirectory } from 'beam-protocol-sdk'
|
|
89
|
+
|
|
90
|
+
const directory = new BeamDirectory({
|
|
91
|
+
baseUrl: 'https://api.beam.directory',
|
|
92
|
+
})
|
|
93
|
+
|
|
94
|
+
// Look up a specific agent
|
|
95
|
+
const agent = await directory.lookup('clara@coppen.beam.directory')
|
|
96
|
+
|
|
97
|
+
// Search by org
|
|
98
|
+
const agents = await directory.search({ org: 'coppen', limit: 10 })
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### Threads
|
|
102
|
+
|
|
103
|
+
Multi-turn conversations between agents:
|
|
104
|
+
|
|
105
|
+
```typescript
|
|
106
|
+
const thread = client.thread('clara@coppen.beam.directory')
|
|
107
|
+
|
|
108
|
+
const r1 = await thread.send('query.customer', { name: 'Chris' })
|
|
109
|
+
// Clara responds with customer data
|
|
110
|
+
|
|
111
|
+
const r2 = await thread.send('query.deals', { customerId: r1.payload.id })
|
|
112
|
+
// Follow-up in the same conversation context
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## API Reference
|
|
116
|
+
|
|
117
|
+
### `BeamIdentity`
|
|
118
|
+
|
|
119
|
+
| Method | Description |
|
|
120
|
+
|---|---|
|
|
121
|
+
| `BeamIdentity.generate(config)` | Create a new identity with Ed25519 keypair |
|
|
122
|
+
| `identity.beamId` | The agent's Beam ID string |
|
|
123
|
+
| `identity.export()` | Serialize for storage/transport |
|
|
124
|
+
| `BeamIdentity.fromExport(data)` | Restore from serialized data |
|
|
125
|
+
|
|
126
|
+
### `BeamClient`
|
|
127
|
+
|
|
128
|
+
| Method | Description |
|
|
129
|
+
|---|---|
|
|
130
|
+
| `new BeamClient(config)` | Create client with identity + directory URL |
|
|
131
|
+
| `client.connect()` | Connect to directory via WebSocket |
|
|
132
|
+
| `client.send(to, intent, payload)` | Send a structured intent frame |
|
|
133
|
+
| `client.talk(to, message)` | Natural language message (no schema needed) |
|
|
134
|
+
| `client.thread(to)` | Start a multi-turn conversation |
|
|
135
|
+
| `client.disconnect()` | Graceful disconnect |
|
|
136
|
+
|
|
137
|
+
### `BeamDirectory`
|
|
138
|
+
|
|
139
|
+
| Method | Description |
|
|
140
|
+
|---|---|
|
|
141
|
+
| `directory.lookup(beamId)` | Find a specific agent |
|
|
142
|
+
| `directory.search(query)` | Search agents by org/capability |
|
|
143
|
+
| `directory.register(name, capabilities)` | Register agent in directory |
|
|
144
|
+
|
|
145
|
+
### Frame Utilities
|
|
146
|
+
|
|
147
|
+
| Function | Description |
|
|
148
|
+
|---|---|
|
|
149
|
+
| `createIntentFrame(opts)` | Build a new intent frame |
|
|
150
|
+
| `createResultFrame(opts)` | Build a result response frame |
|
|
151
|
+
| `signFrame(frame, privateKey)` | Ed25519-sign a frame |
|
|
152
|
+
| `validateIntentFrame(frame)` | Validate structure + replay protection |
|
|
153
|
+
| `MAX_FRAME_SIZE` | 1024 bytes max per frame |
|
|
154
|
+
| `REPLAY_WINDOW_MS` | 5 minute replay window |
|
|
155
|
+
|
|
156
|
+
## Security
|
|
157
|
+
|
|
158
|
+
- **Ed25519 signatures** on every frame
|
|
159
|
+
- **Nonce-based replay protection** (5 min window)
|
|
160
|
+
- **Deny-by-default ACL** — agents must be explicitly authorized
|
|
161
|
+
- **Schema validation** at the directory level
|
|
162
|
+
- **Rate limiting** — 60 intents/min per agent
|
|
163
|
+
|
|
164
|
+
## Examples
|
|
165
|
+
|
|
166
|
+
See [`examples/`](https://github.com/Beam-directory/beam-protocol/tree/main/examples) in the main repo.
|
|
167
|
+
|
|
168
|
+
## Links
|
|
169
|
+
|
|
170
|
+
- 🌐 [beam.directory](https://beam.directory)
|
|
171
|
+
- 📄 [RFC 0001](https://github.com/Beam-directory/beam-protocol/blob/main/spec/RFC-0001.md)
|
|
172
|
+
- 📖 [Full Documentation](https://github.com/Beam-directory/beam-protocol/tree/main/docs)
|
|
173
|
+
- 🐍 [Python SDK](https://pypi.org/project/beam-directory/)
|
|
174
|
+
|
|
175
|
+
## License
|
|
176
|
+
|
|
177
|
+
Apache-2.0
|