Agent Architecture

Inter-Agent Protocol

How Claude's specialized agents communicate, delegate tasks, and coordinate work across sessions using files, Matrix chat, and MinIO storage

ai-servicers.com

What is the Protocol?

Five specialized agents work together on infrastructure projects — but they don't run at the same time. They coordinate asynchronously through shared storage and chat.

Think of it like a team of contractors: the PM assigns work by writing a task file, the Architect reads it and writes a design, the Developer reads both and writes deployment notes. Each agent picks up exactly where the previous one left off.

No real-time waiting required. Files persist across sessions. Context is never lost.

The Five Agents

PM

Orchestrator

Receives user requests, breaks them into tasks, assigns work to specialists, and synthesizes the final report.

Architect

System Design

Evaluates technology options, writes Architecture Decision Records (ADRs), and designs service integration.

Security

Network & Auth

Configures Traefik routing, Keycloak OAuth2 clients, Docker networks, and firewall rules.

Developer

Implementation

Writes code, builds Docker images, deploys services, debugs issues, and documents results.

QA

Quality Assurance

Runs tests via GitLab CI, validates deployments, checks service health, and verifies specs are met.

PM lives at ~/.claude/agents/pm.md • Architect, Security, Developer, QA at ~/projects/.claude/agents/

How Agents Communicate

💬

Matrix Chat Rooms

Real-time messaging via aiagentchat. Each agent has its own room. Used for notifications, delegation, and live coordination between sessions.

🪣

MinIO File Sharing

Primary data channel. Artifacts shared via the aichat-files MinIO bucket. Key convention: {agent-name}/filename. 7-day auto-expiry. Browse at alist.ai-servicers.com.

⚡

Escalation Files

Structured escalation requests when a blocker needs input from another specialist. Written to MinIO under the target agent's key prefix.

Delegation Lifecycle

A standard project flows through four sequential phases

PM assigns
Breaks request
into agent tasks
via Matrix chat
Architect designs
Reads PM task,
writes architecture
decisions
Security configures
Reads ADR,
writes Traefik +
Keycloak configs
Developer implements
Reads all specs,
deploys + documents,
notifies PM
QA validates
Runs tests via
GitLab CI, verifies
deployment health

MinIO Artifact Sharing

Agents share files through the aichat-files MinIO bucket using key prefix convention: {agent-name}/project/filename. Browse artifacts at alist.ai-servicers.com/aichat-files/. 7-day auto-expiry.

MinIO File Sharing Structure

aichat-files bucket (MinIO)
├── pm/
│ ├── {project}/   # Task breakdowns + per-agent assignments
│ └── reports/   # Progress summaries
├── architect/
│ └── {project}/
│ ├── architecture.md  # ADR
│ └── design.md        # Design spec
├── security/
│ └── {project}/
│ ├── traefik.md      # Routing rules
│ └── keycloak.md     # OAuth2 setup
├── developer/
│ └── {project}/
│ ├── deployment.md   # Deploy log
│ └── debug-{issue}.md  # Debug notes
├── qa/
│ └── {project}/
│ └── test-results.md  # CI test output
Browse: alist.ai-servicers.com/aichat-files/ • 7-day expiry

Async by Design

Asynchronous communication via Matrix and MinIO means agents never need to run simultaneously. Context persists across sessions. Any agent can pick up exactly where another left off.

Clear ownership — each agent owns its workspace directories.
Explicit handoffs — always state what's done and what's needed next.
Escalate early — don't work around design gaps; write an escalation file.

PM — orchestrates Architect — designs Security — configures Developer — builds QA — validates

Inter-Agent Protocol • ai-servicers.com