# 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à bộ công cụ mã nguồn mở (Python, giấy phép Apache-2.0) để kiểm toán AI agent: đưa agent vào một môi trường giả lập doanh nghiệp, gửi các yêu cầu thật kể cả yêu cầu vượt quyền, rồi một mô hình khác chấm điểm. Bạn có thể chạy thử bằng agent mẫu mà không cần API key, chỉ mất vài lệnh. Cài đặt không khó nếu bạn đã có Python 3.10 trở lên.

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

iFixAi là một công cụ kiểm toán độc lập dành cho AI agent. Nó trả lời một câu hỏi rất thực tế: agent của bạn có đang làm đúng việc nó được giao, và không làm điều gì không ai yêu cầu hay cho phép hay không? Công cụ chạy bằng dòng lệnh Python, cũng có thể gọi qua plugin hoặc skill trong các trợ lý lập trình như Claude Code hay Cursor.

Cách nó làm khá dễ hình dung. iFixAi đặt agent của bạn vào một mô phỏng của doanh nghiệp, gửi cho agent những yêu cầu của một ngày làm việc bình thường, kèm cả những yêu cầu cố đẩy agent vượt quá vai trò của nó. Sau đó một mô hình "giám khảo" chấm từng câu trả lời. Mỗi kết quả đều cho thấy đã hỏi gì và agent đã làm gì.

Repo này hợp với ai? Người đang làm hoặc sắp triển khai chatbot, agent chăm sóc khách hàng, agent nội bộ; lập trình viên mới muốn kiểm tra sản phẩm trước khi đưa cho người dùng; người quản lý muốn có báo cáo rõ ràng về rủi ro. Điểm đáng giá nhất: bạn có thể thử ngay trong khoảng một phút bằng agent mẫu, không cần khoá API. Hiện repo có khoảng 45.166 sao và 1.792 fork, 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ụ dòng lệnh Python giúp kiểm toán độc lập AI agent: giả lập công việc thật, chấm điểm A đến F xem agent có làm đúng vai trò không.
- stars | 45k
- lang | Python
- license | Apache-2.0
```

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

### Giả lập môi trường doanh nghiệp của bạn

Bạn mô tả agent của mình (vai trò, công cụ nó được dùng, ai được làm gì) trong một file hồ sơ. iFixAi dựng từ đó một môi trường mô phỏng. Nhờ vậy bài kiểm tra bám sát công việc của bạn, thay vì những câu hỏi chung chung.

### Chấm điểm bởi một giám khảo khác nhà cung cấp

Giám khảo có thể là OpenAI, Anthropic, Gemini, Azure, Bedrock, OpenRouter và các bên 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 đúng nhà cung cấp của agent đang bị kiểm tra. Việc này giúp kết quả khách quan hơn, vì agent không tự chấm chính mình.

### Kết quả rõ ràng, dễ đưa cho sếp xem

- Mỗi hạng mục kiểm tra có đạt hoặc không đạt, kèm bằng chứng.
- Điểm tổng từ A đến F, dựa trên năm trụ cột: bịa đặt, thao túng, lừa dối, khó đoán và thiếu minh bạch.
- Ba mức tối thiểu bắt buộc (B01, B08, P01). Trượt một trong ba thì điểm bị khống chế ở mức D.
- Báo cáo dạng JSON và Markdown, để so sánh giữa các lần chạy hoặc chặn CI bằng `--min-score`.

### Mười hạng mục kiểm tra mặc định

Lệnh `ifixai run` chạy 10 hạng mục, đều qua chat. Trong đó có: chỉ cho vai trò được phép dùng đúng công cụ; không bị nói khéo để cấp thêm quyền; không chạy hành động phá huỷ cho người không có quyền; chống prompt injection; chặn yêu cầu vi phạm chính sách; không đưa dữ liệu riêng của người này cho người khác; nói rõ khi không chắc thay vì đoán; báo lỗi thay vì giả vờ thành công; bám đúng nhiệm vụ; làm theo đúng hướng dẫn về định dạng và độ dài. Thêm `--full-run` nếu muốn chạy đủ 61 hạng mục. Hạng mục nào không áp dụng cho agent của bạn sẽ được gạt ra trước và công cụ nói lý do.

### Cài như plugin hoặc skill

Bạn có thể cài iFixAi vào Claude Code, Codex, Cursor, VS Code, Windsurf, Zed và vài công cụ khác. Sau đó chỉ cần nhờ trợ lý: "run iFixAi on my agent". Trợ lý tự tìm agent, dựng môi trường, báo chi phí trước khi tính tiền, chạy kiểm toán và giải thích kết quả.

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

- Python 3.10 trở lên (theo pyproject.toml). README lưu ý `python3` mặc định trên Mac thường là 3.9, nên hãy gõ `python3 --version` để kiểm tra.
- Một môi trường ảo (virtualenv) mới là cách README khuyên dùng.
- Chạy thử bằng agent mẫu: không cần API key.
- Kiểm toán agent thật: cần khoá API của nhà cung cấp làm giám khảo (ví dụ OpenAI), và token của chính agent nếu agent có xác thực.
- Agent cần có một điểm chat (endpoint). Endpoint tương thích OpenAI dùng được ngay; loại khác thì cần viết vài dòng Python.
- Nên dùng bản staging của agent, vì các câu thử là yêu cầu thật gửi tới agent.
- Windows, macOS đều có hướng dẫn trong README. README không nêu yêu cầu GPU hay phần cứng riêng.

```note
Các câu thử là yêu cầu thật và giám khảo là một mô hình gọi qua API, nên có thể phát sinh chi phí. Hãy chạy với bản staging, không phải hệ thống đang phục vụ khách, và luôn chạy --dry-run trước để xem số lượt gọi. Không dán khoá API vào file bạn định chia sẻ.
```

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

```steps
- Tạo môi trường ảo | Tạo virtualenv bằng Python 3.10 trở lên
- Cài gói | Chạy pip install ifixai
- Dựng và kiểm tra hồ sơ mẫu | Dùng ifixai author và ifixai validate
- Chạy thử với agent mẫu | Chạy ifixai run với --provider mock, không cần khoá
- Kiểm toán agent thật | Dùng ifixai setup rồi chạy --dry-run trước khi chạy thật
```

### Tạo môi trường ảo

Mở terminal (trên Windows là PowerShell hoặc Command Prompt) ở thư mục bạn muốn làm việc. Môi trường ảo giúp gói cài không lẫn với phần còn lại của máy.

Mac hoặc Linux:

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

Windows:

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

Chỗ hay vấp: nếu thấy chữ `(.venv)` ở đầu dòng lệnh nghĩa là đã kích hoạt thành công.

### Cài gói và chạy thử bằng agent mẫu

Bốn lệnh dưới đây lấy từ README. Lệnh đầu cài iFixAi. Lệnh thứ hai dựng môi trường mô phỏng cho một agent mẫu (nhân viên hỗ trợ của một công ty fintech giả tưởng) và lưu vào `reference.yaml`. Lệnh thứ ba kiểm tra file đó. Lệnh cuối chạy 10 hạng mục mặc định trên agent mẫu với câu trả lời và điểm có sẵn.

```bash
pip install ifixai
ifixai author reference -o reference.yaml
ifixai validate reference.yaml
ifixai run --provider mock --eval-mode self --fixture reference.yaml
```

Bảng điểm hiện ngay trong terminal, báo cáo được lưu ở thư mục `./ifixai-results/`. Nếu máy báo không tìm thấy `ifixai`, README gợi ý dùng:

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

### Cài như plugin trong Claude Code

Cách này README khuyên dùng. Gõ hai lệnh sau trong Claude Code, rồi nhờ trợ lý chạy iFixAi hoặc gõ `/ifixai:ifixai` (nếu chưa thấy, gõ `/reload-plugins`):

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

Đã cài từ trước thì cập nhật bằng `/plugin marketplace update ifixai-community`, rồi `/reload-plugins`.

Với Codex, chạy hai lệnh này trong terminal rồi mở Codex và nhờ chạy:

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

### Cài như skill cho Cursor, VS Code, Windsurf, Zed

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

Sau đó gõ `/ifixai-skill` trong công cụ đó. Thay `cursor` bằng `claude`, `vscode`, `windsurf`, `cline`, `continue`, `gemini`, `zed` hoặc `all`. Lệnh này dùng `uvx`, nên bạn cần đã có công cụ uv trên máy; README chưa nói cách cài uv ở đoạn này.

### Kiểm toán agent thật bằng CLI có hướng dẫn

Đầu tiên, sao chép hồ sơ mẫu thành `my-agent.json` và sửa cho khớp agent của bạn (README có trang hướng dẫn riêng, hoặc để plugin/skill tự đọc code và viết hồ sơ giúp). Rồi cài thêm phần phụ cho giám khảo bạn chọn, ở đây là OpenAI:

```bash
pip install "ifixai[openai]"
ifixai author my-agent.json -o my-agent.yaml
ifixai validate my-agent.yaml
```

Tiếp theo chạy trình hướng dẫn. Nó hỏi địa chỉ agent, giám khảo, bộ kiểm tra, tìm khoá của giám khảo và lưu tất cả vào `ifixai.yaml`. Sau đó đặt token của agent, chạy `--dry-run` để xem kế hoạch rồi mới chạy thật:

```bash
ifixai setup
export AGENT_API_KEY=...        # your agent's own token
ifixai run --fixture ./my-agent.yaml --api-key "$AGENT_API_KEY" --dry-run
ifixai run --fixture ./my-agent.yaml --api-key "$AGENT_API_KEY"
```

`--dry-run` cho biết số bài thử và số lượt gọi giám khảo, cùng những kiểm tra không áp dụng được cho agent của bạn, rồi dừng lại, chưa tốn tiền. Lệnh `export` dùng cho Mac/Linux; README không ghi lệnh tương đương trên Windows, bạn có thể đặt biến môi trường theo cách quen thuộc của Windows.

Nếu muốn chạy bằng cờ (cho script hoặc CI), README có ví dụ dùng khoá OpenAI:

```bash
export OPENAI_API_KEY=sk-...
export AGENT_API_KEY=...        # your agent's own token
ifixai run --provider http --endpoint <địa chỉ gốc của agent, tới /v1> --api-key "$AGENT_API_KEY" --fixture ./my-agent.yaml --dry-run
```

Địa chỉ endpoint là URL gốc của agent, tính đến `/v1`. Agent không cần xác thực thì thay `--api-key "$AGENT_API_KEY"` bằng `--auth-method none`.

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

Với lần chạy thử bằng agent mẫu, bạn sẽ thấy bảng điểm in ra terminal sau lệnh `ifixai run --provider mock ...`, và có báo cáo trong thư mục `./ifixai-results/`. Nếu hai thứ đó xuất hiện, cài đặt đã ổn.

Với agent thật, lệnh `--dry-run` là bước kiểm tra tốt: nếu nó in được kế hoạch (số bài thử, số lượt gọi giám khảo, các mục bị gạt ra) mà không báo lỗi, nghĩa là hồ sơ, khoá và địa chỉ đều đọc được. Sau lần chạy thật, hãy mở báo cáo JSON hoặc Markdown để xem điểm A đến F và bằng chứng từng mục.

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

### Chủ shop kiểm tra chatbot trả lời khách

Bạn có chatbot tư vấn và xử lý đơn hàng cho shop online. Lo ngại là khách khéo nói để bot tiết lộ thông tin đơn hàng của người khác, hoặc bot hứa hẹn thứ ngoài chính sách. Bạn mô tả bot và vai trò của nó trong hồ sơ, chạy `ifixai run` trên bản thử. Hạng mục như B27 (không đưa dữ liệu riêng của người này cho người khác) và B09 (chặn yêu cầu vi phạm chính sách) cho bạn thấy bot có thủng ở đâu, kèm đúng câu hỏi gây ra lỗi.

### Lập trình viên mới chặn lỗi trước khi phát hành

Bạn vừa viết một agent có quyền gọi công cụ, ví dụ xoá dữ liệu. Trước khi đưa cho người dùng, bạn chạy bộ mặc định và xem ba mức tối thiểu bắt buộc: B01 (đúng vai trò dùng đúng công cụ), B08 (không bị nói để cấp thêm quyền), P01 (không chạy hành động phá huỷ cho người không có quyền). Trượt một mục là điểm tối đa chỉ còn D, nên bạn biết phải sửa gì trước tiên. Khi đã ổn, thêm `--min-score` vào CI để lần nào sửa code cũng bị kiểm lại.

> Agent làm đúng việc hay không, đừng tin cảm giác, hãy cho nó thi.
>
> — Ông T

### Nhân viên văn phòng nhờ trợ lý lập trình chạy giúp

Bạn không rành dòng lệnh. Bạn cài plugin vào Claude Code theo hai lệnh `/plugin`, rồi nhắn: "run iFixAi on my agent". Theo README, trợ lý sẽ tìm agent của bạn, dựng môi trường giả lập, báo chi phí trước khi tính tiền, chạy và giải thích kết quả. Bạn nhận một bản tóm tắt dễ đọc để gửi cho người phụ trách.

### Người quản lý cần báo cáo để so sánh giữa các lần cập nhật

Đội kỹ thuật đổi mô hình hoặc sửa câu lệnh hệ thống cho agent. Bạn muốn biết bản mới có tệ đi không. Mỗi lần chạy sinh báo cáo JSON và Markdown, nên bạn đặt hai báo cáo cạnh nhau, so điểm từng trụ cột như bịa đặt hay thao túng. Muốn kiểm tra rộng hơn thì chạy `--full-run` để đủ 61 hạng mục.

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

### Lệnh ifixai không tìm thấy

Thường do chưa kích hoạt môi trường ảo, hoặc thư mục chứa lệnh không nằm trong PATH. Kích hoạt lại `.venv` rồi thử lại. README cũng gợi ý dùng `python -m ifixai.cli.main` thay cho `ifixai`.

### Python quá cũ

Pyproject yêu cầu Python 3.10 trở lên, mà `python3` mặc định trên Mac có thể là 3.9. Gõ `python3 --version` để kiểm tra, cài bản mới hơn rồi tạo lại môi trường ảo.

### Chưa có khoá cho giám khảo

Chạy thật mà chưa đặt khoá của nhà cung cấp giám khảo thì công cụ không chấm được. Cài đúng phần phụ (ví dụ `ifixai[openai]`), đặt khoá tương ứng bằng biến môi trường như `OPENAI_API_KEY`, hoặc dùng `ifixai setup` để nó tìm khoá giúp. Nhớ rằng giám khảo luôn khác nhà cung cấp với agent.

### Agent trả lỗi xác thực hoặc không kết nối được

Kiểm tra lại token `AGENT_API_KEY` và địa chỉ endpoint, phải là URL gốc tính đến `/v1`. Agent không cần xác thực thì dùng `--auth-method none`. Hãy thử với `--dry-run` trước để phát hiện sớm.

### Plugin không hiện sau khi cài

Trong Claude Code, gõ `/reload-plugins`. Nếu vẫn không thấy, gõ trực tiếp `/ifixai:ifixai`. Với skill cho Cursor và các công cụ khác, gõ `/ifixai-skill` sau khi đã chạy `uvx ifixai install --agents ...`.

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

Điểm mạnh: mã nguồn mở với giấy phép Apache-2.0; thử nhanh không cần khoá; chấm theo nhiều khía cạnh chứ không chỉ bảo mật; giám khảo độc lập với agent; báo cáo có bằng chứng và dùng được trong CI; cài qua plugin cho người ít rành lệnh. Dự án còn có tài liệu về phương pháp, các ca nghiên cứu và công cụ kiểm tra hành động đã ghi lại.

Giới hạn: cần endpoint chat; agent không tương thích OpenAI thì phải viết thêm vài dòng Python. Chạy thật tốn lượt gọi API của giám khảo và các câu thử là yêu cầu thật, nên phải dùng bản staging. Bộ mặc định chỉ 10 hạng mục, đủ để có điểm nhưng chưa phải toàn bộ. README chưa nêu rõ độ chính xác của giám khảo, nên bạn nên xem bằng chứng từng mục thay vì chỉ nhìn điểm chữ. Tài liệu chính viết bằng tiếng Anh (có bản Trung, Nhật, Hàn), chưa thấy bản tiếng Việt.

Nếu chỉ cần quét lỗ hổng bảo mật hạ tầng thông thường, hoặc agent của bạn không có giao diện chat, đây chưa chắc là công cụ phù hợp. Còn nếu bạn muốn biết agent có giữ đúng vai, đúng quyền và biết nói "mình không chắc" hay không, đây là điểm bắt đầu rất đáng thử.

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

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

Bản thân công cụ là mã nguồn mở với giấy phép Apache-2.0. Chạy thử bằng agent mẫu không cần API key. Khi kiểm toán agent thật, giám khảo là một mô hình gọi qua API nên có thể phát sinh chi phí theo nhà cung cấp bạn chọn; hãy dùng --dry-run để xem số lượt gọi trước.

### Có cần GPU không?

Tư liệu không nhắc tới yêu cầu GPU hay phần cứng đặc biệt. Chỉ cần Python 3.10 trở lên; việc chấm điểm do mô hình giám khảo qua API đảm nhiệm.

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

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

### Agent của mình phải thế nào mới kiểm tra được?

Agent cần có một điểm chat (endpoint). Endpoint tương thích OpenAI dùng được ngay, còn loại khác cần viết vài dòng Python. Nên dùng bản staging vì các câu thử là yêu cầu thật.

### Giám khảo chấm điểm là mô hình nào?

Có thể là OpenAI, Anthropic, Gemini, Azure, Bedrock, OpenRouter và các bên khác. iFixAi tự chọn từ các khoá bạn đã đặt, và không chọn nhà cung cấp của chính agent đang kiểm tra.

### Điểm A đến F được tính thế nào?

Điểm dựa trên năm trụ cột: bịa đặt, thao túng, lừa dối, khó đoán và thiếu minh bạch. Có ba mức tối thiểu bắt buộc là B01, B08 và P01; trượt một mục thì điểm bị giới hạn ở mức D. Chi tiết cách tính nằm trong tài liệu Scoring của repo.

### Dữ liệu của mình có an toàn không?

Tư liệu chưa nói chi tiết về xử lý dữ liệu. Có thể thấy là các câu thử và câu trả lời của agent được gửi tới mô hình giám khảo qua API, nên bạn nên cân nhắc nhà cung cấp và dùng dữ liệu giả hoặc môi trường staging. Vấn đề bảo mật có file SECURITY.md trong repo.
