--- 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 --- 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` | 使用正規表示式模式進行文字搜尋 | | Web fetch | `web_fetch` | 從 URL 擷取內容 | | Web search | `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`： ```bash cURL 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 '{ "name": "Coding Assistant", "model": "claude-opus-5-5", "tools": [ { "type": "agent_toolset_20260401", "configs": [ {"name": "web_fetch", "enabled": false} ] } ] }' ) ``` ```bash CLI ant apply agent.md ``` ```markdown --- name: Coding Assistant model: claude-opus-5-5 tools: - type: agent_toolset_20260401 configs: - name: web_fetch enabled: false --- ``` ```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 { Type = "agent_toolset_20260401", 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{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, Configs: []anthropic.BetaManagedAgentsAgentToolConfigParamsUnion{{ OfWebFetch: &anthropic.BetaManagedAgentsWebFetchToolConfigParams{ Enabled: anthropic.Bool(false), }, }}, }, }}, }) if err != nil { panic(err) } _ = agent ``` ```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() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .addConfig(BetaManagedAgentsWebFetchToolConfigParams.builder() .enabled(false) .build()) .build()) .build()); ``` ```php PHP use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params; use Anthropic\Beta\Agents\BetaManagedAgentsWebFetchToolConfigParams; $agent = $client->beta->agents->create( name: 'Coding Assistant', model: 'claude-opus-5-5', tools: [ BetaManagedAgentsAgentToolset20260401Params::with( type: 'agent_toolset_20260401', configs: [ BetaManagedAgentsWebFetchToolConfigParams::with(enabled: false), ], ), ], ); ``` ```ruby Ruby agent = client.beta.agents.create( name: "Coding Assistant", model: "claude-opus-5-5", tools: [ { type: :agent_toolset_20260401, configs: [ {name: :web_fetch, enabled: false} ] } ] ) ``` ### 停用特定工具 若要停用某個工具，請在其 `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 中的設定項目型別 Python、TypeScript、Go、Java、C#、Ruby 和 PHP 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` 的代理： ```bash cURL 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 '{ "name": "Weather Agent", "model": "claude-opus-5-5", "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"] } } ] }' ) ``` ```bash CLI ant apply agent.md ``` ```markdown --- name: Weather Agent model: claude-opus-5-5 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 --- ``` ```python Python agent = client.beta.agents.create( name="Weather Agent", model="claude-opus-5-5", 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"], }, }, ], ) ``` ```typescript TypeScript const agent = await client.beta.agents.create({ name: "Weather Agent", model: "claude-opus-5-5", 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"] } } ] }); ``` ```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 BetaManagedAgentsAgentToolset20260401Params { Type = "agent_toolset_20260401", }, new BetaManagedAgentsCustomToolParams { Type = "custom", Name = "get_weather", Description = "Get current weather for a location", InputSchema = new() { Properties = new Dictionary { ["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{{ 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{ Properties: map[string]any{ "location": map[string]any{ "type": "string", "description": "City name", }, }, Required: []string{"location"}, }, }, }}, }) if err != nil { panic(err) } _ = agent ``` ```java Java 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(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() .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\BetaManagedAgentsAgentToolset20260401Params; use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolInputSchema; use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolParams; $agent = $client->beta->agents->create( name: 'Weather Agent', model: 'claude-opus-5-5', tools: [ BetaManagedAgentsAgentToolset20260401Params::with( type: 'agent_toolset_20260401', ), BetaManagedAgentsCustomToolParams::with( type: 'custom', 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: "claude-opus-5-5", 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"] } } ] ) ``` 自訂工具的名稱不能以 `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 更難擷取重要資訊。 ## 後續步驟 控制網頁工具可存取的網站、限制擷取內容的上限，並將搜尋結果在地化。 將 MCP 伺服器連接到您的代理，以存取外部工具和資料來源。 控制代理工具和 MCP 工具的執行時機。 傳送事件、串流回應，並在執行途中中斷或重新導向您的工作階段。