Tôi đã xây dựng một tác nhân gọi công cụ bằng Python. Đây là cách tôi gỡ lỗi nó.

AI tác nhân Tôi đã xây dựng một tác nhân gọi công cụ bằng Python. Đây là cách tôi gỡ lỗi nó. Một vòng lặp tối thiểu với các lệnh gọi API thực, xác thực, đầu ra nhỏ gọn và bằng chứng theo dõi trước khi thêm một khung tác nhân. Abdullahi Dattijo Ngày 6/8/2026 19 phút đọc Một hệ thống gọi công cụ hai giai đoạn minh bạch chuyển đổi vị trí bản đồ Lagos thành tọa độ, xác thực chúng, truy xuất dự báo mưa và ghi lại từng bước dọc theo dấu vết bằng chứng. Hình ảnh được tạo bằng ChatGPT. Một tác nhân gọi công cụ rất ấn tượng khi nó hoạt động. Nhưng khi nó thất bại, câu trả lời cuối cùng là không đủ. Bạn cần xem hàm mà nó đã chọn, các đối số mà nó đã gửi và kết quả mà mã của bạn đã trả về. Nếu bạn đã xây dựng một tác nhân nhỏ xung quanh API sản phẩm, điểm cuối truy xuất, tra cứu cơ sở dữ liệu, dịch vụ thời tiết hoặc công cụ Giao thức ngữ cảnh mô hình (MCP), bạn có thể đã thấy cùng một vấn đề. Mô hình nói rằng nó đã kiểm tra một cái gì đó. Có thể nó đã làm. Có thể nó đã gửi các đối số bị lỗi. Có thể API không trả về kết quả nào. Có thể yêu cầu mô hình đã thất bại trước khi công cụ của bạn chạy. Nếu không có lịch sử tin nhắn, đối số công cụ, tải trọng trả về và câu trả lời cuối cùng ở một nơi, bạn đang tin vào một câu chuyện thay vì kiểm tra một lần chạy. Tài liệu của OpenAI trình bày bốn bước: bạn mô tả một công cụ, mô hình yêu cầu nó, bạn chạy công cụ và bạn trả về kết quả. Mẫu đó hữu ích, nhưng bản demo đầu tiên thường bỏ qua phần quan trọng khi một tác nhân chạm vào công việc thực tế. Bạn có thể chứng minh những gì mô hình đã yêu cầu, những gì Python đã thực thi, những gì đã thất bại trong xác thực và liệu câu trả lời cuối cùng có sử dụng dữ liệu đã trả về hay không? Bài viết này được xây dựng xung quanh vấn đề gỡ lỗi đó. Tác nhân gọi các API công khai, xác thực các đối số công cụ bằng JSON Schema, trả về các tải trọng công cụ nhỏ gọn, ghi lại từng bước công cụ, bắt lỗi yêu cầu mô hình và có thể ghi cùng một lần chạy vào dấu vết Weights & Biases (W&B) Weave để xem xét. JSON có nghĩa là Ký hiệu đối tượng JavaScript. Trong bài viết này, JSON Schema là hợp đồng cho Python biết đối số công cụ nào hợp lệ trước khi bất kỳ công cụ nào chạy. Vấn đề hướng dẫn rất đơn giản: xây dựng một tác nhân có thể trả lời câu hỏi thời tiết chỉ bằng cách gọi các công cụ thực, sau đó làm cho mọi bước có thể kiểm tra được. Thời tiết là đại diện cho các tác vụ được hỗ trợ bởi dịch vụ mà các nhà phát triển thường giao cho các tác nhân: kiểm tra gói hàng, truy xuất hồ sơ khách hàng, tra cứu hàng tồn kho, định giá đơn hàng hoặc gọi API nội bộ. Câu hỏi hữu ích là liệu lệnh gọi hàm do mô hình chọn có thực sự xảy ra và trả về dữ liệu có thể sử dụng được hay không. Thông điệp chính dành cho độc giả rất trực tiếp: ngừng đánh giá một tác nhân gọi công cụ chỉ bằng câu trả lời cuối cùng. Hãy đánh giá nó bằng yêu cầu mô hình, xác thực lược đồ, thực thi Python, kết quả công cụ nhỏ gọn, đường dẫn lỗi và câu trả lời cuối cùng cùng nhau. Vòng lặp đáng để xây dựng trực tiếp một lần trước khi áp dụng một khung tác nhân lớn hơn hoặc kết nối các công cụ tương tự vào MCP. Các khung và máy chủ MCP hữu ích khi bạn có nhiều công cụ, quy tắc định tuyến, trạng thái, thử lại hoặc quy ước nhóm. Điểm ở đây là hiểu luồng tin nhắn trước khi trừu tượng hóa che giấu nó. Cuối cùng, bạn sẽ có một tập lệnh có thể: xác định các công cụ với JSON Schema cho mô hình OpenAI chạy một vòng lặp gọi công cụ có giới hạn xác thực tên và đối số công cụ trước khi thực thi giữ đầu ra công cụ nhỏ gọn trước khi trả về cho mô hình trả về lỗi có cấu trúc nếu yêu cầu mô hình bị lỗi ghi lại bằng chứng chạy trong đầu ra console và Weave Đây là điểm cốt lõi của bài viết. Người đọc sẽ có được một vòng lặp thông báo có thể chạy được, có thể kiểm tra, ngắt, xác minh và sau đó thay thế hoặc bao bọc bằng MCP hoặc một khung tác nhân (agent framework) từ vị trí của sự hiểu biết. Hình ảnh do tác giả cung cấp. Các điểm đánh giá hữu ích là yêu cầu mô hình, xác thực Python, thực thi Python, định hình kết quả nhỏ gọn, câu trả lời cuối cùng và bản ghi dấu vết. Quá trình chạy phải trả lời bốn câu hỏi: Một tác nhân gọi công cụ (tool-calling agent) có thể trả lời, “Tôi đã kiểm tra API,” nhưng các câu hỏi hữu ích bắt đầu sau câu đó: Mô hình đã yêu cầu công cụ nào? Nó đã gửi những đối số nào? Python đã trả về gì? Câu trả lời cuối cùng có sử dụng dữ liệu được trả về hay che giấu một lỗi? Hướng dẫn này xây dựng một tác nhân nhỏ xoay quanh những câu hỏi đó. Người dùng hỏi liệu có nên mang ô khi đến Lagos không. Mô hình phải yêu cầu tra cứu thành phố, nhận tọa độ, yêu cầu thời tiết, nhận dự báo và trả lời từ dữ liệu được trả về đó. Mọi bước đều được in và có thể theo dõi. Nếu bạn có thể kiểm tra vòng lặp nhỏ này, thói quen tương tự sẽ được áp dụng cho các tác nhân được hỗ trợ bởi dịch vụ nghiêm túc hơn. Một tác nhân hoàn tiền nên hiển thị tra cứu đơn hàng, kiểm tra chính sách, quyết định hoàn tiền và tin nhắn cuối cùng. Một tác nhân tài liệu nên hiển thị truy vấn tìm kiếm, các đoạn văn được truy xuất và câu trả lời. Một công cụ MCP vẫn nên hiển thị tên công cụ, đối số, kết quả và đường dẫn lỗi. **Những gì một tác nhân gọi công cụ thực sự làm** Một tác nhân gọi công cụ trong Python là một vòng lặp được điều khiển bởi một mô hình ngôn ngữ lớn (LLM). Nó cho phép mô hình yêu cầu các hàm được đặt tên, nhận kết quả của chúng và tiếp tục với các tin nhắn được cập nhật. Điều đó nghe có vẻ gần giống với một chatbot, nhưng hành vi thì khác. Một chatbot nhận văn bản và trả về văn bản. Một tác nhân gọi công cụ nhận văn bản, có thể yêu cầu hành động, chờ ứng dụng của bạn thực thi hành động đó, đọc kết quả công cụ và sau đó quyết định nói hoặc làm gì tiếp theo. Các phần quan trọng là các đối tượng kỹ thuật đơn giản: Mô hình quyết định xem nó có cần một công cụ hay không. Công cụ là một hàm Python thuộc sở hữu của ứng dụng của bạn. Lược đồ (schema) chỉ định các đối số mà công cụ chấp nhận. Các tin nhắn là bản ghi đang chạy của yêu cầu người dùng, yêu cầu công cụ của mô hình, kết quả công cụ và câu trả lời cuối cùng. Vòng lặp tác nhân là mã Python của bạn giúp quá trình tiếp tục chạy cho đến khi mô hình ngừng yêu cầu công cụ. Một lệnh gọi hàm cơ bản là một yêu cầu và một kết quả. Một vòng lặp tác nhân là phiên bản lặp lại. Mô hình có thể yêu cầu một công cụ, đọc kết quả, yêu cầu một công cụ khác và tiếp tục cho đến khi nó có đủ ngữ cảnh. Ví dụ về thời tiết sử dụng hai công cụ: geocode_city, chuyển đổi tên thành phố thành vĩ độ, kinh độ và quốc gia. get_weather, chuyển đổi vĩ độ.