Multi-Agent Orchestration for Customer Support: Architecture Guide

                    ┌─────────────────┐
                    │   Orchestrator   │
                    │  (Router Agent)  │
                    └────────┬────────┘
                             │
           ┌─────────┬──────┴──────┬──────────┐
           ▼         ▼             ▼           ▼
    ┌────────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
    │  Billing   │ │ Technical│ │ Shipping │ │ Returns  │
    │   Agent    │ │  Agent   │ │  Agent   │ │  Agent   │
    └────────────┘ └──────────┘ └──────────┘ └──────────┘
         │              │            │             │
    ┌────┴────┐   ┌────┴────┐  ┌───┴────┐   ┌───┴────┐
    │ Billing │   │  Tech   │  │ Order  │   │ Return │
    │   KB    │   │   KB    │  │Tracking│   │ Policy │
    │+ Stripe │   │+ Logs   │  │  API   │   │  KB    │
    └─────────┘   └─────────┘  └────────┘   └────────┘

typescript
interface AgentConfig {
  id: string;
  name: string;
  description: string;
  systemPrompt: string;
  tools: Tool[];
  knowledgeBaseId: string;
}

interface RoutingDecision {
  agentId: string;
  confidence: number;
  reasoning: string;
}

const AGENTS: AgentConfig[] = [
  {
    id: "billing",
    name: "Billing Agent",
    description: "Handles invoices, charges, refunds, plan changes, and payment methods",
    systemPrompt: `You are a billing support specialist. You have access to the
customer's billing history via Stripe. You can issue refunds up to $50 without
approval. For amounts over $50, escalate to a human agent.`,
    tools: [stripeLookup, issueRefund, changePlan, applyCredit],
    knowledgeBaseId: "kb-billing",
  },
  {
    id: "technical",
    name: "Technical Agent",
    description: "Handles setup issues, API errors, integration problems, and bug reports",
    systemPrompt: `You are a technical support engineer. You have access to the
customer's account configuration and recent error logs. Walk users through
debugging steps before escalating.`,
    tools: [getAccountConfig, fetchErrorLogs, runDiagnostic, createBugReport],
    knowledgeBaseId: "kb-technical",
  },
  {
    id: "shipping",
    name: "Shipping Agent",
    description: "Handles order tracking, delivery issues, and address changes",
    systemPrompt: `You are a shipping and delivery specialist. You can look up
order status and tracking information. For lost packages, initiate a trace
before offering a replacement.`,
    tools: [trackOrder, updateAddress, initiateTrace, requestReplacement],
    knowledgeBaseId: "kb-shipping",
  },
  {
    id: "returns",
    name: "Returns Agent",
    description: "Handles return requests, exchanges, and return policy questions",
    systemPrompt: `You are a returns and exchange specialist. Verify the item is
within the return window before initiating. Digital products are non-refundable
unless defective.`,
    tools: [checkReturnEligibility, initiateReturn, schedulePickup, processExchange],
    knowledgeBaseId: "kb-returns",
  },
];

async function routeMessage(
  message: string,
  conversationHistory: Message[]
): Promise<RoutingDecision> {
  const agentDescriptions = AGENTS.map(
    (a) => `- ${a.id}: ${a.description}`
  ).join("\n");

  const response = await llm.chat({
    model: "gpt-4o-mini", // Fast, cheap model for routing
    messages: [
      {
        role: "system",
        content: `You are a routing agent. Classify the customer message and
select the best agent to handle it. Respond with JSON only.

Available agents:
${agentDescriptions}

If the message does not clearly fit any agent, route to "general".
Consider the full conversation history for context.`,
      },
      ...conversationHistory,
      { role: "user", content: message },
    ],
    response_format: { type: "json_object" },
  });

  return JSON.parse(response.content) as RoutingDecision;
}

                    ┌─────────────────┐
                    │  Top Orchestrator│
                    └────────┬────────┘
                    ┌────────┴────────┐
                    ▼                 ▼
            ┌──────────────┐  ┌──────────────┐
            │  Technical   │  │   Commerce   │
            │   Manager    │  │   Manager    │
            └──────┬───────┘  └──────┬───────┘
              ┌────┼────┐       ┌────┼────┐
              ▼    ▼    ▼       ▼    ▼    ▼
            API  Integ Infra  Billing Ship Returns

typescript
interface HierarchicalAgent extends AgentConfig {
  children?: HierarchicalAgent[];
  canHandle: (message: string, context: ConversationContext) => Promise<boolean>;
}

async function hierarchicalRoute(
  message: string,
  context: ConversationContext,
  agents: HierarchicalAgent[]
): Promise<AgentConfig> {
  // First level: pick the domain manager
  const manager = await selectBestAgent(message, context, agents);

  // If the manager has children, route again within that domain
  if (manager.children && manager.children.length > 0) {
    return hierarchicalRoute(message, context, manager.children);
  }

  return manager;
}

typescript
interface AgentMessage {
  fromAgent: string;
  toAgent: string;
  type: "handoff" | "query" | "response";
  payload: {
    conversationState: ConversationState;
    request: string;
    partialResolution?: Record<string, unknown>;
  };
}

class CollaborativeAgent {
  constructor(
    private config: AgentConfig,
    private registry: AgentRegistry
  ) {}

  async handle(message: string, state: ConversationState): Promise<AgentResponse> {
    const response = await llm.chat({
      model: "gpt-4o",
      messages: [
        { role: "system", content: this.config.systemPrompt },
        ...state.history,
        { role: "user", content: message },
      ],
      tools: [
        ...this.config.tools,
        // Special tool: request help from another agent
        {
          name: "delegate_to_agent",
          description: "Pass part of the request to another specialist agent",
          parameters: {
            agentId: { type: "string", enum: this.registry.getAgentIds() },
            request: { type: "string" },
            context: { type: "string" },
          },
        },
      ],
    });

    // If the agent invoked delegate_to_agent, execute the delegation
    if (response.toolCalls?.some((tc) => tc.name === "delegate_to_agent")) {
      return this.handleDelegation(response, state);
    }

    return { content: response.content, state };
  }

  private async handleDelegation(
    response: LLMResponse,
    state: ConversationState
  ): Promise<AgentResponse> {
    const delegation = response.toolCalls.find(
      (tc) => tc.name === "delegate_to_agent"
    );
    const targetAgent = this.registry.get(delegation.args.agentId);

    const delegatedResult = await targetAgent.handle(
      delegation.args.request,
      { ...state, delegatedFrom: this.config.id }
    );

    // Feed the result back to the original agent to compose a final response
    return this.synthesizeResponse(response, delegatedResult, state);
  }
}

typescript
interface HandoffPayload {
  // Full conversation history
  conversationHistory: Message[];

  // Structured summary of what has been resolved so far
  resolutionState: {
    customerIntent: string;
    identifiedIssues: string[];
    actionsCompleted: Array<{
      action: string;
      result: string;
      timestamp: string;
    }>;
    pendingActions: string[];
  };

  // Customer entities extracted during the conversation
  entities: {
    customerId?: string;
    orderId?: string;
    productId?: string;
    accountEmail?: string;
    [key: string]: string | undefined;
  };

  // Why the handoff is happening
  handoffReason: string;

  // The source agent's suggested next step
  suggestedAction?: string;
}

async function executeHandoff(
  fromAgent: AgentConfig,
  toAgent: AgentConfig,
  state: ConversationState
): Promise<HandoffPayload> {
  // Ask the outgoing agent to summarize the state
  const summary = await llm.chat({
    model: "gpt-4o-mini",
    messages: [
      {
        role: "system",
        content: `You are ${fromAgent.name}. The conversation is being handed off
to ${toAgent.name}. Produce a structured JSON summary of the conversation state
so the receiving agent can continue without asking the customer to repeat
themselves. Include: customer intent, issues identified, actions you took,
entities (order IDs, emails, etc.), and why you are handing off.`,
      },
      ...state.history,
    ],
    response_format: { type: "json_object" },
  });

  return JSON.parse(summary.content) as HandoffPayload;
}

typescript
function buildHandoffSystemPrompt(
  agentConfig: AgentConfig,
  handoff: HandoffPayload
): string {
  return `${agentConfig.systemPrompt}

--- HANDOFF CONTEXT ---
This conversation was handed off from another agent.

Customer intent: ${handoff.resolutionState.customerIntent}
Issues identified: ${handoff.resolutionState.identifiedIssues.join(", ")}
Actions already completed:
${handoff.resolutionState.actionsCompleted
  .map((a) => `- ${a.action}: ${a.result}`)
  .join("\n")}

Pending: ${handoff.resolutionState.pendingActions.join(", ")}
Handoff reason: ${handoff.handoffReason}
${handoff.suggestedAction ? `Suggested next step: ${handoff.suggestedAction}` : ""}

Customer entities:
${Object.entries(handoff.entities)
  .filter(([, v]) => v)
  .map(([k, v]) => `- ${k}: ${v}`)
  .join("\n")}

IMPORTANT: Do NOT ask the customer to repeat information already captured above.
Continue the conversation naturally from where it was handed off.
--- END HANDOFF CONTEXT ---`;
}

typescript
async function handleMultiDomainMessage(
  message: string,
  state: ConversationState
): Promise<string> {
  // Step 1: Decompose the message into domain-specific sub-tasks
  const decomposition = await llm.chat({
    model: "gpt-4o-mini",
    messages: [
      {
        role: "system",
        content: `Decompose this customer message into separate domain-specific
tasks. Return a JSON array of { agentId, task } objects. If the message belongs
to a single domain, return an array with one element.`,
      },
      { role: "user", content: message },
    ],
    response_format: { type: "json_object" },
  });

  const tasks: { agentId: string; task: string }[] = JSON.parse(
    decomposition.content
  ).tasks;

  // Step 2: Execute each sub-task with the appropriate agent
  const results: string[] = [];
  for (const { agentId, task } of tasks) {
    const agent = getAgent(agentId);
    const result = await agent.handle(task, state);
    results.push(result.content);
    // Update state with any actions taken
    state = result.state;
  }

  // Step 3: Synthesize a unified response
  const synthesis = await llm.chat({
    model: "gpt-4o",
    messages: [
      {
        role: "system",
        content: `Combine these agent responses into a single, coherent reply
to the customer. Do not repeat information. Be concise.`,
      },
      {
        role: "user",
        content: `Customer asked: "${message}"\n\nAgent responses:\n${results
          .map((r, i) => `${i + 1}. ${r}`)
          .join("\n\n")}`,
      },
    ],
  });

  return synthesis.content;
}

typescript
interface RoutingEval {
  message: string;
  conversationHistory: Message[];
  expectedAgentId: string;
}

async function evaluateRouting(evalSet: RoutingEval[]): Promise<{
  accuracy: number;
  confusionMatrix: Record<string, Record<string, number>>;
}> {
  const confusionMatrix: Record<string, Record<string, number>> = {};
  let correct = 0;

  for (const example of evalSet) {
    const decision = await routeMessage(
      example.message,
      example.conversationHistory
    );

    // Track predicted vs. expected
    if (!confusionMatrix[example.expectedAgentId]) {
      confusionMatrix[example.expectedAgentId] = {};
    }
    confusionMatrix[example.expectedAgentId][decision.agentId] =
      (confusionMatrix[example.expectedAgentId][decision.agentId] || 0) + 1;

    if (decision.agentId === example.expectedAgentId) correct++;
  }

  return {
    accuracy: correct / evalSet.length,
    confusionMatrix,
  };
}

typescript
interface AgentEvent {
  conversationId: string;
  timestamp: string;
  eventType: "route" | "agent_invoke" | "tool_call" | "handoff" | "resolution";
  agentId: string;
  data: {
    routingConfidence?: number;
    toolName?: string;
    toolArgs?: Record<string, unknown>;
    handoffFrom?: string;
    handoffTo?: string;
    resolutionStatus?: "resolved" | "escalated" | "abandoned";
    latencyMs: number;
  };
}

// Query patterns for your monitoring dashboard:
// - Routing confidence distribution per agent
// - Handoff frequency matrix (which agents hand off to which)
// - P95 latency per agent
// - Resolution rate trend over time
// - Tool error rate per agent