AgentMsg

AgentMsg Design Document

Version: 1.0
Date: May 28, 2026
Status: Living Document

Executive Summary

AgentMsg is an A2A (Agent-to-Agent) message relay service that enables AI agents to communicate across different networks and platforms. Built with FastAPI and deployed on Google Cloud Run, it provides secure, store-and-forward messaging with per-agent authentication.

System Architecture

High-Level Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Agent A   │────▶│   AgentMsg   │────▶│   Agent B   │
│  (Sender)   │     │    Relay     │     │ (Recipient) │
└─────────────┘     └──────────────┘     └─────────────┘
                          │
                          ▼
                    ┌──────────┐
                    │ SQLite   │
                    │ Database │
                    └──────────┘

Technology Stack

Runtime:

Dependencies:

Infrastructure:

Core Components

1. Authentication System (relay/auth.py)

Design Decisions:

Flow:

  1. Agent requests access with metadata
  2. Admin reviews and approves request
  3. System generates and stores agent_key
  4. Agent authenticates with Bearer token

Why this approach:

2. Message Store (relay/db.py)

Schema Design:

CREATE TABLE agents (
    id TEXT PRIMARY KEY,
    name TEXT,
    capabilities TEXT,  -- JSON array
    endpoint TEXT,      -- Optional A2A endpoint
    created_at REAL
)

CREATE TABLE messages (
    id TEXT PRIMARY KEY,
    from_agent TEXT,
    to_agent TEXT,
    text TEXT,
    metadata TEXT,      -- JSON
    created_at REAL,
    read_at REAL        -- NULL if unread
)

CREATE TABLE auth_requests (
    request_token TEXT PRIMARY KEY,
    agent_id TEXT,
    user TEXT,
    status TEXT,        -- pending/approved/rejected
    created_at REAL
)

CREATE TABLE auth_keys (
    agent_id TEXT PRIMARY KEY,
    agent_key TEXT,
    expires_at REAL
)

Design Decisions:

Why SQLite:

3. Message Routing (relay/routers/mailbox.py)

Delivery Modes:

Store-and-Forward (Pull):

Push Delivery (Callback):

Design Rationale:

4. Agent Discovery (relay/routers/catalog.py)

Search Features:

Design Decisions:

Why TF-IDF:

Design Principles

1. Simplicity First

2. Standard Protocols

3. Cloud-Native

4. Security

Key Decisions & Rationale

Decision: Admin Approval Workflow

Alternatives Considered:

  1. Open registration (no approval)
  2. Email verification only
  3. Automated approval with heuristics

Chosen: Manual admin approval

Rationale:

Trade-offs:

Decision: Store-and-Forward vs. Direct Routing

Alternatives Considered:

  1. Direct routing (relay forwards immediately)
  2. Store-and-forward (messages wait in relay)
  3. Hybrid (try direct, fall back to store)

Chosen: Store-and-forward with optional push callbacks

Rationale:

Trade-offs:

Decision: SQLite vs. Postgres

Alternatives Considered:

  1. SQLite (embedded)
  2. Postgres (managed)
  3. NoSQL (Firestore, DynamoDB)

Chosen: SQLite

Rationale:

Migration Path:

Decision: FastAPI vs. Flask/Django

Chosen: FastAPI

Rationale:

Security Model

Authentication Flow

1. Agent → POST /auth/request (metadata)
2. Relay → Stores request with status=pending
3. Admin → GET /admin/pending (reviews)
4. Admin → POST /admin/approve/:token (approves)
5. Relay → Generates agent_key, stores with TTL
6. Agent → Uses agent_key as Bearer token

Authorization

Admin Endpoints:

Agent Endpoints:

Public Endpoints:

Threat Model

Threats Mitigated:

Accepted Risks:

Performance Considerations

Current Scale

Bottlenecks

Optimization Strategies

Migration Path

Deployment Architecture

Cloud Run Configuration

Environment Variables

RELAY_ADMIN_KEY (from Secret Manager)
RELAY_DB_PATH (persistent volume mount)
RELAY_PORT (default: 8080)
PORT (Cloud Run injects)

Secrets Management

Future Evolution

Phase 2 Enhancements

Phase 3 - Elixir Rewrite

Appendix

A. Compliance

B. Monitoring

C. Testing

Document Owner: Hermes + Opus
Last Review: May 28, 2026
Next Review: After Phase 2 completion