Bài 2 — Thiết lập môi trường, LLM và định nghĩa tool đầu tiên

Bài này ta dựng nền: chọn model, cấu hình API key an toàn, và định nghĩa schema tool đúng chuẩn để LLM biết cách gọi. Đây là phần nhiều người làm ẩu nhất — schema sai thì agent "gọi nhầm tay chân".

Bước 1: Chuẩn bị môi trường

mkdir my-agent && cd my-agent
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install anthropic            # hoặc openai, tùy nhà cung cấp

Bước 2: Quản lý API key an toàn

Không bao giờ hardcode key vào code. Dùng biến môi trường:

export ANTHROPIC_API_KEY="sk-..."

Và thêm .env, .venv/ vào .gitignore ngay từ đầu. Một key lộ lên GitHub công khai có thể bị quét và lạm dụng trong vài phút.

Bước 3: Chọn model có tool calling

Coding agent bắt buộc dùng model hỗ trợ tool calling (còn gọi function calling) — nghĩa là model có thể trả về một yêu cầu gọi hàm có cấu trúc, không chỉ text. Các họ model hiện đại (Claude, GPT-4 class, nhiều model mã nguồn mở đời mới) đều hỗ trợ. Ưu tiên model mạnh về code cho tác vụ này.

Bước 4: Định nghĩa schema tool

LLM chỉ gọi đúng tool khi bạn mô tả tool rõ ràng. Mỗi tool cần: tên, mô tả (khi nào dùng), và tham số theo JSON Schema.

{
  "name": "read_file",
  "description": "Đọc toàn bộ nội dung một file text theo đường dẫn tương đối so với thư mục làm việc. Dùng khi cần xem code hiện tại trước khi sửa.",
  "input_schema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Đường dẫn tương đối, ví dụ 'src/app.py'"
      }
    },
    "required": ["path"]
  }
}

Mô tả tốt = agent quyết định đúng. Câu "Dùng khi cần xem code trước khi sửa" hướng dẫn LLM khi nào nên đọc file — quan trọng ngang với việc hàm làm gì.

Bước 5: Gọi LLM lần đầu với tool

import anthropic
client = anthropic.Anthropic()

resp = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=[READ_FILE_TOOL],
    messages=[{"role": "user", "content": "Nội dung file config.py là gì?"}],
)
print(resp.stop_reason)   # 'tool_use' nghĩa là LLM muốn gọi tool
for block in resp.content:
    if block.type == "tool_use":
        print(block.name, block.input)   # read_file {'path': 'config.py'}

Khi stop_reason == "tool_use", LLM đang yêu cầu bạn chạy tool. Nó chưa tự chạy — bạn (code điều phối) mới là người thực thi. Bài 3 sẽ nối phần thực thi này vào vòng lặp.

Khung tư duy: một tool tốt cần "3 rõ"

• Rõ mục đích — mô tả nêu khi nào dùng, không chỉ làm gì.
• Rõ tham số — mỗi tham số có type và ví dụ; đánh dấu required chính xác.
• Rõ kết quả — tool trả về chuỗi ngắn gọn, có ích cho LLM (nội dung file, hoặc thông báo lỗi rõ ràng).

Checklist trước khi sang bài 3

• [ ] API key nằm trong biến môi trường, không trong code.
• [ ] .gitignore đã chặn key và venv.
• [ ] Ít nhất một tool có schema đầy đủ (name, description, input_schema).
• [ ] Gọi thử LLM và thấy stop_reason == "tool_use".
• [ ] Đã in ra được tool_name và input mà LLM yêu cầu.

Sai lầm thường gặp

• Mô tả tool sơ sài. "read file" (2 từ) khiến LLM gọi sai lúc hoặc bịa tham số. Mô tả nên 1–3 câu.
• Quên required. LLM có thể gọi tool thiếu tham số bắt buộc, gây lỗi runtime khó lần.
• Nhầm rằng LLM tự chạy tool. LLM chỉ đề xuất; code của bạn phải thực thi rồi trả kết quả. Không có bước này, agent bất động.
• Hardcode key. Vừa mất an toàn vừa khó chuyển môi trường dev/prod.
• Dùng model không hỗ trợ tool calling rồi tự parse text bằng regex — mong manh và dễ vỡ.