Bài 3 — Thiết lập môi trường: API key, SDK, và dự án agent đầu tiên

Bài này bạn dựng môi trường làm việc chuẩn nghề và viết agent tool-calling đầu tiên. Làm đúng một lần, dùng cho cả sự nghiệp.

Bước 1 — Chuẩn bị công cụ

• Cài Python 3.11+ (hoặc Node 20+).
• Cài VS Code + extension Python.
• Tạo tài khoản LLM: OpenAI hoặc Anthropic. Nạp tối thiểu (5-10 USD là dư cho học tập).
• Cài Git, tạo tài khoản GitHub.

Bước 2 — Tạo dự án và virtualenv

mkdir first-agent && cd first-agent
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install openai python-dotenv

Bước 3 — Quản lý API key AN TOÀN

Tuyệt đối không hardcode key vào code. Dùng file .env:

OPENAI_API_KEY=sk-...

Và luôn tạo .gitignore chứa .env và .venv/ trước khi commit. Đây là lỗi bảo mật số 1 của người mới — commit key lên GitHub công khai, bị lộ, bị dùng chùa hết tiền trong vài giờ.

# .gitignore
.env
.venv/
__pycache__/

Bước 4 — Agent tool-calling đầu tiên

Mục tiêu: agent tự quyết định khi nào gọi tool get_weather.

import os, json
from dotenv import load_dotenv
from openai import OpenAI
load_dotenv()
client = OpenAI()

def get_weather(city: str) -> str:
    fake = {"Hanoi": "28C, nang", "Tokyo": "15C, mua"}
    return fake.get(city, "khong co du lieu")

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Lay thoi tiet theo ten thanh pho",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

msgs = [{"role": "user", "content": "Thoi tiet Hanoi the nao?"}]
r = client.chat.completions.create(model="gpt-4o-mini", messages=msgs, tools=tools)
call = r.choices[0].message.tool_calls[0]
args = json.loads(call.function.arguments)
result = get_weather(**args)          # thuc thi tool that

msgs.append(r.choices[0].message)
msgs.append({"role": "tool", "tool_call_id": call.id, "content": result})
final = client.chat.completions.create(model="gpt-4o-mini", messages=msgs)
print(final.choices[0].message.content)

Điểm mấu chốt để hiểu: model không tự chạy tool. Nó chỉ nói cho bạn biết nên gọi hàm nào với tham số gì; code của bạn thực thi rồi trả kết quả về. Nắm được vòng này là nắm được 70% agent engineering.

Khung tư duy vòng lặp tool-calling

1. Gui messages + tools -> model
2. Model tra ve: text HAY tool_call?
3. Neu tool_call -> code chay ham -> append ket qua (role=tool)
4. Goi model lai voi ket qua -> lap den khi ra text cuoi

Bước 5 — Cấu trúc thư mục nên có ngay từ đầu

Dự án gọn gàng giúp bạn (và nhà tuyển dụng) dễ đọc:

first-agent/
  .env            # key (bi .gitignore bo qua)
  .gitignore
  requirements.txt
  tools.py        # cac ham tool + schema
  agent.py        # vong lap agent
  main.py         # diem chay
  README.md       # bai toan, cach chay, anh demo

Tách tool ra file riêng ngay từ đầu giúp bạn thêm/bớt tool mà không đụng vào vòng lặp — thói quen của kỹ sư chuyên nghiệp.

Bước 6 — Kiểm soát chi phí khi học

• Dùng model nhỏ (gpt-4o-mini hoặc tương đương) cho toàn bộ giai đoạn học.
• Đặt usage limit trên dashboard của nhà cung cấp (ví dụ 10 USD/tháng) để không bao giờ bị bất ngờ.
• In số token mỗi lần gọi để hình thành trực giác về chi phí.

Checklist môi trường chuẩn

• [ ] Có virtualenv riêng cho dự án.
• [ ] Key nằm trong .env, KHÔNG trong code.
• [ ] .gitignore có .env trước commit đầu tiên.
• [ ] Chạy được agent tool-calling hoàn chỉnh 1 vòng.
• [ ] Hiểu ai là người thực thi tool (code, không phải model).
• [ ] Đã đặt usage limit trên dashboard.

Sai lầm thường gặp

• Commit .env chứa key. Nếu lỡ, phải xoá key ngay trên dashboard và tạo key mới — xoá file thôi không đủ vì key đã nằm trong lịch sử Git.
• Quên append kết quả tool đúng định dạng (role: "tool" + tool_call_id). Thiếu là model không biết tool đã chạy.
• Dùng model đắt tiền cho việc học. gpt-4o-mini / model nhỏ đủ dùng, rẻ hơn nhiều.
• Cài package linh tinh vào Python hệ thống thay vì virtualenv, gây xung đột version về sau.