AGENIUM

1# AGENIUM
2 
3Stateful agent-to-agent communication client for the `agent://` protocol.
4 
5## What is AGENIUM?
6 
7AGENIUM provides identity, discovery, and messaging for AI agents. Think of it as DNS + HTTP for agents — each agent gets a unique `agent://name` URI and can discover and communicate with other agents.
8 
9## Quick Start
10 
11### Create a New Agent (Recommended)
12 
13```bash
14npx @agenium/create-agent my-agent
15cd my-agent
16npm install
17npm start
18```
19 
20Choose from 3 templates: **echo** (hello world), **tools** (tool-calling), **api** (REST gateway).
21 
22### Use as a Library
23 
24```bash
25npm install agenium
26```
27 
28```typescript
29import { AgeniumClient } from 'agenium';
30 
31const client = new AgeniumClient({
32  apiKey: 'dom_your_api_key_here',  // Get one at marketplace.agenium.net
33  agentUri: 'agent://myagent',
34});
35 
36// Resolve another agent
37const target = await client.resolve('agent://search');
38console.log(target.endpoint); // https://...
39 
40// Connect and send message
41const session = await client.connect('agent://search');
42await session.send({ query: 'find MCP servers for GitHub' });
43const response = await session.receive();
44```
45 
46## Features
47 
48- **`agent://` Protocol** — Unique agent identity via URI scheme
49- **DNS Resolution** — Discover agents by name (`agent://name` → endpoint)
50- **Stateful Sessions** — SQLite-backed persistent sessions
51- **HTTP/2 + mTLS** — Secure transport with mutual TLS
52- **At-Least-Once Delivery** — Outbox pattern for reliable messaging
53- **Circuit Breakers** — Automatic failure detection and recovery
54- **Prometheus Metrics** — Built-in observability
55 
56## Getting an API Key
57 
581. Visit [marketplace.agenium.net](https://marketplace.agenium.net)
592. Register a domain name (e.g., `agent://myagent`)
603. Complete purchase (TON payment)
614. Save your API key (shown only once)
62 
63## CLI
64 
65```bash
66# Initialize agent configuration
67agenium init
68 
69# Resolve an agent
70agenium resolve agent://search
71 
72# Check connection
73agenium status
74 
75# End-to-end connectivity test
76agenium e2e
77```
78 
79## Architecture
80 
81```
82agent://myagent                    agent://search
83     │                                  │
84     ├── resolve("agent://search") ────►│
85     │   (DNS lookup via marketplace)   │
86     │◄── endpoint: https://...  ───────┤
87     │                                  │
88     ├── POST /a2a/message ────────────►│
89     │   (HTTP/2 + mTLS)               │
90     │◄── response ────────────────────┤
91```
92 
93## Configuration
94 
95```typescript
96const client = new AgeniumClient({
97  // Required
98  apiKey: 'dom_xxx',           // Your marketplace API key
99  agentUri: 'agent://myname',  // Your agent URI
100 
101  // Optional
102  dnsServer: 'https://marketplace.agenium.net',  // DNS resolver
103  dataDir: './data',           // SQLite session storage
104  timeout: 30000,              // Request timeout (ms)
105  retries: 3,                  // Max retry attempts
106});
107```
108 
109## API Reference
110 
111### `client.resolve(agentUri)`
112Resolve an agent URI to its endpoint and capabilities.
113 
114### `client.connect(agentUri)`
115Establish a stateful session with another agent.
116 
117### `session.send(message)`
118Send a message in an active session.
119 
120### `session.receive()`
121Receive the next message in a session.
122 
123### `session.close()`
124Gracefully close a session.
125 
126## Protocol Services
127 
128The AGENIUM ecosystem includes:
129 
130| Service | URI | Description |
131|---------|-----|-------------|
132| Search | `agent://agenium` | Agent & tool discovery engine |
133| Marketplace | [marketplace.agenium.net](https://marketplace.agenium.net) | Domain registration & credentials |
134 
135## Development
136 
137```bash
138# Install dependencies
139npm install
140 
141# Run tests
142npm test
143 
144# Build
145npm run build
146 
147# Run E2E tests
148npm run e2e
149```
150 
151## Tests
152 
15356 tests passing:
154- 22 unit tests
155- 24 bug-server integration tests
156- 10 end-to-end tests
157 
158## License
159 
160MIT
161 
162## Ecosystem
163 
164| Package | Description |
165|---------|-------------|
166| [`agenium`](https://npm.im/agenium) | Core client SDK |
167| [`@agenium/create-agent`](https://github.com/Aganium/create-agenium-agent) | CLI scaffold tool |
168| [`@agenium/mcp-server`](https://npm.im/@agenium/mcp-server) | MCP → agent:// bridge |
169| [`discord-agenium`](https://npm.im/discord-agenium) | Discord bot gateway |
170| [`slack-agenium`](https://npm.im/slack-agenium) | Slack app gateway |
171| [`n8n-nodes-agenium`](https://npm.im/n8n-nodes-agenium) | n8n automation nodes |
172 
173## Links
174 
175- Website: [agenium.net](https://agenium.net)
176- Docs: [docs.agenium.net](https://docs.agenium.net)
177- Demo: [demo.agenium.net](https://demo.agenium.net)
178- Marketplace: [marketplace.agenium.net](https://marketplace.agenium.net)
179- Organization: [github.com/Aganium](https://github.com/Aganium)
180