工具

配置代理可用的工具。

Claude 托管代理提供了一组内置工具，Claude 可以在会话中自主使用这些工具。您可以通过在代理配置中指定来控制哪些工具可用。

自定义的用户定义工具也受支持。您的应用程序单独执行这些工具并将工具结果发送回 Claude；Claude 可以使用结果继续手头的任务。

Note

所有托管代理 API 请求都需要 managed-agents-2026-04-01 beta 头。SDK 会自动设置该 beta 头。

可用工具

代理工具集包括以下工具。当您在代理配置中包含工具集时，所有工具默认都是启用的。

工具	名称	描述
Bash	`bash`	在 shell 会话中执行 bash 命令
Read	`read`	从本地文件系统读取文件
Write	`write`	将文件写入本地文件系统
Edit	`edit`	在文件中执行字符串替换
Glob	`glob`	使用 glob 模式进行快速文件模式匹配
Grep	`grep`	使用正则表达式模式进行文本搜索
Web fetch	`web_fetch`	从 URL 获取内容
Web search	`web_search`	搜索网络获取信息

当工具输出超过 100K token 时，它会自动写入沙箱中的文件。模型接收带有文件路径的截断预览，并可以从那里读取完整内容。

配置工具集

在创建代理时使用 agent_toolset_20260401 启用完整工具集。使用 configs 数组禁用特定工具或覆盖其设置。

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "name": "Coding Assistant",
  "model": "claude-opus-4-7",
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "configs": [
        {"name": "web_fetch", "enabled": false}
      ]
    }
  ]
}
EOF
)

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-7
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
YAML

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-opus-4-7",
    tools=[
        {
            "type": "agent_toolset_20260401",
            "configs": [
                {"name": "web_fetch", "enabled": False},
            ],
        },
    ],
)

const agent = await client.beta.agents.create({
  name: "Coding Assistant",
  model: "claude-opus-4-7",
  tools: [
    {
      type: "agent_toolset_20260401",
      configs: [{ name: "web_fetch", enabled: false }]
    }
  ]
});

var agent = await client.Beta.Agents.Create(new()
{
    Name = "Coding Assistant",
    Model = new("claude-opus-4-7"),
    Tools =
    [
        new BetaManagedAgentsAgentToolset20260401Params
        {
            Type = "agent_toolset_20260401",
            Configs =
            [
                new() { Name = "web_fetch", Enabled = false },
            ],
        },
    ],
});

agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "Coding Assistant",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: "claude-opus-4-7",
	},
	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
			Configs: []anthropic.BetaManagedAgentsAgentToolConfigParams{{
				Name:    anthropic.BetaManagedAgentsAgentToolConfigParamsNameWebFetch,
				Enabled: anthropic.Bool(false),
			}},
		},
	}},
})
if err != nil {
	panic(err)
}
_ = agent

var agent = client.beta().agents().create(AgentCreateParams.builder()
    .name("Coding Assistant")
    .model(BetaManagedAgentsModel.CLAUDE_OPUS_4_7)
    .addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
        .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
        .addConfig(BetaManagedAgentsAgentToolConfigParams.builder()
            .name(BetaManagedAgentsAgentToolConfigParams.Name.WEB_FETCH)
            .enabled(false)
            .build())
        .build())
    .build());


$agent = $client->beta->agents->create(
    name: 'Coding Assistant',
    model: 'claude-opus-4-7',
    tools: [
        BetaManagedAgentsAgentToolset20260401Params::with(
            type: 'agent_toolset_20260401',
            configs: [
                BetaManagedAgentsAgentToolConfigParams::with(name: 'web_fetch', enabled: false),
            ],
        ),
    ],
);

agent = client.beta.agents.create(
  name: "Coding Assistant",
  model: "claude-opus-4-7",
  tools: [
    {
      type: :agent_toolset_20260401,
      configs: [
        {name: :web_fetch, enabled: false}
      ]
    }
  ]
)

禁用特定工具

要禁用工具，请在其配置条目中设置 enabled: false：

{
  "type": "agent_toolset_20260401",
  "configs": [
    { "name": "web_fetch", "enabled": false },
    { "name": "web_search", "enabled": false }
  ]
}

仅启用特定工具

要从全部禁用开始并仅启用您需要的工具，请将 default_config.enabled 设置为 false：

{
  "type": "agent_toolset_20260401",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "bash", "enabled": true },
    { "name": "read", "enabled": true },
    { "name": "write", "enabled": true }
  ]
}

自定义工具

除了内置工具，您还可以定义自定义工具。自定义工具类似于 Messages API 中的用户定义客户端工具。

自定义工具允许您扩展 Claude 的能力以执行更广泛的任务。每个工具定义一个契约：您指定可用的操作及其返回内容；Claude 决定何时以及如何调用它们。模型从不自行执行任何操作。它发出一个结构化请求，您的代码运行操作，结果流回对话中。

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "name": "Weather Agent",
  "model": "claude-opus-4-7",
  "tools": [
    {
      "type": "agent_toolset_20260401"
    },
    {
      "type": "custom",
      "name": "get_weather",
      "description": "Get current weather for a location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {"type": "string", "description": "City name"}
        },
        "required": ["location"]
      }
    }
  ]
}
EOF
)

ant beta:agents create <<'YAML'
name: Weather Agent
model: claude-opus-4-7
tools:
  - type: agent_toolset_20260401
  - type: custom
    name: get_weather
    description: Get current weather for a location
    input_schema:
      type: object
      properties:
        location:
          type: string
          description: City name
      required:
        - location
YAML

agent = client.beta.agents.create(
    name="Weather Agent",
    model="claude-opus-4-7",
    tools=[
        {
            "type": "agent_toolset_20260401",
        },
        {
            "type": "custom",
            "name": "get_weather",
            "description": "Get current weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City name"},
                },
                "required": ["location"],
            },
        },
    ],
)

const agent = await client.beta.agents.create({
  name: "Weather Agent",
  model: "claude-opus-4-7",
  tools: [
    { type: "agent_toolset_20260401" },
    {
      type: "custom",
      name: "get_weather",
      description: "Get current weather for a location",
      input_schema: {
        type: "object",
        properties: { location: { type: "string", description: "City name" } },
        required: ["location"]
      }
    }
  ]
});


var agent = await client.Beta.Agents.Create(new()
{
    Name = "Weather Agent",
    Model = new("claude-opus-4-7"),
    Tools =
    [
        new BetaManagedAgentsAgentToolset20260401Params
        {
            Type = "agent_toolset_20260401",
        },
        new BetaManagedAgentsCustomToolParams
        {
            Type = "custom",
            Name = "get_weather",
            Description = "Get current weather for a location",
            InputSchema = new()
            {
                Type = "object",
                Properties = new Dictionary<string, JsonElement>
                {
                    ["location"] = JsonSerializer.SerializeToElement(
                        new { type = "string", description = "City name" }
                    ),
                },
                Required = ["location"],
            },
        },
    ],
});

agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "Weather Agent",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: "claude-opus-4-7",
	},
	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
		},
	}, {
		OfCustom: &anthropic.BetaManagedAgentsCustomToolParams{
			Type:        anthropic.BetaManagedAgentsCustomToolParamsTypeCustom,
			Name:        "get_weather",
			Description: "Get current weather for a location",
			InputSchema: anthropic.BetaManagedAgentsCustomToolInputSchemaParam{
				Type: anthropic.BetaManagedAgentsCustomToolInputSchemaTypeObject,
				Properties: map[string]any{
					"location": map[string]any{
						"type":        "string",
						"description": "City name",
					},
				},
				Required: []string{"location"},
			},
		},
	}},
})
if err != nil {
	panic(err)
}
_ = agent

var agent = client.beta().agents().create(AgentCreateParams.builder()
    .name("Weather Agent")
    .model(BetaManagedAgentsModel.CLAUDE_OPUS_4_7)
    .addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
        .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
        .build())
    .addTool(BetaManagedAgentsCustomToolParams.builder()
        .type(BetaManagedAgentsCustomToolParams.Type.CUSTOM)
        .name("get_weather")
        .description("Get current weather for a location")
        .inputSchema(BetaManagedAgentsCustomToolInputSchema.builder()
            .type(BetaManagedAgentsCustomToolInputSchema.Type.OBJECT)
            .properties(BetaManagedAgentsCustomToolInputSchema.Properties.builder()
                .putAdditionalProperty("location", JsonValue.from(Map.of(
                    "type", "string",
                    "description", "City name")))
                .build())
            .addRequired("location")
            .build())
        .build())
    .build());

use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolInputSchema;
use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolParams;

$agent = $client->beta->agents->create(
    name: 'Weather Agent',
    model: 'claude-opus-4-7',
    tools: [
        BetaManagedAgentsAgentToolset20260401Params::with(
            type: 'agent_toolset_20260401',
        ),
        BetaManagedAgentsCustomToolParams::with(
            type: 'custom',
            name: 'get_weather',
            description: 'Get current weather for a location',
            inputSchema: BetaManagedAgentsCustomToolInputSchema::with(
                type: 'object',
                properties: ['location' => ['type' => 'string', 'description' => 'City name']],
                required: ['location'],
            ),
        ),
    ],
);

agent = client.beta.agents.create(
  name: "Weather Agent",
  model: "claude-opus-4-7",
  tools: [
    {type: :agent_toolset_20260401},
    {
      type: :custom,
      name: "get_weather",
      description: "Get current weather for a location",
      input_schema: {
        type: :object,
        properties: {location: {type: "string", description: "City name"}},
        required: ["location"]
      }
    }
  ]
)

在代理级别定义工具后，代理将在会话过程中调用这些工具。请参阅会话事件流了解完整流程。

自定义工具定义的最佳实践

**提供极其详细的描述。**这是工具性能中最重要的因素。您的描述应解释工具的功能、何时应使用（以及何时不应使用）、每个参数的含义及其如何影响工具的行为，以及任何重要的注意事项或限制。您为 Claude 提供的关于工具的上下文越多，它就越能更好地决定何时以及如何使用它们。每个工具描述至少 3-4 句话，如果工具很复杂则更多。
**将相关操作合并为更少的工具。**与其为每个操作创建单独的工具（create_pr、review_pr、merge_pr），不如将它们分组到一个带有 action 参数的单一工具中。更少、更强大的工具减少选择歧义，使您的工具表面更容易被 Claude 导航。
**在工具名称中使用有意义的命名空间。**当您的工具跨越多个服务或资源时，用资源为名称添加前缀（例如 db_query、storage_read）。随着库的增长，这使工具选择变得明确。
**设计工具响应仅返回高信号信息。**返回语义化的、稳定的标识符（例如 slug 或 UUID），而不是不透明的内部引用，并且只包含 Claude 推理下一步所需的字段。膨胀的响应浪费上下文并使 Claude 更难提取重要内容。