AI Agent Roadmap: Kiểm thử Agent AI – Unit, Tích hợp và Con người trong Vòng lặp

Agent hiếm khi hỏng ở chỗ bạn nghĩ. Nó hỏng theo hai kiểu: tool trả về thứ khác hợp đồng, hoặc model gọi đúng tool nhưng sai thứ tự, sai tham số, hoặc gọi lại lần hai. Unit test bắt kiểu thứ nhất. Trajectory test bắt kiểu thứ hai. Không tầng nào bắt được cả hai, và đó là lý do chiến lược kiểm thử agent phải có nhiều tầng chứ không phải một file test dài.

Bài này đi từ tầng rẻ nhất (hàm Python thuần) lên tầng đắt nhất (người duyệt thật), kèm cách giữ chi phí CI ở mức bạn trả được hàng ngày.

Cập nhật 2026: bốn thay đổi ảnh hưởng trực tiếp đến test

  • Tool calling đã đổi hình dạng. Với GPT-6 Astra và Sol, tool calling chỉ chạy qua Responses API; Chat Completions không tool-call được trừ khi reasoning_effort là none. Nghĩa là fixture ghi từ Chat Completions có thể không đại diện cho đường chạy thật — và test “xanh” trên sai API là test vô dụng.
  • MCP 2026-07-28 là stateless. Không còn initialize, không còn Mcp-Session-Id; mỗi request mang protocolVersion và capabilities trong _meta. Contract test cũ — gọi initialize rồi tái sử dụng session — sẽ fail trên server mới, và ngược lại.
  • Primitive cho human-in-the-loop đã thành API thật. LangGraph có interrupt/Command(resume=...), Microsoft Agent Framework có request_info/response_handler, OpenAI Agents có tool approval + RunState serialize được, CrewAI có cờ human_input trên task. Có API thì có thể test bằng assertion, không cần “kiểm tra thủ công”.
  • Chi phí test là chi phí thật. Reasoning token bị tính như output. Gemini 3.8 Flash ở mức $0,75/$3,75 mỗi 1M token (giá khuyến mại đến 2026-12-31) là lựa chọn hợp lý cho test; GPT-6 Luna ($0,10/$0,50) rẻ hơn cho phân loại hàng loạt. Batch giảm khoảng 50% nhưng là async — hợp với nightly, không hợp với PR gate.

Kiểm thử Agent AI theo bốn tầng, bốn mục tiêu

Tầng Kiểm cái gì Chạy ở đâu
Unit tool Hàm tool, schema, xử lý lỗi, timeout, idempotency — không có LLM Mỗi commit, dưới 2 giây
Contract Tool/API/MCP có còn khớp hợp đồng mà agent giả định Mỗi PR và nightly (live)
Trajectory Chuỗi tool call, thứ tự, ngân sách bước, câu trả lời cuối Mỗi PR với fixture; nightly với model thật
HITL Cổng duyệt chặn/cho qua đúng, resume đúng tham số, có log PR (fixture) và trước release (người thật)

Nguyên tắc phân tầng: mỗi tầng chỉ được phép phụ thuộc vào tầng dưới. Nếu unit test của bạn cần gọi model, nó không còn là unit test — nó là integration test đội lốt, và nó sẽ làm PR gate chậm, đắt, và flaky cùng lúc.

Tầng 1: tool là code, hãy test như code

Tool là nơi dễ test nhất và cũng là nơi lỗi production hay nằm nhất: parse tham số, gọi HTTP, map lỗi, cắt kết quả quá dài. Ba nhóm test bắt buộc: happy path, lỗi có thể xảy ra (404, 429, timeout), và biên dữ liệu (chuỗi rỗng, danh sách 10.000 phần tử, ký tự lạ).

# File: tests/test_tools.py
# pytest + httpx.MockTransport: không gọi mạng, không cần API key
import httpx, pytest
from app.tools import lookup_order

def make_client(handler):
    return httpx.Client(transport=httpx.MockTransport(handler))

def test_lookup_order_happy_path():
    def handler(request):
        assert request.url.path == "/orders/EV-1234"
        return httpx.Response(200, json={"id": "EV-1234", "status": "shipping"})

    with make_client(handler) as client:
        assert lookup_order("EV-1234", client=client)["status"] == "shipping"

def test_lookup_order_maps_404_to_domain_error():
    def handler(request):
        return httpx.Response(404, json={"error": "not_found"})

    with make_client(handler) as client:
        with pytest.raises(OrderNotFound):
            lookup_order("EV-9999", client=client)

Hai chi tiết nhỏ nhưng quan trọng. Thứ nhất, tool nên nhận client hoặc cấu hình qua tham số, không tự tạo client toàn cục — nếu không bạn phải monkeypatch toàn bộ module. Thứ hai, hãy test cả hình dạng kết quả trả về cho model: nếu tool trả JSON 20KB, model sẽ đọc phần đầu và bỏ phần sau. Một test khẳng định “output luôn dưới 2.000 ký tự” rẻ hơn nhiều so với việc chẩn đoán một câu trả lời thiếu dữ kiện.

Đừng quên test idempotency ở tầng này. Nếu tool tạo bản ghi, gọi hai lần với cùng một task_id phải cho cùng kết quả, không tạo bản ghi thứ hai. Đây là test rẻ nhất để chặn loại lỗi đắt nhất: retry tự động của framework nhân đôi side effect.

Tầng 2: contract test — thứ âm thầm hỏng sau khi deploy

Contract test trả lời một câu: “API/tool/MCP server còn đúng như agent giả định không?”. Nó không kiểm tra logic của bạn, nó kiểm tra thế giới bên ngoài. Ba hợp đồng cần khoá:

  • Schema tool. Tên tham số, kiểu, trường bắt buộc. Provider đổi cách mô tả JSON Schema là model bắt đầu gọi sai — test này bắt được ngay.
  • Hình dạng response. Không chỉ 200 OK: trường nào luôn có, trường nào có thể null, đơn vị thời gian là giây hay mili giây.
  • MCP. Danh sách tool server công bố, kiểu tham số, và hành vi với request thiếu session. Với spec 2026-07-28, hãy khẳng định server trả lời được khi client không gửi Mcp-Session-Id.

Cách viết thực dụng: gọi thật, assert ít, chạy nightly. Đừng assert toàn bộ payload — bạn sẽ phải sửa test mỗi lần provider thêm trường. Chỉ assert những gì agent thực sự đọc.

Tầng 3: trajectory test — kiểm tra đường đi, không chỉ đích

Đây là tầng đặc trưng của agent và cũng là tầng bị bỏ qua nhiều nhất. Câu trả lời cuối có thể đúng trong khi đường đi sai: gọi tool tìm kiếm 6 lần, đọc nhầm tài liệu, rồi may mắn trả lời đúng. Lần sau nó sẽ sai.

Trajectory test khẳng định ba thứ: tool nào được gọi, theo thứ tự nào, và dừng trong bao nhiêu bước. Cách rẻ nhất là thay model bằng một stub trả về kịch bản cố định — LangChain có sẵn model giả cho việc này.

# File: tests/test_trajectory.py
# Fixture: model trả lời theo kịch bản, không gọi API, không tốn token
from langchain_core.messages import AIMessage
from langchain_core.language_models.fake_chat_models import FakeMessagesListChatModel

class ScriptedModel(FakeMessagesListChatModel):
    """Model giả: trả lần lượt các message trong danh sách đã chuẩn bị."""

def test_agent_calls_status_before_refund(agent, recorded_tool_calls):
    model = ScriptedModel(responses=[
        AIMessage(content="", tool_calls=[
            {"name": "get_order_status", "args": {"order_id": "EV-1234"}, "id": "c1"}
        ]),
        AIMessage(content="Đơn đang giao, chưa thể hoàn tiền."),
    ])
    result = agent.invoke({"messages": [{"role": "user", "content": "Hoàn tiền đơn EV-1234"}]},
                          config={"configurable": {"thread_id": "t-1"}})

    assert [c["name"] for c in recorded_tool_calls] == ["get_order_status"]
    assert result["messages"][-1].content.startswith("Đơn đang giao")

Với hệ có nhiều bước, thêm hai assertion mang tính hợp đồng: tổng số bước không vượt ngân sách (ví dụ 8), và không có tool nằm trong danh sách cấm (xoá dữ liệu, chuyển tiền). Đây là test chống hồi quy tốt nhất khi bạn đổi prompt: hành vi đường đi thường đổi trước khi chất lượng câu trả lời đổi.

Một lưu ý về stub: FakeMessagesListChatModel nhận message thật, không nhận tool call dạng dict của provider khác. Nếu bạn dùng nhiều provider, hãy viết một lớp adapter nhỏ trong test để chuẩn hoá, thay vì rải điều kiện if provider == ... khắp nơi.

Recorded fixtures hay gọi live?

Loại Dùng cho Rủi ro
Fixture ghi sẵn (VCR/respx/JSON) Unit, trajectory, HITL — chạy mỗi PR Lệch dần khỏi hành vi thật; phải refresh theo lịch
Live, model rẻ Smoke nightly, kiểm tra prompt mới Flaky do sampling; tốn tiền; rate limit
Live, model thật Trước release, đo chất lượng Đắt; không chặn được PR

Quy tắc: fixture là mặc định cho CI, live là ngoại lệ có ngân sách. Nhưng fixture phải được làm mới có kiểm soát — mỗi tuần một lần, hoặc mỗi khi provider đổi phiên bản API, và diff phải được review như code. Fixture cũ không refresh là nguồn gốc của niềm tin sai.

Tầng 4: test cổng duyệt của con người

Phần lớn team test “agent có gọi tool không”, rồi để cổng duyệt cho QA thử tay. Cổng duyệt là logic, nên nó cần test tự động. Năm trường hợp tối thiểu:

  • Chặn đúng: hành động không thể hoàn tác không được chạy trước khi có quyết định duyệt.
  • Cho qua đúng: sau khi resume, tool được gọi với đúng tham số đã duyệt — không phải tham số model tự đổi sau đó.
  • Từ chối: người duyệt nói “không” thì không có side effect nào xảy ra.
  • Sửa tham số: người duyệt giảm số tiền từ 5 triệu xuống 2 triệu; tool phải nhận 2 triệu.
  • Replay: resume hai lần cùng một quyết định không được tạo hai giao dịch. Phê duyệt không phải idempotency key — bạn cần khoá riêng.

Với LangGraph, các test này chạy được hoàn toàn offline: gọi agent đến interrupt, kiểm tra state đã checkpoint, rồi resume bằng Command(resume={...}). Không cần model thật nếu bạn dùng stub ở tầng trajectory. Với CrewAI, cờ human_input chặn ở ranh giới task — test bằng cách chạy crew với input giả và khẳng định task sau không chạy.

Cuối cùng, kiểm tra log: mỗi quyết định duyệt phải ghi ai duyệt, tham số gì, lúc nào, kết quả gì. Không có log thì không có audit, và không có audit thì không qua được review bảo mật.

Non-determinism: đừng cố làm nó biến mất

temperature=0 không đảm bảo đầu ra giống hệt giữa hai lần chạy. Seed cũng không: phần lớn API không cam kết tái lập tuyệt đối, và batching trên GPU làm thay đổi thứ tự tính toán. Vậy nên đừng viết test so sánh chuỗi ký tự. Hãy kiểm tra thuộc tính:

  • Bất biến (invariant): câu trả lời phải chứa mã đơn hàng, phải nằm dưới 500 từ, không được chứa giá trị ngoài tập cho phép.
  • Cấu trúc: output parse được theo schema, tool call có đủ trường bắt buộc.
  • Ngân sách: số bước ≤ N, token ≤ M, thời gian ≤ T. Vượt ngân sách là fail, kể cả khi câu trả lời đẹp.
  • Ổn định: chạy cùng case 5 lần, đếm tỷ lệ pass. Với k lần và c lần đúng, pass@k = 1 - C(n-c,k)/C(n,k). Một case pass 3/5 là tín hiệu xấu, không phải “may mắn”.

Về retry: chỉ retry lỗi có khả năng tạm thời (429, 5xx, timeout), dùng exponential backoff có jitter, có trần số lần. Không retry 400/401/403 — đó là lỗi hợp đồng, retry chỉ làm chậm phát hiện. Và hãy test chính sách retry đó: một test khẳng định 429 được thử lại 2 lần rồi bỏ, một test khẳng định 401 không được thử lại.

Về chi phí: một suite 500 case, mỗi case 1.500 token vào và 300 token ra, chạy trên Gemini 3.8 Flash, tốn khoảng 500 × (1.500 × 0,75 + 300 × 3,75)/1.000.000 ≈ 1,1 USD mỗi lần. Nghe rẻ, nhưng nếu reasoning token gấp ba lần output và bạn chạy 20 lần một ngày trên 6 nhánh, con số thành vài trăm USD mỗi tháng — đủ để phải đặt ngân sách cho CI chứ không chỉ cho production.

Chiến lược CI: ba vòng, ba ngân sách

  1. Vòng PR (dưới 5 phút, 0 USD): unit tool, contract với fixture, trajectory với stub, HITL offline. Fail thì chặn merge.
  2. Vòng nightly: contract live, trajectory live trên 20–50 case đại diện, so sánh với baseline. Có ngân sách token/tháng và alert khi vượt.
  3. Vòng trước release: chạy bộ eval đầy đủ, một phiên HITL với người thật trên các case rủi ro cao, review diff trace của 10 case tệ nhất.

Đừng để test flaky tồn tại lâu: gắn nhãn, đưa ra khỏi gate, mở ticket. Một suite agent có 5% test flaky sẽ bị team bỏ qua hoàn toàn trong vòng hai tuần.

Cạm bẫy

Assert câu trả lời cuối bằng chuỗi cứng. Nó sẽ đỏ mỗi lần model đổi cách diễn đạt, và bạn sẽ học cách bỏ qua màu đỏ.

Mock chính thứ cần test. Mock tool rồi khẳng định agent gọi tool đúng là test phần dễ; phần khó là tool thật xử lý dữ liệu bẩn. Hai thứ cần test riêng, không thay thế nhau.

Đo coverage như thước đo chất lượng. 90% coverage trên code agent không nói gì về việc agent có dừng đúng lúc hay không.

Để test gọi model thật trong unit tier. Một lần refactor là 40 USD, và không ai dám chạy test nữa.

Checklist

  • Mỗi tool có test happy path, lỗi map đúng, timeout, và idempotency.
  • Mỗi agent có ít nhất 5 trajectory test: 1 happy path, 2 lỗi tool, 1 vượt ngân sách, 1 case từ chối.
  • Fixture có ngày ghi và lịch refresh; diff fixture được review.
  • Cổng duyệt có 5 test: chặn, cho qua, từ chối, sửa tham số, replay.
  • CI có trần chi phí theo tháng và alert khi vượt 80%.

Để nối tiếp: bài LangChain, CrewAI và AutoGen giải thích các primitive bạn đang test; bài đánh giá agent bằng LangSmith, Ragas và DeepEval là tầng tiếp theo — đo chất lượng thay vì chỉ khẳng định hành vi; và bài bảo mật agent AI cho bạn danh sách case tấn công nên đưa vào suite.