Tool use: trao cho Claude đôi tay làm việc thật

Vòng lặp 4 bước

Chú ý chỗ quan trọng nhất: Claude không bao giờ tự chạy code. Nó chỉ ĐỀ NGHỊ; quyền thực thi luôn nằm trong tay bạn.

• Bạn gửi request kèm danh sách tools (schema mô tả từng hàm)
• Claude trả lời với stop_reason "tool_use" khi nó cần gọi hàm — kèm tên hàm và tham số
• Code CỦA BẠN thực thi hàm thật, gửi kết quả về qua tool_result
• Claude đọc kết quả và trả lời tiếp — hoặc gọi thêm tool khác

Schema — bản mô tả quyết định tất cả

Mỗi tool có ba phần: name, description và input_schema. Trong đó description quan trọng nhất: Claude dựa vào đó để quyết định khi nào dùng.

{
  "name": "search_orders",
  "description": "Tìm đơn hàng theo email hoặc mã đơn.
    Dùng khi khách hỏi về tình trạng đơn, lịch sử mua,
    hoặc khiếu nại. Trả về danh sách đơn kèm trạng thái.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {"type": "string", "description": "Email hoặc mã đơn"},
      "limit": {"type": "integer", "default": 5}
    },
    "required": ["query"]
  }
}

Công thức description: what — when — returns

Ba câu là đủ: tool làm gì, dùng khi nào, trả về gì. "Gets data" là mô tả khiến Claude gọi sai hoặc không gọi. Mô tả tốt gần như loại bỏ hoàn toàn chuyện gọi nhầm tool.

Vòng lặp đa lượt + cầu chì max_turns

Việc thật hiếm khi xong trong một lần gọi: tìm khách → lấy đơn → kiểm kho. Vòng lặp của bạn cứ tiếp tục chừng nào stop_reason còn là tool_use — nhưng luôn đặt trần số lượt.

turns = 0
while turns < MAX_TURNS:      # cầu chì: 10 lượt
    resp = client.messages.create(model=..., tools=TOOLS, messages=history)
    if resp.stop_reason != "tool_use":
        break                  # Claude đã có câu trả lời cuối
    for block in resp.content:
        if block.type == "tool_use":
            result = run_tool(block.name, block.input)
            history.append(tool_result(block.id, result))
    turns += 1

An toàn theo thiết kế

Học sâu hơn với 11 bài của module Tool Use trong khóa Building with the Claude API — từ schema tới text editor tool có sẵn.

• Tool đọc tách khỏi tool ghi — cấp quyền ghi sau khi quyền đọc chạy ổn
• Hành động không đảo ngược (gửi email, xóa bản ghi): thêm bước con người xác nhận
• Kết quả tool là dữ liệu, không phải mệnh lệnh — validate trước khi đưa ngược vào vòng lặp
• Log mọi lần gọi tool: ai, lúc nào, tham số gì — để audit lại được