Claude 高级工具使用

发布时间: 2025年11月24日

掌握 Claude 的高级工具使用能力,构建强大的 AI 代理应用,实现复杂任务的自动化。

概述

Anthropic 推出了三个强大的 beta 功能,让 Claude 能够动态发现、学习和执行工具:

1. 🔍 工具搜索工具 (Tool Search Tool) - 动态发现和执行工具
2. 💻 程序化工具调用 (Programmatic Tool Calling) - 减少上下文消耗
3. 📚 工具使用示例 (Tool Use Examples) - 从示例中学习

工具搜索工具

🔍 动态工具发现

传统方式需要在每次请求中发送所有工具定义,而工具搜索工具允许 Claude 按需发现和执行工具。

传统方式的问题

// 问题: 需要在每次请求中发送所有工具定义
const response = await claude.messages.create({
  model: 'claude-sonnet-4.5',
  tools: [
    tool1, tool2, tool3, ..., tool100  // 100 个工具定义!
  ],
  messages: [{ role: 'user', content: '查询天气' }]
});

// 即使只用到 1 个工具,也要发送 100 个工具的定义
// 浪费上下文窗口,增加成本

使用工具搜索工具

// 解决方案: 动态搜索和执行工具

// 1. 定义工具搜索工具
const toolSearchTool = {
  name: 'search_tools',
  description: '搜索可用的工具',
  input_schema: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: '搜索查询,描述需要什么功能'
      }
    },
    required: ['query']
  }
};

// 2. 实现工具搜索逻辑
async function searchTools(query: string) {
  // 在工具库中搜索相关工具
  const relevantTools = toolRegistry.search(query);
  return relevantTools.map(tool => ({
    name: tool.name,
    description: tool.description,
    schema: tool.input_schema
  }));
}

// 3. 使用工具搜索
const response = await claude.messages.create({
  model: 'claude-sonnet-4.5',
  tools: [toolSearchTool],  // 只需要提供搜索工具
  messages: [{
    role: 'user',
    content: '查询北京的天气'
  }]
});

// Claude 会:
// 1. 调用 search_tools({ query: "天气查询" })
// 2. 获取相关工具(如 get_weather)
// 3. 使用找到的工具完成任务

实际应用示例

# 构建一个工具注册表

class ToolRegistry:
    def __init__(self):
        self.tools = {}
        self.embeddings = {}  # 工具描述的向量嵌入
    
    def register(self, tool):
        """注册工具"""
        self.tools[tool['name']] = tool
        # 生成工具描述的嵌入向量
        self.embeddings[tool['name']] = self.create_embedding(
            tool['description']
        )
    
    def search(self, query: str, limit: int = 5):
        """搜索相关工具"""
        query_embedding = self.create_embedding(query)
        
        # 计算相似度
        similarities = {}
        for name, embedding in self.embeddings.items():
            similarity = self.cosine_similarity(query_embedding, embedding)
            similarities[name] = similarity
        
        # 返回最相关的工具
        top_tools = sorted(
            similarities.items(),
            key=lambda x: x[1],
            reverse=True
        )[:limit]
        
        return [self.tools[name] for name, _ in top_tools]

# 使用示例
registry = ToolRegistry()

# 注册工具
registry.register({
    'name': 'get_weather',
    'description': '获取指定城市的天气信息',
    'input_schema': {...}
})

registry.register({
    'name': 'search_database',
    'description': '在数据库中搜索信息',
    'input_schema': {...}
})

# 搜索工具
tools = registry.search('天气查询')
# 返回: [get_weather]

程序化工具调用

💻 减少上下文消耗

程序化工具调用允许你通过工具 ID 引用工具,而不是每次都发送完整定义。

基本用法

// 1. 首次注册工具,获取 ID
const toolDefinition = {
  name: 'calculate',
  description: '执行数学计算',
  input_schema: {
    type: 'object',
    properties: {
      expression: { type: 'string' }
    }
  }
};

// 注册并获取 ID
const toolId = await claude.tools.register(toolDefinition);
// 返回: "tool_abc123"

// 2. 后续请求中使用工具 ID
const response = await claude.messages.create({
  model: 'claude-sonnet-4.5',
  tool_ids: [toolId],  // 使用 ID 而不是完整定义
  messages: [{
    role: 'user',
    content: '计算 123 + 456'
  }]
});

// 节省的 tokens: 工具定义的大小

高级示例: 工具版本管理

# 管理工具的多个版本

class ToolVersionManager:
    def __init__(self):
        self.tools = {}
    
    def register_tool(self, name: str, version: str, definition: dict):
        """注册工具版本"""
        tool_id = f"{name}@{version}"
        self.tools[tool_id] = {
            'id': tool_id,
            'name': name,
            'version': version,
            'definition': definition,
            'created_at': datetime.now()
        }
        return tool_id
    
    def get_tool(self, tool_id: str):
        """获取工具定义"""
        return self.tools.get(tool_id)
    
    def get_latest_version(self, name: str):
        """获取工具的最新版本"""
        versions = [
            tool for tool_id, tool in self.tools.items()
            if tool['name'] == name
        ]
        if not versions:
            return None
        return max(versions, key=lambda x: x['version'])

# 使用示例
manager = ToolVersionManager()

# 注册不同版本的工具
v1_id = manager.register_tool('search', 'v1', {...})
v2_id = manager.register_tool('search', 'v2', {...})

# 使用最新版本
latest = manager.get_latest_version('search')
response = claude.messages.create(
    tool_ids=[latest['id']],
    messages=[...]
)

工具使用示例

📚 从示例中学习

提供工具使用示例,帮助 Claude 更好地理解如何使用工具。

基本示例

// 定义工具及其使用示例

const searchTool = {
  name: 'search_products',
  description: '在产品数据库中搜索',
  input_schema: {
    type: 'object',
    properties: {
      query: { type: 'string' },
      category: { type: 'string' },
      price_range: {
        type: 'object',
        properties: {
          min: { type: 'number' },
          max: { type: 'number' }
        }
      }
    },
    required: ['query']
  },
  
  // 提供使用示例
  examples: [
    {
      description: '搜索特定价格范围的产品',
      input: {
        query: '笔记本电脑',
        category: '电子产品',
        price_range: { min: 3000, max: 8000 }
      },
      output: {
        results: [
          { id: 1, name: 'ThinkPad X1', price: 7999 },
          { id: 2, name: 'MacBook Air', price: 7999 }
        ]
      }
    },
    {
      description: '简单搜索',
      input: {
        query: '手机'
      },
      output: {
        results: [
          { id: 3, name: 'iPhone 15', price: 5999 }
        ]
      }
    }
  ]
};

// Claude 会根据示例学习如何正确使用工具

复杂工具的示例

# 为复杂 API 提供详细示例

database_tool = {
    'name': 'query_database',
    'description': '执行数据库查询',
    'input_schema': {
        'type': 'object',
        'properties': {
            'query': {'type': 'string'},
            'parameters': {'type': 'object'},
            'options': {
                'type': 'object',
                'properties': {
                    'limit': {'type': 'number'},
                    'offset': {'type': 'number'},
                    'order_by': {'type': 'string'}
                }
            }
        }
    },
    
    'examples': [
        {
            'description': '查询活跃用户',
            'input': {
                'query': 'SELECT * FROM users WHERE status = :status',
                'parameters': {'status': 'active'},
                'options': {'limit': 10, 'order_by': 'created_at DESC'}
            },
            'explanation': '使用参数化查询防止 SQL 注入,限制结果数量并按创建时间排序'
        },
        {
            'description': '聚合查询',
            'input': {
                'query': '''
                    SELECT category, COUNT(*) as count, AVG(price) as avg_price
                    FROM products
                    WHERE created_at > :date
                    GROUP BY category
                ''',
                'parameters': {'date': '2024-01-01'}
            },
            'explanation': '使用聚合函数统计每个类别的产品数量和平均价格'
        }
    ]
}

实战示例

🚀 构建智能助手

示例 1: 多功能助手

// 构建一个能够处理多种任务的智能助手

class SmartAssistant {
  private toolRegistry: ToolRegistry;
  private claude: Anthropic;
  
  constructor() {
    this.toolRegistry = new ToolRegistry();
    this.claude = new Anthropic();
    this.registerTools();
  }
  
  private registerTools() {
    // 注册各种工具
    this.toolRegistry.register({
      name: 'send_email',
      description: '发送电子邮件',
      execute: async (params) => {
        return await emailService.send(params);
      }
    });
    
    this.toolRegistry.register({
      name: 'schedule_meeting',
      description: '安排会议',
      execute: async (params) => {
        return await calendarService.schedule(params);
      }
    });
    
    this.toolRegistry.register({
      name: 'search_documents',
      description: '搜索文档',
      execute: async (params) => {
        return await documentService.search(params);
      }
    });
  }
  
  async handleRequest(userMessage: string) {
    // 1. 让 Claude 搜索需要的工具
    const response = await this.claude.messages.create({
      model: 'claude-sonnet-4.5',
      tools: [{
        name: 'search_tools',
        description: '搜索可用的工具',
        input_schema: {
          type: 'object',
          properties: {
            query: { type: 'string' }
          }
        }
      }],
      messages: [{
        role: 'user',
        content: userMessage
      }]
    });
    
    // 2. 处理工具调用
    for (const block of response.content) {
      if (block.type === 'tool_use') {
        if (block.name === 'search_tools') {
          // 搜索工具
          const tools = this.toolRegistry.search(block.input.query);
          
          // 3. 使用找到的工具继续对话
          const finalResponse = await this.claude.messages.create({
            model: 'claude-sonnet-4.5',
            tools: tools,
            messages: [
              { role: 'user', content: userMessage },
              { role: 'assistant', content: response.content },
              {
                role: 'user',
                content: [{
                  type: 'tool_result',
                  tool_use_id: block.id,
                  content: JSON.stringify(tools)
                }]
              }
            ]
          });
          
          return finalResponse;
        }
      }
    }
  }
}

// 使用示例
const assistant = new SmartAssistant();

await assistant.handleRequest(
  '帮我发一封邮件给 john@example.com,主题是项目更新'
);
// Claude 会:
// 1. 搜索工具 -> 找到 send_email
// 2. 调用 send_email 工具
// 3. 返回结果

示例 2: 数据分析助手

# 构建数据分析助手

class DataAnalysisAssistant:
    def __init__(self):
        self.tools = self.setup_tools()
    
    def setup_tools(self):
        return [
            {
                'name': 'load_data',
                'description': '从文件或数据库加载数据',
                'execute': self.load_data,
                'examples': [
                    {
                        'input': {'source': 'sales.csv'},
                        'output': {'rows': 1000, 'columns': ['date', 'amount', 'product']}
                    }
                ]
            },
            {
                'name': 'analyze_data',
                'description': '执行数据分析',
                'execute': self.analyze_data,
                'examples': [
                    {
                        'input': {
                            'data_id': 'data_123',
                            'analysis_type': 'summary_statistics'
                        },
                        'output': {
                            'mean': 1250.5,
                            'median': 1100,
                            'std': 450.2
                        }
                    }
                ]
            },
            {
                'name': 'create_visualization',
                'description': '创建数据可视化',
                'execute': self.create_viz,
                'examples': [
                    {
                        'input': {
                            'data_id': 'data_123',
                            'chart_type': 'line',
                            'x_axis': 'date',
                            'y_axis': 'amount'
                        },
                        'output': {'chart_url': 'https://...'}
                    }
                ]
            }
        ]
    
    async def process_request(self, request: str):
        """处理数据分析请求"""
        response = await claude.messages.create(
            model='claude-sonnet-4.5',
            tools=self.tools,
            messages=[{
                'role': 'user',
                'content': request
            }]
        )
        
        # 执行工具调用
        results = []
        for block in response.content:
            if block.type == 'tool_use':
                tool = next(t for t in self.tools if t['name'] == block.name)
                result = await tool['execute'](block.input)
                results.append(result)
        
        return results

# 使用示例
assistant = DataAnalysisAssistant()

await assistant.process_request("""
加载 sales.csv 文件,
分析销售趋势,
并创建一个折线图显示每月销售额
""")

# Claude 会:
# 1. 调用 load_data 加载数据
# 2. 调用 analyze_data 分析趋势
# 3. 调用 create_visualization 创建图表

最佳实践

💡 工具设计原则

1. 单一职责

// ❌ 不好: 一个工具做太多事情
const badTool = {
  name: 'user_operations',
  description: '用户相关的所有操作',
  // 太宽泛,难以使用
};

// ✅ 好: 每个工具职责单一
const goodTools = [
  {
    name: 'create_user',
    description: '创建新用户'
  },
  {
    name: 'update_user',
    description: '更新用户信息'
  },
  {
    name: 'delete_user',
    description: '删除用户'
  }
];

2. 清晰的描述

# ❌ 不好: 描述不清晰
{
    'name': 'process',
    'description': '处理数据'  # 太模糊
}

# ✅ 好: 描述具体明确
{
    'name': 'validate_email',
    'description': '验证电子邮件地址格式是否正确,返回布尔值'
}

3. 提供丰富的示例

// 为复杂工具提供多个示例

const complexTool = {
  name: 'query_api',
  description: '查询外部 API',
  examples: [
    {
      description: '简单 GET 请求',
      input: { method: 'GET', url: '/users' }
    },
    {
      description: 'POST 请求带参数',
      input: {
        method: 'POST',
        url: '/users',
        body: { name: 'John', email: 'john@example.com' }
      }
    },
    {
      description: '带认证的请求',
      input: {
        method: 'GET',
        url: '/protected',
        headers: { 'Authorization': 'Bearer token' }
      }
    }
  ]
};

⚡ 性能优化

1. 工具缓存

# 缓存常用工具定义

class ToolCache:
    def __init__(self):
        self.cache = {}
        self.access_count = {}
    
    def get_popular_tools(self, limit=10):
        """获取最常用的工具"""
        sorted_tools = sorted(
            self.access_count.items(),
            key=lambda x: x[1],
            reverse=True
        )
        return [self.cache[name] for name, _ in sorted_tools[:limit]]
    
    def record_access(self, tool_name):
        """记录工具访问"""
        self.access_count[tool_name] = \
            self.access_count.get(tool_name, 0) + 1

2. 批量工具调用

// 并行执行多个工具调用

async function executeToolsInParallel(toolCalls) {
  const promises = toolCalls.map(async (call) => {
    const tool = toolRegistry.get(call.name);
    return await tool.execute(call.input);
  });
  
  return await Promise.all(promises);
}

总结

Claude 的高级工具使用功能让你能够:

• ✅ 动态发现工具 - 按需搜索和使用
• ✅ 减少上下文消耗 - 使用工具 ID 引用
• ✅ 提供使用示例 - 帮助 Claude 学习
• ✅ 构建强大代理 - 实现复杂自动化

掌握这些功能,你可以构建更智能、更高效的 AI 代理应用!

---

相关文章

• Claude 核心功能详解
• Claude Sonnet 4.5 详解
• Claude Code 使用指南

官方资源

• 📖 工具使用文档
• 💻 Agent SDK
• 🎓 示例代码