Gắn công cụ (tools) để agent hành động thật

Một agent chỉ biết nói thì mới là nửa giá trị. Sức mạnh thật đến khi nó gọi tool: đọc file, tra Google Sheet, gửi Telegram, tạo hóa đơn. Bài này chỉ cách định nghĩa tool và để agent tự quyết khi nào dùng.

Tool hoạt động thế nào

Bạn khai báo cho agent một danh sách hàm, mỗi hàm có: tên, mô tả (khi nào dùng), tham số. Khi cần, agent không tự bịa dữ liệu mà trả về một "yêu cầu gọi tool". Code của bạn chạy hàm thật rồi đưa kết quả lại cho agent.

Vòng lặp: agent nghĩ → gọi tool → nhận kết quả → nghĩ tiếp → ... → trả lời cuối.

Ví dụ: agent tra bảng giá và tạo hóa đơn

tools = [
  {
    "name": "tra_bang_gia",
    "description": "Tra đơn giá theo tên hạng mục. Dùng khi cần biết giá một dịch vụ.",
    "input_schema": {
      "type": "object",
      "properties": {"hang_muc": {"type": "string"}},
      "required": ["hang_muc"]
    }
  },
  {
    "name": "tao_hoa_don",
    "description": "Tạo hóa đơn nháp. CHỈ gọi sau khi người dùng xác nhận.",
    "input_schema": {
      "type": "object",
      "properties": {
        "khach": {"type": "string"},
        "items": {"type": "array"},
        "tong": {"type": "number"}
      },
      "required": ["khach", "items", "tong"]
    }
  }
]

Xử lý khi agent yêu cầu gọi tool:

for block in resp.content:
    if block.type == "tool_use":
        if block.name == "tra_bang_gia":
            gia = BANG_GIA.get(block.input["hang_muc"], None)
            ket_qua = {"gia": gia}
        elif block.name == "tao_hoa_don":
            ket_qua = luu_hoa_don_nhap(block.input)  # KHÔNG gửi
        # gửi ket_qua ngược lại cho agent để nó nghĩ tiếp

Nguyên tắc thiết kế tool tốt

• Mô tả rõ "khi nào dùng" — agent chọn tool dựa vào mô tả, không phải tên.
• Chia nhỏ, đơn nhiệm — một tool làm một việc, dễ kiểm soát.
• Phân loại đọc vs ghi — tool "đọc" (tra giá) an toàn; tool "ghi/gửi" (tạo hóa đơn, gửi email) phải có chốt duyệt.
• Trả lỗi rõ ràng — nếu hàm lỗi, trả message dễ hiểu để agent xử lý, đừng để crash.

Khung phân loại rủi ro tool

Các bước làm

• Liệt kê các hành động agent cần (đọc gì, ghi gì, gửi gì).
• Viết mô tả "khi nào dùng" cho từng tool.
• Code hàm thật cho từng tool, trả kết quả dạng dữ liệu.
• Gắn chốt duyệt cho mọi tool "ra ngoài".
• Test: cho agent một mục tiêu và xem nó chọn đúng tool không.

Sai lầm thường gặp

• Mô tả tool mập mờ: agent gọi nhầm tool hoặc không gọi.
• Tool quá to (một hàm làm 5 việc): khó debug, agent dễ truyền sai tham số.
• Cho tool "gửi/thanh toán" chạy tự do: một lần agent hiểu sai là mất tiền/mất khách.
• Không xử lý lỗi tool: hàm ném exception, cả agent dừng.
• Không log lại lời gọi tool: khi ra kết quả sai, không biết agent đã làm gì.

Checklist

• [ ] Mỗi tool đơn nhiệm, mô tả rõ khi nào dùng
• [ ] Đã phân loại đọc / ghi / ra ngoài
• [ ] Tool ra ngoài có chốt duyệt
• [ ] Có log lời gọi tool

Bài sau: cho agent trí nhớ và ngữ cảnh để làm việc dài hơi hơn.