> ## 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 Agent bên ngoài

> Đưa một Agent đang chạy ngoài FPT AI Platform vào Workspace: Khai báo kết nối, chạy kiểm tra và quản lý Agent đó như mọi Agent khác

Bạn đã có sẵn một Agent chạy trên hệ thống của mình và không muốn dựng lại từ đầu trên nền tảng. Tính năng này cho phép bạn khai báo Agent đó vào Workspace: Nền tảng giữ phần quản lý, kênh triển khai và phân tích, còn phần xử lý vẫn nằm ở hệ thống của bạn.

<Info icon="globe">
  Mở từ menu trái của Console, nhóm **XÂY DỰNG**, mục **Agent bên thứ ba**. Trên giao diện Console tính năng mang tên "Agent bên thứ ba", tài liệu này dùng cùng một nghĩa với "Agent bên ngoài".
</Info>

## Khi nào nên dùng

* Agent đã chạy ổn trên hệ thống riêng, ví dụ n8n, LangGraph, một dịch vụ nội bộ hay một sản phẩm của đối tác.
* Bạn muốn dùng chung Workspace, kênh triển khai và báo cáo của nền tảng mà không phải viết lại logic Agent.
* Bạn muốn kiểm soát dữ liệu: Tri thức và xử lý vẫn nằm trong hạ tầng của mình.

Nếu bạn muốn dựng Agent ngay trên nền tảng thì dùng mục **Agent của tôi** thay vì mục này.

## Cần chuẩn bị gì trước khi kết nối

| Thứ cần có | Ý nghĩa |
| - | - |
| Base URL | Địa chỉ gốc của Agent, ví dụ `https://agent.congty.vn/ai`. Nền tảng sẽ gọi `/health` và `/runs` dưới địa chỉ này |
| Giao thức `fpt-v1` | Agent phải nói đúng giao thức Agent của nền tảng. Đây là việc của đội kỹ thuật bên bạn |
| Thông tin xác thực | Header và giá trị để nền tảng gọi được vào hệ thống của bạn, nếu hệ thống đó có kiểm tra người gọi |

<Note>
  Nút **Hướng dẫn tích hợp** ở góc phải trên màn hình danh sách dành cho đội kỹ thuật đã dựng Agent phía đối tác. Người cấu hình trên Console chỉ cần Base URL và thông tin xác thực do đội kỹ thuật cung cấp.
</Note>

## Kết nối một Agent

<Steps>
  <Step title="Mở mục Agent bên thứ ba">
    Menu trái của Console, nhóm **XÂY DỰNG**.
  </Step>

  <Step title="Bấm Kết nối agent">
    Nút xanh ở góc phải trên. Lần đầu chưa có Agent nào thì bấm nút **Kết nối agent** ở giữa màn hình.
  </Step>

  <Step title="Điền thông tin kết nối">
    Tên agent, Mô tả, Base URL và cách xác thực. Chi tiết từng trường ở bảng dưới.
  </Step>

  <Step title="Bấm Kiểm tra kết nối">
    Nền tảng gọi thử sang hệ thống của bạn và chấm năm mục. Chỉ lưu được khi cả năm mục đều đạt.
  </Step>

  <Step title="Bấm Lưu">
    Agent được tạo ở trạng thái **Nháp** và Console mở thẳng trang chi tiết. Trước khi bấm Lưu thì chưa có gì được ghi lại.
  </Step>
</Steps>

<img src="https://mintcdn.com/fpt-62e894b4/jfePhRHunhqLSFUS/images/ext_form.jpg?fit=max&auto=format&n=jfePhRHunhqLSFUS&q=85&s=ceb8d77e0fb7de161ce2a933c639ef58" alt="Form kết nối Agent bên thứ ba" width="1568" height="677" data-path="images/ext_form.jpg" />

### Bảng tham chiếu các trường

| Trường | Bắt buộc | Ý nghĩa | Ví dụ |
| - | - | - | - |
| Tên agent | Có | Tên hiển thị trong danh sách và trên các kênh. Tối đa 60 ký tự | Trợ lý kho vận |
| Mô tả | Không | Agent làm được gì và khi nào nên dùng. Tối đa 200 ký tự | Tra cứu tồn kho và tình trạng đơn hàng |
| Base URL | Có | Địa chỉ gốc của Agent. Nhận cả https và http | `https://agent.congty.vn/ai` |
| Xác thực | Có | Chọn **Có xác thực** hoặc **Không xác thực** | Có xác thực |
| Header xác thực | Có, khi chọn Có xác thực | Tên header và giá trị. Thêm nhiều header bằng nút **Thêm header** | `Authorization` / `Bearer abc123` |

<Warning>
  Base URL nhận cả `http`, nhưng khi đó thông tin xác thực đi ở dạng văn bản thuần. Chỉ dùng `http` với đối tác nội bộ, còn lại luôn dùng `https`.
</Warning>

### Hai cách xác thực

* **Có xác thực**: Nền tảng gửi đúng nguyên văn header bạn khai, không tự thêm gì. Dùng bearer token thì phải gõ cả chữ `Bearer ` ở đầu giá trị. Giá trị chỉ được lưu, không bao giờ hiển thị lại.
* **Không xác thực**: Nền tảng không gửi gì để xác thực. Chỉ chọn khi hệ thống đối tác đã tự chặn bằng cách khác, ví dụ lọc theo dải IP.

### Năm mục kiểm tra

<img src="https://mintcdn.com/fpt-62e894b4/jfePhRHunhqLSFUS/images/ext_check.jpg?fit=max&auto=format&n=jfePhRHunhqLSFUS&q=85&s=c7e67b779067ac623b1f8c9d2c68b2fa" alt="Kết quả kiểm tra kết nối" width="1568" height="677" data-path="images/ext_check.jpg" />

| Mục | Nền tảng kiểm gì |
| - | - |
| Gọi tới được endpoint | Agent có trả lời lệnh kiểm tra `/health` không |
| Đối tác chấp nhận xác thực | Hệ thống của bạn có chấp nhận thông tin xác thực nền tảng gửi sang không |
| Đối tác hỗ trợ `fpt-v1` | Agent có nói đúng giao thức của nền tảng không |
| Đã lưu credential | Thông tin xác thực đã được lưu. Đây là điều kiện để phát hành |
| Agent trả lời được một lượt thật | Nền tảng gửi một lượt hội thoại vào `/runs` và đối tác trả lời đúng. Đây là điều mà kiểm tra `/health` không phát hiện ra |

Cuối bảng kết quả có dòng đối tác tự khai tên và phiên bản, kèm thời gian phản hồi. Mục nào không đạt sẽ báo đỏ kèm lý do, bạn sửa lại thông tin rồi bấm **Kiểm tra kết nối** lần nữa.

## Xem danh sách Agent đã kết nối

<img src="https://mintcdn.com/fpt-62e894b4/jfePhRHunhqLSFUS/images/ext_list.jpg?fit=max&auto=format&n=jfePhRHunhqLSFUS&q=85&s=ee41fce1942bc2e10cb9914bc0ccbe80" alt="Danh sách Agent bên thứ ba" width="1568" height="677" data-path="images/ext_list.jpg" />

Mỗi Agent hiển thị thành một thẻ, gồm tên, trạng thái, mô tả và thời điểm sửa gần nhất. Phía trên có bộ lọc theo trạng thái: **Tất cả**, **Nháp**, **Đang chạy**, **Tạm dừng**, kèm số lượng của từng nhóm. Ô **Tìm agent** ở bên phải lọc theo tên.

## Trang chi tiết của một Agent

<img src="https://mintcdn.com/fpt-62e894b4/jfePhRHunhqLSFUS/images/ext_detail.jpg?fit=max&auto=format&n=jfePhRHunhqLSFUS&q=85&s=c9c10e00ff69ad4c1720c57cbe8bda52" alt="Trang chi tiết Agent bên thứ ba" width="1568" height="677" data-path="images/ext_detail.jpg" />

Trang chi tiết có bốn thẻ trên thanh trên cùng: **Dựng agent**, **Kiểm thử**, **Kênh triển khai** và **Phân tích**.

Thẻ **Dựng agent** cho biết kết nối đang ở tình trạng nào:

| Mục | Ý nghĩa |
| - | - |
| Base URL | Địa chỉ đang dùng |
| Xác thực | Có hay không có xác thực |
| Credential | Đã lưu thông tin xác thực hay không cần |
| Tình trạng | Kết quả lần kiểm tra gần nhất, kèm nút **Kiểm tra lại** |

Bảng **Endpoint** liệt kê các địa chỉ nền tảng sẽ gọi trên Agent của bạn và trạng thái từng địa chỉ. Hai địa chỉ bắt buộc là `/health` và `/runs`, các địa chỉ còn lại là tùy chọn và chưa mở trong giai đoạn này.

## Sau khi kết nối xong

Agent bên ngoài dùng chung phần còn lại với Agent dựng trên nền tảng:

* Thẻ **Kiểm thử** cho bạn chạy thử một lượt thật trước khi phát hành.
* Thẻ **Kênh triển khai** chọn phạm vi trên Workspace và các kênh ngoài như Web widget, API, Zalo.
* Nút **Publish** ở góc phải trên đưa phiên bản vào chạy.

Ba việc này làm giống hệt Agent thường, xem [Xuất bản](/publish-agent) và [Quản lý kênh triển khai](/quan-ly-kenh-trien-khai).

## Sửa, kiểm tra lại và xóa

<Steps>
  <Step title="Sửa kết nối">
    Ở trang chi tiết, bấm biểu tượng bút chì cạnh nút **Publish**, hoặc nút **Sửa kết nối**. Hộp thoại mở ra giống hệt lúc tạo và cũng phải qua bước kiểm tra trước khi lưu.
  </Step>

  <Step title="Kiểm tra lại kết nối">
    Bấm **Kiểm tra lại** ở khối Kết nối hoặc ở bảng Endpoint. Cũng có thể chọn **Kiểm tra ngay** trong menu **...** ở góc phải trên hoặc trên thẻ Agent ở màn hình danh sách.
  </Step>

  <Step title="Xóa Agent">
    Menu **...** rồi chọn **Xoá agent**. Console hỏi xác nhận trước khi xóa.
  </Step>
</Steps>

<Warning>
  Sửa Base URL hay thông tin xác thực chỉ có hiệu lực với người dùng thật sau khi bạn phát hành lại. Xóa Agent sẽ gỡ nó khỏi mọi kênh đang chạy, khách hàng đang trò chuyện sẽ không nhận được câu trả lời nữa.
</Warning>

## Bước tiếp theo

<CardGroup cols={3}>
  <Card title="Quản lý kênh triển khai" icon="share-nodes" href="/quan-ly-kenh-trien-khai">
    Chọn kênh và phạm vi phát hành cho Agent.
  </Card>

  <Card title="Kênh Live Chat" icon="comments" href="/kenh-live-chat">
    Đưa Agent lên website bằng khung chat có sẵn.
  </Card>

  <Card title="Tích hợp API" icon="code" href="/tich-hop-api">
    Dùng khi bạn đã có sẵn giao diện chat riêng.
  </Card>
</CardGroup>


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