Hand a conversation over to a human agent

{
  "type": "function",
  "name": "transfer_to_human",
  "description": "Transfer this conversation to a human support agent. Call it when the customer asks for a person or when you cannot resolve the request.",
  "strict": true,
  "parameters": {
    "type": "object",
    "properties": {
      "reason": { "type": "string" },
      "queue_hint": { "type": "string", "enum": ["billing", "security", "retention", "general"] }
    },
    "required": ["reason", "queue_hint"],
    "additionalProperties": false
  }
}

const history = await sdk.llm.conversations.listItems({ conversationId: "conv_abc123", order: "asc" });

[
  { "category": "account_access", "priority": "urgent", "queue": "security-incidents" },
  { "category": "billing", "priority": "urgent", "queue": "billing-escalations" },
  { "category": "billing", "queue": "billing" },
  { "category": "complaint", "queue": "retention" }
]

{
  "queue": "billing-escalations",
  "reason": "Customer demands a refund today and threatens a chargeback.",
  "triage": { "category": "billing", "priority": "urgent", "needs_human_handoff": true, "...": "..." },
  "conversation_id": "conv_abc123",
  "history": [{ "type": "message", "role": "user", "content": "..." }]
}

import { SDK } from "@meetkai/mka1";

const sdk = new SDK({ bearerAuth: `Bearer ${process.env.MKA1_API_KEY}` });

const triageAgentId = process.env.TRIAGE_AGENT_ID;
if (!triageAgentId) throw new Error("Set TRIAGE_AGENT_ID to the agent created from the Customer care triage template");

// Routing rules: first match wins. Omit priority to match every priority.
const routingRules = [
  { category: "account_access", priority: "urgent", queue: "security-incidents" },
  { category: "billing", priority: "urgent", queue: "billing-escalations" },
  { category: "billing", queue: "billing" },
  { category: "complaint", queue: "retention" },
];

// 1. The conversation. In your app it already exists; this seeds one so the sample runs on its own.
const messages = [
  { role: "user", content: "I was charged twice for order 48213 and nobody answers my emails." },
  { role: "assistant", content: "I'm sorry about that. Can you confirm the last four digits of the card?" },
  { role: "user", content: "4412. I want a refund today or I'm disputing it with my bank." },
] as const;

const conversation = await sdk.llm.conversations.create({
  createConversationRequest: { items: [...messages], metadata: { channel: "web-chat" } },
});

// 2. Decide: run the triage agent over the transcript.
let run = await sdk.agentRuns.createAgentRun({
  agentId: triageAgentId,
  createAgentRunRequest: { input: messages.map((m) => `${m.role}: ${m.content}`).join("\n") },
});
while (run.status === "waiting" || run.status === "queued" || run.status === "submitting") {
  await new Promise((resolve) => setTimeout(resolve, 1000));
  run = await sdk.agentRuns.getAgentRun({ agentId: triageAgentId, runId: run.id });
}
if (run.status !== "completed") throw new Error(`Triage run ended with status ${run.status}`);

const message = run.gatewayResponse.output.find((item: { type: string }) => item.type === "message");
const triage = JSON.parse(message.content[0].text);
if (!triage.needs_human_handoff) {
  console.log("No handover needed:", triage.summary);
  process.exit(0);
}

// 3. Route: category × priority → queue.
const rule = routingRules.find(
  (r) => r.category === triage.category && (r.priority === undefined || r.priority === triage.priority),
);
const queue = rule?.queue ?? "general-support";

// 4. Full history from the Conversations API.
const history = await sdk.llm.conversations.listItems({ conversationId: conversation.id, order: "asc" });

// 5. Hand over: post the package to your queue, or print it.
const handover = {
  queue,
  reason: triage.handoff_reason,
  triage,
  conversation_id: conversation.id,
  history: history.data,
};
const webhook = process.env.HANDOVER_WEBHOOK_URL;
if (webhook) {
  const posted = await fetch(webhook, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(handover),
  });
  console.log(`Handed over to ${queue}: ${posted.status}`);
} else {
  console.log(JSON.stringify(handover, null, 2));
}