Bài 2 — Thiết lập môi trường: model, tool và bộ khung agent

Bài này bạn sẽ dựng bộ khung tối thiểu để chạy một marketing agent thật. Chúng ta ưu tiên đơn giản, chạy được ngay, không sa đà framework nặng.

Chọn model

Với marketing, bạn cần model giỏi viết tiếng Việt tự nhiên và gọi tool ổn định (function calling). Nguyên tắc chọn:

• Bài viết dài, đòi hỏi giọng văn thương hiệu → model mạnh nhất bạn chi trả nổi.
• Tác vụ phân loại/trích xuất (gắn nhãn từ khóa, tóm tắt số liệu) → model nhỏ, rẻ, nhanh là đủ.
• Chiến lược 2 tầng: dùng model rẻ để nháp/phân loại, model mạnh để viết bản cuối. Tiết kiệm 60–80% chi phí.

Các thành phần bắt buộc của một agent

• Model — bộ não sinh quyết định.
• System prompt — vai trò, giọng văn thương hiệu, ràng buộc.
• Tools — hàm agent gọi để lấy dữ liệu / hành động.
• Loop — vòng lặp: gọi model → nếu model muốn gọi tool thì chạy tool → đưa kết quả lại cho model → lặp.
• Memory/State — lưu ngữ cảnh (brand guideline, lịch sử bài đã đăng).

Cấu hình mẫu

import os, json
from openai import OpenAI  # hoặc SDK model bạn dùng

client = OpenAI(api_key=os.environ["API_KEY"])

SYSTEM = """Bạn là marketing agent của thương hiệu skincare 'Lụa'.
Giọng văn: gần gũi, tin cậy, KHÔNG hứa hẹn quá mức về hiệu quả.
Luôn chèn từ khóa tự nhiên. KHÔNG tự publish, chỉ tạo draft."""

tools = [{
  "type": "function",
  "function": {
    "name": "get_keyword_data",
    "description": "Lấy volume và độ khó cho một chủ đề",
    "parameters": {
      "type": "object",
      "properties": {"topic": {"type": "string"}},
      "required": ["topic"]
    }
  }
}]

def run_agent(goal, max_steps=6):
    msgs = [{"role":"system","content":SYSTEM},
            {"role":"user","content":goal}]
    for _ in range(max_steps):
        r = client.chat.completions.create(
            model="gpt-4o-mini", messages=msgs, tools=tools)
        m = r.choices[0].message
        if not m.tool_calls:
            return m.content            # agent xong
        for call in m.tool_calls:
            result = dispatch(call)      # chạy tool thật
            msgs.append(m)
            msgs.append({"role":"tool",
                         "tool_call_id":call.id,
                         "content":json.dumps(result)})
    return "Đạt giới hạn bước"

Hai chi tiết an toàn quan trọng: max_steps chặn vòng lặp vô tận (rất hay gặp và rất tốn tiền), và dispatch là nơi bạn kiểm soát tool nào được phép chạy. Hãy coi dispatch như một cổng kiểm soát: mỗi tool phải khai báo rõ ràng, và bạn có thể chèn kiểm tra quyền, ghi log, hoặc chặn hành động rủi ro ngay tại đây trước khi nó thực sự chạy.

Chọn framework hay tự viết loop?

Có nhiều framework agent (LangChain, LlamaIndex, CrewAI...) nhưng với marketing agent giai đoạn đầu, tự viết một loop khoảng 30 dòng như trên thường tốt hơn. Lý do: bạn hiểu rõ từng bước, dễ debug, không bị khóa vào abstraction của framework. Chỉ chuyển sang framework khi bạn cần các tính năng phức tạp như quản lý nhiều agent song song hay bộ nhớ vector. Nguyên tắc: đừng thêm phụ thuộc khi chưa có nhu cầu thật.

Thiết kế tool tốt

Chất lượng agent phụ thuộc rất nhiều vào chất lượng mô tả tool. Một tool tốt cần: tên rõ nghĩa, description nói rõ khi nào dùng, và tham số tối thiểu. Ví dụ mô tả kém: "lấy dữ liệu". Mô tả tốt: "Lấy volume tìm kiếm và độ khó SEO cho một chủ đề, dùng khi cần chọn từ khóa trước khi viết bài". Model dựa vào chính những mô tả này để quyết định gọi tool nào, nên đầu tư viết chúng cẩn thận sẽ tiết kiệm nhiều lần thử-sai về sau.

Quản lý bí mật (secrets)

• Không hardcode API key trong code.
• Dùng biến môi trường (.env) và thêm .env vào .gitignore.
• Tách key theo môi trường: dev / prod riêng.
• Đặt giới hạn chi tiêu (spend limit) trên dashboard nhà cung cấp model.

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

• Tạo API key, đặt spend limit thấp để thử nghiệm.
• Cài SDK model + thư viện HTTP.
• Viết system prompt chứa brand guideline (giọng, điều cấm).
• Định nghĩa 1–2 tool đầu tiên (bắt đầu bằng tool đọc, chưa cần tool ghi).
• Viết loop có max_steps.
• Chạy thử với một goal nhỏ, đọc log từng bước.

Checklist môi trường

• [ ] API key trong biến môi trường, không lên git
• [ ] Spend limit đã đặt
• [ ] max_steps có trong loop
• [ ] Log ra từng tool call để debug
• [ ] System prompt có giọng thương hiệu + điều cấm

Sai lầm thường gặp

• Không giới hạn bước lặp: agent kẹt vòng lặp gọi tool liên tục → hóa đơn tăng vọt.
• Cho quyền ghi/publish ngay từ tool đầu tiên: hãy bắt đầu bằng tool chỉ-đọc để quan sát hành vi an toàn.
• Nhồi cả brand guideline dài vào mỗi tin nhắn: tốn token và làm loãng. Đưa vào system prompt hoặc memory có cấu trúc.
• Chọn model đắt cho mọi bước: phân loại/nháp nên dùng model rẻ; chỉ bản cuối mới cần model mạnh.

Giờ bạn đã có bộ khung chạy được. Bài 3 sẽ biến nó thành một content generation agent thực thụ với kiểm soát chất lượng.