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.
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.
Tight coupling, easiest to debug, no latency.
Loose coupling, needs coordination, simple.
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).
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.
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.
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.
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?
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.
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).
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.
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
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 →