---
title: 教學：建構一個使用工具的代理
url: https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/build-a-tool-using-agent
description: 從單一工具呼叫到可用於正式環境的代理迴圈的引導式逐步教學。
---
本教學以五個同心環的方式建構一個行事曆管理代理。每一環都是一個完整、可執行的程式，並在前一環的基礎上恰好新增一個概念。到最後，您將親手寫出「agentic loop」（代理迴圈），然後再以 Tool Runner SDK 抽象層取代它。
範例工具是 `create_calendar_event`。它的 schema 使用了巢狀物件、陣列與選用欄位，因此您將看到 Claude 如何處理貼近實務的輸入結構，而非單一的扁平字串。
每一環都可獨立執行。將任何一環複製到新檔案中，無需先前各環的程式碼即可執行。
## 第 1 環：單一工具、單一回合
最小可行的工具使用程式：一個工具、一則使用者訊息、一次工具呼叫、一個結果。程式碼附有大量註解，讓您能將每一行對應到[工具使用生命週期](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/how-tool-use-works)。
請求會在使用者訊息旁一併送出 `tools` 陣列。當 Claude 判斷需要進行工具呼叫時，回應會帶著 `stop_reason: "tool_use"` 以及一個 `tool_use` 內容區塊返回，其中包含工具名稱、唯一的 `id`，以及結構化的 `input`。您的程式碼執行該工具，然後在 `tool_result` 區塊中將結果送回，其 `tool_use_id` 與呼叫中的 `id` 相符。
```bash cURL
#!/bin/bash
# Ring 1: Single tool, single turn.
# This workflow needs more logic than a single shell command.
# Use the Claude SDK to run it.
```
```bash CLI
#!/usr/bin/env bash
# Ring 1: Single tool, single turn.
# This workflow needs more logic than a single shell command.
# Use the Claude SDK to run it.
```
```python Python
# 第 1 環：單一工具，單一回合。
import json
import anthropic
# 建立一個用戶端。它會從環境變數讀取 ANTHROPIC_API_KEY。
client = anthropic.Anthropic()
# 定義一個工具。input_schema 是一個 JSON Schema 物件，用於描述
# Claude 呼叫此工具時應傳遞的引數。此 schema
# 包含巢狀物件（recurrence）、陣列（attendees）以及選用
# 欄位，這比扁平的字串引數更接近真實世界的工具。
tools = [
{
"name": "create_calendar_event",
"description": "Create a calendar event with attendees and optional recurrence.",
"input_schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"start": {"type": "string", "format": "date-time"},
"end": {"type": "string", "format": "date-time"},
"attendees": {
"type": "array",
"items": {"type": "string", "format": "email"},
},
"recurrence": {
"type": "object",
"properties": {
"frequency": {"enum": ["daily", "weekly", "monthly"]},
"count": {"type": "integer", "minimum": 1},
},
},
},
"required": ["title", "start", "end"],
},
}
]
# 將使用者的請求連同工具定義一起傳送。Claude 會根據
# 請求內容與工具描述來決定是否呼叫該工具。
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "auto", "disable_parallel_tool_use": True},
messages=[
{
"role": "user",
"content": "Schedule a 30-minute sync with alice@example.com and bob@example.com on Monday, March 30, 2026 at 10am.",
}
],
)
# 當 Claude 呼叫工具時，回應的 stop_reason 為 "tool_use"，
# 且 content 陣列中會包含一個 tool_use 區塊以及任何文字內容。
print(f"stop_reason: {response.stop_reason}")
# 尋找 tool_use 區塊。回應中可能在 tool_use 區塊之前包含文字
# 區塊，因此請掃描 content 陣列，而非假設其位置。
tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Tool: {tool_use.name}")
print(f"Input: {tool_use.input}")
# 執行該工具。在真實系統中，這會呼叫您的行事曆 API。
# 此處結果為硬編碼，以保持範例的獨立完整性。
result = {"event_id": "evt_123", "status": "created"}
# 將結果回傳。tool_result 區塊需放在 user 訊息中，且其
# tool_use_id 必須與上方 tool_use 區塊的 id 相符。同時
# 納入助理先前的回應，讓 Claude 擁有完整的對話歷史。
followup = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "auto", "disable_parallel_tool_use": True},
messages=[
{
"role": "user",
"content": "Schedule a 30-minute sync with alice@example.com and bob@example.com on Monday, March 30, 2026 at 10am.",
},
{"role": "assistant", "content": response.content},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": tool_use.id,
"content": json.dumps(result),
}
],
},
],
)
# 取得工具結果後，Claude 會產生最終的自然語言
# 回答，且 stop_reason 變為 "end_turn"。
print(f"stop_reason: {followup.stop_reason}")
final_text = next(block for block in followup.content if block.type == "text")
print(final_text.text)
```
```typescript TypeScript
// 第 1 環：單一工具，單一回合。
import Anthropic from "@anthropic-ai/sdk";
// 建立用戶端。它會從環境變數讀取 ANTHROPIC_API_KEY。
const client = new Anthropic();
// 定義一個工具。input_schema 是一個 JSON Schema 物件，用於描述
// Claude 呼叫此工具時應傳遞的引數。此結構描述
// 包含巢狀物件（recurrence）、陣列（attendees）以及選用
// 欄位，這比扁平的字串引數更接近真實世界的工具。
const tools: Anthropic.Tool[] = [
{
name: "create_calendar_event",
description: "Create a calendar event with attendees and optional recurrence.",
input_schema: {
type: "object",
properties: {
title: { type: "string" },
start: { type: "string", format: "date-time" },
end: { type: "string", format: "date-time" },
attendees: {
type: "array",
items: { type: "string", format: "email" }
},
recurrence: {
type: "object",
properties: {
frequency: { enum: ["daily", "weekly", "monthly"] },
count: { type: "integer", minimum: 1 }
}
}
},
required: ["title", "start", "end"]
}
}
];
// 將使用者的請求連同工具定義一起傳送。Claude 會根據
// 請求內容與工具描述來決定是否呼叫該工具。
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
tools,
tool_choice: { type: "auto", disable_parallel_tool_use: true },
messages: [
{
role: "user",
content:
"Schedule a 30-minute sync with alice@example.com and bob@example.com on Monday, March 30, 2026 at 10am."
}
]
});
// 當 Claude 呼叫工具時，回應的 stop_reason 為 "tool_use"，
// 且 content 陣列會包含一個 tool_use 區塊以及任何文字內容。
console.log(`stop_reason: ${response.stop_reason}`);
// 尋找 tool_use 區塊。回應可能在 tool_use 區塊之前包含文字
// 區塊，因此請掃描 content 陣列，而非假設其位置。
const toolUse = response.content.find((block) => block.type === "tool_use")!;
console.log(`Tool: ${toolUse.name}`);
console.log(`Input: ${JSON.stringify(toolUse.input)}`);
// 執行工具。在真實系統中，這會呼叫您的行事曆 API。
// 此處結果為硬編碼，以保持範例的獨立完整性。
const result = { event_id: "evt_123", status: "created" };
// 將結果回傳。tool_result 區塊須放在 user 訊息中，且其
// tool_use_id 必須與上方 tool_use 區塊的 id 相符。同時包含
// 助理先前的回應，以便 Claude 擁有完整的對話歷史。
const followup = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
tools,
tool_choice: { type: "auto", disable_parallel_tool_use: true },
messages: [
{
role: "user",
content:
"Schedule a 30-minute sync with alice@example.com and bob@example.com on Monday, March 30, 2026 at 10am."
},
{ role: "assistant", content: response.content },
{
role: "user",
content: [
{
type: "tool_result",
tool_use_id: toolUse.id,
content: JSON.stringify(result)
}
]
}
]
});
// 取得工具結果後，Claude 會產生最終的自然語言
// 回答，且 stop_reason 變為 "end_turn"。
console.log(`stop_reason: ${followup.stop_reason}`);
for (const block of followup.content) {
if (block.type === "text") {
console.log(block.text);
}
}
```
```csharp C#
// 第 1 環：單一工具，單一回合。
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text.Json;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages;
// 建立一個用戶端。它會從環境變數讀取 ANTHROPIC_API_KEY。
AnthropicClient client = new();
// 定義一個工具。輸入結構描述是一個 JSON Schema 物件，用於描述
// Claude 呼叫此工具時應傳遞的引數。此結構描述
// 包含巢狀物件（recurrence）、陣列（attendees）以及選用
// 欄位，這比單純的扁平字串引數更接近真實世界的工具。
List tools =
[
new ToolUnion(new Tool()
{
Name = "create_calendar_event",
Description = "Create a calendar event with attendees and optional recurrence.",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["title"] = JsonSerializer.SerializeToElement(new { type = "string" }),
["start"] = JsonSerializer.SerializeToElement(new { type = "string", format = "date-time" }),
["end"] = JsonSerializer.SerializeToElement(new { type = "string", format = "date-time" }),
["attendees"] = JsonSerializer.SerializeToElement(new
{
type = "array",
items = new { type = "string", format = "email" },
}),
["recurrence"] = JsonSerializer.SerializeToElement(new
{
type = "object",
properties = new
{
frequency = new { @enum = new[] { "daily", "weekly", "monthly" } },
count = new { type = "integer", minimum = 1 },
},
}),
},
Required = ["title", "start", "end"],
},
}),
];
// 要求每回合最多呼叫一次工具，以便下方的單回合流程
// 保持可預測性。
var toolChoice = new ToolChoice(new ToolChoiceAuto { DisableParallelToolUse = true });
const string userPrompt =
"Schedule a 30-minute sync with alice@example.com and bob@example.com on Monday, March 30, 2026 at 10am.";
// 將使用者的請求連同工具定義一起傳送。Claude 會根據
// 請求內容與工具描述來決定是否呼叫該工具。
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools = tools,
ToolChoice = toolChoice,
Messages = [new() { Role = Role.User, Content = userPrompt }],
});
// 當 Claude 呼叫工具時，回應的 stop_reason 為 "tool_use"，
// 且 content 陣列中會包含一個 tool_use 區塊以及任何文字。
Console.WriteLine($"stop_reason: {response.StopReason?.Raw()}");
// 尋找 tool_use 區塊。回應中可能在 tool_use 區塊之前包含文字
// 區塊，因此請掃描 content 陣列，而非假設其位置。
ToolUseBlock? toolUse = null;
foreach (var block in response.Content)
{
if (block.TryPickToolUse(out var picked))
{
toolUse = picked;
break;
}
}
Console.WriteLine($"Tool: {toolUse!.Name}");
Console.WriteLine($"Input: {JsonSerializer.Serialize(toolUse.Input)}");
// 執行該工具。在真實系統中，這會呼叫您的行事曆 API。
// 此處結果為硬編碼，以保持範例的獨立完整性。
var result = """{"event_id": "evt_123", "status": "created"}""";
// 將結果回傳。tool_result 區塊需放在 user 訊息中，且其
// tool_use_id 必須與上方 tool_use 區塊的 id 相符。同時包含
// 助理先前的回應，以便 Claude 擁有完整的歷史記錄。
List toolResults =
[
new ContentBlockParam(new ToolResultBlockParam()
{
ToolUseID = toolUse.ID,
Content = result,
}),
];
var followup = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools = tools,
ToolChoice = toolChoice,
Messages =
[
new() { Role = Role.User, Content = userPrompt },
new() { Role = Role.Assistant, Content = response.Content.Select(block => new ContentBlockParam(block.Json)).ToList() },
new() { Role = Role.User, Content = new MessageParamContent(toolResults) },
],
});
// 取得工具結果後，Claude 會產生最終的自然語言
// 回答，且 stop_reason 會變為 "end_turn"。
Console.WriteLine($"stop_reason: {followup.StopReason?.Raw()}");
foreach (var block in followup.Content)
{
if (block.TryPickText(out var text))
{
Console.WriteLine(text.Text);
}
}
```
```go Go
// 第 1 環：單一工具，單一回合。
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
// 建立一個用戶端。它會從環境變數讀取 ANTHROPIC_API_KEY。
client := anthropic.NewClient()
ctx := context.Background()
// 定義一個工具。輸入結構描述是一個 JSON Schema 物件，用於描述
// Claude 呼叫此工具時應傳遞的引數。此結構描述
// 包含巢狀物件（recurrence）、陣列（attendees）以及選用
// 欄位，這比單純的扁平字串引數更接近真實世界的工具。
tools := []anthropic.ToolUnionParam{
{OfTool: &anthropic.ToolParam{
Name: "create_calendar_event",
Description: anthropic.String("Create a calendar event with attendees and optional recurrence."),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"title": map[string]any{"type": "string"},
"start": map[string]any{"type": "string", "format": "date-time"},
"end": map[string]any{"type": "string", "format": "date-time"},
"attendees": map[string]any{
"type": "array",
"items": map[string]any{"type": "string", "format": "email"},
},
"recurrence": map[string]any{
"type": "object",
"properties": map[string]any{
"frequency": map[string]any{"enum": []string{"daily", "weekly", "monthly"}},
"count": map[string]any{"type": "integer", "minimum": 1},
},
},
},
Required: []string{"title", "start", "end"},
},
}},
}
// 要求每回合最多呼叫一次工具，以便下方的單回合流程
// 保持可預測性。
toolChoice := anthropic.ToolChoiceUnionParam{
OfAuto: &anthropic.ToolChoiceAutoParam{DisableParallelToolUse: anthropic.Bool(true)},
}
userMessage := anthropic.NewUserMessage(anthropic.NewTextBlock(
"Schedule a 30-minute sync with alice@example.com and bob@example.com on Monday, March 30, 2026 at 10am.",
))
// 將使用者的請求連同工具定義一起傳送。Claude 會根據
// 請求內容和工具描述來決定是否呼叫該工具。
response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: tools,
ToolChoice: toolChoice,
Messages: []anthropic.MessageParam{userMessage},
})
if err != nil {
log.Fatal(err)
}
// 當 Claude 呼叫工具時，回應的 stop_reason 為 "tool_use"，
// 且 content 陣列中會包含一個 tool_use 區塊以及任何文字。
fmt.Printf("stop_reason: %s\n", response.StopReason)
// 尋找 tool_use 區塊。回應可能在 tool_use 區塊之前包含文字
// 區塊，因此請掃描 content 陣列，而非假設其位置。
var toolUse anthropic.ContentBlockUnion
for _, block := range response.Content {
if block.Type == "tool_use" {
toolUse = block
break
}
}
fmt.Printf("Tool: %s\n", toolUse.Name)
fmt.Printf("Input: %s\n", string(toolUse.Input))
// 執行工具。在真實系統中，這會呼叫您的行事曆 API。
// 此處結果為硬編碼，以保持範例的獨立完整性。
result := `{"event_id": "evt_123", "status": "created"}`
// 將結果回傳。tool_result 區塊需放在 user 訊息中，且其
// tool_use_id 必須與上方 tool_use 區塊的 id 相符。同時包含
// 助理先前的回應，以便 Claude 擁有完整的歷史記錄。
var assistantContent []anthropic.ContentBlockParamUnion
for _, block := range response.Content {
assistantContent = append(assistantContent, block.ToParam())
}
followup, err := client.Messages.New(ctx, anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: tools,
ToolChoice: toolChoice,
Messages: []anthropic.MessageParam{
userMessage,
anthropic.NewAssistantMessage(assistantContent...),
anthropic.NewUserMessage(anthropic.NewToolResultBlock(toolUse.ID, result, false)),
},
})
if err != nil {
log.Fatal(err)
}
// 取得工具結果後，Claude 會產生最終的自然語言
// 回答，且 stop_reason 會變為 "end_turn"。
fmt.Printf("stop_reason: %s\n", followup.StopReason)
for _, block := range followup.Content {
if block.Type == "text" {
fmt.Println(block.Text)
}
}
}
```
```java Java
// 第 1 環：單一工具，單一回合。
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.JsonValue;
import com.anthropic.models.messages.ContentBlockParam;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.Tool;
import com.anthropic.models.messages.Tool.InputSchema;
import com.anthropic.models.messages.ToolChoiceAuto;
import com.anthropic.models.messages.ToolResultBlockParam;
import com.anthropic.models.messages.ToolUseBlock;
import java.util.List;
import java.util.Map;
void main() {
// 建立一個用戶端。它會從環境變數讀取 ANTHROPIC_API_KEY。
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// 定義一個工具。輸入結構描述是一個 JSON Schema 物件，用於描述
// Claude 呼叫此工具時應傳遞的引數。此結構描述
// 包含巢狀物件（recurrence）、陣列（attendees）以及選用
// 欄位，這比單純的扁平字串引數更接近真實世界的工具。
Tool calendarTool = Tool.builder()
.name("create_calendar_event")
.description("Create a calendar event with attendees and optional recurrence.")
.inputSchema(InputSchema.builder()
.properties(JsonValue.from(Map.of(
"title", Map.of("type", "string"),
"start", Map.of("type", "string", "format", "date-time"),
"end", Map.of("type", "string", "format", "date-time"),
"attendees", Map.of(
"type", "array",
"items", Map.of("type", "string", "format", "email")
),
"recurrence", Map.of(
"type", "object",
"properties", Map.of(
"frequency", Map.of("enum", List.of("daily", "weekly", "monthly")),
"count", Map.of("type", "integer", "minimum", 1)
)
)
)))
.required(List.of("title", "start", "end"))
.build())
.build();
// 每回合最多要求一次工具呼叫，以便下方的單回合流程
// 保持可預測性。
ToolChoiceAuto toolChoice = ToolChoiceAuto.builder()
.disableParallelToolUse(true)
.build();
String userPrompt =
"Schedule a 30-minute sync with alice@example.com and bob@example.com on Monday, March 30, 2026 at 10am.";
// 將使用者的請求連同工具定義一起傳送。Claude 會根據
// 請求內容與工具描述來決定是否呼叫該工具。
Message response = client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addTool(calendarTool)
.toolChoice(toolChoice)
.addUserMessage(userPrompt)
.build());
// 當 Claude 呼叫工具時，回應的 stop_reason 為 "tool_use"，
// 且 content 陣列中會包含一個 tool_use 區塊以及任何文字內容。
IO.println("stop_reason: " + response.stopReason().orElse(null));
// 尋找 tool_use 區塊。回應中可能在 tool_use 區塊之前包含文字
// 區塊，因此請掃描 content 陣列，而非假設其位置。
ToolUseBlock toolUse = response.content().stream()
.flatMap(block -> block.toolUse().stream())
.findFirst()
.orElseThrow();
IO.println("Tool: " + toolUse.name());
IO.println("Input: " + toolUse._input());
// 執行該工具。在真實系統中，這會呼叫您的行事曆 API。
// 此處結果為硬編碼，以保持範例的獨立完整性。
String result = "{\"event_id\": \"evt_123\", \"status\": \"created\"}";
// 將結果回傳。tool_result 區塊需放在 user 訊息中，且其
// tool_use_id 必須與上方 tool_use 區塊的 id 相符。同時包含
// 助理先前的回應，以便 Claude 擁有完整的對話歷史。
Message followup = client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addTool(calendarTool)
.toolChoice(toolChoice)
.addUserMessage(userPrompt)
.addMessage(response)
.addUserMessageOfBlockParams(List.of(ContentBlockParam.ofToolResult(
ToolResultBlockParam.builder()
.toolUseId(toolUse.id())
.content(result)
.build())))
.build());
// 取得工具結果後，Claude 會產生最終的自然語言
// 回答，且 stop_reason 變為 "end_turn"。
IO.println("stop_reason: " + followup.stopReason().orElse(null));
followup.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
```
```php PHP
'create_calendar_event',
'description' => 'Create a calendar event with attendees and optional recurrence.',
'input_schema' => [
'type' => 'object',
'properties' => [
'title' => ['type' => 'string'],
'start' => ['type' => 'string', 'format' => 'date-time'],
'end' => ['type' => 'string', 'format' => 'date-time'],
'attendees' => [
'type' => 'array',
'items' => ['type' => 'string', 'format' => 'email'],
],
'recurrence' => [
'type' => 'object',
'properties' => [
'frequency' => ['enum' => ['daily', 'weekly', 'monthly']],
'count' => ['type' => 'integer', 'minimum' => 1],
],
],
],
'required' => ['title', 'start', 'end'],
],
],
];
$userMessage = [
'role' => 'user',
'content' => 'Schedule a 30-minute sync with alice@example.com and bob@example.com on Monday, March 30, 2026 at 10am.',
];
// 要求每回合最多呼叫一次工具，以便下方的單回合流程
// 保持可預測性。
$toolChoice = ToolChoiceAuto::with(disableParallelToolUse: true);
// 將使用者的請求連同工具定義一起傳送。Claude 會根據
// 請求內容與工具描述來決定是否呼叫該工具。
$response = $client->messages->create(
model: 'claude-opus-5-5',
maxTokens: 1024,
tools: $tools,
toolChoice: $toolChoice,
messages: [$userMessage],
);
// 當 Claude 呼叫工具時，回應的 stop_reason 為 "tool_use"，
// 且 content 陣列中會包含一個 tool_use 區塊以及任何文字。
printf("stop_reason: %s\n", $response->stopReason);
// 尋找 tool_use 區塊。回應中可能在 tool_use 區塊之前包含
// 文字區塊，因此請掃描 content 陣列，而非假設其位置。
$toolUse = null;
foreach ($response->content as $block) {
if ($block->type === 'tool_use') {
$toolUse = $block;
break;
}
}
printf("Tool: %s\n", $toolUse->name);
printf("Input: %s\n", json_encode($toolUse->input));
// 執行該工具。在真實系統中，這會呼叫您的行事曆 API。
// 此處結果為硬編碼，以保持範例的獨立完整性。
$result = ['event_id' => 'evt_123', 'status' => 'created'];
// 將結果回傳。tool_result 區塊需放在 user 訊息中，且其
// tool_use_id 必須與上方 tool_use 區塊的 id 相符。同時包含
// 助理先前的回應，以便 Claude 擁有完整的歷史記錄。
$followup = $client->messages->create(
model: 'claude-opus-5-5',
maxTokens: 1024,
tools: $tools,
toolChoice: $toolChoice,
messages: [
$userMessage,
['role' => 'assistant', 'content' => $response->content],
[
'role' => 'user',
'content' => [
[
'type' => 'tool_result',
'tool_use_id' => $toolUse->id,
'content' => json_encode($result),
],
],
],
],
);
// 取得工具結果後，Claude 會產生最終的自然語言
// 回答，且 stop_reason 會變為 "end_turn"。
printf("stop_reason: %s\n", $followup->stopReason);
foreach ($followup->content as $block) {
if ($block->type === 'text') {
echo $block->text, "\n";
}
}
```
```ruby Ruby
# 第 1 環：單一工具，單一回合。
require "anthropic"
# 建立一個用戶端。它會從環境變數讀取 ANTHROPIC_API_KEY。
client = Anthropic::Client.new
# 定義一個工具。input_schema 是一個 JSON Schema 物件，用於描述
# Claude 呼叫此工具時應傳遞的引數。此 schema
# 包含巢狀物件（recurrence）、陣列（attendees）以及選填
# 欄位，這比單純的扁平字串引數更接近真實世界的工具。
tools = [
{
name: "create_calendar_event",
description: "Create a calendar event with attendees and optional recurrence.",
input_schema: {
type: "object",
properties: {
title: {type: "string"},
start: {type: "string", format: "date-time"},
end: {type: "string", format: "date-time"},
attendees: {
type: "array",
items: {type: "string", format: "email"}
},
recurrence: {
type: "object",
properties: {
frequency: {enum: ["daily", "weekly", "monthly"]},
count: {type: "integer", minimum: 1}
}
}
},
required: ["title", "start", "end"]
}
}
]
user_message = {
role: "user",
content: "Schedule a 30-minute sync with alice@example.com and bob@example.com on Monday, March 30, 2026 at 10am."
}
# 每回合最多要求一次工具呼叫，以便下方的單回合流程
# 保持可預測性。
tool_choice = {type: "auto", disable_parallel_tool_use: true}
# 將使用者的請求連同工具定義一起傳送。Claude 會根據
# 請求內容與工具描述來決定是否呼叫該工具。
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
tools: tools,
tool_choice: tool_choice,
messages: [user_message]
)
# 當 Claude 呼叫工具時，回應的 stop_reason 為 "tool_use"，
# 且 content 陣列中會包含一個 tool_use 區塊以及任何文字內容。
puts "stop_reason: #{response.stop_reason}"
# 尋找 tool_use 區塊。回應中可能在 tool_use 區塊之前包含文字
# 區塊，因此請掃描 content 陣列，而非假設其位置。
tool_use = response.content.find { |block| block.type == :tool_use }
puts "Tool: #{tool_use.name}"
puts "Input: #{tool_use.input}"
# 執行該工具。在真實系統中，這會呼叫您的行事曆 API。
# 此處結果為硬編碼，以保持範例的獨立完整性。
result = {event_id: "evt_123", status: "created"}
# 將結果回傳。tool_result 區塊需放在 user 訊息中，且其
# tool_use_id 必須與上方 tool_use 區塊的 id 相符。同時包含
# 助理先前的回應，以便 Claude 擁有完整的對話歷史。
followup = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
tools: tools,
tool_choice: tool_choice,
messages: [
user_message,
{role: "assistant", content: response.content},
{
role: "user",
content: [
{
type: "tool_result",
tool_use_id: tool_use.id,
content: JSON.generate(result)
}
]
}
]
)
# 取得工具結果後，Claude 會產生最終的自然語言
# 回答，且 stop_reason 會變為 "end_turn"。
puts "stop_reason: #{followup.stop_reason}"
followup.content.each do |block|
puts block.text if block.type == :text
end
```
**預期結果**
```text Output wrap
stop_reason: tool_use
Tool: create_calendar_event
Input: {'title': 'Sync', 'start': '2026-03-30T10:00:00', 'end': '2026-03-30T10:30:00', 'attendees': ['alice@example.com', 'bob@example.com']}
stop_reason: end_turn
I've scheduled your 30-minute sync with Alice and Bob for Monday, March 30 at 10am.
```
第一個 `stop_reason` 是 `tool_use`，因為 Claude 正在等待行事曆的結果。在您送出結果之後，第二個 `stop_reason` 是 `end_turn`，而內容則是給使用者的自然語言。
## 第 2 環：代理迴圈
第 1 環假設 Claude 只會呼叫工具恰好一次。實際任務往往需要多次呼叫：Claude 可能會建立一個活動、讀取確認訊息，然後再建立另一個。解決方法是一個 `while` 迴圈，持續執行工具並將結果回饋，直到 `stop_reason` 不再是 `"tool_use"` 為止。
另一項變更是對話歷史。與其在每次請求時從頭重建 `messages` 陣列，不如維護一份持續累積的清單並向其附加內容。每一回合都能看到完整的先前上下文。
```bash cURL
#!/bin/bash
# Ring 2: The agentic loop.
# This workflow needs more logic than a single shell command.
# Use the Claude SDK to run it.
```
```bash CLI
#!/usr/bin/env bash
# Ring 2: The agentic loop.
# This workflow needs more logic than a single shell command.
# Use the Claude SDK to run it.
```
```python Python
# Ring 2：代理迴圈（agentic loop）。
import json
import anthropic
client = anthropic.Anthropic()
tools = [
{
"name": "create_calendar_event",
"description": "Create a calendar event with attendees and optional recurrence.",
"input_schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"start": {"type": "string", "format": "date-time"},
"end": {"type": "string", "format": "date-time"},
"attendees": {
"type": "array",
"items": {"type": "string", "format": "email"},
},
"recurrence": {
"type": "object",
"properties": {
"frequency": {"enum": ["daily", "weekly", "monthly"]},
"count": {"type": "integer", "minimum": 1},
},
},
},
"required": ["title", "start", "end"],
},
}
]
def run_tool(name, tool_input):
if name == "create_calendar_event":
return {
"event_id": "evt_123",
"status": "created",
"title": tool_input["title"],
}
return {"error": f"Unknown tool: {name}"}
# 將完整對話歷史保存在清單中，讓每一輪都能看到先前的上下文。
messages = [
{
"role": "user",
"content": "Schedule a weekly team standup every Monday at 9am for the next 4 weeks, starting Monday, March 30, 2026. Invite the whole team: alice@example.com, bob@example.com, carol@example.com.",
}
]
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "auto", "disable_parallel_tool_use": True},
messages=messages,
)
# 持續迴圈直到 Claude 不再要求使用工具。每次迭代會執行所要求的
# 工具，將結果附加到歷史中，並請 Claude 繼續。
while response.stop_reason == "tool_use":
tool_use = next(block for block in response.content if block.type == "tool_use")
result = run_tool(tool_use.name, tool_use.input)
messages.append({"role": "assistant", "content": response.content})
messages.append(
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": tool_use.id,
"content": json.dumps(result),
}
],
}
)
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "auto", "disable_parallel_tool_use": True},
messages=messages,
)
final_text = next(block for block in response.content if block.type == "text")
print(final_text.text)
```
```typescript TypeScript
// Ring 2：代理迴圈（agentic loop）。
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const tools: Anthropic.Tool[] = [
{
name: "create_calendar_event",
description: "Create a calendar event with attendees and optional recurrence.",
input_schema: {
type: "object",
properties: {
title: { type: "string" },
start: { type: "string", format: "date-time" },
end: { type: "string", format: "date-time" },
attendees: {
type: "array",
items: { type: "string", format: "email" }
},
recurrence: {
type: "object",
properties: {
frequency: { enum: ["daily", "weekly", "monthly"] },
count: { type: "integer", minimum: 1 }
}
}
},
required: ["title", "start", "end"]
}
}
];
function runTool(name: string, input: Record) {
if (name === "create_calendar_event") {
return { event_id: "evt_123", status: "created", title: input.title };
}
return { error: `Unknown tool: ${name}` };
}
// 保留完整的對話歷史，讓每一輪都能看到先前的上下文。
const messages: Anthropic.MessageParam[] = [
{
role: "user",
content:
"Schedule a weekly team standup every Monday at 9am for the next 4 weeks, starting Monday, March 30, 2026. Invite the whole team: alice@example.com, bob@example.com, carol@example.com."
}
];
let response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
tools,
tool_choice: { type: "auto", disable_parallel_tool_use: true },
messages
});
// 持續迴圈，直到 Claude 不再要求使用工具。每次迭代會執行所要求的
// 工具，將結果附加到歷史中，並請 Claude 繼續。
while (response.stop_reason === "tool_use") {
const toolUse = response.content.find((block) => block.type === "tool_use")!;
const result = runTool(toolUse.name, toolUse.input as Record);
messages.push({ role: "assistant", content: response.content });
messages.push({
role: "user",
content: [
{
type: "tool_result",
tool_use_id: toolUse.id,
content: JSON.stringify(result)
}
]
});
response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
tools,
tool_choice: { type: "auto", disable_parallel_tool_use: true },
messages
});
}
for (const block of response.content) {
if (block.type === "text") {
console.log(block.text);
}
}
```
```csharp C#
// Ring 2：代理迴圈（agentic loop）。
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text.Json;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages;
AnthropicClient client = new();
List tools =
[
new ToolUnion(new Tool()
{
Name = "create_calendar_event",
Description = "Create a calendar event with attendees and optional recurrence.",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["title"] = JsonSerializer.SerializeToElement(new { type = "string" }),
["start"] = JsonSerializer.SerializeToElement(new { type = "string", format = "date-time" }),
["end"] = JsonSerializer.SerializeToElement(new { type = "string", format = "date-time" }),
["attendees"] = JsonSerializer.SerializeToElement(new
{
type = "array",
items = new { type = "string", format = "email" },
}),
["recurrence"] = JsonSerializer.SerializeToElement(new
{
type = "object",
properties = new
{
frequency = new { @enum = new[] { "daily", "weekly", "monthly" } },
count = new { type = "integer", minimum = 1 },
},
}),
},
Required = ["title", "start", "end"],
},
}),
];
// 執行所請求的工具，並以字串形式回傳其結果。
string RunTool(ToolUseBlock toolUse)
{
if (toolUse.Name == "create_calendar_event")
{
var title = toolUse.Input.TryGetValue("title", out var t) ? t.GetString() : "";
return JsonSerializer.Serialize(new { event_id = "evt_123", status = "created", title });
}
return JsonSerializer.Serialize(new { error = $"Unknown tool: {toolUse.Name}" });
}
var toolChoice = new ToolChoice(new ToolChoiceAuto { DisableParallelToolUse = true });
// 將完整對話歷史保存在 list 中，讓每一輪都能看到先前的上下文。
List messages =
[
new()
{
Role = Role.User,
Content = "Schedule a weekly team standup every Monday at 9am for the next 4 weeks, starting Monday, March 30, 2026. Invite the whole team: alice@example.com, bob@example.com, carol@example.com.",
},
];
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools = tools,
ToolChoice = toolChoice,
Messages = messages,
});
// 持續迴圈直到 Claude 不再請求工具。每次迭代會執行所請求的
// 工具，將結果附加到歷史中，並請 Claude 繼續。
while (response.StopReason == StopReason.ToolUse)
{
ToolUseBlock? toolUse = null;
foreach (var block in response.Content)
{
if (block.TryPickToolUse(out var picked))
{
toolUse = picked;
break;
}
}
var result = RunTool(toolUse!);
messages.Add(new()
{
Role = Role.Assistant,
Content = response.Content.Select(block => new ContentBlockParam(block.Json)).ToList(),
});
messages.Add(new()
{
Role = Role.User,
Content = new MessageParamContent(
[
new ContentBlockParam(new ToolResultBlockParam() { ToolUseID = toolUse!.ID, Content = result }),
]),
});
response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools = tools,
ToolChoice = toolChoice,
Messages = messages,
});
}
foreach (var block in response.Content)
{
if (block.TryPickText(out var text))
{
Console.WriteLine(text.Text);
}
}
```
```go Go
// Ring 2：代理迴圈（agentic loop）。
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func runTool(name string, input map[string]any) string {
if name == "create_calendar_event" {
title, _ := input["title"].(string)
return fmt.Sprintf(`{"event_id": "evt_123", "status": "created", "title": %q}`, title)
}
return fmt.Sprintf(`{"error": "Unknown tool: %s"}`, name)
}
func main() {
client := anthropic.NewClient()
ctx := context.Background()
tools := []anthropic.ToolUnionParam{
{OfTool: &anthropic.ToolParam{
Name: "create_calendar_event",
Description: anthropic.String("Create a calendar event with attendees and optional recurrence."),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"title": map[string]any{"type": "string"},
"start": map[string]any{"type": "string", "format": "date-time"},
"end": map[string]any{"type": "string", "format": "date-time"},
"attendees": map[string]any{
"type": "array",
"items": map[string]any{"type": "string", "format": "email"},
},
"recurrence": map[string]any{
"type": "object",
"properties": map[string]any{
"frequency": map[string]any{"enum": []string{"daily", "weekly", "monthly"}},
"count": map[string]any{"type": "integer", "minimum": 1},
},
},
},
Required: []string{"title", "start", "end"},
},
}},
}
toolChoice := anthropic.ToolChoiceUnionParam{
OfAuto: &anthropic.ToolChoiceAutoParam{DisableParallelToolUse: anthropic.Bool(true)},
}
// 將完整對話歷史保存在 slice 中，讓每一輪都能看到先前的上下文。
messages := []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock(
"Schedule a weekly team standup every Monday at 9am for the next 4 weeks, starting Monday, March 30, 2026. Invite the whole team: alice@example.com, bob@example.com, carol@example.com.",
)),
}
response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: tools,
ToolChoice: toolChoice,
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
// 持續迴圈直到 Claude 不再請求工具。每次迭代會執行所請求的
// 工具，將結果附加到歷史中，並請 Claude 繼續。
for response.StopReason == "tool_use" {
var toolUse anthropic.ContentBlockUnion
for _, block := range response.Content {
if block.Type == "tool_use" {
toolUse = block
break
}
}
var input map[string]any
if err := json.Unmarshal(toolUse.Input, &input); err != nil {
log.Fatal(err)
}
result := runTool(toolUse.Name, input)
var assistantContent []anthropic.ContentBlockParamUnion
for _, block := range response.Content {
assistantContent = append(assistantContent, block.ToParam())
}
messages = append(messages, anthropic.NewAssistantMessage(assistantContent...))
messages = append(messages, anthropic.NewUserMessage(
anthropic.NewToolResultBlock(toolUse.ID, result, false),
))
response, err = client.Messages.New(ctx, anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: tools,
ToolChoice: toolChoice,
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
}
for _, block := range response.Content {
if block.Type == "text" {
fmt.Println(block.Text)
}
}
}
```
```java Java
// 第 2 環：agentic loop（代理迴圈）。
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.JsonValue;
import com.anthropic.models.messages.ContentBlockParam;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.MessageParam;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.StopReason;
import com.anthropic.models.messages.Tool;
import com.anthropic.models.messages.Tool.InputSchema;
import com.anthropic.models.messages.ToolChoiceAuto;
import com.anthropic.models.messages.ToolResultBlockParam;
import com.anthropic.models.messages.ToolUseBlock;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
String runTool(ToolUseBlock toolUse) {
// 原始工具輸入是一個 JSON 物件；請將其視為 map 讀取欄位。
Map input = (Map) toolUse._input().asObject().get();
if (toolUse.name().equals("create_calendar_event")) {
String title = input.containsKey("title") ? input.get("title").asStringOrThrow() : "";
return "{\"event_id\": \"evt_123\", \"status\": \"created\", \"title\": \"" + title + "\"}";
}
return "{\"error\": \"Unknown tool: " + toolUse.name() + "\"}";
}
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Tool calendarTool = Tool.builder()
.name("create_calendar_event")
.description("Create a calendar event with attendees and optional recurrence.")
.inputSchema(InputSchema.builder()
.properties(JsonValue.from(Map.of(
"title", Map.of("type", "string"),
"start", Map.of("type", "string", "format", "date-time"),
"end", Map.of("type", "string", "format", "date-time"),
"attendees", Map.of(
"type", "array",
"items", Map.of("type", "string", "format", "email")
),
"recurrence", Map.of(
"type", "object",
"properties", Map.of(
"frequency", Map.of("enum", List.of("daily", "weekly", "monthly")),
"count", Map.of("type", "integer", "minimum", 1)
)
)
)))
.required(List.of("title", "start", "end"))
.build())
.build();
ToolChoiceAuto toolChoice = ToolChoiceAuto.builder()
.disableParallelToolUse(true)
.build();
// 將完整對話歷史保存在清單中，讓每一輪都能看到先前的上下文。
List messages = new ArrayList<>();
messages.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.content("Schedule a weekly team standup every Monday at 9am for the next 4 weeks, starting Monday, March 30, 2026. Invite the whole team: alice@example.com, bob@example.com, carol@example.com.")
.build());
Message response = client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addTool(calendarTool)
.toolChoice(toolChoice)
.messages(messages)
.build());
// 持續迴圈，直到 Claude 不再要求使用工具。每次迭代會執行所要求的
// 工具，將結果附加到歷史中，並請 Claude 繼續。
while (response.stopReason().isPresent()
&& response.stopReason().get().equals(StopReason.TOOL_USE)) {
ToolUseBlock toolUse = response.content().stream()
.flatMap(block -> block.toolUse().stream())
.findFirst()
.orElseThrow();
String result = runTool(toolUse);
messages.add(response.toParam());
messages.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.contentOfBlockParams(List.of(ContentBlockParam.ofToolResult(
ToolResultBlockParam.builder()
.toolUseId(toolUse.id())
.content(result)
.build())))
.build());
response = client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addTool(calendarTool)
.toolChoice(toolChoice)
.messages(messages)
.build());
}
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
```
```php PHP
'create_calendar_event',
'description' => 'Create a calendar event with attendees and optional recurrence.',
'input_schema' => [
'type' => 'object',
'properties' => [
'title' => ['type' => 'string'],
'start' => ['type' => 'string', 'format' => 'date-time'],
'end' => ['type' => 'string', 'format' => 'date-time'],
'attendees' => [
'type' => 'array',
'items' => ['type' => 'string', 'format' => 'email'],
],
'recurrence' => [
'type' => 'object',
'properties' => [
'frequency' => ['enum' => ['daily', 'weekly', 'monthly']],
'count' => ['type' => 'integer', 'minimum' => 1],
],
],
],
'required' => ['title', 'start', 'end'],
],
],
];
function runTool(string $name, array $input): string
{
if ($name === 'create_calendar_event') {
return json_encode([
'event_id' => 'evt_123',
'status' => 'created',
'title' => $input['title'],
]);
}
return json_encode(['error' => "Unknown tool: {$name}"]);
}
$toolChoice = ToolChoiceAuto::with(disableParallelToolUse: true);
// 將完整對話歷史保存在陣列中，讓每一輪都能看到先前的上下文。
$messages = [
[
'role' => 'user',
'content' => 'Schedule a weekly team standup every Monday at 9am for the next 4 weeks, starting Monday, March 30, 2026. Invite the whole team: alice@example.com, bob@example.com, carol@example.com.',
],
];
$response = $client->messages->create(
model: 'claude-opus-5-5',
maxTokens: 1024,
tools: $tools,
toolChoice: $toolChoice,
messages: $messages,
);
// 持續迴圈直到 Claude 不再請求工具。每次迭代會執行所請求的
// 工具，將結果附加到歷史中，並請 Claude 繼續。
while ($response->stopReason === 'tool_use') {
$toolUse = null;
foreach ($response->content as $block) {
if ($block->type === 'tool_use') {
$toolUse = $block;
break;
}
}
$result = runTool($toolUse->name, $toolUse->input);
$messages[] = ['role' => 'assistant', 'content' => $response->content];
$messages[] = [
'role' => 'user',
'content' => [
[
'type' => 'tool_result',
'tool_use_id' => $toolUse->id,
'content' => $result,
],
],
];
$response = $client->messages->create(
model: 'claude-opus-5-5',
maxTokens: 1024,
tools: $tools,
toolChoice: $toolChoice,
messages: $messages,
);
}
foreach ($response->content as $block) {
if ($block->type === 'text') {
echo $block->text, "\n";
}
}
```
```ruby Ruby
# Ring 2：代理迴圈（agentic loop）。
require "anthropic"
client = Anthropic::Client.new
tools = [
{
name: "create_calendar_event",
description: "Create a calendar event with attendees and optional recurrence.",
input_schema: {
type: "object",
properties: {
title: {type: "string"},
start: {type: "string", format: "date-time"},
end: {type: "string", format: "date-time"},
attendees: {
type: "array",
items: {type: "string", format: "email"}
},
recurrence: {
type: "object",
properties: {
frequency: {enum: ["daily", "weekly", "monthly"]},
count: {type: "integer", minimum: 1}
}
}
},
required: ["title", "start", "end"]
}
}
]
def run_tool(name, input)
case name
when "create_calendar_event"
JSON.generate({event_id: "evt_123", status: "created", title: input[:title]})
else
JSON.generate({error: "Unknown tool: #{name}"})
end
end
tool_choice = {type: "auto", disable_parallel_tool_use: true}
# 將完整對話歷史保存在陣列中，讓每一輪都能看到先前的上下文。
messages = [
{
role: "user",
content: "Schedule a weekly team standup every Monday at 9am for the next 4 weeks, starting Monday, March 30, 2026. Invite the whole team: alice@example.com, bob@example.com, carol@example.com."
}
]
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
tools: tools,
tool_choice: tool_choice,
messages: messages
)
# 持續迴圈直到 Claude 不再要求使用工具。每次迭代會執行所要求的
# 工具，將結果附加到歷史中，並請 Claude 繼續。
while response.stop_reason == :tool_use
tool_use = response.content.find { |block| block.type == :tool_use }
result = run_tool(tool_use.name, tool_use.input)
messages << {role: "assistant", content: response.content}
messages << {
role: "user",
content: [
{
type: "tool_result",
tool_use_id: tool_use.id,
content: result
}
]
}
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
tools: tools,
tool_choice: tool_choice,
messages: messages
)
end
response.content.each do |block|
puts block.text if block.type == :text
end
```
**預期結果**
```text Output wrap
I've set up your weekly team standup for the next 4 Mondays at 9am with Alice, Bob, and Carol invited.
```
迴圈可能執行一次或多次，取決於 Claude 如何拆解任務。您的程式碼不再需要事先知道。
## 第 3 環：多個工具、平行呼叫
代理很少只有一項能力。新增第二個工具 `list_calendar_events`，讓 Claude 能在建立新活動之前先檢查現有的行程。
當 Claude 有多個彼此獨立的工具呼叫要進行時，它可能會在單一回應中回傳數個 `tool_use` 區塊。您的迴圈需要處理所有這些區塊，並在一則使用者訊息中將所有結果一併送回。請遍歷 `response.content` 中的每一個 `tool_use` 區塊，而不只是第一個。
```bash cURL
#!/bin/bash
# Ring 3: Multiple tools, parallel calls.
# This workflow needs more logic than a single shell command.
# Use the Claude SDK to run it.
```
```bash CLI
#!/usr/bin/env bash
# Ring 3: Multiple tools, parallel calls.
# This workflow needs more logic than a single shell command.
# Use the Claude SDK to run it.
```
```python Python
# Ring 3：多個工具，平行呼叫。
import json
import anthropic
client = anthropic.Anthropic()
tools = [
{
"name": "create_calendar_event",
"description": "Create a calendar event with attendees and optional recurrence.",
"input_schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"start": {"type": "string", "format": "date-time"},
"end": {"type": "string", "format": "date-time"},
"attendees": {
"type": "array",
"items": {"type": "string", "format": "email"},
},
"recurrence": {
"type": "object",
"properties": {
"frequency": {"enum": ["daily", "weekly", "monthly"]},
"count": {"type": "integer", "minimum": 1},
},
},
},
"required": ["title", "start", "end"],
},
},
{
"name": "list_calendar_events",
"description": "List all calendar events on a given date.",
"input_schema": {
"type": "object",
"properties": {
"date": {"type": "string", "format": "date"},
},
"required": ["date"],
},
},
]
def run_tool(name, tool_input):
if name == "create_calendar_event":
return {
"event_id": "evt_123",
"status": "created",
"title": tool_input["title"],
}
if name == "list_calendar_events":
return {
"events": [{"title": "Existing meeting", "start": "14:00", "end": "15:00"}]
}
return {"error": f"Unknown tool: {name}"}
messages = [
{
"role": "user",
"content": "Check what I have on Monday, March 30, 2026, then schedule a one-hour planning session that day that avoids any conflicts.",
}
]
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
messages=messages,
)
while response.stop_reason == "tool_use":
# 單一回應可能包含多個 tool_use 區塊。請處理所有
# 區塊，並在同一則 user 訊息中一併傳回所有結果。
tool_results = []
for block in response.content:
if block.type == "tool_use":
result = run_tool(block.name, block.input)
tool_results.append(
{
"type": "tool_result",
"tool_use_id": block.id,
"content": json.dumps(result),
}
)
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_results})
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
messages=messages,
)
final_text = next(block for block in response.content if block.type == "text")
print(final_text.text)
```
```typescript TypeScript
// Ring 3：多個工具，平行呼叫。
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const tools: Anthropic.Tool[] = [
{
name: "create_calendar_event",
description: "Create a calendar event with attendees and optional recurrence.",
input_schema: {
type: "object",
properties: {
title: { type: "string" },
start: { type: "string", format: "date-time" },
end: { type: "string", format: "date-time" },
attendees: {
type: "array",
items: { type: "string", format: "email" }
},
recurrence: {
type: "object",
properties: {
frequency: { enum: ["daily", "weekly", "monthly"] },
count: { type: "integer", minimum: 1 }
}
}
},
required: ["title", "start", "end"]
}
},
{
name: "list_calendar_events",
description: "List all calendar events on a given date.",
input_schema: {
type: "object",
properties: {
date: { type: "string", format: "date" }
},
required: ["date"]
}
}
];
function runTool(name: string, input: Record) {
if (name === "create_calendar_event") {
return { event_id: "evt_123", status: "created", title: input.title };
}
if (name === "list_calendar_events") {
return {
events: [{ title: "Existing meeting", start: "14:00", end: "15:00" }]
};
}
return { error: `Unknown tool: ${name}` };
}
const messages: Anthropic.MessageParam[] = [
{
role: "user",
content:
"Check what I have on Monday, March 30, 2026, then schedule a one-hour planning session that day that avoids any conflicts."
}
];
let response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
tools,
messages
});
while (response.stop_reason === "tool_use") {
// 單一回應可能包含多個 tool_use 區塊。請處理所有
// 區塊，並在同一則 user 訊息中一併傳回所有結果。
const toolResults: Anthropic.ToolResultBlockParam[] = [];
for (const block of response.content) {
if (block.type === "tool_use") {
const result = runTool(block.name, block.input as Record);
toolResults.push({
type: "tool_result",
tool_use_id: block.id,
content: JSON.stringify(result)
});
}
}
messages.push({ role: "assistant", content: response.content });
messages.push({ role: "user", content: toolResults });
response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
tools,
messages
});
}
for (const block of response.content) {
if (block.type === "text") {
console.log(block.text);
}
}
```
```csharp C#
// 第 3 環：多個工具，平行呼叫。
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text.Json;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages;
AnthropicClient client = new();
List tools =
[
new ToolUnion(new Tool()
{
Name = "create_calendar_event",
Description = "Create a calendar event with attendees and optional recurrence.",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["title"] = JsonSerializer.SerializeToElement(new { type = "string" }),
["start"] = JsonSerializer.SerializeToElement(new { type = "string", format = "date-time" }),
["end"] = JsonSerializer.SerializeToElement(new { type = "string", format = "date-time" }),
["attendees"] = JsonSerializer.SerializeToElement(new
{
type = "array",
items = new { type = "string", format = "email" },
}),
["recurrence"] = JsonSerializer.SerializeToElement(new
{
type = "object",
properties = new
{
frequency = new { @enum = new[] { "daily", "weekly", "monthly" } },
count = new { type = "integer", minimum = 1 },
},
}),
},
Required = ["title", "start", "end"],
},
}),
new ToolUnion(new Tool()
{
Name = "list_calendar_events",
Description = "List all calendar events on a given date.",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["date"] = JsonSerializer.SerializeToElement(new { type = "string", format = "date" }),
},
Required = ["date"],
},
}),
];
string RunTool(ToolUseBlock toolUse)
{
if (toolUse.Name == "create_calendar_event")
{
var title = toolUse.Input.TryGetValue("title", out var t) ? t.GetString() : "";
return JsonSerializer.Serialize(new { event_id = "evt_123", status = "created", title });
}
if (toolUse.Name == "list_calendar_events")
{
return """{"events": [{"title": "Existing meeting", "start": "14:00", "end": "15:00"}]}""";
}
return JsonSerializer.Serialize(new { error = $"Unknown tool: {toolUse.Name}" });
}
List messages =
[
new()
{
Role = Role.User,
Content = "Check what I have on Monday, March 30, 2026, then schedule a one-hour planning session that day that avoids any conflicts.",
},
];
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools = tools,
Messages = messages,
});
while (response.StopReason == StopReason.ToolUse)
{
// 單一回應可能包含多個 tool_use 區塊。請處理所有
// 區塊，並在同一則 user 訊息中一併傳回所有結果。
List toolResults = [];
foreach (var block in response.Content)
{
if (block.TryPickToolUse(out var toolUse))
{
toolResults.Add(new ContentBlockParam(new ToolResultBlockParam()
{
ToolUseID = toolUse.ID,
Content = RunTool(toolUse),
}));
}
}
messages.Add(new()
{
Role = Role.Assistant,
Content = response.Content.Select(block => new ContentBlockParam(block.Json)).ToList(),
});
messages.Add(new() { Role = Role.User, Content = new MessageParamContent(toolResults) });
response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools = tools,
Messages = messages,
});
}
foreach (var block in response.Content)
{
if (block.TryPickText(out var text))
{
Console.WriteLine(text.Text);
}
}
```
```go Go
// 第 3 環：多個工具，平行呼叫。
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func runTool(name string, input map[string]any) string {
if name == "create_calendar_event" {
title, _ := input["title"].(string)
return fmt.Sprintf(`{"event_id": "evt_123", "status": "created", "title": %q}`, title)
}
if name == "list_calendar_events" {
return `{"events": [{"title": "Existing meeting", "start": "14:00", "end": "15:00"}]}`
}
return fmt.Sprintf(`{"error": "Unknown tool: %s"}`, name)
}
func main() {
client := anthropic.NewClient()
ctx := context.Background()
tools := []anthropic.ToolUnionParam{
{OfTool: &anthropic.ToolParam{
Name: "create_calendar_event",
Description: anthropic.String("Create a calendar event with attendees and optional recurrence."),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"title": map[string]any{"type": "string"},
"start": map[string]any{"type": "string", "format": "date-time"},
"end": map[string]any{"type": "string", "format": "date-time"},
"attendees": map[string]any{
"type": "array",
"items": map[string]any{"type": "string", "format": "email"},
},
"recurrence": map[string]any{
"type": "object",
"properties": map[string]any{
"frequency": map[string]any{"enum": []string{"daily", "weekly", "monthly"}},
"count": map[string]any{"type": "integer", "minimum": 1},
},
},
},
Required: []string{"title", "start", "end"},
},
}},
{OfTool: &anthropic.ToolParam{
Name: "list_calendar_events",
Description: anthropic.String("List all calendar events on a given date."),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"date": map[string]any{"type": "string", "format": "date"},
},
Required: []string{"date"},
},
}},
}
messages := []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock(
"Check what I have on Monday, March 30, 2026, then schedule a one-hour planning session that day that avoids any conflicts.",
)),
}
response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: tools,
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
for response.StopReason == "tool_use" {
// 單一回應可能包含多個 tool_use 區塊。請處理所有
// 區塊，並在同一則 user 訊息中一併傳回所有結果。
var toolResults []anthropic.ContentBlockParamUnion
for _, block := range response.Content {
if block.Type == "tool_use" {
var input map[string]any
if err := json.Unmarshal(block.Input, &input); err != nil {
log.Fatal(err)
}
result := runTool(block.Name, input)
toolResults = append(toolResults, anthropic.NewToolResultBlock(block.ID, result, false))
}
}
var assistantContent []anthropic.ContentBlockParamUnion
for _, block := range response.Content {
assistantContent = append(assistantContent, block.ToParam())
}
messages = append(messages, anthropic.NewAssistantMessage(assistantContent...))
messages = append(messages, anthropic.NewUserMessage(toolResults...))
response, err = client.Messages.New(ctx, anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: tools,
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
}
for _, block := range response.Content {
if block.Type == "text" {
fmt.Println(block.Text)
}
}
}
```
```java Java
// Ring 3：多個工具，平行呼叫。
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.JsonValue;
import com.anthropic.models.messages.ContentBlock;
import com.anthropic.models.messages.ContentBlockParam;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.MessageParam;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.StopReason;
import com.anthropic.models.messages.Tool;
import com.anthropic.models.messages.Tool.InputSchema;
import com.anthropic.models.messages.ToolResultBlockParam;
import com.anthropic.models.messages.ToolUseBlock;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
String runTool(ToolUseBlock toolUse) {
// 原始工具輸入是 JSON 物件；請將其視為 map 讀取欄位。
Map input = (Map) toolUse._input().asObject().get();
if (toolUse.name().equals("create_calendar_event")) {
String title = input.containsKey("title") ? input.get("title").asStringOrThrow() : "";
return "{\"event_id\": \"evt_123\", \"status\": \"created\", \"title\": \"" + title + "\"}";
}
if (toolUse.name().equals("list_calendar_events")) {
return "{\"events\": [{\"title\": \"Existing meeting\", \"start\": \"14:00\", \"end\": \"15:00\"}]}";
}
return "{\"error\": \"Unknown tool: " + toolUse.name() + "\"}";
}
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Tool calendarTool = Tool.builder()
.name("create_calendar_event")
.description("Create a calendar event with attendees and optional recurrence.")
.inputSchema(InputSchema.builder()
.properties(JsonValue.from(Map.of(
"title", Map.of("type", "string"),
"start", Map.of("type", "string", "format", "date-time"),
"end", Map.of("type", "string", "format", "date-time"),
"attendees", Map.of(
"type", "array",
"items", Map.of("type", "string", "format", "email")
),
"recurrence", Map.of(
"type", "object",
"properties", Map.of(
"frequency", Map.of("enum", List.of("daily", "weekly", "monthly")),
"count", Map.of("type", "integer", "minimum", 1)
)
)
)))
.required(List.of("title", "start", "end"))
.build())
.build();
Tool listTool = Tool.builder()
.name("list_calendar_events")
.description("List all calendar events on a given date.")
.inputSchema(InputSchema.builder()
.properties(JsonValue.from(Map.of(
"date", Map.of("type", "string", "format", "date")
)))
.required(List.of("date"))
.build())
.build();
List messages = new ArrayList<>();
messages.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.content("Check what I have on Monday, March 30, 2026, then schedule a one-hour planning session that day that avoids any conflicts.")
.build());
Message response = client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addTool(calendarTool)
.addTool(listTool)
.messages(messages)
.build());
while (response.stopReason().isPresent()
&& response.stopReason().get().equals(StopReason.TOOL_USE)) {
// 單一回應可能包含多個 tool_use 區塊。請處理所有
// 區塊，並在同一則 user 訊息中一併傳回所有結果。
List toolResults = new ArrayList<>();
for (ContentBlock block : response.content()) {
if (block.toolUse().isPresent()) {
ToolUseBlock toolUse = block.toolUse().get();
toolResults.add(ContentBlockParam.ofToolResult(
ToolResultBlockParam.builder()
.toolUseId(toolUse.id())
.content(runTool(toolUse))
.build()));
}
}
messages.add(response.toParam());
messages.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.contentOfBlockParams(toolResults)
.build());
response = client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addTool(calendarTool)
.addTool(listTool)
.messages(messages)
.build());
}
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
```
```php PHP
'create_calendar_event',
'description' => 'Create a calendar event with attendees and optional recurrence.',
'input_schema' => [
'type' => 'object',
'properties' => [
'title' => ['type' => 'string'],
'start' => ['type' => 'string', 'format' => 'date-time'],
'end' => ['type' => 'string', 'format' => 'date-time'],
'attendees' => [
'type' => 'array',
'items' => ['type' => 'string', 'format' => 'email'],
],
'recurrence' => [
'type' => 'object',
'properties' => [
'frequency' => ['enum' => ['daily', 'weekly', 'monthly']],
'count' => ['type' => 'integer', 'minimum' => 1],
],
],
],
'required' => ['title', 'start', 'end'],
],
],
[
'name' => 'list_calendar_events',
'description' => 'List all calendar events on a given date.',
'input_schema' => [
'type' => 'object',
'properties' => [
'date' => ['type' => 'string', 'format' => 'date'],
],
'required' => ['date'],
],
],
];
function runTool(string $name, array $input): string
{
if ($name === 'create_calendar_event') {
return json_encode([
'event_id' => 'evt_123',
'status' => 'created',
'title' => $input['title'],
]);
}
if ($name === 'list_calendar_events') {
return json_encode([
'events' => [['title' => 'Existing meeting', 'start' => '14:00', 'end' => '15:00']],
]);
}
return json_encode(['error' => "Unknown tool: {$name}"]);
}
$messages = [
[
'role' => 'user',
'content' => 'Check what I have on Monday, March 30, 2026, then schedule a one-hour planning session that day that avoids any conflicts.',
],
];
$response = $client->messages->create(
model: 'claude-opus-5-5',
maxTokens: 1024,
tools: $tools,
messages: $messages,
);
while ($response->stopReason === 'tool_use') {
// 單一回應可能包含多個 tool_use 區塊。請處理所有
// 區塊，並在同一則 user 訊息中一併傳回所有結果。
$toolResults = [];
foreach ($response->content as $block) {
if ($block->type === 'tool_use') {
$toolResults[] = [
'type' => 'tool_result',
'tool_use_id' => $block->id,
'content' => runTool($block->name, $block->input),
];
}
}
$messages[] = ['role' => 'assistant', 'content' => $response->content];
$messages[] = ['role' => 'user', 'content' => $toolResults];
$response = $client->messages->create(
model: 'claude-opus-5-5',
maxTokens: 1024,
tools: $tools,
messages: $messages,
);
}
foreach ($response->content as $block) {
if ($block->type === 'text') {
echo $block->text, "\n";
}
}
```
```ruby Ruby
# 第 3 環：多個工具，平行呼叫。
require "anthropic"
client = Anthropic::Client.new
tools = [
{
name: "create_calendar_event",
description: "Create a calendar event with attendees and optional recurrence.",
input_schema: {
type: "object",
properties: {
title: {type: "string"},
start: {type: "string", format: "date-time"},
end: {type: "string", format: "date-time"},
attendees: {
type: "array",
items: {type: "string", format: "email"}
},
recurrence: {
type: "object",
properties: {
frequency: {enum: ["daily", "weekly", "monthly"]},
count: {type: "integer", minimum: 1}
}
}
},
required: ["title", "start", "end"]
}
},
{
name: "list_calendar_events",
description: "List all calendar events on a given date.",
input_schema: {
type: "object",
properties: {
date: {type: "string", format: "date"}
},
required: ["date"]
}
}
]
def run_tool(name, input)
case name
when "create_calendar_event"
JSON.generate({event_id: "evt_123", status: "created", title: input[:title]})
when "list_calendar_events"
JSON.generate({events: [{title: "Existing meeting", start: "14:00", end: "15:00"}]})
else
JSON.generate({error: "Unknown tool: #{name}"})
end
end
messages = [
{
role: "user",
content: "Check what I have on Monday, March 30, 2026, then schedule a one-hour planning session that day that avoids any conflicts."
}
]
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
tools: tools,
messages: messages
)
while response.stop_reason == :tool_use
# 單一回應可能包含多個 tool_use 區塊。請處理所有
# 區塊，並在同一則 user 訊息中一併傳回所有結果。
tool_results = response.content.select { |block| block.type == :tool_use }.map do |tool_use|
{
type: "tool_result",
tool_use_id: tool_use.id,
content: run_tool(tool_use.name, tool_use.input)
}
end
messages << {role: "assistant", content: response.content}
messages << {role: "user", content: tool_results}
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
tools: tools,
messages: messages
)
end
response.content.each do |block|
puts block.text if block.type == :text
end
```
**預期結果**
```text Output wrap
I checked your calendar for Monday, March 30 and found an existing meeting from 2pm to 3pm. I've scheduled the planning session for 10am to 11am to avoid the conflict.
```
關於並行執行與順序保證的更多資訊，請參閱[平行工具使用](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/parallel-tool-use)。
## 第 4 環：錯誤處理
工具會失敗。行事曆 API 可能會拒絕與會者過多的活動，或者日期格式可能有誤。當工具拋出錯誤時，請以 `is_error: true` 將錯誤訊息送回，而不是讓程式當掉。Claude 會讀取錯誤，並可以用修正後的輸入重試、向使用者要求釐清，或說明該限制。
```bash cURL
#!/bin/bash
# Ring 4: Error handling.
# This workflow needs more logic than a single shell command.
# Use the Claude SDK to run it.
```
```bash CLI
#!/usr/bin/env bash
# Ring 4: Error handling.
# This workflow needs more logic than a single shell command.
# Use the Claude SDK to run it.
```
```python Python
# Ring 4：錯誤處理。
import json
import anthropic
client = anthropic.Anthropic()
tools = [
{
"name": "create_calendar_event",
"description": "Create a calendar event with attendees and optional recurrence.",
"input_schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"start": {"type": "string", "format": "date-time"},
"end": {"type": "string", "format": "date-time"},
"attendees": {
"type": "array",
"items": {"type": "string", "format": "email"},
},
"recurrence": {
"type": "object",
"properties": {
"frequency": {"enum": ["daily", "weekly", "monthly"]},
"count": {"type": "integer", "minimum": 1},
},
},
},
"required": ["title", "start", "end"],
},
},
{
"name": "list_calendar_events",
"description": "List all calendar events on a given date.",
"input_schema": {
"type": "object",
"properties": {
"date": {"type": "string", "format": "date"},
},
"required": ["date"],
},
},
]
def run_tool(name, tool_input):
if name == "create_calendar_event":
if "attendees" in tool_input and len(tool_input["attendees"]) > 10:
raise ValueError("Too many attendees (max 10)")
return {
"event_id": "evt_123",
"status": "created",
"title": tool_input["title"],
}
if name == "list_calendar_events":
return {
"events": [{"title": "Existing meeting", "start": "14:00", "end": "15:00"}]
}
raise ValueError(f"Unknown tool: {name}")
messages = [
{
"role": "user",
"content": "Schedule a one-hour all-hands on Monday, March 30, 2026 at 10am with everyone: "
+ ", ".join(f"user{i}@example.com" for i in range(15)),
}
]
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
messages=messages,
)
while response.stop_reason == "tool_use":
tool_results = []
for block in response.content:
if block.type == "tool_use":
try:
result = run_tool(block.name, block.input)
tool_results.append(
{
"type": "tool_result",
"tool_use_id": block.id,
"content": json.dumps(result),
}
)
except Exception as exc:
# 回報失敗，讓 Claude 可以重試或要求釐清。
tool_results.append(
{
"type": "tool_result",
"tool_use_id": block.id,
"content": str(exc),
"is_error": True,
}
)
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_results})
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
messages=messages,
)
final_text = next(block for block in response.content if block.type == "text")
print(final_text.text)
```
```typescript TypeScript
// Ring 4：錯誤處理。
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const tools: Anthropic.Tool[] = [
{
name: "create_calendar_event",
description: "Create a calendar event with attendees and optional recurrence.",
input_schema: {
type: "object",
properties: {
title: { type: "string" },
start: { type: "string", format: "date-time" },
end: { type: "string", format: "date-time" },
attendees: {
type: "array",
items: { type: "string", format: "email" }
},
recurrence: {
type: "object",
properties: {
frequency: { enum: ["daily", "weekly", "monthly"] },
count: { type: "integer", minimum: 1 }
}
}
},
required: ["title", "start", "end"]
}
},
{
name: "list_calendar_events",
description: "List all calendar events on a given date.",
input_schema: {
type: "object",
properties: {
date: { type: "string", format: "date" }
},
required: ["date"]
}
}
];
function runTool(name: string, input: Record) {
if (name === "create_calendar_event") {
const attendees = input.attendees as string[] | undefined;
if (attendees && attendees.length > 10) {
throw new Error("Too many attendees (max 10)");
}
return { event_id: "evt_123", status: "created", title: input.title };
}
if (name === "list_calendar_events") {
return {
events: [{ title: "Existing meeting", start: "14:00", end: "15:00" }]
};
}
throw new Error(`Unknown tool: ${name}`);
}
const emails = Array.from({ length: 15 }, (_, i) => `user${i}@example.com`).join(", ");
const messages: Anthropic.MessageParam[] = [
{
role: "user",
content: `Schedule a one-hour all-hands on Monday, March 30, 2026 at 10am with everyone: ${emails}`
}
];
let response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
tools,
messages
});
while (response.stop_reason === "tool_use") {
const toolResults: Anthropic.ToolResultBlockParam[] = [];
for (const block of response.content) {
if (block.type === "tool_use") {
try {
const result = runTool(block.name, block.input as Record);
toolResults.push({
type: "tool_result",
tool_use_id: block.id,
content: JSON.stringify(result)
});
} catch (err) {
// 回報失敗，讓 Claude 可以重試或要求釐清。
toolResults.push({
type: "tool_result",
tool_use_id: block.id,
content: String(err),
is_error: true
});
}
}
}
messages.push({ role: "assistant", content: response.content });
messages.push({ role: "user", content: toolResults });
response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
tools,
messages
});
}
for (const block of response.content) {
if (block.type === "text") {
console.log(block.text);
}
}
```
```csharp C#
// 第 4 環：錯誤處理。
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text.Json;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages;
AnthropicClient client = new();
List tools =
[
new ToolUnion(new Tool()
{
Name = "create_calendar_event",
Description = "Create a calendar event with attendees and optional recurrence.",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["title"] = JsonSerializer.SerializeToElement(new { type = "string" }),
["start"] = JsonSerializer.SerializeToElement(new { type = "string", format = "date-time" }),
["end"] = JsonSerializer.SerializeToElement(new { type = "string", format = "date-time" }),
["attendees"] = JsonSerializer.SerializeToElement(new
{
type = "array",
items = new { type = "string", format = "email" },
}),
["recurrence"] = JsonSerializer.SerializeToElement(new
{
type = "object",
properties = new
{
frequency = new { @enum = new[] { "daily", "weekly", "monthly" } },
count = new { type = "integer", minimum = 1 },
},
}),
},
Required = ["title", "start", "end"],
},
}),
new ToolUnion(new Tool()
{
Name = "list_calendar_events",
Description = "List all calendar events on a given date.",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["date"] = JsonSerializer.SerializeToElement(new { type = "string", format = "date" }),
},
Required = ["date"],
},
}),
];
string RunTool(ToolUseBlock toolUse)
{
if (toolUse.Name == "create_calendar_event")
{
if (toolUse.Input.TryGetValue("attendees", out var attendees) && attendees.GetArrayLength() > 10)
{
throw new InvalidOperationException("Too many attendees (max 10)");
}
var title = toolUse.Input.TryGetValue("title", out var t) ? t.GetString() : "";
return JsonSerializer.Serialize(new { event_id = "evt_123", status = "created", title });
}
if (toolUse.Name == "list_calendar_events")
{
return """{"events": [{"title": "Existing meeting", "start": "14:00", "end": "15:00"}]}""";
}
throw new InvalidOperationException($"Unknown tool: {toolUse.Name}");
}
// 建立一個超過該工具與會者上限的請求，以觸發錯誤處理路徑。
var emails = string.Join(", ", Enumerable.Range(0, 15).Select(i => $"user{i}@example.com"));
List messages =
[
new() { Role = Role.User, Content = $"Schedule a one-hour all-hands on Monday, March 30, 2026 at 10am with everyone: {emails}" },
];
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools = tools,
Messages = messages,
});
while (response.StopReason == StopReason.ToolUse)
{
List toolResults = [];
foreach (var block in response.Content)
{
if (block.TryPickToolUse(out var toolUse))
{
ToolResultBlockParam toolResult;
try
{
toolResult = new ToolResultBlockParam() { ToolUseID = toolUse.ID, Content = RunTool(toolUse) };
}
catch (Exception e)
{
// 回報失敗，讓 Claude 可以重試或請求釐清。
toolResult = new ToolResultBlockParam()
{
ToolUseID = toolUse.ID,
Content = e.Message,
IsError = true,
};
}
toolResults.Add(new ContentBlockParam(toolResult));
}
}
messages.Add(new()
{
Role = Role.Assistant,
Content = response.Content.Select(block => new ContentBlockParam(block.Json)).ToList(),
});
messages.Add(new() { Role = Role.User, Content = new MessageParamContent(toolResults) });
response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools = tools,
Messages = messages,
});
}
foreach (var block in response.Content)
{
if (block.TryPickText(out var text))
{
Console.WriteLine(text.Text);
}
}
```
```go Go
// 第 4 環：錯誤處理。
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"strings"
"github.com/anthropics/anthropic-sdk-go"
)
func runTool(name string, input map[string]any) (string, error) {
if name == "create_calendar_event" {
if attendees, ok := input["attendees"].([]any); ok && len(attendees) > 10 {
return "", fmt.Errorf("too many attendees (max 10)")
}
title, _ := input["title"].(string)
return fmt.Sprintf(`{"event_id": "evt_123", "status": "created", "title": %q}`, title), nil
}
if name == "list_calendar_events" {
return `{"events": [{"title": "Existing meeting", "start": "14:00", "end": "15:00"}]}`, nil
}
return "", fmt.Errorf("unknown tool: %s", name)
}
func main() {
client := anthropic.NewClient()
ctx := context.Background()
tools := []anthropic.ToolUnionParam{
{OfTool: &anthropic.ToolParam{
Name: "create_calendar_event",
Description: anthropic.String("Create a calendar event with attendees and optional recurrence."),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"title": map[string]any{"type": "string"},
"start": map[string]any{"type": "string", "format": "date-time"},
"end": map[string]any{"type": "string", "format": "date-time"},
"attendees": map[string]any{
"type": "array",
"items": map[string]any{"type": "string", "format": "email"},
},
"recurrence": map[string]any{
"type": "object",
"properties": map[string]any{
"frequency": map[string]any{"enum": []string{"daily", "weekly", "monthly"}},
"count": map[string]any{"type": "integer", "minimum": 1},
},
},
},
Required: []string{"title", "start", "end"},
},
}},
{OfTool: &anthropic.ToolParam{
Name: "list_calendar_events",
Description: anthropic.String("List all calendar events on a given date."),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"date": map[string]any{"type": "string", "format": "date"},
},
Required: []string{"date"},
},
}},
}
// 建立一個超過該工具與會者上限的請求，以觸發錯誤處理路徑。
emails := make([]string, 15)
for i := range emails {
emails[i] = fmt.Sprintf("user%d@example.com", i)
}
messages := []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock(
"Schedule a one-hour all-hands on Monday, March 30, 2026 at 10am with everyone: " + strings.Join(emails, ", "),
)),
}
response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: tools,
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
for response.StopReason == "tool_use" {
var toolResults []anthropic.ContentBlockParamUnion
for _, block := range response.Content {
if block.Type == "tool_use" {
var input map[string]any
if err := json.Unmarshal(block.Input, &input); err != nil {
log.Fatal(err)
}
result, toolErr := runTool(block.Name, input)
if toolErr != nil {
// 回報失敗，讓 Claude 可以重試或請求釐清。
toolResults = append(toolResults, anthropic.NewToolResultBlock(block.ID, toolErr.Error(), true))
} else {
toolResults = append(toolResults, anthropic.NewToolResultBlock(block.ID, result, false))
}
}
}
var assistantContent []anthropic.ContentBlockParamUnion
for _, block := range response.Content {
assistantContent = append(assistantContent, block.ToParam())
}
messages = append(messages, anthropic.NewAssistantMessage(assistantContent...))
messages = append(messages, anthropic.NewUserMessage(toolResults...))
response, err = client.Messages.New(ctx, anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: tools,
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
}
for _, block := range response.Content {
if block.Type == "text" {
fmt.Println(block.Text)
}
}
}
```
```java Java
// Ring 4：錯誤處理。
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.JsonValue;
import com.anthropic.models.messages.ContentBlock;
import com.anthropic.models.messages.ContentBlockParam;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.MessageParam;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.StopReason;
import com.anthropic.models.messages.Tool;
import com.anthropic.models.messages.Tool.InputSchema;
import com.anthropic.models.messages.ToolResultBlockParam;
import com.anthropic.models.messages.ToolUseBlock;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
import java.util.stream.IntStream;
String runTool(ToolUseBlock toolUse) {
// 原始工具輸入是 JSON 物件；請將其當作 map 讀取欄位。
Map input = (Map) toolUse._input().asObject().get();
if (toolUse.name().equals("create_calendar_event")) {
int attendeeCount = input.containsKey("attendees")
? ((List) input.get("attendees").asArray().get()).size()
: 0;
if (attendeeCount > 10) {
throw new IllegalArgumentException("Too many attendees (max 10)");
}
String title = input.containsKey("title") ? input.get("title").asStringOrThrow() : "";
return "{\"event_id\": \"evt_123\", \"status\": \"created\", \"title\": \"" + title + "\"}";
}
if (toolUse.name().equals("list_calendar_events")) {
return "{\"events\": [{\"title\": \"Existing meeting\", \"start\": \"14:00\", \"end\": \"15:00\"}]}";
}
throw new IllegalArgumentException("Unknown tool: " + toolUse.name());
}
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Tool calendarTool = Tool.builder()
.name("create_calendar_event")
.description("Create a calendar event with attendees and optional recurrence.")
.inputSchema(InputSchema.builder()
.properties(JsonValue.from(Map.of(
"title", Map.of("type", "string"),
"start", Map.of("type", "string", "format", "date-time"),
"end", Map.of("type", "string", "format", "date-time"),
"attendees", Map.of(
"type", "array",
"items", Map.of("type", "string", "format", "email")
),
"recurrence", Map.of(
"type", "object",
"properties", Map.of(
"frequency", Map.of("enum", List.of("daily", "weekly", "monthly")),
"count", Map.of("type", "integer", "minimum", 1)
)
)
)))
.required(List.of("title", "start", "end"))
.build())
.build();
Tool listTool = Tool.builder()
.name("list_calendar_events")
.description("List all calendar events on a given date.")
.inputSchema(InputSchema.builder()
.properties(JsonValue.from(Map.of(
"date", Map.of("type", "string", "format", "date")
)))
.required(List.of("date"))
.build())
.build();
// 建立超過工具出席者上限的請求，以觸發錯誤處理路徑。
String emails = IntStream.range(0, 15)
.mapToObj(i -> "user" + i + "@example.com")
.collect(Collectors.joining(", "));
List messages = new ArrayList<>();
messages.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.content("Schedule a one-hour all-hands on Monday, March 30, 2026 at 10am with everyone: " + emails)
.build());
Message response = client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addTool(calendarTool)
.addTool(listTool)
.messages(messages)
.build());
while (response.stopReason().isPresent()
&& response.stopReason().get().equals(StopReason.TOOL_USE)) {
List toolResults = new ArrayList<>();
for (ContentBlock block : response.content()) {
if (block.toolUse().isPresent()) {
ToolUseBlock toolUse = block.toolUse().get();
ToolResultBlockParam.Builder resultBuilder = ToolResultBlockParam.builder()
.toolUseId(toolUse.id());
try {
resultBuilder.content(runTool(toolUse));
} catch (Exception e) {
// 回報失敗，讓 Claude 可以重試或要求釐清。
resultBuilder.content(e.getMessage()).isError(true);
}
toolResults.add(ContentBlockParam.ofToolResult(resultBuilder.build()));
}
}
messages.add(response.toParam());
messages.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.contentOfBlockParams(toolResults)
.build());
response = client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addTool(calendarTool)
.addTool(listTool)
.messages(messages)
.build());
}
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
```
```php PHP
'create_calendar_event',
'description' => 'Create a calendar event with attendees and optional recurrence.',
'input_schema' => [
'type' => 'object',
'properties' => [
'title' => ['type' => 'string'],
'start' => ['type' => 'string', 'format' => 'date-time'],
'end' => ['type' => 'string', 'format' => 'date-time'],
'attendees' => [
'type' => 'array',
'items' => ['type' => 'string', 'format' => 'email'],
],
'recurrence' => [
'type' => 'object',
'properties' => [
'frequency' => ['enum' => ['daily', 'weekly', 'monthly']],
'count' => ['type' => 'integer', 'minimum' => 1],
],
],
],
'required' => ['title', 'start', 'end'],
],
],
[
'name' => 'list_calendar_events',
'description' => 'List all calendar events on a given date.',
'input_schema' => [
'type' => 'object',
'properties' => [
'date' => ['type' => 'string', 'format' => 'date'],
],
'required' => ['date'],
],
],
];
function runTool(string $name, array $input): string
{
if ($name === 'create_calendar_event') {
if (count($input['attendees'] ?? []) > 10) {
throw new \InvalidArgumentException('Too many attendees (max 10)');
}
return json_encode([
'event_id' => 'evt_123',
'status' => 'created',
'title' => $input['title'],
]);
}
if ($name === 'list_calendar_events') {
return json_encode([
'events' => [['title' => 'Existing meeting', 'start' => '14:00', 'end' => '15:00']],
]);
}
throw new \InvalidArgumentException("Unknown tool: {$name}");
}
// 建立一個超過該工具與會者上限的請求，以觸發錯誤處理路徑。
$emails = array_map(fn (int $i): string => "user{$i}@example.com", range(0, 14));
$messages = [
[
'role' => 'user',
'content' => 'Schedule a one-hour all-hands on Monday, March 30, 2026 at 10am with everyone: ' . implode(', ', $emails),
],
];
$response = $client->messages->create(
model: 'claude-opus-5-5',
maxTokens: 1024,
tools: $tools,
messages: $messages,
);
while ($response->stopReason === 'tool_use') {
$toolResults = [];
foreach ($response->content as $block) {
if ($block->type === 'tool_use') {
try {
$toolResults[] = [
'type' => 'tool_result',
'tool_use_id' => $block->id,
'content' => runTool($block->name, $block->input),
];
} catch (\Exception $e) {
// 回報失敗，讓 Claude 可以重試或請求釐清。
$toolResults[] = [
'type' => 'tool_result',
'tool_use_id' => $block->id,
'content' => $e->getMessage(),
'is_error' => true,
];
}
}
}
$messages[] = ['role' => 'assistant', 'content' => $response->content];
$messages[] = ['role' => 'user', 'content' => $toolResults];
$response = $client->messages->create(
model: 'claude-opus-5-5',
maxTokens: 1024,
tools: $tools,
messages: $messages,
);
}
foreach ($response->content as $block) {
if ($block->type === 'text') {
echo $block->text, "\n";
}
}
```
```ruby Ruby
# 第 4 環：錯誤處理。
require "anthropic"
client = Anthropic::Client.new
tools = [
{
name: "create_calendar_event",
description: "Create a calendar event with attendees and optional recurrence.",
input_schema: {
type: "object",
properties: {
title: {type: "string"},
start: {type: "string", format: "date-time"},
end: {type: "string", format: "date-time"},
attendees: {
type: "array",
items: {type: "string", format: "email"}
},
recurrence: {
type: "object",
properties: {
frequency: {enum: ["daily", "weekly", "monthly"]},
count: {type: "integer", minimum: 1}
}
}
},
required: ["title", "start", "end"]
}
},
{
name: "list_calendar_events",
description: "List all calendar events on a given date.",
input_schema: {
type: "object",
properties: {
date: {type: "string", format: "date"}
},
required: ["date"]
}
}
]
def run_tool(name, input)
case name
when "create_calendar_event"
attendees = input[:attendees]
raise ArgumentError, "Too many attendees (max 10)" if attendees && attendees.length > 10
JSON.generate({event_id: "evt_123", status: "created", title: input[:title]})
when "list_calendar_events"
JSON.generate({events: [{title: "Existing meeting", start: "14:00", end: "15:00"}]})
else
raise ArgumentError, "Unknown tool: #{name}"
end
end
# 建立一個超過該工具與會者上限的請求，以觸發錯誤處理路徑。
emails = (0...15).map { |i| "user#{i}@example.com" }
messages = [
{
role: "user",
content: "Schedule a one-hour all-hands on Monday, March 30, 2026 at 10am with everyone: #{emails.join(", ")}"
}
]
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
tools: tools,
messages: messages
)
while response.stop_reason == :tool_use
tool_results = response.content.select { |block| block.type == :tool_use }.map do |tool_use|
begin
{
type: "tool_result",
tool_use_id: tool_use.id,
content: run_tool(tool_use.name, tool_use.input)
}
rescue => e
# 回報失敗，讓 Claude 可以重試或請求釐清。
{
type: "tool_result",
tool_use_id: tool_use.id,
content: e.message,
is_error: true
}
end
end
messages << {role: "assistant", content: response.content}
messages << {role: "user", content: tool_results}
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
tools: tools,
messages: messages
)
end
response.content.each do |block|
puts block.text if block.type == :text
end
```
**預期結果**
```text Output wrap
I tried to schedule the all-hands but the calendar only allows 10 attendees per event. I can split this into two sessions, or you can let me know which 10 people to prioritize.
```
`is_error` 旗標是與成功結果之間唯一的差異。Claude 會看到該旗標與錯誤文字，並據此回應。完整的錯誤處理參考請參閱[處理工具呼叫](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/handle-tool-calls)。
## 第 5 環：Tool Runner SDK 抽象層
第 2 環到第 4 環都是親手撰寫相同的迴圈：呼叫 API、檢查 `stop_reason`、執行工具、附加結果、重複。Tool Runner 會替您完成這些工作。將每個工具定義為函式，把清單傳給 `client.beta.messages.tool_runner()` (typescript: `client.beta.messages.toolRunner()`; java: `client.beta().messages().toolRunner()`; php: `$client->beta->messages->toolRunner()`; csharp: `client.Beta.Messages.ToolRunner()`; go: `client.Beta.Messages.NewToolRunner()`)，並在迴圈完成後取得最終訊息。錯誤包裝、結果格式化和對話管理都會在內部處理。
每個 SDK 都提供一個輔助工具，可將一般函式轉換為可執行的工具，並從其簽章推導出輸入 schema；下方的分頁顯示了各語言的慣用寫法。
Tool Runner 是 Claude SDK 中的輔助工具。原始 HTTP 請求沒有對應的功能。若要繼續使用 curl，請使用[第 4 環](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/build-a-tool-using-agent#ring-4-error-handling)中的迴圈。
Tool Runner 是 Claude SDK 中的輔助工具。`ant` CLI 沒有對應的功能。若要繼續使用 CLI，請使用[第 4 環](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/build-a-tool-using-agent#ring-4-error-handling)中的迴圈。
```python Python
# Ring 5：Tool Runner SDK 抽象層。
import json
import anthropic
from anthropic import beta_tool
client = anthropic.Anthropic()
@beta_tool
def create_calendar_event(
title: str,
start: str,
end: str,
attendees: list[str] | None = None,
recurrence: dict | None = None,
) -> str:
"""Create a calendar event with attendees and optional recurrence.
Args:
title: Event title.
start: Start time in ISO 8601 format.
end: End time in ISO 8601 format.
attendees: Email addresses to invite.
recurrence: Dict with 'frequency' (daily, weekly, monthly) and 'count'.
"""
if attendees and len(attendees) > 10:
raise ValueError("Too many attendees (max 10)")
return json.dumps({"event_id": "evt_123", "status": "created", "title": title})
@beta_tool
def list_calendar_events(date: str) -> str:
"""List all calendar events on a given date.
Args:
date: Date in YYYY-MM-DD format.
"""
return json.dumps(
{"events": [{"title": "Existing meeting", "start": "14:00", "end": "15:00"}]}
)
final_message = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
tools=[create_calendar_event, list_calendar_events],
messages=[
{
"role": "user",
"content": "Check what I have on Monday, March 30, 2026, then schedule a one-hour planning session that day that avoids any conflicts.",
}
],
).until_done()
for block in final_message.content:
if block.type == "text":
print(block.text)
```
```typescript TypeScript
// Ring 5：Tool Runner SDK 抽象層。
import Anthropic from "@anthropic-ai/sdk";
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";
const client = new Anthropic();
const createCalendarEvent = betaZodTool({
name: "create_calendar_event",
description: "Create a calendar event with attendees and optional recurrence.",
inputSchema: z.object({
title: z.string(),
start: z.string().datetime(),
end: z.string().datetime(),
attendees: z.array(z.string().email()).optional(),
recurrence: z
.object({
frequency: z.enum(["daily", "weekly", "monthly"]),
count: z.number().int().min(1)
})
.optional()
}),
run: async (input) => {
if (input.attendees && input.attendees.length > 10) {
throw new Error("Too many attendees (max 10)");
}
return JSON.stringify({
event_id: "evt_123",
status: "created",
title: input.title
});
}
});
const listCalendarEvents = betaZodTool({
name: "list_calendar_events",
description: "List all calendar events on a given date.",
inputSchema: z.object({
date: z.string().date()
}),
run: async () => {
return JSON.stringify({
events: [{ title: "Existing meeting", start: "14:00", end: "15:00" }]
});
}
});
const finalMessage = await client.beta.messages.toolRunner({
model: "claude-opus-5-5",
max_tokens: 1024,
tools: [createCalendarEvent, listCalendarEvents],
messages: [
{
role: "user",
content:
"Check what I have on Monday, March 30, 2026, then schedule a one-hour planning session that day that avoids any conflicts."
}
]
});
for (const block of finalMessage.content) {
if (block.type === "text") {
console.log(block.text);
}
}
```
```csharp C#
// Ring 5：Tool Runner SDK 抽象層。
using System;
using System.Collections.Generic;
using System.Text.Json;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Helpers.Beta;
using Anthropic.Models.Beta.Messages;
using MessageCreateParams = Anthropic.Models.Beta.Messages.MessageCreateParams;
using InputSchema = Anthropic.Models.Beta.Messages.InputSchema;
using Role = Anthropic.Models.Beta.Messages.Role;
using Model = Anthropic.Models.Messages.Model;
AnthropicClient client = new();
// 將每個工具定義為可執行工具：定義中包含 JSON Schema，
// 而 Run 回呼則存放實作。拋出例外時，會將
// 該訊息以設定了 is_error 的工具結果傳回給 Claude。
var createCalendarEvent = new BetaRunnableTool
{
Name = "create_calendar_event",
Definition = new BetaTool
{
Name = "create_calendar_event",
Description = "Create a calendar event with attendees and optional recurrence.",
InputSchema = new InputSchema
{
Properties = new Dictionary
{
["title"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Event title" }),
["start"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Start time in ISO 8601 format" }),
["end"] = JsonSerializer.SerializeToElement(new { type = "string", description = "End time in ISO 8601 format" }),
["attendees"] = JsonSerializer.SerializeToElement(new
{
type = "array",
items = new { type = "string" },
description = "Email addresses to invite",
}),
["recurrence"] = JsonSerializer.SerializeToElement(new
{
type = "object",
properties = new
{
frequency = new { @enum = new[] { "daily", "weekly", "monthly" } },
count = new { type = "integer", minimum = 1 },
},
}),
},
Required = ["title", "start", "end"],
},
},
Run = (toolUse, _) =>
{
if (toolUse.Input.TryGetValue("attendees", out var attendees) && attendees.GetArrayLength() > 10)
{
throw new InvalidOperationException("Too many attendees (max 10)");
}
var title = toolUse.Input.TryGetValue("title", out var t) ? t.GetString() : "";
return Task.FromResult(
JsonSerializer.Serialize(new { event_id = "evt_123", status = "created", title })
);
},
};
var listCalendarEvents = new BetaRunnableTool
{
Name = "list_calendar_events",
Definition = new BetaTool
{
Name = "list_calendar_events",
Description = "List all calendar events on a given date.",
InputSchema = new InputSchema
{
Properties = new Dictionary
{
["date"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Date in YYYY-MM-DD format" }),
},
Required = ["date"],
},
},
Run = (toolUse, _) => Task.FromResult(
"""{"events": [{"title": "Existing meeting", "start": "14:00", "end": "15:00"}]}"""
),
};
// runner 會呼叫 API、執行所請求的工具，並將結果回傳，
// 直到 Claude 產生最終答案為止。
var runner = client.Beta.Messages.ToolRunner(
new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages =
[
new()
{
Role = Role.User,
Content = "Check what I have on Monday, March 30, 2026, then schedule a one-hour planning session that day that avoids any conflicts.",
},
],
},
[createCalendarEvent, listCalendarEvents]
);
BetaMessage? finalMessage = null;
await foreach (var message in runner)
{
finalMessage = message;
}
foreach (var block in finalMessage!.Content)
{
if (block.TryPickText(out var text))
{
Console.WriteLine(text.Text);
}
}
```
```go Go
// Ring 5：Tool Runner SDK 抽象層。
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
"github.com/anthropics/anthropic-sdk-go/toolrunner"
)
// 輸入 struct 定義每個工具的 schema。tool runner 會根據
// struct 欄位及其 jsonschema 標籤產生 JSON Schema。
type RecurrenceInput struct {
Frequency string `json:"frequency,omitempty" jsonschema:"enum=daily,enum=weekly,enum=monthly,description=How often the event repeats"`
Count int `json:"count,omitempty" jsonschema:"description=Number of occurrences"`
}
type CreateCalendarEventInput struct {
Title string `json:"title" jsonschema:"required,description=Event title"`
Start string `json:"start" jsonschema:"required,description=Start time in ISO 8601 format"`
End string `json:"end" jsonschema:"required,description=End time in ISO 8601 format"`
Attendees []string `json:"attendees,omitempty" jsonschema:"description=Email addresses to invite"`
Recurrence *RecurrenceInput `json:"recurrence,omitempty"`
}
type ListCalendarEventsInput struct {
Date string `json:"date" jsonschema:"required,description=Date in YYYY-MM-DD format"`
}
func main() {
client := anthropic.NewClient()
ctx := context.Background()
// 將每個工具定義為處理函式。回傳錯誤時，會將
// 該訊息作為設定了 is_error 的工具結果傳回給 Claude。
createCalendarEvent, err := toolrunner.NewBetaToolFromJSONSchema(
"create_calendar_event",
"Create a calendar event with attendees and optional recurrence.",
func(ctx context.Context, input CreateCalendarEventInput) (anthropic.BetaToolResultBlockParamContentUnion, error) {
if len(input.Attendees) > 10 {
return anthropic.BetaToolResultBlockParamContentUnion{}, fmt.Errorf("too many attendees (max 10)")
}
return anthropic.BetaToolResultBlockParamContentUnion{
OfText: &anthropic.BetaTextBlockParam{
Text: fmt.Sprintf(`{"event_id": "evt_123", "status": "created", "title": %q}`, input.Title),
},
}, nil
},
)
if err != nil {
log.Fatal(err)
}
listCalendarEvents, err := toolrunner.NewBetaToolFromJSONSchema(
"list_calendar_events",
"List all calendar events on a given date.",
func(ctx context.Context, input ListCalendarEventsInput) (anthropic.BetaToolResultBlockParamContentUnion, error) {
return anthropic.BetaToolResultBlockParamContentUnion{
OfText: &anthropic.BetaTextBlockParam{
Text: `{"events": [{"title": "Existing meeting", "start": "14:00", "end": "15:00"}]}`,
},
}, nil
},
)
if err != nil {
log.Fatal(err)
}
// runner 會呼叫 API、執行所請求的工具，並將結果回傳，
// 直到 Claude 產生最終答案為止。
runner := client.Beta.Messages.NewToolRunner(
[]anthropic.BetaTool{createCalendarEvent, listCalendarEvents},
anthropic.BetaToolRunnerParams{
BetaMessageNewParams: anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(
"Check what I have on Monday, March 30, 2026, then schedule a one-hour planning session that day that avoids any conflicts.",
)),
},
},
},
)
var finalMessage *anthropic.BetaMessage
for message, err := range runner.All(ctx) {
if err != nil {
log.Fatal(err)
}
finalMessage = message
}
for _, block := range finalMessage.Content {
if block.Type == "text" {
fmt.Println(block.Text)
}
}
}
```
```java Java
// 第 5 環：Tool Runner SDK 抽象層。
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.helpers.BetaToolRunner;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.fasterxml.jackson.annotation.JsonClassDescription;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;
import java.util.List;
import java.util.function.Supplier;
// 將每個工具定義為類別：欄位描述輸入結構描述（input schema），而
// get() 方法包含實作。拋出例外時，會將
// 訊息以設定了 is_error 的工具結果傳回給 Claude。
@JsonClassDescription("Create a calendar event with attendees.")
static class CreateCalendarEvent implements Supplier {
@JsonPropertyDescription("Event title")
public String title;
@JsonPropertyDescription("Start time in ISO 8601 format")
public String start;
@JsonPropertyDescription("End time in ISO 8601 format")
public String end;
@JsonPropertyDescription("Email addresses to invite")
public List attendees;
@Override
public String get() {
if (attendees != null && attendees.size() > 10) {
throw new IllegalArgumentException("Too many attendees (max 10)");
}
return "{\"event_id\": \"evt_123\", \"status\": \"created\", \"title\": \"" + title + "\"}";
}
}
@JsonClassDescription("List all calendar events on a given date.")
static class ListCalendarEvents implements Supplier {
@JsonPropertyDescription("Date in YYYY-MM-DD format")
public String date;
@Override
public String get() {
return "{\"events\": [{\"title\": \"Existing meeting\", \"start\": \"14:00\", \"end\": \"15:00\"}]}";
}
}
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// runner 會呼叫 API、執行所請求的工具，並將結果回傳，
// 直到 Claude 產生最終答案為止。
BetaToolRunner runner = client.beta()
.messages()
.toolRunner(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addBeta("structured-outputs-2025-11-13")
.addUserMessage("Check what I have on Monday, March 30, 2026, then schedule a one-hour planning session that day that avoids any conflicts.")
.addTool(CreateCalendarEvent.class)
.addTool(ListCalendarEvents.class)
.build());
BetaMessage finalMessage = null;
for (BetaMessage message : runner) {
finalMessage = message;
}
finalMessage.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
```
```php PHP
'create_calendar_event',
'description' => 'Create a calendar event with attendees and optional recurrence.',
'input_schema' => [
'type' => 'object',
'properties' => [
'title' => ['type' => 'string', 'description' => 'Event title'],
'start' => ['type' => 'string', 'description' => 'Start time in ISO 8601 format'],
'end' => ['type' => 'string', 'description' => 'End time in ISO 8601 format'],
'attendees' => [
'type' => 'array',
'items' => ['type' => 'string'],
'description' => 'Email addresses to invite',
],
'recurrence' => [
'type' => 'object',
'properties' => [
'frequency' => ['enum' => ['daily', 'weekly', 'monthly']],
'count' => ['type' => 'integer', 'minimum' => 1],
],
],
],
'required' => ['title', 'start', 'end'],
],
],
run: function (array $input): string {
if (count($input['attendees'] ?? []) > 10) {
throw new \InvalidArgumentException('Too many attendees (max 10)');
}
return json_encode([
'event_id' => 'evt_123',
'status' => 'created',
'title' => $input['title'],
]);
},
);
$listCalendarEvents = new BetaRunnableTool(
definition: [
'name' => 'list_calendar_events',
'description' => 'List all calendar events on a given date.',
'input_schema' => [
'type' => 'object',
'properties' => [
'date' => ['type' => 'string', 'description' => 'Date in YYYY-MM-DD format'],
],
'required' => ['date'],
],
],
run: fn (array $input): string => json_encode([
'events' => [['title' => 'Existing meeting', 'start' => '14:00', 'end' => '15:00']],
]),
);
// runner 會呼叫 API、執行所請求的工具，並將結果回傳，
// 直到 Claude 產生最終答案為止。
$runner = $client->beta->messages->toolRunner(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => 'Check what I have on Monday, March 30, 2026, then schedule a one-hour planning session that day that avoids any conflicts.',
],
],
model: Model::CLAUDE_OPUS_5_5,
tools: [$createCalendarEvent, $listCalendarEvents],
);
$finalMessage = null;
foreach ($runner as $message) {
$finalMessage = $message;
}
foreach ($finalMessage->content as $block) {
if ($block->type === 'text') {
echo $block->text, "\n";
}
}
```
```ruby Ruby
# Ring 5：Tool Runner SDK 抽象層。
require "anthropic"
client = Anthropic::Client.new
# 將每個工具定義為類別：以具型別的輸入模型描述 schema，
# 並由 call 方法負責實作。拋出錯誤時，錯誤訊息會
# 以設定了 is_error 的工具結果形式傳回給 Claude。
class RecurrenceInput < Anthropic::BaseModel
optional :frequency, Anthropic::InputSchema::EnumOf["daily", "weekly", "monthly"],
doc: "How often the event repeats"
optional :count, Integer, doc: "Number of occurrences"
end
class CreateCalendarEventInput < Anthropic::BaseModel
required :title, String, doc: "Event title"
required :start, String, doc: "Start time in ISO 8601 format"
required :end, String, doc: "End time in ISO 8601 format"
optional :attendees, Anthropic::InputSchema::ArrayOf[String], doc: "Email addresses to invite"
optional :recurrence, RecurrenceInput, doc: "Optional recurrence rule"
end
class CreateCalendarEvent < Anthropic::BaseTool
doc "Create a calendar event with attendees and optional recurrence."
input_schema CreateCalendarEventInput
def call(input)
raise ArgumentError, "Too many attendees (max 10)" if input.attendees && input.attendees.length > 10
JSON.generate({event_id: "evt_123", status: "created", title: input.title})
end
end
class ListCalendarEventsInput < Anthropic::BaseModel
required :date, String, doc: "Date in YYYY-MM-DD format"
end
class ListCalendarEvents < Anthropic::BaseTool
doc "List all calendar events on a given date."
input_schema ListCalendarEventsInput
def call(input)
JSON.generate({events: [{title: "Existing meeting", start: "14:00", end: "15:00"}]})
end
end
# runner 會呼叫 API、執行所請求的工具，並將結果回傳，
# 直到 Claude 產生最終答案為止。
runner = client.beta.messages.tool_runner(
model: "claude-opus-5-5",
max_tokens: 1024,
tools: [CreateCalendarEvent.new, ListCalendarEvents.new],
messages: [
{
role: "user",
content: "Check what I have on Monday, March 30, 2026, then schedule a one-hour planning session that day that avoids any conflicts."
}
]
)
final_message = nil
runner.each_message { |message| final_message = message }
final_message.content.each do |block|
puts block.text if block.type == :text
end
```
**預期結果**
```text Output wrap
I checked your calendar for Monday, March 30 and found an existing meeting from 2pm to 3pm. I've scheduled the planning session for 10am to 11am to avoid the conflict.
```
輸出與第 3 環完全相同。差異在於程式碼：行數大約減半、沒有手動迴圈，而且 schema 與實作放在一起。
## 您建構了什麼
您從單一寫死的工具呼叫開始，最終完成了一個具備正式環境樣貌的代理，能處理多個工具、平行呼叫與錯誤，然後將這一切收斂到 Tool Runner 中。過程中您看到了工具使用協定的每一個部分：`tool_use` 區塊、`tool_result` 區塊、`tool_use_id` 比對、`stop_reason` 檢查，以及 `is_error` 訊號。
## 後續步驟
Schema 規格與最佳實務。
完整的 SDK 抽象層參考。
修正常見的工具使用錯誤。