Build Your Human Handoff Agent with Mastra

import { createTool } from '@mastra/core/tools';
import { z } from 'zod';

export const handoffTool = createTool({
  id: 'handoff',
  description: 'Escalate chat to a specific human or system.',
  inputSchema: z.object({
    target: z.string().describe('User or system to handoff to, e.g., "swapnil" or "support-team"'),
    reason: z.string().describe('Reason for the handoff'),
  }),
  outputSchema: z.object({
    success: z.boolean(),
    message: z.string(),
  }),
  execute: async ({ context }) => {
    // Stub: in production, call CometChat API to reassign chat
    console.log(`Handing off to ${context.target} because ${context.reason}`);
    return { success: true, message: `Conversation handed off to ${context.target}` };
  },
});

import { openai } from '@ai-sdk/openai';
import { Agent } from '@mastra/core/agent';
import { handoffTool } from '../tools/handoff-tool';

export const handoffAgent = new Agent({
  name: 'Handoff Agent',
  instructions: `
You are a support triage bot. 
- If you cannot answer a question or detect the user needs a human, call the 'handoff' tool. 
- Provide the right target and reason.
- Otherwise, try to answer simply.
  `,
  model: openai('gpt-4o-mini'),
  tools: {
    'handoff': handoffTool,
  },
});

import { Mastra } from '@mastra/core/mastra';
import { PinoLogger } from '@mastra/loggers';
import { LibSQLStore } from '@mastra/libsql';

import { handoffAgent } from '../agents/handoff-agent';

export const mastra = new Mastra({
  agents: { 'handoff': handoffAgent }, // API path: /api/agents/handoff/*
  storage: new LibSQLStore({ url: 'file:../mastra.db' }),
  logger: new PinoLogger({ name: 'Mastra', level: 'info' }),
});

rm -rf .mastra/output
npx mastra dev

Mastra API running on port http://localhost:4111/api

curl -X POST http://localhost:4111/api/agents/handoff/generate   -H "Content-Type: application/json"   -d '{"messages":[{"role":"user","content":"I need to speak with Swapnil about my billing issue"}]}'

{
  "success": true,
  "message": "Conversation handed off to Swapnil"
}