Tool schemas

📖 Nội dung bài học

Anthropic Mở trên Claude

Anthropic

Mở trên Claude Màu khung

Đen

Độ trong suốt khung

Tóm tắt

Sau khi viết hàm tool của bạn, bước tiếp theo là tạo một JSON schema để cho Claude biết các đối số mà hàm của bạn mong đợi và cách sử dụng nó. Schema này hoạt động như tài liệu mà Claude đọc để hiểu khi nào và làm thế nào để gọi các tool của bạn.

Hiểu về JSON Schema

JSON Schema không dành riêng cho AI hay tool calling. Đây là một đặc tả xác thực dữ liệu được sử dụng rộng rãi và đã có từ nhiều năm. Cộng đồng AI đã áp dụng nó vì đây là một cách thuận tiện để mô tả các tham số hàm và xác thực dữ liệu.

Thông số kỹ thuật tool hoàn chỉnh có ba phần chính:

name - Tên rõ ràng, mô tả cho tool của bạn (ví dụ: "get_weather")
description - Tool làm gì, khi nào nên sử dụng nó và nó trả về dữ liệu gì
input_schema - JSON schema thực tế mô tả các đối số của hàm

Viết Mô tả Hiệu quả

Mô tả tool của bạn rất quan trọng để giúp Claude hiểu khi nào nên sử dụng hàm của bạn. Các thực hành tốt nhất bao gồm:

Đặt mục tiêu 3-4 câu giải thích tool làm gì
Mô tả khi nào Claude nên sử dụng nó
Giải thích loại dữ liệu mà nó trả về
Cung cấp mô tả chi tiết cho từng đối số

Cách Dễ Dàng Tạo Schema

Thay vì viết JSON schema từ đầu, bạn có thể sử dụng chính Claude để tạo chúng. Đây là quy trình:

Sao chép mã hàm tool của bạn
Truy cập Claude và yêu cầu nó viết một JSON schema cho tool calling
Bao gồm tài liệu của Anthropic về tool use làm ngữ cảnh
Để Claude tạo một schema được định dạng đúng theo các thực hành tốt nhất

Prompt nên có dạng như: "Write a valid JSON schema spec for the purposes of tool calling for this function. Follow the best practices listed in the attached documentation." (Viết một spec JSON schema hợp lệ cho mục đích tool calling cho hàm này. Tuân theo các thực hành tốt nhất được liệt kê trong tài liệu đính kèm.)

Triển khai Schema trong Mã

Sau khi Claude tạo schema của bạn, hãy sao chép nó vào tệp mã của bạn. Đây là một mẫu đặt tên tốt để làm theo:

def get_current_datetime(date_format="%Y-%m-%d %H:%M:%S"):
    if not date_format:
        raise ValueError("date_format cannot be empty")
    return datetime.now().strftime(date_format)

get_current_datetime_schema = {
    "name": "get_current_datetime",
    "description": "Returns the current date and time formatted according to the specified format",
    "input_schema": {
        "type": "object",
        "properties": {
            "date_format": {
                "type": "string",
                "description": "A string specifying the format of the returned datetime. Uses Python's strftime format codes.",
                "default": "%Y-%m-%d %H:%M:%S"
            }
        },
        "required": []
    }
}

Sử dụng mẫu function_name theo sau là function_name_schema để giữ cho các schema của bạn được tổ chức và dễ dàng khớp với các hàm tương ứng.

Thêm Type Safety

Để kiểm tra kiểu tốt hơn, hãy nhập và sử dụng kiểu ToolParam từ thư viện Anthropic:

from anthropic.types import ToolParam

get_current_datetime_schema = ToolParam({
    "name": "get_current_datetime",
    "description": "Returns the current date and time formatted according to the specified format",
    # ... phần còn lại của schema
})

Mặc dù không hoàn toàn cần thiết cho chức năng, điều này ngăn chặn các lỗi kiểu khi bạn sử dụng schema với API của Claude và làm cho mã của bạn mạnh mẽ hơn.

🔁 Bài học liên quan

Bài tiếp: Handling message blocks
Bài trước: Tool functions
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/287753
Crawl: 2026-04-23 · Chuẩn hoá: 2026-05-01