Bài 2 — Thiết lập kiến trúc & công cụ

Bài này bạn dựng "bộ xương" cho agent: chọn kênh, chọn LLM, chọn nơi lưu knowledge base, và định nghĩa các công cụ (tools) mà agent được phép gọi. Kiến trúc đúng ngay từ đầu giúp bạn tránh viết lại toàn bộ sau này.

Kiến trúc tham chiếu

 Khách  ──►  Kênh (web chat / Zendesk / Messenger)
                     │  webhook
                     ▼
            ┌──────────────────┐
            │   ORCHESTRATOR   │  (code của bạn)
            │  - nhận message  │
            │  - gọi LLM       │
            │  - gọi tools     │
            └──────────────────┘
              │        │        │
     ┌────────┘        │        └─────────┐
     ▼                 ▼                   ▼
  KB Search       Ticket API          Human Handoff
 (vector DB)   (Zendesk/Freshdesk)   (assign to agent)

Điểm mấu chốt: LLM không tự làm gì cả. Nó chỉ quyết định gọi tool nào. Orchestrator của bạn mới thực thi. Đây là mô hình "tool calling" — an toàn và kiểm soát được.

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

• Chọn kênh khởi điểm. Bắt đầu với MỘT kênh (thường là web chat hoặc Zendesk) để giới hạn phạm vi.
• Chọn LLM. Bất kỳ model hỗ trợ tool calling / function calling đều được. Ưu tiên model rẻ cho phân loại, model mạnh hơn cho tổng hợp câu trả lời.
• Chọn nơi lưu KB. Giai đoạn đầu có thể dùng vector DB nhẹ (ví dụ pgvector, Chroma). Đừng vội mua giải pháp đắt tiền.
• Định nghĩa danh sách tools — bản hợp đồng giữa LLM và hệ thống của bạn.
• Dựng vòng lặp orchestrator nhận message → gọi LLM → thực thi tool → trả kết quả.

Định nghĩa tools (JSON schema)

[
  {
    "name": "search_kb",
    "description": "Tìm trong knowledge base để trả lời câu hỏi tier-1. Luôn gọi TRƯỚC khi trả lời.",
    "parameters": {
      "query": "string - câu hỏi của khách, viết lại rõ ràng"
    }
  },
  {
    "name": "create_ticket",
    "description": "Tạo ticket khi không thể tự trả lời.",
    "parameters": {
      "category": "enum[billing, technical, order, complaint]",
      "priority": "enum[low, normal, high, urgent]",
      "summary": "string"
    }
  },
  {
    "name": "escalate_to_human",
    "description": "Chuyển ngay cho nhân viên khi rủi ro cao hoặc khách yêu cầu.",
    "parameters": {
      "reason": "string",
      "context": "string - tóm tắt hội thoại"
    }
  }
]

Vòng lặp orchestrator (pseudocode)

def handle_message(conversation, user_msg):
    conversation.append(user_msg)
    response = llm.chat(
        messages=conversation,
        tools=TOOLS,
        system=SYSTEM_PROMPT   # sẽ viết ở Bài 4
    )
    if response.tool_call:
        name = response.tool_call.name
        args = response.tool_call.args
        result = TOOL_REGISTRY[name](**args)   # thực thi thật
        conversation.append(tool_result(result))
        return handle_message(conversation, None)  # cho LLM đọc kết quả
    return response.text   # câu trả lời cuối cho khách

Checklist môi trường

• [ ] API key LLM lưu trong biến môi trường, KHÔNG hardcode.
• [ ] Có tài khoản sandbox/test của helpdesk (không dùng thẳng production).
• [ ] Vector DB đã tạo, có sẵn 5–10 bài KB mẫu để thử.
• [ ] Ghi log mỗi lần gọi tool (tên, tham số, kết quả) để debug.
• [ ] Có "kill switch": biến AGENT_ENABLED để tắt agent ngay nếu sự cố.

Sai lầm thường gặp

• Cho LLM quyền gọi API nguy hiểm không giới hạn (ví dụ refund_money). Ở giai đoạn đầu chỉ nên có tools chỉ đọc + tạo ticket + escalate. Hành động động tiền phải qua người duyệt.
• Nhét cả knowledge base vào system prompt. Vừa tốn token, vừa dễ lẫn. Hãy để agent tìm kiếm KB qua tool search_kb.
• Không có kill switch: Khi bot lỗi hàng loạt lúc 2 giờ sáng, bạn không có cách tắt nhanh.
• Triển khai đa kênh ngay từ ngày đầu: Bạn sẽ chết chìm trong khác biệt định dạng. Một kênh trước, ổn rồi mới mở rộng.

Bài 3, ta sẽ xây knowledge base — nguồn sống của khả năng deflect.