Fine grained tool calling

📖 Nội dung bài học

TrắngĐenĐỏXanh lụcXanh lamVàngĐỏ tươiLục lam TrắngĐenĐỏXanh lụcXanh lamVàngĐỏ tươiLục lam

TrắngĐenĐỏXanh lụcXanh lamVàngĐỏ tươiLục lam

Tóm tắt

Khi bạn kết hợp tool use với streaming trong Claude, bạn sẽ nhận được các cập nhật theo thời gian thực khi AI tạo ra các đối số công cụ. Điều này tạo ra trải nghiệm người dùng đáp ứng hơn, nhưng có một số chi tiết quan trọng cần hiểu về cách nó hoạt động.

Streaming công cụ cơ bản

Với streaming được bật, Claude gửi lại các loại sự kiện khác nhau khi nó xử lý yêu cầu của bạn. Bạn đã quen thuộc với các sự kiện như ContentBlockDelta cho việc tạo văn bản thông thường. Đối với tool use, bạn cũng sẽ cần xử lý một loại sự kiện mới có tên là InputJsonEvent.

Mỗi InputJsonEvent chứa hai thuộc tính chính:

partial_json - Một phần của JSON đại diện cho một phần của các đối số công cụ
snapshot - JSON tích lũy được xây dựng từ tất cả các phần đã nhận cho đến nay

Đây là cách bạn xử lý các sự kiện này trong pipeline streaming của mình:

for chunk in stream:
    if chunk.type == "input_json":
        # Process the partial JSON chunk
        print(chunk.partial_json)
        # Or use the complete snapshot so far
        current_args = chunk.snapshot

Cách thức hoạt động của xác thực JSON

Đây là nơi mọi thứ trở nên thú vị. Claude API không gửi ngay cho bạn mọi phần khi nó tạo ra. Thay vào đó, nó lưu trữ các phần và xác thực chúng trước.

API đợi cho đến khi các cặp khóa-giá trị cấp cao nhất hoàn chỉnh trước khi gửi bất cứ thứ gì. Ví dụ, nếu công cụ của bạn mong đợi cấu trúc này:

{
  "abstract": "This paper presents a novel...",
  "meta": {
    "word_count": 847,
    "review": "This paper introduces QuanNet..."
  }
}

API sẽ:

Đợi cho đến khi toàn bộ giá trị abstract hoàn thành
Xác thực cặp khóa-giá trị đó so với schema của bạn
Gửi tất cả các phần đã lưu trữ cho abstract cùng một lúc
Lặp lại quy trình cho đối tượng meta

Quy trình xác thực này giải thích tại sao bạn thấy độ trễ sau đó là các đợt văn bản, ngay cả khi streaming được bật. Các phần đang bị giữ lại cho đến khi một cặp khóa-giá trị cấp cao nhất hoàn chỉnh, hợp lệ đã sẵn sàng.

Triệu hồi công cụ chi tiết

Nếu bạn cần streaming nhanh hơn, chi tiết hơn - có lẽ để hiển thị cho người dùng các cập nhật ngay lập tức hoặc bắt đầu xử lý các kết quả một phần một cách nhanh chóng - bạn có thể bật triệu hồi công cụ chi tiết.

Triệu hồi công cụ chi tiết thực hiện một việc chính: nó vô hiệu hóa xác thực JSON ở phía API. Điều này có nghĩa là:

Bạn nhận được các phần ngay khi Claude tạo ra chúng
Không có độ trễ lưu trữ giữa các khóa cấp cao nhất
Hành vi streaming truyền thống hơn
Quan trọng: Xác thực JSON bị vô hiệu hóa - code của bạn phải xử lý JSON không hợp lệ

Bật nó bằng cách thêm fine_grained=True vào lệnh gọi API của bạn:

run_conversation(
    messages, 
    tools=[save_article_schema], 
    fine_grained=True
)

Với triệu hồi công cụ chi tiết, bạn có thể nhận được giá trị word_count sớm hơn nhiều trong luồng, mà không cần đợi toàn bộ đối tượng meta được hoàn thành.

Xử lý JSON không hợp lệ

Khi dùng triệu hồi công cụ chi tiết, Claude có thể tạo ra JSON không hợp lệ như "word_count": undefined thay vì một số thích hợp. Ứng dụng của bạn cần xử lý các trường hợp này một cách duyên dáng:

try:
    parsed_args = json.loads(chunk.snapshot)
except json.JSONDecodeError:
    # Handle invalid JSON appropriately
    print("Received invalid JSON, continuing...")

Nếu không có triệu hồi công cụ chi tiết, việc xác thực của API sẽ bắt lỗi này và có thể bao bọc các giá trị có vấn đề trong các chuỗi, điều này có thể không khớp với schema mong đợi của bạn.

Khi nào nên dùng Triệu hồi công cụ chi tiết

Hãy cân nhắc việc bật triệu hồi công cụ chi tiết khi:

Bạn cần hiển thị cho người dùng tiến trình theo thời gian thực về việc tạo đối số công cụ
Bạn muốn bắt đầu xử lý các kết quả công cụ một phần nhanh nhất có thể
Độ trễ lưu trữ ảnh hưởng tiêu cực đến trải nghiệm người dùng của bạn
Bạn cảm thấy thoải mái khi triển khai xử lý lỗi JSON mạnh mẽ

Đối với hầu hết các ứng dụng, hành vi mặc định với xác thực là hoàn toàn đầy đủ. Nhưng khi bạn cần khả năng đáp ứng thêm đó, triệu hồi công cụ chi tiết cho bạn quyền kiểm soát để nhận các phần nhanh nhất có thể khi Claude tạo ra chúng.

Tải xuống

🔁 Bài học liên quan

Bài tiếp: The text edit tool
Bài trước: Using multiple tools
Cùng section: Making a request · Multi-Turn conversations · Chat exercise
Thuộc lộ trình: Path C
Docs tham khảo: Glossary · Skills atlas · By use-case

📚 Nguồn & ghi nhận

Bài học gốc Anthropic Academy: https://anthropic.skilljar.com/claude-with-the-anthropic-api/313160
Crawl: — · Chuẩn hoá: 2026-05-01