Schema của Tool

📖 Nội dung bài học

Mở trong Claude (Anthropic) Tìm %0-9 Cỡ chữ

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. Schema này sẽ cho Claude biết hàm của bạn mong đợi những đối số nào và cách sử dụng nó. Schema này hoạt động như một tài liệu để Claude đọc, giúp nó 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ả (specification) xác thực dữ liệu được sử dụng rộng rãi và đã tồn tại 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 (function parameters) và xác thực dữ liệu.

Đặc tả tool hoàn chỉnh có ba phần chính:

name - Tên hàm (ví dụ "get_weather")
description - Tool làm gì và khi nào nên dùng nó
input_schema - JSON schema thực tế mô tả các đối số

Viết Description Hiệu quả

Trường description rất quan trọng để giúp Claude hiểu tool của bạn. Hãy làm theo các phương pháp hay nhất (best practices) sau:

Giải thích tool làm gì, khi nào nên dùng và nó trả về gì
Đặt mục tiêu 3-4 câu
Cung cấp description chi tiết cho từng đối số

Phần input_schema mô tả các tham số của hàm bạn bằng định dạng JSON Schema tiêu chuẩn, bao gồm thông tin về kiểu dữ liệu (type information) và description chi tiết cho từng đối số.

Cách dễ dàng: Để Claude viết Schema cho bạn

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

Sao chép hàm tool của bạn
Vào 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 context
Để Claude tạo một schema được định dạng đúng theo các best practices

prompt nên giống như: "Viết một JSON schema spec hợp lệ cho mục đích tool calling cho hàm này. Làm theo các best practices được liệt kê trong tài liệu đính kèm."

Triển khai Schema trong Code

Khi Claude đã tạo schema của bạn, hãy sao chép nó vào file code của bạn. Dùng một mẫu đặt tên nhất quán như function_name_schema để giữ mọi thứ có tổ chức:

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": []
    }
}

Thêm Type Safety

Để kiểm tra kiểu dữ liệu (type checking) tốt hơn, hãy import và dùng kiểu ToolParam từ thư viện Anthropic:

from anthropic.types import ToolParam

get_current_datetime_schema = ToolParam({
    # your schema dictionary here
})

Điều này không hoàn toàn cần thiết cho chức năng, nhưng nó giúp ngăn ngừa lỗi kiểu dữ liệu (type errors) khi bạn dùng schema sau này trong code của mình.

Sự kết hợp giữa một hàm tool được viết tốt và một JSON schema chi tiết cung cấp cho Claude mọi thứ nó cần để hiểu và sử dụng đúng cách các tool của bạn trong các cuộc hội thoại.

🔁 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-google-vertex/289174
Crawl: 2026-04-23 · Chuẩn hoá: 2026-05-01