> ## Documentation Index
> Fetch the complete documentation index at: https://docs-agents.fpt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kết nối Custom API trên Space

> Tạo, xem, sửa và xoá REST API connector ở trang Kết nối của Workspace, bằng tài liệu Swagger/OpenAPI hoặc tự khai báo.

<Info icon="plug">
  **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.
</Info>

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

| Lối vào | Đường đi | Dùng để |
| - | - | - |
| Trang Kết nối | Thanh bên trái → **Kết nối** → tab **Custom Connectors** → **Thêm connector** → **REST API** | Tạo, xem, sửa, xoá Connector |
| Màn hình trống | Tab **Custom Connectors** khi chưa có Connector nào → nút **Thêm connector** ở giữa màn hình | Tạo Connector đầu tiên |
| Trang chi tiết Agent | **Agent của tôi** → mở Agent → **Dựng agent** → panel **Cấu hình** → mục **Kết nối** → dấu **+** | Gắn Connector vào Agent, đặt quyền, gỡ khỏi Agent |
| Hộp chọn Connector của Agent | Trong hộp thoại chọn Connector → **Tạo connector mới** → **REST API** | Tạo Connector mới mà không rời trang Agent |

## 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

<Steps>
  <Step title="Mở tab Custom Connectors">
    Vào **Kết nối** ở thanh bên trái, chọn tab **Custom Connectors**.

    <img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/custom_api_empty.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=1bf0a672d0cf98634ec6fa6cdaf9698f" alt="Tab Custom Connectors khi chưa có Connector nào" width="1568" height="706" data-path="images/custom_api_empty.jpg" />
  </Step>

  <Step title="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**.

    <img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/custom_api_add_menu.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=13245c0a80290e3ca07ee192ae8e2759" alt="Menu Thêm connector với hai lựa chọn REST API và MCP server" width="1568" height="706" data-path="images/custom_api_add_menu.jpg" />
  </Step>

  <Step title="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**.

    <img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/custom_api_source_import.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=d544805ea641138a231fd17e52944230" alt="Bước Nguồn với tài liệu OpenAPI đã dán" width="1568" height="706" data-path="images/custom_api_source_import.jpg" />
  </Step>

  <Step title="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.

    <img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/custom_api_connection.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=61a280b977ca2957bf5bed0d68f001cc" alt="Bước Kết nối với Base URL và xác thực lấy từ tài liệu" width="1568" height="706" data-path="images/custom_api_connection.jpg" />
  </Step>

  <Step title="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**.

    <img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/custom_api_operations.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=8feccd0b9067488d80bb019db80ced90" alt="Bước Thao tác với 5 thao tác đã chọn" width="1568" height="706" data-path="images/custom_api_operations.jpg" />
  </Step>

  <Step title="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**.

    <img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/custom_api_card.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=c5ff2dbb2ed9c7cf630352398fddf13e" alt="Thẻ Connector mới tạo với trạng thái Đã kết nối" width="1568" height="706" data-path="images/custom_api_card.jpg" />
  </Step>
</Steps>

<Tip>
  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`.
</Tip>

### 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.

<Steps>
  <Step title="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**.

    <img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/custom_api_source_manual.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=08afd33f93ea9fcd26679e38b95fadf3" alt="Tab Tự khai báo ở bước Nguồn" width="1568" height="706" data-path="images/custom_api_source_manual.jpg" />
  </Step>

  <Step title="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.
  </Step>

  <Step title="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**.

    <img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/custom_api_manual_ops.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=b0c063202fb9cc96efc07ff7d8958a1e" alt="Form khai báo thao tác lấy chi tiết đơn hàng" width="1568" height="706" data-path="images/custom_api_manual_ops.jpg" />
  </Step>
</Steps>

<Tip>
  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**.
</Tip>

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

| Trường | Bắt buộc | Ý nghĩa | Ví dụ |
| - | - | - | - |
| **Tên** | Có | Tên hiển thị của Connector, không trùng với Connector khác. Tên cũng là tiền tố của tên công cụ | `Demo Orders API` |
| **Base URL** | Có | Địa chỉ gốc. Đường dẫn của mọi thao tác được nối sau URL này | `https://api.example.com/v1` |
| **Xác thực** | Có | **Không xác thực**, **API key / Token**, **OAuth 2.1 (Auto)** hoặc **OAuth 2.1 (Manual)** | API key / Token |
| **Gửi qua** | Khi chọn API key | Gửi khoá trong **Header** hay **Query** | Header |
| **Tên header** | Khi chọn API key | Tên header hoặc tham số query chứa khoá | `X-API-Key`, `Authorization` |
| **Giá trị** | Khi chọn API key | Khoá hoặc token. Được lưu mã hoá và không hiển thị lại | `sk-...` |
| **Kiểm tra kết nối khi lưu** | Không | Gọi thử một thao tác GET không cần tham số để xác nhận khoá hợp lệ | Bật |
| **Nâng cao → Mô tả** | Không | Mô tả ngắn về API, hiện trên thẻ Connector | API quản lý đơn hàng |
| **Nâng cao → Thao tác dùng để kiểm tra** | Không | Thao tác GET dùng khi kiểm tra kết nối. Mặc định **Tự chọn** | `list_orders` |

Với OAuth 2.1:

| Kiểu | Bạn cần nhập | Ghi chú |
| - | - | - |
| **OAuth 2.1 (Auto)** | Không cần nhập thêm | Console tự tìm endpoint OAuth từ base URL (RFC 9728, RFC 8414) và tự đăng ký client (RFC 7591) |
| **OAuth 2.1 (Manual)** | **Authorize URL**, **Token URL**, **Client ID**. Tuỳ chọn: **Client secret**, **Scope** (cách nhau bằng dấu cách hoặc dấu phẩy) | Dành cho API không công bố metadata OAuth hoặc không cho đăng ký client |

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

| Trường | Bắt buộc | Ý nghĩa | Ví dụ |
| - | - | - | - |
| **Method** | Có | `GET`, `POST`, `PUT`, `PATCH` hoặc `DELETE` | `GET` |
| **Đường dẫn** | Có | Đường dẫn nối sau Base URL. Tham số path viết dạng `{id}` | `/orders/{order_id}` |
| **Tên** | Có | Tên công cụ. Agent thấy công cụ dưới dạng `tên-connector__tên` | `get_order` |
| **Mức độ** | Có | **Chỉ đọc**, **Ghi dữ liệu** hoặc **Có thể xoá dữ liệu**. Quyết định quyền mặc định khi gắn vào Agent | Chỉ đọc |
| **Mô tả** | Nên có | Agent dựa vào mô tả để quyết định khi nào gọi thao tác | Lấy chi tiết một đơn hàng theo mã đơn. |
| **Tham số** | Không | Mỗi tham số gồm tên, vị trí (**Path**, **Query**, **Header**, **Trường trong body (JSON)**, **Toàn bộ body (JSON)**, **Trường form**), kiểu dữ liệu, mô tả và ô **Bắt buộc**. Có thể sửa dạng **Bảng** hoặc **JSON** | `order_id`, Path, string |
| **Mô tả kết quả trả về** | Không | Mô tả dữ liệu API trả về, tối đa 1000 ký tự | Trạng thái đơn, tổng tiền, tên khách hàng. |

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.

<img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/custom_api_edit_connection.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=7fdb88ad0948d020ec39b15ecee6a089" alt="Tab Kết nối trong hộp thoại Chỉnh sửa connector API" width="1568" height="706" data-path="images/custom_api_edit_connection.jpg" />

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.

<img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/custom_api_auth_warning.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=2d2f938ab4c6f9c18c2098d2c26a18ac" alt="Cảnh báo khi đổi địa chỉ hoặc kiểu xác thực" width="1568" height="706" data-path="images/custom_api_auth_warning.jpg" />

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

<Steps>
  <Step title="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.

    <img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/custom_api_reimport.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=94962a88786744d965afd9f817269ba8" alt="Tab Nguồn với tài liệu phiên bản 1.1.0" width="1568" height="706" data-path="images/custom_api_reimport.jpg" />
  </Step>

  <Step title="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.

    <img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/custom_api_reimport_operations.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=837f864df430104a81d6b7a4446444a4" alt="Tab Thao tác sau khi import lại, có thêm thao tác hoàn tiền" width="1568" height="706" data-path="images/custom_api_reimport_operations.jpg" />
  </Step>

  <Step title="Lưu thay đổi">
    Nhấn **Lưu thay đổi**. Số thao tác trên thẻ Connector được cập nhật.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

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

<Steps>
  <Step title="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.

    <img src="https://mintcdn.com/fpt-62e894b4/QoR5TRjlHkD1hiEJ/images/custom_api_delete.jpg?fit=max&auto=format&n=QoR5TRjlHkD1hiEJ&q=85&s=549251014931eb2c63596e4ea0d97007" alt="Hộp thoại xác nhận xoá Connector" width="1568" height="706" data-path="images/custom_api_delete.jpg" />
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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á.
</Warning>

<Note>
  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**.
</Note>

Sau khi tạo xong, gắn Connector vào Agent theo hướng dẫn ở [Dùng Custom API trong Agent](/agent-custom-api-connectors).

## Lỗi thường gặp

| Hiện tượng | Nguyên nhân | Cách xử lý |
| - | - | - |
| **Đã có connector tên này. Chọn tên khác.** | Tên trùng với Connector đã có | Đổi tên ở bước Kết nối |
| **Base URL phải là địa chỉ công khai...** khi nhấn Tạo connector | Base URL trỏ tới máy cục bộ hoặc IP nội bộ | Dùng địa chỉ công khai của API |
| Chỉ 200 thao tác được nhập | Tài liệu có hơn 200 thao tác | Tách tài liệu thành nhiều Connector theo nhóm nghiệp vụ |
| Không đọc được tài liệu | JSON/YAML sai cú pháp hoặc không phải OpenAPI/Swagger | Kiểm tra tài liệu bằng công cụ validate OpenAPI rồi import lại |
| Tên công cụ có dạng lạ như `api-n-h-ng-demo__...` | Tên Connector có dấu tiếng Việt, ký tự có dấu bị thay bằng `-` | Đặt tên Connector không dấu, ví dụ `Orders API` |

## Xem thêm

<CardGroup cols={2}>
  <Card title="Dùng Custom API trong Agent" icon="robot" href="/agent-custom-api-connectors">
    Gắn Connector vào Agent, đặt quyền và chạy thử.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.