This article was originally published on[BuildZn].
Everyone talks about multi-agent systems but few show you how to actually coordinate them without a ton of boilerplate and deadlocks. I spent weeks trying to get agents to talk, especially when building something like FarahGPT's multi-agent trading system, often hitting insane latency. Turns out, qm
can drastically simplify this, and this qm multiplayer AI agent tutorial
will show you how to cut task completion times by 20% using a specific Node.js workflow.
qm
Helps) Single LLM calls hit a wall, fast. You get generic answers, struggle with complex, multi-step tasks, and prompt engineering becomes a full-time job. I've built 9-agent YouTube automation pipelines and an AI gold trading system that needed to analyze market data, news sentiment, and historical trends concurrently. Trying to jam all that into one prompt for a single agent? Forget about it. You need a collaborative AI agent architecture.
That's where multi-agent systems shine. You break down complex problems into smaller, manageable tasks, assign them to specialized agents, and have them work together. Think of it like a dev team: one person focuses on backend, another on frontend, another on CI/CD. This is how you handle real-world complexity, and it's how I scaled FarahGPT to 5,100+ users.
The challenge? Orchestration. How do these agents communicate? Who manages their state? How do you ensure they don't step on each other's toes or get stuck waiting for slow upstream tasks? This is exactly where qm
, a lightweight agent harness, becomes a game-changer for building AI teams. It gives you the primitives to define agents, tasks, and workflows without drowning in custom event loops.
qm
Most qm
examples show simple agent interactions. Agent A asks Agent B. Done. But what if Agent A needs to delegate a task that itself needs parallel sub-tasks, and then aggregate the results? This is the pattern that drove the 20% latency reduction I saw in my systems. It’s not just about one agent talking to another; it's about a primary agent acting as a coordinator, breaking down work, and efficiently distributing it.
Here's the thing — the qm
library, while powerful, often assumes a simpler, more linear flow in its basic examples. For true orchestrate multiple AI agents scenarios, especially when dealing with dynamic task splitting and parallel execution, you need to be explicit about how tasks are assigned and how concurrency is managed.
Our goal: A main ResearchAgent
gets a broad request (e.g., "Analyze market sentiment for Tesla, Apple, and Google"). It then delegates specific sentiment analysis tasks for each company to a SentimentAgent
in parallel, collects results, and provides a summary.
qm
Workflow for Parallel Delegation
First, make sure you have qm
installed.
npm install qm-agent
Let's define our agents and the orchestrator. We'll use a simple Node.js setup.
// agents.js
import { Agent } from 'qm-agent';
import { OpenAI } from 'openai'; // Assuming you have an OpenAI API key
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
// Agent 1: SentimentAgent - analyzes sentiment for a single company
export const sentimentAgent = new Agent({
name: 'SentimentAgent',
goal: 'Analyze the sentiment of recent news for a given company.',
tools: [], // No external tools for this example, just LLM
async onMessage(message, session) {
// message.content will be like: "Analyze sentiment for Tesla"
console.log(`[SentimentAgent] Analyzing: "${message.content}"`);
try {
const completion = await openai.chat.completions.create({
model: 'gpt-3.5-turbo', // or gpt-4, depending on your needs
messages: [
{ role: 'system', content: 'You are a sentiment analysis expert. Analyze the given text and return a single word: Positive, Negative, or Neutral.' },
{ role: 'user', content: `Analyze the market sentiment for ${message.content} based on recent news. Output only one word: Positive, Negative, Neutral.` }
],
temperature: 0.2,
max_tokens: 10,
});
const sentiment = completion.choices[0].message.content.trim();
console.log(`[SentimentAgent] Result for "${message.content}": ${sentiment}`);
return sentiment;
} catch (error) {
console.error(`[SentimentAgent] Error analyzing "${message.content}":`, error.message);
return 'Error';
}
}
});
// Agent 2: ResearchAgent - orchestrates sentiment analysis for multiple companies
export const researchAgent = new Agent({
name: 'ResearchAgent',
goal: 'Coordinate and summarize market sentiment analysis for a list of companies.',
tools: [],
async onMessage(message, session) {
const companyList = message.content.split(',').map(c => c.trim());
console.log(`[ResearchAgent] Orchestrating sentiment for: ${companyList.join(', ')}`);
// This is the core: parallel task delegation
const results = await session.task().parallel(
companyList.map(company => ({
agent: 'SentimentAgent', // Target the SentimentAgent
input: `Analyze market sentiment for ${company}` // Specific input for each task
}))
).run(); // Run all these sub-tasks in parallel
console.log(`[ResearchAgent] Aggregating results.`);
const summary = results.map((res, index) => {
const company = companyList[index];
return `${company}: ${res}`;
}).join('\n');
return `Market Sentiment Summary:\n${summary}`;
}
});
// For local testing, ensure these agents are registered in your session
// In a real app, this would be handled by a qm.AgentManager
Now, let's create our main script to run this.
// index.js
import { Session, AgentManager } from 'qm-agent';
import { sentimentAgent, researchAgent } from './agents.js';
import dotenv from 'dotenv';
dotenv.config(); // Load OPENAI_API_KEY from .env
const agentManager = new AgentManager();
agentManager.register(sentimentAgent);
agentManager.register(researchAgent);
async function runAnalysis() {
const session = new Session('my-multi-agent-session', agentManager);
console.log('Starting multi-agent analysis...');
const startTime = Date.now();
const result = await session.tell(
'ResearchAgent',
'Tesla, Apple, Google'
);
const endTime = Date.now();
console.log(`\nFinal Result:\n${result}`);
console.log(`Total time taken: ${(endTime - startTime) / 1000} seconds`);
}
runAnalysis().catch(console.error);
To make this truly copy-paste ready, create agents.js
and index.js
in the same directory, and a .env
file with OPENAI_API_KEY=your_key_here
. Then run node index.js
.
session.task().parallel()
and the Latency Drop
The key line here is session.task().parallel(...)
. This isn't just session.tell
multiple times. qm
internally manages these parallel tasks, optimizing communication and execution.
I ran this exact setup against a sequential version where the ResearchAgent
would await session.tell('SentimentAgent', ...)
for each company one by one. Over 50 runs, the parallel
execution reduced task completion latency by 20%.
This was measured using Date.now()
around the session.tell
call to the ResearchAgent
in index.js
, running on a Vercel serverless function (Node.js 18 environment) with a gpt-3.5-turbo
backend. The difference comes from overlapping API calls and qm
's efficient internal message passing, minimizing idle time. Honestly, I don't get why this isn't the default example for building AI teams that need actual throughput.
When I first started orchestrating multiple AI agents with qm
, I made a classic mistake: I tried to manage concurrency myself with Promise.all
inside onMessage
without using session.task().parallel()
.
// DON'T DO THIS (or do it carefully)
// Inside ResearchAgent.onMessage
const promises = companyList.map(async company => {
// This creates a new session implicitly, or re-uses, but without qm's task management overhead
// It's not leveraging qm's internal parallelization model
const subSession = new Session(`sub-session-${company}`, agentManager);
const result = await subSession.tell('SentimentAgent', `Analyze market sentiment for ${company}`);
return result;
});
const results = await Promise.all(promises);
This might work, but it bypasses qm
's built-in task management, error handling within the agent harness, and context propagation. You're effectively losing the benefits of qm
as an agent orchestrator.
The error I often hit was Error: Session ID already exists
or Agent 'SentimentAgent' not found in current session scope
. This happens because when you manually create new Session()
inside an onMessage
without careful management, you're not correctly extending the parent session
's context or properly registering agents within that new, isolated session scope. ** session.task().parallel() is the idiomatic qm way to handle parallel sub-tasks within a single, cohesive workflow.** It ensures context is maintained and agents are properly invoked.
Another pitfall: forgetting to dotenv.config()
or incorrectly setting OPENAI_API_KEY
. You'll get Error: Invalid API key provided
or Error: connect ECONNREFUSED
if your LLM client can't reach the API. Basic, but easy to miss when you're focused on collaborative AI agent architecture.
The example above uses a fixed SentimentAgent
. But what if you need to dynamically pick an agent based on the task? Say, a FinancialNewsAgent
vs. a TechNewsAgent
.
You can modify the parallel
input:
// Inside ResearchAgent.onMessage
const results = await session.task().parallel(
companyList.map(company => ({
// Dynamic agent selection based on company, for example
agent: company === 'Tesla' ? 'EVAnalystAgent' : 'GeneralSentimentAgent',
input: `Analyze market sentiment for ${company}`
}))
).run();
This flexibility is crucial for complex qm agent harness workflow implementations. It allows your orchestrator agent to make intelligent routing decisions, leading to more specialized and accurate outputs.
Important: For this to work, EVAnalystAgent
and GeneralSentimentAgent
would need to be registered with the AgentManager
just like SentimentAgent
. This dynamic assignment lets you scale your building AI teams with specialized roles easily.
qm
handle agent communication overhead?
qm
handles communication by serializing messages and managing an internal queue. For agents within the same process (like our Node.js example), this is extremely efficient, relying on direct function calls and event loops. For distributed setups, qm
can be extended with custom transport layers (e.g., Redis, Kafka), where overhead depends on your chosen message broker.
qm
scale to dozens of agents?
Yes, qm
is designed for this. The AgentManager
can register many agents, and session.task().parallel()
(or queue()
) allows you to orchestrate them efficiently. The primary scaling bottleneck usually shifts to your underlying LLM providers (API limits, latency) or the computational resources of the host machine, rather than qm
itself.
qm
agent failures?
qm
provides session.logs
and the onMessage
method's session
object itself can expose debugging info. However, for deeper insights, I always add extensive console.log
statements within each agent's onMessage
method, along with try...catch
blocks. If an agent returns an error string instead of useful output, you can inspect the session.logs
(if you configure qm
for persistence) or just the console output from the specific agent.
Honestly, setting up effective building AI teams isn't just about throwing agents together; it's about thoughtful orchestration and understanding the tools you're using. qm
gives you a solid foundation for that, especially once you dig into its parallel execution capabilities. Skip the manual Promise.all
for sub-tasks and embrace session.task().parallel()
; your latency and mental health will thank you.