Bài 4 — Định nghĩa Tool: trao tay chân cho agent

Tool (công cụ) là cầu nối giữa "bộ não" LLM và thế giới thật. Không có tool, agent chỉ biết nói. Bài này bạn định nghĩa tool đầu tiên và làm cho LLM biết cách gọi nó.

Một tool gồm những gì?

Tool = Tên + Mô tả + Tham số (schema) + Hàm thực thi

• Tên: định danh, ví dụ lookup_order.
• Mô tả: câu văn giải thích tool làm gì và khi nào dùng — LLM đọc cái này để quyết định.
• Schema tham số: kiểu dữ liệu đầu vào, giúp LLM điền đúng.
• Hàm thực thi: code Python thật sự chạy.

Ví dụ: tool tra cứu thời tiết

def get_weather(city: str) -> str:
    # Bản demo: dữ liệu giả để test an toàn
    fake = {"Hanoi": "28C, nắng", "Da Nang": "31C, ít mây"}
    return fake.get(city, "Không có dữ liệu cho thành phố này")

TOOLS = {
    "get_weather": {
        "fn": get_weather,
        "description": "Tra thời tiết hiện tại theo tên thành phố (tiếng Anh không dấu).",
        "parameters": {"city": "str - tên thành phố, ví dụ 'Hanoi'"},
    }
}

Cho LLM biết về tool

Có hai cách:

• Native function calling (khuyến nghị): nhiều API hỗ trợ truyền danh sách tool dưới dạng JSON schema, LLM trả về lời gọi có cấu trúc.
• Prompt-based (dễ hiểu để học): mô tả tool trong system prompt và yêu cầu LLM xuất JSON khi muốn gọi.

Ví dụ prompt-based, ta ép agent xuất JSON:

Khi cần dùng công cụ, chỉ xuất DUY NHẤT một JSON:
{"action": "get_weather", "args": {"city": "Hanoi"}}
Khi đã đủ thông tin để trả lời, xuất:
{"action": "final", "answer": "..."}

Các bước xây tool

• Viết hàm Python làm một việc rõ ràng, trả về chuỗi/JSON.
• Viết mô tả tool như thể giải thích cho một thực tập sinh: làm gì, khi nào dùng, đầu vào gì.
• Định nghĩa schema tham số chặt (kiểu, ví dụ, bắt buộc hay không).
• Bắt đầu bằng phiên bản giả lập (trả dữ liệu cứng) để test vòng lặp an toàn.
• Validate đầu vào trong hàm: nếu thiếu/sai, trả thông báo lỗi rõ ràng thay vì crash.
• Chỉ nối vào API/hệ thống thật sau khi vòng lặp đã chạy đúng với bản giả.

Khung tư duy: viết mô tả tool như viết cho người

Mô tả tốt = Động từ hành động + Đầu vào + Đầu ra + Điều kiện dùng

Ví dụ: "Gửi email xác nhận (đầu vào: địa chỉ, tiêu đề, nội dung; đầu ra: trạng thái gửi). Dùng khi đơn hàng đã được xử lý xong." LLM chọn tool chủ yếu dựa vào mô tả — mô tả kém là nguyên nhân số một khiến agent gọi sai tool.

Checklist một tool tốt

• [ ] Làm một việc duy nhất, tên là động từ.
• [ ] Mô tả nói rõ khi nào dùng.
• [ ] Tham số có kiểu và ví dụ.
• [ ] Hàm không crash: lỗi thì trả chuỗi báo lỗi.
• [ ] Có bản giả lập để test trước khi nối hệ thống thật.

Sai lầm thường gặp

• Tool ôm đồm nhiều việc ("quản lý đơn hàng") khiến LLM khó chọn và điền tham số. Tách nhỏ.
• Mô tả tool sơ sài, LLM đoán mò khi nào dùng.
• Hàm ném exception ra ngoài làm sập cả vòng lặp; hãy bọc try/except và trả thông báo lỗi dạng chuỗi để agent tự xử lý.
• Nối thẳng tool gây hậu quả thật (xóa DB, gửi tiền) khi đang test — luôn có chế độ "dry-run".
• Trả về dữ liệu quá dài/thô (cả trang HTML) làm ngập context; hãy tóm tắt hoặc trích xuất trước khi trả cho LLM.

Đã có tool. Bài 5 chúng ta ghép mọi thứ lại thành vòng lặp agent chạy tự động.