MULTI_AGENT_ORCHESTRATION

TUTORIAL

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".

THE_PATTERN#

Complex tasks often require different "specialists". Instead of one giant prompt, we can use multiple agents:

ROUTER

Decides which specialist to call.

RESEARCHER

Gathers information.

WRITER

Synthesizes the final output.

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.