Bài 3 — Định nghĩa tool đúng chuẩn
Chất lượng agent phụ thuộc trực tiếp vào chất lượng định nghĩa tool. Model chọn tool và điền tham số dựa trên tên tool, mô tả (description) và JSON schema bạn cung cấp. Mô tả mơ hồ = model gọi sai tool hoặc điền sai tham số.
Anthropic: khai báo tool tường minh
tools = [{
"name": "tao_ma_giam_gia",
"description": (
"Tạo mã giảm giá cho một khách hàng. Dùng KHI khách yêu cầu "
"ưu đãi và đã xác thực danh tính. KHÔNG dùng để tra cứu mã cũ."
),
"input_schema": {
"type": "object",
"properties": {
"customer_id": {"type": "string", "description": "ID khách, dạng CUS-xxxx"},
"percent": {"type": "integer", "minimum": 5, "maximum": 50,
"description": "Phần trăm giảm, 5-50"},
},
"required": ["customer_id", "percent"],
},
}]
Chú ý ba điều: (1) description nói khi nào DÙNG và khi nào KHÔNG, (2) mỗi field có description riêng, (3) minimum/maximum ràng buộc để model không điền số vô lý.
OpenAI Agents SDK: schema tự sinh từ type hint
from agents import function_tool
from typing import Literal
@function_tool
def tao_ma_giam_gia(customer_id: str, percent: int) -> str:
"""Tạo mã giảm giá cho khách đã xác thực.
Args:
customer_id: ID khách, dạng CUS-xxxx.
percent: Phần trăm giảm, hợp lệ 5-50.
"""
if not (5 <= percent <= 50):
return "Lỗi: percent phải trong khoảng 5-50"
return f"Đã tạo mã SALE{percent} cho {customer_id}"
SDK đọc type hint + docstring để sinh schema. Docstring chính là description model nhìn thấy — viết cho model đọc, không chỉ cho người.
Nguyên tắc đặt tên và mô tả
- Tên tool = động từ + đối tượng:
tao_ma_giam_gia,tra_cuu_don_hang. Tránhhandle,process,do_stuff. - Description trả lời: dùng khi nào, không dùng khi nào, trả về gì.
- Ràng buộc trong schema (enum, min/max, pattern) thay vì chỉ dặn trong prompt — model tuân schema tốt hơn tuân lời dặn.
- Trả lỗi dưới dạng dữ liệu, không raise exception thô: trả chuỗi/JSON mô tả lỗi để model tự sửa và thử lại.
- Validate lại trong hàm: model có thể vẫn điền sai; code là lớp phòng thủ cuối.
Ví dụ: lỗi trả về giúp model tự sửa
@function_tool
def tra_cuu_don_hang(order_id: str) -> str:
if not order_id.startswith("ORD-"):
return '{"error": "order_id phải bắt đầu bằng ORD-", "hint": "ví dụ ORD-1234"}'
...
Khi nhận lỗi này, model thường tự hỏi lại người dùng hoặc sửa định dạng rồi gọi lại — đúng tinh thần agent.
Bao nhiêu tool là quá nhiều?
Model chọn tool bằng cách so khớp yêu cầu với tên và mô tả của từng tool. Khi danh sách tool quá dài hoặc nhiều tool na ná nhau (tra_cuu_don, tim_don_hang, lay_thong_tin_don), tỉ lệ chọn nhầm tăng vọt. Kinh nghiệm thực chiến: giữ mỗi agent dưới khoảng 7-10 tool có ranh giới rõ ràng. Nếu cần nhiều hơn, đó là dấu hiệu nên tách thành nhiều agent qua handoff (Bài 5). Trước khi thêm một tool mới, hãy hỏi: nó có chồng lấn với tool nào đang có không? Nếu có, hãy gộp lại hoặc làm mô tả phân biệt thật rõ để model không lưỡng lự.
Trả về ngắn gọn, có cấu trúc
Output của tool sẽ được nhồi lại vào ngữ cảnh model ở vòng sau, tốn token và có thể làm loãng thông tin. Đừng trả cả một cục JSON 500 dòng khi model chỉ cần trạng thái đơn và ngày giao. Trả đúng thứ model cần để ra quyết định tiếp theo — vừa tiết kiệm token vừa giúp model tập trung.
Checklist một tool tốt
- [ ] Tên là động từ + đối tượng, không mơ hồ.
- [ ] Description nêu rõ dùng/không-dùng và giá trị trả về.
- [ ] Mỗi tham số có description và ràng buộc (enum/min/max/pattern).
- [ ] Hàm validate đầu vào, trả lỗi dạng dữ liệu chứ không crash.
- [ ] Có unit test chạy độc lập với model.
- [ ] Idempotent hoặc có cơ chế chống gọi trùng nếu tool ghi dữ liệu.
Sai lầm thường gặp
- Description dạng "tra cứu thông tin" quá chung → model gọi nhầm tool khác cũng "tra cứu".
- Không ràng buộc schema, chỉ dặn trong prompt → model điền số/enum sai.
- Raise exception thô → SDK báo lỗi, agent dừng thay vì tự phục hồi.
- Tool ghi dữ liệu nhưng không idempotent → model gọi 2 lần tạo 2 mã giảm giá.
- Nhồi 20 tool na ná nhau → model rối, chọn sai; hãy gộp/đặt tên phân biệt rõ.