Bài 2 — Định nghĩa schema tool chuẩn (JSON Schema)

Model chọn tool nào và điền tham số ra sao hoàn toàn phụ thuộc vào schema bạn viết. Schema tồi = model gọi sai, thiếu field, đoán bừa. Đây là kỹ năng đòn bẩy cao nhất trong toàn khóa: sửa schema thường hiệu quả hơn sửa prompt.

Cấu trúc một tool definition

Mọi nhà cung cấp (OpenAI, Anthropic, Gemini) đều dùng chung ý tưởng: mỗi tool có name, description, và parameters viết bằng JSON Schema. Cú pháp có thể khác nhau đôi chút giữa các SDK, nhưng ba thành phần này là bất biến, và kỹ năng viết chúng chuyển được giữa mọi nền tảng. Khi bạn thành thạo tư duy schema, đổi nhà cung cấp chỉ là đổi lớp vỏ.

{
  "name": "search_orders",
  "description": "Tìm đơn hàng của một khách theo email. Chỉ dùng khi người dùng hỏi về đơn hàng CỤ THỂ của họ, không dùng để tra cứu sản phẩm.",
  "parameters": {
    "type": "object",
    "properties": {
      "email": {
        "type": "string",
        "format": "email",
        "description": "Email của khách, ví dụ an@gmail.com"
      },
      "status": {
        "type": "string",
        "enum": ["pending", "shipped", "done", "cancelled"],
        "description": "Lọc theo trạng thái. Bỏ trống nếu khách không nêu."
      }
    },
    "required": ["email"]
  }
}

Các bước viết schema tốt

• Đặt tên hàm bằng động từ rõ nghĩa: create_ticket, get_balance, cancel_order. Tránh do_stuff, helper.
• Viết description như hướng dẫn cho đồng nghiệp mới: nêu khi nào dùng và khi nào KHÔNG dùng. Đây là nơi bạn chống việc chọn nhầm tool (Bài 5).
• Khai báo type chặt: dùng enum cho tập giá trị cố định, format cho email/date, integer thay vì number khi cần số nguyên.
• Đánh dấu required đúng: chỉ những field bắt buộc mới cho vào required. Field tùy chọn phải nói rõ trong description khi nào bỏ trống.
• Mô tả từng field: mỗi property có description riêng, kèm ví dụ giá trị. Model đọc cái này để điền.
• Ràng buộc giá trị: dùng minimum, maximum, pattern, maxLength để chặn đầu vào vô lý ngay từ schema.

Khung tư duy: schema là hợp đồng

Hãy coi schema là hợp đồng ba bên giữa model, code của bạn, và người dùng:

• Với model: nó là tài liệu API — model chỉ biết những gì bạn viết ở đây.
• Với code: nó là lớp validate đầu tiên — dữ liệu vào phải khớp type.
• Với bạn: nó là nơi khai báo ý định — tool này làm gì, giới hạn ở đâu.

Ví dụ: enum cứu bạn khỏi rác

So sánh hai cách khai báo tham số priority:

// TỆ: model có thể điền "gấp", "urgent!!!", "cao", "P0"...
{ "priority": { "type": "string" } }

// TỐT: model buộc chọn 1 trong 3
{ "priority": { "type": "string", "enum": ["low", "medium", "high"] } }

Với enum, bạn không bao giờ phải viết code chuẩn hóa "gấp" thành "high" nữa. Ràng buộc ở schema rẻ hơn ràng buộc ở code.

Checklist review schema trước khi ship

• [ ] Tên hàm là động từ, không trùng nghĩa với tool khác.
• [ ] Description nói rõ khi nào KHÔNG dùng.
• [ ] Mọi field có type chặt (enum/format/integer khi phù hợp).
• [ ] required chỉ chứa field thật sự bắt buộc.
• [ ] Field tùy chọn có hướng dẫn "bỏ trống khi...".
• [ ] Không có field mơ hồ kiểu data, info, params.
• [ ] Số lượng tool ≤ ~10–15 cho một agent (nhiều hơn thì gom nhóm).

Sai lầm thường gặp

• Description quá ngắn. "Tìm đơn hàng" không đủ. Model cần biết ranh giới để không gọi nhầm.
• Dùng string cho mọi thứ. Bỏ enum/format khiến model điền giá trị lung tung, code bạn phải dọn.
• Đưa field không cần vào required. Model sẽ bịa giá trị cho field required nếu người dùng không cung cấp — nguồn gốc của lỗi "hallucinate tham số".
• Tên tool na ná nhau. get_order và find_order cùng tồn tại → model phân vân, chọn sai.
• Schema không khớp code. Bạn thêm field vào schema nhưng hàm thật không đọc nó (hoặc ngược lại). Luôn giữ schema và chữ ký hàm đồng bộ.