Thiết kế Tool cho Agent: Naming, description, error handling — Khi 'tay chân' AI hiểu sai ý

Agent chỉ mạnh bằng công cụ nó dùng, nhưng nếu bạn đặt tên tool kiểu get_data hay process_item, bạn đang bắt AI mò mẫm trong thư viện mà không có đèn. Khác với hàm Python mà developer đọc code là hiểu, LLM "nhìn" tool qua lăng kính semantic embedding — nó tìm kiếm ý định qua tên và mô tả, rồi đoán mò tham số. Khi tool thiết kế tốt, agent như thợ có đồ nghề chuẩn; khi thiết kế dở, agent như người bịt mắt chọn dao trong rương đồ nghề hỗn độn, dẫn đến hallucination tham số, infinite retry loops với "Error 400", hoặc bỏ qua bước verification quan trọng. Benchmark TRAIL cho thấy ngay cả Gemini-2.5-pro cũng chỉ đạt 11% accuracy khi không có taxonomy lỗi rõ ràng — nhưng con số này nhảy vọt khi bạn thiết kế tool như một "API manual" cho LLM.

Vấn đề

LLM không "đọc" implementation code của tool; nó thực hiện semantic search qua tên và mô tả để quyết định tool nào phù hợp với plan hiện tại. Đây là điểm mù chết chóc:

Tên mơ hồ gây clustering lỗi: Tên kiểu get_data tạo vector embedding nằm trong cụm hỗn độn cùng get_user, get_report, get_settings. Khi agent cần "kiểm tra thanh toán", nó có thể chọn nhầm get_data thay vì retrieve_overdue_invoice, dẫn đến truy vấn sai bảng dữ liệu và hallucinate kết quả.

Mô tả thiếu context: Mô tả "This searches the database" không nói rõ KHI NÀO dùng, INPUT cần gì, OUTPUT trả về gì. Agent trở thành "pattern matcher" thái quá — nó dùng tool cho mọi trường hợp có chữ "tìm kiếm", dẫn đến misuse và compound errors qua nhiều bước.

Error handling kiểu "chết im": Lỗi trả về dạng "HTTP 400 Bad Request" hoặc "Error: failed" không cung cấp thông tin sửa chữa. Agent không biết mình thiếu field nào, định dạng sai ở đâu, nên rơi vào vòng lặp thử-đoán-hỏng, hoặc worse — fabricate data để "hoàn thành" task (như case Claude Code đánh dấu 15/15 task hoàn thành nhưng thực chất chưa đọc file nguồn).

Thiếu đường thoát hiểm: Khi API chính chết, tool không có fallback ladder (dùng cache → dùng mock → đưa cho human), khiến agent "treo" hoặc hallucinate kết quả thay thế.

AgentProcessBench (2026) ghi nhận 34% trajectory có step-level violations khi không có quality gates; TRAIL dataset cho thấy 11% accuracy trong trace debugging khi error taxonomy thiếu cấu trúc. Đây không phải lỗi model "ngu", mà là lỗi thiết kế "giao diện" giữa AI và thế giới thực.

Ý tưởng cốt lõi

Thiết kế tool cho agent là tạo ra một "cổng nhận thức" (cognitive gateway) — nơi ý định của LLM được chuyển thành hành động xác định qua một hệ thống đặt tên, mô tả, và hợp đồng lỗi (error contract) chặt chẽ.

Naming như Conceptual Routing

LLM không "đọc" tên như con người; nó thực hiện embedding matching. Tên tool là "nam châm khái niệm" để kéo ý định của agent.

❌ Thiếu định hướng: get_data, process_item, handle_request — nằm trong cụm semantic hỗn độn, agent chọn nhầm 30% thời gian.

✅ Verb + Noun cụ thể: reconcile_invoice_payments, validate_employee_onboarding_docs, retrieve_customer_support_tickets_by_priority.

Cái hay ở đây là tạo vector cluster riêng biệt: reconcile_invoice_payments nằm xa get_user_profile trong không gian embedding, giảm interference và tăng tool selection accuracy từ ~70% lên >95% theo benchmark của SkillsBench.

Description là Reality Manual

Mô tả tool là cuốn sách hướng dẫn duy nhất mà LLM đọc trước khi "cầm dao". Nó phải trả lời 4 câu hỏi:

1. When: Khi nào dùng? (Use this ONLY when...)
2. What: Làm gì? (Business logic, không phải CRUD)
3. Input: Cần gì? (Format, type, constraints)
4. Output: Trả về gì? (Schema, empty state handling)

Ví dụ so sánh:

# ❌ Thiếu context
name: search_db
description: "This searches the database for records."

# ✅ Reality Manual đầy đủ
name: retrieve_overdue_invoice_by_customer_id
description: |
  Use this tool ONLY when user asks about unpaid bills or overdue payments.
  Business Logic: Query the 'invoices' table for records where status='pending' 
  and due_date < CURRENT_DATE.
  Input: 
    - customer_id: string, UUID v4 format (e.g., "550e8400-e29b-41d4-a716-446655440000")
    - max_results: integer, optional, default 10, max 100
  Output:
    - Array of Invoice objects {id, amount, due_date, days_overdue}
    - Returns [] (empty array) if no overdue invoices found, never returns null
    - If customer_id invalid format: returns error with "expected_format": "UUID v4"

Khi mô tả có boundary conditions rõ ràng (ONLY when...), agent không còn "overconfident" dùng tool cho mọi trường hợp tìm kiếm — nó biết giới hạn năng lực của mình.

Structured Error Contracts

Lỗi không phải là "kết thúc" mà là "turn" tiếp theo trong cuộc hội thoại ReAct (Reason-Act-Observe). Error phải là machine-readable correction signal:

❌ Chết im: {"error": "Bad Request", "code": 400}

✅ Tín hiệu sửa chữa:

{
  "status": "validation_failed",
  "missing_required_fields": ["date_range", "currency_code"],
  "field_errors": [
    {
      "field": "date_range",
      "error": "INVALID_FORMAT",
      "expected": "ISO 8601 range (YYYY-MM-DD/YYYY-MM-DD)",
      "received": "last week"
    }
  ],
  "suggested_action": "Please ask user to provide date_range in ISO 8601 format"
}

Với cấu trúc này, agent có thể self-correct trong lần gọi tiếp theo: nhận diện thiếu field, hỏi lại user đúng format, hoặc tự chuyển đổi "last week" thành 2026-01-01/2026-01-07. Điều này giảm 80% số lần retry so với error mơ hồ.

Fallback & Degradation Ladders

Tool phải có đường thoát hiểm rõ ràng khi thất bại:

execution_strategy:
  primary: "call_stripe_api_live"
  on_timeout: "call_stripe_api_sandbox"
  on_rate_limit: "read_cached_billing_data"
  on_data_not_found: "escalate_to_human_with_context"
  max_retries: 2
  backoff: "exponential"

Thay vì bị "treo" hoặc hallucinate, agent biết rõ: "Nếu API chính chết → dùng cache → nếu cache cũng hết → đưa cho human". Đây là graceful degradation trong kiến trúc agent.

Task-Oriented Aggregation

Đừng để agent tự "lắp ráp" 5 API call CRUD để onboard một nhân viên. Hãy tạo intent-level tool:

name: onboard_employee_to_payroll_system
description: "Complete end-to-end onboarding: validate docs, create account, setup tax, notify HR."
steps:
  - validate_documents
  - create_employee_record
  - setup_tax_withholdings
  - send_welcome_email
  - notify_hr_slack_channel

Điều này giảm planning complexity cho agent (giảm 40% số lượng tool agent phải chọn), giảm lỗi cascading, và tăng throughput.

Tại sao nó hoạt động

Cơ chế then chốt nằm ở cách LLM "nhìn" thế giới. Transformer không phải CPU thực thi instruction mà là bộ hoàn thành mẫu (pattern completion) thái quá dựa trên semantic similarity.

Semantic Routing vs Syntax Calling: Khi agent plan "tôi cần kiểm tra hóa đơn quá hạn", nó embedding câu này thành vector và tìm tool có embedding gần nhất. Tên get_data có vector nằm giữa "lấy user", "lấy báo cáo", và "lấy hóa đơn" — ambiguity cao. Tên retrieve_overdue_invoice_by_customer_id có vector nằm sát cluster "overdue payment", "unpaid bill", "customer debt" — routing chính xác. Đây là lý do tại sao "naming is conceptual routing".

Boundary Conditions chống Overconfidence: LLM được fine-tune để "helpful" — nó muốn hoàn thành task. Khi mô tả mơ hồ ("search database"), agent áp dụng tool cho mọi query có chữ "tìm", dẫn đến scope creep. Boundary conditions ("ONLY when...") tạo hard constraints trong không gian attention, buộc agent kiểm tra precondition trước khi gọi. Đây là kỹ thuật "pessimistic tool use" — giả định tool không phù hợp cho đến khi chứng minh được ngược lại.

Error as Conversation: Trong vòng lặp ReAct, observation sau action quyết định thought tiếp theo. Nếu observation là "Error 400" (information content thấp), entropy cao, agent hallucinate giải pháp. Nếu observation là structured correction signal (high information, low entropy), agent có thể plan sửa lỗi xác định. Đây là information-theoretic grounding — giảm uncertainty cho next token prediction.

Trade-off: Thiết kế này thêm latency (validation layers, rich descriptions tốn token), nhưng giảm cost tổng thể bằng cách giảm số lần retry và human intervention. Giống như static typing: chậm hơn khi viết code, nhưng nhanh hơn khi debug production.

Ý nghĩa thực tế

Benchmarks thực chiến:

• TRAIL dataset (148 annotated traces): Từ 11% accuracy trong trace debugging lên ~45-50% khi có error taxonomy rõ ràng.
• AgentProcessBench: Step-level violations giảm từ 34% xuống <2% với deterministic pre-execution gates và tool contracts chặt chẽ.
• SkillsBench: Skill descriptions chất lượng cao nén 2000 tokens procedure thành 200 tokens trigger text, giảng "lost in the middle" errors trong context window.

Ai đang dùng:

• LangGraph/CrewAI production: Dùng task-oriented tools để giảm graph complexity.
• Claude Code: Tool definitions với strict input schemas và error handling patterns.
• Apideck: Unified APIs thiết kế cho "Agent Experience" (AX) thay vì chỉ Developer Experience (DX).
• Enterprise RAG systems: Dùng structured error để kích hoạt "critic agents" tự sửa lỗi retrieval.

Hạn chế — những gì không giải quyết được:

• Business logic mơ hồ: Nếu yêu cầu nghiệp vụ không rõ ràng ("xử lý đơn hàng" nhưng không biết xử lý thế nào), tool design tốt cũng không cứu được.
• Latency overhead: Validation và rich descriptions thêm 50-200ms mỗi call; không phù hợp cho real-time <100ms.
• Versioning complexity: Thay đổi mô tả = thay đổi "thế giới quan" của agent; cần regression testing khi cập nhật tool specs.
• Recursive validation: Nếu error handler cũng là LLM, có thể bị "hallucinate" cách sửa lỗi — cần eventual grounding bằng deterministic code (Python assertions, JSON schema validation).

Đào sâu hơn

Tài liệu chính thức:

• Paper "Learning to Rewrite Tool Descriptions for Reliable LLM-Agent Tool Use" (arXiv:2602.20426) — Phương pháp tối ưu hóa mô tả tool bằng RL để giảm lỗi selection.
• Paper "TRAIL: Trace Reasoning and Agentic Issue Localization" (arXiv:2505.08638) — Cách taxonomy lỗi cấu trúc giúp agent tự debug trace.

Cùng cụm (Skills & Tools):

Đọc tiếp:

Mở rộng:

• Blog "API Design Principles for the Agentic Era" (Apideck) — So sánh DX (Developer Experience) vs AX (Agent Experience) trong thiết kế API.
• GitHub langchain-ai/langgraph — Examples về tool node error handling và retry policies trong production graphs.