AGENIUM
Stateful agent-to-agent communication client for the agent:// protocol.
What is AGENIUM?
AGENIUM 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.
Quick Start
Create a New Agent (Recommended)
npx @agenium/create-agent my-agent
cd my-agent
npm install
npm startChoose from 3 templates: echo (hello world), tools (tool-calling), api (REST gateway).
Use as a Library
npm install ageniumimport { AgeniumClient } from 'agenium';
const client = new AgeniumClient({
apiKey: 'dom_your_api_key_here', // Get one at marketplace.agenium.net
agentUri: 'agent://myagent',
});
// Resolve another agent
const target = await client.resolve('agent://search');
console.log(target.endpoint); // https://...
// Connect and send message
const session = await client.connect('agent://search');
await session.send({ query: 'find MCP servers for GitHub' });
const response = await session.receive();Features
agent://Protocol — Unique agent identity via URI scheme- DNS Resolution — Discover agents by name (
agent://name→ endpoint) - Stateful Sessions — SQLite-backed persistent sessions
- HTTP/2 + mTLS — Secure transport with mutual TLS
- At-Least-Once Delivery — Outbox pattern for reliable messaging
- Circuit Breakers — Automatic failure detection and recovery
- Prometheus Metrics — Built-in observability
Getting an API Key
- Visit marketplace.agenium.net
- Register a domain name (e.g.,
agent://myagent) - Complete purchase (TON payment)
- Save your API key (shown only once)
CLI
# Initialize agent configuration
agenium init
# Resolve an agent
agenium resolve agent://search
# Check connection
agenium status
# End-to-end connectivity test
agenium e2eArchitecture
agent://myagent agent://search
│ │
├── resolve("agent://search") ────►│
│ (DNS lookup via marketplace) │
│◄── endpoint: https://... ───────┤
│ │
├── POST /a2a/message ────────────►│
│ (HTTP/2 + mTLS) │
│◄── response ────────────────────┤Configuration
const client = new AgeniumClient({
// Required
apiKey: 'dom_xxx', // Your marketplace API key
agentUri: 'agent://myname', // Your agent URI
// Optional
dnsServer: 'https://marketplace.agenium.net', // DNS resolver
dataDir: './data', // SQLite session storage
timeout: 30000, // Request timeout (ms)
retries: 3, // Max retry attempts
});API Reference
client.resolve(agentUri)
Resolve an agent URI to its endpoint and capabilities.
client.connect(agentUri)
Establish a stateful session with another agent.
session.send(message)
Send a message in an active session.
session.receive()
Receive the next message in a session.
session.close()
Gracefully close a session.
Protocol Services
The AGENIUM ecosystem includes:
| Service | URI | Description | |---------|-----|-------------| | Search | agent://agenium | Agent & tool discovery engine | | Marketplace | marketplace.agenium.net | Domain registration & credentials |
Development
# Install dependencies
npm install
# Run tests
npm test
# Build
npm run build
# Run E2E tests
npm run e2eTests
56 tests passing:
- 22 unit tests
- 24 bug-server integration tests
- 10 end-to-end tests
License
MIT
Ecosystem
| Package | Description | |---------|-------------| | agenium | Core client SDK | | @agenium/create-agent | CLI scaffold tool | | @agenium/mcp-server | MCP → agent:// bridge | | discord-agenium | Discord bot gateway | | slack-agenium | Slack app gateway | | n8n-nodes-agenium | n8n automation nodes |
Links
- Website: agenium.net
- Docs: docs.agenium.net
- Demo: demo.agenium.net
- Marketplace: marketplace.agenium.net
- Organization: github.com/Aganium
