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

# Bắt Đầu với AgentEye

> Tài liệu Bắt Đầu với AgentEye.

Hướng dẫn này sẽ hướng dẫn bạn qua một quá trình thiết lập AgentEye hoàn chỉnh: triển khai máy chủ và bảng điều khiển, cài đặt trình thu thập dữ liệu trên máy agent, và thêm công cụ theo dõi vào mã agent Python của bạn.

***

## AgentEye là gì?

AgentEye là một **nền tảng theo dõi và đánh giá được tự lưu trữ cho các AI agent**. Nó ghi lại những gì agent của bạn làm — mọi bước của một lần chạy — và tự động đánh giá chất lượng của mỗi lần chạy hoàn thành, giúp bạn thấy cách agent của bạn hoạt động trong môi trường production và phát hiện những suy giảm trước khi người dùng của bạn phát hiện.

Dữ liệu chảy theo một hướng: mã agent của bạn phát ra **các sự kiện** thông qua **Python SDK** → một daemon **trình thu thập** nhẹ nhàng gom lô và gửi chúng đến **máy chủ** → các sự kiện và phân tích được lưu trữ trong **ClickHouse** (trạng thái hoạt động như tổ chức, người dùng, khóa API, bảng điều khiển và các truy vấn đã lưu sống trong **Postgres**) → bạn khám phá mọi thứ trong **bảng điều khiển**.

Những gì bạn nhận được:

* **Các sự kiện** — đường dẫu thô, từng bước của mỗi lần chạy agent (các lệnh gọi công cụ, lệnh gọi mô hình, hook, lỗi).
* **Các phiên** — những sự kiện đó được tập hợp thành một hàng cho mỗi lần chạy, mỗi cái được **tự động đánh giá** và chấm điểm.
* **Các đánh giá** — điểm chất lượng được tạo ra bởi các dịch vụ đánh giá của riêng bạn, vì vậy những sự suy giảm chất lượng sẽ được phát hiện mà không cần kiểm tra thủ công.
* **Các truy vấn và bảng điều khiển** — SQL ClickHouse đã lưu trên dữ liệu của bạn, được vẽ thành các bảng điều khiển được chia sẻ và được phạm vi tổ chức.
* **Cảnh báo và sự cố** — các quy tắc ngưỡng sẽ gửi thông báo cho bạn (email, Slack, webhook, trong bảng điều khiển) cộng với quy trình làm việc sự cố để phân loại chúng.
* **CLI và trợ lý AI** — một ứng dụng khách terminal (`agenteye`) và một trợ lý trong bảng điều khiển để đặt câu hỏi bằng tiếng Anh thuần.

Bạn chạy tất cả chúng trong cơ sở hạ tầng của riêng mình, dưới dạng một ngăn xếp Docker Compose (hướng dẫn này), một bộ cài đặt production Kubernetes, hoặc một pod đơn lẻ cùng địa phương. Phần còn lại của hướng dẫn này thiết lập ngăn xếp Compose từ đầu đến cuối.

***

## Bước 1: Xác thực

Tất cả các tạo tác AgentEye được phân phối từ tổ chức GitHub `agenteye-enterprise`. Là một nhà phát triển doanh nghiệp, bạn có thể tạo PAT GitHub của riêng mình. Theo dõi [enterprise-docs/github-token.md](/vi/agenteye/github-token) để thực hiện các bước chính xác và các quyền bắt buộc.

```bash theme={null}
export AGENTEYE_TOKEN=<your-github-pat>

# Authenticate Docker against GHCR
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin
```

***

## Bước 2: Triển khai Máy chủ và Bảng điều khiển

Máy chủ nhận các sự kiện từ các trình thu thập và làm cho chúng có thể truy vấn được; bảng điều khiển là nơi bạn khám phá chúng. Các sự kiện và phân tích được nạp sống trong ClickHouse (kho lưu trữ phân tích bắt buộc), trong khi Postgres giữ trạng thái hoạt động như các tổ chức, người dùng, khóa API, bảng điều khiển và các truy vấn đã lưu.

**Tải xuống tệp compose đã xuất bản:**

```bash theme={null}
mkdir -p ./agenteye
curl -fsSL \
  -H "Authorization: token $AGENTEYE_TOKEN" \
  https://raw.githubusercontent.com/agenteye-enterprise/releases/main/docker-compose.yml \
  -o ./agenteye/docker-compose.yml
cd agenteye
```

**Đặt các bí mật của bạn:**

Tạo một tệp `.env` để việc triển khai không chạy trên thông tin đăng nhập `admin` mặc định. Ở mức tối thiểu, hãy đặt `ADMIN_KEY` và `POSTGRES_PASSWORD`:

```bash theme={null}
POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret
```

**Khởi động ngăn xếp:**

```bash theme={null}
docker compose up -d
```

Điều này đưa toàn bộ ngăn xếp lên, bao gồm kho lưu trữ phân tích ClickHouse bắt buộc và bộ đệm Redis tùy chọn, cùng với máy chủ và bảng điều khiển. ClickHouse phải khỏe mạnh để máy chủ khởi động.

Máy chủ hiện đang lắng nghe ở `http://localhost:8080` và bảng điều khiển ở `http://localhost:3000`.

Để triển khai production (Postgres tùy chỉnh, TLS, proxy ngược), xem [enterprise-docs/deployment.md](/vi/agenteye/deployment).

***

## Bước 3: Tạo một Khóa API cho Trình thu thập

Mỗi trình thu thập xác thực với một khóa API được xác định phạm vi. Sử dụng `ADMIN_KEY` bạn đặt trong Bước 2 để tạo một khóa:

```bash theme={null}
curl -s -X POST http://localhost:8080/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}'
```

Bạn cung cấp giá trị `key` cho chính mình; sử dụng nó trong cấu hình trình thu thập ở Bước 4. Xem [enterprise-docs/api-keys.md](/vi/agenteye/api-keys) để quản lý khóa đầy đủ.

***

## Bước 4: Cài đặt Trình thu thập

Trên mỗi máy chạy AI agent của bạn, hãy cài đặt daemon trình thu thập.

**Tải xuống nhị phân (Linux x86\_64):**

```bash theme={null}
VERSION=0.0.1-beta.13
GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "collector/v${VERSION}" \
  --repo agenteye-enterprise/releases \
  --pattern 'agenteye-collector-linux-x86_64'
chmod +x agenteye-collector-linux-x86_64
sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector
```

> Điều này tải xuống bản dựng **Linux x86\_64**. Để sử dụng macOS (Apple Silicon hoặc Intel), Linux arm64, hoặc thiết lập Docker / systemd / launchd, xem [collector-installation.md](/vi/agenteye/collector-installation), liệt kê bản tải xuống cho mỗi nền tảng — lệnh trên cài đặt một nhị phân Linux sẽ không chạy ở nơi khác.

**Cấu hình:**

```bash theme={null}
mkdir -p ~/.agenteye
cat > ~/.agenteye/config.json <<EOF
{
  "url": "http://your-server-host:8080/events",
  "key": "the-key-from-step-3"
}
EOF
```

**Khởi động daemon:**

```bash theme={null}
agenteye-collector start
```

Xác minh kết nối với một lần xả nước duy nhất (thoát sau khi thoát bất kỳ sự kiện nào đang chờ xử lý):

```bash theme={null}
agenteye-collector flush
```

Để thiết lập Docker, systemd và launchd, xem [enterprise-docs/collector-installation.md](/vi/agenteye/collector-installation).

***

## Bước 5: Cài đặt Python SDK

Trên mỗi máy nơi bạn muốn thêm công cụ theo dõi vào mã agent, hãy cài đặt wheel từ GitHub Releases.

```bash theme={null}
VERSION=0.0.1b9
GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "python-sdk/v${VERSION}" \
  --repo agenteye-enterprise/releases \
  --pattern 'agenteye-*.whl'
pip install agenteye-${VERSION}-py3-none-any.whl
```

***

## Bước 6: Thêm công cụ theo dõi vào Agent của bạn

Thêm các sự kiện vào mã agent của bạn. Ở mức tối thiểu, phát ra `agent_start` và `agent_end`:

```python theme={null}
import agenteye

agenteye.event.agent_start(
    session_id="run-001",
    agent_id="my-agent",
    goal="answer the user query",
)

# your agent logic here

agenteye.event.agent_end(
    session_id="run-001",
    agent_id="my-agent",
    outcome="success",
)
```

Các sự kiện được đệm và được xả vào `$AGENTEYE_HOME/events/` (hoặc `~/.agenteye/events/` nếu `AGENTEYE_HOME` không được đặt) mỗi 500 ms. Trình thu thập tự động nhận chúng.

Xem [enterprise-docs/python-sdk.md](/vi/agenteye/python-sdk) để xem API sự kiện đầy đủ.

***

## Bước 7: Xem các sự kiện trong Bảng điều khiển

Mở `http://your-dashboard-host:3000` và đăng nhập. AgentEye gửi cho bạn một mã dùng một lần qua email (hoặc một liên kết magic một cú nhấp), vì vậy không có mật khẩu để quản lý.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/login.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=8f83cb747193d872f7883cb709587635" alt="Màn hình đăng nhập AgentEye, gửi mã dùng một lần đến email của bạn" width="2880" height="1800" data-path="agenteye/images/login.png" />

Khi bạn vào, trang **Events** hiển thị một đường dẫu trực tiếp của tất cả các sự kiện được nạp. Lọc theo `session_id` hoặc `agent_id` để tìm hiểu chi tiết một lần chạy cụ thể.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/events-stream.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=79714903a85d10773f4f9b36cb44b1cf" alt="Luồng Events trực tiếp, được mã hóa màu theo loại sự kiện và có thể lọc theo môi trường, agent và phiên" width="2880" height="1800" data-path="agenteye/images/events-stream.png" />

Trang **Sessions** tập hợp những sự kiện đó thành một hàng cho mỗi lần chạy. AgentEye tự động đánh giá các phiên đã hoàn thành, vì vậy mỗi lần chạy được chấm điểm và những suy giảm chất lượng được hiển thị mà không cần kiểm tra thủ công; điểm đánh giá mới nhất xuất hiện trên mỗi hàng một cách sắc nét:

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/sessions-list.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=10de161665eef64465d3d100e80b643f" alt="Danh sách Sessions, một hàng cho mỗi lần chạy, với huy hiệu trạng thái và huy hiệu điểm đánh giá" width="2880" height="1800" data-path="agenteye/images/sessions-list.png" />

Để định cấu hình cách các phiên được chấm điểm, xem [enterprise-docs/evaluation-suite.md](/vi/agenteye/evaluation-suite).

Nhấp vào bất kỳ phiên nào để mở **biểu đồ thực thi** của nó, một dạng xem kiểu git về cách agent, công cụ, hook và lệnh gọi mô hình diễn ra theo thời gian, với các sub-agent song song trên các làn của riêng chúng và một bảng phân tích từng lần chạy trong đường ray bên phải:

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/session-detail.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=63cc2480e8124a05ea6a0a92d5f20690" alt="Biểu đồ thực thi kiểu git của phiên bên cạnh dòng thời gian sự kiện của nó, với bảng phân tích công cụ/mô hình/hook" width="2880" height="1800" data-path="agenteye/images/session-detail.png" />

***

## Bước 8: Khám phá, biểu đồ và cảnh báo

Với các sự kiện chảy, các trang **phân tích** biến hoạt động thô thành các câu trả lời, vì vậy bạn có thể đo lường hành vi agent, chia sẻ các phát hiện với nhóm và được gọi vào trang thái nếu có gì đó suy giảm. Các trang bảng điều khiển được phạm vi tổ chức, vì vậy các URL bạn thấy trong thanh địa chỉ có tiền tố với slug org của bạn (`/<org>/…`).

* **Queries** (`/<org>/queries`): bắt đầu từ một thư viện các truy vấn đã lưu, có thể tái sử dụng trên các sự kiện và đánh giá của bạn (các cài đặt trước tích hợp cộng với các truy vấn tùy chỉnh của bạn)…

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/queries.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=1b42be492d5b650b4bd6b8a2241f6633" alt="Thư viện các truy vấn đã lưu: lưới các truy vấn có thể tái sử dụng, cả cài đặt trước tích hợp và các truy vấn tùy chỉnh" width="2880" height="1800" data-path="agenteye/images/queries.png" />

…rồi mở một trong số chúng trong soạn thảo viên SQL để điều chỉnh nó và chạy nó với kết quả trực tiếp:

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/query-lab.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=aec1a1d95bb0bf1280d62a2e2430f20e" alt="Soạn thảo viên truy vấn SQL chạy một truy vấn đã lưu, với thanh bên lược đồ và lưới kết quả trực tiếp" width="2880" height="1800" data-path="agenteye/images/query-lab.png" />

* **Dashboards** (`/<org>/dashboards`): ghim các truy vấn như ô đường kẻ, thanh, diện tích hoặc hình tròn vào các bảng điều khiển được chia sẻ, toàn org.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/dashboard-fleet.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=d1fed0deace0ebb0bc02421f3b994107" alt="Bảng điều khiển được tạo từ các truy vấn đã lưu: một dòng sự kiện trên giờ, thanh lỗi theo loại, biểu đồ diện tích độ trễ và mã thông báo theo mô hình" width="2880" height="1800" data-path="agenteye/images/dashboard-fleet.png" />

* **Alerts** (`/<org>/alerts`): nâng cao bất kỳ ngưỡng nào thành một quy tắc ghi trang thái được thông báo qua email, Slack, webhook hoặc trong bảng điều khiển. Xem [enterprise-docs/alerts.md](/vi/agenteye/alerts).

***

## Các bước tiếp theo

* [Deployment](/vi/agenteye/deployment): cứng hóa cho production
* [API Keys](/vi/agenteye/api-keys): quản lý quyền truy cập
* [Troubleshooting](/vi/agenteye/troubleshooting): chẩn đoán các vấn đề