Agents need contracts, just like APIs

You're building a 3-agent system: a Researcher gathers facts, a Writer composes a description, an Editor polishes it. How does the Researcher tell the Writer what it found? It can't just pass a string. The Writer needs to know if there are missing fields. The Editor needs to know what was revised.

This is why microservices have API contracts. Agents need the same thing.

🏪
Real-world scenario
Jumia Kenya: automated product descriptions for 50,000 SKUs

Every day, Jumia Kenya receives hundreds of new products. Each needs a description for the marketplace. Jumia builds a 3-agent pipeline:

  • Researcher agent: looks up the product specs, price, availability.
  • Writer agent: composes a 100-word description for customers.
  • Editor agent: checks for brand guidelines, tone, correctness.

Without message contracts, the Writer doesn't know which fields are guaranteed from the Researcher. It might write "Price: $X" when the Researcher couldn't find the price. The Editor has no way to report which sentences it changed or why.

With typed messages, each agent knows exactly what it receives and sends. The pipeline is bulletproof.

Three message-passing patterns

All multi-agent systems use one of three patterns. Each trades off coupling, simplicity, and scalability.

Direct Calls
Agent A calls Agent B synchronously

Tight coupling, easiest to debug, no latency.

Shared Blackboard
Agents read/write a shared dict or Redis

Loose coupling, needs coordination, simple.

Pub/Sub or Queue
Producer agent sends message to broker; consumer picks it up

Fully decoupled, async, scales, complex broker setup.

Pydantic message types: the envelope pattern

Every message between agents is a Pydantic model. Think of it as a typed envelope. The envelope says who sent it, what it contains, and what went wrong (if anything).

message_types.py Define agent messages as Pydantic models
Why Pydantic?
Each field is documented. The LLM can read descriptions. When an agent receives a message, Pydantic validates every field. If validation fails, you know exactly what went wrong—no silent bugs.

Pattern 1: Direct calls—simple, tightly coupled

Agent A calls Agent B's function synchronously. Agent B returns a result. This is the simplest pattern: good for small pipelines where latency doesn't matter.

direct_calls.py Agent-to-agent calls in sequence

Pros and cons:

  • Pro: Simplest to debug. Stack traces show exactly where errors occur.
  • Pro: No infrastructure needed. No message broker, no database.
  • Con: If Writer fails, the Researcher is blocked waiting for its response.
  • Con: Hard to retry individual agents; you often restart the whole pipeline.

Pattern 2: Shared blackboard—loose coupling, simple coordination

All agents read and write to a shared dictionary or Redis. Agent A writes its result to a key; Agent B reads it. No direct calls. Agents don't know about each other.

blackboard_pattern.py Agents coordinate via shared dict

Pros and cons:

  • Pro: Agents are decoupled. Researcher doesn't call Writer; both just read/write to blackboard.
  • Pro: Easy to add a new agent; it just reads/writes its own stage.
  • Con: Polling (waiting for data) wastes CPU. Need to add event subscriptions or sleep.
  • Con: Hard to guarantee ordering. If Editor runs before Writer finishes, it reads incomplete data.

Pattern 3: Pub/Sub with queues—async, decoupled, production-scale

Agent A publishes a message to a queue or broker. Agent B subscribes and consumes it. Many brokers exist: Python's asyncio.Queue (in-process), RabbitMQ, Redis Streams, AWS SQS. This is the pattern used by production frameworks like CrewAI.

pubsub_pattern.py Async queue-based message passing

Pros and cons:

  • Pro: Fully async. Agents run in parallel. One agent's slowness doesn't block others.
  • Pro: Highly resilient. Dead agents can restart and pick up where they left off.
  • Con: Requires a message broker (queue) to manage. More infrastructure.
  • Con: Harder to debug. Errors happen asynchronously; need good logging.

Error propagation: when agents fail, communicate it

An agent fails: network timeout, LLM refuses, Pydantic validation error. The supervisor needs to know: can we retry, or should we escalate?

error_handling.py Supervisor decides retry vs escalate

When to use frameworks: CrewAI, AutoGen, vs roll-your-own

You can build message passing from scratch (like we've done above) or use a framework. Each trades off control for convenience.

Simple pipeline (2-3 agents)
→
Roll your own
Complex pipeline (5+ agents, loops)
→
CrewAI or AutoGen

Frameworks to know:

  • CrewAI: High-level abstractions for agent teams. Handles message passing, error recovery, parallel execution. Best for business workflows.
  • AutoGen (Microsoft): Multi-agent orchestration with conversation history. Better for chat-based systems where agents iterate.
  • LangChain / LangGraph: Lower-level toolkit. More control, more code. Good for custom orchestration.
  • Roll your own: For education, full control, or when you need custom message types (like Jumia's pipeline).
Pro tip:
Start with direct calls or a simple queue. Only move to a framework once your pipeline has 5+ agents or you need advanced features like agent memory or dynamic routing.

How this connects to real LLM systems

Every multi-agent system in production—from OpenAI's multi-agent orchestrators to enterprise AI pipelines at companies like Jumia and SouthBank India—uses one of these three message-passing patterns. The differences are just implementation details: Ollama vs Claude, asyncio.Queue vs Kafka, direct Python calls vs gRPC. By mastering Pydantic message types and error handling, you've learned the universal language of agent communication.

Multi-Agent Patterns Async/Await Error Recovery Production Orchestration
Mini Challenge: Build a 2-agent message pipeline

Task: Define two Pydantic models: QueryMessage (sent to search agent) and SearchResult (returned). Implement a simple SearchAgent that receives QueryMessage via direct call and returns SearchResult. Then call it from an Orchestrator. No LLM required—hardcode the result.

Hint 1: Define QueryMessage with query (string) field. SearchResult with results (list) and count (int).

Hint 2: SearchAgent.search(message: QueryMessage) → SearchResult.

Hint 3: Orchestrator calls agent.search(query_msg) and receives validated result.

Test your knowledge

Question 1 of 5
Why do agents need message contracts (like Pydantic models)?
Question 2 of 5
What is the main advantage of the direct-calls pattern for agent communication?
Question 3 of 5
In the blackboard pattern, how do agents avoid polling (constantly checking for data)?
Question 4 of 5
Which message-passing pattern is most suitable for a 5+ agent production system with high latency tolerance?
Question 5 of 5
When an agent fails with a timeout error, how should the supervisor respond?
0
/5
Perfect! You understand multi-agent communication patterns.
Africa & India's Best AI Academy
🤖 AI-first 🎓 Placement Assistance

You've wired up agent communication.
Now build the bull vs bear debate.

Join the Best AI Program: The AI-Era Agentic Engineer — 5 months, fully online, with placement assistance. Week 1 is free.

Explore The AI-Era Agentic Engineer →