name: create-tool description: 使用 @tool 装饰器为 Claude Agent SDK 生成自定义工具模板。在添加新工具到自定义代理时使用。 argument-hint: [工具名称] [描述] allowed-tools: Read, Write, Glob

创建工具

使用 @tool 装饰器生成自定义工具模板。

参数

$1: 工具名称 (snake_case)
$ARGUMENTS: 工具描述和目的 (名称之后)

步骤

您正在创建一个用于自定义代理的自定义工具。

步骤 1: 解析参数

提取：

从 $1 获取工具名称 (必需, snake_case)
从剩余参数获取描述

如果未提供名称，停止并询问工具名称。如果未提供描述，停止并询问工具目的。

步骤 2: 确定参数

基于工具目的，确定：

工具需要什么输入？
哪些是必需的 vs 可选的？
类型是什么 (str, int, float, bool)？

步骤 3: 生成工具定义

使用 @tool 装饰器创建工具：

from typing import Any
from claude_agent_sdk import tool

@tool(
    "[tool_name]",
    "[工具描述 - 代理何时使用此工具]",
    {
        "param1": str,
        "param2": int,
    }
)
async def [tool_name](args: dict[str, Any]) -> dict[str, Any]:
    """
    [简要文档字符串]
    """
    try:
        # 提取参数
        param1 = args["param1"]
        param2 = args.get("param2", default_value)

        # 验证输入
        if not param1:
            return {
                "content": [{"type": "text", "text": "错误: param1 必填"}],
                "is_error": True
            }

        # 执行操作
        result = perform_operation(param1, param2)

        # 返回成功
        return {
            "content": [{"type": "text", "text": str(result)}]
        }

    except Exception as e:
        return {
            "content": [{"type": "text", "text": f"错误: {str(e)}"}],
            "is_error": True
        }

步骤 4: 生成 MCP 服务器设置

from claude_agent_sdk import create_sdk_mcp_server

# 创建带有工具的服务器
[server_name]_server = create_sdk_mcp_server(
    name="[server_name]",
    version="1.0.0",
    tools=[[tool_name]]
)

步骤 5: 生成代理配置

from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient

options = ClaudeAgentOptions(
    mcp_servers={"[server_name]": [server_name]_server},
    allowed_tools=["mcp__[server_name]__[tool_name]"],
    system_prompt=system_prompt,
    model="opus",
)

# 重要：使用 ClaudeSDKClient 用于自定义工具
async with ClaudeSDKClient(options=options) as client:
    await client.query(prompt)
    async for message in client.receive_response():
        pass

输出

## 工具已创建

**名称:** [tool_name]
**服务器:** [server_name]
**工具 ID:** mcp__[server_name]__[tool_name]

### 工具定义

```python
[生成的 @tool 装饰函数]

MCP 服务器

[生成的服务器设置]

代理配置

[生成的配置]

参数

名称	类型	必需	描述
param1	str	是	[描述]
param2	int	否	[描述], 默认: [值]

使用示例

代理提示: “[触发工具的示例提示]” 预期调用: [tool_name](param1=“值”, param2=10) 预期结果: “[预期输出]”

测试

# 直接测试工具
result = await [tool_name]({"param1": "测试", "param2": 10})
assert "content" in result
assert not result.get("is_error", False)

下一步

将工具添加到 MCP 服务器
配置代理以访问工具
单独测试工具
通过代理测试工具

注释

参见 @tool-design 技能以了解设计工作流程
参见 @custom-tool-patterns.md 以了解模式
关键：使用 ClaudeSDKClient (而非 query()) 用于自定义工具