Tool Design cho Agent: Giới hạn kết quả, format output

Định nghĩa

Tool Design cho Agent là nghệ thuật thiết kế giao diện giữa AI và hệ thống bên ngoài — không phải để con người dễ nhìn, mà để AI dễ "nhai". Mục tiêu là giảm tải cognitive load của model thông qua việc kiểm soát kích thước output, cấu trúc format, và thứ tự thông tin, thay vì để AI tự mò mẫm trong biển dữ liệu.

Giải thích chi tiết

AI nhìn thế giới qua "cửa sổ nhỏ"

Hãy tưởng tượng AI như một người đang đọc một cuốn sách qua ô cửa sổ chỉ hiện được 100 dòng tại một thời điểm — và họ không thể lật lại trang đã đọc. Đây là thực tế của Context Window và working memory hạn chế.

Khi thiết kế Tool cho Agent, bạn không thể trả về "toàn bộ database" rồi bảo AI "tự tìm đi". SWE-agent — một trong những system đỉnh cao trong lĩnh vực này — chỉ trả về tối đa 50 kết quả search. Không phải vì họ lười lập trình, mà vì họ biết: nếu trả 500 kết quả, AI sẽ "ngộp" và bỏ lỡ thông tin quan trọng ở cuối danh sách do giới hạn Context Engineering.

Nguyên tắc "Chunk & Bound"

Thiết kế Tool cho Agent tuân theo hai nguyên tắc vàng:

1. Chunking (Phân mảnh thông tin) Thay vì trả về file 10,000 dòng một lúc, Claude Code chia thành các block 100 dòng, kèm line numbers cố định. Điều này cho phép AI:

• Xử lý tuần tự từng phần nhỏ
• Tham chiếu chính xác bằng số dòng thay vì "dòng đó, chỗ đó"
• Tránh "lạc trôi" giữa nội dung dài

2. Bounding (Giới hạn rõ ràng) Mỗi Tool phải có "hàng rào" kích thước: max_results=50, max_lines=100, max_chars=4000. Đây không phải arbitrary limits — chúng là kết quả của việc tính toán token budget giữa input prompt và output dự kiến.

Format là ngôn lưỡi của Tool

AI không "nhìn" UI — AI đọc text. Do đó, format output quyết định khả năng parsing:

XML/JSON có nhãn rõ ràng được ưu tiên hơn plain text. Ví dụ, thay vì:

Tìm thấy 3 file: app.py, utils.py, test.py

Hãy trả về:

<search_results>
  <file><path>app.py</path><size>2048</size><lines>100</lines></file>
  <file><path>utils.py</path><size>1024</size><lines>50</lines></file>
</search_results>

Lý do: cấu trúc thẻ XML tạo "neo semantic" giúp model dễ định vị thông tin hơn là parsing tự do.

Thứ tự thông tin = Độ ưu tiên

AI xử lý token theo thứ tự tuyến tính, và thông tin ở đầu context thường được chú ý hơn thông tin ở cuối (primacy effect). Do đó, trong Tool Design:

• Thông tin quan trọng nhất phải ở đầu (tên file, trạng thái lỗi, kết quả tóm tắt)
• Metadata phụ để cuối (timestamp, permissions chi tiết)
• Line numbers đặt bên trái (như margin) để AI có thể "nhìn lướt" và nhảy đến vị trí cụ thể

Ví dụ thực tế

Claude Code: 23 lớp validation và file viewer 100 dòng

Claude Code — agent IDE của Anthropic — là case study điển hình cho Tool Design đỉnh cao. Họ không để AI tự do edit file mà thiết kế:

File Viewer:

• Giới hạn 100 dòng mỗi lần read
• Line numbers bắt buộc ở cột đầu tiên (1-100, 101-200...)
• Syntax highlighting bằng markdown code block (```python) để AI hiểu ngữ cảnh ngôn ngữ

Kết quả: Khi AI cần sửa hàm ở dòng 1500, nó không read toàn bộ file (tốn token, rối), mà gọi view file.py 1450-1550 — đúng vùng cần thiết.

SWE-agent: Giới hạn 50 search results

Trong paper SWE-agent, nhóm nghiên cứu phát hiện rằng việc giới hạn search trả về 50 items thay vì unlimited tăng hiệu suất giải quyết issue lên 64% — cùng một model GPT-4, chỉ khác interface design.

Lý do: khi có 500 kết quả, AI mất khả năng đánh giá relevance ở cuối danh sách do context window pressure. 50 items là "sweet spot" cho working memory của model.

Tool Validation Layers

Claude Code implement 23 lớp validation trước khi thực thi bất kỳ tool nào — từ kiểm tra path traversal, xác nhận file tồn tại, đến validate JSON schema. Mỗi lớp trả về lỗi bằng format chuẩn:

<validation_error>
  <type>PathNotFound</type>
  <message>File /etc/passwd không tồn tại trong workspace</message>
  <suggested_action>Kiểm tra lại đường dẫn: ./config/local.txt</suggested_action>
</validation_error>

Format này cho phép AI "đọc" lỗi và tự sửa behavior (self-correction) thay vì crash.

Ứng dụng

Dành cho AI Engineer đang xây dựng Agent

Nếu bạn đang viết Python code để AI gọi hàm search_codebase(), đừng trả list[str]. Hãy trả object có giới hạn kích thước, thêm line numbers, và summary ở đầu. Đây là khác biệt giữa "demo chạy được" và "system production".

Dành cho Tech Lead thiết kế ACI

Khi review kiến trúc Tool cho team, hãy hỏi: "Nếu AI chỉ đọc được 100 dòng đầu, nó có hiểu gì không?" Nếu câu trả lời là không, bạn cần redesign — không phải để thêm tính năng, mà để giới hạn output.

Dành cho Developer tích hợp API

Nếu bạn đang wrap một API cũ cho AI dùng, đừng chỉ forward JSON nguyên bản. Hãy:

1. Truncate bớt fields không cần thiết
2. Reorder để critical info lên đầu
3. Thêm "explanation" field do AI viết lại bằng ngôn ngữ tự nhiên

So sánh

Kết luận: ACI (Agent-Computer Interface) là lĩnh vực mới hoàn toàn. Bạn không thể copy best practices từ UI/UX design sang Tool Design cho AI, vì người dùng ở đây là một hệ thống xử lý tuần tự với memory giới hạn, không phải con người có khả năng tổng hợp thông tin toàn cục.

Bài viết liên quan

Cùng cụm

Đọc tiếp