agentdial 1.0.0 → 1.0.1

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.
Files changed (2) hide show
  1. package/README.md +69 -131
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,34 +1,26 @@
1
- # agentdial
1
+ # Agent Identity Protocol (AIP)
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/agentdial.svg)](https://www.npmjs.com/package/agentdial)
4
+ [![Protocol: AIP v1.0](https://img.shields.io/badge/Protocol-AIP%20v1.0-blueviolet.svg)](#identitymd-spec)
4
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
- [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20WSL-blue.svg)](#supported-channels)
6
6
  [![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](#tests)
7
7
  [![Downloads](https://img.shields.io/npm/dm/agentdial.svg)](https://www.npmjs.com/package/agentdial)
8
8
 
9
- **Dial your AI agent into every platform.**
9
+ **MCP gave agents tools. A2A gave agents collaboration. AIP gives agents identity.**
10
10
 
11
- One identity file. Seven channels. Zero boilerplate.
11
+ Agents are the new employees. They need phone numbers, inboxes, and handles -- not just API keys. Today every platform reinvents this: Twilio for SMS, Discord.js for chat, Slack SDK for work, SendGrid for email. Fifteen APIs to give one agent a presence.
12
+
13
+ AIP is a protocol. `IDENTITY.md` is the spec. `agentdial` is the CLI.
12
14
 
13
15
  ```bash
14
16
  npx agentdial setup
15
17
  ```
16
18
 
17
19
  ```
18
- ___ __ ____ _ __
19
- / _ |___ ____ ___ ____/ / / __ \(_)___ _/ /
20
- / __ / _ `/ -_) _ \/ __/ / / / / / / _ `/ /
21
- /_/ |_\_, /\__/_//_/\__/_/ /_/ /_/_/\_,_/_/
22
- /___/
23
-
24
- v1.0.0 One identity. Every channel.
25
-
26
20
  ┌────────────────────────────────────────┐
27
- │ Agent Identity │
28
- ├────────────────────────────────────────┤
29
- │ Name: Spark │
30
- │ Tagline: Your AI concierge │
31
- │ Backend: http://localhost:8080/agent │
21
+ │ Agent: Spark │
22
+ │ Tagline: Your AI concierge │
23
+ │ Backend: http://localhost:8080/agent │
32
24
  └────────────────────────────────────────┘
33
25
 
34
26
  Channel Status Cost Setup
@@ -37,10 +29,23 @@ npx agentdial setup
37
29
  Discord Bot active Free 3 min
38
30
  Slack App ready Free 5 min
39
31
  SMS (Twilio) ---- ~$0.01 5 min
40
- Web Widget active Free 1 min
32
+ Voice (Twilio) ---- ~$0.01 5 min
41
33
  ```
42
34
 
43
- agentdial gives your AI agent a single identity file (`IDENTITY.md`) and connects it to Telegram, Discord, Slack, SMS, WhatsApp, email, and voice -- through one unified gateway.
35
+ One file. Seven channels. Your agent has an identity.
36
+
37
+ ## The Protocol Stack
38
+
39
+ | Protocol | Solves | Spec | Reference Impl |
40
+ | -------- | ------------------- | ----------------------------- | ----------------- |
41
+ | **MCP** | Tool access | Tool schemas (JSON) | SDK + CLI |
42
+ | **A2A** | Agent collaboration | Agent Cards (JSON) | SDK + server |
43
+ | **AIP** | Agent identity | `IDENTITY.md` (YAML+Markdown) | SDK + `agentdial` |
44
+
45
+ AIP defines two primitives:
46
+
47
+ - **`IDENTITY.md`** -- a single markdown file with YAML frontmatter that declares who your agent is, where it lives, and which channels it speaks on. Human-readable. Machine-parseable. Portable.
48
+ - **`GatewayMessage`** -- a normalized message format (`{ id, channel, from, text, timestamp }`) that collapses Telegram, Discord, Slack, SMS, WhatsApp, email, and voice into one schema. Your agent handles one format. agentdial handles the rest.
44
49
 
45
50
  ## Install
46
51
 
@@ -54,63 +59,36 @@ Or run directly:
54
59
  npx agentdial setup
55
60
  ```
56
61
 
57
- **Requirements:** Node.js >= 18 · **Supports:** macOS, Linux, Windows (WSL)
62
+ **Requirements:** Node.js >= 18 | **Platforms:** macOS, Linux, Windows (WSL)
58
63
 
59
64
  ## Quick Start
60
65
 
61
- Three steps. Two minutes.
62
-
63
66
  ```bash
64
- # 1. Create your agent identity + pick channels
67
+ # 1. Create identity + pick channels
65
68
  agentdial setup
66
69
 
67
- # 2. Add a channel (interactive credential prompts)
70
+ # 2. Add a channel
68
71
  agentdial channels add telegram
69
72
 
70
73
  # 3. Start the gateway
71
74
  agentdial serve --agent-url http://localhost:8080/agent
72
75
  ```
73
76
 
74
- Your agent is now live on Telegram. Add more channels anytime with `agentdial channels add <channel>`.
75
-
76
- ## Why agentdial?
77
+ Your agent is live on Telegram. Add more channels anytime with `agentdial channels add <channel>`.
77
78
 
78
- Every AI agent needs to talk to users. Today that means:
79
+ ## Channels
79
80
 
80
- - **5-15 separate API integrations** (Telegram Bot API, Discord.js, Slack SDK, Twilio, SendGrid...)
81
- - **Hundreds of lines of boilerplate** per channel (webhook setup, message normalization, response formatting)
82
- - **No standard identity format** -- every platform represents your agent differently
83
- - **Credential sprawl** -- API keys scattered across env files, dashboards, and config files
81
+ | Channel | Cost | Setup | Credentials |
82
+ | ----------------- | ----------- | ------ | -------------------------- |
83
+ | Telegram Bot | Free | 2 min | Bot token from @BotFather |
84
+ | Discord Bot | Free | 3 min | Bot token + application ID |
85
+ | Slack App | Free | 5 min | Bot token + signing secret |
86
+ | SMS (Twilio) | ~$0.008/msg | 5 min | Account SID + auth token |
87
+ | WhatsApp (Twilio) | ~$0.005/msg | 10 min | Account SID + auth token |
88
+ | Email (SendGrid) | Free trial | 3 min | API key + verified sender |
89
+ | Voice (Twilio) | ~$0.013/min | 5 min | Account SID + auth token |
84
90
 
85
- agentdial solves this with:
86
-
87
- - **One identity file** (`IDENTITY.md`) that defines your agent's name, personality, and channel config
88
- - **One gateway** that normalizes all incoming messages to a single `GatewayMessage` format
89
- - **One response format** (`GatewayResponse`) that agentdial translates per-channel (Markdown for Telegram, embeds for Discord, blocks for Slack)
90
- - **Secure credential storage** in `~/.agentdial/credentials/` with 0600 permissions
91
- - **Zero lock-in** -- your agent backend is a plain HTTP endpoint that receives JSON
92
-
93
- ## Supported Channels
94
-
95
- | Channel | Cost | Setup Time | Credentials Needed |
96
- | ----------------- | -------------- | ---------- | -------------------------- |
97
- | Telegram Bot | Free | 2 min | Bot token from @BotFather |
98
- | Discord Bot | Free | 3 min | Bot token + application ID |
99
- | Slack App | Free | 5 min | Bot token + signing secret |
100
- | SMS (Twilio) | ~$0.0079/msg | 5 min | Account SID + auth token |
101
- | WhatsApp (Twilio) | ~$0.005/msg | 10 min | Account SID + auth token |
102
- | Email (SendGrid) | 60-day trial\* | 3 min | API key + verified sender |
103
- | Voice (Twilio) | ~$0.013/min | 5 min | Account SID + auth token |
104
-
105
- Free channels (Telegram, Discord) need zero payment info. Paid channels use Twilio or SendGrid with usage-based pricing. \*SendGrid free tier was removed May 2025; 60-day trial (100 emails/day), then $19.95/mo.
106
-
107
- ### Coming Soon
108
-
109
- | Channel | Status |
110
- | ------------------ | ------- |
111
- | Microsoft Teams | Planned |
112
- | Facebook Messenger | Planned |
113
- | Web Widget | Planned |
91
+ Telegram, Discord, and Slack need zero payment info.
114
92
 
115
93
  ## Architecture
116
94
 
@@ -123,23 +101,21 @@ Free channels (Telegram, Discord) need zero payment info. Paid channels use Twil
123
101
  Email ──┤ │ :3141 │ │ (any HTTP) │
124
102
  Voice ──┘ └────────────┘ └──────────────────┘
125
103
  │
126
- │ Normalizes all messages to:
127
- │ { id, channel, from, text, timestamp }
104
+ │ GatewayMessage (normalized)
105
+ │ { id, channel, from, text, timestamp }
128
106
  │
129
- │ Formats responses per-channel:
130
- │ Telegram: Markdown + inline keyboards
131
- │ Discord: Embeds + components
132
- │ Slack: Blocks + actions
133
- └ Others: Plain text fallback
107
+ │ GatewayResponse (per-channel)
108
+ │ Telegram: Markdown + inline keyboards
109
+ │ Discord: Embeds + components
110
+ │ Slack: Blocks + actions
111
+ └ Others: Plain text fallback
134
112
  ```
135
113
 
136
- The gateway runs on port 3141 by default. Every incoming message from any channel is normalized into a `GatewayMessage`, forwarded to your agent backend as a POST request, and the response is formatted back into the channel's native format.
137
-
138
- Your agent backend just needs one endpoint that accepts a JSON body and returns `{ text: "..." }`.
114
+ Your agent backend is a plain HTTP endpoint. It receives a JSON `GatewayMessage`, returns `{ text: "..." }`. That's the entire contract.
139
115
 
140
116
  ## IDENTITY.md Spec
141
117
 
142
- agentdial introduces the **Agent Identity Protocol (AIP) v1.0** -- a single markdown file that defines your agent across all platforms.
118
+ The **Agent Identity Protocol v1.0** spec. YAML frontmatter is machine-readable. Markdown body is human-readable context (usable as a system prompt).
143
119
 
144
120
  ```yaml
145
121
  ---
@@ -168,26 +144,21 @@ channels:
168
144
 
169
145
  - Friendly and knowledgeable
170
146
  - Concise but thorough
171
- - Uses casual tone with professional substance
172
147
 
173
148
  ## Capabilities
174
149
 
175
150
  - Restaurant recommendations and reservations
176
151
  - Event discovery and booking
177
- - Local area knowledge
178
152
 
179
153
  ## Boundaries
180
154
 
181
155
  - No financial transactions
182
156
  - No medical or legal advice
183
- - No personal data retention beyond the session
184
157
  ```
185
158
 
186
- The YAML frontmatter is machine-readable. The markdown body is human-readable context your agent can use as a system prompt. The `channels` block declares which platforms your agent is active on.
187
-
188
159
  ## Claude Code Integration
189
160
 
190
- agentdial ships as an MCP server for Claude Code. Add it to your project's `.mcp.json`:
161
+ agentdial ships as an MCP server for Claude Code:
191
162
 
192
163
  ```json
193
164
  {
@@ -200,90 +171,64 @@ agentdial ships as an MCP server for Claude Code. Add it to your project's `.mcp
200
171
  }
201
172
  ```
202
173
 
203
- This gives Claude Code tools to manage channels, test connections, and check agent status without leaving the terminal.
204
-
205
- Start the MCP server standalone:
206
-
207
- ```bash
208
- agentdial mcp-serve
209
- ```
174
+ This gives Claude Code tools to manage channels, test connections, and check agent status.
210
175
 
211
176
  ## Voice
212
177
 
213
- Voice channels use Twilio for telephony. Configure with:
214
-
215
178
  ```bash
216
179
  agentdial voice setup
217
- ```
218
-
219
- This prompts for your Twilio Account SID, Auth Token, and phone number. Test with:
220
-
221
- ```bash
222
180
  agentdial voice test --number +15551234567
223
181
  ```
224
182
 
225
- Voice calls are transcribed to text, sent through the same gateway pipeline as chat messages, and the response is synthesized back to speech via Twilio.
183
+ Calls are transcribed, routed through the same gateway as chat, and responses are synthesized back to speech via Twilio.
226
184
 
227
185
  ## Configuration
228
186
 
229
- All config and credentials are stored locally:
230
-
231
187
  ```
232
188
  ~/.agentdial/
233
- ├── config.json # Gateway port, log level, identity file path
234
- ├── credentials/ # Per-channel credential files (0600 permissions)
189
+ ├── config.json # Gateway port, log level, identity path
190
+ ├── credentials/ # Per-channel credentials (0600 permissions)
235
191
  │ ├── telegram.json
236
192
  │ ├── discord.json
237
- │ ├── slack.json
238
193
  │ └── twilio.json
239
194
  ├── templates/ # Identity file templates
240
195
  └── logs/ # Gateway logs
241
196
  ```
242
197
 
243
- Example `config.json`:
198
+ Credentials never touch your project directory or git.
244
199
 
245
- ```json
246
- {
247
- "identityFile": "IDENTITY.md",
248
- "gatewayPort": 3141,
249
- "logLevel": "info"
250
- }
251
- ```
252
-
253
- Credentials are never stored in your project directory or committed to git. The `credentials/` directory is created with 0700 permissions, and individual credential files with 0600.
254
-
255
- ## All Commands
200
+ ## Commands
256
201
 
257
202
  ```
258
203
  SETUP
259
- agentdial setup Interactive wizard (identity + channels)
204
+ agentdial setup Interactive wizard
260
205
  agentdial setup --file ./agent.md Use existing identity file
261
206
 
262
207
  CHANNELS
263
- agentdial channels add <channel> Configure a new channel
208
+ agentdial channels add <channel> Add a channel
264
209
  agentdial channels remove <channel> Remove a channel
265
- agentdial channels list Show all channels and status
266
- agentdial channels test [channel] Test one or all channels
210
+ agentdial channels list List all channels
211
+ agentdial channels test [channel] Test connectivity
267
212
 
268
213
  VOICE
269
214
  agentdial voice setup Configure Twilio voice
270
- agentdial voice test -n <phone> Test call to a number
215
+ agentdial voice test -n <phone> Test call
271
216
 
272
217
  GATEWAY
273
- agentdial serve Start the gateway (port 3141)
274
- agentdial serve -p 8080 Custom port
275
- agentdial serve -a http://my-agent Point to agent backend
218
+ agentdial serve Start gateway (port 3141)
219
+ agentdial serve -p 8080 Custom port
220
+ agentdial serve -a http://my-agent Custom backend
276
221
 
277
222
  STATUS
278
- agentdial status Show all channel statuses
223
+ agentdial status Show channel statuses
279
224
  agentdial status --json Machine-readable output
280
225
 
281
226
  TEST
282
- agentdial test Send test message through gateway
227
+ agentdial test Test full pipeline
283
228
  agentdial test -c telegram -m "hi" Test specific channel
284
229
 
285
230
  MCP
286
- agentdial mcp-serve Start as MCP server for Claude Code
231
+ agentdial mcp-serve Start as MCP server
287
232
  ```
288
233
 
289
234
  ## Tests
@@ -292,19 +237,12 @@ MCP
292
237
  cd tools/agentdial && pnpm test
293
238
  ```
294
239
 
295
- Tests cover identity parsing/validation, gateway message normalization, response formatting, adapter interface compliance, and Zod schema validation. All tests use mocks -- no real API calls.
240
+ Covers identity parsing, gateway normalization, response formatting, adapter compliance, and Zod schema validation. All mocked -- no real API calls.
296
241
 
297
242
  ## Contributing
298
243
 
299
- See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding adapters, running tests, and submitting PRs.
300
-
301
- ## See Also
302
-
303
- - **[agentgrid](https://github.com/naman10parikh/agentgrid)** -- Spawn grids of AI coding agents in parallel terminal panes
304
- - **[Energy](https://github.com/naman10parikh/Energy)** -- Self-improving agent platform. agentdial is part of the Energy toolkit
305
- - **[Model Context Protocol](https://modelcontextprotocol.io)** -- The MCP standard agentdial integrates with
306
- - **[Google A2A](https://google.github.io/A2A/)** -- Agent-to-Agent protocol for inter-agent communication
244
+ See [CONTRIBUTING.md](CONTRIBUTING.md).
307
245
 
308
246
  ## License
309
247
 
310
- MIT -- see [LICENSE](LICENSE).
248
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentdial",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "Dial your AI agent into every platform. One identity. Every channel.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -44,7 +44,7 @@
44
44
  "license": "MIT",
45
45
  "repository": {
46
46
  "type": "git",
47
- "url": "https://github.com/naman10parikh/agentdial"
47
+ "url": "git+https://github.com/naman10parikh/agentdial.git"
48
48
  },
49
49
  "homepage": "https://github.com/naman10parikh/agentdial",
50
50
  "bugs": {