Building CVCrew — a career copilot where multiple Claude agents work together — taught me a lot about multi-agent architecture. Here are the lessons that mattered most.
Specialist agents instead of one giant prompt
The first attempt was the classic one: a single assistant that knows everything. The result was an assistant that does everything averagely. The turning point was splitting the work into single-responsibility agents — one analyzes the CV, one matches it against the listing, one generates content. Each agent's system prompt is short, sharp and single-topic:
const agents = {
analyzer: { system: "Convert the CV into structured data. No commentary." },
matcher: { system: "Match CV data against listing requirements, list the gaps." },
writer: { system: "Generate application content from the match report." },
};The quality difference shows immediately: a narrow agent is consistent at a narrow job.
Orchestration is its own layer
The decision of who calls which agent, in what order, with what data should not be left to the agents themselves. The orchestration layer — plain code that validates agent output, pipes it to the next agent, retries on failure — is the real backbone of the system. LLM flexibility lives inside the agents; flow control stays in deterministic code.
Streaming is non-negotiable
A three-agent chain can take 30-60 seconds. Show the user an empty spinner and the product feels broken; stream each agent's intermediate output over WebSocket and the same duration turns into "it's working, I'm watching". Perceived speed matters more than actual speed.
Takeaways
- Agent boundaries beat prompt instructions: instead of telling an agent what not to do, don't give it that capability at all.
- Validate intermediate outputs with schemas: schema-check every piece of data that changes hands between agents; failures get caught at the start of the chain.
- Observability from day one: debugging a multi-agent system without logging which agent produced what is close to impossible.