Core Concepts

Understanding AGENIUM's architecture and design principles.

Overview

AGENIUM is built on five core concepts that work together to enable reliable agent-to-agent communication:

1. agent:// Protocol - Unique agent identity via URI scheme
2. DNS Resolution - Discovery mechanism from name to endpoint
3. Sessions & State - Persistent connection management
4. Transport Layer - HTTP/2 + mTLS secure communication
5. Outbox Pattern - Reliable message delivery

The Big Picture

┌─────────────────────────────────────────────────────────────────┐
│                         AGENIUM Agent                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐    ┌─────────────┐    ┌─────────────┐       │
│  │   Identity   │────│     DNS     │────│   Session   │       │
│  │ agent://name │    │  Resolver   │    │   Manager   │       │
│  └──────────────┘    └─────────────┘    └─────────────┘       │
│                                                                 │
│  ┌──────────────┐    ┌─────────────┐    ┌─────────────┐       │
│  │  Transport   │────│  Protocol   │────│   Outbox    │       │
│  │  HTTP/2+mTLS │    │  Dispatcher │    │  (Reliable) │       │
│  └──────────────┘    └─────────────┘    └─────────────┘       │
│                                                                 │
│  ┌──────────────────────────────────────────────────────┐      │
│  │         Persistence Layer (SQLite)                   │      │
│  │  - Sessions  - Messages  - Deduplication Cache       │      │
│  └──────────────────────────────────────────────────────┘      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Design Principles

1. Identity First

Every agent has a unique URI (agent://name) that serves as:

• Identity: Globally unique identifier
• Discovery: Resolved to endpoint via DNS
• Security: Public key pinning for authentication

2. Stateful by Default

Unlike HTTP's stateless model, AGENIUM maintains persistent sessions:

• Sessions survive restarts (SQLite persistence)
• Automatic reconnection and resume
• Message ordering guarantees within a session

3. Reliable Delivery

Messages are delivered at least once:

• Outbox pattern for guaranteed delivery
• Automatic retries with exponential backoff
• Deduplication to prevent duplicates
• ACK-based confirmation

4. Secure by Design

Security is built-in, not bolted on:

• Mutual TLS (both parties authenticate)
• Ed25519 public key cryptography
• Certificate pinning via DNS
• Encrypted transport (HTTP/2 over TLS)

5. Observable

Built-in observability for production:

• Prometheus metrics export
• Health check endpoints
• Structured logging
• Bug reporting integration

Communication Flow

Here's how a typical agent-to-agent interaction works:

Step 1: Resolution

// Client resolves agent URI to endpoint
const result = await resolver.resolve('agent://bob');
// Returns: { host: '203.0.113.42', port: 8443, publicKey: '...' }

Step 2: Handshake

Alice (client)                    Bob (server)
      │                                 │
      ├─── POST /handshake/init ───────▶│
      │    { agentId, nonce, pubkey }   │
      │                                 │
      │◀── 200 OK ──────────────────────┤
      │    { agentId, challenge, ... }  │
      │                                 │
      ├─── POST /handshake/complete ───▶│
      │    { signature, capabilities }  │
      │                                 │
      │◀── 200 OK ──────────────────────┤
      │    { sessionId }                │

Step 3: Messaging

Alice                             Bob
  │                                 │
  ├─── POST /message ──────────────▶│
  │    REQUEST: greet(name='Alice') │
  │                                 │
  │◀── 200 OK ──────────────────────┤
  │    RESPONSE: { msg: 'Hello!' }  │
  │                                 │
  ├─── POST /message ──────────────▶│
  │    EVENT: status_update         │
  │                                 │
  │◀── 200 OK ──────────────────────┤
  │    ACK: { msgId: '...' }        │

Step 4: Persistence

All session state is persisted to SQLite:

-- sessions table
CREATE TABLE sessions (
  session_id TEXT PRIMARY KEY,
  remote_agent_name TEXT,
  remote_public_key TEXT,
  endpoint TEXT,
  state TEXT,
  capabilities TEXT,
  created_at INTEGER,
  last_seen_at INTEGER
);

-- outbox table (reliable delivery)
CREATE TABLE outbox (
  id INTEGER PRIMARY KEY,
  session_id TEXT,
  message_id TEXT,
  frame_json TEXT,
  created_at INTEGER,
  last_attempt INTEGER,
  retry_count INTEGER,
  state TEXT
);

Error Handling

AGENIUM provides robust error handling:

Circuit Breakers

Automatically detect and recover from failures:

const breaker = new CircuitBreaker({
  failureThreshold: 5,      // Open after 5 failures
  resetTimeoutMs: 30_000,   // Try again after 30s
  successThreshold: 2       // Close after 2 successes
});

// Automatically wraps network calls
const result = await breaker.execute(() => 
  client.request(host, port, { method: 'POST', path: '/message' })
);

States:

• Closed: Normal operation
• Open: Failures exceeded threshold, reject fast
• Half-Open: Testing if service recovered

Retries

Automatic retry with exponential backoff:

{
  retries: 3,
  retryDelayMs: [1000, 2000, 4000]  // 1s, 2s, 4s
}

Deduplication

Prevent duplicate message processing:

// Check if message already processed
if (db.isDuplicate(messageId, sessionId)) {
  return { ok: true, duplicate: true };
}

// Mark as processed
db.markProcessed(messageId, sessionId);

Next Steps

Dive deeper into each concept:

• agent:// Protocol - URI scheme and identity
• DNS Resolution - Discovery and registration
• Sessions & State - Session lifecycle
• Transport Layer - HTTP/2 + mTLS details
• Outbox Pattern - Reliable delivery internals