> ## Documentation Index
> Fetch the complete documentation index at: https://docs-eos.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 Nhân sự số đ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ý Nhân sự số đó như mọi Nhân sự số khác

Bạn đã có sẵn một Nhân sự số 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 Nhân sự số đó 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.

> [!NOTE]
>
> 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".

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

* Nhân sự số đã 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 Nhân sự số.
* 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 Nhân sự số ngay trên nền tảng thì dùng mục **Nhân sự số 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 Nhân sự số, 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` | External Agent phải nói đúng giao thức `fpt-v1` 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 Nhân sự số 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]
>
> Đội kỹ thuật bên đối tác đọc [Chuẩn bị kỹ thuật cho External Agent](https://docs-eos.fpt.ai/eos/vi/external-agent-requirements.md). Trang đó mô tả đầy đủ hai endpoint, cách xác thực, định dạng luồng trả về và các mốc thời gian phải đạt.

## Kết nối một Nhân sự số

**1. Mở mục Agent bên thứ ba**

Menu trái của Console, nhóm **XÂY DỰNG**.

**2. Bấm Kết nối Nhân sự số**

Nút xanh ở góc phải trên. Lần đầu chưa có Nhân sự số nào thì bấm nút **Kết nối Nhân sự số** ở giữa màn hình.

**3. Điền thông tin kết nối**

Tên Nhân sự số, Mô tả, Base URL và cách xác thực. Chi tiết từng trường ở bảng dưới.

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

**5. Bấm Lưu**

Nhân sự số đượ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.

![Form kết nối Agent bên thứ ba](https://mintcdn.com/fpt-15dbd015/gDW0AWl75k3m2kQW/images/eos/ext_form.jpg?fit=max\&auto=format\&n=gDW0AWl75k3m2kQW\&q=85\&s=fef4fc97336092ea60628d00a749bb57)

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

| Trường | Bắt buộc | Ý nghĩa | Ví dụ |
| - | - | - | - |
| Tên Nhân sự số | 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 | Nhân sự số 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 Nhân sự số. 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`.

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

![Kết quả kiểm tra kết nối](https://mintcdn.com/fpt-15dbd015/gDW0AWl75k3m2kQW/images/eos/ext_check.jpg?fit=max\&auto=format\&n=gDW0AWl75k3m2kQW\&q=85\&s=b3b579cd0701d3e13143ecb7302ea046)

| Mục | Nền tảng kiểm gì |
| - | - |
| Gọi tới được endpoint | Nhân sự số 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` | Nhân sự số 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 |
| Nhân sự số 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 Nhân sự số đã kết nối

![Danh sách Agent bên thứ ba](https://mintcdn.com/fpt-15dbd015/gDW0AWl75k3m2kQW/images/eos/ext_list.jpg?fit=max\&auto=format\&n=gDW0AWl75k3m2kQW\&q=85\&s=2b9a7357edee7d83188d9e37a0f468cb)

Mỗi Nhân sự số 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 Nhân sự số** ở bên phải lọc theo tên.

## Trang chi tiết của một Nhân sự số

![Trang chi tiết Agent bên thứ ba](https://mintcdn.com/fpt-15dbd015/gDW0AWl75k3m2kQW/images/eos/ext_detail.jpg?fit=max\&auto=format\&n=gDW0AWl75k3m2kQW\&q=85\&s=9cf77f19f83c76c83c1e38ddf898e53b)

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

Thẻ **Dựng Nhân sự số** 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 Nhân sự số 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 Nhân sự số 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 Nhân sự số thường, xem [Xuất bản](https://docs-eos.fpt.ai/eos/vi/publishing.md) và [Quản lý kênh triển khai](https://docs-eos.fpt.ai/eos/vi/manage-channels.md).

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

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

**2. 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ẻ Nhân sự số ở màn hình danh sách.

**3. Xóa Nhân sự số**

Menu **...** rồi chọn **Xoá Nhân sự số**. Console hỏi xác nhận trước khi xóa.

> [!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 Nhân sự số 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.

## Bước tiếp theo

> **[Quản lý kênh triển khai](https://docs-eos.fpt.ai/eos/vi/manage-channels.md)**
>
> Chọn kênh và phạm vi phát hành cho Nhân sự số.

> **[Kênh Live Chat](https://docs-eos.fpt.ai/eos/vi/live-chat-channel.md)**
>
> Đưa Nhân sự số lên website bằng khung chat có sẵn.

> **[Tích hợp API](https://docs-eos.fpt.ai/eos/vi/api-integration.md)**
>
> Dùng khi bạn đã có sẵn giao diện chat riêng.


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