Tutorial: Multi-Agent Orchestration

Learn how to build complex systems by coordinating specialized agents working together.

Why Multi-Agent?#

Single agents are powerful, but they struggle with complex, multi-step workflows that require different "mindsets" or tools. By decomposing a task into sub-problems and assigning them to specialized agents, you can achieve higher accuracy and reliability.

The Specialist Principle

Just as a software team has Product Managers, Engineers, and QA, a robust AI system should have specialized agents. A "Coder" agent shouldn't be responsible for "Product Strategy".

Architecture Patterns#

1. Handoff (Relay)

Agent A finishes a task and passes the full context to Agent B. Good for linear workflows (e.g., Research > Draft > Edit).

2. Router (Manager)

A central "Manager" agent analyzes the request and delegates to the appropriate specialist, then aggregates the results.

Building a Research Team#

In this tutorial, we'll build a **Manager-Worker** system where a main agent delegates tasks to a Researcher and a Writer.

Define the Specialist Agents

First, create the specialized agents with narrow system prompts.

agents.ts

import { Agent } from '@akios/sdk'

// 1. The Researcher: Good at finding facts
const researcher = new Agent({
  name: 'Researcher',
  model: 'gpt-4o',
  systemPrompt: `You are a senior research analyst. 
  Your goal is to find accurate, cited facts about the user's topic.
  Be concise and list sources.`,
  tools: [webSearchTool] // Assume we have a search tool
})

// 2. The Writer: Good at prose and formatting
const writer = new Agent({
  name: 'Writer',
  model: 'gpt-4o',
  systemPrompt: `You are a technical blog writer.
  Take raw research notes and turn them into an engaging article.
  Use markdown formatting.`
})

Create the Manager Agent

The Manager needs a tool to "call" other agents. We'll wrap the specialists in a `Tool` interface.

manager.ts

import { Tool } from '@akios/sdk'

// Wrap researcher as a tool
const askResearcher = new Tool({
  name: 'ask_researcher',
  description: 'Delegate a research task to the specialist.',
  schema: z.object({ query: z.string() }),
  execute: async ({ query }) => {
    const result = await researcher.run(query)
    return result.output
  }
})

// Wrap writer as a tool
const askWriter = new Tool({
  name: 'ask_writer',
  description: 'Delegate a writing task to the specialist.',
  schema: z.object({ notes: z.string() }),
  execute: async ({ notes }) => {
    const result = await writer.run(notes)
    return result.output
  }
})

const manager = new Agent({
  name: 'Manager',
  model: 'gpt-4o',
  systemPrompt: `You are a project manager. 
  1. Ask the researcher for information on the topic.
  2. Pass the research to the writer to create a draft.
  3. Return the final draft to the user.`,
  tools: [askResearcher, askWriter]
})

Run the Team

Now you just interact with the Manager.

main.ts

const result = await manager.run("Write a blog post about the future of Quantum Computing")

console.log(result.output)
// Output will be the final article produced by the Writer, 
// based on facts found by the Researcher.