Multi-Agent Architecture Playbook

Chapter 1: When to Go Multi-Agent

Go multi-agent when you need:

• Parallelism — independent tasks that should run simultaneously
• Specialization — different tasks need different expertise and different permissions
• Isolation — failure in one task shouldn’t affect another
• Audit clarity — clean, attributable trails per agent vs. tangled monolith

Stick with one agent when you only have one use case. Multi-agent adds coordination complexity — only split when the benefit outweighs it.

Chapter 2: Architecture Patterns

Pipeline (sequential): Agent A → Agent B → Agent C. Each agent’s output becomes the next agent’s input. Use when tasks have natural dependencies.

Code Review Agent → Deploy Agent → Notification Agent

Fan-out (parallel): One coordinator spawns multiple workers in parallel, collects results.

PR Trigger → [Security Scanner + Code Reviewer + Docs Checker] → Summary

Hierarchical: A supervisor agent delegates to specialists based on context.

Research Coordinator → [Data Gatherer + Analysis Agent + Report Writer]

Chapter 3: Per-Agent Isolation

Every agent needs its own identity and policy. Never share identities between agents.

Same project, different agents:

# Project: acme-webapp

agent: code-reviewer
policies:
  - git:read on repos/acme-webapp
  - git:comment on repos/acme-webapp/pull-requests/*

---
agent: deployer
policies:
  - git:push on repos/acme-webapp/branches/feature/*
  - aws:ecs:UpdateService on arn:aws:ecs:*:*:service/staging-acme-*

Separate projects when you need hard isolation — agents in different projects cannot see each other’s resources, sessions, or audit trails.

Chapter 4: Agent-to-Agent Messaging

Sentrely provides A2A messaging so agents coordinate without manual intervention:

# Agent A sends a message to Agent B
curl -X POST $GATEWAY_URL/a2a/send \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -d '{
    "to": "deployer",
    "type": "pipeline_stage_complete",
    "payload": {"stage": "code_review", "result": "passed", "pr": 142}
  }'

A2A messages are logged in the audit trail. Control which agents can message which via policy:

agent: code-reviewer
policies:
  - a2a:send to deployer
  - a2a:send to notification-bot
  # Cannot message: support-bot, security-auditor

Chapter 5: Fleet Monitoring

With multiple agents you need a fleet-level view. Sentrely dashboard shows:

• Agent Status — Active, idle, or failed sessions in real-time
• Resource Usage — Token consumption per agent with trend lines
• Audit Timeline — Unified view of all agent actions, filterable
• Alert Feed — Denied requests, budget warnings, approval requests

Set up a daily digest: total sessions, total tokens (with cost), approval outcomes, denied requests, errors.

Chapter 6: Cost at Scale

Set budgets at three levels:

budget:
  per_session: 100000 tokens          # Catches runaway sessions
  per_agent_per_day: 500000 tokens    # Catches over-active agents
  per_project_per_month: $500         # Catches aggregate creep

Cost attribution identifies which agents cost most. Often, one or two agents account for 80% of total spend — focus optimization there.

Chapter 7: Common Mistakes

Starting with too many agents — Begin with one, get governance right, add a second, stabilize, then expand.

Shared credentials — Every agent needs its own identity. Shared credentials make audit trails useless.

No communication boundaries — Define the communication graph explicitly. Not every agent should be able to message every other.

No kill switch — You need to stop any agent immediately. Test the session termination function before you need it.

One big policy — Each agent gets its own policy. When you read a policy, you should understand exactly what that one agent can do.