Agent Architecture
Advanced 13 min read Agent Architecture

Multi-Agent Systems

Crews, contracts, and boundaries

Multiple agents with distinct roles, permissions and communication topology. Multi-agent design multiplies focus — and failure surfaces. Contracts between agents and a shared task log keep the crew coherent.

multi-agentrolescontractstopologyshared statenegotiation
Prerequisites: Orchestration
Before we start

What you will learn

  • Design role-separated agents
  • Define inter-agent contracts
  • Manage shared state and task coordination
Introduction

What is this?

A multi-agent system runs several agent roles (researcher, reviewer, executor) with distinct prompts, tools and permissions, coordinated by contracts — a message format either side must honor — and shared state such as a task log. It focuses specialization while introducing coordination and security surface that must be designed explicitly.

Motivation

Why do you need it?

  • Roles with scoped tools raise per-stage quality and safety.
  • Separation enables parallel work and independent evals.
  • Contracts make inter-agent boundaries testable.
  • Code review loops (writer vs reviewer) materially improve outputs.
Think about it

Mental model

Imagine

A newsroom

Think of

Multi-agent

Reporter (research), sub-editor (compliance/length), copy desk (style), editor (final call). Each has distinct desks, tools and rules; copy moves with an explicit handoff sheet (contract); the editor arbitrates conflicts. The newsroom works because roles and handoffs are defined, not because everyone chats freely.

Mechanics

How it works

  • Choose roles that map to distinct work + distinct tools.
  • Define the handoff contract (message shape, attachments).
  • Establish shared task log / blackboard for coordination.
  • Set permissions per role; govern shared resources.
  • Run a coordinator for merge, arbitration, and final gates.

Role topology.

Coordinator
Researcher
Reviewer
Executor
Log
Real world

In production

  • Writer→reviewer→gate loops for customer-facing copy.
  • Research supervisor+specialists across sources.
  • Incident response: observer + actioner + notifier roles.
Guidelines

Best practices

  • Fewer, sharper roles beat a crowd of vague ones.
  • Define contracts before wiring agents.
  • Share a task log so no two agents do the same work.
  • Eval each role independently AND the end-to-end crew.
Watch out

Common mistakes

  • Agents stepping on each other's tools or writes.
  • Contractless chats 'that seem to work in demos'.
  • Unevaluated roles hidden behind a good final output.
Root cause analysis

Common issues

Error
Inter-agent info loss
Root cause

Handoff summaries too thin

Fix

Contract carries required context; verify at accept.

Error
Permission creep across roles
Root cause

Scoped tools not enforced

Fix

Give each role its own tool set; default-deny.

When things break

Debugging tips

  • Task log shows duplicate work → ownership rules missing; assign scope.
  • Handoff garbled → contract not enforced; validate payloads at the boundary.
  • One agent blocked forever → its input edge lacks timeout/error handling.
Interviews

Interview checkpoint

Test yourself

Quick quiz

0/2
1

Inter-agent handoffs should be…

2

Roles should share one unrestricted tool set.

Go deeper

Official documentation

Multi-agent workflows (LangGraph)
docs