Designing a Multi-Agent Swarm with Vercel AI SDK for Complex Workflows

import { openai } from '@ai-sdk/openai';

// Define the configurations for our specialized agents
const AGENTS = {
  Triage: {
    model: openai('gpt-4o-mini'), // Fast, cheap model for routing
    system: `You are the Triage Agent. Your only job is to route the user's request to the correct specialist. 
    If the user wants recent information, transfer them to the Researcher. 
    If the user wants marketing copy or an essay written, transfer them to the Copywriter.`
  },
  Researcher: {
    model: openai('gpt-4o'), // Smarter model for complex tool use
    system: `You are an elite Web Researcher. You have access to search the web. 
    Find accurate, factual information to answer the user's query.`
  },
  Copywriter: {
    model: openai('gpt-4o'),
    system: `You are an expert Copywriter. You write engaging, highly persuasive marketing copy. 
    Take any research provided to you and format it into a stunning blog post.`
  }
};

import { tool } from 'ai';
import { z } from 'zod';

const researcherTools = {
  search_web: tool({
    description: 'Search the internet for current information.',
    parameters: z.object({ query: z.string() }),
    execute: async ({ query }) => {
      console.log(`[Researcher] Searching web for: ${query}`);
      // Mock search result
      return `Results for ${query}: The Vercel AI SDK v7 introduced durable Workflow agents and OpenTelemetry support in 2026.`;
    }
  })
};

type HandoffSignal = {
  type: 'HANDOFF';
  targetAgent: keyof typeof AGENTS;
  context: string;
};

// This helper creates a tool that an agent can call to transfer control
function createHandoffTool(targetAgent: keyof typeof AGENTS, description: string) {
  return tool({
    description,
    parameters: z.object({
      context: z.string().describe("The information and instructions to pass to the next agent.")
    }),
    execute: async ({ context }): Promise<HandoffSignal> => {
      console.log(`\n>>> Transferring control to ${targetAgent}...`);
      // We return a structured signal that the outer loop will interpret
      return { type: 'HANDOFF', targetAgent, context };
    }
  });
}

const triageTools = {
  transfer_to_researcher: createHandoffTool('Researcher', 'Transfer the user to the Web Researcher to find factual information.'),
  transfer_to_copywriter: createHandoffTool('Copywriter', 'Transfer the user to the Copywriter to write marketing text.')
};

const researcherHandoffTools = {
  transfer_to_copywriter: createHandoffTool('Copywriter', 'Transfer your research findings to the Copywriter to format them into an article.')
};

import { generateText, CoreMessage } from 'ai';

async function runSwarm(initialPrompt: string) {
  let currentAgentName: keyof typeof AGENTS = 'Triage';
  let messages: CoreMessage[] = [{ role: 'user', content: initialPrompt }];

  console.log(`\n[User]: ${initialPrompt}`);

  // The infinite orchestration loop
  while (true) {
    const activeAgent = AGENTS[currentAgentName];
    
    // Determine which tools the active agent has access to
    let activeTools = {};
    if (currentAgentName === 'Triage') activeTools = triageTools;
    if (currentAgentName === 'Researcher') activeTools = { ...researcherTools, ...researcherHandoffTools };
    // Copywriter has no handoff tools; it is the end of the line

    console.log(`\n--- Active Agent: ${currentAgentName} ---`);

    const result = await generateText({
      model: activeAgent.model,
      system: activeAgent.system,
      messages: messages,
      tools: activeTools,
      maxSteps: 5, // Allow the agent to use standard tools multiple times
    });

    // Check if the agent called a handoff tool
    const handoffToolCall = result.toolResults.find(
      (tr) => (tr.result as any)?.type === 'HANDOFF'
    );

    if (handoffToolCall) {
      const signal = handoffToolCall.result as HandoffSignal;
      
      // Save the transition in the chat history
      messages.push({
        role: 'assistant',
        content: `I am transferring this task to the ${signal.targetAgent}. Context provided: ${signal.context}`
      });

      // Switch the active agent and loop again!
      currentAgentName = signal.targetAgent;
      continue;
    }

    // If no handoff was triggered, the agent is finished communicating
    console.log(`\n[${currentAgentName} Final Output]:\n${result.text}`);
    break; 
  }
}

async function main() {
  await runSwarm("Find out what features were released in Vercel AI SDK v7, and write a hyped-up marketing tweet about it.");
}

main();