Tác giả bài gốc: Thariq Shihipar (Member of Technical Staff). Đăng ngày 10/04/2026 trên claude.dev.
Một trong những phần khó nhất khi xây dựng harness cho agent là thiết kế các tool của nó.
Claude thực hiện mọi hành động thông qua tool calling, nhưng có nhiều cách xây dựng tool trong Claude API từ các thành phần cơ bản như bash, skill và thực thi code. (Bạn có thể đọc thêm về cách gọi tool bằng chương trình trên Claude API trong bài viết mới của @RLanceMartin).
Vậy bạn thiết kế tool cho agent như thế nào? Cho nó một tool đa dụng như bash hay thực thi code? Hay năm mươi tool chuyên biệt, mỗi tool dành cho một trường hợp sử dụng?
Để đặt mình vào cách suy nghĩ của model, hãy tưởng tượng bạn được giao một bài toán khó. Bạn muốn có những công cụ nào để giải bài toán đó? Điều này phụ thuộc vào chính những kỹ năng bạn có!
Tối thiểu bạn cần giấy, nhưng khi đó bạn sẽ bị giới hạn bởi việc tính toán thủ công. Máy tính bỏ túi sẽ tốt hơn, nhưng bạn cần biết cách dùng các chức năng nâng cao. Lựa chọn nhanh và mạnh nhất là máy tính, nhưng bạn phải biết cách dùng nó để viết và chạy code.
Đây là một cách tư duy hữu ích khi thiết kế agent. Bạn muốn cung cấp những tool phù hợp với khả năng của chính nó. Nhưng làm sao biết những khả năng đó là gì? Bạn quan sát, đọc output của nó, thử nghiệm. Bạn học cách nhìn từ góc độ agent.
Nếu đang xây dựng agent, bạn sẽ gặp những câu hỏi giống chúng tôi: khi nào nên thêm tool, khi nào nên bỏ một tool, và làm sao phân biệt được hai trường hợp đó. Dưới đây là cách chúng tôi trả lời những câu hỏi ấy khi xây dựng Claude Code, bao gồm cả những chỗ ban đầu chúng tôi đã làm sai.
Cải thiện khả năng khai thác thông tin với tool AskUserQuestion
Khi xây dựng tool AskUserQuestion, mục tiêu của chúng tôi là cải thiện khả năng đặt câu hỏi của Claude (thường gọi là khai thác thông tin — elicitation).
Dù Claude có thể đặt câu hỏi bằng văn bản thuần, chúng tôi nhận thấy việc trả lời những câu hỏi đó có vẻ tốn thời gian một cách không cần thiết. Làm sao giảm trở ngại này và tăng lượng thông tin trao đổi giữa người dùng với Claude?
Lần thử 1: Chỉnh sửa ExitPlanTool
Cách đầu tiên chúng tôi thử là thêm một tham số vào ExitPlanTool để chứa một mảng câu hỏi bên cạnh kế hoạch. Đây là cách sửa dễ triển khai nhất, nhưng lại khiến Claude bối rối vì chúng tôi đồng thời yêu cầu nó đưa ra kế hoạch và một bộ câu hỏi về kế hoạch đó. Nếu câu trả lời của người dùng mâu thuẫn với nội dung kế hoạch thì sao? Claude có cần gọi ExitPlanTool hai lần không? Chúng tôi biết cách này sẽ không hiệu quả nên quay lại tìm phương án khác. (Bạn có thể đọc thêm về lý do chúng tôi tạo ExitPlanTool trong bài viết về prompt caching của chúng tôi)
Lần thử 2: Thay đổi định dạng output
Tiếp theo, chúng tôi thử cập nhật hướng dẫn về output của Claude để nó dùng một định dạng markdown được điều chỉnh đôi chút khi đặt câu hỏi. Chẳng hạn, chúng tôi có thể yêu cầu nó xuất danh sách câu hỏi dạng gạch đầu dòng, với các lựa chọn nằm trong dấu ngoặc. Sau đó, chúng tôi có thể parse và định dạng câu hỏi đó thành UI cho người dùng.
Claude thường tạo được định dạng này, nhưng không ổn định. Nó có thể thêm câu, bỏ bớt lựa chọn hoặc bỏ hẳn cấu trúc. Vậy là chúng tôi chuyển sang cách tiếp theo.
Lần thử 3: Tool AskUserQuestion
Cuối cùng, chúng tôi chọn tạo một tool mà Claude có thể gọi bất cứ lúc nào, nhưng đặc biệt được nhắc gọi trong chế độ lập kế hoạch. Khi tool được kích hoạt, chúng tôi hiển thị một modal chứa các câu hỏi và chặn vòng lặp của agent cho đến khi người dùng trả lời.
Tool này cho phép chúng tôi yêu cầu Claude tạo output có cấu trúc và giúp đảm bảo Claude đưa ra nhiều lựa chọn cho người dùng. Nó cũng cho người dùng cách kết hợp chức năng này với những thành phần khác, chẳng hạn gọi tool trong Agent SDK hoặc tham chiếu đến nó trong skill.
Quan trọng nhất, Claude có vẻ thích gọi tool này và chúng tôi nhận thấy output của nó hoạt động tốt. Suy cho cùng, ngay cả tool được thiết kế tốt nhất cũng không có tác dụng nếu Claude không hiểu cách gọi nó.
Đây có phải hình thức cuối cùng của việc khai thác thông tin trong Claude Code không? Chúng tôi không nghĩ vậy. Khi Claude có thêm năng lực, những tool phục vụ nó cũng phải phát triển theo. Phần tiếp theo cho thấy một trường hợp mà tool từng hữu ích lại bắt đầu trở thành trở ngại.
Cập nhật theo năng lực: task và todo
Khi mới ra mắt Claude Code, chúng tôi nhận ra model cần một danh sách todo để đi đúng hướng. Các todo có thể được viết ngay từ đầu và đánh dấu hoàn thành khi model làm việc. Để thực hiện điều này, chúng tôi cung cấp cho Claude tool TodoWrite để viết hoặc cập nhật todo và hiển thị chúng cho người dùng.
Nhưng ngay cả khi đó, chúng tôi vẫn thường thấy Claude quên việc nó cần làm. Để thích ứng, chúng tôi chèn lời nhắc hệ thống sau mỗi 5 lượt, nhắc Claude về mục tiêu của nó.
Khi các model tiến bộ, chúng bắt đầu thấy danh sách todo gây hạn chế. Những lời nhắc về danh sách todo khiến Claude nghĩ rằng nó phải bám sát danh sách, thay vì điều chỉnh khi nhận ra cần đổi hướng. Chúng tôi cũng thấy Opus 4.5 dùng subagent tốt hơn nhiều, nhưng làm sao các subagent phối hợp trên một danh sách todo chung?
Thấy vậy, chúng tôi thay tính năng TodoWrite bằng tool Task. Trong khi todo tập trung vào việc giữ model đi đúng hướng, task giúp các agent giao tiếp với nhau. Task có thể bao gồm quan hệ phụ thuộc, chia sẻ cập nhật giữa các subagent, và model có thể sửa hoặc xóa chúng.
Khi năng lực model tăng lên, những tool mà model từng cần có thể lại đang kìm hãm chúng. Điều quan trọng là thường xuyên xem xét lại các giả định trước đây về những tool cần thiết. Đây cũng là lý do việc chỉ hỗ trợ một nhóm nhỏ model có năng lực tương đối giống nhau sẽ hữu ích.
Thiết kế giao diện tìm kiếm
Những tool có tác động lớn nhất mà chúng tôi xây dựng là những tool cho phép Claude tự tìm context của mình.
Khi Claude Code lần đầu được phát hành nội bộ, chúng tôi dùng phương pháp sinh có tăng cường truy xuất (RAG): một cơ sở dữ liệu vector lập chỉ mục codebase trước, rồi harness truy xuất các đoạn liên quan và đưa cho Claude trước mỗi phản hồi. Dù RAG mạnh và nhanh, nó cần lập chỉ mục, cần thiết lập, và có thể hoạt động thiếu ổn định trong nhiều môi trường khác nhau. Quan trọng nhất, Claude được cung cấp context này thay vì tự tìm context.
Nhưng nếu Claude có thể tìm kiếm trên web, tại sao nó lại không thể tìm trong codebase của bạn? Bằng cách cung cấp tool Grep cho Claude, chúng tôi có thể để nó tìm file và tự xây dựng context.
Khi Claude thông minh hơn, nó ngày càng giỏi xây dựng context nếu được cung cấp đúng tool.
Khi giới thiệu Agent Skills, chúng tôi chính thức hóa ý tưởng tiết lộ dần (progressive disclosure), cho phép agent khám phá từng bước những context liên quan thông qua việc tìm hiểu.
Giờ Claude có thể đọc file skill, và những file đó có thể tham chiếu đến các file khác để model tiếp tục đọc theo kiểu đệ quy. Trên thực tế, một cách dùng skill phổ biến là bổ sung khả năng tìm kiếm cho Claude, chẳng hạn hướng dẫn nó cách dùng một API hoặc truy vấn cơ sở dữ liệu.
Trong vòng một năm, Claude đã đi từ chỗ chưa thực sự có thể tự xây dựng context đến chỗ có thể tìm kiếm lồng nhau qua nhiều tầng file để tìm đúng context nó cần.
Tiết lộ dần hiện là kỹ thuật chúng tôi thường dùng để bổ sung chức năng mới mà không cần thêm tool. Trong phần tiếp theo, chúng tôi giải thích lý do.
Tiết lộ dần: agent Claude Code Guide
Claude Code hiện có ~20 tool, và đội ngũ chúng tôi thường xuyên xem xét liệu có cần tất cả những tool đó để Claude hoạt động hiệu quả nhất hay không. Ngưỡng để thêm một tool mới rất cao, vì nó tạo thêm một lựa chọn mà model phải cân nhắc.
Chẳng hạn, chúng tôi nhận thấy Claude chưa biết đủ về cách dùng Claude Code. Nếu bạn hỏi cách thêm một MCP hoặc một slash command làm gì, nó sẽ không trả lời được.
Chúng tôi có thể đưa tất cả thông tin này vào system prompt, nhưng vì người dùng hiếm khi hỏi về những điều đó, cách này sẽ làm tăng hiện tượng suy giảm hiệu quả do context (context rot) và ảnh hưởng đến công việc chính của Claude Code: viết code.
Thay vào đó, chúng tôi thử tiết lộ dần: cung cấp cho Claude một đường dẫn đến tài liệu của nó để nó tải và tìm kiếm khi cần. Cách này có hiệu quả, nhưng Claude lại đưa những phần tài liệu rất lớn vào context để tìm một câu trả lời mà người dùng chỉ cần nhận trong một câu.
Vì vậy, chúng tôi xây dựng Claude Code Guide — một subagent mà Claude gọi mỗi khi người dùng hỏi về chính Claude Code. Subagent tìm kiếm tài liệu trong context riêng, làm theo hướng dẫn chi tiết về cách tìm kiếm và những gì cần trích xuất, rồi chỉ trả lại câu trả lời. Context của agent chính vẫn gọn gàng.
Dù đây chưa phải giải pháp hoàn hảo (Claude vẫn có thể bối rối khi bạn hỏi nó cách thiết lập chính nó), chúng tôi đã có thể mở rộng tập hành động của Claude mà không thêm tool mới.
Nhìn từ góc độ agent là một nghệ thuật, không phải khoa học
Thiết kế tool cho model vừa là nghệ thuật, vừa là khoa học. Nó phụ thuộc rất nhiều vào model bạn dùng, mục tiêu của agent và môi trường mà agent hoạt động.
Lời khuyên tốt nhất của chúng tôi? Thường xuyên thử nghiệm, đọc output của bạn, thử những điều mới. Và quan trọng nhất, hãy thử nhìn từ góc độ agent.
Bắt đầu dùng Claude Code ngay hôm nay.
Về tác giả: Thariq Shihipar là thành viên đội ngũ kỹ thuật tại Anthropic, làm việc trên Claude Code.