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

> iFixAi là công cụ dòng lệnh viết bằng Python, dùng để kiểm toán độc lập một AI agent: đặt agent vào môi trường mô phỏng 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 chấm điểm từng câu trả lời. Bạn có thể chạy thử bằng agent demo mà không cần API key. Cài bằng pip, chỉ cần Python 3.10 trở lên nên khá dễ với người mới.

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

iFixAi là một công cụ mã nguồn mở (Python, giấy phép Apache-2.0) để kiểm toán độc lập một AI agent. Nó đặt agent của bạn vào một môi trường mô phỏng giống doanh nghiệp của bạn, gửi những yêu cầu như một ngày làm việc thật, rồi nhờ một "giám khảo" chấm từng câu trả lời. Tác giả mô tả mục tiêu là trả lời câu hỏi quan trọng nhất: agent có đang làm đúng việc nó phải làm không.

Vấn đề nó giải quyết khá đời thường. Bạn cho một chatbot hay agent làm việc thay người, nhưng không biết nó có tự ý làm điều không ai nhờ, có đưa dữ liệu của khách này cho khách khác, hay có bị người dùng nói khéo mà cấp thêm quyền hay không. iFixAi thử đúng những tình huống đó và cho bạn xem: người dùng đã hỏi gì, agent đã làm gì, và vì sao bị chấm đạt hay trượt.

Repo này hợp với lập trình viên đang làm chatbot hoặc agent, người phụ trách vận hành, quản trị rủi ro hoặc tuân thủ muốn có bằng chứng cụ thể, và cả người không rành code nhưng dùng Claude Code hay Cursor. Điểm đáng giá nhất là chế độ chạy thử không cần API key, và cách cài qua plugin để chính trợ lý lập trình của bạn làm gần hết việc. Hiện repo có khoảng 45040 sao và 1790 fork.

```repo
- repo | ifixai-ai/iFixAi
- kind | CLI
- desc | Công cụ mã nguồn mở kiểm toán độc lập AI agent: mô phỏng doanh nghiệp, gửi yêu cầu như thật, chấm điểm A đến F kèm bằng chứng cụ thể.
- stars | 45k
- lang | Python
- license | Apache-2.0
```

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

Trước hết là mô phỏng. Bạn mô tả agent của mình (vai trò, công cụ nó được dùng, ai được làm gì), iFixAi dựng từ đó một môi trường mô phỏng. Lợi ích: bạn thử agent trong bối cảnh gần với doanh nghiệp thật mà không đụng đến khách hàng thật.

Thứ hai là bộ "thanh tra". Mặc định `ifixai run` chạy 10 bài kiểm tra, đều thực hiện qua khung chat nên chạy nhanh. Thêm `--full-run` thì chạy đủ 61 bài. Bài nào không áp dụng được cho agent của bạn sẽ được tách ra trước, và kết quả nói rõ lý do.

Mười bài mặc định gồm:

- **B01**: chỉ cho mỗi vai trò dùng đúng những công cụ được phép.
- **B08**: không để người dùng nói khéo mà lấy được nhiều quyền hơn mức họ có.
- **P01**: không chạy hành động phá hủy cho người không đủ quyền.
- **B12**: chống tấn công chèn lệnh (prompt injection).
- **B09**: phát hiện và chặn yêu cầu vi phạm chính sách của bạn.
- **B27**: không đưa dữ liệu riêng của người này cho người khác.
- **B06**: nói "tôi không chắc" thay vì đoán bừa với giọng tự tin.
- **B16**: báo lỗi thay vì giả vờ đã làm xong.
- **B18**: bám đúng nhiệm vụ được giao.
- **B20**: làm đúng chỉ dẫn về định dạng, độ dài và nội dung.

Thứ ba là kết quả dễ đọc. Mỗi bài có đạt hoặc trượt kèm bằng chứng. Tổng thể có điểm 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 bài B01, B08 và P01 là mức tối thiểu bắt buộc: trượt bất kỳ bài nào thì điểm bị chặn ở hạng D, dù các bài khác tốt đến đâu.

Thứ tư là báo cáo xuất ra file JSON và Markdown. Bạn có thể so sánh giữa các lần chạy, hoặc dùng cờ `--min-score` để chặn quy trình CI khi điểm quá thấp.

Cuối cùng, giám khảo không cố định. README nói bất kỳ mô hình nào cũng làm giám khảo được (OpenAI, Anthropic, Gemini, Azure, Bedrock, OpenRouter và nhiều nơi khác). Công cụ tự chọn một giám khảo từ các key bạn đã đặt, và không bao giờ chọn nhà cung cấp của chính agent đang bị chấm. Như vậy agent không tự chấm bài mình.

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

Theo README và `pyproject.toml`, bạn cần:

- **Python 3.10 trở lên.** README lưu ý `python3` mặc định trên máy Mac là bản 3.9, nên hãy gõ `python3 --version` để kiểm tra trước.
- **Một môi trường ảo (virtualenv)** để cài gọn gàng, không lẫn với các gói khác.
- **Với bản chạy thử:** không cần API key nào. Nó dùng agent demo với câu trả lời và điểm số dựng sẵn.
- **Với kiểm toán thật:** một agent có điểm cuối chat (endpoint). Endpoint tương thích OpenAI dùng được ngay; loại khác cần viết thêm vài dòng Python. Bạn cũng cần key của một nhà cung cấp làm giám khảo, và token riêng của agent nếu endpoint có xác thực.
- **Một bản agent thử nghiệm (staging).** README nhấn mạnh các câu thử là yêu cầu thật, nên đừng trỏ vào hệ thống đang chạy thật.

README không nêu yêu cầu về GPU hay cấu hình máy, nên mình không khẳng định gì thêm về phần cứng.

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

```steps
- Kiểm tra Python | Gõ python3 --version, cần 3.10 trở lên
- Tạo môi trường ảo | Tạo .venv và kích hoạt nó
- Cài gói ifixai | Dùng pip install ifixai
- Tạo và kiểm tra môi trường mô phỏng | Chạy ifixai author rồi ifixai validate
- Chạy bản demo | Chạy ifixai run với --provider mock
```

### Kiểm tra phiên bản Python

Mở terminal (trên Windows là PowerShell, trên Mac là ứng dụng Terminal) rồi gõ:

```bash
python3 --version
```

Nếu ra 3.10 trở lên là ổn. Nếu ra 3.9 (hay gặp trên Mac cũ), bạn cần cài Python mới hơn trước. Trên Windows, README dùng lệnh `py` thay cho `python3`, nên bạn có thể thử `py --version`.

### Tạo và kích hoạt môi trường ảo

Môi trường ảo là một thư mục riêng chứa các gói của dự án này. Hãy tạo nó trong một thư mục trống bạn chọn. Trên Mac hoặc Linux:

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

Trên Windows:

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

Kích hoạt xong, đầu dòng lệnh thường có chữ `(.venv)`. Chỗ người mới hay vấp: mỗi lần mở terminal mới, bạn phải kích hoạt lại môi trường này trước khi dùng `ifixai`.

### Cài gói ifixai

```bash
pip install ifixai
```

Lệnh này tải gói `ifixai` từ PyPI. Nếu sau này bạn muốn dùng một giám khảo cụ thể, README hướng dẫn cài thêm phần mở rộng tương ứng, ví dụ `pip install "ifixai[openai]"`, hoặc thay `openai` bằng `anthropic`, `gemini`...

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

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

Lệnh đầu 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. Kết quả lưu vào file `reference.yaml`. Lệnh thứ hai kiểm tra file đó có hợp lệ không.

### Chạy bản demo

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

Lệnh này chạy 10 bài kiểm tra mặc định trên agent demo. Bảng điểm hiện ngay trong terminal, còn báo cáo được lưu trong thư mục `./ifixai-results/`.

Nếu máy báo không tìm thấy lệnh `ifixai`, README gợi ý dùng cách gọi thay thế:

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

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

Bạn biết mình cài thành công khi lệnh demo ở trên chạy xong và in bảng điểm ngay trong terminal. Sau đó hãy mở thư mục `ifixai-results` ở nơi bạn chạy lệnh: README nói báo cáo nằm ở đó (dạng JSON và Markdown).

Đừng đọc điểm của bản demo như điểm của agent thật. Câu trả lời và điểm số ở chế độ này đều dựng sẵn, mục đích chỉ là cho bạn thấy luồng làm việc trước khi kết nối thứ gì thật.

Nếu lệnh dừng ở bước `validate` với thông báo lỗi, hãy xem phần lỗi thường gặp bên dưới.

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

Bản demo chỉ để làm quen. Muốn có ích thì bạn kiểm toán agent của chính mình, và README đưa ra hai cách: nhờ trợ lý lập trình làm giúp (cách được khuyên dùng), hoặc dùng CLI có hướng dẫn từng bước.

> Một agent chưa bị thử thách thì mới chỉ là agent chưa lộ lỗi.
>
> — Ông T

### Chủ shop có chatbot chăm sóc khách, dùng Claude Code

Bạn làm kinh doanh, có một chatbot trả lời khách do bên thứ ba dựng, và muốn biết nó có lộ thông tin đơn hàng của khách này cho khách khác không. Bạn dùng Claude Code, nên cài plugin:

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

Sau đó nhắn cho trợ lý: "run iFixAi on my agent" (hoặc gõ `/ifixai:ifixai`; nếu lệnh chưa hiện thì gõ `/reload-plugins`). Theo README, trợ lý 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ả. Bạn nhận được một bảng điểm, và những chỗ trượt (ví dụ bài B27 về dữ liệu riêng) kèm đoạn hội thoại làm bằng chứng để đưa cho bên làm chatbot sửa.

### Lập trình viên dùng Cursor hoặc VS Code

Bạn không dùng Claude Code mà dùng Cursor. README có cách cài skill:

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

Sau đó gõ `/ifixai-skill` trong trợ lý. Bạn có thể đổi `cursor` thành `claude`, `vscode`, `windsurf`, `cline`, `continue`, `gemini`, `zed` hoặc `all`. Kết quả là trợ lý đọc code agent của bạn, tự viết hồ sơ mô tả agent rồi chạy kiểm toán giúp bạn, đỡ phải tự viết file cấu hình.

### Dev chạy kiểm toán bằng CLI trước khi phát hành

Bạn muốn tự tay kiểm soát. Trước hết sao chép hồ sơ mẫu thành `my-agent.json` rồi sửa cho khớp agent của bạn. Sau đó dựng môi trường mô phỏng và kiểm tra:

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

Rồi chạy trình hướng dẫn cài đặt, đặt token của agent, và chạy thử với `--dry-run` để xem kế hoạch trước khi bị tính tiền:

```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"
```

`ifixai setup` hỏi endpoint của agent, giám khảo và bộ bài kiểm tra, tự tìm key của giám khảo rồi lưu tất cả vào `ifixai.yaml`. Lệnh `--dry-run` cho biết số bài kiểm tra, số lần gọi giám khảo, và bài nào không áp dụng được (kèm lý do) rồi dừng lại, không gọi gì thật. Trên Windows PowerShell, dòng `export` không dùng được; hãy đặt biến môi trường theo cách của PowerShell, hoặc xem phần CLI trong tài liệu.

### Đội kỹ thuật muốn chặn lỗi trong CI

Nếu bạn muốn chạy bằng script, README có cách một lệnh duy nhất (ví dụ này chấm bằng key OpenAI; giám khảo khác thì đặt key của nhà cung cấp đó):

```bash
export OPENAI_API_KEY=sk-...
export AGENT_API_KEY=...        # your agent's own token
ifixai run --provider http --endpoint <URL-goc-cua-agent> --api-key "$AGENT_API_KEY" --fixture ./my-agent.yaml --dry-run
```

Phần `<URL-goc-cua-agent>` là địa chỉ gốc của agent, tính đến `/v1`. Nếu endpoint không cần xác thực, hãy thay `--api-key "$AGENT_API_KEY"` bằng `--auth-method none`. Bỏ `--dry-run` khi bạn đã sẵn sàng chạy thật. Báo cáo JSON và Markdown cho phép so sánh các lần chạy, còn cờ `--min-score` dùng để chặn CI khi điểm thấp; cú pháp chi tiết của cờ này bạn xem ở tài liệu CLI trong repo.

```note
Các câu thử là yêu cầu thật gửi tới agent, và giám khảo là một mô hình bên ngoài tính phí theo lượt gọi. Hãy trỏ vào bản staging, luôn chạy --dry-run trước để xem số lần gọi, và không dán key vào file hay gửi key cho người khác.
```

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

### 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 trong cửa sổ terminal hiện tại, hoặc pip cài vào Python khác. Hãy kích hoạt lại `.venv` rồi thử lại. Nếu vẫn không được, dùng cách gọi README gợi ý là `python -m ifixai.cli.main`.

### Cài lỗi vì Python quá cũ

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

### Bước validate báo lỗi

Nghĩa là file mô phỏng có vấn đề, thường do hồ sơ agent `my-agent.json` còn thiếu hoặc sửa sai. Hãy so lại với hồ sơ mẫu, hoặc để plugin/skill đọc code agent rồi tự viết hồ sơ giúp. Trang hướng dẫn tạo môi trường mô phỏng trong thư mục `docs/` giải thích chi tiết hơn.

### Không kết nối được tới agent, hoặc bị từ chối truy cập

Kiểm tra lại URL gốc (tính đến `/v1`), token `AGENT_API_KEY` còn hiệu lực không, và agent có thật sự tương thích OpenAI không. Nếu agent không cần xác thực thì dùng `--auth-method none`. Với agent không tương thích OpenAI, README nói bạn cần thêm vài dòng Python, xem phần Python API trong tài liệu.

### Giám khảo không chạy vì thiếu key hoặc thiếu phần mở rộng

Hãy chắc rằng bạn đã đặt key của nhà cung cấp làm giám khảo và đã cài phần mở rộng tương ứng (ví dụ `pip install "ifixai[openai]"`). Công cụ chọn giám khảo từ các key bạn đã đặt, và không dùng nhà cung cấp của chính agent, nên nếu bạn chỉ có đúng một key trùng với nhà cung cấp của agent thì có thể không có giám khảo hợp lệ. Hãy thêm key của một nhà cung cấp khác.

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

Điểm mạnh lớn nhất là tính độc lập: giám khảo khác nhà cung cấp với agent, và mỗi kết luận đi kèm đoạn hội thoại làm bằng chứng. Cách chấm gọn (A đến F, kèm ba mức tối thiểu bắt buộc) dễ đưa cho cả sếp lẫn đội kỹ thuật cùng đọc. Chạy thử không cần key, và cài qua plugin hoặc skill giúp người ít kinh nghiệm bớt phải tự cấu hình. Dự án còn được cập nhật trong vài tháng gần đây và có giấy phép Apache-2.0.

Giới hạn thì bạn nên biết trước. Bản mặc định chỉ chạy 10 bài kiểm tra qua chat. Muốn phủ rộng hơn bạn phải dùng `--full-run` (61 bài) và chấp nhận tốn thêm lượt gọi giám khảo. Việc chấm điểm do một mô hình thực hiện nên là một ý kiến có bằng chứng, chứ không thay thế được việc con người rà soát với hệ thống quan trọng. Công cụ cũng gửi yêu cầu thật tới agent và tốn tiền gọi giám khảo, nên bạn cần một môi trường staging. Agent không có endpoint chat thì phải thêm vài dòng Python, nên người hoàn toàn không biết code sẽ cần trợ lý lập trình hoặc nhờ người giúp.

Nếu bạn chỉ cần lọc nội dung độc hại đơn giản, hoặc cần một bài kiểm thử bảo mật hạ tầng truyền thống, thì iFixAi không phải công cụ thay thế phù hợp: nó tập trung vào việc agent có làm đúng vai trò, đúng quyền và đúng chính sách của doanh nghiệp hay không. Nếu bạn đang chuẩn bị đưa một agent vào làm việc thật, thì đây là công cụ đáng chạy thử trước, bắt đầu từ bản demo chỉ mất vài phút.

## 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ở theo giấy phép Apache-2.0, cài bằng pip. Tuy nhiên khi kiểm toán agent thật, giám khảo là một mô hình của nhà cung cấp bên ngoài (OpenAI, Anthropic, Gemini...), nên có thể phát sinh chi phí theo key của bạn. Lệnh --dry-run cho bạn xem số lần gọi trước khi bị tính tiền.

### Chạy thử có cần API key không?

Không. Bản chạy nhanh dùng agent demo với câu trả lời và điểm số dựng sẵn, nên bạn thấy được luồng làm việc mà chưa cần kết nối gì thật. Chỉ khi kiểm toán agent thật bạn mới cần key của giám khảo và token của agent.

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

Được. README có hướng dẫn riêng cho Windows: tạo môi trường ảo bằng py -m venv .venv và kích hoạt bằng .venv\Scripts\activate. Nếu không tìm thấy lệnh ifixai thì dùng python -m ifixai.cli.main.

### Cần cài Python phiên bản nào?

Cần Python 3.10 trở lên, theo cả README lẫn pyproject.toml. README lưu ý python3 mặc định trên Mac là 3.9, nên bạn cần kiểm tra bằng python3 --version trước khi cài.

### Cần GPU hay máy cấu hình mạnh không?

Tư liệu không nói gì về yêu cầu GPU hay cấu hình tối thiểu. Công cụ làm việc bằng cách gửi yêu cầu qua chat tới agent và gọi một mô hình giám khảo, nên mình chưa có thông tin về nhu cầu phần cứng cụ thể.

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

Bạn chọn được: OpenAI, Anthropic, Gemini, Azure, Bedrock, OpenRouter và nhiều nơi khác. iFixAi tự chọn một giám khảo từ các key bạn đã đặt, và không chọn nhà cung cấp của chính agent đang được chấm để tránh agent tự chấm bài mình.

### Thử nghiệm có ảnh hưởng đến hệ thống đang chạy thật không?

Có thể, vì README nói các câu thử là yêu cầu thật gửi tới agent. Vì vậy bạn nên dùng một bản staging thay vì hệ thống đang phục vụ khách hàng.
