Bạn đã cấp cho tác nhân hai công cụ: updateUser và deactivateUser. Một phiếu hỗ trợ ghi “đóng tài khoản này.” Tác nhân đã gọi deactivateUser. Tuần trước, một phiếu tương tự gần như y hệt đã khiến nó gọi updateUser với status: "closed", điều mà API của bạn đã chấp nhận và có nghĩa hơi khác một chút ở các bước tiếp theo.
Không có gì bị hỏng. Mô hình đang lựa chọn giữa hai tùy chọn hợp lý với các mô tả không cho biết tùy chọn nào được áp dụng. Lựa chọn công cụ là chế độ lỗi mà mọi người đổ lỗi cho mô hình và khắc phục trong lược đồ, bởi vì lược đồ là thứ duy nhất mà mô hình có thể dựa vào.
Hướng dẫn này bao gồm những gì mô hình thực sự đọc khi chọn một công cụ, cách viết tên và mô tả có tính phân biệt, cách thiết kế tham số thay đổi tỷ lệ lỗi và cách kiểm tra lựa chọn để thay đổi cách diễn đạt không làm hỏng nó một cách âm thầm. Khi các công cụ của bạn được tạo từ một đặc tả, như trong hướng dẫn của chúng tôi về chuyển đổi đặc tả OpenAPI thành công cụ tác nhân, đây trở thành câu hỏi về những gì có trong đặc tả đó.
Apidog là nơi chứa các mô tả nếu các công cụ của bạn đến từ định nghĩa API của bạn, vì vậy việc cải thiện một cái sẽ cải thiện cả tài liệu và các công cụ.
Mô hình nhìn thấy gì
Tại thời điểm lựa chọn, mô hình có cuộc trò chuyện, lời nhắc hệ thống và danh sách các định nghĩa công cụ. Mỗi định nghĩa bao gồm tên, mô tả và lược đồ tham số. Nó không có tài liệu API của bạn, các bình luận mã của bạn, hoặc kiến thức truyền miệng rằng updateUser là công cụ cũ.
Điều đó có nghĩa là mọi sự làm rõ phải được viết vào chính định nghĩa. Cả hướng dẫn gọi hàm của OpenAI và tài liệu sử dụng công cụ của Anthropic đều nhấn mạnh cùng một điểm: mô tả là văn bản quan trọng nhất trong toàn bộ định nghĩa, và nó nên chi tiết thay vì ngắn gọn.
Các lỗi lựa chọn có bốn dạng, và mỗi dạng có một cách khắc phục khác nhau.
Mô hình chọn một công cụ tương tự khi hai định nghĩa trùng lặp. Khắc phục các mô tả để mỗi mô tả nêu rõ khi nào không nên sử dụng. Mô hình không chọn gì và trả lời từ bộ nhớ khi không có mô tả nào khớp với ngôn ngữ tác vụ. Khắc phục bằng cách sử dụng các từ mà người dùng của bạn sử dụng. Mô hình chọn đúng công cụ với các đối số sai khi các tham số không rõ ràng. Khắc phục bằng cách sử dụng các kiểu, enum và đơn vị. Mô hình liên kết các công cụ không tốt khi thứ tự quan trọng mà không có gì chỉ ra điều đó. Khắc phục bằng cách nêu rõ điều kiện tiên quyết trong mô tả.
Đặt tên công cụ theo chức năng của chúng
Tên mang nhiều tín hiệu hơn so với độ dài của chúng, bởi vì mô hình đọc chúng đầu tiên.
Sử dụng định dạng độngTừDanhTừ, theo cùng một phong cách trên toàn bộ tập hợp công cụ: createOrder, refundOrder, getOrderStatus. Tính nhất quán quan trọng không kém gì lựa chọn cá nhân, vì một tập hợp mà trộn lẫn order_create, getOrder, và refund sẽ khiến mỗi tên hơi khó đọc hơn.
Hãy cụ thể về đối tượng. search là một tên công cụ tồi. searchCustomersByEmail là một tên tốt, và nó cho mô hình biết cả những gì nó tìm kiếm và cách thức tìm kiếm.
Tránh các biệt ngữ nội bộ. Nếu API của bạn gọi khách hàng là "entity" và gói đăng ký là "instrument", mô hình sẽ không kết nối chúng với một phiếu yêu cầu ghi "customer" và "plan". Hãy đặt tên công cụ bằng ngôn ngữ của tác vụ, không phải ngôn ngữ của lược đồ.
Không bao giờ sử dụng lại một tên trên các ngữ cảnh khác nhau. Hai công cụ có tên list trong các không gian tên khác nhau sẽ trở nên mơ hồ ngay khi chúng xuất hiện trong một danh sách.
Viết mô tả có tính phân biệt
Một mô tả hữu ích trả lời bốn câu hỏi: nó làm gì, nó thay đổi gì, khi nào nên sử dụng, và khi nào không nên sử dụng.
Đây là một cặp yếu:
{ "name": "updateUser", "description": "Cập nhật một người dùng." }
{ "name": "deactivateUser", "description": "Hủy kích hoạt một người dùng." }
Và một cặp thực sự phân biệt:
{
"name": "updateUser",
"description": "Cập nhật các trường hồ sơ của một người dùng đang hoạt động, chẳng hạn như tên, email hoặc múi giờ. Sử dụng cho các chỉnh sửa và sửa đổi hồ sơ do người dùng yêu cầu. KHÔNG thay đổi trạng thái tài khoản. Để vô hiệu hóa tài khoản, hãy sử dụng deactivateUser thay thế. Không sử dụng để đóng hoặc hủy tài khoản."
}
{
"name": "deactivateUser",
"description": "Vô hiệu hóa một tài khoản người dùng, thu hồi tất cả các phiên và chặn đăng nhập. Có thể đảo ngược bằng reactivateUser. Sử dụng khi khách hàng yêu cầu đóng, hủy, tạm dừng hoặc đình chỉ tài khoản của họ. KHÔNG xóa dữ liệu. Để xóa vĩnh viễn, hãy sử dụng deleteUser, không thể hoàn tác."
}
Bốn kỹ thuật đang hoạt động ở đây.
Gọi tên công cụ liên quan. “Sử dụng deactivateUser thay thế” giải quyết sự mơ hồ trực tiếp, tại chính thời điểm mô hình đang so sánh chúng.
Bao gồm từ vựng của người dùng. Các từ “close”, “cancel”, “pause” và “suspend” xuất hiện vì đó là những từ thường có trong phiếu yêu cầu. Đây là chỉnh sửa mang lại hiệu quả cao nhất mà bạn có thể thực hiện, và nó gần như miễn phí.
Nói rõ những gì nó không làm. Các câu phát biểu phủ định có tính phân biệt cao hơn các câu khẳng định, bởi vì các tuyên bố tích cực của hai công cụ lân cận có xu hướng trông giống nhau.
Đánh dấu khả năng đảo ngược. Mô hình sẽ suy luận về rủi ro khi bạn nói cho nó biết có rủi ro. Điều này kết hợp với các mẫu thực thi trong bài đăng của chúng tôi về hàng rào bảo vệ tác nhân AI, nơi thuộc về sự bảo vệ thực sự.
Độ dài không phải là vấn đề. Một mô tả dài trăm từ mà ngăn chặn một cuộc gọi sai đến một điểm cuối có tính hủy diệt là rẻ.
Thiết kế tham số sao cho khó có đối số sai
Khi công cụ phù hợp đã được chọn, các đối số là nơi tiếp theo mọi thứ có thể sai.
JSON Schema cung cấp cho bạn hầu hết các ràng buộc cần thiết ở đây, và từ vựng xác thực JSON Schema rất đáng để xem qua để tìm các từ khóa mà API gọi công cụ của bạn hỗ trợ.
Sử dụng enum bất cứ nơi nào tập hợp là đóng. Một tham số status được định kiểu là chuỗi sẽ khuyến khích sự tự tạo. Được định kiểu là enum, nó giới hạn mô hình trong các giá trị mà API của bạn chấp nhận.
"status": {
"type": "string",
"enum": ["pending", "paid", "refunded", "cancelled"],
"description": "Trạng thái đơn hàng. 'cancelled' nghĩa là chưa bao giờ được thực hiện; 'refunded' nghĩa là đã được thực hiện sau đó đảo ngược."
}
Đặt đơn vị vào tên. amount là mơ hồ và các mô hình sẽ đoán đô la hoặc xu không nhất quán. amount_cents thì không bao giờ. Tương tự với timeout_seconds, distance_meters, và duration_ms.
Cung cấp ví dụ về định dạng ngày. "description": "Ngày bắt đầu ở định dạng ISO 8601, ví dụ 2026-08-26" tạo ra các ngày được định dạng chính xác thường xuyên hơn nhiều so với chỉ “ngày bắt đầu”.
Giữ danh sách bắt buộc trung thực. Đánh dấu mọi thứ là tùy chọn sẽ đẩy lỗi vào thời gian chạy; đánh dấu những thứ bắt buộc mà API mặc định hợp lý sẽ khiến mô hình tự tạo giá trị. Cả hai đều phổ biến, và cả hai đều xuất hiện dưới dạng lỗi xác thực được đề cập trong bài đăng của chúng tôi về thiết kế lỗi API cho tác nhân.
Ưu tiên cấu trúc phẳng hơn lồng ghép. Một mô hình điền {"customer": {"address": {"postal_code": "..."}}} mắc lỗi cấu trúc mà nó không mắc phải với customer_postal_code. Làm phẳng tại ranh giới công cụ và tập hợp lại trong trình thực thi của bạn.
Tách các công cụ bị quá tải. Một công cụ với tham số mode làm thay đổi ý nghĩa của mọi trường khác thực chất là hai công cụ. Tách nó ra sẽ cải thiện lựa chọn và đơn giản hóa cả hai lược đồ.
Nêu rõ các điều kiện tiên quyết và thứ tự
Công việc nhiều bước thất bại khi mô hình không biết trình tự. Hãy nói rõ điều đó trong mô tả của công cụ phụ thuộc:
{
"name": "captureCharge",
"description": "Thu tiền một khoản phí đã được ủy quyền trước đó. Yêu cầu một authorization_id từ authorizeCharge. Hãy gọi authorizeCharge trước nếu bạn chưa có. Không thể thu tiền nhiều hơn số tiền đã được ủy quyền."
}
Chỉ hai dòng, và vấn đề thứ tự được xử lý ngay tại nơi mô hình đang đọc. Điều này đúng cho toàn bộ loại: tạo trước khi cập nhật, tải lên trước khi xử lý, ủy quyền trước khi thu tiền. Nếu mô tả của một bước phụ thuộc không nêu tên bước trước đó, hãy dự đoán mô hình sẽ bỏ qua nó. Khi trình tự kéo dài qua nhiều tác nhân thay vì nhiều cuộc gọi, các quy tắc chuyển giao trong bài đăng của chúng tôi về truyền ngữ cảnh giữa các tác nhân phụ sẽ được áp dụng.
Kiểm tra lựa chọn như bất kỳ hành vi nào khác
Mô tả là mã, và chúng có thể bị thoái hóa. Ai đó rút gọn một mô tả để phù hợp với hướng dẫn phong cách và tác nhân bắt đầu chọn sai điểm cuối vào thứ Ba tới.
Xây dựng một bộ kiểm thử lựa chọn nhỏ. Hai mươi đến năm mươi lời nhắc, mỗi lời nhắc với công cụ bạn mong đợi. Chạy chúng, ghi lại công cụ mà mô hình chọn, và chỉ xác nhận tên. Các đối số thay đổi theo từng lần chạy; lựa chọn thì không nên. Đây là hình thức thực tế của phương pháp trong hướng dẫn của chúng tôi về kiểm thử các tác nhân AI không xác định.
Gieo hạt với các trường hợp có khả năng bị hỏng nhất:
- Hai công cụ tương tự nhất trong bộ của bạn, với các lời nhắc nên dẫn đến mỗi công cụ.
- Các lời nhắc sử dụng từ vựng của khách hàng thay vì từ vựng của API.
- Một lời nhắc không nên khớp với gì cả, trong đó hành vi đúng là hỏi thay vì buộc phải gọi.
- Một công cụ gây phá hủy, nơi một lựa chọn sai sẽ gây ra chi phí thực sự.
Chạy mỗi lời nhắc nhiều lần. Một công cụ thắng bốn trên năm lần là một sự may rủi trong môi trường sản xuất và mô tả cần được cải thiện.
Hướng các lần chạy đến các bản mô phỏng để một kiểm thử lựa chọn không bao giờ chạm vào dữ liệu trực tiếp. Bài đăng của chúng tôi về chạy tác nhân chống lại các bản mô phỏng thay vì môi trường sản xuất bao gồm thiết lập, và Apidog có thể cung cấp các bản mô phỏng đó từ cùng một định nghĩa mà các công cụ của bạn được tạo ra, điều này giúp giữ cho lược đồ và hành vi được đồng bộ hóa.
Ba bộ thường gặp lỗi theo cùng một cách
Bộ CRUD. Một API cung cấp getUser, listUsers, searchUsers và queryUsers, tất cả đều được tạo từ các điểm cuối đã phát triển qua nhiều năm. Đối với một mô hình, đây là bốn tên cho một ý tưởng. Cách khắc phục không phải là mô tả tốt hơn cho cả bốn; mà là chỉ hiển thị một trong số chúng cho tác nhân và bỏ phần còn lại ra khỏi danh sách công cụ. Một bộ được tuyển chọn luôn tốt hơn một bộ đầy đủ.
Bộ quản trị. Các công cụ đọc và công cụ gây phá hủy nằm cạnh nhau với cùng một tông giọng: getInvoice, voidInvoice, deleteInvoice. Không có gì trong văn bản cho thấy hai trong số này có thể kết thúc sự nghiệp. Thêm hậu quả vào mô tả, đánh dấu chúng để phê duyệt và giữ việc thực thi trong trình thực thi thay vì tin tưởng vào cách diễn đạt. Phương pháp phân lớp có trong bài đăng của chúng tôi về ngăn chặn tác nhân AI phá hủy API của bạn.
Bộ cũ. Hai điểm cuối thực hiện cùng một công việc, một cái đã bị lỗi thời. Đặc tả vẫn liệt kê cả hai, vì vậy trình tạo phát ra cả hai, và tác nhân chọn cái cũ khoảng một nửa thời gian. Hoặc bỏ hoạt động bị lỗi thời khỏi các công cụ được tạo hoặc bắt đầu mô tả của nó bằng các từ “Đã lỗi thời. Thay vào đó hãy sử dụng createOrderV2.” Các mô hình sẽ tôn trọng dòng đó khi nó ở đầu, và bỏ qua khi nó bị chôn vùi ở cuối.
Mô tả là cấu hình được chia sẻ
Khi bạn chấp nhận rằng mô tả công cụ định hướng hành vi, câu hỏi tiếp theo là ai sở hữu chúng. Trong hầu hết các nhóm, câu trả lời là ngẫu nhiên: bất cứ ai thiết lập tác nhân đầu tiên, trong một tệp trên máy của họ.
Thay vào đó, hãy coi bộ công cụ như một hiện vật được chia sẻ, được xem xét như bất kỳ giao diện nào khác. Các nền tảng được xây dựng xung quanh công việc của tác nhân thường mô hình hóa điều này trực tiếp. Một Tác nhân Sharkly là một cấu hình đã lưu bao gồm hướng dẫn, Thời gian chạy, Kỹ năng và kho lưu trữ, và việc chia sẻ nó trong một Không gian giúp cài đặt làm việc của một người có thể tái sử dụng bởi nhóm. Giá trị không phải là bộ nhớ. Mà là việc thay đổi mô tả trở thành một chỉnh sửa có thể xem xét lại ảnh hưởng đến tất cả mọi người, thay vì một điều chỉnh cục bộ âm thầm khiến tác nhân của một nhà phát triển hoạt động khác với phần còn lại.
Hãy chú ý đến những từ mà người dùng sử dụng
Khoảng trống phổ biến nhất là từ vựng. API của bạn nói subscription, khách hàng của bạn nói plan, membership và billing. API của bạn nói deactivate, họ nói cancel, close và turn off.
Thu thập ngôn ngữ thực tế. Lấy các cụm từ hàng đầu từ các phiếu hỗ trợ, nhật ký tìm kiếm hoặc bản ghi các lần chạy tác nhân thất bại, sau đó đưa chúng vào các mô tả của các công cụ mà chúng đáng lẽ phải khớp. Việc này tốn một giờ và thường cải thiện độ chính xác lựa chọn nhiều hơn bất kỳ điều chỉnh lược đồ nào.
Cũng hãy để mắt đến các thất bại. Khi một tác nhân không chọn gì và trả lời từ kiến thức của chính nó, đó là sự thiếu từ vựng, không phải lỗi suy luận. Ngôn ngữ tác vụ không bao giờ trùng lặp với văn bản công cụ, vì vậy công cụ đó đã bị vô hình.
Danh sách kiểm tra cho một bộ công cụ
- Tên tuân theo một quy ước
độngTừDanhTừvà đặt tên một đối tượng cụ thể. - Mỗi mô tả nêu rõ những gì thay đổi, khi nào nên sử dụng và khi nào không nên.
- Các công cụ trùng lặp tự gọi tên nhau một cách rõ ràng.
- Mô tả bao gồm các từ mà người dùng thực sự sử dụng, không chỉ các thuật ngữ nội bộ.
- Các hành động phá hủy và không thể đảo ngược phải được ghi rõ trong mô tả.
- Enums được khai báo cho mọi tập hợp đóng.
- Đơn vị và định dạng nằm trong tên tham số hoặc mô tả, kèm theo ví dụ.
- Danh sách bắt buộc khớp với những gì API thực sự áp dụng.
- Các công cụ phụ thuộc nêu rõ điều kiện tiên quyết của chúng.
- Một bộ kiểm tra lựa chọn chạy trong CI chống lại các bản mô phỏng.
Mô hình đang thực hiện so khớp mẫu với văn bản bạn đã viết. Khi nó chọn sai, văn bản là nơi đầu tiên cần xem xét, và thường là nơi duy nhất bạn cần thay đổi. Tải xuống Apidog nếu bạn muốn các mô tả, bản mô phỏng và các bài kiểm tra trong một dự án.
Câu hỏi thường gặp
Mô tả công cụ nên dài bao nhiêu? Đủ dài để làm rõ, thường là hai đến năm câu. Mô tả chiếm ngữ cảnh, vì vậy hãy rút gọn những mô tả cho các công cụ không mơ hồ và dành không gian cho các công cụ liền kề nhau.
Tôi có nên đưa ví dụ vào mô tả không? Có, đối với các định dạng và đơn vị, nơi một ví dụ loại bỏ toàn bộ các loại lỗi. Bỏ qua các ví dụ sử dụng dài, vì chúng tốn ngữ cảnh và hiếm khi thay đổi lựa chọn.
Nên có nhiều công cụ hẹp hay một vài công cụ linh hoạt hơn? Các công cụ hẹp, đến một mức độ nào đó. Mỗi công cụ chọn đáng tin cậy hơn vì nó chỉ làm một việc. Sau vài chục công cụ, bản thân danh sách trở thành vấn đề và bạn sẽ phải lọc hoặc truy xuất, như đã đề cập trong bài đăng của chúng tôi về tạo công cụ tác nhân từ OpenAPI.
Tôi có thể khắc phục lựa chọn trong lời nhắc hệ thống thay vì mô tả công cụ không? Có thể một phần, và đó là một giải pháp tạm thời hợp lý cho một hoặc hai sự nhầm lẫn đã biết. Tuy nhiên, nó không mở rộng được, bởi vì lời nhắc được chia sẻ trên tất cả các công cụ trong khi mô tả đi kèm với công cụ cần nó.
Điều gì sẽ xảy ra nếu mô hình cứ tiếp tục tự tạo giá trị tham số? Hạn chế kiểu dữ liệu, thêm enum và nêu rõ trong mô tả rằng giá trị phải đến từ một cuộc gọi trước đó thay vì được tự tạo. Nếu vẫn xảy ra, hãy xác thực trong lớp bao bọc và trả về lỗi nêu rõ các giá trị được phép.
Các quy tắc này có áp dụng cho máy chủ MCP không? Có. Một máy chủ MCP hiển thị tên, mô tả và lược đồ theo cùng một hình dạng, vì vậy các quy tắc diễn đạt tương tự được áp dụng. Giải thích của chúng tôi về MCP là gì bao gồm chính giao thức đó.