Tool calling là gì? Cho chatbot quán Mộc tra đơn hàng thật

System prompt hiện tại:  669 ký tự
Kèm 200 đơn trong ngày:  22.037 ký tự (gấp 32.9 lần)
Số điện thoại khách nằm trong prompt: 200
Một dòng trong đó: {"ma_don":"5041","so_dien_thoai":"0901000040","mon":["cà phê sữa","cà phê sữa"],"trang_thai":"đang giao"}

03-tool-calling/
  package.json
  src/
    thong-tin-quan.ts       giờ mở cửa, phí ship, bảng giá
    don-hang.ts             dữ liệu đơn hàng và hai hàm tra cứu
    cong-cu.ts              mô tả công cụ gửi cho mô hình + code chạy công cụ
    prompts.ts              system prompt
    offline.ts              mô hình giả lập, để chạy được khi chưa có API key
    goi-llm.ts              gọi Claude thật (hoặc bản giả lập)
    hoi-moc.ts              hỏi 4 câu mẫu
    xem-request.ts          in toàn bộ cuộc trao đổi
    dua-het-vao-prompt.ts   script đo độ dài ở mục trước

{
  "name": "moc-ai-agent-03",
  "private": true,
  "type": "module",
  "dependencies": {
    "@anthropic-ai/sdk": "1.5.0"
  }
}

// Thông tin cố định của quán Mộc (minh họa), giống dữ liệu ở tập 1.
export const MENU: Record<string, number> = {
  "cà phê đen": 25000,
  "cà phê sữa": 29000,
  "bạc xỉu": 32000,
  "cà phê muối": 35000,
  "bánh mì trứng": 25000,
};

export const GIO_MO_CUA = "Mộc mở cửa từ 6:30 đến 22:00 mỗi ngày.";
export const PHI_SHIP = "Mộc giao trong bán kính 5 km, phí 15.000đ; đơn từ 150.000đ được miễn phí.";

export function bangGia(): string {
  return Object.entries(MENU)
    .map(([mon, gia]) => `- ${mon}: ${gia.toLocaleString("vi-VN")}đ`)
    .join("\n");
}

export type Don = {
  maDon: string;
  soDienThoai: string;
  mon: string[];
  trangThai: "đang pha chế" | "đang giao" | "đã giao";
  datLuc: string;
};

const DON_HANG: Don[] = [
  { maDon: "1041", soDienThoai: "0901000001", mon: ["cà phê sữa", "bánh mì trứng"], trangThai: "đang pha chế", datLuc: "hôm nay 8:12" },
  { maDon: "1042", soDienThoai: "0901000002", mon: ["bạc xỉu"], trangThai: "đang giao", datLuc: "hôm nay 9:40" },
];

export function timDonTheoMa(maDon: string): Don | undefined {
  return DON_HANG.find((don) => don.maDon === maDon);
}

export function timDonTheoSdt(soDienThoai: string): Don | undefined {
  return DON_HANG.find((don) => don.soDienThoai === soDienThoai);
}

import type Anthropic from "@anthropic-ai/sdk";

import { timDonTheoMa, timDonTheoSdt } from "./don-hang.ts";

export const CONG_CU: Anthropic.Tool[] = [
  {
    name: "xem_don",
    description:
      "Xem món và trạng thái hiện tại của một đơn hàng theo mã đơn (4 chữ số, ví dụ 1041). " +
      "Gọi công cụ này mỗi khi khách hỏi đơn đã giao chưa, đang ở đâu, khi nào tới.",
    strict: true,
    input_schema: {
      type: "object",
      properties: { ma_don: { type: "string", description: "Mã đơn gồm 4 chữ số, không có dấu #" } },
      required: ["ma_don"],
      additionalProperties: false,
    },
  },
  {
    name: "tim_don_theo_sdt",
    description:
      "Tìm mã đơn gần nhất của khách theo số điện thoại (10 chữ số, bắt đầu bằng 0). " +
      "Chỉ trả về mã đơn; muốn biết trạng thái thì gọi tiếp xem_don.",
    strict: true,
    input_schema: {
      type: "object",
      properties: { so_dien_thoai: { type: "string", description: "Số điện thoại 10 chữ số" } },
      required: ["so_dien_thoai"],
      additionalProperties: false,
    },
  },
];

export type KetQuaCongCu = { noiDung: string; loi: boolean };

// Đầu vào do mô hình viết ra: luôn kiểm tra lại trước khi dùng, như với dữ liệu người dùng gửi lên.
export function chayCongCu(ten: string, dauVao: unknown): KetQuaCongCu {
  const input = (dauVao ?? {}) as Record<string, unknown>;
  if (ten === "xem_don") {
    const ma = String(input.ma_don ?? "").trim();
    if (!/^\d{4}$/.test(ma)) return { noiDung: `Mã đơn "${ma}" không hợp lệ, cần đúng 4 chữ số.`, loi: true };
    const don = timDonTheoMa(ma);
    if (!don) return { noiDung: `Không có đơn ${ma}.`, loi: true };
    return { noiDung: JSON.stringify({ ma_don: don.maDon, mon: don.mon, trang_thai: don.trangThai, dat_luc: don.datLuc }), loi: false };
  }
  if (ten === "tim_don_theo_sdt") {
    const sdt = String(input.so_dien_thoai ?? "").replace(/\s/g, "");
    if (!/^0\d{9}$/.test(sdt)) return { noiDung: `Số điện thoại "${sdt}" không hợp lệ.`, loi: true };
    const don = timDonTheoSdt(sdt);
    if (!don) return { noiDung: "Không tìm thấy đơn nào với số này.", loi: true };
    return { noiDung: JSON.stringify({ ma_don: don.maDon }), loi: false };
  }
  return { noiDung: `Không có công cụ tên "${ten}".`, loi: true };
}

import { GIO_MO_CUA, PHI_SHIP, bangGia } from "./thong-tin-quan.ts";

export const SYSTEM_V3 = `Bạn là nhân viên chăm sóc khách hàng của quán cà phê Mộc. Trả lời ngắn gọn, thân thiện, bằng tiếng Việt.

Chỉ dùng thông tin trong thẻ <thong_tin_quan> để trả lời câu hỏi chung.
<thong_tin_quan>
${GIO_MO_CUA}
${PHI_SHIP}
Bảng giá:
${bangGia()}
</thong_tin_quan>

Khi khách hỏi về một đơn hàng, hãy dùng công cụ để tra, và chỉ nói trạng thái đúng như kết quả công cụ trả về.
Nếu công cụ báo lỗi hoặc không tìm thấy đơn, hãy nói thật và xin khách kiểm tra lại mã đơn hoặc số điện thoại.`;

import Anthropic from "@anthropic-ai/sdk";

import { CONG_CU } from "./cong-cu.ts";
import { moHinhOffline, type PhanHoi } from "./offline.ts";

export const MODEL = "claude-opus-5-5";

export function coKey(): boolean {
  return Boolean(process.env.ANTHROPIC_API_KEY) && process.env.MOC_OFFLINE !== "1";
}

export async function goiMoHinh(system: string, messages: Anthropic.MessageParam[]): Promise<PhanHoi> {
  if (!coKey()) return moHinhOffline(system, messages);
  const client = new Anthropic(); // tự đọc ANTHROPIC_API_KEY từ biến môi trường
  const response = await client.messages.create({
    model: MODEL,
    max_tokens: 16000,
    output_config: { effort: "low" },
    system,
    tools: CONG_CU, // khác bài trước: gửi kèm mô tả công cụ
    messages,
  });
  return {
    content: response.content,
    stop_reason: response.stop_reason,
    inputTokens: response.usage.input_tokens,
    outputTokens: response.usage.output_tokens,
  };
}

export function layChu(content: Anthropic.ContentBlock[]): string {
  return content
    .filter((b) => b.type === "text")
    .map((b) => b.text)
    .join("");
}

import type Anthropic from "@anthropic-ai/sdk";

import { chayCongCu } from "./cong-cu.ts";
import { coKey, goiMoHinh, layChu, MODEL } from "./goi-llm.ts";
import { SYSTEM_V3 } from "./prompts.ts";

const CAU_HOI = [
  "Quán mở cửa mấy giờ vậy ạ?",
  "Đơn 1041 của em giao chưa ạ?",
  "Đơn #1099 sao chưa thấy ạ",
  "Sáng nay em đặt mà chưa thấy ai gọi, sđt 0901000001",
];

console.log(coKey() ? `Gọi Claude thật (${MODEL})\n` : "Chế độ OFFLINE (giả lập, không phải mô hình thật)\n");

async function hoi(cauHoi: string): Promise<string> {
  const messages: Anthropic.MessageParam[] = [{ role: "user", content: cauHoi }];
  const lan1 = await goiMoHinh(SYSTEM_V3, messages);
  if (lan1.stop_reason !== "tool_use") return layChu(lan1.content);

  // Mô hình xin gọi công cụ: chạy từng khối tool_use, gom mọi kết quả vào MỘT tin nhắn.
  const ketQua: Anthropic.ToolResultBlockParam[] = [];
  for (const block of lan1.content) {
    if (block.type !== "tool_use") continue;
    const kq = chayCongCu(block.name, block.input);
    console.log(`  [công cụ] ${block.name}(${JSON.stringify(block.input)}) → ${kq.noiDung}${kq.loi ? "  (is_error)" : ""}`);
    ketQua.push({ type: "tool_result", tool_use_id: block.id, content: kq.noiDung, is_error: kq.loi });
  }
  messages.push({ role: "assistant", content: lan1.content }); // gửi lại nguyên văn phản hồi có khối tool_use
  messages.push({ role: "user", content: ketQua });

  const lan2 = await goiMoHinh(SYSTEM_V3, messages);
  if (lan2.stop_reason === "tool_use") {
    const muonGoi = lan2.content.filter((b) => b.type === "tool_use").map((b) => `${b.name}(${JSON.stringify(b.input)})`);
    return `(mô hình còn muốn gọi ${muonGoi.join(", ")}, nhưng code này chỉ chạy một vòng nên dừng ở đây)`;
  }
  return layChu(lan2.content);
}

for (const cauHoi of CAU_HOI) {
  console.log(`Khách: ${cauHoi}`);
  const traLoi = await hoi(cauHoi);
  console.log(`Mộc:   ${traLoi}\n`);
}

Chế độ OFFLINE (giả lập, không phải mô hình thật)

Khách: Quán mở cửa mấy giờ vậy ạ?
Mộc:   Dạ, quán mở cửa từ 6:30 đến 22:00 mỗi ngày.

Khách: Đơn 1041 của em giao chưa ạ?
  [công cụ] xem_don({"ma_don":"1041"}) → {"ma_don":"1041","mon":["cà phê sữa","bánh mì trứng"],"trang_thai":"đang pha chế","dat_luc":"hôm nay 8:12"}
Mộc:   Dạ đơn 1041 (cà phê sữa, bánh mì trứng) bạn đặt hôm nay 8:12 hiện vẫn đang pha chế, chưa giao ạ. Mộc sẽ báo bạn ngay khi đơn lên đường nhé!

Khách: Đơn #1099 sao chưa thấy ạ
  [công cụ] xem_don({"ma_don":"1099"}) → Không có đơn 1099.  (is_error)
Mộc:   Dạ Mộc chưa tìm thấy đơn này (Không có đơn 1099). Bạn kiểm tra lại mã đơn hoặc gửi Mộc số điện thoại đặt hàng nhé!

Khách: Sáng nay em đặt mà chưa thấy ai gọi, sđt 0901000001
  [công cụ] tim_don_theo_sdt({"so_dien_thoai":"0901000001"}) → {"ma_don":"1041"}
Mộc:   (mô hình còn muốn gọi xem_don({"ma_don":"1041"}), nhưng code này chỉ chạy một vòng nên dừng ở đây)

import type Anthropic from "@anthropic-ai/sdk";

import { CONG_CU, chayCongCu } from "./cong-cu.ts";
import { moHinhOffline } from "./offline.ts";
import { SYSTEM_V3 } from "./prompts.ts";

console.log("Công cụ đầu tiên trong danh sách gửi kèm mỗi request:");
console.log(JSON.stringify(CONG_CU[0], null, 2));

const messages: Anthropic.MessageParam[] = [{ role: "user", content: "Đơn 1041 của em giao chưa ạ?" }];
const lan1 = moHinhOffline(SYSTEM_V3, messages);
const toolUse = lan1.content.find((b) => b.type === "tool_use")!;
const kq = chayCongCu(toolUse.name, toolUse.input);
messages.push({ role: "assistant", content: lan1.content });
messages.push({ role: "user", content: [{ type: "tool_result", tool_use_id: toolUse.id, content: kq.noiDung }] });
const lan2 = moHinhOffline(SYSTEM_V3, messages);
messages.push({ role: "assistant", content: lan2.content });

console.log(`\nLần gọi 1: stop_reason = "${lan1.stop_reason}". Lần gọi 2: stop_reason = "${lan2.stop_reason}".`);
console.log("Mảng messages sau hai lần gọi:");
for (const m of messages) console.log(`${m.role}: ${JSON.stringify(m.content)}`);

Lần gọi 1: stop_reason = "tool_use". Lần gọi 2: stop_reason = "end_turn".
Mảng messages sau hai lần gọi:
user: "Đơn 1041 của em giao chưa ạ?"
assistant: [{"type":"tool_use","id":"toolu_offline_1","name":"xem_don","input":{"ma_don":"1041"}}]
user: [{"type":"tool_result","tool_use_id":"toolu_offline_1","content":"{\"ma_don\":\"1041\",\"mon\":[\"cà phê sữa\",\"bánh mì trứng\"],\"trang_thai\":\"đang pha chế\",\"dat_luc\":\"hôm nay 8:12\"}"}]
assistant: [{"type":"text","text":"Dạ đơn 1041 (cà phê sữa, bánh mì trứng) bạn đặt hôm nay 8:12 hiện vẫn đang pha chế, chưa giao ạ. Mộc sẽ báo bạn ngay khi đơn lên đường nhé!"}]

import type Anthropic from "@anthropic-ai/sdk";

export type PhanHoi = Pick<Anthropic.Message, "content" | "stop_reason"> & { inputTokens: number; outputTokens: number };

let dem = 0;
function goiCongCu(name: string, input: Record<string, string>): PhanHoi {
  dem += 1;
  const block = { type: "tool_use", id: `toolu_offline_${dem}`, name, input } as Anthropic.ToolUseBlock;
  return { content: [block], stop_reason: "tool_use", inputTokens: 0, outputTokens: 0 };
}

function traLoi(text: string): PhanHoi {
  return { content: [{ type: "text", text } as Anthropic.TextBlock], stop_reason: "end_turn", inputTokens: 0, outputTokens: 0 };
}

function dongCo(system: string, tuKhoa: RegExp): string | undefined {
  return system.split("\n").find((dong) => tuKhoa.test(dong));
}

export function moHinhOffline(system: string, messages: Anthropic.MessageParam[]): PhanHoi {
  const cauHoi = String(messages[0].content).toLowerCase();
  const cuoi = messages.at(-1)!;

  // Lượt đầu: chỉ có câu hỏi của khách.
  if (typeof cuoi.content === "string") {
    const ma = cauHoi.match(/\b\d{4}\b/)?.[0];
    if (ma) return goiCongCu("xem_don", { ma_don: ma });
    const sdt = cauHoi.match(/\b0\d{9}\b/)?.[0];
    if (sdt) return goiCongCu("tim_don_theo_sdt", { so_dien_thoai: sdt });
    if (/giờ|mở cửa/.test(cauHoi)) return traLoi(`Dạ, ${(dongCo(system, /mở cửa từ/) ?? "").replace("Mộc mở", "quán mở")}`);
    return traLoi("Dạ Mộc chưa có thông tin này ạ.");
  }

  // Lượt sau: code của mình gửi lại kết quả công cụ (trong một tin nhắn vai "user").
  const ketQua = (cuoi.content as Anthropic.ToolResultBlockParam[]).find((b) => b.type === "tool_result")!;
  const noiDung = String(ketQua.content);
  if (ketQua.is_error) {
    return traLoi(`Dạ Mộc chưa tìm thấy đơn này (${noiDung.replace(/\.$/, "")}). Bạn kiểm tra lại mã đơn hoặc gửi Mộc số điện thoại đặt hàng nhé!`);
  }
  const don = JSON.parse(noiDung) as { ma_don: string; mon?: string[]; trang_thai?: string; dat_luc?: string };
  // Mới có mã đơn mà khách hỏi trạng thái: cần gọi thêm xem_don.
  if (!don.trang_thai) return goiCongCu("xem_don", { ma_don: don.ma_don });
  return traLoi(`Dạ đơn ${don.ma_don} (${don.mon!.join(", ")}) bạn đặt ${don.dat_luc} hiện vẫn ${don.trang_thai}, chưa giao ạ. Mộc sẽ báo bạn ngay khi đơn lên đường nhé!`);
}

npm install
export ANTHROPIC_API_KEY="sk-ant-..."   # Windows PowerShell: $env:ANTHROPIC_API_KEY="sk-ant-..."
node src/hoi-moc.ts