tool-use-concepts

# 工具使用概念 本文档涵盖了使用 Claude API 进行工具使用的概念基础。有关特定语言的代码示例，请参阅 `python/`、`typescript/` 或其他语言文件夹。有关暴露哪些工具的决策启发式方法、如何在长期运行的智能体中管理上下文以及缓存策略，请参阅 `agent-design.md`。 ## 用户自定义工具 ### 工具定义结构 > **注意：** 使用工具运行器（测试版）时，工具模式会自动从您的函数签名（Python）、Zod 模式（TypeScript）、注解类（Java）、`jsonschema` 结构标签（Go）或 `BaseTool` 子类（Ruby）生成。下方的原始 JSON 模式格式适用于手动方法 — 包括 PHP 的 `BetaRunnableTool`（它在手写模式周围封装了一个运行闭包）— 或不支持工具运行器的 SDK。 每个工具都需要一个名称、描述和用于输入的 JSON 模式： { "name": "get_weather", "description": "获取指定地点的当前天气", "input_schema": { "type": "object", "properties": { "location": { "type": "string", "description": "城市和州，例如：San Francisco, CA" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "温度单位" } }, "required": ["location"] } } **工具定义的最佳实践：** - 使用清晰、描述性的名称（例如 `get_weather`, `search_database`, `send_email`） - 编写详细的描述 — Claude 使用这些描述来决定何时使用该工具 - 为每个属性包含描述 - 对具有固定值集的参数使用 `enum` - 在 `required` 中标记真正必需的参数；通过默认值使其他参数可选 --- ### 工具选择选项 控制 Claude 何时使用工具： | 值 | 行为 | | --------------------------------- | --------------------------------------------- | | `{"type": "auto"}` | Claude 决定是否使用工具（默认） | | `{"type": "any"}` | Claude 必须至少使用一个工具 | | `{"type": "tool", "name": "..."}` | Claude 必须使用指定的工具 | | `{"type": "none"}` | Claude 不能使用工具 | 任何 `tool_choice` 值也可以包含 `"disable_parallel_tool_use": true` 以强制 Claude 在每次响应中最多使用一个工具。默认情况下，Claude 可能会请求多个工具