Bài 2 — Thiết lập môi trường và kết nối công cụ

Agent chỉ mạnh bằng những công cụ nó cầm. Bài này ta chuẩn bị môi trường và kết nối thật vào Google Calendar và một task manager (dùng Todoist làm ví dụ vì API đơn giản). Sau bài này agent của bạn đọc được lịch và task thật.

Chuẩn bị môi trường

python -m venv venv && source venv/bin/activate
pip install openai google-api-python-client google-auth-oauthlib requests python-dotenv

Tạo file .env để giữ khóa bí mật — không bao giờ hardcode key vào code:

OPENAI_API_KEY=sk-...
TODOIST_TOKEN=...
GOOGLE_CREDENTIALS=credentials.json

Các bước lấy quyền truy cập Google Calendar

• Vào Google Cloud Console → tạo project mới.
• Bật Google Calendar API trong thư viện API.
• Tạo OAuth Client ID loại Desktop → tải file credentials.json.
• Ở màn hình OAuth consent, thêm scope .../auth/calendar và thêm email của bạn vào Test users.
• Lần chạy đầu, code sẽ mở trình duyệt để bạn cấp quyền, sau đó lưu token.json để lần sau không cần đăng nhập lại.

from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

SCOPES = ["https://www.googleapis.com/auth/calendar"]
flow = InstalledAppFlow.from_client_secrets_file("credentials.json", SCOPES)
creds = flow.run_local_server(port=0)
cal = build("calendar", "v3", credentials=creds)

events = cal.events().list(
    calendarId="primary", maxResults=10,
    singleEvents=True, orderBy="startTime"
).execute()
for e in events.get("items", []):
    print(e["start"].get("dateTime"), "-", e.get("summary"))

Kết nối Todoist

Todoist chỉ cần một token cá nhân (Settings → Integrations → API token). Không cần OAuth cho bản cá nhân:

import requests, os
H = {"Authorization": f"Bearer {os.getenv('TODOIST_TOKEN')}"}
tasks = requests.get("https://api.todoist.com/rest/v2/tasks", headers=H).json()
for t in tasks:
    print(t["content"], "| due:", (t.get("due") or {}).get("date"))

Khung kiểm thử kết nối (checklist)

• [ ] venv hoạt động, pip list thấy đủ thư viện.
• [ ] .env load được (in thử os.getenv), file này đã nằm trong .gitignore.
• [ ] Đọc được ít nhất 1 event thật từ Calendar.
• [ ] Đọc được ít nhất 1 task thật từ Todoist.
• [ ] Token/credentials KHÔNG bị commit lên git.

Nếu cả 5 mục xanh, phần "tay chân" của agent đã sẵn sàng.

Ví dụ cụ thể: hàm bọc để agent dùng lại

Đừng để agent gọi thẳng API thô. Bọc mỗi thao tác thành một hàm sạch, trả về dữ liệu đã lọc — điều này giúp bài 3-4 nối tool dễ hơn nhiều:

def list_events_today():
    from datetime import datetime, timezone
    now = datetime.now(timezone.utc).isoformat()
    end = now[:10] + "T23:59:59Z"
    r = cal.events().list(calendarId="primary", timeMin=now,
                          timeMax=end, singleEvents=True).execute()
    return [{"title": e.get("summary"), "start": e["start"]}
            for e in r.get("items", [])]

Sai lầm thường gặp

• Quên xử lý timezone. Google Calendar dùng ISO 8601 có offset; nếu bạn so sánh chuỗi giờ ngây thơ sẽ đặt nhầm lịch sai vài tiếng. Luôn làm việc với datetime có timezone.
• Hardcode API key trong file .py rồi push lên GitHub. Key bị lộ trong vài phút. Dùng .env + .gitignore ngay từ đầu.
• Xin scope quá rộng. Chỉ xin calendar khi cần ghi; nếu chỉ đọc, dùng calendar.readonly an toàn hơn.
• Không cache token. Bắt người dùng OAuth lại mỗi lần chạy khiến trải nghiệm tệ; hãy lưu token.json.
• Test trực tiếp trên lịch chính. Trong lúc dev, tạo một calendar phụ để thử tạo/xóa event, tránh làm rối lịch thật.

Chốt bài: Bạn đã có hai công cụ thật được bọc thành hàm sạch. Bài 3 ta dạy agent tự chọn gọi hàm nào qua cơ chế tool-calling.