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

# Dùng Custom API trong Agent

> Gắn REST API connector vào Agent, đặt quyền Tự động, Hỏi, Chặn cho từng thao tác, chạy thử và gỡ khỏi Agent.

<Info icon="plug">
  Trang này hướng dẫn dùng một **REST API connector** đã tạo ở Workspace trong từng Agent. Nếu chưa có Connector, xem [Kết nối Custom API trên Space](/custom-api-connectors) để tạo trước.
</Info>

## Lối vào

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

<Steps>
  <Step title="Mở mục Kết nối của Agent">
    Mở Agent, ở màn hình **Dựng agent** chọn panel **Cấu hình**, nhấn dấu **+** ở mục **Kết nối**.
  </Step>

  <Step title="Chọn kiểu tài khoản">
    Chọn **Dùng chung** (một tài khoản của Workspace) hoặc **Theo người dùng** (tài khoản riêng của mỗi người).

    <img src="https://mintcdn.com/fpt-62e894b4/uqPyYHBiBqVpDc_G/images/agent_connector_add_menu.jpg?fit=max&auto=format&n=uqPyYHBiBqVpDc_G&q=85&s=3806006c91b324fd4dd9131a37e297c5" alt="Menu chọn Dùng chung hoặc Theo người dùng" width="1568" height="706" data-path="images/agent_connector_add_menu.jpg" />
  </Step>

  <Step title="Tích Connector rồi nhấn Xong">
    Custom Connector nằm chung danh sách với Connector có sẵn. Tích Connector cần dùng rồi nhấn **Xong**. Nút **Tạo connector mới** ở góc dưới mở cùng hộp thoại tạo REST API như trên trang Kết nối.

    <img src="https://mintcdn.com/fpt-62e894b4/uqPyYHBiBqVpDc_G/images/agent_connector_picker.jpg?fit=max&auto=format&n=uqPyYHBiBqVpDc_G&q=85&s=64de74369f02759b818cf2a900c5c44c" alt="Hộp chọn Connector dùng chung với Demo Orders API đã được chọn" width="1568" height="706" data-path="images/agent_connector_picker.jpg" />
  </Step>

  <Step title="Mở rộng Connector để xem các thao tác">
    Connector xuất hiện trong mục **Kết nối** kèm kiểu tài khoản và số ngoại lệ. Nhấn vào dòng Connector để xem tài khoản đang dùng và quyền của từng thao tác.

    <img src="https://mintcdn.com/fpt-62e894b4/uqPyYHBiBqVpDc_G/images/agent_connector_permissions.jpg?fit=max&auto=format&n=uqPyYHBiBqVpDc_G&q=85&s=728f3006bb1df3a9ce8728c22275c3f9" alt="Connector đã gắn với quyền mặc định của từng thao tác" width="1568" height="706" data-path="images/agent_connector_permissions.jpg" />
  </Step>
</Steps>

| Kiểu tài khoản | Khi Agent chạy | Nên dùng khi |
| - | - | - |
| **Dùng chung** | Agent luôn dùng cùng một tài khoản của Workspace, bất kể ai hỏi | API nghiệp vụ chung, khoá do quản trị viên cấp |
| **Theo người dùng** | Mỗi người tự kết nối và dùng tài khoản của mình. Trong mục Kết nối, tab này hiện tên **Riêng người** | Mỗi người có khoá hoặc quyền khác nhau trên API |

Với **Dùng chung**, phần **Tài khoản** cho biết Agent đang dùng tài khoản nào. Nhấn biểu tượng đổi tài khoản để chọn tài khoản khác, **Thêm tài khoản** hoặc **Quản lý tài khoản**.

<img src="https://mintcdn.com/fpt-62e894b4/uqPyYHBiBqVpDc_G/images/agent_connector_account.jpg?fit=max&auto=format&n=uqPyYHBiBqVpDc_G&q=85&s=c6c05effc8c20a6eb2abae9c437cea47" alt="Menu chọn tài khoản cho Connector dùng chung" width="1568" height="706" data-path="images/agent_connector_account.jpg" />

Với **Theo người dùng**, mục Connector không có phần Tài khoản. Người dùng chưa kết nối tài khoản của mình thì Agent sẽ báo cần kết nối trước khi gọi thao tác.

<img src="https://mintcdn.com/fpt-62e894b4/uqPyYHBiBqVpDc_G/images/agent_connector_peruser.jpg?fit=max&auto=format&n=uqPyYHBiBqVpDc_G&q=85&s=744f5d1c1bd818b53141c6b74a8f78aa" alt="Connector gắn theo kiểu Theo người dùng" width="1568" height="706" data-path="images/agent_connector_peruser.jpg" />

<Note>
  Trên một Agent, mỗi Connector chỉ gắn được theo một kiểu. Connector đã gắn kiểu Dùng chung sẽ hiện nhãn **Đã thêm** trong hộp chọn Theo người dùng. Muốn đổi kiểu, gỡ Connector rồi gắn lại.
</Note>

## Đặt quyền cho từng thao tác

Mỗi thao tác có ba mức quyền:

| Mức | Agent làm gì | Mặc định cho |
| - | - | - |
| **Tự động** | Gọi API ngay, không hỏi | Thao tác **Chỉ đọc** |
| **Hỏi** | Dừng lại xin người dùng duyệt trước khi gọi | Thao tác **Ghi dữ liệu** và **Có thể xoá dữ liệu** |
| **Chặn** | Không được gọi thao tác này | Không có mặc định, bạn tự đặt |

Số **ngoại lệ** cạnh tên Connector cho biết có bao nhiêu thao tác đang khác mức mặc định. Ví dụ dưới đây đặt **Huỷ đơn hàng** về **Chặn** để Agent không thể huỷ đơn.

<img src="https://mintcdn.com/fpt-62e894b4/uqPyYHBiBqVpDc_G/images/agent_connector_block.jpg?fit=max&auto=format&n=uqPyYHBiBqVpDc_G&q=85&s=9da8c7804d49ba8799849b033ae02803" alt="Thao tác Huỷ đơn hàng được đặt về Chặn" width="1568" height="706" data-path="images/agent_connector_block.jpg" />

<Tip>
  Gỡ rồi gắn lại Connector sẽ đưa quyền của mọi thao tác về mặc định. Ghi lại các ngoại lệ trước khi gỡ.
</Tip>

## Chạy thử Agent với Connector

<Steps>
  <Step title="Gửi yêu cầu ở tab Chạy thử">
    Mở tab **Chạy thử** và gửi một yêu cầu cần đến API, ví dụ: Tạo đơn hàng cho khách Trần Thị B, tổng tiền 250000.
  </Step>

  <Step title="Duyệt hoặc từ chối thao tác">
    Với thao tác ở mức **Hỏi**, thẻ **Cần bạn phê duyệt hành động** hiện tên thao tác và các tham số Agent định gửi. Nhấn **Duyệt** để gọi API. Nhấn **Từ chối** để không gọi, có thể nhập **Lý do từ chối** để Agent điều chỉnh.

    <img src="https://mintcdn.com/fpt-62e894b4/uqPyYHBiBqVpDc_G/images/agent_approval_card.jpg?fit=max&auto=format&n=uqPyYHBiBqVpDc_G&q=85&s=2a789b740a9368f22ff6663aafc46832" alt="Thẻ Cần bạn phê duyệt hành động cho thao tác create_order" width="1568" height="706" data-path="images/agent_approval_card.jpg" />
  </Step>

  <Step title="Xem tham số và kết quả">
    Sau khi Agent trả lời, mở **Đã gọi N công cụ** rồi mở tên công cụ để xem **Tham số** đã gửi và **Kết quả** API trả về.

    <img src="https://mintcdn.com/fpt-62e894b4/uqPyYHBiBqVpDc_G/images/agent_tool_result.jpg?fit=max&auto=format&n=uqPyYHBiBqVpDc_G&q=85&s=c9b7483583521a749acb15167ad7e6cd" alt="Chi tiết lần gọi create_order với tham số và kết quả" width="1568" height="706" data-path="images/agent_tool_result.jpg" />
  </Step>
</Steps>

<Warning>
  Chạy thử gọi API thật và dùng token thật của Workspace. Khi thử các thao tác ghi hoặc xoá, hãy trỏ Connector tới môi trường thử nghiệm của API.
</Warning>

<Note>
  Thay đổi Connector trong Agent được tự động lưu vào bản nháp. Người dùng cuối chỉ thấy thay đổi sau khi bạn Publish phiên bản mới của Agent.
</Note>

## Gỡ Connector khỏi Agent

Nhấn biểu tượng **thùng rác** ở dòng Connector trong mục **Kết nối**. Connector được gỡ ngay, không có hộp thoại xác nhận. Connector vẫn còn trong Workspace và có thể gắn lại bất cứ lúc nào.

<Note>
  Khi Connector được import lại ở Space, thao tác bị xoá hoặc đổi tên trong tài liệu mới không còn trong Agent. Mở lại mục **Kết nối** của Agent để kiểm tra quyền và chạy thử lại.
</Note>

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

| Hiện tượng | Nguyên nhân | Cách xử lý |
| - | - | - |
| Agent báo cần kết nối tài khoản | Connector gắn kiểu **Theo người dùng** và người dùng chưa kết nối | Người dùng kết nối tài khoản của mình trước khi dùng |

## Xem thêm

<CardGroup cols={2}>
  <Card title="Kết nối Custom API trên Space" icon="plug" href="/custom-api-connectors">
    Tạo, sửa, import lại và xoá Connector.
  </Card>

  <Card title="Kết nối (Connectors)" icon="link" href="/connections">
    Cách gắn Connector có sẵn và các mức quyền cho công cụ.
  </Card>
</CardGroup>


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