Bài 2 — Kiến trúc & thiết lập môi trường cho Agent bán lẻ

Bài này bạn dựng bộ khung chạy được: một agent kết nối LLM, gọi được tool giả lập tồn kho/đơn hàng. Mục tiêu là có "xương sống" để các bài sau cắm thêm tính năng.

Kiến trúc tổng thể

[Kênh chat: Web/Zalo/Messenger]
        │
   [Agent Orchestrator]  ← LLM + vòng lặp tool-calling
        │
  ┌─────┼───────────┬──────────────┐
[Catalog] [Inventory] [Orders/Returns] [Shipping]
  API       API          API            API
        │
   [Memory: hội thoại + hồ sơ khách]

Orchestrator là trung tâm: nhận tin nhắn, hỏi LLM "cần gọi tool nào", thực thi tool, đưa kết quả lại cho LLM, lặp đến khi có câu trả lời cuối.

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

• Tạo project và biến môi trường. Không hardcode API key.
• Định nghĩa tool bằng JSON schema để LLM biết gọi thế nào.
• Viết vòng lặp orchestrator xử lý tool-calling.
• Chạy thử với tool giả lập (dữ liệu cứng) trước khi nối API thật.

Bước 1 — Cấu hình

# .env
LLM_API_KEY=sk-...
LLM_MODEL=your-model
SHOP_API_BASE=https://shop.example.com/api

Bước 2 — Khai báo tool

{
  "name": "get_stock",
  "description": "Tra số lượng tồn của một SKU",
  "parameters": {
    "type": "object",
    "properties": {
      "sku": { "type": "string", "description": "Mã SKU sản phẩm" }
    },
    "required": ["sku"]
  }
}

Bước 3 — Vòng lặp orchestrator (pseudocode)

def run_agent(user_msg, history):
    messages = history + [{"role": "user", "content": user_msg}]
    for _ in range(5):  # tối đa 5 vòng tool để tránh lặp vô hạn
        resp = llm.chat(messages, tools=TOOLS)
        if resp.tool_calls:
            for call in resp.tool_calls:
                result = TOOL_IMPL[call.name](**call.args)
                messages.append(tool_result(call.id, result))
        else:
            return resp.content  # câu trả lời cuối
    return "Xin lỗi, để mình chuyển bạn cho nhân viên nhé."

Bước 4 — Tool giả lập để test

STOCK = {"SHIRT-BLACK-L": 12, "SHIRT-WHITE-M": 0}
def get_stock(sku):
    return {"sku": sku, "qty": STOCK.get(sku, 0)}

Khung tư duy: 3 tầng tách biệt

Luôn tách 3 tầng để dễ bảo trì:

• Tầng LLM/prompt — chỉ lo hiểu ý và diễn đạt.
• Tầng tool — chỉ lo gọi API, không chứa "trí thông minh".
• Tầng dữ liệu — nền tảng shop thật (Shopify/Woo/KiotViet).

Khi đổi nền tảng shop, bạn chỉ sửa tầng tool, không đụng prompt.

Checklist môi trường

• [ ] Key nằm trong biến môi trường, không commit lên git.
• [ ] Mỗi tool có description rõ để LLM chọn đúng.
• [ ] Có giới hạn số vòng lặp tool (tránh cháy token).
• [ ] Log lại mọi tool call (tên + tham số + kết quả) để debug.
• [ ] Có tool giả lập cho môi trường dev, tách khỏi API thật.

Sai lầm thường gặp

• Nối thẳng API thật lúc dev. Một agent lỗi có thể tạo 50 đơn rác. Dùng sandbox/giả lập trước.
• Không giới hạn vòng lặp. LLM có thể gọi tool lặp mãi, đốt token và treo hội thoại.
• Nhồi mọi logic vào prompt. Việc tính phí ship nên nằm ở tool/code, không bắt LLM tự nhẩm — nó sẽ sai số.
• Description tool viết mơ hồ. Nếu mô tả không rõ, LLM gọi nhầm tool hoặc bịa tham số.
• Quên logging. Không có log thì không thể biết agent trả lời sai vì hiểu sai ý hay vì tool trả sai dữ liệu.

Sau bài này bạn có một agent chạy được cục bộ, gọi được get_stock giả lập. Bài 3 sẽ cắm tính năng đầu tiên có giá trị kinh doanh: tự động sinh mô tả sản phẩm.