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)

bash

npx @agenium/create-agent my-agent
cd my-agent
npm install
npm start

Choose from 3 templates: echo (hello world), tools (tool-calling), api (REST gateway).

Use as a Library

bash

npm install agenium

typescript

import { 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

bash

# Initialize agent configuration
agenium init

# Resolve an agent
agenium resolve agent://search

# Check connection
agenium status

# End-to-end connectivity test
agenium e2e

Architecture

agent://myagent                    agent://search
     │                                  │
     ├── resolve("agent://search") ────►│
     │   (DNS lookup via marketplace)   │
     │◄── endpoint: https://...  ───────┤
     │                                  │
     ├── POST /a2a/message ────────────►│
     │   (HTTP/2 + mTLS)               │
     │◄── response ────────────────────┤

Configuration

typescript

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

bash

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Run E2E tests
npm run e2e

Tests

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