failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/vi/agenteye/api-keys.mdx

@@ -0,0 +1,280 @@
+---
+title: "API Keys"
+description: "API keys kiểm soát ai và những gì có thể tiếp cận máy chủ Failproof AI Observability của bạn, vì vậy một collector có thể gửi sự kiện mà không bao giờ có được quyền đọc hoặc quyền admin."
+---
+
+
+API keys kiểm soát ai và những gì có thể tiếp cận máy chủ Failproof AI Observability của bạn, vì vậy một collector có thể gửi sự kiện mà không bao giờ có được quyền đọc hoặc quyền admin. Mỗi key mang một hoặc nhiều quyền, và mỗi quyền kiểm soát các route máy chủ cụ thể; bạn chỉ cấp những quyền mà công việc cần. Hầu hết các triển khai chỉ tạo ba loại key.
+
+## 3 key mà hầu hết các triển khai cần
+
+| Key | Quyền | Ai sử dụng |
+|---|---|---|
+| Collector key | `events:add` | `agenteye-collector` trên mỗi máy agent, để gửi sự kiện. |
+| Dashboard read key | `events:read`, `keys:read` | Một nhà điều hành chỉ đọc hoặc tích hợp truy vấn dữ liệu mà không thay đổi nó. |
+| Bootstrap admin key | tất cả quyền | Nhà điều hành đưa instance lên lần đầu tiên (và dashboard). Được khởi tạo từ biến môi trường `ADMIN_KEY`. Xem [Bootstrap admin key](#bootstrap-admin-key). |
+
+Bắt đầu từ đây. Chỉ sử dụng danh mục quyền đầy đủ dưới đây khi bạn cần một key tùy chỉnh hạn chế hơn. Xem thêm [Recommended key layout](#recommended-key-layout) và [Creating keys](#creating-keys).
+
+---
+
+## Quyền
+
+Máy chủ thực thi một danh mục quyền cố định; mỗi cái kiểm soát các route HTTP cụ thể. Một **admin key** nắm giữ tất cả chúng; một key có phạm vi nắm giữ tập hợp con bạn cấp khi tạo. Các chuỗi quyền không xác định bị từ chối khi tạo key.
+
+> **Lưu ý:** Hai quyền hợp lệ chỉ dành cho dashboard con người và không thể được cấp cho API key: `orgs:admin` (quản trị instance, chỉ dành cho nhà điều hành) và `keys:update`. Một yêu cầu `POST /keys` hoặc `PATCH /keys/:id` cố gắng cấp một trong hai quyền bị từ chối với HTTP 422. Xem hàng `keys:update` dưới đây để biết lý do tại sao một bearer key có thể tạo key nhưng không bao giờ chỉnh sửa chúng.
+
+### Events ingest & query
+
+| Quyền | HTTP routes | Những gì nó cho phép |
+|---|---|---|
+| `events:add` | `POST /events` | Nhập các lô sự kiện từ một collector. Quyền duy nhất mà một collector cần. |
+| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Truy vấn sự kiện, liệt kê các môi trường đã biết, liệt kê các định danh mô hình được nhìn thấy trong dữ liệu (được sử dụng bởi chế độ xem Models và bộ lọc mô hình), tính toán tổng hợp độ trễ cung cấp năng lượng cho heat-map / dải phần trăm, và xuất phiên dưới dạng JSONL. Các endpoint facet bộ lọc chung `GET /events/environments` và `GET /events/agent_ids` có thể truy cập được với **bất kỳ** `events:read` **hoặc** `evaluations:read`, vì vậy trang sessions (gated `evaluations:read`) sử dụng lại cùng một facet mỗi tổ chức. `GET /events/models` không phải là một trong số đó: nó yêu cầu `events:read`, vì vậy một principal chỉ nắm giữ `evaluations:read` nhận được 403 từ nó. |
+
+### Sessions & evaluations
+
+| Quyền | HTTP routes | Những gì nó cho phép |
+|---|---|---|
+| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Liệt kê phiên, đọc kết quả đánh giá, tình trạng eval được tóm gọn lại được sử dụng bởi dashboard, và trạng thái hàng đợi worker công việc đánh giá. |
+| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Thủ công đưa một phiên hoàn tất vào hàng đợi đánh giá lại. |
+
+### Dashboards
+
+| Quyền | HTTP routes | Những gì nó cho phép |
+|---|---|---|
+| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Liệt kê dashboard, tải một cái, và đọc các tile của nó. |
+| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | Tạo và chỉnh sửa dashboard, thêm / chỉnh sửa / xóa tile, và sắp xếp lại lưới tile. |
+| `dashboards:delete` | `DELETE /dashboards/:id` | Xóa toàn bộ một dashboard (xóa cấp độ tile nằm trong `dashboards:write`). |
+
+### Saved queries (SQL composer)
+
+| Quyền | HTTP routes | Những gì nó cho phép |
+|---|---|---|
+| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Liệt kê các truy vấn đã lưu, tải một cái, và kiểm tra schema chỉ đọc mà composer nhắm đến. |
+| `queries:write` | `POST /queries`, `PUT /queries/:id` | Tạo và chỉnh sửa các truy vấn đã lưu. SQL vẫn được định tuyến qua cùng một role chỉ đọc và các kiểm tra SQL được bảo vệ như một lệnh gọi `queries:run`. |
+| `queries:delete` | `DELETE /queries/:id` | Xóa một truy vấn đã lưu. |
+| `queries:run` | `POST /queries/run` | Thực thi SQL đã lưu hoặc ad-hoc cho role chỉ đọc được sử dụng bởi composer. |
+
+### AI assistant
+
+| Quyền | HTTP routes | Những gì nó cho phép |
+|---|---|---|
+| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | Nói chuyện với trợ lý AI và quản lý các cuộc trò chuyện của riêng bạn (private). Cần thiết trên **người dùng** để xem dock trợ lý; key của trợ lý tự nó là `dashboard-assistant` và được khởi tạo riêng (xem dưới đây). |
+
+### API keys
+
+| Quyền | HTTP routes | Những gì nó cho phép |
+|---|---|---|
+| `keys:create` | `POST /keys` | Tạo một API key có phạm vi mới. **Không** cấp việc chỉnh sửa quyền của key hiện tại (đó là `keys:update`). |
+| `keys:read` | `GET /keys` | Liệt kê các key hiện tại. Secrets không bao giờ được trả lại bởi endpoint này. |
+| `keys:update` | `PATCH /keys/:id` | Chỉnh sửa quyền của key hiện tại. Một quyền **chỉ dành cho dashboard con người**; nó không thể được gán cho API key (một bearer key có thể tạo key nhưng không bao giờ chỉnh sửa chúng). |
+| `keys:disable` | `POST /keys/:id/disable` | Thu hồi một key. Các key được bảo vệ (`admin`, `dashboard-assistant`) không thể bị vô hiệu hóa; xoay chúng qua biến env + khởi động lại. |
+| `keys:regenerate` | `POST /keys/:id/regenerate` | Xoay secret của key. Các key được bảo vệ không thể được tái tạo thông qua route này. |
+
+### Dashboard users
+
+| Quyền | HTTP routes | Những gì nó cho phép |
+|---|---|---|
+| `users:create` | `POST /users`, `GET /users/defaults` | Mời một người dùng dashboard mới (phát hành email + one-time passcode (OTP) login) và đọc tập hợp quyền mặc định được cấu hình dashboard được sử dụng để khởi tạo biểu mẫu mời. |
+| `users:read` | `GET /users`, `GET /users/:id` | Liệt kê người dùng và tải một bản ghi người dùng duy nhất. |
+| `users:update` | `PUT /users/:id` | Chỉnh sửa quyền của người dùng. Cập nhật gửi email thay đổi quyền đến người dùng bị ảnh hưởng và có hiệu lực khi yêu cầu tiếp theo của họ; không cần đăng nhập lại. |
+| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Vô hiệu hóa một người dùng (thu hồi các phiên của họ ngay lập tức) và kích hoạt lại một người dùng đã bị vô hiệu hóa trước đó. |
+
+Các quyền này hỗ trợ trang **Users** của dashboard, nơi mà các phạm vi được cấp của mỗi thành viên được hiển thị dưới dạng chip:
+
+![Trang Users: một thẻ cho mỗi người dùng dashboard với email, quyền được cấp, và điều khiển chỉnh sửa/vô hiệu hóa của họ](/agenteye/images/users.png)
+
+### Operational settings
+
+| Quyền | HTTP routes | Những gì nó cho phép |
+|---|---|---|
+| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Xem các cài đặt hoạt động được quản lý bằng dashboard và siêu dữ liệu của chúng; liệt kê các ghi đè cửa sổ ngữ cảnh mỗi mô hình; và giải quyết cửa sổ hiệu quả cho một mô hình. |
+| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Chỉnh sửa các cài đặt hoạt động và thêm, thay đổi, hoặc xóa các ghi đè cửa sổ ngữ cảnh mỗi mô hình. Các thay đổi ảnh hưởng đến các sự kiện mới mà không cần khởi động lại máy chủ. |
+
+![Trang Settings: các cài đặt hoạt động được quản lý bằng dashboard như đăng nhập được phép và tuổi thọ session/OTP, có thể chỉnh sửa mà không cần khởi động lại](/agenteye/images/settings.png)
+
+### Alerts & incidents
+
+| Quyền | HTTP routes | Những gì nó cho phép |
+|---|---|---|
+| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Xem các định nghĩa cảnh báo được cấu hình. |
+| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Tạo, chỉnh sửa, xóa, và test-fire các định nghĩa cảnh báo. |
+| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Xem các incident và dấu vết triage của chúng. |
+| `incidents:write` | `POST /alerts/:id/incidents` | Mở một incident theo cách thủ công đối với một cảnh báo hiện tại. |
+| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | Xác nhận, gán, giải quyết, và bình luận trên incident. |
+
+### Audits
+
+| Quyền | HTTP routes | Những gì nó cho phép |
+|---|---|---|
+| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Xem các định nghĩa audit, lịch sử chạy, và những phát hiện. |
+| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Tạo, chỉnh sửa, xóa, và chạy audit; triage finding (xác nhận / im lặng / bỏ qua / giải quyết / mở lại / gán). |
+
+> **Lưu ý:** Để cấp cho key bề mặt audit, cấp `audits:*` cho nó một cách rõ ràng. Xem [Upgrade and backward-compatibility notes](#upgrade-and-backward-compatibility-notes) để biết các grantee hiện tại được di chuyển khi Audits vận hành.
+
+> Endpoint bộ chọn người nhận `GET /alerts/recipients` (liệt kê các email thành viên mà trình chỉnh sửa cảnh báo có thể thông báo) có thể truy cập được bởi một người nắm giữ **bất kỳ** `alerts:read` **hoặc** `alerts:write`, vì vậy các trình chỉnh sửa cảnh báo có thể điền bộ chọn mà không được cấp `users:read`.
+
+> Một người xem dashboard cần **cả hai** `dashboards:read` (để tải các chế độ xem đã lưu) và `evaluations:read` (các chỉ số sức khỏe được tính từ dữ liệu đánh giá). Cấp `dashboards:write` để cho phép người dùng tạo hoặc chỉnh sửa dashboard, và `dashboards:delete` để xóa chúng.
+
+> `/health` và `/auth/*` (yêu cầu OTP, xác minh OTP, kiểm tra phiên, đăng xuất) không được xác thực theo thiết kế; chúng là dòng đăng nhập và liveness probe. `GET /access-granters` yêu cầu một key hợp lệ nhưng không có quyền cụ thể nào, vì vậy bất kỳ người dùng đã đăng nhập nào cũng có thể xem những admin nào để liên hệ về các thay đổi truy cập.
+
+---
+
+## Permission Sets
+
+Permission sets cho phép bạn áp dụng một vai trò được đặt tên thay vì chọn tay từng token mỗi lần. Thay vì chọn tá quyền một cách từng cái một cho mỗi người dùng dashboard hoặc API key mới, bạn chọn một tập hợp, và mọi người được gán cho nó mang một cấp phát nhất quán, có thể xem xét. Chỉnh sửa một tập hợp tùy chỉnh tái áp dụng cấp phát mới cho mọi người dùng đã được gán cho nó, vì vậy một thay đổi vai trò là một chỉnh sửa chứ không phải một quét qua mỗi thành viên.
+
+Mỗi tổ chức được khởi tạo với ba tập hợp tích hợp:
+
+| Tập hợp | Quyền | Dành cho |
+|---|---|---|
+| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Truy cập chỉ xem trên mọi bề mặt hoạt động. |
+| `standard` | mọi thứ trong `read-only`, cộng với `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Chỉ đọc cộng với các hành động trên gọi hàng ngày: chạy truy vấn, đánh giá lại phiên, xác nhận incident, và sử dụng trợ lý AI. |
+| `admin` | mọi quyền có thể gán | Kiểm soát toàn bộ tổ chức. |
+
+Ba tập hợp tích hợp là **bất biến**; các tên của chúng luôn có nghĩa giống nhau, vì vậy `read-only`, `standard`, và `admin` an toàn để tham chiếu trong chính sách và onboarding. Một nhà điều hành có thể tạo các **tập hợp tùy chỉnh** bổ sung để mô hình hóa các vai trò cụ thể cho tổ chức của bạn (ví dụ: vai trò "dashboard author" hoặc vai trò "collector-only").
+
+Các tập hợp được hiển thị trong dashboard và được quản lý trên API tại `GET /permission-sets` (danh sách, gated bởi `users:read`) và `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (tạo, chỉnh sửa, xóa tập hợp tùy chỉnh, gated bởi `settings:write`). Xóa hoặc chỉnh sửa một tập hợp tích hợp bị từ chối.
+
+Thành viên tập hợp là những gì hỗ trợ hai tính năng khác:
+
+- **`DEFAULT_USER_PERMISSIONS`** (cấp được chọn trước khi admin mở **+ new user**) mặc định cho tập hợp `standard`.
+- **Flag `--set`** trên `agenteye-orgctl` (quản lý thành viên nhà điều hành) bắt đầu một thành viên từ một tập hợp được đặt tên, mà sau đó bạn tinh chỉnh với `--add` / `--remove`.
+
+> **Lưu ý:** Khi một tập hợp bao gồm một quyền không thể gán key (ví dụ: một tập hợp tùy chỉnh mang `keys:update`), khởi tạo một key từ tập hợp đó sẽ loại bỏ các token không thể gán; máy chủ sẽ từ chối key khác với HTTP 422. Những người dùng dashboard không phải chịu hạn chế đó.
+
+---
+
+## Bootstrap Admin Key
+
+Admin key là thông tin xác thực gốc duy nhất cho phép nhà điều hành đưa quyền lên từ không có gì: với nó, bạn có thể tạo ra mỗi key được phạm vi khác, mời những người dùng dashboard đầu tiên, và cấu hình instance trước khi bất kỳ key nào khác tồn tại. Nó là key duy nhất mà bạn không tạo thông qua keys API; nó được cung cấp từ môi trường vì vậy máy chủ có thể đạt được khi khởi động lần đầu.
+
+Đặt biến môi trường `ADMIN_KEY` trên máy chủ. Khi mỗi lần khởi động, máy chủ upsert giá trị này như một admin key với tất cả quyền.
+
+Để xoay: thay đổi `ADMIN_KEY` thành một secret mới và khởi động lại máy chủ.
+
+---
+
+## Organization scoping
+
+**Các tổ chức chính nó được tạo và quản lý ngoài hệ thống bởi một nhà điều hành, không thông qua keys API này.** Vòng đời tổ chức và thành viên (tạo / đổi tên / xóa / xóa sạch một tổ chức; thêm / cập nhật / xóa một thành viên) được thực hiện với **CLI `agenteye-orgctl`**; không có HTTP API hoặc nút dashboard cho nó. Những gì *không thay đổi*: **các API key mỗi tổ chức vẫn được tạo trong dashboard (hoặc qua keys API này)** bởi các thành viên tổ chức.
+
+Trong một triển khai đa tổ chức, mỗi key mà một thành viên tổ chức tạo (thông qua keys API này hoặc trang **Keys** của dashboard) thuộc về **một tổ chức** và chỉ có thể đọc hoặc ghi dữ liệu của tổ chức đó; tổ chức được đóng dấu trên key khi tạo và được thực thi khi mỗi yêu cầu. Hai bootstrap key là ngoại lệ duy nhất: key `admin` (khởi tạo từ `ADMIN_KEY`) và key `dashboard-assistant` (khởi tạo từ `AGENT_API_KEY`) là **instance-scoped** (chúng không mang tổ chức). Dashboard xác thực bằng key `admin` để nó có thể ủy đại các yêu cầu mỗi tổ chức thay mặt cho các thành viên đã đăng nhập. Các triển khai single-tenant không cần nghĩ về điều này; tất cả các key thuộc về tổ chức `default` tích hợp.
+
+---
+
+## Creating Keys
+
+Sử dụng admin key (hoặc bất kỳ key nào có quyền `keys:create`) để tạo các key có phạm vi bổ sung.
+
+### Collector key (ingest only)
+
+```bash
+curl -s -X POST http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "prod-collector",
+    "key": "your-collector-secret",
+    "permissions": ["events:add"]
+  }'
+```
+
+### Dashboard key (read only)
+
+```bash
+curl -s -X POST http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "dashboard",
+    "key": "your-dashboard-secret",
+    "permissions": ["events:read", "keys:read"]
+  }'
+```
+
+Khi bạn tạo một key trên HTTP API, bạn cung cấp giá trị `key` của riêng mình; chọn một secret mạnh và lưu trữ nó một cách an toàn. (Dashboard hoạt động theo cách khác: nó tạo ra một secret mạnh cho bạn và hiển thị nó một lần khi tạo; xem [Key Management in the Dashboard](#key-management-in-the-dashboard).) Phản hồi xác nhận key được tạo:
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "prod-collector",
+  "permissions": ["events:add"],
+  "created_at": "2026-04-01T12:00:00Z"
+}
+```
+
+---
+
+## Listing Keys
+
+```bash
+curl -s http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+Các secret key không được trả lại trong các phản hồi danh sách, chỉ ID, tên, và quyền.
+
+---
+
+## Disabling a Key
+
+Vô hiệu hóa thu hồi quyền truy cập ngay lập tức mà không xóa bản ghi key.
+
+```bash
+curl -s -X POST http://your-server/keys/<id>/disable \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+---
+
+## Regenerating a Key
+
+Tạo ra một secret mới cho một key hiện tại. Secret cũ được vô hiệu hóa ngay lập tức.
+
+```bash
+curl -s -X POST http://your-server/keys/<id>/regenerate \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+Phản hồi bao gồm secret plaintext mới, **hiển thị chỉ một lần**.
+
+---
+
+## Key Management in the Dashboard
+
+Trang **Keys** trong dashboard cung cấp một UI cho tất cả các hoạt động trên. Bạn cần một key có quyền `keys:read` để xem danh sách, và `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` cho các hành động tạo / chỉnh sửa / vô hiệu hóa / tái tạo tương ứng. Chỉnh sửa quyền của key (`keys:update`) là riêng biệt với việc tạo một cái (`keys:create`), vì vậy bạn có thể cấp cho nhà điều hành khả năng tạo key mà không có khả năng phạm vi lại key hiện tại, hoặc ngược lại. Admin key bao gồm tất cả những cái này.
+
+Khi bạn tạo một key từ dashboard, bạn không cung cấp secret; dashboard tạo ra một secret mạnh cho bạn và hiển thị nó **một lần** khi tạo. Sao chép nó ngay lập tức và lưu trữ nó một cách an toàn; nó không bao giờ được hiển thị lại, giống như một lần tái tạo. Bạn vẫn có thể chọn quyền của key một cách trực tiếp, hoặc khởi tạo chúng từ một permission set (xem dưới đây).
+
+![Trang API Keys: một thẻ cho mỗi key hiển thị tên, quyền được cấp, và thời gian tạo, với các hành động tái tạo và vô hiệu hóa; các key được bảo vệ như `admin` được đánh dấu](/agenteye/images/api-keys.png)
+
+---
+
+## Recommended Key Layout
+
+| Key | Quyền | Được sử dụng bởi |
+|---|---|---|
+| `admin` (bootstrap qua biến env `ADMIN_KEY`) | tất cả | Ops/setup, và dashboard (xác thực bằng `ADMIN_KEY`, ủy đại yêu cầu người dùng với các kiểm tra quyền) |
+| Per-host collector key | `events:add` | Collector trên mỗi máy agent |
+| `dashboard-assistant` (bootstrap qua biến env `AGENT_API_KEY`) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | Trợ lý AI, khởi tạo tự động, **protected**; không thể chỉnh sửa qua API |
+| Assistant telemetry key (optional) | `events:add` | AI assistant self-instrumentation, nếu được bật |
+
+> **Lưu ý:** Key của trợ lý **được khởi tạo tự động** bởi máy chủ từ biến env `AGENT_API_KEY` (secret giống nhau mà agent trình bày dưới dạng `AGENTEYE_API_KEY`); không có bước tạo key thủ công và không có admin key liên quan. Các quyền của nó được khắc phục trong source code vì vậy phạm vi không thể được mở rộng bởi cấu hình sai: đọc trên sự kiện / đánh giá / dashboard, cộng với dashboards-write và queries-read / write / run cho dòng tác giả "Ask AI to write a query". Tất cả SQL vẫn đi qua cùng một role chỉ đọc và đường dẫn SQL được bảo vệ như một truy vấn do người dùng viết, vì vậy điều này mở rộng *bề mặt tác giả*, không phải bề mặt dữ liệu; các hoạt động phá hủy (`queries:delete`, `dashboards:delete`) cố ý ở ngoài assistant key. Giống như key `admin`, nó **được bảo vệ**: nó không thể bị vô hiệu hóa hoặc tái tạo thông qua keys API, chỉ xoay bằng cách thay đổi `AGENT_API_KEY` và khởi động lại. Người dùng *dashboard* cần quyền `agent:use` để xem và sử dụng trợ lý. Nếu bạn bật self-instrumentation, hãy cung cấp cho trợ lý một key riêng chỉ `events:add`.
+
+---
+
+## Upgrade and backward-compatibility notes
+
+Bạn chỉ cần những cái này nếu bạn đang nâng cấp một instance hiện tại; các triển khai mới có thể bỏ qua chúng.
+
+> Khi Audits được vận hành, các grantee hiện tại được mở rộng cùng các hình dạng vai trò với alert: mỗi người dùng và permission set nắm giữ `alerts:read` đã đạt được `audits:read`, và mỗi người nắm giữ `alerts:write` đã đạt được `audits:write`. Các API key hiện tại **không** được mở rộng. Cấp `audits:*` cho một key một cách rõ ràng nếu nó cần bề mặt audit.
+
+> Cấp của legacy token `alerts:ack` được lưu trữ được phân tích cú pháp thành `incidents:ack` vì vậy on-caller vẫn giữ quyền truy cập mà không cần đổi key. Token không còn có thể gán từ trình chỉnh sửa người dùng của dashboard; ma trận cung cấp `incidents:ack` thay thế.
+
+---
+
+## Các bước tiếp theo
+
+- [Python SDK](/vi/agenteye/python-sdk): cách mã agent của bạn xác thực khi gửi sự kiện.
+- [Security](/vi/agenteye/security): cách đăng nhập, kiểm soát truy cập, và cách cô lập dữ liệu mỗi tổ chức hoạt động.

package/.next/standalone/docs-old/vi/agenteye/assistant.mdx

@@ -0,0 +1,63 @@
+---
+title: "Trợ lý AI"
+description: "Đặt câu hỏi cho dữ liệu agent của bạn bằng tiếng Anh thuần túy và nhận được câu trả lời có liên kết trực tiếp đến bằng chứng."
+---
+
+
+Đặt câu hỏi cho dữ liệu agent của bạn bằng tiếng Anh thuần túy và nhận được câu trả lời có liên kết trực tiếp đến bằng chứng. Không cần viết SQL, không cần tìm kiếm trong các bảng điều khiển — trợ lý **Failproof AI Observability** là cách nhanh nhất để bất kỳ ai trong nhóm của bạn có thể nhận được câu trả lời về các agent của bạn.
+
+![Trợ lý Failproof AI Observability trả lời một câu hỏi bằng tiếng Anh thuần túy bên trong bảng điều khiển, hiển thị bảng Hoạt động Agent trực tiếp, phân tích sử dụng mô hình theo từng agent và các điểm chính, cùng với các truy vấn mà nó chạy được hiển thị inline](/agenteye/images/assistant.png)
+*Đặt câu hỏi bằng tiếng Anh thuần túy và nhận được câu trả lời được xây dựng từ dữ liệu của riêng bạn. Ở đây nó phân tích những agent nào bận rộn nhất và những mô hình nào họ sử dụng, đồng thời hiển thị các truy vấn mà nó chạy để bạn có thể xác minh từng con số.*
+
+Không có gì phải học. Mở cuộc trò chuyện, gõ những gì bạn muốn biết, và theo dõi các liên kết mà nó cung cấp:
+
+```
+You:  which sessions errored today?
+AI:   5 sessions errored today, newest first. Each one is linked:
+      • checkout-agent   14:02   tool timeout
+      • billing-agent    11:47   unhandled error
+      • ...and 3 more
+
+You:  summarize this session          (asked while viewing a run)
+AI:   This run took 12 steps across 3 tools and failed near the end when a
+      payment tool returned an error. It scored low on your "resolved" eval.
+      Links: the session, the failing event, and that evaluation.
+```
+
+## Chỉ cần hỏi và nhảy thẳng đến bằng chứng
+
+Bạn không còn phải đoán và không cần phải viết truy vấn. Hỏi "chất lượng đang xu hướng như thế nào trong prod tuần này?", "phiên nào bị lỗi hôm nay?", hoặc "tóm tắt phiên này", và bạn sẽ nhận được câu trả lời rõ ràng trong vài giây thay vì phải xây dựng truy vấn và tự đọc kết quả.
+
+Mọi câu trả lời đều kèm theo bằng chứng của nó. Trợ lý liên kết đến các phiên chính xác, các truy vấn đã lưu và bảng điều khiển mà nó sử dụng để đưa ra câu trả lời, vì vậy bạn có thể nhấp để xác nhận thay vì chỉ tin tưởng theo lời nó. Nó cũng **nhận biết trang**: hỏi về "phiên này" khi bạn đang xem một phiên và nó đã biết bạn muốn nói về phiên chạy nào. Mở lại bất kỳ cuộc trò chuyện trước đó nào từ công tắc lịch sử và tiếp tục từ nơi bạn để dở.
+
+## Biến một câu trả lời tốt thành truy vấn đã lưu hoặc bảng điều khiển
+
+Khi một câu trả lời xứng đáng được giữ, yêu cầu trợ lý lưu nó. Nó soạn SQL cho một truy vấn đã lưu hoặc lắp ráp một bảng điều khiển từ các truy vấn đó, sau đó hiển thị cho bạn thẻ **Phê duyệt / Từ chối**. Không gì được ghi lại cho đến khi bạn nhấp Phê duyệt, vì vậy bạn có thể trải nghiệm tốc độ của "chỉ cần hỏi" với quyền quyết định cuối cùng luôn thuộc về bạn.
+
+Trên trang **Truy vấn** nó đi xa hơn một bước và trở thành tác giả SQL: mô tả truy vấn bạn muốn ("hiển thị tỷ lệ lỗi theo agent cho 7 ngày qua") và nó sẽ phát trực tiếp SQL vào trình chỉnh sửa, mở chế độ diff để bạn có thể **Chấp nhận** hoặc **Từ chối** thay đổi trước khi nó được áp dụng.
+
+![Trang Truy vấn Observability và trình chỉnh sửa SQL của nó](/agenteye/images/query-lab.png)
+*Trang Truy vấn: trình chỉnh sửa này là nơi trợ lý phát một bản nháp truy vấn chỉ đọc cho bạn chấp nhận hoặc từ chối.*
+
+Soạn SQL bằng cách hỏi ở đây sử dụng quyền `queries:run`, quyền giống như quyền đằng sau nút **Chạy** của trình chỉnh sửa. Chat ở mọi nơi khác cần `agent:use`.
+
+## An toàn để giao cho toàn bộ nhóm
+
+Bạn có thể mở trợ lý cho tất cả mọi người mà không lo lắng về những gì nó có thể chạm vào:
+
+- **Nó chỉ đọc những gì bạn đã có thể thấy.** Câu trả lời được giới hạn trong quyền đọc của riêng bạn, vì vậy nó không bao giờ mở rộng diện tích dữ liệu của bạn.
+- **Mọi lần ghi đều chờ bạn.** Các truy vấn và bảng điều khiển đã lưu chỉ được tạo sau khi bạn nhấp Phê duyệt một cách rõ ràng, và không có cài đặt nào tắt cổng này.
+- **Nó không bao giờ có thể xóa bất cứ điều gì.** Không có công cụ xóa nào được hiển thị và trợ lý không có quyền xóa. Các lần xóa vẫn nằm trong tay bạn, trên bảng điều khiển.
+- **Nó ở bên trong tổ chức của bạn.** Trợ lý chỉ khi nào cũng chỉ nhìn thấy tổ chức bạn đang xem hiện tại.
+- **Các câu hỏi của bạn vẫn là của bạn.** Lời nhắc và câu trả lời sống trong cơ sở dữ liệu Observability riêng của bạn; phân tích sản phẩm chỉ ghi lại siêu dữ liệu sử dụng, không bao giờ văn bản lời nhắc của bạn.
+
+## Nơi tìm nó
+
+Trợ lý nằm dọc theo cạnh bên phải của mọi trang dưới tổ chức của bạn (`/<org-slug>/...`). Nhấp vào ray hoặc nhấn `⌘J` / `Ctrl+J` để mở rộng nó thành bảng trò chuyện đầy đủ, và kéo cạnh của nó để thay đổi kích thước; chiều rộng của bạn được lưu nhớ qua các lần tải lại. Bạn cần quyền **`agent:use`** để sử dụng nó, nếu không ray sẽ bị làm mờ. Nếu nó chưa được bật cho triển khai của bạn (nó cần kết nối LLM), bạn sẽ thấy ray bị làm mờ thay vì trò chuyện hoạt động.
+
+## Liên quan
+
+- [CLI and agents](/vi/agenteye/cli-and-agents)
+- [Queries](/vi/agenteye/queries)
+- [Dashboards](/vi/agenteye/dashboards)
+- [Evaluation suite](/vi/agenteye/evaluation-suite)

package/.next/standalone/docs-old/vi/agenteye/audits.mdx

@@ -0,0 +1,54 @@
+---
+title: "Audits: trợ lý phân tích độ tin cậy tự động của bạn"
+description: "Failproof AI Observability tìm kiếm các lỗi mà bạn chưa bao giờ viết quy tắc cho chúng và cung cấp cho bạn danh sách việc cần làm được xếp hạng, có bằng chứng chính xác về những gì cần sửa."
+---
+
+
+Failproof AI Observability tìm kiếm các lỗi mà bạn chưa bao giờ viết quy tắc cho chúng và cung cấp cho bạn danh sách việc cần làm được xếp hạng, có bằng chứng chính xác về những gì cần sửa. Nó giống như có một nhà phân tích duyệt qua nhật ký của bạn mỗi tối, rồi để lại danh sách ngắn gọn trên bàn của bạn vào sáng hôm sau.
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/C5nHKGQIqZQ?autoplay=1&mute=1&loop=1&playlist=C5nHKGQIqZQ&rel=0&playsinline=1" title="Watch: Automatically find where your agent is failing (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+*Một bài tour hai phút: từ một lần chạy theo lịch đến một bản sửa mà bạn có thể thực hiện.*
+
+![Trang Audits: các công việc định kỳ quét các phiên của bạn tìm kiếm các mẫu lỗi, mỗi công việc có lịch trình và độ nhạy cảm](/agenteye/images/audits.png)
+*Mỗi audit là một công việc định kỳ khai thác các phiên của bạn và viết các khuyến nghị được xếp hạng, có bằng chứng.*
+
+## Ngừng đoán xem cần sửa gì tiếp theo
+
+Cảnh báo bắt các vấn đề mà bạn đã biết cần theo dõi. Audits bắt những vấn đề bạn không biết. Theo lịch trình bạn đặt, một audit đọc qua tất cả các phiên của agent bạn và tìm kiếm các mẫu đáng được sửa, do đó bạn dành thời gian thực hiện các phát hiện thay vì cuộn qua nhật ký hy vọng tự mình phát hiện chúng.
+
+Một lần chạy duy nhất nhắm vào các chế độ lỗi thực sự phá vỡ các agent trong production:
+
+- **Cụm lỗi**: cùng một lỗi lặp lại dưới một nguyên nhân gốc chung.
+- **D漂drift so với đường cơ sở**: hành vi âm thầm trôi ra khỏi một cửa sổ đã biết là tốt.
+- **Lỗi mục tiêu trong bản ghi**: các lần chạy về mặt kỹ thuật đã hoàn thành nhưng không bao giờ thực hiện công việc.
+- **Sử dụng công cụ sai**: công cụ sai, đối số xấu, hoặc các vòng lặp tiêu burn các lệnh gọi.
+- **Tối ưu hóa chất lượng và chi phí**: nơi bạn chi trả quá mức cho đầu ra mà bạn có thể nhận được rẻ hơn.
+- **Khoảng trống phạm vi**: hành vi mà không có eval hoặc cảnh báo nào đang theo dõi.
+
+Bạn quyết định nó tìm kiếm bao nhiêu với một cài đặt **sensitivity** (thấp, trung bình hoặc cao), vì vậy một agent staging ồn ào và một agent production bị khóa chặt có thể được điều chỉnh riêng để có được tín hiệu bạn muốn.
+
+## Mỗi khuyến nghị đều có bằng chứng
+
+Bạn không bao giờ phải tin một phát hiện không cần kiểm chứng. Mỗi khuyến nghị trích dẫn các phiên chính xác mà nó đến từ đó và SQL đã làm nổi bật nó, vì vậy bạn có thể mở bằng chứng và xác nhận vấn đề chỉ trong một cú nhấp chuột thay vì reverse-engineering một yêu cầu.
+
+Khi một phát hiện là về thông tin đăng nhập bị rò rỉ, nó đi thêm một bước nữa và liên kết các sự kiện riêng lẻ mà nó đã khớp. Nhấp vào một sự kiện và bạn sẽ đến đúng thời điểm đó trong phiên, đã được chọn — không phải đầu của một bản ghi dài để cuộn qua. Liên kết đặt tên cho sự kiện; nó không bao giờ sao chép bí mật được phát hiện vào phát hiện, vì vậy đọc một phát hiện không phải là nơi thứ hai thông tin đăng nhập của bạn được viết ra. Nếu một sự kiện không còn ở đó vì phiên đã vượt quá cửa sổ lưu giữ của bạn, trang sẽ nói rõ điều đó thay vì để bạn tự hỏi liệu bạn đã nhấp vào sai thứ gì.
+
+Đó cũng là thứ giữ cho các audit trung thực. Máy chủ kiểm tra rằng mỗi phiên được trích dẫn thực sự tồn tại và **loại bỏ bất kỳ khuyến nghị nào có bằng chứng không chứng thực được**, vì vậy audit điều tra nhưng không bao giờ phát minh ra. Những gì được đưa lên danh sách của bạn là có thật, có thể tái tạo được, và được xếp hạng theo mức độ quan trọng của nó, với những chiến thắng lớn nhất ở phía trên.
+
+## Chuyển một bản sửa thành một biện pháp bảo vệ
+
+Sửa một vấn đề chỉ là nửa chiến thắng. Nửa kia là đảm bảo nó không thể âm thầm quay trở lại. Mỗi phát hiện mang theo **một phím tắt một cú nhấp chuột nháp một cảnh báo tái diễn**, được điền trước một trích kích hoạt hợp lý mà bạn có thể điều chỉnh. Đóng phát hiện, vũ trang cảnh báo, và lần tiếp theo mẫu đó xuất hiện bạn sẽ được trang thái thay vì tái khám phá nó trong một audit tương lai.
+
+## Tìm nó ở đâu
+
+Audits nằm trong bảng điều khiển tại **`/<org-slug>/audits`** (thanh bên đến *analyze* đến *audits*). Xem các lần chạy và phát hiện cần **`audits:read`**; tạo, chỉnh sửa và phân loại các audit cần **`audits:write`**. Đặt phạm vi và tần suất của một audit, rồi nhấp **Run now** bất cứ khi nào bạn muốn kết quả ngay lập tức thay vì chờ lần chạy theo lịch tiếp theo.
+
+## Liên quan
+
+- [Alerts](/vi/agenteye/alerts): nhận thông báo thời điểm ngưỡng bạn đã biết được vượt qua.
+- [Evaluations](/vi/agenteye/evaluations): đánh điểm mỗi lần chạy để các hồi quy chất lượng tự nổi bật.
+- [Error tracking](/vi/agenteye/error-tracking): nhóm và theo dõi các lỗi mà agent của bạn ném ra.
+- [Incidents](/vi/agenteye/incidents): theo dõi một vấn đề mà audit phát hiện cho đến khi sửa nó.

package/.next/standalone/docs-old/vi/agenteye/cli-and-agents.mdx

@@ -0,0 +1,80 @@
+---
+title: "CLI"
+description: "Toàn bộ triển khai Failproof AI Observability của bạn, chỉ cách một lệnh."
+---
+
+
+Toàn bộ triển khai Failproof AI Observability của bạn, chỉ cách một lệnh. Kiểm tra production, tạo khóa API, hoặc xác nhận sự cố mà không cần rời khỏi terminal, sau đó đưa bất kỳ lệnh nào vào CI, hoặc để một coding agent thực hiện cho bạn bằng ngôn ngữ tự nhiên.
+
+```bash
+pipx install agenteye
+agenteye login --email you@example.com      # a 6-digit code lands in your inbox
+agenteye --json sessions --since 24h         # every agent run from the last day, newest first
+```
+
+*CLI `agenteye` giao tiếp với dashboard của bạn. Đây là một công cụ khác biệt với collector, công cụ này gửi sự kiện đến máy chủ.*
+
+## Toàn bộ triển khai của bạn, chỉ cách một lệnh
+
+Dừng việc chuyển tab để trả lời một câu hỏi nhanh. CLI `agenteye` đọc dữ liệu của bạn và quản trị tổ chức của bạn từ một tệp nhị phân duy nhất, vì vậy một kiểm tra mà trước đây có nghĩa là nhấp vào dashboard trở thành một dòng mà bạn có thể chạy lại, tạo bí danh hoặc dán vào runbook. Bạn có bốn giao diện:
+
+- **Đọc dữ liệu của bạn:** `sessions`, `events`, `evals`, và `errors`, được lọc theo thời gian, agent và môi trường.
+- **Quản lý tổ chức của bạn:** `keys`, `users`, `settings`, `alerts`, và `incidents`.
+- **Chạy phân tích:** SQL được lưu cùng với trình chạy `query` ad-hoc trên dữ liệu sự kiện của bạn.
+- **Hỏi trợ lý:** `agent ask` tiếp cận cùng một nhà phân tích chỉ đọc mà bạn trò chuyện với trong dashboard.
+
+Cài đặt một lần bằng `pipx`, đăng nhập bằng mã 6 chữ số được gửi qua email, và bạn đã sẵn sàng. Phiên kéo dài khoảng một ngày; chạy lại `agenteye login` khi nó hết hạn. Dùng nó để kiểm tra production, cấp phát khóa, hoặc phân loại sự cố kích hoạt, tất cả mà không cần mở trình duyệt:
+
+```bash
+agenteye errors --since 24h --aggregate      # what is breaking, grouped by error type
+agenteye incidents list --state firing       # what is on fire right now
+agenteye keys create ci --add events:add     # a key that can only push events, secret shown once
+```
+
+Một thói quen cần biết: các tùy chọn toàn cục như `--json` đi trước lệnh. `agenteye --json sessions` là đúng; `agenteye sessions --json` là sai.
+
+## Viết script nó, tích hợp vào CI
+
+Mọi lệnh đều nhận `--json`, và điều đó thay đổi mọi thứ. JSON sạch đi đến stdout trong khi trạng thái và cảnh báo của con người đi đến stderr, vì vậy việc capture `--json` đi thẳng vào `jq` mà không có dòng lạc để xóa. Đó là những gì làm cho CLI tốt như nhau cho bạn khi nhắc lệnh và cho một coding agent phân tích đầu ra:
+
+```bash
+agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'
+```
+
+Nó được xây dựng để chạy không được giám sát. Các lời nhắc xác nhận tự động bỏ qua khi không có terminal được đính kèm, vì vậy không có gì bị treo trong đường ống, và mọi lệnh đều trả về mã thoát có ý nghĩa: `0` thành công, `4` chưa đăng nhập, `5` thiếu quyền (thông báo đặt tên nó, ví dụ `alerts:write`), `3` dashboard không thể tiếp cận. Một script có thể phân nhánh trên `4` để xác thực lại hoặc `5` để cho bạn biết chính xác những gì để yêu cầu admin, thay vì thất bại mù quáng.
+
+## Để một coding agent điều khiển nó bằng ngôn ngữ tự nhiên
+
+Tốt hơn, bạn không nên phải nhớ bất kỳ cờ nào trong số này. **CLI skill** là một thư mục Agent Skill nhỏ có tên `agenteye-cli` dạy một coding agent chẳng hạn như Claude Code hoặc Codex cách điều khiển CLI từ các yêu cầu bằng ngôn ngữ tự nhiên. Hỏi "có bất cứ điều gì bị hỏng hôm nay không?" và agent chọn lệnh, chạy nó dưới danh nghĩa bạn, và trả lời bằng văn bản.
+
+Đối với Claude Code, thả thư mục `agenteye-cli` vào `~/.claude/skills/` và nó sẽ được tự động phát hiện. Failproof AI Observability cung cấp thư mục; không có gì thêm để cài đặt, vì nó chỉ điều khiển CLI mà bạn đã cài đặt. Đăng nhập chính mình trước: skill không thể hoàn tất đăng nhập mã email cho bạn.
+
+Vì agent chạy CLI dưới danh nghĩa bạn, nó có thể làm mọi thứ mà đăng nhập của bạn cho phép, cả đọc và ghi: tạo khóa, thay đổi cài đặt, giải quyết sự cố. Lời nhắc "bạn có chắc chắn không?" của CLI không kích hoạt đối với agent, vì vậy skill được viết để nêu lệnh chính xác và chờ OK của bạn trước bất kỳ thay đổi nào. Bạn là bước xác nhận.
+
+```text
+you    Why did session run-001 fail?
+
+agent  Running: agenteye --json events --session-id run-001 --all
+       The checkout-agent hit a TimeoutError on its third tool call.
+```
+
+Các lần đọc vẫn nhanh tức thời, và mỗi lần ghi tạm dừng cho bạn:
+
+```text
+you    Give CI a key that can only push events.
+
+agent  This creates an API key. I'll run:
+         agenteye keys create ci --add events:add
+       OK to proceed?
+
+you    yes
+
+agent  Done. Key "ci" created with events:add only. The secret is shown once, so store it now.
+```
+
+## Liên quan
+
+- [Tham khảo CLI](/vi/agenteye/cli): mọi lệnh, cờ và hình dạng JSON.
+- [Công thức CLI cho agent](/vi/agenteye/cli-recipes): mẫu `jq` sao chép dán và xử lý mã thoát.
+- [CLI agent skill](/vi/agenteye/cli-skill): cài đặt và chạy skill `agenteye-cli`.
+- [Trợ lý AI](/vi/agenteye/assistant): nhà phân tích trong dashboard mà `agent ask` giao tiếp với.