---
title: 工具
url: https://platform.claude.com/docs/zh-TW/managed-agents/tools
description: 設定您的代理可使用的工具。
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
  zdr:
    eligibility: not-eligible
    note: 不具 ZDR 適用資格，自行託管的 Managed Agents 除外。工作階段是具狀態的資源；對話記錄會保留至您將其刪除為止。
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
    Claude Platform on AWS: beta
---

Claude Managed Agents 提供一組內建工具，Claude 可以在 [session](https://platform.claude.com/docs/zh-TW/managed-agents/sessions)（工作階段）中自主使用這些工具。您可以透過在代理設定中指定工具，來控制哪些工具可供使用。

Claude Managed Agents 也支援自訂的使用者定義工具。您的應用程式會另外執行這些工具，並將結果傳回給 Claude，Claude 再利用這些結果繼續執行任務。若要為代理提供來自 MCP 伺服器的工具，請改用 [MCP 連接器](https://platform.claude.com/docs/zh-TW/managed-agents/mcp-connector)。

## 可用工具

代理工具集包含下列工具。當您在代理設定中納入此工具集時，所有工具預設皆為啟用。

| 工具 | 名稱 | 說明 |
| ----- | ----- | ----- |
| Bash | `bash` | 在 shell 工作階段中執行 bash 命令 |
| Read | `read` | 從沙箱檔案系統讀取檔案 |
| Write | `write` | 將檔案寫入沙箱檔案系統 |
| Edit | `edit` | 在檔案中執行字串取代 |
| Glob | `glob` | 使用 glob 模式執行快速的檔案模式比對 |
| Grep | `grep` | 使用 regex 模式搜尋文字 |
| 網頁擷取 | `web_fetch` | 從 URL 擷取內容 |
| 網頁搜尋 | `web_search` | 在網路上搜尋資訊 |

當工具輸出超過 100,000 個字元（約 25,000 個 token）時，會自動寫入 [sandbox](https://platform.claude.com/docs/zh-TW/managed-agents/environments)（沙箱）中的檔案。模型會收到包含檔案路徑的截斷預覽，並可從該處讀取完整內容。

## 設定工具集

建立代理時，使用 `agent_toolset_20260401` 啟用完整工具集。使用 `configs` (csharp, go: `Configs`) 陣列來停用特定工具或覆寫其設定。每個項目以其 `name` (csharp, go: `Name`) 識別，其值取自[可用工具](https://platform.claude.com/docs/zh-TW/managed-agents/tools#available-tools)中的「名稱」欄。項目也接受一個選用的 `type` (csharp, go: `Type`) 欄位，其值相同。

每個設定項目也可以設定 `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`)。此政策控制工具的呼叫是無需確認即執行、需要確認，還是交由伺服器，由伺服器評估每個呼叫。請參閱[權限政策](https://platform.claude.com/docs/zh-TW/managed-agents/permission-policies)以了解可用的政策類型。

下列範例啟用工具集並停用 `web_fetch`：

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/agents \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "name": "Coding Assistant",
      "model": "claude-opus-5-5",
      "tools": [
        {
          "type": "agent_toolset_20260401",
          "configs": [
            {"name": "web_fetch", "enabled": false}
          ]
        }
      ]
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply agent.md
    ```

    <File filename="agent.md">
      ```markdown
      ---
      name: Coding Assistant
      model: claude-opus-5-5
      tools:
        - type: agent_toolset_20260401
          configs:
            - name: web_fetch
              enabled: false
      ---
      ```
    </File>
  </CodeGroupItem>

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

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

  ```csharp C#
  using Anthropic.Models.Beta.Agents;

  var agent = await client.Beta.Agents.Create(new()
  {
      Name = "Coding Assistant",
      Model = BetaManagedAgentsModel.ClaudeOpus5_5,
      Tools =
      [
          new BetaManagedAgentsAgentToolset20260401Params
          {
              Configs =
              [
                  new BetaManagedAgentsWebFetchToolConfigParams { Enabled = false },
              ],
          },
      ],
  });
  ```

  ```go Go
  agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
  	Name: "Coding Assistant",
  	Model: anthropic.BetaManagedAgentsModelConfigParams{
  		ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5,
  	},
  	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
  		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
  			Configs: []anthropic.BetaManagedAgentsAgentToolConfigParamsUnion{{
  				OfWebFetch: &anthropic.BetaManagedAgentsWebFetchToolConfigParams{
  					Enabled: anthropic.Bool(false),
  				},
  			}},
  		},
  	}},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  import com.anthropic.models.beta.agents.*;

  var agent = client.beta().agents().create(AgentCreateParams.builder()
      .name("Coding Assistant")
      .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
      .addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
          .addConfig(BetaManagedAgentsWebFetchToolConfigParams.builder()
              .enabled(false)
              .build())
          .build())
      .build());
  ```

  ```php PHP
  use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
  use Anthropic\Beta\Agents\BetaManagedAgentsModel;
  use Anthropic\Beta\Agents\BetaManagedAgentsWebFetchToolConfigParams;

  $agent = $client->beta->agents->create(
      name: 'Coding Assistant',
      model: BetaManagedAgentsModel::CLAUDE_OPUS_5_5,
      tools: [
          BetaManagedAgentsAgentToolset20260401Params::with(
              configs: [
                  BetaManagedAgentsWebFetchToolConfigParams::with(enabled: false),
              ],
          ),
      ],
  );
  ```

  ```ruby Ruby
  agent = client.beta.agents.create(
    name: "Coding Assistant",
    model: Anthropic::Beta::BetaManagedAgentsModel::CLAUDE_OPUS_5_5,
    tools: [
      {
        type: :agent_toolset_20260401,
        configs: [
          {name: :web_fetch, enabled: false}
        ]
      }
    ]
  )
  ```
</CodeGroup>

### 停用特定工具

若要停用某個工具，請在其 `configs` 項目中設定 `enabled: false`：

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

### 僅啟用特定工具

`default_config` 物件為工具集中的每個工具設定基準，而各工具的 `configs` 項目會覆寫它。若要從全部關閉開始，僅啟用您需要的工具，請將 `default_config.enabled` 設為 `false`：

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

### 限制網頁搜尋與網頁擷取

`web_search` 和 `web_fetch` 項目也接受網域清單、擷取內容的上限，以及搜尋位置。請參閱[限制網頁搜尋與網頁擷取的網域](https://platform.claude.com/docs/zh-TW/managed-agents/tools-web-restrictions)。

### SDK 中的設定項目型別

SDK 會依工具為每個 `configs` (csharp, go: `Configs`) 項目指定類型。此類型是一個聯集（union），每個內建工具各有一個成員，並以 `type` (csharp, go: `Type`) 區分。

在 Go、Java、C# 和 PHP 中，您需要從具型別的值建構項目，而非使用一般的字典或雜湊。在這些 SDK 中，`configs` (csharp, go: `Configs`) 的元素型別就是該聯集本身，因此請從各工具的成員型別建構每個項目。

建構項目時，您可以省略 `type` (csharp, go: `Type`)，因為伺服器會從 `name` (csharp, go: `Name`) 推斷它。回應中一律會包含此欄位。此型別定義不會改變項目序列化後的 JSON。項目僅設定 `name`、`enabled` 和 `permission_policy` 的請求，無論是否包含 `type` 皆為有效。

## 自訂工具

自訂工具類似於 Messages API 中的[使用者定義用戶端工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/how-tool-use-works#user-defined-tools-client-executed)。您指定有哪些操作可用以及它們傳回什麼，而 Claude 決定何時以及如何呼叫它們。

Claude 不會自行執行自訂工具。它會發出結構化請求，由您的程式碼執行該操作，然後您將結果傳回工作階段。

下列範例建立一個具有一個自訂工具 `get_weather` 且不含任何內建工具的代理：

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/agents \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "name": "Weather Agent",
      "model": "claude-opus-5-5",
      "tools": [
        {
          "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"]
          }
        }
      ]
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply agent.md
    ```

    <File filename="agent.md">
      ```markdown
      ---
      name: Weather Agent
      model: claude-opus-5-5
      tools:
        - 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
      ---
      ```
    </File>
  </CodeGroupItem>

  ```python Python
  agent = client.beta.agents.create(
      name="Weather Agent",
      model="claude-opus-5-5",
      tools=[
          {
              "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"],
              },
          },
      ],
  )
  ```

  ```typescript TypeScript
  const agent = await client.beta.agents.create({
    name: "Weather Agent",
    model: "claude-opus-5-5",
    tools: [
      {
        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"]
        }
      }
    ]
  });
  ```

  ```csharp C#
  using System.Text.Json;
  using Anthropic.Models.Beta.Agents;

  var agent = await client.Beta.Agents.Create(new()
  {
      Name = "Weather Agent",
      Model = BetaManagedAgentsModel.ClaudeOpus5_5,
      Tools =
      [
          new BetaManagedAgentsCustomToolParams
          {
              Name = "get_weather",
              Description = "Get current weather for a location",
              InputSchema = new()
              {
                  Properties = new Dictionary<string, JsonElement>
                  {
                      ["location"] = JsonSerializer.SerializeToElement(
                          new { type = "string", description = "City name" }
                      ),
                  },
                  Required = ["location"],
              },
          },
      ],
  });
  ```

  ```go Go
  agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
  	Name: "Weather Agent",
  	Model: anthropic.BetaManagedAgentsModelConfigParams{
  		ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5,
  	},
  	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
  		OfCustom: &anthropic.BetaManagedAgentsCustomToolParams{
  			Name:        "get_weather",
  			Description: "Get current weather for a location",
  			InputSchema: anthropic.BetaManagedAgentsCustomToolInputSchemaParam{
  				Properties: map[string]any{
  					"location": map[string]any{
  						"type":        "string",
  						"description": "City name",
  					},
  				},
  				Required: []string{"location"},
  			},
  		},
  	}},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  import com.anthropic.core.JsonValue;
  import com.anthropic.models.beta.agents.*;
  import java.util.Map;

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

  ```php PHP
  use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolInputSchema;
  use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolParams;
  use Anthropic\Beta\Agents\BetaManagedAgentsModel;

  $agent = $client->beta->agents->create(
      name: 'Weather Agent',
      model: BetaManagedAgentsModel::CLAUDE_OPUS_5_5,
      tools: [
          BetaManagedAgentsCustomToolParams::with(
              name: 'get_weather',
              description: 'Get current weather for a location',
              inputSchema: BetaManagedAgentsCustomToolInputSchema::with(
                  properties: ['location' => ['type' => 'string', 'description' => 'City name']],
                  required: ['location'],
              ),
          ),
      ],
  );
  ```

  ```ruby Ruby
  agent = client.beta.agents.create(
    name: "Weather Agent",
    model: Anthropic::Beta::BetaManagedAgentsModel::CLAUDE_OPUS_5_5,
    tools: [
      {
        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"]
        }
      }
    ]
  )
  ```
</CodeGroup>

新自訂工具的名稱不能以 `mcp__` 或 `ant__` 開頭，也不能與內建代理工具的名稱相同。違反此規則的請求會傳回 400 錯誤。不過，既有的自訂工具名稱可能以 `ant__` 開頭。具有此類工具的代理，只有在更新所傳送的 `tools` (csharp, go: `Tools`) 不含該名稱時才會接受更新，因此請在下次更新時重新命名或移除該工具。若此類工具存在於新工作階段的代理上（套用任何[覆寫](https://platform.claude.com/docs/zh-TW/managed-agents/sessions#override-agent-configuration-for-a-session)之後）、存在於 `subagents` (csharp, go: `Subagents`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單中的代理上，或存在於 `workflows` (csharp, go: `Workflows`) 的 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 清單中的代理上，該新工作階段會以 400 錯誤遭到拒絕。已存在的工作階段不受影響。

代理會在工作階段期間呼叫其自訂工具。若要接收呼叫並傳回結果，請參閱[回應會暫停工作階段的工具呼叫](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming#handling-custom-tool-calls)。

對於在自行託管沙箱中執行的工作階段，環境 worker 可以[從沙箱提供自訂工具](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-custom-tools)。這些工具可以包括包裝您網路內 MCP 伺服器的工具。

### 自訂工具定義的最佳實務

* **提供極為詳細的說明。** 這是影響工具效能最重要的因素。您能提供給 Claude 關於工具的上下文越多，它就越能判斷何時以及如何使用這些工具。每個工具說明以三到四句為目標，若工具較複雜則可更多。您的說明應涵蓋：

  * 工具的功能
  * 何時使用，以及何時不應使用
  * 每個參數的意義，以及它如何影響工具的行為
  * 任何重要的注意事項或限制

* **將相關操作整合為較少的工具。** 將 `create_pr`、`review_pr` 和 `merge_pr` 等動作歸納為單一工具，並搭配 `action` 參數。較少但功能更強的工具可減少選擇上的模糊性，並讓 Claude 更容易瀏覽您的工具介面。

* **在工具名稱中使用有意義的命名空間。** 當您的工具橫跨多個服務或資源時，請以資源作為名稱前綴（例如 `db_query` 或 `storage_read`）。隨著您的工具庫成長，這能讓工具選擇毫無歧義。

* **設計工具回應時僅傳回高訊號資訊。** 傳回具語意且穩定的識別碼（例如 slug 或 UUID），而非不透明的內部參照。僅包含 Claude 判斷下一步所需的欄位。臃腫的回應會浪費上下文，並讓 Claude 更難擷取重要資訊。

## 後續步驟

<CardGroup cols={2}>
  <Card title="限制網頁搜尋與網頁擷取的網域" icon="shield" href="https://platform.claude.com/docs/zh-TW/managed-agents/tools-web-restrictions">
    控制網頁工具可存取的網站、限制擷取內容的上限，並將搜尋結果在地化。
  </Card>

  <Card title="MCP 連接器" icon="link" href="https://platform.claude.com/docs/zh-TW/managed-agents/mcp-connector">
    將 MCP 伺服器連接到您的代理，以存取外部工具和資料來源。
  </Card>

  <Card title="權限政策" icon="lock" href="https://platform.claude.com/docs/zh-TW/managed-agents/permission-policies">
    控制代理工具和 MCP 工具的執行時機。
  </Card>

  <Card title="工作階段事件串流" icon="lightning" href="https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming">
    在工作階段執行期間傳送事件、串流回應，以及中斷或重新導向您的工作階段。
  </Card>
</CardGroup>

## 可用性

代理工具集在所有模型上處於 Beta 階段。

### API 支援

#### [Managed Agents](https://platform.claude.com/docs/zh-TW/managed-agents/overview)

* 可用性：可用

| 狀態 | 雲端平台 |
| ----- | ----- |
| Beta | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws) |

### 必要的 Beta 標頭

[Beta 標頭概覽](https://platform.claude.com/docs/zh-TW/api/beta-headers)

Beta 標頭可讓您在實驗性功能與新模型能力成為標準 API 的一部分之前搶先存取。

* `managed-agents-2026-04-01`

### 資料處理

[資料處理概覽](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention#feature-eligibility)

| 項目 | 零資料保留 | HIPAA |
| ----- | ----- | ----- |
| 狀態 | 不符合資格 | 不符合資格 |
| 詳細資訊 | 不具 ZDR 適用資格，自行託管的 Managed Agents 除外。工作階段是具狀態的資源；對話記錄會保留至您將其刪除為止。 [深入了解](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-data-and-access#how-long-data-is-kept) | 不具 HIPAA 適用資格。適用於所有 Managed Agents 子功能。 |

適用端點：

* `/v1/agents`
* `/v1/sessions`
* `/v1/environments`
