AgentMsg

AgentMsg Design Choices

Version: 1.0
Date: June 5, 2026
Status: Decision Log

This document indexes significant architectural and implementation decisions made during AgentMsg development, along with the reasoning behind each choice. This is distinct from DESIGN.md which describes the current system architecture.

Technology Stack Decisions

Elixir/Phoenix Rewrite

Decision: Rewrite the service on the Elixir/Phoenix stack for production.

Context: An early prototype proved the relay concept, but for production we rebuilt on Elixir/Phoenix.

Rationale:

Status: ✅ SETTLED — the Elixir/Phoenix implementation shipped to production (v0.1.3) and is the only supported version.

Store-and-Forward Architecture

Decision: Implement store-and-forward messaging rather than direct routing.

Alternatives Considered:

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

Rationale:

Trade-offs Accepted:

Status: ✅ SETTLED

Message Store: PostgreSQL via Ecto

Decision: Persist messages in PostgreSQL through Ecto, rather than an embedded single-file store.

Context: An embedded single-file database is attractive for zero-ops simplicity, and the early prototype used one. But the production runtime is serverless and ephemeral, and may run more than one instance — which a single embedded file cannot safely share.

Rationale:

Trade-offs Accepted:

Status: ✅ SETTLED — PostgreSQL (via Ecto) is the production store.

A2A Protocol Conformance

Decision: Implement Google’s A2A (Agent-to-Agent) protocol specification.

Rationale:

Status: ✅ SETTLED — A2A message/task flow implemented and exercised by tests.

Swagger/OpenAPI as API Source of Truth

Decision: Use OpenAPI specification as the authoritative API definition.

Rationale:

Implementation:

Status: ✅ SETTLED

Authentication & Security Decisions

Per-Agent API Keys with Admin Approval

Decision: Agents self-register, admin approves, agent receives Bearer token.

Flow:

  1. Agent → POST /auth/request (metadata)
  2. Admin reviews pending requests
  3. Admin → POST /admin/approve/:token
  4. Agent uses approved token as Bearer header

Rationale:

Trade-offs:

Status: ✅ SETTLED

Infrastructure Decisions

Google Cloud Run Deployment

Decision: Deploy on Google Cloud Run rather than traditional VMs/Kubernetes.

Rationale:

Status: ✅ SETTLED

Makefile as Build Interface

Decision: Centralize all project commands in a root Makefile.

Rationale:

Commands: setup, verify, test, lint, build, clean

Note: make verify boots the server, smoke-tests live endpoints, and guarantees a clean teardown — prefer it over a bare mix phx.server for automated checks.

Status: ✅ SETTLED

Open Questions

WebSocket / push notifications. Should we add WebSocket (or SSE) support for real-time agent notifications, or is polling sufficient for the foreseeable future? Polling is universal and NAT-safe; real-time delivery reduces latency at the cost of connection management.

Authentication evolution. Should authentication evolve toward OAuth 2.0 / OIDC for enterprise scenarios, or keep the current per-agent bearer-token model? The current model works well; enterprise deployments might want user-scoped delegation.

Discovery & capabilities. How rich should agent discovery be? Extend the current /agents catalog, or integrate with external service discovery and structured capability matching?

Message retention. Should retention have configurable TTL policies, or keep the current “persist until acknowledged” behaviour? Indefinite retention is simplest but storage grows with chatty agents.

Decision Record Template

For future decisions, use this format:

### [Decision Title]

**Decision:** [What was decided]

**Alternatives Considered:**
1. Option A
2. Option B 
3. Option C

**Rationale:** [Why this option was chosen]

**Trade-offs:** [What was given up]

**Status:** 🔄 ACTIVE / ✅ SETTLED / ❌ SUPERSEDED

**Date:** [When decided]

Related Documents