Bài 2 — Thiết lập môi trường, CRM và tools

Bài này bạn dựng "bộ khung" để agent có thể chạy: khóa API, CRM, và định nghĩa tool theo chuẩn function-calling. Không có tools tốt thì LLM giỏi mấy cũng vô dụng.

1. Chuẩn bị tài khoản và khóa

• LLM: một API hỗ trợ tool/function calling (ví dụ Claude, hoặc bất kỳ model nào có tool use). Lấy API_KEY.
• CRM: HubSpot (free tier) là lựa chọn tốt để học vì có Private App token. Tạo Private App → cấp scope crm.objects.contacts.read/write, crm.objects.deals.read/write.
• Enrichment/Search: một search API (Serper/Brave/Tavily) để research.
• Lưu tất cả vào biến môi trường, không hardcode.

export LLM_API_KEY="sk-..."
export HUBSPOT_TOKEN="pat-na1-..."
export SEARCH_API_KEY="..."

2. Định nghĩa tool theo JSON schema

Agent chỉ gọi được tool nếu bạn mô tả rõ ràng. Mỗi tool cần: tên, mô tả (LLM đọc để quyết định), và schema tham số.

{
  "name": "enrich_company",
  "description": "Tra cứu thông tin công ty từ tên hoặc domain: industry, quy mô, tin tức gần đây. Dùng khi cần hiểu bối cảnh lead trước khi viết outreach.",
  "input_schema": {
    "type": "object",
    "properties": {
      "domain": {"type": "string", "description": "domain website, vd abcfoods.vn"},
      "company_name": {"type": "string"}
    },
    "required": ["company_name"]
  }
}

3. Bọc CRM thành tool

Viết hai hàm mỏng bọc quanh API CRM, rồi khai báo cho agent:

def crm_upsert_contact(email, firstname, company, note):
    # gọi HubSpot API, trả về contact_id
    resp = hubspot.crm.contacts.basic_api.create(...)
    return {"contact_id": resp.id}

def crm_log_activity(contact_id, activity_type, body):
    # tạo engagement/note gắn với contact
    ...
    return {"ok": True}

Nguyên tắc: tool trả về dữ liệu có cấu trúc (dict/JSON), không trả chuỗi tự do, để bước sau parse được.

4. Kiểm thử từng tool riêng lẻ

Trước khi ghép vào agent, gọi tay từng tool với dữ liệu thật:

• enrich_company({"company_name":"ABC Foods","domain":"abcfoods.vn"}) → kiểm tra ra industry đúng.
• crm_upsert_contact(...) với email test → mở HubSpot xem contact có xuất hiện.
• crm_log_activity(...) → xem note gắn đúng contact.

Nếu tool lỗi ở bước này, đừng đổ lỗi cho LLM sau đó.

Khung tư duy: tool phải "idempotent"

Mỗi tool nên an toàn khi gọi lại. crm_upsert_contact phải update nếu email đã tồn tại, không tạo trùng. Vì agent có thể retry, tool không idempotent sẽ sinh rác. Quy tắc: tìm-trước-ghi-sau (find-or-create).

Checklist thiết lập

• [ ] API key nằm trong env var, không trong code.
• [ ] Mỗi tool có description đủ để LLM biết KHI NÀO dùng.
• [ ] Tool trả JSON có cấu trúc.
• [ ] CRM write là upsert (idempotent).
• [ ] Đã test tay từng tool với dữ liệu thật, thành công.
• [ ] Có tài khoản/sandbox CRM riêng để không làm bẩn data thật.

Ví dụ mô tả tool tốt vs tệ

• Tệ: "description": "tìm công ty" → LLM không biết khi nào dùng, dùng bừa.
• Tốt: "Dùng khi đã có tên/domain công ty và cần industry + tin tức để cá nhân hóa. KHÔNG dùng để tìm email cá nhân."

Sai lầm thường gặp

• Ghi thẳng vào CRM production khi đang học: tạo hàng trăm contact rác. Dùng sandbox/pipeline test.
• Mô tả tool mơ hồ: agent gọi sai tool hoặc bỏ qua tool cần dùng.
• Tool trả text tự do: bước sau không parse được, phải nhờ LLM parse lại → tốn token, dễ sai.
• Không xử lý rate limit của CRM/search API: agent chạy batch bị 429, mất dữ liệu. Thêm retry + backoff.
• Cấp scope CRM quá rộng: rủi ro bảo mật. Chỉ cấp read/write đúng object cần.