为 Agent SDK 代理创建自定义工具——让 Claude 能操作你的系统和数据。
工具定义
工具是代理可以调用的函数。每个工具需要定义：
- 名称：工具的唯一标识符
- 描述：告诉代理何时以及如何使用这个工具
- 输入 Schema：使用 JSON Schema 定义参数
- 实现函数：执行实际逻辑
创建工具
Python 示例
tools = [
{
"name": "search_database",
"description": "搜索数据库中的用户记录",
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "搜索关键词"
},
"limit": {
"type": "integer",
"description": "返回结果的最大数量",
"default": 10
}
},
"required": ["query"]
}
}
]
def execute_tool(tool_name, **kwargs):
if tool_name == "search_database":
return search_db(kwargs["query"], kwargs.get("limit", 10))
# ...其他工具
def search_db(query, limit):
# 实现数据库搜索
return f"找到 {limit} 条关于 '{query}' 的记录"Node.js 示例
const tools = [
{
name: "search_database",
description: "搜索数据库中的用户记录",
input_schema: {
type: "object",
properties: {
query: {
type: "string",
description: "搜索关键词"
},
limit: {
type: "integer",
description: "返回结果的最大数量",
default: 10
}
},
required: ["query"]
}
}
];处理工具调用
def handle_tool_calls(content):
"""处理代理返回的工具调用。"""
results = []
for item in content:
if item.type == "tool_use":
tool_name = item.name
tool_input = item.input
tool_id = item.id
# 执行工具
result = execute_tool(tool_name, **tool_input)
results.append({
"type": "tool_result",
"tool_use_id": tool_id,
"content": str(result)
})
return results工具设计原则
- 描述要详细：帮助代理理解何时使用该工具
- 参数要明确：使用 JSON Schema 严格定义输入
- 错误要清晰：返回有意义的错误信息
- 输出要简洁：避免返回过大的数据撑大上下文
示例：文件系统工具
import os
import glob
file_tools = [
{
"name": "list_files",
"description": "列出目录中的文件",
"input_schema": {
"type": "object",
"properties": {
"path": {"type": "string", "description": "目录路径"},
"pattern": {"type": "string", "description": "文件匹配模式，如 *.py"}
},
"required": ["path"]
}
}
]
def execute_file_tool(name, **kwargs):
if name == "list_files":
path = kwargs["path"]
pattern = kwargs.get("pattern", "*")
files = glob.glob(os.path.join(path, pattern))
return "\n".join(files)
return "未知工具"下一步
- Agent SDK 工具搜索：让代理搜索和使用工具
- Agent SDK 概览