Build Your Human Handoff Agent with Mastra

Create a Mastra agent that hands the conversation off to the right human or system when needed, then returns control smoothly.

Imagine an agent that knows its limits. When it detects a user needs human support, or another specialist agent, it can gracefully hand off the chat instead of fumbling for an answer.

---

What You’ll Build

• A Mastra agent that detects when to escalate.
• A simple handoff action returning JSON with target user/system.
• A deployable agent via Mastra’s API.
• Integration into CometChat, so the chat seamlessly moves to a human.

---

Prerequisites

• A Mastra project (npx create-mastra@latest my-mastra-app).
• Node.js installed.
• OpenAI API key in .env as OPENAI_API_KEY.
• A CometChat app with users/roles defined (for live handoff).

---

Step 1

Define Handoff Action

src/tools/handoff-tool.ts:

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}` };
  },
});

---

Step 2

Create the Agent

src/agents/handoff-agent.ts:

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,
  },
});

---

Step 3

Register the Agent in Mastra

src/mastra/index.ts:

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' }),
});

---

Step 4

Run the Agent

rm -rf .mastra/output
npx mastra dev

You should see:

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

Test it locally:

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"}]}'

Expected output:

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

---

Step 5

Deploy & Connect

• Deploy the API (/api/agents/handoff/generate) using Render, Railway, Vercel, or any host.
• In CometChat Dashboard → AI Agents, create an agent with:
  • Provider: Mastra
  • Agent ID: handoff
  • Deployment URL: public endpoint from your host

Now users can say “I need human help” and the agent will call the handoff tool to route them.

---

Troubleshooting

• Agent doesn’t escalate: Improve instructions with clear escalation rules.
• Handoff not working: Ensure your tool executes CometChat’s API to transfer conversations.
• Looping answers: Add a fallback to always call handoff after repeated failed answers.

---

Next Steps

• Add logic to choose specific team members (billing, tech support).
• Connect to external ticketing systems (Zendesk, Freshdesk).
• Add a coordinator (relay) agent that can ask multiple humans/agents and return the answer.