Phần lớn “agent gọi tool sai” không phải lỗi model. Đó là lỗi hợp đồng: tên mơ hồ, description không nói khi nào dùng, schema cho phép giá trị vô nghĩa, và lỗi trả về không nói cách sửa. Model không đọc code của bạn; nó chỉ thấy tên, description, schema và thông báo lỗi.
Bản gốc của bài này dừng ở lời khuyên “viết unit test và xử lý lỗi”. Điều đó đúng nhưng thiếu phần quan trọng nhất: thiết kế tool như một API công khai, vì với MCP và function calling, tool của bạn thực sự là API công khai cho một client không đọc được source.
Mục lục
Cập nhật 2026
- Tool đã ra khỏi process của bạn. MCP biến tool thành server mà nhiều agent, IDE và team cùng gọi. Tên tool, schema và lỗi là hợp đồng dài hạn, không phải chi tiết nội bộ.
- Framework có typed tool. PydanticAI 2.66.0 dùng
@agent.tool,RunContextvàModelRetry; OpenAI Agents SDK lấy docstring làm description quafunction_tool; MAF và ADK có tool confirmation. Chọn framework nào cũng phải giữ schema chặt. - Eval tool call đã là metric chuẩn. DeepEval 4.3.3 và promptfoo 0.125.1 cho phép chấm tool nào được gọi, tham số nào, thứ tự ra sao — không chỉ chấm câu trả lời cuối.
- Structured output là mặc định, không phải tính năng thêm. Ép JSON Schema và từ chối tham số ngoài enum rẻ hơn nhiều so với việc sửa prompt sau mỗi lần model bịa mã đơn hàng.
Hợp đồng tool có bốn phần
1. Tên. Dùng động từ + đối tượng: get_order, create_ticket, refund_payment. Không viết tắt, không dùng tên trùng nghĩa (fetch_order và get_order_detail là hai tool khác nhau hay một?). Nếu tool nằm trong MCP server dùng chung, thêm namespace để tránh đụng tên.
2. Description. Đây là prompt thật của tool. Nó phải nói bốn thứ: khi nào dùng, khi nào không dùng, tác dụng phụ, và đơn vị/định dạng. Ví dụ: “Lấy một đơn hàng theo mã. Dùng khi đã có mã đơn cụ thể. Không dùng để tìm đơn theo tên khách — dùng search_orders. Chỉ đọc, không thay đổi trạng thái. total_vnd là số nguyên VND.”
Câu “không dùng khi” quan trọng hơn bạn tưởng. Phần lớn lỗi chọn tool là do hai tool có description giống nhau; model không có cách nào phân biệt ngoài văn bản bạn viết.
3. Schema. Kiểu cụ thể, enum cho tập giá trị đóng, required rõ ràng, min/max cho số, format cho ngày và email, additionalProperties: false để chặn field lạ. Nếu một tham số có hai đơn vị (giây và phút), đặt tên theo đơn vị: timeout_seconds. Đừng để model đoán.
4. Kết quả và lỗi. Trả về cấu trúc cố định, chỉ gồm trường cần thiết, có cap kích thước. Lỗi phải máy đọc được: code, retryable, message, hint. "Lỗi hệ thống" không giúp model sửa gì; "invalid_order_id: phải có dạng ORD-####" thì có.
Tool hay workflow?
Không phải mọi bước đều nên là một tool riêng. Nếu quy trình cố định — tra đơn, kiểm tra trạng thái, tính phí, tạo ticket — hãy expose một tool composite như handle_return_request thay vì bốn tool nhỏ. Mỗi tool thêm vào là một lựa chọn nữa cho model, và lựa chọn là nơi sinh ra lỗi.
Ngược lại, nếu các bước cần rẽ nhánh theo dữ liệu hoặc người dùng phải can thiệp giữa đường, giữ chúng tách biệt để còn đặt approval và timeout. Tiêu chí không phải “tool nhỏ thì tốt” hay “tool lớn thì gọn”, mà là ai kiểm soát thứ tự: code hay model. Nếu code biết thứ tự, đừng giao quyền chọn cho model.
Ba lỗi thiết kế hay gặp
Tool vạn năng với tham số action. Một tool manage_order(action, payload) nghe tiết kiệm nhưng biến schema thành union lồng nhau, khiến model phải đoán payload nào đi với action nào. Hãy tách thành các tool có schema riêng; số tool tăng nhưng xác suất gọi đúng cũng tăng.
Trả về cả object. Một API trả 40 field, agent chỉ cần 4. Phần còn lại đẩy context lên, che mất thông tin quan trọng và tăng chi phí mỗi bước. Projection ở nguồn, hoặc ít nhất map sang một view nhỏ trước khi trả về model.
Description mô tả implementation. “Gọi endpoint /v2/orders với bearer token” không giúp model chọn tool. Model cần biết mục đích nghiệp vụ và điều kiện sử dụng. Viết description cho người mới tiếp nhận hệ thống, không phải cho người đã đọc code.
Code trước, model sau
Nguyên tắc rẻ nhất trong toàn bộ bài: nếu code xác định làm được, đừng hỏi model. Model dùng cho thứ mơ hồ — phân loại ý định, trích xuất từ văn bản tự do, tóm tắt, viết lại. Code dùng cho thứ có quy tắc — tính tiền, parse ngày, kiểm tra mã, sắp xếp, so khớp.
| Việc | Công cụ | Lý do |
|---|---|---|
| Parse ngày theo format cố định | Code | Không có ambiguity, sai thì raise |
| Tính thuế, tổng tiền | Code | Decimal, không để model làm số học |
| Phân loại ý định từ email | Model | Ngôn ngữ tự do, nhiều cách diễn đạt |
| Trích field từ hợp đồng | Model + schema | Model đọc, Pydantic validate |
| Kiểm tra quyền truy cập | Code | Không bao giờ giao cho model |
| Quyết định ngoại lệ hoàn tiền | Model + policy gate | Model đề xuất, code và người duyệt |
Mô hình hybrid đúng là: model đề xuất, code kiểm tra, người duyệt khi cần. Đừng đảo thành “model quyết định, code ghi log”. Một tool tính tiền gọi model để cộng số là một lỗi thiết kế, không phải một lỗi prompt.
Một tool có kiểu, đầy đủ
# File: tools/orders.py — pydantic-ai 2.66.0
# Repo: lop truy cap du lieu cua ban, co tenant_id bat buoc
from pydantic import BaseModel
from pydantic_ai import Agent, ModelRetry, RunContext
class Order(BaseModel):
id: str
status: str
total_vnd: int
agent = Agent("openai:gpt-6.1-sol", deps_type=Repo, output_type=str)
@agent.tool
async def get_order(ctx: RunContext[Repo], order_id: str) -> Order:
"""Lay mot don hang theo ma. Dung khi da co ma don cu the.
Khong dung de tim don theo ten khach hay so dien thoai."""
if not order_id.startswith("ORD-"):
raise ModelRetry("order_id phai co dang ORD-####. Hoi lai nguoi dung.")
row = await ctx.deps.orders.get(order_id, tenant_id=ctx.deps.tenant_id)
if row is None:
raise ModelRetry(f"Khong thay {order_id} trong tenant nay.")
return Order(**row)
Ba chi tiết đáng chú ý. ModelRetry trả lỗi về cho model kèm hướng sửa, thay vì ném exception làm chết lượt chạy. tenant_id lấy từ RunContext, không lấy từ tham số do model truyền — model không được phép chọn tenant. Và output là Pydantic model, nên nếu database trả field lạ, lỗi nổi lên ngay tại boundary thay vì trôi vào context.
Test tool, không chỉ test agent
Tool cần bốn lớp test. Unit: schema từ chối input sai, error mapping đúng, truncation không cắt giữa cấu trúc, kiểm tra tenant. Contract: fixture HTTP đã ghi lại cho 200, 400, 401, 429, 500 và JSON hỏng. Failure injection: timeout, 429 kèm Retry-After, body cụt, gọi trùng, permission denied, kết quả rỗng. Eval: chấm tool-call accuracy — tool nào, tham số nào, thứ tự nào — bằng DeepEval hoặc promptfoo trong CI.
Thêm một assertion ít ai viết: lỗi và log không được chứa token, stack trace nội bộ hay dữ liệu của tenant khác. Đây là test bảo mật rẻ nhất bạn có thể thêm vào hôm nay.
Đừng mock toàn bộ HTTP client ở mọi test. Contract test với fixture thật bắt được thay đổi response schema — thứ mà mock viết tay không bao giờ bắt được vì mock phản ánh giả định của bạn, không phản ánh API thật.
Versioning và deprecation
Tool là API. Đổi ý nghĩa của một tham số là breaking change, kể cả khi schema không đổi. Đổi đơn vị từ đồng sang nghìn đồng, đổi status từ enum cũ sang enum mới, đổi thứ tự ưu tiên khi có nhiều kết quả — tất cả đều làm agent chạy sai mà không có lỗi schema nào.
Quy tắc: chỉ thêm field optional, thêm enum value khi model đã biết, giữ tên cũ như alias trong một chu kỳ, ghi deprecation trong description kèm ngày sunset, và log tool_version trong trace. Khi xóa, xóa theo lịch đã công bố — đừng xóa im lặng vì “ít người dùng”. Agent không đọc changelog.
Observability: đo từng tool call
Mỗi call nên ghi: tên tool và version, tenant, args đã redact hoặc hash, latency, status, số lần retry, bytes vào/ra, và chi phí nếu bên trong tool có gọi model. Metric quan trọng nhất không phải số call mà là tỷ lệ call thành công trên mỗi task, p95 latency, và phân phối error code.
Đặt alert theo ba tín hiệu: schema validation failure tăng, một error code xuất hiện liên tục, và retry rate vượt ngưỡng. Cả ba đều là dấu hiệu hợp đồng tool đang lệch với thực tế, không phải dấu hiệu “model ngu đi”.
Không log payload đầy đủ. Lưu hash và sample đã redact; khi cần điều tra, dùng trace ID để truy vết thay vì bật log toàn bộ trên production.
Chi phí và độ trễ
- Trả về đúng trường cần dùng, projection ở nguồn thay vì tải cả object rồi cắt ở agent.
- Cache read có TTL, key theo tenant + args; không cache kết quả phụ thuộc quyền người dùng.
- Chạy song song các call độc lập, nhưng cap concurrency để không đánh sập API đích.
- Timeout từng call và ngân sách tổng cho task; retry có backoff và chỉ với lỗi idempotent.
- Đo cost per successful task, không phải cost per call — một tool rẻ mà fail liên tục là tool đắt.
Nhìn tới 2027
Hợp đồng tool sẽ chuẩn hóa hơn nhờ MCP và các format mô tả agent, nhưng điều đó không thay bạn thiết kế schema. Xu hướng rõ là tool có version, provenance và confirmation như một phần của giao thức, không phải tính năng riêng của framework. Chuẩn bị trước bằng cách đặt tên, schema và error code nghiêm túc ngay từ tool đầu tiên.
Checklist
- Tên là động từ + đối tượng, không trùng nghĩa, có namespace nếu dùng chung.
- Description nói khi nào dùng, khi nào không, side effect và đơn vị.
- Schema chặt: enum, min/max, required,
additionalProperties: false. - Output bounded, lỗi có
code/retryable/hint. - Việc xác định giao cho code; model chỉ xử lý phần mơ hồ.
- Có unit, contract, failure injection và eval tool-call trong CI.
- Version trong trace; deprecation có lịch và alias.
- Log redact; alert theo schema failure và retry rate.
Đọc tiếp
Hợp đồng đầu vào/đầu ra được viết chi tiết trong thiết kế công cụ cho AI Agent. Khi tool đã ổn, đọc web search, REPL và API trong agent để xử lý boundary và quyền. Và để kiểm thử toàn bộ vòng lặp, xem kiểm thử agent: unit, tích hợp và con người trong vòng lặp.
