qm multiplayer AI agent tutorial: Cut Latency 20% with Node.js

A developer built a multi-agent AI system using the qm-agent library and Node.js, achieving a 20% reduction in task completion times by implementing parallel delegation. The system, which powers FarahGPT's multi-agent trading platform with over 5,100 users, uses a primary ResearchAgent to coordinate specialized SentimentAgents for concurrent analysis.

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. js // 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. js // 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 . js // 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: js // 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.