Bài 3 — Thiết lập môi trường: tool, bộ nhớ và kết nối dữ liệu

Agent chỉ mạnh khi được cắm đúng "dây"

Một đội agent giỏi cần 3 nền tảng kỹ thuật: tools (để hành động), memory (để nhớ ngữ cảnh), và kết nối dữ liệu (để biết sự thật). Bài này hướng dẫn thiết lập cả ba một cách gọn gàng, dùng chung cho cả đội.

1. Định nghĩa tool theo chuẩn function-calling

Mỗi tool là một hàm có schema rõ ràng để agent biết cách gọi:

{
  "name": "get_order",
  "description": "Lấy thông tin đơn hàng theo mã đơn",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "description": "Mã đơn, ví dụ VN12345" }
    },
    "required": ["order_id"]
  }
}

Mô tả (description) là thứ agent đọc để quyết định gọi tool nào — viết rõ ràng như hướng dẫn cho người mới.

2. Phân tầng bộ nhớ (memory)

Đội agent cần 3 tầng nhớ, đừng gộp làm một:

• Short-term (hội thoại hiện tại): lịch sử tin nhắn của phiên. Xóa khi phiên kết thúc.
• Shared scratchpad (bộ nhớ đội): nơi các agent ghi kết quả trung gian cho nhau đọc trong cùng một task.
• Long-term (kiến thức lâu dài): hồ sơ khách hàng, chính sách công ty — thường để trong vector DB hoặc DB truyền thống, truy cập qua tool.

3. Kết nối dữ liệu qua RAG khi cần

Với kiến thức tĩnh (chính sách, FAQ), dùng retrieval thay vì nhồi hết vào prompt:

def search_policy(query: str) -> str:
    # 1. Nhúng câu hỏi thành vector
    q_vec = embed(query)
    # 2. Tìm 3 đoạn chính sách gần nhất
    chunks = vector_db.search(q_vec, top_k=3)
    # 3. Trả về cho agent làm ngữ cảnh
    return "\n---\n".join(chunks)

Tool ghi dữ liệu vs tool đọc dữ liệu

Phân biệt rõ hai loại tool vì chúng có mức rủi ro khác hẳn nhau:

• Tool đọc (read): get_order, search_policy — an toàn, chạy tự do được. Sai cùng lắm là trả nhầm thông tin, dễ phát hiện.
• Tool ghi (write): create_refund, send_email, update_customer — nguy hiểm, không hoàn tác được. Mỗi tool ghi PHẢI kèm validate đầu vào chặt và guardrail hạn mức, và nên có log riêng để audit.

Một mẹo thực chiến: đặt tên tool ghi có tiền tố rõ ràng (ví dụ write_, create_, delete_) để khi review code và log, bạn nhận ra ngay các hành động cần soi kỹ. Nhiều sự cố hoàn tiền nhầm đến từ việc một tool ghi bị đối xử như tool đọc — không validate, không guardrail.

Chia sẻ scratchpad đúng cách

Shared scratchpad rất mạnh nhưng dễ bị lạm dụng. Nguyên tắc: chỉ ghi vào scratchpad những kết quả mà agent KHÁC thực sự cần đọc (ví dụ order_agent ghi trạng thái đơn để refund_agent dùng). Đừng ghi mọi suy nghĩ trung gian vào đó, nếu không scratchpad phình to, tốn token và gây nhiễu cho các agent đọc sau.

Các bước thiết lập môi trường

• Liệt kê mọi hành động agent cần làm → biến mỗi hành động thành 1 tool có schema.
• Với mỗi tool, viết description rõ và validate tham số đầu vào.
• Quyết định tool nào ghi dữ liệu (nguy hiểm) → gắn xác nhận hoặc guardrail.
• Thiết kế 3 tầng memory; định nghĩa cái gì được chia sẻ giữa agent.
• Đưa kiến thức tĩnh vào vector DB, tạo tool search_* để truy cập.
• Ghi log mọi lời gọi tool (input/output) để phục vụ debug ở Bài 7.

Checklist môi trường sẵn sàng

• [ ] Mọi tool có schema + description + validate input
• [ ] Tool ghi dữ liệu đã có guardrail/xác nhận
• [ ] Đã tách 3 tầng memory
• [ ] Kiến thức tĩnh nằm trong retrieval, không nhồi prompt
• [ ] Mọi lời gọi tool đều được log

Sai lầm thường gặp

• Description tool sơ sài: "lấy đơn" → agent gọi sai hoặc bịa tham số. Description càng rõ, agent càng gọi đúng.
• Gộp mọi memory làm một: nhồi cả hồ sơ khách + lịch sử chat + chính sách vào một context → tốn token, dễ nhiễu, chậm.
• Nhồi toàn bộ tài liệu vào prompt: vượt giới hạn context và tốn tiền; dùng RAG cho kiến thức tĩnh.
• Không validate input tool: agent truyền order_id rỗng → API lỗi, agent bối rối. Luôn kiểm tra tham số.
• Quên log: khi đội chạy sai, không có dấu vết để lần ra agent/tool nào gây lỗi.