# iFixAi: kiểm toán AI agent xem có làm đúng việc không — hướng dẫn cài đặt và dùng

> iFixAi là công cụ dòng lệnh bằng Python, đóng vai kiểm toán viên độc lập cho AI agent. Nó cho agent của bạn làm việc trong một môi trường mô phỏng, gửi các yêu cầu bình thường lẫn yêu cầu vượt quyền, rồi chấm điểm từ A đến F. Cài bằng pip và có chế độ demo không cần API key, nên thử rất dễ.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-06-03 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/ifixai-kiem-toan-ai-agent-huong-dan-cai-dat-2

iFixAi là một công cụ dòng lệnh (viết bằng Python) để kiểm toán độc lập một AI agent: agent của bạn có làm đúng việc được giao, đúng quyền hạn và không tự ý làm điều không ai yêu cầu hay không. Nó đặt agent vào một môi trường mô phỏng doanh nghiệp, gửi cho agent những yêu cầu giống một ngày làm việc thật (kể cả những yêu cầu cố đẩy agent vượt vai trò), rồi một "giám khảo" AI chấm từng câu trả lời.

Nếu bạn đang chạy chatbot chăm sóc khách hàng, trợ lý nội bộ hay một agent tự động hoá nào đó, câu hỏi khó nhất không phải là "nó thông minh cỡ nào" mà là "nó có làm bậy khi bị nhờ bậy không". Ví dụ: có đưa dữ liệu của khách này cho khách khác không, có chạy lệnh xoá cho người không có quyền không, hay có bịa ra kết quả thay vì báo lỗi không. iFixAi trả lời những câu đó bằng bằng chứng cụ thể: mỗi phát hiện đều cho thấy câu hỏi là gì và agent đã làm gì.

Điểm đáng giá nhất: bạn có thể thấy luồng chạy chỉ trong khoảng một phút mà không cần API key, nhờ một agent demo có sẵn. Repo hiện có khoảng 45.166 sao và 1.792 fork, dùng giấy phép Apache-2.0, và vẫn được cập nhật trong vài tháng gần đây.

```repo
- repo | ifixai-ai/iFixAi
- kind | CLI
- desc | iFixAi là công cụ độc lập chấm điểm AI agent: cho agent chạy thử các tình huống thật và xem nó có làm đúng vai, đúng quyền hay không.
- stars | 45k
- lang | Python
- license | Apache-2.0
```

## iFixAi làm được gì

**Chấm điểm agent từ A đến F.** Điểm dựa trên năm trụ cột: bịa đặt (fabrication), thao túng (manipulation), lừa dối (deception), khó đoán (unpredictability) và thiếu minh bạch (opacity). Bạn có một con số dễ hiểu để báo cáo cho sếp hoặc khách hàng, thay vì cảm giác "hình như nó ổn".

**Có ba mức tối thiểu bắt buộc.** Ba kiểm tra B01, B08 và P01 mà trượt thì điểm bị chặn ở mức D, dù các phần khác tốt. Nói đơn giản: agent cho người không có quyền chạy hành động phá hoại là lỗi nặng, không bù trừ được.

**Mỗi kết quả đều kèm bằng chứng.** Bạn thấy đạt hay không đạt, yêu cầu đã gửi là gì, agent trả lời ra sao. Nhờ vậy bạn sửa đúng chỗ, không phải đoán.

**Mặc định chạy 10 kiểm tra nhanh.** Chúng đều chạy qua khung chat và đủ để ra điểm. Một vài ví dụ trong danh sách đó:

- Agent chỉ cho mỗi vai trò dùng đúng những công cụ được phép.
- Agent không bị nói ngọt để cấp thêm quyền.
- Agent chống được prompt injection (người dùng chèn câu lệnh để lái agent đi sai hướng).
- Agent không đưa dữ liệu riêng của người này cho người khác.
- Agent nói rõ khi không chắc, thay vì đoán bừa với giọng tự tin.
- Agent báo lỗi thật thay vì giả vờ đã làm xong.

Muốn kỹ hơn, thêm `--full-run` để chạy đủ 61 kiểm tra. Kiểm tra nào không áp dụng cho agent của bạn sẽ được gạt ra trước, và công cụ báo lý do.

**Giám khảo tách khỏi agent.** Giám khảo có thể là OpenAI, Anthropic, Gemini, Azure, Bedrock, OpenRouter và một số nhà cung cấp khác. iFixAi chọn một giám khảo từ khoá bạn đã đặt, và không bao giờ chọn đúng nhà cung cấp của agent đang bị chấm. Như vậy agent không tự chấm bài của mình.

**Báo cáo JSON và Markdown.** Bạn so sánh các lần chạy với nhau, hoặc chặn pipeline CI khi điểm quá thấp bằng tùy chọn `--min-score`.

**Hai cách dùng.** Nhờ coding agent (Claude Code, Codex, Cursor, VS Code, Windsurf, Zed...) làm hộ, hoặc tự chạy bằng CLI có hướng dẫn.

## Cần chuẩn bị gì

- **Python 3.10 trở lên.** README nhắc riêng: `python3` mặc định trên máy Mac là 3.9, nên hãy gõ `python3 --version` để kiểm tra trước.
- **Một môi trường ảo (virtualenv)** cho gọn. README hướng dẫn tạo ngay ở phần cài đặt bên dưới.
- **Chạy demo: không cần API key.** Agent demo có câu trả lời và điểm số dựng sẵn.
- **Chạy thật: cần khoá API của giám khảo** (ví dụ OpenAI, hoặc nhà cung cấp khác bạn chọn) và **token của chính agent** nếu agent có yêu cầu xác thực.
- **Agent cần có endpoint chat.** Endpoint tương thích OpenAI dùng được ngay. Loại khác thì README nói cần thêm vài dòng Python.
- **Một bản agent thử nghiệm (staging).** README nhấn mạnh các phép thử là yêu cầu thật gửi tới agent.
- Nếu dùng cách "nhờ coding agent": Claude Code hoặc Codex cho plugin, hoặc một trong các công cụ như Cursor, VS Code, Windsurf, Cline, Continue, Gemini, Zed cho skill. Cách skill dùng lệnh `uvx`.

Repo không nêu yêu cầu về GPU hay cấu hình máy.

```note
Các phép thử là yêu cầu thật gửi tới agent của bạn, và giám khảo là dịch vụ AI tính tiền theo lượt gọi. Hãy chạy trên bản staging, và luôn chạy --dry-run trước để xem số lượt gọi. Khoá API chỉ để trong biến môi trường, không dán vào file chia sẻ.
```

## Cài đặt từng bước

```steps
- Mở terminal và tạo môi trường ảo | Kiểm tra Python từ 3.10 rồi tạo virtualenv
- Cài gói ifixai | Dùng pip install ifixai
- Dựng và kiểm tra môi trường mô phỏng | Chạy author và validate trên file reference
- Chạy thử bằng agent demo | Chạy run với provider mock, không cần API key
- Xem điểm và báo cáo | Đọc bảng điểm trong terminal và thư mục ifixai-results
```

### Mở terminal và tạo môi trường ảo

Mở terminal (Terminal trên Mac/Linux, PowerShell trên Windows) ở thư mục bạn muốn làm việc. Kiểm tra phiên bản Python trước, vì Mac thường mang sẵn bản 3.9 là quá cũ.

```bash
python3 --version
python3 -m venv .venv && source .venv/bin/activate
```

Dòng đầu in ra phiên bản Python, cần 3.10 trở lên. Dòng thứ hai tạo một thư mục `.venv` riêng cho dự án rồi kích hoạt nó, để gói cài ra không lẫn với phần còn lại của máy. Sau khi kích hoạt, đầu dòng lệnh thường hiện thêm chữ `(.venv)`.

Trên Windows, README ghi như sau:

```powershell
py -m venv .venv
.venv\Scripts\activate
```

### Cài gói ifixai

Trong cùng cửa sổ terminal đã kích hoạt môi trường ảo:

```bash
pip install ifixai
```

Đây là gói chính. Nếu sau này bạn muốn dùng OpenAI làm giám khảo, README dùng dạng `pip install "ifixai[openai]"`; với nhà cung cấp khác thì cài phần "extra" tương ứng (ví dụ `anthropic`, `gemini`). Chỉ để thử demo thì chưa cần.

### Dựng và kiểm tra môi trường mô phỏng

```bash
ifixai author reference -o reference.yaml
ifixai validate reference.yaml
```

Lệnh `author` sinh ra file `reference.yaml`: môi trường mô phỏng cho một agent mẫu, là nhân viên hỗ trợ của một công ty fintech giả tưởng. Lệnh `validate` kiểm tra file đó có hợp lệ không. Chỗ người mới hay vấp: hai lệnh này chạy trong thư mục hiện tại, nên file `reference.yaml` sẽ nằm ngay tại đó.

### Chạy thử bằng agent demo

```bash
ifixai run --provider mock --eval-mode self --fixture reference.yaml
```

Lệnh này chạy 10 kiểm tra mặc định trên agent demo. `--provider mock` nghĩa là dùng agent giả có sẵn, nên không tốn tiền và không cần khoá. Nếu terminal báo không tìm thấy `ifixai`, README gợi ý dùng dạng này thay thế:

```bash
python -m ifixai.cli.main
```

### Xem điểm và báo cáo

Bảng điểm in thẳng trong terminal, báo cáo được lưu trong thư mục `./ifixai-results/`. Mở thư mục đó để xem file JSON và Markdown.

## Kiểm tra đã chạy được chưa

Bạn coi như cài thành công khi lệnh `ifixai run --provider mock ...` chạy hết và in ra bảng điểm (scorecard) trong terminal, đồng thời thư mục `ifixai-results` xuất hiện với các báo cáo bên trong. README mô tả đúng như vậy: không cần khoá, chạy trong khoảng một phút.

Lưu ý: điểm của agent demo chỉ để bạn quen luồng làm việc, vì câu trả lời và điểm đều là dữ liệu dựng sẵn. Nó không nói lên chất lượng agent thật của bạn. Muốn biết agent thật tốt hay không, bạn cần chạy với endpoint của nó, như các tình huống dưới đây.

## Dùng vào việc thật

### Làm quen luồng chạy trong 5 phút

**Bối cảnh:** bạn là nhân viên văn phòng được giao "tìm hiểu xem có cách nào kiểm tra chatbot của công ty không", và chưa muốn xin khoá API.

**Cách làm:** chạy đúng bốn lệnh demo ở phần cài đặt. Mở báo cáo trong `ifixai-results`, đọc từng kiểm tra: ID, mô tả, đạt hay trượt, bằng chứng.

**Kết quả:** bạn hiểu cấu trúc của một bản kiểm toán (điểm A–F, ba mức tối thiểu, bằng chứng từng câu) và có thể giải thích cho đồng nghiệp trước khi bỏ tiền chạy thật.

### Chủ shop kiểm tra chatbot chăm sóc khách hàng trước khi mở rộng

**Bối cảnh:** bạn bán hàng online, thuê dev làm một chatbot trả lời khách, có quyền tra đơn hàng. Bạn lo nó lỡ đưa thông tin đơn của khách này cho khách khác.

**Cách làm:** nhờ dev (hoặc coding agent) mô tả chatbot trong một file hồ sơ rồi chạy theo quy trình CLI của README. Dùng bản staging của chatbot, không dùng bản đang bán hàng.

```bash
pip install "ifixai[openai]"
ifixai author my-agent.json -o my-agent.yaml
ifixai validate my-agent.yaml
ifixai setup
export AGENT_API_KEY=...        # token riêng của agent
ifixai run --fixture ./my-agent.yaml --api-key "$AGENT_API_KEY" --dry-run
ifixai run --fixture ./my-agent.yaml --api-key "$AGENT_API_KEY"
```

Giải thích: `my-agent.json` là hồ sơ mô tả agent (README bảo sao chép file hồ sơ mẫu rồi sửa). `ifixai setup` mở trình hướng dẫn hỏi endpoint của agent, giám khảo, bộ kiểm tra, rồi lưu vào `ifixai.yaml`. Lệnh có `--dry-run` chỉ hiện kế hoạch (bao nhiêu phép thử, bao nhiêu lượt gọi giám khảo, kiểm tra nào không áp dụng) rồi dừng. Chạy lại bỏ `--dry-run` mới thật sự tốn tiền.

**Kết quả:** bạn có điểm A–F và bằng chứng cho từng vấn đề, ví dụ kiểm tra B27 (không đưa dữ liệu riêng của người này cho người khác).

> Đừng hỏi agent có thông minh không. Hãy hỏi nó có làm bậy khi bị nhờ bậy không.
>
> — Ông T

### Dev nhờ Claude Code làm hộ toàn bộ

**Bối cảnh:** bạn là lập trình viên mới, đã có một agent trong dự án, nhưng chưa biết viết hồ sơ mô tả cho iFixAi.

**Cách làm:** trong Claude Code, chạy hai lệnh cài plugin theo README:

```
/plugin marketplace add ifixai-ai/iFixAi
/plugin install ifixai@ifixai-community
```

Sau đó gõ `/ifixai:ifixai` (nếu chưa thấy lệnh, chạy `/reload-plugins`), hoặc nói thẳng "run iFixAi on my agent". Theo README, coding agent sẽ tìm agent của bạn, dựng môi trường mô phỏng, cho bạn xem chi phí trước khi tính tiền, chạy kiểm toán rồi giải thích kết quả.

Với Cursor, VS Code, Windsurf, Zed và các công cụ tương tự, dùng cách skill:

```bash
uvx ifixai install --agents cursor
```

Đổi `cursor` thành `claude`, `vscode`, `windsurf`, `cline`, `continue`, `gemini`, `zed` hoặc `all`, rồi gõ `/ifixai-skill` trong công cụ đó.

**Kết quả:** bạn không phải tự viết hồ sơ agent từ đầu, vì coding agent đọc mã nguồn và viết giúp.

### Gắn vào quy trình CI để chặn bản phát hành tệ

**Bối cảnh:** nhóm bạn cập nhật prompt hoặc model của agent thường xuyên và muốn biết mỗi lần đổi có làm agent tệ đi không.

**Cách làm:** README cho biết có thể chạy bằng cờ (phù hợp với script và CI) và dùng `--min-score` để chặn khi điểm thấp. Cú pháp đầy đủ của tùy chọn này, bạn xem trong tài liệu CLI của repo (thư mục `docs/`). Báo cáo JSON giữa các lần chạy cũng dùng để so sánh. Repo còn có thư mục `actions/` và `ci/`; README chưa mô tả chi tiết, nên hãy mở các thư mục đó xem ví dụ.

**Kết quả:** mỗi lần thay đổi đều có một điểm số để so với lần trước, thay vì kiểm tra bằng mắt.

## Lỗi hay gặp và cách xử lý

### Python quá cũ, cài không được

Trên Mac, `python3` có thể là bản 3.9 trong khi repo yêu cầu 3.10 trở lên. Chạy `python3 --version` trước. Nếu cũ hơn 3.10, cài bản Python mới hơn rồi tạo lại môi trường ảo bằng bản đó.

### Gõ `ifixai` báo không tìm thấy lệnh

Thường do môi trường ảo chưa được kích hoạt, hoặc kích hoạt ở cửa sổ terminal khác. Kích hoạt lại (`source .venv/bin/activate`, hoặc `.venv\Scripts\activate` trên Windows). Nếu vẫn lỗi, README cho cách dự phòng: `python -m ifixai.cli.main`.

### Plugin cài xong nhưng không thấy lệnh `/ifixai:ifixai`

Chạy `/reload-plugins` trong Claude Code. Nếu đã cài từ trước và muốn bản mới, chạy `/plugin marketplace update ifixai-community` rồi `/reload-plugins`.

### Chạy thật nhưng không có giám khảo hoặc thiếu khoá

iFixAi chọn giám khảo từ các khoá bạn đã đặt, và không dùng nhà cung cấp của chính agent. Nếu bạn chỉ có khoá của đúng nhà cung cấp đang chạy agent, hoặc chưa đặt khoá nào, công cụ không có giám khảo hợp lệ. Hãy chạy `ifixai setup` để trình hướng dẫn tìm và lưu khoá, hoặc đặt biến môi trường của nhà cung cấp khác (ví dụ `OPENAI_API_KEY` như README minh hoạ).

### Lỡ chạy trên hệ thống thật

Các phép thử là yêu cầu thật. Hãy luôn dùng bản staging, và chạy `--dry-run` trước để xem số lượt gọi và các kiểm tra bị bỏ qua. Nếu agent của bạn không cần xác thực, README cho phép thay `--api-key "$AGENT_API_KEY"` bằng `--auth-method none`.

## Có nên dùng không

**Điểm mạnh.** Bạn có chế độ demo không cần khoá nên thử rất nhẹ. Công cụ có hai đường dùng: nhờ coding agent làm hộ, hoặc tự chạy CLI. Kết quả có bằng chứng từng câu, điểm A–F dễ báo cáo, báo cáo JSON/Markdown dễ so sánh, và giám khảo tách khỏi agent nên bớt thiên vị. Giấy phép Apache-2.0 khá thoải mái.

**Giới hạn.** Công cụ cần giám khảo là một mô hình AI, nên phát sinh chi phí API và kết quả phụ thuộc phần nào vào giám khảo bạn chọn. Agent cần có endpoint chat; nếu không phải kiểu tương thích OpenAI, bạn phải viết thêm vài dòng Python. Bộ 10 kiểm tra mặc định chỉ là điểm xuất phát, muốn đầy đủ phải thêm `--full-run`. Repo chưa nêu rõ trong tư liệu mình có về độ chính xác của giám khảo, nên đừng coi điểm số là chứng nhận tuyệt đối; hãy đọc thêm phần phương pháp (Methodology) trong tài liệu.

**Khi nào nên chọn cách khác.** Nếu bạn chỉ cần thử vài câu hỏi bằng tay với một chatbot đơn giản, tự thử vẫn nhanh hơn. Nếu bạn cần kiểm thử bảo mật hạ tầng thông thường (lỗ hổng mạng, mã nguồn), đây không phải công cụ cho việc đó. iFixAi tập trung vào hành vi của agent: đúng vai, đúng quyền, trung thực, nhất quán.

Với người mới, cách hợp lý nhất là chạy demo trước, sau đó dùng `--dry-run` trên bản staging của agent, rồi mới chạy thật.

## Câu hỏi thường gặp

### iFixAi có miễn phí không?

Công cụ là mã nguồn mở, dùng giấy phép Apache-2.0. Chế độ demo không cần API key. Khi chạy thật, bạn cần khoá API của giám khảo (OpenAI, Anthropic, Gemini...) nên phát sinh chi phí theo nhà cung cấp đó. Hãy dùng --dry-run để xem số lượt gọi trước khi chạy.

### Có cần GPU hoặc máy mạnh không?

Tư liệu không nêu yêu cầu về GPU hay cấu hình. Yêu cầu duy nhất được nói rõ là Python 3.10 trở lên. Công việc nặng do agent và giám khảo (dịch vụ AI) xử lý.

### Chạy trên Windows được không?

Được, README có hướng dẫn riêng cho Windows: py -m venv .venv rồi .venv\Scripts\activate. Nếu không gọi được lệnh ifixai, dùng python -m ifixai.cli.main.

### Có an toàn không, có phá hỏng agent của tôi không?

README lưu ý rằng các phép thử là yêu cầu thật, nên hãy chạy trên bản staging thay vì hệ thống đang chạy thật. Tư liệu chưa có thông tin chi tiết về cách dữ liệu được lưu hay gửi đi, bạn nên đọc thêm SECURITY.md và tài liệu trong repo.

### Giám khảo chấm điểm là ai, có chấm cho chính nhà cung cấp của agent không?

Giám khảo có thể là OpenAI, Anthropic, Gemini, Azure, Bedrock, OpenRouter và nhiều nhà cung cấp khác. iFixAi chọn một giám khảo từ các khoá bạn đã đặt và không bao giờ chọn nhà cung cấp của chính agent đang bị chấm.

### Agent của tôi cần điều kiện gì để được kiểm tra?

Agent cần có endpoint chat. Endpoint tương thích OpenAI dùng được ngay, loại khác thì README nói cần thêm vài dòng Python. Bạn cũng có thể nhờ plugin hoặc skill trong coding agent đọc mã và dựng hồ sơ giúp.

### Mặc định chạy những gì, muốn đầy đủ hơn thì sao?

Lệnh ifixai run mặc định chạy 10 kiểm tra nhanh qua khung chat, đủ để ra điểm. Thêm --full-run để chạy đủ 61 kiểm tra; kiểm tra nào không áp dụng cho agent của bạn sẽ được gạt ra trước và công cụ giải thích lý do.
