System Architecture

AGENIUM is a modular system with clear separation of concerns.

High-Level Overview

┌─────────────────────────────────────────────────┐
│                   Your Agent                     │
│                                                  │
│  ┌─────────┐  ┌──────────┐  ┌───────────────┐  │
│  │  CLI    │  │ Agent API │  │  Your Logic   │  │
│  └────┬────┘  └─────┬─────┘  └───────┬───────┘  │
│       └─────────────┼────────────────┘           │
│                     ▼                            │
│  ┌──────────────────────────────────────────┐   │
│  │              AGENIUM Core                 │   │
│  │                                           │   │
│  │  ┌─────────┐ ┌──────────┐ ┌───────────┐ │   │
│  │  │  DNS    │ │Transport │ │ Sessions  │ │   │
│  │  │Resolver │ │ HTTP/2   │ │  SQLite   │ │   │
│  │  └────┬────┘ └─────┬────┘ └─────┬─────┘ │   │
│  │       │            │            │         │   │
│  │  ┌────┴────┐ ┌─────┴────┐ ┌────┴──────┐ │   │
│  │  │ Crypto  │ │ Circuit  │ │  Outbox   │ │   │
│  │  │  mTLS   │ │ Breaker  │ │  Pattern  │ │   │
│  │  └─────────┘ └──────────┘ └───────────┘ │   │
│  └──────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘
         │                          │
         ▼                          ▼
┌──────────────────┐    ┌───────────────────────┐
│  Marketplace DNS │    │    Remote Agents       │
│  (Resolution)    │    │  agent://search        │
│                  │    │  agent://weather        │
└──────────────────┘    └───────────────────────┘

Component Breakdown

DNS Resolver

Resolves agent://name URIs to network endpoints.

agent://search  →  DNS Resolver  →  https://130.185.123.247:8443

• Queries the marketplace DNS bridge service
• Caches results locally
• Falls back gracefully on resolution failure

Transport Layer

HTTP/2 with mutual TLS (mTLS) for secure agent-to-agent communication.

• HTTP/2 multiplexing — Multiple streams over a single connection
• mTLS — Both sides present certificates
• Connection pooling — Reuse connections across requests
• Automatic retries — Configurable retry policy

Session Manager

SQLite-backed persistent sessions with deduplication.

sessions.db
├── Active sessions (agent URI, state, metadata)
├── Message history (sent/received)
└── Deduplication cache (message IDs)

Outbox Pattern

At-least-once delivery guarantee via the outbox pattern:

1. Message written to outbox (SQLite)
2. Background worker sends message
3. On success, message removed from outbox
4. On failure, retried with backoff

Crypto Module

• Ed25519 key pairs for signing
• X.509 certificates for TLS
• Self-signed CA per agent
• Automatic key generation on first run

Circuit Breaker

Prevents cascading failures:

CLOSED  ──[failures > threshold]──►  OPEN
   ▲                                   │
   │                              [timeout]
   │                                   ▼
   └──[successes > threshold]──  HALF-OPEN

Metrics

Prometheus-compatible metrics:

Metric	Type	Description
agenium_messages_sent_total	Counter	Total messages sent
agenium_messages_received_total	Counter	Total messages received
agenium_dns_lookups_total	Counter	DNS resolution attempts
agenium_active_sessions	Gauge	Current active sessions
agenium_circuit_breaker_state	Gauge	Circuit breaker state (0/1/2)

Data Flow

Sending a Message

1. agent.send('agent://target', message)
2. │
3. ├── DNS Resolution: agent://target → endpoint
4. │   └── Cache hit? Return cached. Miss? Query marketplace.
5. │
6. ├── Session Lookup: existing session? Create new?
7. │   └── SQLite: SELECT FROM sessions WHERE agent_uri = ?
8. │
9. ├── Outbox Write: persist message for delivery guarantee
10.│   └── SQLite: INSERT INTO outbox (message, target, ...)
11.│
12.├── Transport: HTTP/2 POST to endpoint
13.│   ├── mTLS handshake (first connection)
14.│   ├── Connection pool (reuse existing)
15.│   └── Circuit breaker check
16.│
17.├── Response: process reply
18.│   └── Remove from outbox on success
19.│
20.└── Return result to caller

Receiving a Message

1. Incoming HTTP/2 request on listenPort
2. │
3. ├── mTLS verification: validate client certificate
4. │
5. ├── Session lookup/create
6. │   └── SQLite: UPSERT sessions
7. │
8. ├── Deduplication check
9. │   └── SQLite: SELECT FROM processed WHERE message_id = ?
10.│
11.├── Deliver to message handler
12.│
13.└── Send response

Directory Structure

agenium/
├── src/
│   ├── index.ts          # Public API exports
│   ├── agent.ts          # Main agent class
│   ├── cli.ts            # CLI entry point
│   ├── config.ts         # Configuration management
│   ├── shutdown.ts       # Graceful shutdown
│   ├── core/             # Core logic
│   ├── crypto/           # Key generation, certificates
│   ├── dns/              # DNS resolver
│   ├── metrics/          # Prometheus metrics
│   ├── persistence/      # SQLite session/outbox storage
│   ├── protocol/         # A2A protocol implementation
│   ├── state/            # Agent state machine
│   └── transport/        # HTTP/2 + mTLS transport
├── tests/
│   ├── unit/             # 22 unit tests
│   ├── bug-server/       # 24 integration tests
│   └── e2e/              # 10 end-to-end tests
└── data/                 # Runtime data (SQLite, keys)

Infrastructure

Marketplace (Registration & DNS)

marketplace.agenium.net (194.5.206.148) — Domain Registration
├── api-gateway          # REST API
├── domain-service       # Domain registration
├── dns-bridge-service   # DNS resolution for agents
├── user-service         # User management
├── billing-service      # TON payments
├── frontend             # Telegram Mini App
├── postgres             # Primary database
├── redis                # Caching layer
└── nginx                # Reverse proxy + SSL

Search Engine

search.agenium.net (130.185.123.247)
├── search-api           # OpenSearch-powered agent discovery
└── opensearch           # Full-text + vector search

Security Model

Layer	Mechanism
Identity	Ed25519 key pairs + X.509 certificates
Transport	HTTP/2 + mTLS (mutual authentication)
DNS	HMAC-SHA256 signed API requests
API Keys	dom_<64 hex> format with replay protection
Database	localhost-only binding, no external access

See Also

• Transport Layer — HTTP/2 + mTLS details
• Sessions — Session persistence
• Configuration — Tuning parameters