Tool Use chuyên sâu — Thiết kế công cụ cho Agent
Tool là giao diện giữa agent và thế giới. Nguyên tắc thiết kế tool để model dùng đúng: gom theo việc cần làm, đặt tên, mô tả, định dạng kết quả, lỗi có hướng dẫn.
Khi một agent hoạt động kém, phản xạ đầu tiên thường là sửa system prompt. Trong thực tế, nguyên nhân hay nằm ở tool: mô tả mơ hồ, hai tool chồng chéo chức năng, kết quả trả về 20.000 token JSON thô, lỗi chỉ nói "400 Bad Request". Đội xây agent giỏi dành thời gian cho giao diện agent-máy (ACI) nhiều như đội frontend dành cho giao diện người-máy. Tool tốt làm một model trung bình chạy ổn; tool tồi làm model tốt nhất cũng loay hoay.
🎯 Mục tiêu học tập
- Thiết kế bộ tool theo 'việc agent cần làm' thay vì bọc 1-1 từng API endpoint
- Viết tên, mô tả, và schema tham số đủ rõ để model chọn đúng tool và điền đúng tham số
- Thiết kế kết quả trả về tiết kiệm context: đúng trọng tâm, có phân trang, có định danh dùng lại được
- Trả lỗi theo cách giúp agent tự sửa, và phân biệt tool đọc/ghi để đặt quyền phù hợp
- Biết khi nào dùng bash/code thay cho tool chuyên biệt, và cách xử lý khi có hàng trăm tool
Tool không phải là API wrapper
API truyền thống được thiết kế cho lập trình viên: nhiều endpoint nhỏ, trả đủ mọi trường, lập trình viên tự ghép lại. Agent thì khác: mỗi lần gọi tool tốn một vòng lặp (tiền + độ trễ), và mọi byte trả về chiếm chỗ trong context. Vì vậy:
| Thay vì (bọc API 1-1) | Hãy làm (gom theo việc cần làm) |
|---|---|
list_users + list_events + create_event | schedule_meeting — tự tìm khung giờ trống và đặt lịch |
read_logs trả toàn bộ log | search_logs(query, since) trả các dòng khớp kèm vài dòng ngữ cảnh |
get_customer_by_id + list_transactions + list_notes | get_customer_context — gộp thông tin gần đây, liên quan nhất |
list_contacts (trả 5.000 dòng để agent tự lọc) | search_contacts(name) |
Ít tool nhưng mỗi tool đáng giá tốt hơn nhiều tool vụn. Mỗi tool thêm vào là một lựa chọn nữa model phải cân nhắc ở mọi bước; hai tool na ná nhau là nguồn nhầm lẫn số một.
Đưa bộ tool (chỉ tên, mô tả, tham số) cho một đồng nghiệp chưa biết hệ thống. Nếu họ phải hỏi "cái này khác cái kia chỗ nào?" hay "tham số này điền gì?" — model cũng sẽ vướng đúng chỗ đó.
Tên, mô tả, tham số — phần prompt quan trọng nhất mà ít ai coi là prompt
Định nghĩa tool được nạp vào context ở mọi bước. Viết nó như viết tài liệu onboarding:
{
"name": "orders_search", # tiền tố theo miền: orders_*, billing_*
"description": (
"Tìm đơn hàng theo email khách hoặc khoảng ngày. Trả tối đa 20 đơn mới nhất, "
"mỗi đơn gồm mã đơn, ngày, trạng thái, tổng tiền. "
"Dùng khi khách hỏi về đơn mà chưa cho mã đơn. "
"Nếu đã có mã đơn, dùng orders_get để lấy chi tiết thay vì tool này. "
"Trạng thái hợp lệ: pending, paid, shipped, delivered, refunded."
),
"input_schema": {
"type": "object",
"properties": {
"customer_email": {"type": "string", "description": "Email đăng ký tài khoản, ví dụ an@example.com"},
"placed_after": {"type": "string", "description": "Chỉ lấy đơn đặt sau ngày này, định dạng YYYY-MM-DD"},
"status": {"type": "string", "enum": ["pending", "paid", "shipped", "delivered", "refunded"]},
},
"required": ["customer_email"],
"additionalProperties": False,
},
"strict": True, # đảm bảo tham số model sinh ra luôn khớp schema
}
- Mô tả nói cả "khi nào dùng" lẫn "khi nào không", và nhắc tên tool thay thế. Model hiện đại rất bám sát mô tả — mô tả là nơi điều chỉnh hành vi gọi tool hiệu quả nhất.
- Tên tham số tự giải thích:
customer_emailthay vìq,user_idthay vìuser. Dùngenumcho tập giá trị đóng. - Tiền tố theo miền (
orders_,jira_) giúp model không lẫn khi có nhiều nguồn tool cùng lúc. - Nêu rõ định dạng (ngày, đơn vị tiền, múi giờ) ngay trong mô tả tham số.
strict: trueđảm bảo tham số luôn hợp lệ theo schema; bạn vẫn phải kiểm tra tính hợp lệ nghiệp vụ (đơn đó có thuộc về người đang hỏi không).
Thiết kế kết quả trả về
- Trả thứ có nghĩa, không trả thứ thô:
"name": "Nguyễn An"hữu ích hơn"uuid": "9f3c...". Chỉ trả ID khi agent cần dùng nó cho lần gọi sau — và khi đó dùng ID ngắn, dễ đọc. - Bỏ trường thừa:
created_by_internal_ref, URL ảnh thumbnail, metadata hệ thống... mỗi trường thừa nhân lên qua hàng chục lần gọi. - Phân trang và cắt bớt có hướng dẫn: đặt mặc định hợp lý (20 dòng, vài nghìn token),
và khi cắt thì nói rõ cách lấy phần còn lại: "Hiển thị 20/312 kết quả. Thu hẹp bằng tham số
statushoặc dùngpage=2." - Cho agent chọn mức chi tiết khi cần: tham số
response_formatnhận"concise"(mặc định) hoặc"detailed". - Định dạng nhất quán: chọn một kiểu (JSON gọn, hoặc bảng văn bản) và giữ cho mọi tool. Thử cả hai trong eval — định dạng model đọc tốt nhất không phải lúc nào cũng là JSON.
Lỗi là lời hướng dẫn
| Lỗi vô dụng | Lỗi giúp agent tự sửa |
|---|---|
400 Bad Request | placed_after phải có dạng YYYY-MM-DD, nhận được "tuần trước". Hôm nay là 2026-10-08. |
KeyError: 'DH-88' | Không có đơn DH-88. Mã đơn có dạng DH-xxxxxx (6 chữ số). Dùng orders_search để tìm theo email. |
Permission denied | Tài khoản hiện tại không có quyền hoàn tiền trên 2.000.000đ. Hãy chuyển cho nhân viên bằng tool escalate_to_human. |
Phân biệt hai loại thất bại: lỗi agent sửa được (sai tham số, không tìm thấy) → trả
về với is_error: true và lời hướng dẫn; lỗi hạ tầng (database sập, hết quota)
→ harness tự retry có backoff, và nếu vẫn hỏng thì báo cho agent rằng tool tạm thời không dùng được để nó
đổi hướng hoặc dừng, thay vì để nó thử lại vô tận.
Tool đọc, tool ghi, và tool không thể hoàn tác
| Loại | Ví dụ | Chính sách mặc định |
|---|---|---|
| Chỉ đọc | search, get, list | Tự do gọi; có thể chạy song song |
| Ghi, hoàn tác được | sửa file trong sandbox, tạo bản nháp | Cho phép, có log; chạy tuần tự |
| Ghi, khó/không hoàn tác | gửi email, chuyển tiền, xoá dữ liệu, deploy | Cần người duyệt hoặc luật cứng (Module 14) |
- Idempotency: agent có thể gọi lại cùng một tool khi không chắc lần trước thành công.
Tool ghi nên nhận
idempotency_keyhoặc tự kiểm tra trùng — đúng kỹ thuật bạn đã học ở khoá Backend API. - Tách "chuẩn bị" và "thực thi":
draft_refund(trả về bản xem trước) rồiconfirm_refund(draft_id). Bước xác nhận là chỗ tự nhiên để gắn cổng duyệt. - Kiểm tra quyền ở phía tool, theo danh tính người dùng — không bao giờ tin rằng "prompt đã dặn agent chỉ xem đơn của khách này".
Bash, code, và hàng trăm tool
Bash/code so với tool chuyên biệt. Một tool bash (hoặc chạy code trong
sandbox) cho agent khả năng gần như vô hạn chỉ với một định nghĩa tool — model vốn rất thạo dòng lệnh.
Đổi lại, harness chỉ thấy một chuỗi lệnh mờ đục, khó duyệt và khó kiểm soát. Quy tắc: bắt đầu bằng
bash/code cho độ phủ, rồi nâng một hành động lên thành tool riêng khi bạn cần chặn duyệt,
hiển thị riêng, ghi audit, hoặc chạy song song hành động đó. send_email là tool
riêng thì dễ gắn cổng duyệt; bash -c "curl -X POST ..." thì không.
Gọi tool bằng code (programmatic tool calling). Khi cần 30 lần gọi nối tiếp mà kết quả trung gian không quan trọng, để model viết một đoạn script gọi các tool như hàm, chạy trong sandbox, và chỉ kết quả cuối quay về context. Giảm mạnh cả token lẫn số vòng lặp.
Khi có quá nhiều tool. 5 MCP server × 30 tool = 150 định nghĩa, hàng chục nghìn token nạp vào mỗi request trước khi agent làm gì. Giải pháp là tool search: chỉ nạp sẵn vài tool cốt lõi cùng một tool tìm kiếm; các tool còn lại được đánh dấu nạp trễ và chỉ đưa schema vào context khi agent tìm ra chúng. Cùng họ ý tưởng "nạp theo nhu cầu" với Skills (Module 4, 9).
Cải thiện tool bằng cách đọc transcript
Quy trình lặp thực tế:
- Viết bản đầu của tool, chạy agent trên 10-20 nhiệm vụ thật.
- Đọc transcript từng bước. Tìm: agent chọn sai tool? gọi thừa? điền sai tham số? bối rối sau khi nhận kết quả? gọi lại cùng một thứ nhiều lần?
- Sửa tool trước khi sửa prompt: đổi tên, viết lại mô tả, gộp hai tool, rút gọn kết quả.
- Chạy lại bộ nhiệm vụ, so số bước, token, tỉ lệ thành công (Module 13).
Mẹo: đưa transcript cho chính một model và hỏi "tool nào khiến agent bối rối, đề xuất sửa mô tả thế nào?" — model thường chỉ ra đúng chỗ, vì nó chính là "người dùng" của các tool đó.
🏋️ Bài tập thực hành
Lấy một REST API bạn quen (GitHub, Jira, hoặc API nội bộ). Bước 1: bọc 8-10 endpoint thành tool theo kiểu 1-1 với mô tả một dòng, chạy agent trên 10 nhiệm vụ (ví dụ "tìm các issue bug chưa ai nhận trong 2 tuần qua và tóm tắt theo mức độ nghiêm trọng"), ghi lại số bước, token, tỉ lệ thành công. Bước 2: thiết kế lại thành 3-5 tool theo việc cần làm, viết mô tả đầy đủ, rút gọn kết quả, viết lại thông báo lỗi. Chạy lại cùng 10 nhiệm vụ và lập bảng so sánh trước/sau. Giữ lại bảng này — nó là bằng chứng tốt trong portfolio.
📚 Tài nguyên học tập
-
Anthropic — Writing effective tools for agentsNguyên tắc thiết kế tool và quy trình cải thiện tool bằng evalBài viết
-
Claude Docs — Define toolsChi tiết định nghĩa tool, schema, strict, tool_resultDocs
-
Anthropic — Advanced tool useTool search, programmatic tool calling, ví dụ sử dụng toolBài viết
-
SWE-agent paper — Agent-Computer InterfaceNghiên cứu cho thấy thiết kế giao diện tool ảnh hưởng lớn thế nào tới hiệu năng agentPaper
✅ Tự đánh giá hoàn thành
- Bộ tool của mình được gom theo việc cần làm, không có hai tool chồng chéo chức năng
- Mỗi mô tả tool nói rõ khi nào dùng, khi nào không, và định dạng tham số
- Kết quả tool có giới hạn kích thước, phân trang, và thông báo cắt bớt có hướng dẫn
- Mọi thông báo lỗi đều cho agent biết bước tiếp theo nên làm gì
- Đã phân loại tool đọc/ghi/không hoàn tác và có chính sách riêng cho từng loại