Skip to main content

Tools

Một tool là một hành động được đặt tên mà AI có thể gọi, với các đầu vào được gõ — ví dụ: send_email(to, subject, body). Các công cụ được khai báo trong tools.ts của một skill và, đối với các công cụ mà ứng dụng của bạn cung cấp, được hỗ trợ bởi một tuyến đường HTTP trong một trong các thành phần của bạn. Trang này là nguồn sự thật cho hợp đồng công cụ; Skills bao gồm nơi tools.ts nằm.

Khai báo một công cụ

Mỗi mục trong tools.ts có một name an toàn với nhà cung cấp, một displayName thân thiện, một description, một lược đồ Zod input, và một target cho biết Kazzle gọi cái gì.

Targets

target là địa chỉ có thể tái sử dụng cho một công cụ hoặc nút hành động bắt buộc. Một lệnh gọi công cụ AI trực tiếp và một cú nhấp chuột nút có thể sử dụng cùng một đối tượng target, vì vậy cả hai đều chạy cùng một mã. Các target HTTP sử dụng các trường yêu cầu giống nhau:
Không có giá trị mặc định yêu cầu ngầm. Nếu trình xử lý của bạn sẽ nhận đầu vào công cụ thô dưới dạng JSON, hãy viết body: '${input}'.

References

Kazzle phân giải các tham chiếu trong các trường query, headers, bodyurl của HTTP target trước khi gửi:
  • ${input} — toàn bộ đầu vào công cụ, hoặc toàn bộ đầu vào nút.
  • ${input.path} — một giá trị lồng nhau từ đầu vào.
  • ${env.NAME} — một biến môi trường được đặt tên từ env.collection + env.environment được khai báo của thành phần ứng dụng sở hữu.
Phân giải là một lần duy nhất. Nếu một tham chiếu bị thiếu hoặc không xác định, công cụ sẽ thất bại thay vì thay thế một giá trị trống. Sử dụng $${input.name} khi bạn cần văn bản ${input.name} theo nghĩa đen.

Handler request

Đối với một target app, hãy thêm tuyến đường phù hợp trong thành phần target. Với body: '${input}', Kazzle gửi đầu vào được gõ dưới dạng phần thân JSON:
Các target app cũng nhận: Các target ứng dụng không thể đặt Authorization thông qua headers; Kazzle sở hữu header đó. Đọc ngữ cảnh với toolContext(req) từ @kazzle/app/tools khi trình xử lý phải phân nhánh thread so với Tools API. Một công cụ được khai báo mà không có tuyến đường phù hợp sẽ không làm gì hữu ích — hãy thêm cả hai. tools.json không được hỗ trợ; trình biên dịch ứng dụng sẽ thất bại nếu tìm thấy một.

Handler response

Trả về văn bản thuần túy hoặc JSON với tối đa ba kênh:
  • content — kết quả thuần túy mà AI đọc (được cung cấp cho mô hình). Bắt buộc.
  • markdown — tùy chọn. Một bản tóm tắt văn bản phong phú ngắn được hiển thị trong thẻ công cụ (react-markdown; HTML thô bị thoát). Tốt cho một câu, một danh sách nhỏ, một liên kết nội tuyến. Một đường dẫn tương đối trần hiển thị dưới dạng văn bản được định dạng trước chết — các liên kết phải là tuyệt đối.
  • embedUrl — tùy chọn. Một URL tuyệt đối mà ứng dụng của bạn cung cấp; thẻ hiển thị nó trong một iframe được cách ly. Đây là cách bạn hiển thị một giao diện người dùng thực, toàn chiều rộng — một màn hình kết nối, một bảng điều khiển, một biểu đồ. Ứng dụng của bạn lưu trữ và sở hữu trang, vì vậy nó có thể hoàn toàn tương tác với backend, cookie và OAuth của riêng bạn. Không có gì được viết vào drive.
embedUrl thắng markdown khi cả hai được đặt. Luôn giữ một content có ý nghĩa — đó là những gì AI đọc.

Required action

Một công cụ ứng dụng có thể tạm dừng thread khi nó cần một hành động của người dùng (hoặc thiết bị). Trả về type: 'action_required' với tiêu đề thẻ và các nút. Chỉ hợp lệ khi toolContext(req).source === 'thread' — qua Tools API (source: 'api'), hãy trả về một lỗi miền bình thường thay thế.
Kazzle lưu thẻ trên lệnh gọi công cụ và tiếp tục thông qua /chat/resume sau khi một nút được nhấn. Các máy khách phù hợp thấy các nút tác giả; các máy khách không phù hợp vẫn thấy Skip/Cancel cộng với “Continue on ”. Một nút không có target gửi input của nó dưới dạng kết quả công cụ. Một nút có target chạy target đó trước, sau đó sử dụng kết quả target làm kết quả công cụ.

Rich UI — nhúng một trang được lưu trữ bởi ứng dụng

Khi kết quả của một công cụ là trực quan hoặc tương tác (một màn hình kết nối, một biểu đồ, một bảng điều khiển tóm tắt), hãy cung cấp trang từ một trong các thành phần của bạn và trả về URL tuyệt đối của nó dưới dạng embedUrl. Xây dựng URL từ URL thành phần được tiêm — không bao giờ là một đường dẫn tương đối.
Trang chạy trong một iframe gốc chéo (gốc, cookie và tập lệnh của riêng nó). Để thay đổi kích thước thẻ, hãy đăng chiều cao của nó cho cha mẹ — thẻ lắng nghe điều này và thay đổi kích thước (được giới hạn ở 70% của viewport):
Ưu tiên embedUrl hơn phát ra các chuỗi HTML: ứng dụng của bạn đã cung cấp các trang, giao diện người dùng vẫn tương tác và được phiên bản với mã của bạn, và không có hiện vật trên mỗi cuộc gọi được viết ở bất kỳ đâu.