Worked Example: Multi-Agent Handoff

This step-by-step example demonstrates how to build a multi-agent system where a Triage Router dynamically delegates user queries to specialized sub-agents (Code Specialist and Math Specialist).

Step-by-Step Implementation

Step 1: Install Dependencies

npm install @kikoyu/core zod

Step 2: Set Environment Variables (`.env`)

OPENAI_API_KEY=sk-proj-your_openai_api_key_here

Step 3: Complete Executable Code (`index.js`)

import { Agent, createHandoff, createTool, OpenAIProvider, Runner, z } from '@kikoyu/core';
 
// 1. Code Specialist Agent with TypeScript tool
const runCodeFormatterTool = createTool({
  name: 'format_code',
  description: 'Format TypeScript code snippet.',
  parameters: z.object({ code: z.string() }),
  execute: async ({ code }) => ({ formattedCode: code.trim(), status: 'SUCCESS' }),
});
 
const codeSpecialist = Agent.builder()
  .setName('Code Specialist')
  .setInstructions('You are an expert TypeScript engineer. Provide clean code solutions.')
  .setModel(new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, model: 'gpt-4o-mini' }))
  .addTool(runCodeFormatterTool)
  .build();
 
// 2. Math Specialist Agent
const mathSpecialist = Agent.builder()
  .setName('Math Specialist')
  .setInstructions('You are a mathematician. Solve complex math expressions step-by-step.')
  .setModel(new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, model: 'gpt-4o-mini' }))
  .build();
 
// 3. Triage Router Agent with Handoff Targets
const triageRouter = Agent.builder()
  .setName('Triage Router')
  .setInstructions('Analyze incoming user requests. Hand off coding questions to Code Specialist and math questions to Math Specialist.')
  .setModel(new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, model: 'gpt-4o-mini' }))
  .withHandoffs(
    createHandoff(codeSpecialist, { description: 'Hand off technical coding questions.' }),
    createHandoff(mathSpecialist, { description: 'Hand off mathematical calculations.' })
  )
  .build();
 
// 4. Run execution loop
const runner = new Runner();
 
async function main() {
  console.log('Running Triage Router...');
 
  const result = await runner.run(
    triageRouter,
    'Can you write a TypeScript function to check if a string is a palindrome?'
  );
 
  console.log('\n--- Handoff Complete ---');
  console.log('Final Active Specialist:', result.agent.name); // "Code Specialist"
  console.log('Final Response:\n', result.text);
}
 
main().catch(console.error);

Step 4: Run the Script

node index.js

Single Agent with Tools Readme