Bài 2 — Thiết lập môi trường: dữ liệu, tools và bộ khung agent

Bài này ta dựng nền móng kỹ thuật: chuẩn hóa dữ liệu đầu vào và định nghĩa các tool mà agent sẽ gọi. Nếu nền móng lỏng, mọi bài sau sẽ sụp.

1. Chuẩn hóa dữ liệu đầu vào

Dữ liệu tài chính đến từ nhiều nguồn với định dạng hỗn loạn: CSV sao kê ngân hàng, export Excel từ cổng thanh toán, hóa đơn PDF. Bước đầu tiên luôn là đưa tất cả về một schema chuẩn.

# schema chuẩn cho mọi giao dịch
transaction = {
    "id": "txn_001",
    "date": "2026-06-03",        # ISO 8601
    "amount": -4500000,          # số nguyên (VND), âm = chi
    "currency": "VND",
    "description": "CT TNHH VP MIEN NAM",
    "counterparty": "Văn phòng phẩm Miền Nam",
    "source": "bank_vcb",
    "category": None,            # sẽ điền ở bước phân loại
    "matched": False
}

Quy tắc: lưu số tiền dạng số nguyên (đơn vị đồng), tránh sai số dấu phẩy động của tiền tệ.

2. Định nghĩa các tool nền tảng

Agent không tự đọc file hay tính toán — nó gọi tool. Tool là hàm có mô tả rõ ràng để LLM biết khi nào dùng.

tools = [
  {
    "name": "load_transactions",
    "description": "Đọc file sao kê/sổ, trả về list giao dịch theo schema chuẩn",
    "params": {"path": "str", "source": "str"}
  },
  {
    "name": "match_amount",
    "description": "So khớp tất định 2 danh sách theo số tiền + ngày (± n ngày)",
    "params": {"bank": "list", "ledger": "list", "date_window": "int"}
  },
  {
    "name": "fuzzy_name",
    "description": "Tính độ tương đồng tên đối tác (0..1)",
    "params": {"a": "str", "b": "str"}
  }
]

3. Bộ khung vòng lặp agent

Agent chạy theo vòng lặp: nhận input, LLM quyết gọi tool nào, thực thi tool, đưa kết quả về LLM, lặp đến khi xong.

def run_agent(task, tools, llm):
    messages = [{"role": "user", "content": task}]
    while True:
        resp = llm.chat(messages, tools=tools)
        if resp.tool_calls:
            for call in resp.tool_calls:
                result = execute_tool(call.name, call.args)
                messages.append({"role": "tool", "content": result})
        else:
            return resp.content   # agent kết luận

4. Cấu hình biến môi trường

# .env
LLM_API_KEY=sk-xxx
LLM_MODEL=your-model
DATE_WINDOW=3          # cho phép lệch 3 ngày khi đối soát
FUZZY_THRESHOLD=0.85   # ngưỡng khớp tên
AMOUNT_TOLERANCE=0     # VND lệch cho phép (0 = phải khớp tuyệt đối)

Các bước thiết lập

• Tạo thư mục dự án, cài SDK LLM và thư viện xử lý CSV/Excel.
• Viết hàm load_transactions cho từng nguồn, ánh xạ về schema chuẩn.
• Viết các tool tất định (match_amount, fuzzy_name) bằng code thuần, có unit test.
• Dựng vòng lặp agent và đăng ký tools.
• Chạy thử với 10 giao dịch mẫu, in ra từng lệnh gọi tool để debug.
• Lưu log mọi lời gọi tool phục vụ audit.

Checklist môi trường

• [ ] Mọi nguồn dữ liệu đã map về 1 schema?
• [ ] Số tiền lưu dạng số nguyên?
• [ ] Mỗi tool có mô tả đủ để LLM chọn đúng?
• [ ] Có log lại từng tool call?
• [ ] Cấu hình (ngưỡng, cửa sổ ngày) tách khỏi code?

Sai lầm thường gặp

• Lưu tiền dạng float: 0.1 + 0.2 != 0.3, gây lệch đối soát khó hiểu. Dùng số nguyên hoặc Decimal.
• Nhồi hết logic vào một prompt khổng lồ: khó debug, tốn token, dễ ảo giác. Tách thành tools nhỏ.
• Mô tả tool mơ hồ: LLM gọi sai tool hoặc sai tham số. Viết description như hướng dẫn cho người mới.
• Không log tool call: khi số liệu sai không truy được nguyên nhân. Log ngay từ đầu.

Bài sau ta bắt tay vào nghiệp vụ đầu tiên và cũng nặng nhất: đối soát giao dịch.