AGENIUM

Appearance

API Reference ​

Complete TypeScript API documentation for AGENIUM.

Installation ​

bash
npm install agenium

Quick Example ​

typescript
import { createAgent } from 'agenium';

const agent = createAgent('myagent', {
  persistence: true,
  dataDir: './data'
});

await agent.start();

const result = await agent.connect('agent://remote');
if (result.success) {
  const response = await agent.request(
    result.session!.id,
    'method',
    { param: 'value' }
  );
}

Core API ​

createAgent(name, config?) ​

Create a new agent instance.

Parameters:

  • name (string): Agent name (must be valid agent URI name)
  • config (AgentConfig, optional): Configuration options

Returns: Agent

Example:

typescript
const agent = createAgent('alice', {
  persistence: true,
  dataDir: './data',
  capabilities: ['messaging', 'streaming']
});

Agent ​

Main agent class for communication.

agent.start(): Promise<void> ​

Start the agent server.

typescript
await agent.start();
console.log('Agent started on port:', agent.config.listenPort);

agent.stop(): Promise<void> ​

Stop the agent and close all connections.

typescript
await agent.stop();

agent.connect(target): Promise<ConnectResult> ​

Connect to a remote agent.

Parameters:

  • target (string | { host, port }): Agent URI or direct endpoint

Returns: Promise<ConnectResult>

typescript
const result = await agent.connect('agent://bob');

if (result.success) {
  console.log('Session ID:', result.session!.id);
} else {
  console.error('Error:', result.error);
}

agent.request(sessionId, method, params?, timeout?): Promise<unknown> ​

Send a request and wait for response.

Parameters:

  • sessionId (string): Active session ID
  • method (string): Method/action name
  • params (object, optional): Method parameters
  • timeout (number, optional): Request timeout in ms

Returns: Promise<unknown> - Response data

typescript
const response = await agent.request(sessionId, 'greet', {
  name: 'Alice'
});

agent.event(sessionId, event, data?): Promise<boolean> ​

Send a fire-and-forget event.

Parameters:

  • sessionId (string): Active session ID
  • event (string): Event name
  • data (any, optional): Event data

Returns: Promise<boolean> - Success status

typescript
await agent.event(sessionId, 'status_update', {
  status: 'processing',
  progress: 0.5
});

agent.onRequest(method, handler) ​

Register a request handler.

Parameters:

  • method (string): Method name to handle
  • handler (RequestHandler): Handler function
typescript
agent.onRequest('greet', async (params, sessionId) => {
  return { message: `Hello, ${params?.name}!` };
});

Handler signature:

typescript
type RequestHandler = (
  params: unknown,
  sessionId: string
) => Promise<unknown>;

agent.onEvent(event, handler) ​

Register an event handler.

Parameters:

  • event (string): Event name to handle
  • handler (EventHandler): Handler function
typescript
agent.onEvent('notification', async (data, sessionId) => {
  console.log('Notification:', data);
});

Handler signature:

typescript
type EventHandler = (
  data: unknown,
  sessionId: string
) => Promise<void>;

agent.getIdentity(): AgentID ​

Get agent identity information.

typescript
const identity = agent.getIdentity();
console.log('Name:', identity.name);
console.log('Public Key:', identity.publicKey);

agent.getURI(): string ​

Get agent URI.

typescript
console.log(agent.getURI());
// Output: agent://alice

agent.getSession(sessionId): Session | undefined ​

Get session by ID.

typescript
const session = agent.getSession(sessionId);
if (session) {
  console.log('State:', session.state);
  console.log('Capabilities:', session.capabilities);
}

agent.getAllSessions(): Session[] ​

Get all sessions.

typescript
const sessions = agent.getAllSessions();
console.log('Total sessions:', sessions.length);

agent.getStats() ​

Get agent statistics.

typescript
const stats = agent.getStats();
console.log('Active sessions:', stats.sessions.active);
console.log('Total requests:', stats.dispatcher.totalRequests);

Types ​

AgentConfig ​

typescript
interface AgentConfig {
  // Core
  agentName?: string;            // Agent name (default: from first param)
  persistence?: boolean;         // Enable persistence (default: true)
  dataDir?: string;              // Data directory (default: '~/.agenium')
  listenPort?: number;           // Server port (default: 8443)
  historyDepth?: number;         // Session history depth (default: 100)
  
  // DNS
  dnsServer?: string;            // DNS server address (default: '185.204.169.26')
  bugReportServer?: string;      // Bug report server URL
  
  // Timeouts (flat structure)
  connectionTimeoutMs?: number;  // Connection timeout (default: 10000)
  requestTimeoutMs?: number;     // Request timeout (default: 30000)
  
  // Capabilities
  capabilities?: Capability[];   // Agent capabilities (default: ['messaging'])
}

TIP

For connection pool, circuit breaker, and advanced timeout configuration, use the global setConfig() API (see Configuration section).

Session ​

typescript
interface Session {
  id: string;
  localAgent: AgentID;
  remoteAgent?: AgentID;
  state: SessionState;
  createdAt: number;
  lastSeenAt: number;
  capabilities: Capability[];
}

SessionState ​

typescript
enum SessionState {
  IDLE = 'IDLE',
  CONNECTING = 'CONNECTING',
  CONNECTED = 'CONNECTED',
  ACTIVE = 'ACTIVE',
  ERROR = 'ERROR',
  CLOSED = 'CLOSED'
}

ConnectResult ​

typescript
interface ConnectResult {
  success: boolean;
  session?: Session;
  error?: string;
}

AgentID ​

typescript
interface AgentID {
  name: string;
  publicKey: string;
  description?: string;
}

DNS API ​

DNSResolver ​

new DNSResolver(config?) ​

Create a DNS resolver.

typescript
import { DNSResolver } from 'agenium';

const resolver = new DNSResolver({
  server: '185.204.169.26',
  port: 3000,
  useHttps: false,
  timeoutMs: 10000
});

resolver.resolve(uri): Promise<ResolveResult> ​

Resolve agent URI to endpoint.

typescript
const result = await resolver.resolve('agent://bob');

if (result.ok) {
  console.log('Endpoint:', result.agent.endpoint);
  console.log('Public Key:', result.agent.publicKey);
}

ResolveResult ​

typescript
type ResolveResult = 
  | { ok: true; agent: ResolvedAgent }
  | { ok: false; error: { code: DNSErrorCode; message: string } };

ResolvedAgent ​

typescript
interface ResolvedAgent {
  name: string;
  publicKey: string;
  endpoint: string;
  host: string;
  port: number;
  capabilities: string[];
  protocolVersions: string[];
  resolvedAt: number;
  expiresAt: number;
}

Protocol API ​

Frame Types ​

RequestFrame ​

typescript
interface RequestFrame {
  version: string;
  messageId: string;
  type: 'REQUEST';
  sessionId: string;
  timestamp: number;
  payload: {
    method: string;
    params?: Record<string, unknown>;
  };
  timeoutMs?: number;
}

ResponseFrame ​

typescript
interface ResponseFrame {
  version: string;
  messageId: string;
  type: 'RESPONSE';
  sessionId: string;
  timestamp: number;
  replyTo: string;
  payload: {
    success: boolean;
    result?: unknown;
    error?: {
      code: string;
      message: string;
      details?: unknown;
    };
  };
}

EventFrame ​

typescript
interface EventFrame {
  version: string;
  messageId: string;
  type: 'EVENT';
  sessionId: string;
  timestamp: number;
  payload: {
    event: string;
    data?: unknown;
  };
}

Frame Builders ​

typescript
import { 
  createRequestFrame, 
  createResponseFrame, 
  createEventFrame 
} from 'agenium';

const request = createRequestFrame(sessionId, 'method', { param: 'value' });
const response = createResponseFrame(sessionId, replyTo, true, { result: 'ok' });
const event = createEventFrame(sessionId, 'event', { data: 'value' });

Configuration API ​

getConfig(): AgeniumConfig ​

Get current global configuration.

typescript
import { getConfig } from 'agenium';

const config = getConfig();
console.log('DNS timeout:', config.timeouts.dnsLookupMs);

setConfig(config: Partial<AgeniumConfig>): void ​

Update global configuration.

typescript
import { setConfig } from 'agenium';

setConfig({
  timeouts: {
    requestMs: 60000  // 60 seconds
  }
});

DEFAULT_CONFIG ​

Default configuration values.

typescript
import { DEFAULT_CONFIG } from 'agenium';

console.log(DEFAULT_CONFIG);
/*
{
  timeouts: {
    dnsLookupMs: 10000,
    handshakeMs: 10000,
    requestMs: 30000,
    connectionIdleMs: 60000
  },
  pool: {
    maxConnectionsPerAgent: 4,
    maxStreamsPerConnection: 100
  },
  circuitBreaker: {
    failureThreshold: 5,
    resetTimeoutMs: 30000,
    successThreshold: 2
  }
}
*/

Utility Functions ​

URI Utilities ​

typescript
import { 
  parseAgentURI, 
  isValidAgentURI, 
  toAgentURI,
  validateAgentName 
} from 'agenium';

// Parse URI
const parsed = parseAgentURI('agent://alice');
// { scheme: 'agent', name: 'alice' }

// Validate URI
console.log(isValidAgentURI('agent://alice'));  // true

// Create URI
const uri = toAgentURI('alice');  // 'agent://alice'

// Validate name
console.log(validateAgentName('alice'));  // true
console.log(validateAgentName('123'));    // false

ID Generation ​

typescript
import { generateId } from 'agenium';

const id = generateId();
console.log(id);  // 'msg_1703260800_abc123'

Metrics API ​

getHealth(): HealthStatus ​

Get current health status.

typescript
import { getHealth } from 'agenium';

const health = getHealth();
console.log(health);
/*
{
  status: 'ok',
  uptime: 12345,
  timestamp: 1703260800
}
*/

getMetricsText(): string ​

Get Prometheus-formatted metrics.

typescript
import { getMetricsText } from 'agenium';

const metrics = getMetricsText();
console.log(metrics);
// # HELP agenium_requests_total Total requests
// # TYPE agenium_requests_total counter
// agenium_requests_total 1234

Event Reference ​

Agent Events ​

typescript
agent.on('started', (info) => {
  console.log('Agent started:', info.name, info.port);
});

agent.on('stopped', () => {
  console.log('Agent stopped');
});

agent.on('connected', (info) => {
  console.log('Connected to:', info.remoteAgent.name);
  console.log('Session ID:', info.sessionId);
});

agent.on('connection', (info) => {
  console.log('Incoming connection from:', info.remoteAgent.name);
});

agent.on('listening', (addr) => {
  console.log('Listening on:', addr.address, addr.port);
});

agent.on('error', (err) => {
  console.error('Agent error:', err.message);
});

agent.on('message_sent', (info) => {
  console.log('Message sent:', info.messageId);
});

agent.on('message_failed', (info) => {
  console.error('Message failed:', info.messageId, info.error);
});

See Also ​

Released under the MIT License.

Copyright © 2026 Agenium Team