Tweet
Hướng dẫn sử dụng Tools với Claude
Giới thiệu về Tools
Tools cho phép Claude truy cập thông tin từ thế giới bên ngoài, mở rộng khả năng của nó vượt ra ngoài những gì nó đã học trong quá trình huấn luyện. Theo mặc định, Claude chỉ biết thông tin từ dữ liệu huấn luyện và không thể truy cập các sự kiện hiện tại, dữ liệu thời gian thực, hoặc hệ thống bên ngoài. Việc sử dụng tools giải quyết hạn chế này bằng cách tạo ra một cách có cấu trúc để Claude yêu cầu và nhận thông tin mới.
Vấn đề khi không có Tools
Khi người dùng hỏi Claude về thông tin hiện tại, nó gặp phải rào cản. Ví dụ, nếu ai đó hỏi "Thời tiết ở San Francisco, California như thế nào?" Claude phải trả lời bằng câu như "Xin lỗi, nhưng tôi không có quyền truy cập vào thông tin thời tiết cập nhật."
Điều này tạo ra trải nghiệm người dùng khó chịu khi mọi người cần dữ liệu thời gian thực mà về mặt lý thuyết Claude có thể giúp đỡ nếu nó chỉ có quyền truy cập vào thông tin hiện tại.
Cách Tool Use hoạt động
Tool use tuân theo một mẫu trao đổi cụ thể giữa ứng dụng của bạn và Claude. Đây là quy trình hoàn chỉnh:
Ví dụ thời tiết trong thực tế
Hãy xem cách này hoạt động với câu hỏi về thời tiết. Quy trình trở nên cụ thể hơn nhiều:
Khi người dùng hỏi về thời tiết hiện tại, bạn bao gồm hướng dẫn trong prompt về cách truy xuất dữ liệu thời tiết. Claude nhận ra nó cần thông tin hiện tại và yêu cầu dữ liệu thời tiết cho địa điểm cụ thể. Server của bạn sau đó gọi API thời tiết để lấy điều kiện thời gian thực và gửi dữ liệu đó trở lại cho Claude. Cuối cùng, Claude kết hợp dữ liệu thời tiết mới với câu hỏi của người dùng để cung cấp phản hồi chính xác, hiện tại. Tạo Tool Functions
Khi xây dựng ứng dụng AI với Claude, bạn thường cần cung cấp cho nó quyền truy cập vào thông tin thời gian thực hoặc khả năng thực hiện các hành động. Đây là lúc các tool functions có ích - chúng là các hàm Python mà Claude có thể gọi khi nó cần dữ liệu bổ sung để giúp người dùng.
Tool Functions là gì?
Một tool function là một hàm Python thuần túy được thực thi tự động khi Claude quyết định rằng nó cần thông tin bổ sung để giúp người dùng. Ví dụ, nếu ai đó hỏi "Mấy giờ rồi?", Claude sẽ gọi tool ngày/giờ của bạn để lấy thời gian hiện tại.
Đây là ví dụ về một tool function thời tiết. Chú ý cách nó xác thực đầu vào và cung cấp thông báo lỗi rõ ràng - đây là những thực hành tốt quan trọng.
Thực hành tốt nhất cho Tool Functions
Khi viết tool functions, hãy tuân theo các hướng dẫn này:
Việc xác thực đặc biệt quan trọng vì Claude học từ lỗi. Nếu bạn raise một lỗi rõ ràng như "Location cannot be empty", Claude có thể thử gọi hàm lại với giá trị location phù hợp.
Xây dựng Tool Function đầu tiên của bạn
Hãy tạo một hàm để lấy ngày và giờ hiện tại. Hàm này sẽ chấp nhận tham số định dạng ngày để Claude có thể yêu cầu thời gian theo các định dạng khác nhau:
pythondef 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)
Hàm này sử dụng module datetime của Python để lấy thời gian hiện tại và định dạng nó theo chuỗi định dạng được cung cấp. Định dạng mặc định cho chúng ta năm-tháng-ngày giờ:phút:giây.
Bạn có thể test với các định dạng khác nhau:
python# Định dạng mặc định: "2024-01-15 14:30:25"
get_current_datetime()
# Chỉ giờ và phút: "14:30"
get_current_datetime("%H:%M")
Kiểm tra xác thực đảm bảo Claude không thể truyền chuỗi rỗng cho định dạng ngày. Mặc dù lỗi cụ thể này không có khả năng xảy ra, nó minh họa mẫu xác thực đầu vào và cung cấp thông báo lỗi hữu ích mà Claude có thể học từ đó. Tạo JSON Schema cho Tools
Sau khi viết tool function của bạn, bước tiếp theo là tạo một JSON schema cho Claude biết những đối số nào 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à cách gọi tools của bạn.
Hiểu JSON Schema
JSON Schema không cụ thể cho AI hoặc gọi tool - nó là một đặc tả xác thực dữ liệu được sử dụng rộng rãi đã tồn tại nhiều năm. Cộng đồng AI áp dụng nó vì nó là một cách thuận tiện để mô tả tham số hàm và xác thực dữ liệu.
Đặc tả tool hoàn chỉnh có ba phần chính:
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 sử dụng hàm của bạn. Thực hành tốt nhất bao gồm:
Cách dễ dàng để tạo Schemas
Thay vì viết JSON schemas từ đầu, bạn có thể sử dụng chính Claude để tạo chúng. Đây là quy trình:
Prompt nên là một cái gì đó như: "Viết một JSON schema spec hợp lệ cho mục đích gọi tool 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 Code
Khi Claude tạo schema của bạn, sao chép nó vào file code của bạn. Đây là mẫu đặt tên tốt để tuân theo:
pythondef 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": "Trả về ngày và giờ hiện tại được định dạng theo định dạng được chỉ định",
"input_schema": {
"type": "object",
"properties": {
"date_format": {
"type": "string",
"description": "Một chuỗi chỉ định định dạng của datetime được trả về. Sử dụng mã định dạng strftime của Python.",
"default": "%Y-%m-%d %H:%M:%S"
}
},
"required": []
}
}
Sử dụng mẫu function_name theo sau bởi function_name_schema để giữ schemas của bạn được tổ chức và dễ khớp với các hàm tương ứng.
Thêm Type Safety
Để kiểm tra kiểu tốt hơn, import và sử dụng kiểu ToolParam từ thư viện Anthropic:
pythonfrom anthropic.types import ToolParam
get_current_datetime_schema = ToolParam({
"name": "get_current_datetime",
"description": "Trả về ngày và giờ hiện tại được định dạng theo định dạng được chỉ định",
# ... phần còn lại của schema
})
Mặc dù không thực sự cần thiết cho chức năng, điều này ngăn chặn lỗi kiểu khi bạn sử dụng schema với API của Claude và làm cho code của bạn mạnh mẽ hơn. Xử lý phản hồi Multi-Block
Khi làm việc với chức năng tool của Claude, bạn sẽ gặp một loại cấu trúc phản hồi mới khác với các phản hồi văn bản đơn giản mà bạn đã thấy trước đây. Thay vì chỉ nhận lại một khối văn bản duy nhất, Claude bây giờ có thể trả về các thông điệp multi-block chứa cả thông tin văn bản và thông tin sử dụng tool.
Thực hiện API Calls có hỗ trợ Tool
Để cho phép Claude sử dụng tools, bạn cần bao gồm tham số tools trong API call của mình. Đây là cách cấu trúc yêu cầu:
pythonmessages = []
messages.append({
"role": "user",
"content": "Thời gian chính xác là bao nhiêu, được định dạng là HH:MM:SS?"
})
response = client.messages.create(
model=model,
max_tokens=1000,
messages=messages,
tools=[get_current_datetime_schema],
)
Tham số tools nhận một danh sách các JSON schemas mô tả các hàm có sẵn mà Claude có thể gọi.
Hiểu Multi-Block Messages
Khi Claude quyết định sử dụng một tool, nó trả về một thông điệp assistant với nhiều blocks trong danh sách content. Đây là một thay đổi đáng kể từ các phản hồi chỉ có văn bản đơn giản mà bạn đã làm việc trước đây.
Một thông điệp multi-block thường chứa:
ToolUse Block bao gồm:
Quản lý lịch sử hội thoại với Multi-Block Messages
Nhớ rằng Claude không lưu trữ lịch sử hội thoại - bạn cần quản lý nó thủ công. Khi làm việc với phản hồi tool, bạn phải bảo tồn toàn bộ cấu trúc nội dung, bao gồm tất cả các blocks.
Đây là cách thêm một thông điệp assistant multi-block vào lịch sử hội thoại của bạn một cách đúng đắn:
pythonmessages.append({
"role": "assistant",
"content": response.content
})
Điều này bảo tồn cả text block và tool use block, điều quan trọng để duy trì ngữ cảnh hội thoại khi bạn thực hiện các API calls tiếp theo.
Quy trình sử dụng Tool hoàn chỉnh
Quy trình sử dụng tool tuân theo mẫu này:
Mỗi bước yêu cầu xử lý cẩn thận cấu trúc thông điệp để đảm bảo Claude có đầy đủ ngữ cảnh cần thiết để cung cấp phản hồi chính xác.
Cập nhật Helper Functions
Nếu bạn đã sử dụng các helper functions như add_user_message() và add_assistant_message(), bạn sẽ cần cập nhật chúng để xử lý nội dung multi-block. Các phiên bản hiện tại có thể chỉ hỗ trợ các text blocks đơn lẻ, nhưng bây giờ chúng cần phù hợp với các cấu trúc nội dung phức tạp hơn bao gồm tool use blocks.
Việc xử lý multi-block message này rất cần thiết để xây dựng các ứng dụng mạnh mẽ có thể tích hợp liền mạch khả năng tool của Claude trong khi duy trì luồng hội thoại phù hợp.
Giới thiệu về Tools
Tools cho phép Claude truy cập thông tin từ thế giới bên ngoài, mở rộng khả năng của nó vượt ra ngoài những gì nó đã học trong quá trình huấn luyện. Theo mặc định, Claude chỉ biết thông tin từ dữ liệu huấn luyện và không thể truy cập các sự kiện hiện tại, dữ liệu thời gian thực, hoặc hệ thống bên ngoài. Việc sử dụng tools giải quyết hạn chế này bằng cách tạo ra một cách có cấu trúc để Claude yêu cầu và nhận thông tin mới.
Vấn đề khi không có Tools
Khi người dùng hỏi Claude về thông tin hiện tại, nó gặp phải rào cản. Ví dụ, nếu ai đó hỏi "Thời tiết ở San Francisco, California như thế nào?" Claude phải trả lời bằng câu như "Xin lỗi, nhưng tôi không có quyền truy cập vào thông tin thời tiết cập nhật."
Điều này tạo ra trải nghiệm người dùng khó chịu khi mọi người cần dữ liệu thời gian thực mà về mặt lý thuyết Claude có thể giúp đỡ nếu nó chỉ có quyền truy cập vào thông tin hiện tại.
Cách Tool Use hoạt động
Tool use tuân theo một mẫu trao đổi cụ thể giữa ứng dụng của bạn và Claude. Đây là quy trình hoàn chỉnh:
- Yêu cầu ban đầu: Bạn gửi cho Claude một câu hỏi cùng với hướng dẫn về cách lấy dữ liệu bổ sung từ các nguồn bên ngoài
- Yêu cầu Tool: Claude phân tích câu hỏi và quyết định rằng nó cần thông tin bổ sung, sau đó yêu cầu chi tiết cụ thể về dữ liệu nào cần thiết
- Truy xuất dữ liệu: Server của bạn chạy code để lấy thông tin được yêu cầu từ API hoặc cơ sở dữ liệu bên ngoài
- Phản hồi cuối cùng: Bạn gửi dữ liệu đã truy xuất trở lại cho Claude, sau đó nó tạo ra một phản hồi hoàn chỉnh sử dụng cả câu hỏi gốc và dữ liệu mới
Ví dụ thời tiết trong thực tế
Hãy xem cách này hoạt động với câu hỏi về thời tiết. Quy trình trở nên cụ thể hơn nhiều:
Khi người dùng hỏi về thời tiết hiện tại, bạn bao gồm hướng dẫn trong prompt về cách truy xuất dữ liệu thời tiết. Claude nhận ra nó cần thông tin hiện tại và yêu cầu dữ liệu thời tiết cho địa điểm cụ thể. Server của bạn sau đó gọi API thời tiết để lấy điều kiện thời gian thực và gửi dữ liệu đó trở lại cho Claude. Cuối cùng, Claude kết hợp dữ liệu thời tiết mới với câu hỏi của người dùng để cung cấp phản hồi chính xác, hiện tại. Tạo Tool Functions
Khi xây dựng ứng dụng AI với Claude, bạn thường cần cung cấp cho nó quyền truy cập vào thông tin thời gian thực hoặc khả năng thực hiện các hành động. Đây là lúc các tool functions có ích - chúng là các hàm Python mà Claude có thể gọi khi nó cần dữ liệu bổ sung để giúp người dùng.
Tool Functions là gì?
Một tool function là một hàm Python thuần túy được thực thi tự động khi Claude quyết định rằng nó cần thông tin bổ sung để giúp người dùng. Ví dụ, nếu ai đó hỏi "Mấy giờ rồi?", Claude sẽ gọi tool ngày/giờ của bạn để lấy thời gian hiện tại.
Đây là ví dụ về một tool function thời tiết. Chú ý cách nó xác thực đầu vào và cung cấp thông báo lỗi rõ ràng - đây là những thực hành tốt quan trọng.
Thực hành tốt nhất cho Tool Functions
Khi viết tool functions, hãy tuân theo các hướng dẫn này:
- Sử dụng tên mô tả: Cả tên hàm và tên tham số của bạn nên chỉ rõ mục đích của chúng
- Xác thực đầu vào: Kiểm tra rằng các tham số bắt buộc không rỗng hoặc không hợp lệ, và raise lỗi khi chúng không hợp lệ
- Cung cấp thông báo lỗi có ý nghĩa: Claude có thể thấy thông báo lỗi và có thể thử lại gọi hàm với các tham số đã được sửa
Việc xác thực đặc biệt quan trọng vì Claude học từ lỗi. Nếu bạn raise một lỗi rõ ràng như "Location cannot be empty", Claude có thể thử gọi hàm lại với giá trị location phù hợp.
Xây dựng Tool Function đầu tiên của bạn
Hãy tạo một hàm để lấy ngày và giờ hiện tại. Hàm này sẽ chấp nhận tham số định dạng ngày để Claude có thể yêu cầu thời gian theo các định dạng khác nhau:
pythondef 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)
Hàm này sử dụng module datetime của Python để lấy thời gian hiện tại và định dạng nó theo chuỗi định dạng được cung cấp. Định dạng mặc định cho chúng ta năm-tháng-ngày giờ:phút:giây.
Bạn có thể test với các định dạng khác nhau:
python# Định dạng mặc định: "2024-01-15 14:30:25"
get_current_datetime()
# Chỉ giờ và phút: "14:30"
get_current_datetime("%H:%M")
Kiểm tra xác thực đảm bảo Claude không thể truyền chuỗi rỗng cho định dạng ngày. Mặc dù lỗi cụ thể này không có khả năng xảy ra, nó minh họa mẫu xác thực đầu vào và cung cấp thông báo lỗi hữu ích mà Claude có thể học từ đó. Tạo JSON Schema cho Tools
Sau khi viết tool function của bạn, bước tiếp theo là tạo một JSON schema cho Claude biết những đối số nào 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à cách gọi tools của bạn.
Hiểu JSON Schema
JSON Schema không cụ thể cho AI hoặc gọi tool - nó là một đặc tả xác thực dữ liệu được sử dụng rộng rãi đã tồn tại nhiều năm. Cộng đồng AI áp dụng nó vì nó là một cách thuận tiện để mô tả tham số hàm và xác thực dữ liệu.
Đặc tả tool hoàn chỉnh có ba phần chính:
- name - Một tên rõ ràng, mô tả cho tool của bạn (như "get_weather")
- description - Tool làm gì, khi nào sử dụng nó, và nó trả về 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 sử dụng hàm của bạn. Thực hành tốt nhất bao gồm:
- Nhắm tới 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 nó trả về
- Cung cấp mô tả chi tiết cho từng đối số
Cách dễ dàng để tạo Schemas
Thay vì viết JSON schemas từ đầu, bạn có thể sử dụng chính Claude để tạo chúng. Đây là quy trình:
- Sao chép code tool function của bạn
- Đến Claude và yêu cầu nó viết JSON schema cho tool calling
- Bao gồm tài liệu Anthropic về tool use làm ngữ cảnh
- Để Claude tạo schema được định dạng đúng theo thực hành tốt nhất
Prompt nên là một cái gì đó như: "Viết một JSON schema spec hợp lệ cho mục đích gọi tool 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 Code
Khi Claude tạo schema của bạn, sao chép nó vào file code của bạn. Đây là mẫu đặt tên tốt để tuân theo:
pythondef 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": "Trả về ngày và giờ hiện tại được định dạng theo định dạng được chỉ định",
"input_schema": {
"type": "object",
"properties": {
"date_format": {
"type": "string",
"description": "Một chuỗi chỉ định định dạng của datetime được trả về. Sử dụng mã định dạng strftime của Python.",
"default": "%Y-%m-%d %H:%M:%S"
}
},
"required": []
}
}
Sử dụng mẫu function_name theo sau bởi function_name_schema để giữ schemas của bạn được tổ chức và dễ khớp với các hàm tương ứng.
Thêm Type Safety
Để kiểm tra kiểu tốt hơn, import và sử dụng kiểu ToolParam từ thư viện Anthropic:
pythonfrom anthropic.types import ToolParam
get_current_datetime_schema = ToolParam({
"name": "get_current_datetime",
"description": "Trả về ngày và giờ hiện tại được định dạng theo định dạng được chỉ định",
# ... phần còn lại của schema
})
Mặc dù không thực sự cần thiết cho chức năng, điều này ngăn chặn lỗi kiểu khi bạn sử dụng schema với API của Claude và làm cho code của bạn mạnh mẽ hơn. Xử lý phản hồi Multi-Block
Khi làm việc với chức năng tool của Claude, bạn sẽ gặp một loại cấu trúc phản hồi mới khác với các phản hồi văn bản đơn giản mà bạn đã thấy trước đây. Thay vì chỉ nhận lại một khối văn bản duy nhất, Claude bây giờ có thể trả về các thông điệp multi-block chứa cả thông tin văn bản và thông tin sử dụng tool.
Thực hiện API Calls có hỗ trợ Tool
Để cho phép Claude sử dụng tools, bạn cần bao gồm tham số tools trong API call của mình. Đây là cách cấu trúc yêu cầu:
pythonmessages = []
messages.append({
"role": "user",
"content": "Thời gian chính xác là bao nhiêu, được định dạng là HH:MM:SS?"
})
response = client.messages.create(
model=model,
max_tokens=1000,
messages=messages,
tools=[get_current_datetime_schema],
)
Tham số tools nhận một danh sách các JSON schemas mô tả các hàm có sẵn mà Claude có thể gọi.
Hiểu Multi-Block Messages
Khi Claude quyết định sử dụng một tool, nó trả về một thông điệp assistant với nhiều blocks trong danh sách content. Đây là một thay đổi đáng kể từ các phản hồi chỉ có văn bản đơn giản mà bạn đã làm việc trước đây.
Một thông điệp multi-block thường chứa:
- Text Block - Văn bản con người có thể đọc được giải thích những gì Claude đang làm (như "Tôi có thể giúp bạn tìm hiểu thời gian hiện tại. Hãy để tôi tìm thông tin đó cho bạn")
- ToolUse Block - Hướng dẫn cho code của bạn về tool nào cần gọi và tham số nào sử dụng
ToolUse Block bao gồm:
- Một ID để theo dõi tool call
- Tên của hàm cần gọi (như "get_current_datetime")
- Tham số đầu vào được định dạng như một dictionary
- Chỉ định kiểu "tool_use"
Quản lý lịch sử hội thoại với Multi-Block Messages
Nhớ rằng Claude không lưu trữ lịch sử hội thoại - bạn cần quản lý nó thủ công. Khi làm việc với phản hồi tool, bạn phải bảo tồn toàn bộ cấu trúc nội dung, bao gồm tất cả các blocks.
Đây là cách thêm một thông điệp assistant multi-block vào lịch sử hội thoại của bạn một cách đúng đắn:
pythonmessages.append({
"role": "assistant",
"content": response.content
})
Điều này bảo tồn cả text block và tool use block, điều quan trọng để duy trì ngữ cảnh hội thoại khi bạn thực hiện các API calls tiếp theo.
Quy trình sử dụng Tool hoàn chỉnh
Quy trình sử dụng tool tuân theo mẫu này:
- Gửi thông điệp user với tool schema cho Claude
- Nhận thông điệp assistant với text block và tool use block
- Trích xuất thông tin tool và thực thi hàm thực tế
- Gửi kết quả tool trở lại cho Claude cùng với lịch sử hội thoại hoàn chỉnh
- Nhận phản hồi cuối cùng từ Claude
Mỗi bước yêu cầu xử lý cẩn thận cấu trúc thông điệp để đảm bảo Claude có đầy đủ ngữ cảnh cần thiết để cung cấp phản hồi chính xác.
Cập nhật Helper Functions
Nếu bạn đã sử dụng các helper functions như add_user_message() và add_assistant_message(), bạn sẽ cần cập nhật chúng để xử lý nội dung multi-block. Các phiên bản hiện tại có thể chỉ hỗ trợ các text blocks đơn lẻ, nhưng bây giờ chúng cần phù hợp với các cấu trúc nội dung phức tạp hơn bao gồm tool use blocks.
Việc xử lý multi-block message này rất cần thiết để xây dựng các ứng dụng mạnh mẽ có thể tích hợp liền mạch khả năng tool của Claude trong khi duy trì luồng hội thoại phù hợp.