Skip to main content
REST API connector biến mỗi thao tác (operation) của một REST API thành một công cụ mà Agent gọi được. Bạn tạo và quản lý Connector ở trang Kết nối của Workspace, sau đó gắn vào từng Agent và đặt quyền cho từng thao tác trong trang chi tiết Agent.

​
Các lối vào tính năng

​
Trước khi bắt đầu

  • Tài liệu API: File OpenAPI 3.x hoặc Swagger 2.0 dạng JSON/YAML, tối đa 2 MB. Nếu không có tài liệu, bạn cần base URL và danh sách endpoint để tự khai báo.
  • Base URL công khai: Hệ thống chặn địa chỉ trỏ tới máy cục bộ hoặc dải IP nội bộ (ví dụ localhost, 169.254.169.254). Nên dùng https.
  • Thông tin xác thực: API key/token, hoặc thông tin OAuth 2.1 của API.
  • Giới hạn: Mỗi Connector giữ tối đa 200 thao tác. Tài liệu có nhiều hơn thì chỉ 200 thao tác đầu tiên được nhập.

​
Tạo Connector

​
Cách 1: Import tài liệu Swagger/OpenAPI

1

Mở tab Custom Connectors

Vào Kết nối ở thanh bên trái, chọn tab Custom Connectors.Tab Custom Connectors khi chưa có Connector nào
2

Chọn Thêm connector → REST API

Menu có hai lựa chọn: REST API (import Swagger/OpenAPI hoặc tự khai báo) và MCP server (kết nối MCP server qua URL). Chọn REST API.Menu Thêm connector với hai lựa chọn REST API và MCP server
3

Bước 1 Nguồn: Đưa tài liệu vào

Ở tab Import Swagger/OpenAPI, kéo thả file vào khung hoặc nhấn Chọn file. Bạn cũng có thể dán nội dung vào ô Hoặc dán nội dung tài liệu. Nhấn Tiếp tục.Bước Nguồn với tài liệu OpenAPI đã dán
4

Bước 2 Kết nối: Kiểm tra thông tin kết nối

Tên, Base URL và kiểu Xác thực được điền sẵn từ tài liệu (có nhãn Lấy từ tài liệu). Kiểm tra lại, nhập Giá trị khoá nếu API cần, rồi nhấn Tiếp tục. Ý nghĩa từng trường xem ở bảng trường bước Kết nối bên dưới.Bước Kết nối với Base URL và xác thực lấy từ tài liệu
5

Bước 3 Thao tác: Chọn thao tác cho Agent

Mỗi thao tác hiện method, đường dẫn, nhãn mức độ, tên công cụ Agent sẽ thấy (ví dụ demo-orders-api__list_orders) và mô tả. Bỏ tích thao tác không cần, lọc theo method, hoặc mở rộng một thao tác để sửa mô tả và tham số. Nhấn Tạo connector.Bước Thao tác với 5 thao tác đã chọn
6

Kiểm tra kết quả

Thông báo Đã tạo connector với N thao tác. hiện lên và thẻ Connector xuất hiện với trạng thái Đã kết nối.Thẻ Connector mới tạo với trạng thái Đã kết nối
Mô tả của thao tác là thứ Agent đọc để quyết định khi nào gọi API. Viết mô tả rõ việc thao tác làm và khi nào nên dùng, kể cả khi tài liệu gốc đã có summary.

​
Cách 2: Tự khai báo

Dùng khi API không có tài liệu OpenAPI, hoặc bạn chỉ muốn mở vài endpoint cho Agent.
1

Chọn tab Tự khai báo

Trong hộp thoại Tạo connector API, chọn tab Tự khai báo rồi nhấn Tiếp tục.Tab Tự khai báo ở bước Nguồn
2

Nhập thông tin kết nối

Nhập Tên, Base URL và chọn kiểu Xác thực như ở cách 1.
3

Khai báo từng thao tác

Điền Method, Đường dẫn, Tên, Mức độ, Mô tả, tham số và Mô tả kết quả trả về. Nhấn Thêm thao tác để khai báo thêm, rồi nhấn Tạo connector.Form khai báo thao tác lấy chi tiết đơn hàng
Viết tham số đường dẫn dạng {order_id} trong ô Đường dẫn, Console sẽ tự thêm tham số tương ứng với vị trí Path.

​
Bảng trường bước Kết nối

Với OAuth 2.1: Với cả hai kiểu OAuth, sau khi lưu sẽ có một cửa sổ mở ra để bạn uỷ quyền.

​
Bảng trường bước Thao tác

Khi import tài liệu, mức độ được gợi ý theo method: GET là Chỉ đọc, POST/PUT/PATCH là Ghi dữ liệu, DELETE là Có thể xoá dữ liệu. Bạn có thể đổi lại khi mở rộng thao tác.

​
Xem danh sách Connector

Tab Custom Connectors hiện số lượng Connector và một thẻ cho mỗi Connector:
  • Tên và mô tả của Connector.
  • Trạng thái, ví dụ Đã kết nối.
  • Số thao tác và nguồn tạo (OpenAPI khi import từ tài liệu).
  • Biểu tượng thùng rác để xoá và nút Quản lý để sửa.
Dùng ô Tìm Custom Connectors… để lọc theo tên khi có nhiều Connector.

​
Sửa Connector

Nhấn Quản lý trên thẻ để mở hộp thoại Chỉnh sửa connector API. Hộp thoại có ba tab Nguồn, Kết nối, Thao tác. Sửa xong nhấn Lưu thay đổi, thông báo Đã cập nhật connector. sẽ hiện lên.

​
Sửa thông tin kết nối

Ở tab Kết nối, bạn đổi được tên, Base URL và kiểu xác thực. Khoá đã lưu hiện dạng •••• đã lưu, nhấn Thay khoá để nhập khoá mới. Tab Kết nối trong hộp thoại Chỉnh sửa connector API Nếu bạn đổi Base URL hoặc kiểu xác thực, Console cảnh báo mọi kết nối hiện có sẽ bị ngắt và cần kết nối lại. Cảnh báo khi đổi địa chỉ hoặc kiểu xác thực

​
Import lại tài liệu khi API thay đổi

1

Dán phiên bản tài liệu mới

Ở tab Nguồn, kéo thả file mới hoặc dán nội dung tài liệu mới.Tab Nguồn với tài liệu phiên bản 1.1.0
2

Rà lại tab Thao tác

Mở tab Thao tác để xem danh sách sau khi import, chọn lại thao tác cần dùng.Tab Thao tác sau khi import lại, có thêm thao tác hoàn tiền
3

Lưu thay đổi

Nhấn Lưu thay đổi. Số thao tác trên thẻ Connector được cập nhật.
Import lại sẽ thay toàn bộ danh sách thao tác bằng nội dung tài liệu mới. Thao tác bị xoá hoặc đổi tên trong tài liệu mới sẽ không còn trong các Agent đang dùng Connector này. Sau khi lưu, mở lại các Agent liên quan để kiểm tra quyền của từng thao tác và chạy thử lại.
Nếu bạn nhấn Hủy khi đang có thay đổi chưa lưu, Console hỏi Bỏ thay đổi?. Chọn Bỏ thay đổi để thoát hoặc Tiếp tục chỉnh sửa để quay lại.

​
Xoá Connector

1

Nhấn biểu tượng thùng rác trên thẻ Connector

Hộp thoại xác nhận hiện lên.Hộp thoại xác nhận xoá Connector
2

Nhấn Xoá connector

Thông báo Đã xoá connector. hiện lên. Connector được gỡ khỏi mọi Agent đang dùng.
Xoá Connector không thể hoàn tác. Các Agent đang dùng thao tác của Connector sẽ mất quyền truy cập ngay. Hộp thoại không liệt kê Agent nào đang dùng, nên hãy tự kiểm tra trước khi xoá.
Connector không có trạng thái tạm dừng. Muốn ngừng tạm thời cho một Agent, hãy gỡ Connector khỏi Agent đó hoặc đặt các thao tác về Chặn.
Sau khi tạo xong, gắn Connector vào Agent theo hướng dẫn ở Dùng Custom API trong Agent.

​
Lỗi thường gặp

​
Xem thêm

Dùng Custom API trong Agent

Gắn Connector vào Agent, đặt quyền và chạy thử.