iFixAi: kiểm toán AI agent xem có làm đúng việc — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về ifixai-ai/iFixAi — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: 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 →

Tóm tắt nhanh
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.
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.
ifixai-ai/iFixAi
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ể.
I.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:
- B01chỉ cho mỗi vai trò dùng đúng những công cụ được phép.
- B08không để người dùng nói khéo mà lấy được nhiều quyền hơn mức họ có.
- P01không chạy hành động phá hủy cho người không đủ quyền.
- B12chống tấn công chèn lệnh (prompt injection).
- B09phát hiện và chặn yêu cầu vi phạm chính sách của bạn.
- B27không đưa dữ liệu riêng của người này cho người khác.
- B06nói "tôi không chắc" thay vì đoán bừa với giọng tự tin.
- B16báo lỗi thay vì giả vờ đã làm xong.
- B18bám đúng nhiệm vụ được giao.
- B20là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.
II.Cần chuẩn bị gì
Theo README và pyproject.toml, bạn cần:
- Python 3.10 trở lên. README lưu ý
python3mặ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.
III.Cài đặt từng bước
- Kiểm tra PythonGõ python3 --version, cần 3.10 trở lên
- Tạo môi trường ảoTạo .venv và kích hoạt nó
- Cài gói ifixaiDùng pip install ifixai
- Tạo và kiểm tra môi trường mô phỏngChạy ifixai author rồi ifixai validate
- Chạy bản demoChạy ifixai run với --provider mock
A.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õ:
python3 --versionNế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.
B.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:
python3 -m venv .venv && source .venv/bin/activateTrên Windows:
py -m venv .venv
.venv\Scripts\activateKí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.Cài gói ifixai
pip install ifixaiLệ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.Dựng và kiểm tra môi trường mô phỏng mẫu
ifixai author reference -o reference.yaml
ifixai validate reference.yamlLệ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.
E.Chạy bản demo
ifixai run --provider mock --eval-mode self --fixture reference.yamlLệ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ế:
python -m ifixai.cli.mainIV.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.
V.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
A.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-communitySau đó 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.
B.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:
uvx ifixai install --agents cursorSau đó 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.
C.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:
pip install "ifixai[openai]"
ifixai author my-agent.json -o my-agent.yaml
ifixai validate my-agent.yamlRồ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:
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.
D.Độ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 đó):
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-runPhầ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.
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.
VI.Lỗi hay gặp và cách xử lý
A.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.
B.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 đó.
C.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.
D.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.
E.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.
VII.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.


