AGENIUM

Appearance

Configuration ​

Complete reference for configuring AGENIUM agents.

Overview ​

AGENIUM can be configured via:

  1. Constructor options (programmatic)
  2. Environment variables
  3. Global configuration API

Agent Configuration ​

Basic Configuration ​

typescript
import { createAgent } from 'agenium';

const agent = createAgent('myagent', {
  // Core
  persistence: true,
  dataDir: './data',
  listenPort: 8443,
  
  // DNS
  dnsServer: '185.204.169.26',
  
  // Timeouts (flat structure)
  connectionTimeoutMs: 10_000,
  requestTimeoutMs: 30_000,
  
  // Capabilities
  capabilities: ['messaging', 'streaming']
});

Full Configuration ​

typescript
const agent = createAgent('myagent', {
  // === Core Settings ===
  agentName: 'myagent',
  persistence: true,
  dataDir: './data',
  listenPort: 8443,
  historyDepth: 100,
  
  // === DNS Settings ===
  dnsServer: '185.204.169.26',
  bugReportServer: 'https://bugs.agenium.local',
  
  // === Timeouts (flat) ===
  connectionTimeoutMs: 10_000,   // Connection timeout
  requestTimeoutMs: 30_000,      // Request/response timeout
  
  // === Capabilities ===
  capabilities: [
    'messaging',
    'streaming',
    'file-transfer'
  ]
});

Configuration Options ​

Core Settings ​

persistence ​

  • Type: boolean
  • Default: true
  • Description: Enable SQLite persistence for sessions and outbox
typescript
persistence: true  // Recommended for production

dataDir ​

  • Type: string
  • Default: './data'
  • Description: Directory for SQLite databases and keys
typescript
dataDir: '/var/lib/agenium'

Supports tilde expansion:

typescript
dataDir: '~/.agenium/data'  // Expands to /home/user/.agenium/data

listenPort ​

  • Type: number
  • Default: 8443
  • Description: Port for incoming connections
typescript
listenPort: 8443  // Standard HTTPS alternate port

DNS Settings ​

dnsServer ​

  • Type: string
  • Default: '185.204.169.26'
  • Description: DNS server address for agent resolution (port 3000, HTTP)
typescript
dnsServer: '185.204.169.26'

Capabilities ​

capabilities ​

  • Type: string[]
  • Default: ['messaging']
  • Description: Features supported by this agent
typescript
capabilities: [
  'messaging',      // Request/response messaging
  'streaming',      // Server-sent events
  'file-transfer',  // Binary file transfer
  'pubsub',         // Publish/subscribe
  'rpc'             // Remote procedure calls
]

Standard capabilities:

  • messaging - Basic request/response
  • streaming - Real-time event streams
  • file-transfer - Binary uploads/downloads
  • pubsub - Topic-based messaging
  • rpc - Remote procedure calls

Custom capabilities:

typescript
capabilities: ['messaging', 'custom:weather-api']

Timeout Configuration ​

connectionTimeoutMs ​

  • Type: number
  • Default: 10000 (10 seconds)
  • Description: Connection timeout (includes DNS resolution and TLS handshake)
typescript
connectionTimeoutMs: 10_000  // 10 seconds

requestTimeoutMs ​

  • Type: number
  • Default: 30000 (30 seconds)
  • Description: Request/response timeout
typescript
requestTimeoutMs: 60_000  // 60 seconds for long-running requests

Other Configuration Options ​

historyDepth ​

  • Type: number
  • Default: 100
  • Description: Session history depth for tracking
typescript
historyDepth: 200  // Track more history

bugReportServer ​

  • Type: string
  • Default: 'https://bugs.agenium.local'
  • Description: Bug report server URL
typescript
bugReportServer: 'https://my-bug-server.com/api/reports'

Global Configuration ​

AGENIUM also provides a separate global configuration system (distinct from AgentConfig) for advanced tuning of timeouts, connection pooling, and circuit breakers.

Setting Global Config ​

typescript
import { setConfig } from 'agenium';

setConfig({
  timeouts: {
    dnsLookupMs: 10_000,
    handshakeMs: 10_000,
    requestMs: 60_000,  // 60 seconds for all agents
    connectionIdleMs: 60_000,
    bugReportUploadMs: 5_000
  },
  pool: {
    maxConnectionsPerAgent: 8,
    maxStreamsPerConnection: 200
  },
  circuitBreaker: {
    failureThreshold: 3,
    resetTimeoutMs: 60_000,
    successThreshold: 2
  }
});

Getting Global Config ​

typescript
import { getConfig } from 'agenium';

const config = getConfig();
console.log('Request timeout:', config.timeouts.requestMs);

Default Configuration ​

typescript
import { DEFAULT_CONFIG } from 'agenium';

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

Environment Variables ​

Override global configuration via environment variables (note: these affect the global config, not per-agent config):

AGENIUM_DNS_TIMEOUT_MS ​

DNS lookup timeout:

bash
export AGENIUM_DNS_TIMEOUT_MS=5000

AGENIUM_HANDSHAKE_TIMEOUT_MS ​

TLS handshake timeout:

bash
export AGENIUM_HANDSHAKE_TIMEOUT_MS=15000

AGENIUM_REQUEST_TIMEOUT_MS ​

Request/response timeout:

bash
export AGENIUM_REQUEST_TIMEOUT_MS=60000

AGENIUM_MAX_CONNECTIONS_PER_AGENT ​

Connection pool size:

bash
export AGENIUM_MAX_CONNECTIONS_PER_AGENT=8

AGENIUM_CIRCUIT_BREAKER_THRESHOLD ​

Circuit breaker failure threshold:

bash
export AGENIUM_CIRCUIT_BREAKER_THRESHOLD=3

Configuration Patterns ​

Development ​

typescript
const agent = createAgent('dev-agent', {
  persistence: false,  // In-memory only
  dataDir: '/tmp/agenium',
  requestTimeoutMs: 5000  // Short timeout
});

Production ​

typescript
const agent = createAgent('prod-agent', {
  persistence: true,
  dataDir: '/var/lib/agenium',
  requestTimeoutMs: 60_000,
  connectionTimeoutMs: 15_000,
  historyDepth: 200
});

Custom DNS Server ​

typescript
const agent = createAgent('custom-dns', {
  dnsServer: 'custom-dns.example.com',
  persistence: true
});

Long-Running Operations ​

typescript
const agent = createAgent('long-ops', {
  requestTimeoutMs: 300_000,  // 5 minutes
  connectionTimeoutMs: 30_000
});

Database Configuration ​

SQLite Settings ​

AGENIUM uses SQLite for persistence. Database files are stored in dataDir:

{dataDir}/
  ├── alice/
  │   ├── sessions.db        # Session state
  │   ├── outbox.db          # Outbox messages
  │   └── processed.db       # Deduplication cache

Database Options ​

Databases use these settings:

  • WAL mode - Write-Ahead Logging for better concurrency
  • Synchronous NORMAL - Balance between safety and speed
  • Foreign keys ON - Referential integrity

Custom Database Location ​

typescript
const agent = createAgent('myagent', {
  dataDir: '/var/lib/agenium/data'
});

Security Configuration ​

TLS Certificates ​

AGENIUM automatically generates:

  • Self-signed CA certificate
  • Agent certificate (signed by CA)
  • Ed25519 key pairs

Certificates are stored in {dataDir}/{agentName}/:

alice/
  ├── agent-signing-key.pem
  ├── agent-signing-key.pub
  ├── tls-key.pem
  ├── tls-key.pub
  ├── ca-cert.pem
  ├── ca-key.pem
  └── agent-cert.pem

Custom Certificates ​

For advanced use cases, provide your own:

typescript
import { initializeKeys, initializeCA, createAgentCert } from 'agenium';

const keys = initializeKeys('./custom-keys');
const ca = initializeCA('myagent', './custom-ca');
const cert = createAgentCert('myagent', keys.tlsKeys.publicKey, ca);

Performance Tuning ​

Memory Usage ​

Control memory usage:

typescript
// Lower memory footprint - use global config
import { setConfig } from 'agenium';

setConfig({
  pool: {
    maxConnectionsPerAgent: 2,
    maxStreamsPerConnection: 50
  }
});

const agent = createAgent('low-memory', {
  historyDepth: 50  // Smaller history
});

Latency Optimization ​

Minimize latency:

typescript
// Use global config for connection pooling
setConfig({
  timeouts: {
    connectionIdleMs: 3600_000  // Keep connections alive 1 hour
  },
  pool: {
    maxConnectionsPerAgent: 8  // More connections = less queuing
  }
});

const agent = createAgent('low-latency', {
  connectionTimeoutMs: 5_000,  // Fast timeout
  requestTimeoutMs: 10_000
});

Throughput Optimization ​

Maximize throughput:

typescript
setConfig({
  pool: {
    maxConnectionsPerAgent: 16,
    maxStreamsPerConnection: 200
  }
});

Monitoring Configuration ​

Prometheus Metrics ​

Expose metrics endpoint:

typescript
import { MetricsServer } from 'agenium';

const metricsServer = new MetricsServer({
  port: 9090,
  host: '0.0.0.0'
});

await metricsServer.start();

Access metrics at http://localhost:9090/metrics.

Health Checks ​

Enable health endpoint:

typescript
// Health check automatically available at GET /health
// Returns:
// {
//   "agent": "myagent",
//   "status": "ok",
//   "uptime": 12345
// }

Best Practices ​

1. Use Persistence in Production ​

typescript
// ✅ Recommended
persistence: true

// ❌ Only for testing
persistence: false

2. Set Reasonable Timeouts ​

typescript
// ✅ Good
requestTimeoutMs: 30_000  // 30 seconds

// ❌ Too short
requestTimeoutMs: 1_000  // 1 second

3. Configure Global Settings Separately ​

typescript
// ✅ Use global config for pool and circuit breaker tuning
import { setConfig } from 'agenium';

setConfig({
  pool: { maxConnectionsPerAgent: 8 },
  circuitBreaker: { failureThreshold: 5 }
});

// Agent config focuses on agent-specific settings
const agent = createAgent('myagent', {
  persistence: true,
  dataDir: './data',
  requestTimeoutMs: 30_000
});

4. Monitor Agent Statistics ​

typescript
setInterval(() => {
  const stats = agent.getStats();
  console.log('Sessions:', stats.sessions);
  console.log('Connections:', stats.connections);
}, 60_000);

See Also ​

Released under the MIT License.

Copyright © 2026 Agenium Team