Add constraints with the `#[Constrained]` attribute: ```php hidelines={..2} highlight={3}

For schemas that PHP type hints can't express, pass a raw associative array through `OutputConfig::with()`. This path skips the `parsedOutput()` helper; decode the response with `json_decode()`: ```php hidelines={1..3} messages->create( maxTokens: 1024, messages: [ ['role' => 'user', 'content' => 'Extract the key information from this email: John Smith (john@example.com) is interested in our Enterprise plan.'], ], model: 'claude-opus-4-7', outputConfig: OutputConfig::with(format: JSONOutputFormat::with(schema: [ 'type' => 'object', 'properties' => [ 'name' => ['type' => 'string'], 'email' => ['type' => 'string'], 'plan_interest' => ['type' => 'string'], ], 'required' => ['name', 'email', 'plan_interest'], 'additionalProperties' => false, ])), ); $contact = json_decode($message->content[0]->text, associative: true); echo "{$contact['name']} ({$contact['email']})\n"; ```

**`output_config: {format: Model}` with `parsed_output`** Define a model class extending `Anthropic::BaseModel` and pass it as the format to `messages.create()`. The response includes a `parsed_output` attribute with a typed Ruby object. ```ruby hidelines={1..2} require "anthropic" class ContactInfo < Anthropic::BaseModel required :name, String required :email, String required :plan_interest, String end client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-7", max_tokens: 1024, messages: [ { role: "user", content: "Extract contact info: John Smith, john@example.com, interested in the Pro plan" } ], output_config: {format: ContactInfo} ) contact = message.parsed_output puts "#{contact.name} (#{contact.email})" ```

The Ruby SDK supports additional model definition features for richer schemas: - **`doc:` keyword:** Add descriptions to fields for more informative schema output - **`Anthropic::ArrayOf[T]`:** Typed arrays. Pass array-level constraints (`min_items:`, `max_items:`) as keywords on `required`/`optional`, not on `ArrayOf` itself - **`Anthropic::EnumOf[:a, :b]`:** Enum fields with constrained values - **`Anthropic::UnionOf[T1, T2]`:** Union types mapped to `anyOf` ```ruby class FamousNumber < Anthropic::BaseModel required :value, Float optional :reason, String, doc: "why is this number mathematically significant?" end class Output < Anthropic::BaseModel required :numbers, Anthropic::ArrayOf[FamousNumber], min_items: 3, max_items: 5 end message = client.messages.create( model: "claude-opus-4-7", max_tokens: 1024, messages: [{role: "user", content: "give me some famous numbers"}], output_config: {format: Output} ) message.parsed_output # => #...]> ```

#### How SDK transformation works The Python, TypeScript, Ruby, and PHP SDKs automatically transform schemas with unsupported features: 1. **Remove unsupported constraints** (for example, `minimum`, `maximum`, `minLength`, `maxLength`) 2. **Update descriptions** with constraint info (for example, "Must be at least 100"), when the constraint is not directly supported with structured outputs 3. **Add `additionalProperties: false`** to all objects 4. **Filter string formats** to supported list only 5. **Validate responses** against your original schema (with all constraints) This means Claude receives a simplified schema, but your code still enforces all constraints through validation. **Example:** A Pydantic field with `minimum: 100` becomes a plain integer in the sent schema, but the SDK updates the description to "Must be at least 100" and validates the response against the original constraint. ### Common use cases

Extract structured data from unstructured text: ```bash CLI ant messages create \ --transform 'content.0.text|@fromstr' --format jsonl <<'YAML' model: claude-opus-4-7 max_tokens: 4096 messages: - role: user content: "Extract invoice data from: Invoice #12345, Date: 2024-01-15, Total: $500.00" output_config: format: type: json_schema schema: type: object properties: invoice_number: {type: string} date: {type: string} total_amount: {type: number} line_items: type: array items: {type: object, additionalProperties: false} customer_name: {type: string} required: [invoice_number, date, total_amount, line_items, customer_name] additionalProperties: false YAML ``` ```python Python hidelines={1} import anthropic from pydantic import BaseModel class Invoice(BaseModel): invoice_number: str date: str total_amount: float line_items: list[dict] customer_name: str client = anthropic.Anthropic() invoice_text = "Invoice #12345, Date: 2024-01-15, Total: $500.00" response = client.messages.parse( model="claude-opus-4-7", max_tokens=4096, output_format=Invoice, messages=[ {"role": "user", "content": f"Extract invoice data from: {invoice_text}"} ], ) print(response.parsed_output) ``` ```typescript TypeScript hidelines={1} import Anthropic from "@anthropic-ai/sdk"; import { z } from "zod"; import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod"; const client = new Anthropic(); const InvoiceSchema = z.object({ invoice_number: z.string(), date: z.string(), total_amount: z.number(), line_items: z.array(z.record(z.string(), z.any())), customer_name: z.string() }); const invoiceText = "Invoice #12345, Date: 2024-01-15, Total: $500.00"; const response = await client.messages.parse({ model: "claude-opus-4-7", max_tokens: 4096, output_config: { format: zodOutputFormat(InvoiceSchema) }, messages: [{ role: "user", content: `Extract invoice data from: ${invoiceText}` }] }); console.log(response.parsed_output); ``` ```csharp C# hidelines={1..4} using System.Text.Json; using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); string invoiceText = "Invoice #12345, Date: 2024-01-15, Total: $500.00"; var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 4096, OutputConfig = new OutputConfig { Format = new JsonOutputFormat { Schema = new Dictionary { ["type"] = JsonSerializer.SerializeToElement("object"), ["properties"] = JsonSerializer.SerializeToElement(new { invoice_number = new { type = "string" }, date = new { type = "string" }, total_amount = new { type = "number" }, line_items = new { type = "array", items = new { type = "object", additionalProperties = false, }, }, customer_name = new { type = "string" }, }), ["required"] = JsonSerializer.SerializeToElement(new[] { "invoice_number", "date", "total_amount", "line_items", "customer_name" }), ["additionalProperties"] = JsonSerializer.SerializeToElement(false), }, }, }, Messages = [new() { Role = Role.User, Content = $"Extract invoice data from: {invoiceText}" }] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() invoiceText := "Invoice #12345, Date: 2024-01-15, Total: $500.00" schema := map[string]any{ "type": "object", "additionalProperties": false, "properties": map[string]any{ "invoice_number": map[string]any{"type": "string"}, "date": map[string]any{"type": "string"}, "total_amount": map[string]any{"type": "number"}, "line_items": map[string]any{ "type": "array", "items": map[string]any{ "type": "object", "additionalProperties": false, "properties": map[string]any{ "description": map[string]any{"type": "string"}, "quantity": map[string]any{"type": "number"}, "unit_price": map[string]any{"type": "number"}, }, "required": []string{"description", "quantity", "unit_price"}, }, }, "customer_name": map[string]any{"type": "string"}, }, "required": []string{"invoice_number", "date", "total_amount", "line_items", "customer_name"}, } response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, OutputConfig: anthropic.OutputConfigParam{ Format: anthropic.JSONOutputFormatParam{ Schema: schema, }, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock(fmt.Sprintf("Extract invoice data from: %s", invoiceText))), }, }) if err != nil { log.Fatal(err) } for _, block := range response.Content { switch variant := block.AsAny().(type) { case anthropic.TextBlock: fmt.Println(variant.Text) } } } ``` ```java Java hidelines={1..6} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.StructuredMessage; import com.anthropic.models.messages.StructuredMessageCreateParams; import com.anthropic.models.messages.Model; import com.fasterxml.jackson.annotation.JsonProperty; static class LineItem { @JsonProperty("description") public String description; @JsonProperty("quantity") public int quantity; @JsonProperty("unit_price") public double unitPrice; } static class Invoice { @JsonProperty("invoice_number") public String invoiceNumber; @JsonProperty("date") public String date; @JsonProperty("total_amount") public double totalAmount; @JsonProperty("line_items") public List lineItems; @JsonProperty("customer_name") public String customerName; } void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); String invoiceText = "Invoice #12345, Date: 2024-01-15, Total: $500.00"; StructuredMessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(4096L) .outputConfig(Invoice.class) .addUserMessage("Extract invoice data from: " + invoiceText) .build(); StructuredMessage response = client.messages().create(params); Invoice invoice = response.content().stream() .flatMap(block -> block.text().stream()) .findFirst().orElseThrow().text(); IO.println(invoice.invoiceNumber + ": $" + invoice.totalAmount); } ``` ```php PHP hidelines={1..3} messages->create( maxTokens: 4096, messages: [ ['role' => 'user', 'content' => "Extract invoice data from: $invoiceText"] ], model: 'claude-opus-4-7', outputConfig: ['format' => Invoice::class], ); $invoice = $message->parsedOutput(); if ($invoice instanceof Invoice) { echo "Invoice {$invoice->invoice_number}: \${$invoice->total_amount}\n"; } ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new class LineItem < Anthropic::BaseModel required :description, String required :amount, Float end class Invoice < Anthropic::BaseModel required :invoice_number, String required :date, String required :total_amount, Float required :line_items, Anthropic::ArrayOf[LineItem] required :customer_name, String end invoice_text = "Invoice #12345, Date: 2024-01-15, Total: $500.00" message = client.messages.create( model: "claude-opus-4-7", max_tokens: 4096, output_config: {format: Invoice}, messages: [ {role: "user", content: "Extract invoice data from: #{invoice_text}"} ] ) invoice = message.parsed_output puts "Invoice #{invoice.invoice_number}: $#{invoice.total_amount}" ```

Classify content with structured categories: ```bash CLI ant messages create \ --transform 'content.0.text|@fromstr' --format jsonl <<'YAML' model: claude-opus-4-7 max_tokens: 1024 messages: - role: user content: "Classify this feedback: Great product, fast shipping!" output_config: format: type: json_schema schema: type: object properties: category: type: string confidence: type: number tags: type: array items: type: string sentiment: type: string required: - category - confidence - tags - sentiment additionalProperties: false YAML ``` ```python Python hidelines={1} from anthropic import Anthropic from pydantic import BaseModel client = Anthropic() class Classification(BaseModel): category: str confidence: float tags: list[str] sentiment: str feedback_text = "Great product, but the delivery was slow." response = client.messages.parse( model="claude-opus-4-7", max_tokens=1024, output_format=Classification, messages=[{"role": "user", "content": f"Classify this feedback: {feedback_text}"}], ) print(response.parsed_output) ``` ```typescript TypeScript hidelines={1} import Anthropic from "@anthropic-ai/sdk"; import { z } from "zod"; import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod"; const client = new Anthropic(); const ClassificationSchema = z.object({ category: z.string(), confidence: z.number(), tags: z.array(z.string()), sentiment: z.string() }); const feedbackText = "Great product, but the delivery was slow."; const response = await client.messages.parse({ model: "claude-opus-4-7", max_tokens: 1024, output_config: { format: zodOutputFormat(ClassificationSchema) }, messages: [{ role: "user", content: `Classify this feedback: ${feedbackText}` }] }); console.log(response.parsed_output); ``` ```csharp C# hidelines={1..6} using System.Text.Json; using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); string feedbackText = "Great product, fast shipping!"; var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = $"Classify this feedback: {feedbackText}" }], OutputConfig = new OutputConfig { Format = new JsonOutputFormat { Schema = new Dictionary { ["type"] = JsonSerializer.SerializeToElement("object"), ["properties"] = JsonSerializer.SerializeToElement(new { category = new { type = "string" }, confidence = new { type = "number" }, tags = new { type = "array", items = new { type = "string" } }, sentiment = new { type = "string" }, }), ["required"] = JsonSerializer.SerializeToElement(new[] { "category", "confidence", "tags", "sentiment" }), ["additionalProperties"] = JsonSerializer.SerializeToElement(false), }, }, }, }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go hidelines={1..14,-1} package main import ( "context" "encoding/json" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() feedbackText := "Great product, fast shipping!" schema := map[string]any{ "type": "object", "properties": map[string]any{ "category": map[string]any{"type": "string"}, "confidence": map[string]any{"type": "number"}, "tags": map[string]any{"type": "array", "items": map[string]any{"type": "string"}}, "sentiment": map[string]any{"type": "string"}, }, "required": []string{"category", "confidence", "tags", "sentiment"}, "additionalProperties": false, } response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 1024, OutputConfig: anthropic.OutputConfigParam{ Format: anthropic.JSONOutputFormatParam{ Schema: schema, }, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock(fmt.Sprintf("Classify this feedback: %s", feedbackText))), }, }) if err != nil { log.Fatal(err) } for _, block := range response.Content { switch variant := block.AsAny().(type) { case anthropic.TextBlock: var result map[string]any json.Unmarshal([]byte(variant.Text), &result) fmt.Println(result) } } } ``` ```java Java hidelines={1..6} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.StructuredMessage; import com.anthropic.models.messages.StructuredMessageCreateParams; import com.anthropic.models.messages.Model; import com.fasterxml.jackson.annotation.JsonProperty; static class Classification { @JsonProperty("category") public String category; @JsonProperty("confidence") public double confidence; @JsonProperty("tags") public List tags; @JsonProperty("sentiment") public String sentiment; } void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); String feedbackText = "Great product, fast shipping!"; StructuredMessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(1024L) .outputConfig(Classification.class) .addUserMessage("Classify this feedback: " + feedbackText) .build(); StructuredMessage response = client.messages().create(params); Classification result = response.content().stream() .flatMap(block -> block.text().stream()) .findFirst().orElseThrow().text(); IO.println(result.category + " (" + result.confidence + ")"); } ``` ```php PHP hidelines={1..3} messages->create( maxTokens: 1024, messages: [ ['role' => 'user', 'content' => "Classify this feedback: {$feedbackText}"] ], model: 'claude-opus-4-7', outputConfig: ['format' => Classification::class], ); $result = $message->parsedOutput(); if ($result instanceof Classification) { echo "{$result->category} ({$result->confidence}): {$result->sentiment}\n"; } ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new class Classification < Anthropic::BaseModel required :category, String required :confidence, Float required :tags, Anthropic::ArrayOf[String] required :sentiment, String end feedback_text = "Great product, fast shipping!" message = client.messages.create( model: "claude-opus-4-7", max_tokens: 1024, output_config: {format: Classification}, messages: [ {role: "user", content: "Classify this feedback: #{feedback_text}"} ] ) puts message.parsed_output ```

Generate API-ready responses: ```bash CLI ant messages create \ --transform 'content.0.text' --raw-output <<'YAML' model: claude-opus-4-7 max_tokens: 1024 output_config: format: type: json_schema schema: type: object properties: status: type: string data: type: object additionalProperties: false errors: type: array items: type: object additionalProperties: false metadata: type: object additionalProperties: false required: - status - data - metadata additionalProperties: false messages: - role: user content: "Process this request: ..." YAML ``` ```python Python hidelines={1} from anthropic import Anthropic from pydantic import BaseModel client = Anthropic() class APIResponse(BaseModel): status: str data: dict errors: list[dict] | None metadata: dict response = client.messages.parse( model="claude-opus-4-7", max_tokens=1024, output_format=APIResponse, messages=[{"role": "user", "content": "Process this request: ..."}], ) print(response.parsed_output) ``` ```typescript TypeScript hidelines={1} import Anthropic from "@anthropic-ai/sdk"; import { z } from "zod"; import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod"; const client = new Anthropic(); const APIResponseSchema = z.object({ status: z.string(), data: z.record(z.string(), z.any()), errors: z.array(z.record(z.string(), z.any())).optional(), metadata: z.record(z.string(), z.any()) }); const response = await client.messages.parse({ model: "claude-opus-4-7", max_tokens: 1024, output_config: { format: zodOutputFormat(APIResponseSchema) }, messages: [{ role: "user", content: "Process this request..." }] }); console.log(response.parsed_output); ``` ```csharp C# hidelines={1..6} using System.Text.Json; using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "Process this request: ..." }], OutputConfig = new OutputConfig { Format = new JsonOutputFormat { Schema = new Dictionary { ["type"] = JsonSerializer.SerializeToElement("object"), ["properties"] = JsonSerializer.SerializeToElement(new { status = new { type = "string" }, data = new { type = "object", additionalProperties = false }, errors = new { type = "array", items = new { type = "object", additionalProperties = false }, }, metadata = new { type = "object", additionalProperties = false }, }), ["required"] = JsonSerializer.SerializeToElement(new[] { "status", "data", "metadata" }), ["additionalProperties"] = JsonSerializer.SerializeToElement(false), }, }, }, }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 1024, OutputConfig: anthropic.OutputConfigParam{ Format: anthropic.JSONOutputFormatParam{ Schema: map[string]any{ "type": "object", "additionalProperties": false, "properties": map[string]any{ "status": map[string]any{ "type": "string", }, "data": map[string]any{ "type": "object", "additionalProperties": false, }, "errors": map[string]any{ "type": "array", "items": map[string]any{ "type": "object", "additionalProperties": false, }, }, "metadata": map[string]any{ "type": "object", "additionalProperties": false, }, }, "required": []string{"status", "data", "metadata"}, }, }, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Process this request: ...")), }, }) if err != nil { log.Fatal(err) } for _, block := range response.Content { switch variant := block.AsAny().(type) { case anthropic.TextBlock: fmt.Println(variant.Text) } } } ``` ```java Java hidelines={1..6} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.StructuredMessage; import com.anthropic.models.messages.StructuredMessageCreateParams; import com.anthropic.models.messages.Model; import com.fasterxml.jackson.annotation.JsonProperty; static class APIData { @JsonProperty("message") public String message; @JsonProperty("resource_id") public String resourceId; } static class APIError { @JsonProperty("code") public String code; @JsonProperty("message") public String message; } static class APIMetadata { @JsonProperty("request_id") public String requestId; @JsonProperty("timestamp") public String timestamp; } static class APIResponse { @JsonProperty("status") public String status; @JsonProperty("data") public APIData data; @JsonProperty("errors") public List errors; @JsonProperty("metadata") public APIMetadata metadata; } void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); StructuredMessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(1024L) .outputConfig(APIResponse.class) .addUserMessage("Process this request: ...") .build(); StructuredMessage response = client.messages().create(params); APIResponse result = response.content().stream() .flatMap(block -> block.text().stream()) .findFirst().orElseThrow().text(); IO.println(result.status); } ``` ```php PHP hidelines={1..3} messages->create( maxTokens: 1024, messages: [ ['role' => 'user', 'content' => 'Process this request: ...'] ], model: 'claude-opus-4-7', outputConfig: ['format' => APIResponse::class], ); $result = $message->parsedOutput(); if ($result instanceof APIResponse) { echo "{$result->status}: {$result->data->message}\n"; } ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new class Payload < Anthropic::BaseModel required :message, String end class APIError < Anthropic::BaseModel required :code, String required :detail, String end class Metadata < Anthropic::BaseModel required :request_id, String end class APIResponse < Anthropic::BaseModel required :status, String required :data, Payload optional :errors, Anthropic::ArrayOf[APIError] required :metadata, Metadata end message = client.messages.create( model: "claude-opus-4-7", max_tokens: 1024, output_config: {format: APIResponse}, messages: [ {role: "user", content: "Process this request: ..."} ] ) puts message.parsed_output ```

## Strict tool use For enforcing JSON Schema compliance on tool inputs with grammar-constrained sampling, see [Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use). ## Using both features together JSON outputs and strict tool use solve different problems and work together: - **JSON outputs** control Claude's response format (what Claude says) - **Strict tool use** validates tool parameters (how Claude calls your functions) When combined, Claude can call tools with guaranteed-valid parameters AND return structured JSON responses. This is useful for agentic workflows where you need both reliable tool calls and structured final outputs. ```bash CLI nocheck ant messages create <<'YAML' model: claude-opus-4-7 max_tokens: 1024 messages: - role: user content: Help me plan a trip to Paris departing May 15, 2026 # JSON outputs: structured response format output_config: format: type: json_schema schema: type: object properties: summary: type: string next_steps: type: array items: type: string required: [summary, next_steps] additionalProperties: false # Strict tool use: guaranteed tool parameters tools: - name: search_flights strict: true input_schema: type: object properties: destination: type: string date: type: string format: date required: [destination, date] additionalProperties: false YAML ``` ```python Python hidelines={1..4} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-4-7", max_tokens=1024, messages=[ { "role": "user", "content": "Help me plan a trip to Paris departing May 15, 2026", } ], # JSON outputs: structured response format output_config={ "format": { "type": "json_schema", "schema": { "type": "object", "properties": { "summary": {"type": "string"}, "next_steps": {"type": "array", "items": {"type": "string"}}, }, "required": ["summary", "next_steps"], "additionalProperties": False, }, } }, # Strict tool use: guaranteed tool parameters tools=[ { "name": "search_flights", "strict": True, "input_schema": { "type": "object", "properties": { "destination": {"type": "string"}, "date": {"type": "string", "format": "date"}, }, "required": ["destination", "date"], "additionalProperties": False, }, } ], ) print(response) ``` ```typescript TypeScript hidelines={1..4} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const response = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 1024, messages: [{ role: "user", content: "Help me plan a trip to Paris departing May 15, 2026" }], // JSON outputs: structured response format output_config: { format: { type: "json_schema", schema: { type: "object", properties: { summary: { type: "string" }, next_steps: { type: "array", items: { type: "string" } } }, required: ["summary", "next_steps"], additionalProperties: false } } }, // Strict tool use: guaranteed tool parameters tools: [ { name: "search_flights", description: "Search for available flights to a destination on a specific date", strict: true, input_schema: { type: "object", properties: { destination: { type: "string" }, date: { type: "string", format: "date" } }, required: ["destination", "date"], additionalProperties: false } } ] }); // Claude may call the tool first (tool_use) or respond with JSON (text) console.log("Stop reason:", response.stop_reason); for (const block of response.content) { if (block.type === "tool_use") { console.log(`Tool call: ${block.name}(${JSON.stringify(block.input)})`); } else if (block.type === "text") { console.log("Response:", block.text); } } ``` ```csharp C# hidelines={1..6} using System.Text.Json; using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "Help me plan a trip to Paris departing May 15, 2026" }], // JSON outputs: structured response format OutputConfig = new OutputConfig { Format = new JsonOutputFormat { Schema = new Dictionary { ["type"] = JsonSerializer.SerializeToElement("object"), ["properties"] = JsonSerializer.SerializeToElement(new { summary = new { type = "string" }, next_steps = new { type = "array", items = new { type = "string" } }, }), ["required"] = JsonSerializer.SerializeToElement(new[] { "summary", "next_steps" }), ["additionalProperties"] = JsonSerializer.SerializeToElement(false), }, }, }, // Strict tool use: guaranteed tool parameters Tools = [ new Tool { Name = "search_flights", Strict = true, InputSchema = new InputSchema(new Dictionary { ["properties"] = JsonSerializer.SerializeToElement(new Dictionary { ["destination"] = new { type = "string" }, ["date"] = new { type = "string", format = "date" }, }), ["required"] = JsonSerializer.SerializeToElement(new[] { "destination", "date" }), ["additionalProperties"] = JsonSerializer.SerializeToElement(false), }), } ], }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Help me plan a trip to Paris departing May 15, 2026")), }, // JSON outputs: structured response format OutputConfig: anthropic.OutputConfigParam{ Format: anthropic.JSONOutputFormatParam{ Schema: map[string]any{ "type": "object", "additionalProperties": false, "properties": map[string]any{ "summary": map[string]any{"type": "string"}, "next_steps": map[string]any{"type": "array", "items": map[string]any{"type": "string"}}, }, "required": []string{"summary", "next_steps"}, }, }, }, // Strict tool use: guaranteed tool parameters Tools: []anthropic.ToolUnionParam{ {OfTool: &anthropic.ToolParam{ Name: "search_flights", Strict: anthropic.Bool(true), InputSchema: anthropic.ToolInputSchemaParam{ Properties: map[string]any{ "destination": map[string]any{"type": "string"}, "date": map[string]any{"type": "string", "format": "date"}, }, Required: []string{"destination", "date"}, ExtraFields: map[string]any{ "additionalProperties": false, }, }}}, }, }) if err != nil { log.Fatal(err) } fmt.Println(response.Content) } ``` ```java Java hidelines={1..12,53} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.core.JsonValue; import com.anthropic.models.messages.JsonOutputFormat; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; import com.anthropic.models.messages.OutputConfig; import com.anthropic.models.messages.Tool; import com.anthropic.models.messages.Tool.InputSchema; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); // JSON outputs: structured response format JsonOutputFormat.Schema outputSchema = JsonOutputFormat.Schema.builder() .putAdditionalProperty("type", JsonValue.from("object")) .putAdditionalProperty("properties", JsonValue.from(Map.of( "summary", Map.of("type", "string"), "next_steps", Map.of("type", "array", "items", Map.of("type", "string")) ))) .putAdditionalProperty("required", JsonValue.from(List.of("summary", "next_steps"))) .putAdditionalProperty("additionalProperties", JsonValue.from(false)) .build(); // Strict tool use: guaranteed tool parameters InputSchema toolSchema = InputSchema.builder() .properties(JsonValue.from(Map.of( "destination", Map.of("type", "string"), "date", Map.of("type", "string", "format", "date") ))) .putAdditionalProperty("required", JsonValue.from(List.of("destination", "date"))) .putAdditionalProperty("additionalProperties", JsonValue.from(false)) .build(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(1024L) .addUserMessage("Help me plan a trip to Paris departing May 15, 2026") .outputConfig(OutputConfig.builder() .format(JsonOutputFormat.builder().schema(outputSchema).build()) .build()) .addTool(Tool.builder() .name("search_flights") .description("Search for available flights to a destination on a specific date") .strict(true) .inputSchema(toolSchema) .build()) .build(); Message response = client.messages().create(params); IO.println(response); } ``` ```php PHP hidelines={1..3} messages->create( maxTokens: 1024, messages: [ ['role' => 'user', 'content' => 'Help me plan a trip to Paris departing May 15, 2026'] ], model: 'claude-opus-4-7', // JSON outputs: structured response format outputConfig: ['format' => TripPlan::class], // Strict tool use: guaranteed tool parameters tools: [ [ 'name' => 'search_flights', 'strict' => true, 'input_schema' => [ 'type' => 'object', 'properties' => [ 'destination' => ['type' => 'string'], 'date' => ['type' => 'string', 'format' => 'date'] ], 'required' => ['destination', 'date'], 'additionalProperties' => false ] ] ], ); // Claude may call the tool first (tool_use) or respond with JSON (text) $plan = $message->parsedOutput(); if ($plan instanceof TripPlan) { echo $plan->summary, "\n"; } elseif ($toolUse = array_find($message->content, fn($block) => $block instanceof ToolUseBlock)) { echo "Tool call: {$toolUse->name}(", json_encode($toolUse->input), ")\n"; } ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-7", max_tokens: 1024, messages: [ {role: "user", content: "Help me plan a trip to Paris departing May 15, 2026"} ], # JSON outputs: structured response format output_config: { format: { type: :json_schema, schema: { type: "object", properties: { summary: {type: "string"}, next_steps: {type: "array", items: {type: "string"}} }, required: ["summary", "next_steps"], additionalProperties: false } } }, # Strict tool use: guaranteed tool parameters tools: [ { name: "search_flights", strict: true, input_schema: { type: "object", properties: { destination: {type: "string"}, date: {type: "string", format: "date"} }, required: ["destination", "date"], additionalProperties: false } } ] ) puts message ``` ## Important considerations ### Grammar compilation and caching Structured outputs use constrained sampling with compiled grammar artifacts. This introduces some performance characteristics to be aware of: - **First request latency:** The first time you use a specific schema, there is additional latency while the grammar compiles - **Automatic caching:** Compiled grammars are cached for 24 hours from last use, making subsequent requests much faster - **Cache invalidation:** The cache is invalidated if you change: - The JSON schema structure - The set of tools in your request (when using both structured outputs and tool use) - Changing only `name` or `description` fields does not invalidate the cache ### Prompt modification and token costs When using structured outputs, Claude automatically receives an additional system prompt explaining the expected output format. This means: - Your input token count is slightly higher - The injected prompt costs you tokens like any other system prompt - Changing the `output_config.format` parameter will invalidate any [prompt cache](/docs/en/build-with-claude/prompt-caching) for that conversation thread ### JSON Schema limitations Structured outputs support standard JSON Schema with some limitations. Both JSON outputs and strict tool use share these limitations.

- All basic types: object, array, string, integer, number, boolean, null - `enum` (strings, numbers, bools, or nulls only - no complex types) - `const` - `anyOf` and `allOf` (with limitations - `allOf` with `$ref` not supported) - `$ref`, `$def`, and `definitions` (external `$ref` not supported) - `default` property for all supported types - `required` and `additionalProperties` (must be set to `false` for objects) - String formats: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `uri`, `ipv4`, `ipv6`, `uuid` - Array `minItems` (only values 0 and 1 supported)

- Recursive schemas - Complex types within enums - External `$ref` (for example, `'$ref': 'http://...'`) - Numerical constraints (`minimum`, `maximum`, `multipleOf`, etc.) - String constraints (`minLength`, `maxLength`) - Array constraints beyond `minItems` of 0 or 1 - `additionalProperties` set to anything other than `false` If you use an unsupported feature, you'll receive a 400 error with details.

**Supported regex features:** - Full matching (`^...$`) and partial matching - Quantifiers: `*`, `+`, `?`, simple `{n,m}` cases - Character classes: `[]`, `.`, `\d`, `\w`, `\s` - Groups: `(...)` **NOT supported:** - Backreferences to groups (for example, `\1`, `\2`) - Lookahead/lookbehind assertions (for example, `(?=...)`, `(?!...)`) - Word boundaries: `\b`, `\B` - Complex `{n,m}` quantifiers with large ranges Simple regex patterns work well. Complex patterns may result in 400 errors.

The Python, TypeScript, Ruby, and PHP SDKs can automatically transform schemas with unsupported features by removing them and adding constraints to field descriptions. See [SDK-specific methods](#sdk-specific-methods) for details. ### Property ordering When using structured outputs, properties in objects maintain their defined ordering from your schema, with one important caveat: **required properties appear first, followed by optional properties**. For example, given this schema: ```json { "type": "object", "properties": { "notes": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "age": { "type": "integer" } }, "required": ["name", "email"], "additionalProperties": false } ``` The output will order properties as: 1. `name` (required, in schema order) 2. `email` (required, in schema order) 3. `notes` (optional, in schema order) 4. `age` (optional, in schema order) This means the output might look like: ```json { "name": "John Smith", "email": "john@example.com", "notes": "Interested in enterprise plan", "age": 35 } ``` If property order in the output is important to your application, mark all properties as required, or account for this reordering in your parsing logic. ### Invalid outputs While structured outputs guarantee schema compliance in most cases, there are scenarios where the output may not match your schema: **Refusals** (`stop_reason: "refusal"`) Claude maintains its safety and helpfulness properties even when using structured outputs. If Claude refuses a request for safety reasons: - The response has `stop_reason: "refusal"` - You'll receive a 200 status code - You'll be billed for the tokens generated - The output may not match your schema because the refusal message takes precedence over schema constraints **Token limit reached** (`stop_reason: "max_tokens"`) If the response is cut off due to reaching the `max_tokens` limit: - The response has `stop_reason: "max_tokens"` - The output may be incomplete and not match your schema - Retry with a higher `max_tokens` value to get the complete structured output ### Schema complexity limits Structured outputs work by compiling your JSON schemas into a grammar that constrains Claude's output. More complex schemas produce larger grammars that take longer to compile. To protect against excessive compilation times, the API enforces several complexity limits. #### Explicit limits The following limits apply to all requests with `output_config.format` or `strict: true`: | Limit | Value | Description | |-------|-------|-------------| | Strict tools per request | 20 | Maximum number of tools with `strict: true`. Non-strict tools don't count toward this limit. | | Optional parameters | 24 | Total optional parameters across all strict tool schemas and JSON output schemas. Each parameter not listed in `required` counts toward this limit. | | Parameters with union types | 16 | Total parameters that use `anyOf` or type arrays (for example, `"type": ["string", "null"]`) across all strict schemas. These are especially expensive because they create exponential compilation cost. | These limits apply to the combined total across all strict schemas in a single request. For example, if you have 4 strict tools with 6 optional parameters each, you'll reach the 24-parameter limit even though no single tool seems complex. #### Additional internal limits Beyond the explicit limits in the preceding table, there are additional internal limits on the compiled grammar size. These limits exist because schema complexity doesn't reduce to a single dimension: features like optional parameters, union types, nested objects, and number of tools interact with each other in ways that can make the compiled grammar disproportionately large. When these limits are exceeded, you'll receive a 400 error with the message "Schema is too complex for compilation." These errors mean the combined complexity of your schemas exceeds what can be efficiently compiled, even if each individual limit in the preceding table is satisfied. As a final stop-gap, the API also enforces a **compilation timeout of 180 seconds**. Schemas that pass all explicit checks but produce very large compiled grammars may hit this timeout. #### Tips for reducing schema complexity If you're hitting complexity limits, try these strategies in order: 1. **Mark only critical tools as strict.** If you have many tools, reserve it for tools where schema violations cause real problems, and rely on Claude's natural adherence for simpler tools. 2. **Reduce optional parameters.** Make parameters `required` where possible. Each optional parameter roughly doubles a portion of the grammar's state space. If a parameter always has a reasonable default, consider making it required and having Claude provide that default explicitly. 3. **Simplify nested structures.** Deeply nested objects with optional fields compound the complexity. Flatten structures where possible. 4. **Split into multiple requests.** If you have many strict tools, consider splitting them across separate requests or sub-agents. For persistent issues with valid schemas, [contact support](https://support.claude.com/en/articles/9015913-how-to-get-support) with your schema definition. ## Data retention Prompts and responses are processed with ZDR when using structured outputs. However, the JSON schema itself is temporarily cached for up to 24 hours since last use for optimization purposes. No prompt or response data is retained beyond the API response. Structured outputs are HIPAA eligible, but **PHI must not be included in JSON schema definitions**. The API compiles JSON schemas into grammars that are cached separately from message content, and these cached schemas do not receive the same PHI protections as prompts and responses. Do not include PHI in schema property names, `enum` values, `const` values, or `pattern` regular expressions. PHI should only appear in message content (prompts and responses), where it is protected under HIPAA safeguards. For ZDR and HIPAA eligibility across all features, see [API and data retention](/docs/en/manage-claude/api-and-data-retention). ## Feature compatibility **Works with:** - **[Batch processing](/docs/en/build-with-claude/batch-processing):** Process structured outputs at scale with 50% discount - **[Token counting](/docs/en/build-with-claude/token-counting):** Count tokens without compilation - **[Streaming](/docs/en/build-with-claude/streaming):** Stream structured outputs like normal responses - **Combined usage:** Use JSON outputs (`output_config.format`) and strict tool use (`strict: true`) together in the same request **Incompatible with:** - **[Citations](/docs/en/build-with-claude/citations):** Citations require interleaving citation blocks with text, which conflicts with strict JSON schema constraints. Returns 400 error if citations enabled with `output_config.format`. - **Message Prefilling:** Incompatible with JSON outputs **Grammar scope:** Grammars apply only to Claude's direct output, not to tool use calls, tool results, or thinking tags (when using [Extended Thinking](/docs/en/build-with-claude/extended-thinking)). Grammar state resets between sections, allowing Claude to think freely while still producing structured output in the final response. --- # Task budgets URL: https://platform.claude.com/docs/en/build-with-claude/task-budgets # Task budgets Give Claude an advisory token budget for the full agentic loop to help the model self-regulate on long agentic tasks with task budgets. --- This feature is eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned. Task budgets let you tell Claude how many tokens it has for a full agentic loop, including thinking, tool calls, tool results, and output. The model sees a running countdown and uses it to prioritize work and finish gracefully as the budget is consumed. Task budgets are in public beta on [Claude Opus 4.7](/docs/en/about-claude/models/overview). Set the `task-budgets-2026-03-13` beta header to opt in. ## When to use task budgets Task budgets work best for agentic workflows where Claude makes multiple tool calls and decisions before finalizing its output to await the next human response. Use them when: - You want Claude to self-regulate token spend on long-horizon tasks. - You have a predictable per-task cost or latency ceiling to enforce. - You want the model to finish gracefully (summarize findings, report progress) as it approaches the budget rather than cutting off mid-action. Task budgets complement the [effort parameter](/docs/en/build-with-claude/effort): effort controls how thoroughly Claude reasons about each step, while task budgets cap the total work Claude can do across an agentic loop. ## Setting a task budget Add `task_budget` to `output_config` and include the beta header: ```bash cURL curl https://api.anthropic.com/v1/messages \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "anthropic-beta: task-budgets-2026-03-13" \ --header "content-type: application/json" \ --data '{ "model": "claude-opus-4-7", "max_tokens": 128000, "messages": [{ "role": "user", "content": "Review the codebase and propose a refactor plan." }], "output_config": { "effort": "high", "task_budget": {"type": "tokens", "total": 64000} } }' ``` ```bash CLI ant beta:messages create --beta task-budgets-2026-03-13 <<'YAML' model: claude-opus-4-7 max_tokens: 128000 messages: - role: user content: Review the codebase and propose a refactor plan. output_config: effort: high task_budget: type: tokens total: 64000 YAML ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() response = client.beta.messages.create( model="claude-opus-4-7", max_tokens=128000, output_config={ "effort": "high", "task_budget": {"type": "tokens", "total": 64000}, }, messages=[ {"role": "user", "content": "Review the codebase and propose a refactor plan."} ], betas=["task-budgets-2026-03-13"], ) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const response = await client.beta.messages.create({ model: "claude-opus-4-7", max_tokens: 128000, output_config: { effort: "high", task_budget: { type: "tokens", total: 64000 } }, messages: [{ role: "user", content: "Review the codebase and propose a refactor plan." }], betas: ["task-budgets-2026-03-13"] }); ``` ```go Go hidelines={1..10,-2..} package main import ( "context" "fmt" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, _ := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: "claude-opus-4-7", MaxTokens: 128000, Betas: []anthropic.AnthropicBeta{"task-budgets-2026-03-13"}, Messages: []anthropic.BetaMessageParam{{ Role: anthropic.BetaMessageParamRoleUser, Content: []anthropic.BetaContentBlockParamUnion{{ OfText: &anthropic.BetaTextBlockParam{Text: "Review the codebase and propose a refactor plan."}, }}, }}, OutputConfig: anthropic.BetaOutputConfigParam{ Effort: anthropic.BetaOutputConfigEffortHigh, TaskBudget: anthropic.BetaTokenTaskBudgetParam{ Total: 64000, }, }, }) fmt.Println(response) } ``` ```java Java hidelines={1..7,9..11,-2..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.beta.messages.BetaMessage; import com.anthropic.models.beta.messages.BetaOutputConfig; import com.anthropic.models.beta.messages.BetaTokenTaskBudget; import com.anthropic.models.beta.messages.MessageCreateParams; import com.anthropic.models.messages.Model; public class Main { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(128000L) .addUserMessage("Review the codebase and propose a refactor plan.") .outputConfig(BetaOutputConfig.builder() .effort(BetaOutputConfig.Effort.HIGH) .taskBudget(BetaTokenTaskBudget.builder().total(64000L).build()) .build()) .addBeta("task-budgets-2026-03-13") .build(); BetaMessage response = client.beta().messages().create(params); } } ``` ```csharp C# hidelines={1..3} using Anthropic; using Anthropic.Models.Beta.Messages; using Anthropic.Models.Messages; var client = new AnthropicClient(); var response = await client.Beta.Messages.Create(new MessageCreateParams { Model = "claude-opus-4-7", MaxTokens = 128000, Messages = [new() { Role = Role.User, Content = "Review the codebase and propose a refactor plan." }], OutputConfig = new BetaOutputConfig { Effort = Effort.High, TaskBudget = new BetaTokenTaskBudget { Total = 64000 }, }, Betas = ["task-budgets-2026-03-13"], }); ``` ```php PHP hidelines={1..4} beta->messages->create( model: 'claude-opus-4-7', maxTokens: 128000, messages: [ ['role' => 'user', 'content' => 'Review the codebase and propose a refactor plan.'], ], outputConfig: [ 'effort' => 'high', 'taskBudget' => ['type' => 'tokens', 'total' => 64000], ], betas: ['task-budgets-2026-03-13'], ); ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new response = client.beta.messages.create( model: "claude-opus-4-7", max_tokens: 128_000, messages: [ { role: "user", content: "Review the codebase and propose a refactor plan." } ], output_config: { effort: :high, task_budget: { type: :tokens, total: 64_000 } }, betas: ["task-budgets-2026-03-13"] ) puts response ``` The `task_budget` object has three fields: - `type`: always `"tokens"`. - `total`: the number of tokens Claude can spend across the agentic loop, including thinking, tool calls, tool results, and output. - `remaining` (optional): the budget remainder carried over from a prior request. Defaults to `total` when omitted. ## How the budget countdown works Claude sees a budget-countdown marker injected server-side throughout the conversation. The marker shows how many tokens remain in the current agentic loop and updates as the model generates thinking, tool calls, and output, and as it processes tool results. Claude uses this signal to pace itself and finish gracefully as the budget is consumed. **The countdown reflects tokens Claude has processed in the current agentic loop, not tokens you resend between turns.** If your client sends the full conversation history on every follow-up request, your client-side token count may differ from the budget Claude is tracking. If you also decrement `remaining` while resending full history, the model sees an under-reported budget and the countdown drops faster than it should, causing Claude to wrap up earlier than the budget actually allows. Set a generous budget and let the model self-regulate against the countdown rather than trying to mirror it client-side. ### Worked example: budget counting across turns The task budget counts what Claude **sees** (thinking, tool calls and results, and text), not what's in your request payload. In an agentic loop your client resends the full conversation on every request, so the payload grows turn over turn, but the budget only decrements by the tokens Claude sees this turn. Consider a loop with `task_budget: {type: "tokens", total: 100000}` and a single `bash` tool. **Turn 1.** You send the initial request: ```json { "messages": [ { "role": "user", "content": "Audit this repo for security issues and report findings." } ] } ``` Claude thinks, then emits a tool call and stops with `stop_reason: "tool_use"`: ```json { "role": "assistant", "content": [ { "type": "thinking", "thinking": "I'll start by listing dependencies to look for known-vulnerable packages..." }, { "type": "tool_use", "id": "toolu_01", "name": "bash", "input": { "command": "cat package.json && npm audit --json" } } ] } ``` Suppose this assistant turn (thinking plus the tool call) totals 5,000 generated tokens. The countdown Claude saw during generation ended near `remaining` ≈ 95,000. **Turn 2.** Your client executes the tool, then resends the full history with the tool result appended: ```json { "messages": [ { "role": "user", "content": "Audit this repo for security issues and report findings." }, { "role": "assistant", "content": [ { "type": "thinking", "thinking": "I'll start by listing dependencies..." }, { "type": "tool_use", "id": "toolu_01", "name": "bash", "input": { "command": "cat package.json && npm audit --json" } } ] }, { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01", "content": "<2,800 tokens of npm audit output>" } ] } ] } ``` The resent turn-1 user and assistant messages are not counted again, but the 2,800-token tool result is new content Claude sees this turn and counts against the budget. Claude spends another 4,000 tokens on thinking and a second tool call (`grep -rn "eval(" src/`). The countdown ends near `remaining` ≈ 88,200. **Turn 3.** Full history resent again with the second tool result (1,200 tokens of grep output) appended. Claude writes a 6,000-token final findings report and stops with `stop_reason: "end_turn"`. `remaining` ≈ 81,000. Putting the three turns side by side makes the distinction between payload size and budget spend explicit: | Turn | Request payload (approx. input tokens you sent) | Tokens counted against budget this turn | Budget `remaining` after | |---|---|---|---| | 1 | ~20 | 5,000 (thinking + `tool_use`) | ~95,000 | | 2 | ~7,800 (turn 1 history + tool result) | 6,800 (2,800 tool result + 4,000 thinking and `tool_use`) | ~88,200 | | 3 | ~13,000 (full history + second tool result) | 7,200 (1,200 tool result + 6,000 `text`) | ~81,000 | | **Total** | **~20,820 sent across requests** | **19,000 counted against budget** | — | Your client sent the turn-1 user message three times and the turn-1 assistant message twice, but each was counted once. The budget spent 19,000 of 100,000 tokens, even though the cumulative payload your client transmitted was larger and the prompt-cached input on turns 2 and 3 was larger still. ### Carrying a budget across compaction with `remaining` If your agentic loop compacts or rewrites context between requests (for example, by summarizing earlier turns), the server has no memory of how much budget was spent before compaction. Pass `remaining` on the next request so the countdown continues from where you left off rather than resetting to `total`: ```python Python output_config = { "effort": "high", "task_budget": { "type": "tokens", "total": 128000, "remaining": 128000 - tokens_spent_so_far, }, } ``` ```typescript TypeScript const output_config = { effort: "high", task_budget: { type: "tokens", total: 128000, remaining: 128000 - tokensSpentSoFar } }; ``` ```go Go outputConfig := anthropic.BetaOutputConfigParam{ Effort: anthropic.BetaOutputConfigEffortHigh, TaskBudget: anthropic.BetaTokenTaskBudgetParam{ Total: 128000, Remaining: anthropic.Int(128000 - tokensSpentSoFar), }, } ``` ```java Java BetaOutputConfig outputConfig = BetaOutputConfig.builder() .effort(BetaOutputConfig.Effort.HIGH) .taskBudget(BetaTokenTaskBudget.builder() .total(128000L) .remaining(128000L - tokensSpentSoFar) .build()) .build(); ``` ```csharp C# var outputConfig = new BetaOutputConfig { Effort = Effort.High, TaskBudget = new BetaTokenTaskBudget { Total = 128000, Remaining = 128000 - tokensSpentSoFar, }, }; ``` ```php PHP $outputConfig = [ 'effort' => 'high', 'taskBudget' => [ 'type' => 'tokens', 'total' => 128000, 'remaining' => 128000 - $tokensSpentSoFar, ], ]; ``` ```ruby Ruby output_config = { effort: :high, task_budget: { type: :tokens, total: 128_000, remaining: 128_000 - tokens_spent_so_far } } ``` For loops that resend the full uncompacted history on every turn, omit `remaining` and let the server track the countdown. ## Task budgets are advisory, not enforced Task budgets are a **soft hint, not a hard cap**. Claude may occasionally exceed the budget if it is in the middle of an action that would be more disruptive to interrupt than to finish. The enforced limit on total output tokens is still `max_tokens`, which truncates the response with `stop_reason: "max_tokens"` when reached. For a hard cap on cost or latency, combine task budgets with a reasonable `max_tokens` value: - Use `task_budget` to give Claude a target to pace against. - Use `max_tokens` as the absolute ceiling that prevents runaway generation. Because `task_budget` spans the full agentic loop (potentially many requests) while `max_tokens` caps each individual request, the two values are independent; one is not required to be at or below the other. **A budget that is too small for the task can cause refusal-like behavior.** When Claude sees a budget that is clearly insufficient for the work being asked (for example, a 20,000-token budget for a multi-hour agentic coding task), it may decline to attempt the task at all, scope it down aggressively, or stop early with a partial result rather than start work it cannot finish. If you observe unexpected refusals or premature stops after setting a budget, raise the budget before debugging other parameters. Size budgets against your actual task-length distribution rather than a fixed default; see [Choosing a budget](#choosing-a-budget). ## Choosing a budget The right budget depends on how much work your agentic loop currently does. Rather than guessing, measure your existing token usage first and then tune from there. ### Measure your current usage Run a representative sample of tasks **without** `task_budget` set and record the total tokens Claude spends per task. For an agentic loop, sum `usage.output_tokens` plus thinking and tool-result tokens across every request in the loop: ```python Python def run_task_and_count_tokens(messages: list) -> int: """Runs an agentic loop to completion and returns total tokens spent.""" total_spend = 0 while True: response = client.beta.messages.create( model="claude-opus-4-7", max_tokens=128000, messages=messages, tools=tools, betas=["task-budgets-2026-03-13"], ) # Count what Claude generated this turn (output covers text + thinking + tool calls). # Tool-result tokens also count against the budget; add the token count of the # tool_result blocks you append below if you want client-side tracking to match # the server-side countdown. total_spend += response.usage.output_tokens if response.stop_reason == "end_turn": return total_spend # Append the assistant turn and your tool results, then continue the loop. messages += [ {"role": "assistant", "content": response.content}, {"role": "user", "content": run_tools(response.content)}, ] ``` ```typescript TypeScript async function runTaskAndCountTokens( messages: Anthropic.Beta.BetaMessageParam[] ): Promise { let totalSpend = 0; while (true) { const response = await client.beta.messages.create({ model: "claude-opus-4-7", max_tokens: 128000, messages, tools, betas: ["task-budgets-2026-03-13"] }); // Count what Claude generated this turn (output covers text + tool calls; // add cache creation and thinking via the same usage object if you opt in). totalSpend += response.usage.output_tokens; if (response.stop_reason === "end_turn") { return totalSpend; } // Append the assistant turn and your tool results, then continue the loop. messages = [ ...messages, { role: "assistant", content: response.content }, { role: "user", content: runTools(response.content) } ]; } } ``` Run this across a representative set of tasks and record the distribution. Start with the p99 of your per-task token spend to understand how providing the model with a task budget may modify the model's behavior, then test up or down as needed. The minimum accepted `task_budget.total` is **20,000 tokens**; values below the minimum return a 400 error. ## Interaction with other parameters - **`max_tokens`:** Orthogonal to task budgets. `max_tokens` is a hard per-request cap on generated tokens, while `task_budget` is an advisory cap across the full agentic loop (potentially spanning many requests). At `xhigh` or `max` effort, set `max_tokens` to at least 64k to give Claude room to think and act on each request. - **[Effort](/docs/en/build-with-claude/effort):** Effort controls how deeply Claude reasons per step. Task budgets control how much total work Claude does across an agentic loop. The two are complementary: effort tunes depth, task budgets tune breadth. - **[Adaptive thinking](/docs/en/build-with-claude/adaptive-thinking):** Task budgets include thinking tokens in the count, so adaptive thinking naturally scales down as the budget depletes. - **[Prompt caching](/docs/en/build-with-claude/prompt-caching):** The budget-countdown marker is injected server-side per turn, so it does not match across requests. If your client decrements `task_budget.remaining` on each follow-up request, the changed value invalidates any cache prefix that contains it. To preserve caching, set the budget once on the initial request and let the model self-regulate against the server-side countdown rather than mutating the budget client-side. ## Feature support | Model | Support | |-------|---------| | Claude Opus 4.7 | Public beta (set `task-budgets-2026-03-13` header) | | Claude Opus 4.6 | Not supported | | Claude Sonnet 4.6 | Not supported | | Claude Haiku 4.5 | Not supported | Task budgets are not supported on [Claude Code](https://docs.claude.com/en/docs/claude-code) or Cowork surfaces at launch. Use task budgets directly via the Messages API on Claude Opus 4.7. ### Tools --- # Tool use with Claude URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview # Tool use with Claude Connect Claude to external tools and APIs. Learn where tools execute and how the agentic loop works. --- Tool use lets Claude call functions you define or that Anthropic provides. Claude decides when to call a tool based on the user's request and the tool's description, then returns a structured call that your application executes (client tools) or that Anthropic executes (server tools). Here's the simplest example using a server tool, where Anthropic handles execution: ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-4-7", "max_tokens": 1024, "tools": [{"type": "web_search_20260209", "name": "web_search"}], "messages": [{"role": "user", "content": "What'\''s the latest on the Mars rover?"}] }' ``` ```bash CLI ant messages create --transform content --format yaml \ --model claude-opus-4-7 \ --max-tokens 1024 \ --tool '{type: web_search_20260209, name: web_search}' \ --message '{role: user, content: "What is the latest on the Mars rover?"}' ``` ```python Python import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-4-7", max_tokens=1024, tools=[{"type": "web_search_20260209", "name": "web_search"}], messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}], ) print(response.content) ``` ```typescript TypeScript import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const response = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 1024, tools: [{ type: "web_search_20260209", name: "web_search" }], messages: [{ role: "user", content: "What's the latest on the Mars rover?" }] }); console.log(response.content); ``` --- ## How tool use works Tools differ primarily by where the code executes. **Client tools** (including user-defined tools and Anthropic-schema tools like bash and text_editor) run in your application: Claude responds with `stop_reason: "tool_use"` and one or more `tool_use` blocks, your code executes the operation, and you send back a `tool_result`. **Server tools** (web_search, code_execution, web_fetch, tool_search) run on Anthropic's infrastructure: you see the results directly without handling execution. For the full conceptual model including the agentic loop and when to choose each approach, see [How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works). For connecting to MCP servers, see the [MCP connector](/docs/en/agents-and-tools/mcp-connector). For building your own MCP client, see [modelcontextprotocol.io](https://modelcontextprotocol.io/docs/develop/build-client). **Guarantee schema conformance with strict tool use** Add `strict: true` to your tool definitions to ensure Claude's tool calls always match your schema exactly. See [Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use). Tool access is one of the highest-leverage primitives you can give an agent. On benchmarks like [LAB-Bench FigQA](https://lab-bench.org/) (scientific figure interpretation) and [SWE-bench](https://www.swebench.com/) (real-world software engineering), adding even basic tools produces outsized capability gains, often surpassing human expert baselines. --- ## Tool use examples For a complete hands-on walkthrough, see the [tutorial](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent). For reference examples of individual concepts, see [Define tools](/docs/en/agents-and-tools/tool-use/define-tools) and [Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls).

If the user's prompt doesn't include enough information to fill all the required parameters for a tool, Claude Opus is much more likely to recognize that a parameter is missing and ask for it. Claude Sonnet may ask, especially when prompted to think before outputting a tool request. But it may also do its best to infer a reasonable value. For example, given a `get_weather` tool that requires a `location` parameter, if you ask Claude "What's the weather?" without specifying a location, Claude (particularly Claude Sonnet) may make a guess about tool inputs: ```json JSON { "type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "get_weather", "input": { "location": "New York, NY", "unit": "fahrenheit" } } ``` This behavior is not guaranteed, especially for more ambiguous prompts and for less intelligent models. If Claude Opus doesn't have enough context to fill in the required parameters, it is far more likely to respond with a clarifying question instead of making a tool call.

--- ## Pricing Tool use requests are priced based on: 1. The total number of input tokens sent to the model (including in the `tools` parameter) 2. The number of output tokens generated 3. For server-side tools, additional usage-based pricing (e.g., web search charges per search performed) Client-side tools are priced the same as any other Claude API request, while server-side tools may incur additional charges based on their specific usage. The additional tokens from tool use come from: - The `tools` parameter in API requests (tool names, descriptions, and schemas) - `tool_use` content blocks in API requests and responses - `tool_result` content blocks in API requests When you use `tools`, we also automatically include a special system prompt for the model which enables tool use. The number of tool use tokens required for each model are listed below (excluding the additional tokens listed above). Note that the table assumes at least 1 tool is provided. If no `tools` are provided, then a tool choice of `none` uses 0 additional system prompt tokens. | Model | Tool choice | Tool use system prompt token count | |--------------------------|------------------------------------------------------|---------------------------------------------| | Claude Opus 4.7 | `auto`, `none`

`any`, `tool` | 346 tokens

313 tokens | | Claude Opus 4.6 | `auto`, `none`

`any`, `tool` | 346 tokens

313 tokens | | Claude Opus 4.5 | `auto`, `none`

`any`, `tool` | 346 tokens

313 tokens | | Claude Opus 4.1 | `auto`, `none`

`any`, `tool` | 346 tokens

313 tokens | | Claude Opus 4 ([deprecated](/docs/en/about-claude/model-deprecations)) | `auto`, `none`

`any`, `tool` | 346 tokens

313 tokens | | Claude Sonnet 4.6 | `auto`, `none`

`any`, `tool` | 346 tokens

313 tokens | | Claude Sonnet 4.5 | `auto`, `none`

`any`, `tool` | 346 tokens

313 tokens | | Claude Sonnet 4 ([deprecated](/docs/en/about-claude/model-deprecations)) | `auto`, `none`

`any`, `tool` | 346 tokens

313 tokens | | Claude Haiku 4.5 | `auto`, `none`

`any`, `tool` | 346 tokens

313 tokens | | Claude Haiku 3.5 ([retired, except on Bedrock and Vertex AI](/docs/en/about-claude/model-deprecations)) | `auto`, `none`

`any`, `tool` | 264 tokens

340 tokens | These token counts are added to your normal input and output tokens to calculate the total cost of a request. Refer to the [models overview table](/docs/en/about-claude/models/overview#latest-models-comparison) for current per-model prices. When you send a tool use prompt, just like any other API request, the response will output both input and output token counts as part of the reported `usage` metrics. --- ## Next steps ### Choose your path Where tools run, how the loop works, and when to use tools. The tutorial: from a single tool call to production. Directory of Anthropic-provided tools and properties. --- # Advisor tool URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool # Advisor tool Pair a faster executor model with a higher-intelligence advisor model that provides strategic guidance mid-generation. --- The advisor tool lets a faster, lower-cost **executor model** consult a higher-intelligence **advisor model** mid-generation for strategic guidance. The advisor reads the full conversation, produces a plan or course correction (typically 400 to 700 text tokens, 1,400 to 1,800 tokens total including thinking), and the executor continues with the task. This pattern fits long-horizon agentic workloads (coding agents, computer use, multi-step research pipelines) where most turns are mechanical but having an excellent plan is crucial. You get close to advisor-solo quality while the bulk of token generation happens at executor-model rates. The advisor tool is in beta. Include the beta header `advisor-tool-2026-03-01` in your requests. To request access or share feedback, contact your Anthropic account team. This feature is eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned. ## When to use it Early benchmarks show meaningful gains for these configurations: - **You currently use Sonnet on complex tasks:** Add Opus as the advisor for a quality lift at similar or lower total cost. - **You currently use Haiku and want a step up in intelligence:** Add Opus as the advisor. Expect higher cost than Haiku alone, but lower than switching the executor to a larger model. Results are task-dependent. Evaluate on your own workload. The advisor is a weaker fit for single-turn Q&A (nothing to plan), pure pass-through model pickers where your users already choose their own cost and quality tradeoff, or workloads where every turn genuinely requires the advisor model's full capability. ## Model compatibility The executor model (the top-level `model` field) and the advisor model (the `model` field inside the tool definition) must form a valid pair. The advisor must be at least as capable as the executor. | Executor models | Advisor models | | ---------------------------------------------- | ----------------------------------- | | Claude Haiku 4.5 (`claude-haiku-4-5-20251001`) | Claude Opus 4.7 (`claude-opus-4-7`) | | Claude Sonnet 4.6 (`claude-sonnet-4-6`) | Claude Opus 4.7 (`claude-opus-4-7`) | | Claude Opus 4.6 (`claude-opus-4-6`) | Claude Opus 4.7 (`claude-opus-4-7`) | | Claude Opus 4.7 (`claude-opus-4-7`) | Claude Opus 4.7 (`claude-opus-4-7`) | If you request an invalid pair, the API returns a `400 invalid_request_error` naming the unsupported combination. ## Platform availability The advisor tool is available in beta on the Claude API and on [Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws). It is not currently available on Amazon Bedrock, Vertex AI, or Microsoft Foundry. ## Quick start ```bash cURL curl https://api.anthropic.com/v1/messages \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "anthropic-beta: advisor-tool-2026-03-01" \ --header "content-type: application/json" \ --data '{ "model": "claude-sonnet-4-6", "max_tokens": 4096, "tools": [ { "type": "advisor_20260301", "name": "advisor", "model": "claude-opus-4-7" } ], "messages": [{ "role": "user", "content": "Build a concurrent worker pool in Go with graceful shutdown." }] }' ``` ```bash CLI ant beta:messages create --beta advisor-tool-2026-03-01 <<'YAML' model: claude-sonnet-4-6 max_tokens: 4096 tools: - type: advisor_20260301 name: advisor model: claude-opus-4-7 messages: - role: user content: Build a concurrent worker pool in Go with graceful shutdown. YAML ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() response = client.beta.messages.create( model="claude-sonnet-4-6", max_tokens=4096, betas=["advisor-tool-2026-03-01"], tools=[ { "type": "advisor_20260301", "name": "advisor", "model": "claude-opus-4-7", } ], messages=[ { "role": "user", "content": "Build a concurrent worker pool in Go with graceful shutdown.", } ], ) print(response) ``` ```typescript TypeScript hidelines={1..5,-3..-1} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); async function main() { const response = await client.beta.messages.create({ model: "claude-sonnet-4-6", max_tokens: 4096, betas: ["advisor-tool-2026-03-01"], tools: [ { type: "advisor_20260301", name: "advisor", model: "claude-opus-4-7" } ], messages: [ { role: "user", content: "Build a concurrent worker pool in Go with graceful shutdown." } ] }); console.log(response); } main().catch(console.error); ``` ```csharp C# nocheck hidelines={1} using Anthropic; using Anthropic.Models.Beta.Messages; using Messages = Anthropic.Models.Messages; var client = new AnthropicClient(); var parameters = new MessageCreateParams { Model = Messages::Model.ClaudeSonnet4_6, MaxTokens = 4096, Tools = new BetaToolUnion[] { new BetaAdvisorTool20260301 { Model = Messages::Model.ClaudeOpus4_7 } }, Messages = [ new BetaMessageParam { Role = Role.User, Content = "Build a concurrent worker pool in Go with graceful shutdown." } ], Betas = ["advisor-tool-2026-03-01"] }; var response = await client.Beta.Messages.Create(parameters); Console.WriteLine(response); ``` ```go Go nocheck hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeSonnet4_6, MaxTokens: 4096, Tools: []anthropic.BetaToolUnionParam{ {OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{ Model: anthropic.ModelClaudeOpus4_7, }}, }, Messages: []anthropic.BetaMessageParam{ anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Build a concurrent worker pool in Go with graceful shutdown.")), }, Betas: []anthropic.AnthropicBeta{ anthropic.AnthropicBetaAdvisorTool2026_03_01, }, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```php PHP hidelines={1..4} beta->messages->create( maxTokens: 4096, messages: [ [ 'role' => 'user', 'content' => 'Build a concurrent worker pool in Go with graceful shutdown.', ], ], model: 'claude-sonnet-4-6', tools: [ [ 'type' => 'advisor_20260301', 'name' => 'advisor', 'model' => 'claude-opus-4-7', ], ], betas: ['advisor-tool-2026-03-01'], ); echo $response; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new response = client.beta.messages.create( model: "claude-sonnet-4-6", max_tokens: 4096, tools: [ { type: "advisor_20260301", name: "advisor", model: "claude-opus-4-7" } ], messages: [ { role: "user", content: "Build a concurrent worker pool in Go with graceful shutdown." } ], betas: ["advisor-tool-2026-03-01"] ) puts response ``` ## How it works When you add the advisor tool to your `tools` array, the executor model decides when to call it, just like any other tool. When the executor invokes the advisor: 1. The executor emits a `server_tool_use` block with `name: "advisor"` and an empty `input`. The executor signals timing; the server supplies context. 2. Anthropic runs a separate inference pass on the advisor model server-side, passing the executor's full transcript. The advisor sees the system prompt, all tool definitions, all prior turns, and all prior tool results. 3. The advisor's response returns to the executor as an `advisor_tool_result` block. 4. The executor continues generating, informed by the advice. All of this happens inside a single `/v1/messages` request. No extra round trips on your side. The advisor itself runs without tools and without context management. Its thinking blocks are dropped before the result returns; only the advice text reaches the executor. ## Tool parameters | Parameter | Type | Default | Description | | ----------------------- | -------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | _required_ | Must be `"advisor_20260301"`. | | `name` | string | _required_ | Must be `"advisor"`. | | `model` | string | _required_ | The advisor model ID, such as `"claude-opus-4-7"`. Billed at this model's rates for the sub-inference. | | `max_uses` | integer | unlimited | Maximum number of advisor calls allowed in a single request. Once the executor reaches this cap, further advisor calls return an `advisor_tool_result_error` with `error_code: "max_uses_exceeded"` and the executor continues without further advice. This is a per-request cap, not a per-conversation cap; see [Cost control](#cost-control) for conversation-level limits. | | `caching` | object \| null | `null` (off) | Enables prompt caching for the advisor's own transcript across calls within a conversation. See [Advisor prompt caching](#advisor-prompt-caching). | The `caching` object has the shape `{"type": "ephemeral", "ttl": "5m" | "1h"}`. Unlike `cache_control` on content blocks, this is not a breakpoint marker; it is an on/off switch. The server decides where cache boundaries go. ## Response structure ### Successful advisor call When the advisor is invoked, a `server_tool_use` block is followed by an `advisor_tool_result` block in the assistant's content: ```json { "role": "assistant", "content": [ { "type": "text", "text": "Let me consult the advisor on this." }, { "type": "server_tool_use", "id": "srvtoolu_abc123", "name": "advisor", "input": {} }, { "type": "advisor_tool_result", "tool_use_id": "srvtoolu_abc123", "content": { "type": "advisor_result", "text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..." } }, { "type": "text", "text": "Here's the implementation. I'm using a channel-based coordination pattern to avoid writer starvation..." } ] } ``` The `server_tool_use.input` is always empty. The server constructs the advisor's view from the full transcript automatically; nothing the executor puts in `input` reaches the advisor. ### Result variants The `advisor_tool_result.content` field is a discriminated union. For successful calls, the variant depends on the advisor model: | Variant | Fields | Returned when | | ------------------------- | ------------------- | ------------------------------------------------------------------- | | `advisor_result` | `text` | The advisor model returns plaintext (for example, Claude Opus 4.7). | | `advisor_redacted_result` | `encrypted_content` | The advisor model returns encrypted output. | With `advisor_result`, the `text` field contains human-readable advice. With `advisor_redacted_result`, the `encrypted_content` field contains an opaque blob that you cannot read; on the next turn, the server decrypts it and renders the plaintext into the executor's prompt. In both cases, round-trip the content verbatim on subsequent turns. If you switch advisor models mid-conversation, branch on `content.type` to handle both shapes. ### Error results If the advisor call fails, the result carries an error: ```json { "type": "advisor_tool_result", "tool_use_id": "srvtoolu_abc123", "content": { "type": "advisor_tool_result_error", "error_code": "overloaded" } } ``` The executor sees the error and continues without further advice. The request itself does not fail. | `error_code` | Meaning | | ------------------------- | ----------------------------------------------------------------------------------------------------------- | | `max_uses_exceeded` | The request reached the `max_uses` cap set on the tool definition. Further advisor calls in the same request return this error. | | `too_many_requests` | The advisor sub-inference was rate-limited. | | `overloaded` | The advisor sub-inference hit capacity limits. | | `prompt_too_long` | The transcript exceeded the advisor model's context window. | | `execution_time_exceeded` | The advisor sub-inference timed out. | | `unavailable` | Any other advisor failure. | Advisor rate limits draw from the same per-model bucket as direct calls to the advisor model. A rate limit on the advisor appears as `too_many_requests` inside the tool result; a rate limit on the executor fails the whole request with HTTP 429. ## Multi-turn conversations Pass the full assistant content, including `advisor_tool_result` blocks, back to the API on subsequent turns: ```python import anthropic client = anthropic.Anthropic() tools = [ { "type": "advisor_20260301", "name": "advisor", "model": "claude-opus-4-7", } ] messages = [ { "role": "user", "content": "Build a concurrent worker pool in Go with graceful shutdown.", } ] response = client.beta.messages.create( model="claude-sonnet-4-6", max_tokens=4096, betas=["advisor-tool-2026-03-01"], tools=tools, messages=messages, ) # Append the full response content, including any advisor_tool_result blocks messages.append({"role": "assistant", "content": response.content}) # Continue the conversation messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."}) response = client.beta.messages.create( model="claude-sonnet-4-6", max_tokens=4096, betas=["advisor-tool-2026-03-01"], tools=tools, messages=messages, ) ``` If you omit the advisor tool from `tools` on a follow-up turn while the message history still contains `advisor_tool_result` blocks, the API returns a `400 invalid_request_error`. The advisor tool has no built-in conversation-level cap. To limit advisor calls across a conversation, count them client-side. When you reach your ceiling, remove the advisor tool from your `tools` array **and** strip all `advisor_tool_result` blocks from your message history to avoid a `400 invalid_request_error`. ## Streaming The advisor sub-inference does not stream. The executor's stream pauses while the advisor runs, then the full result arrives in a single event. The `server_tool_use` block with `name: "advisor"` signals that an advisor call is starting. The pause begins when that block closes (`content_block_stop`). During the pause, the stream is quiet except for standard SSE `ping` keepalives emitted roughly every 30 seconds; short advisor calls may show no pings. When the advisor finishes, the `advisor_tool_result` arrives fully formed in a single `content_block_start` event (no deltas). Executor output then resumes streaming. A `message_delta` event follows with the updated `usage.iterations` array reflecting the advisor's token counts. ## Usage and billing Advisor calls run as a separate sub-inference billed at the advisor model's rates. Usage is reported in the `usage.iterations[]` array: ```json { "usage": { "input_tokens": 412, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0, "output_tokens": 531, "iterations": [ { "type": "message", "input_tokens": 412, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0, "output_tokens": 89 }, { "type": "advisor_message", "model": "claude-opus-4-7", "input_tokens": 823, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0, "output_tokens": 1612 }, { "type": "message", "input_tokens": 1348, "cache_read_input_tokens": 412, "cache_creation_input_tokens": 0, "output_tokens": 442 } ] } } ``` Top-level `usage` fields reflect executor tokens only. Advisor tokens are not rolled into the top-level totals because they are billed at a different rate. Iterations with `type: "advisor_message"` are billed at the advisor model's rates; iterations with `type: "message"` are billed at the executor model's rates. The aggregation rules differ by field. Top-level `output_tokens` is the sum of all executor iterations. Top-level `input_tokens` and `cache_read_input_tokens` reflect the first executor iteration only; subsequent executor iterations' inputs are not re-summed because they include prior output tokens. Use `usage.iterations` for a full per-iteration breakdown when building cost-tracking logic. Advisor output is typically 400 to 700 text tokens, or 1,400 to 1,800 tokens total including thinking. The cost savings come from the advisor not generating your full final output; the executor does that at its lower rate. The top-level `max_tokens` applies to executor output only. It does not bound advisor sub-inference tokens. The advisor's tokens also do not draw from any task budget applied to the executor. ## Advisor prompt caching There are two independent caching layers. ### Executor-side caching The `advisor_tool_result` block is cacheable like any other content block. A `cache_control` breakpoint placed after it on a subsequent turn will hit. The executor's prompt always contains the plaintext advice regardless of whether your client received `text` or `encrypted_content`, so caching behavior is identical for both result variants. ### Advisor-side caching Set `caching` on the tool definition to enable prompt caching for the advisor's own transcript across calls within the same conversation: ```python tools = [ { "type": "advisor_20260301", "name": "advisor", "model": "claude-opus-4-7", "caching": {"type": "ephemeral", "ttl": "5m"}, } ] ``` The advisor's prompt on the Nth call is the (N-1)th call's prompt with one more segment appended, so the prefix is stable across calls. With `caching` enabled, each advisor call writes a cache entry; the next call reads up to that point and pays only for the delta. You'll see `cache_read_input_tokens` become nonzero on the second and later `advisor_message` iterations. **When to enable it:** The cache write costs more than the reads save when the advisor is called two or fewer times per conversation. Caching breaks even at roughly three advisor calls and improves from there. Enable it for long agent loops; keep it off for short tasks. **Keep it consistent:** Set `caching` once and leave it for the whole conversation. Toggling it off and on mid-conversation causes cache misses. [`clear_thinking`](/docs/en/build-with-claude/context-editing) with a `keep` value other than `"all"` shifts the advisor's quoted transcript each turn, causing advisor-side cache misses. This is a cost degradation only; advice quality is unaffected. When extended thinking is enabled without explicit `clear_thinking` configuration, the API defaults to `keep: {type: "thinking_turns", value: 1}`, which triggers this behavior (the default on earlier Opus/Sonnet models and all Haiku models; on Opus 4.5+ and Sonnet 4.6+ the default is to keep all turns). Set `keep: "all"` to preserve advisor cache stability. ## Combining with other tools The advisor tool composes with other server-side and client-side tools. Add them all to the same `tools` array: ```python tools = [ { "type": "web_search_20250305", "name": "web_search", "max_uses": 5, }, { "type": "advisor_20260301", "name": "advisor", "model": "claude-opus-4-7", }, { "name": "run_bash", "description": "Run a bash command", "input_schema": { "type": "object", "properties": {"command": {"type": "string"}}, }, }, ] ``` The executor can search the web, call the advisor, and use your custom tools in the same turn. The advisor's plan can inform which tools the executor reaches for next. | Feature | Interaction | | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Batch processing](/docs/en/build-with-claude/batch-processing) | Supported. `usage.iterations` is reported per item. | | [Token counting](/docs/en/build-with-claude/token-counting) | Returns the executor's first-iteration input tokens only. For a rough advisor estimate, call `count_tokens` with `model` set to the advisor model and the same messages. | | [Context editing](/docs/en/build-with-claude/context-editing) | `clear_tool_uses` is not fully compatible with advisor tool blocks. With `clear_thinking`, see the earlier caching warning. | | `pause_turn` | A dangling advisor call ends the response with `stop_reason: "pause_turn"` and the `server_tool_use` block as the last content block. The advisor executes on resumption. See [Server tools](/docs/en/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn). | ## Best practices ### Prompting for coding and agent tasks The advisor tool ships with a built-in description that nudges the executor to call it near the start of complex tasks and when it hits difficulty. For research tasks, no additional prompting is typically needed. On coding and agent tasks, the advisor produces higher intelligence at similar cost when it reduces total tool calls and conversation length. Two timings drive this improvement: 1. An early first advisor call, after a few exploratory reads are in the transcript. 2. For difficult tasks, a final advisor call after file writes and test outputs are in the transcript. If your agent exposes other planner-like tools (for example, a todo list tool), prompt the model to call the advisor before those tools so the advisor's plan funnels into them. The suggested system prompt below reinforces the early-call pattern; add your own funnel-in sentence pointing at whichever planner tools your agent exposes. #### Suggested system prompt for coding tasks For coding tasks where you want consistent advisor timing and around two to three calls per task, prepend the following blocks to your executor system prompt before any other sentences that mention the advisor. On internal coding evaluations this pattern produced the highest intelligence at near-Sonnet cost. Timing guidance: ```text You have access to an `advisor` tool backed by a stronger reviewer model. It takes NO parameters — when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen. Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are. Also call advisor: - When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't. - When stuck — errors recurring, approach not converging, results that don't fit. - When considering a change of approach. On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling — the advisor adds most of its value on the first call, before the approach crystallizes. ``` How the executor should treat the advice (place directly after the timing block): ```text Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong — it's evidence your test doesn't check what the advice is checking. If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call — "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch. ``` #### Trimming advisor output length Advisor output is the advisor's largest cost driver. To reduce that cost, prepend a single conciseness instruction to the system prompt before any other sentence that mentions the advisor. In internal testing, the following line cut total advisor output tokens by roughly 35 to 45 percent without changing call frequency: ```text The advisor should respond in under 100 words and use enumerated steps, not explanations. ``` Pair this with the timing block above for the strongest cost-versus-quality tradeoff. ### Pairing with effort settings For coding tasks, pairing a Sonnet executor at medium [effort](/docs/en/build-with-claude/effort) with an Opus advisor achieves intelligence comparable to Sonnet at default effort, at lower cost. For maximum intelligence, keep the executor at default effort. ### Cost control - For conversation-level budgets, count advisor calls client-side. When you reach your cap, remove the advisor tool from `tools` **and** strip all `advisor_tool_result` blocks from your message history to avoid a `400 invalid_request_error`. - Enable `caching` only for conversations where you expect three or more advisor calls. ## Limitations - **Advisor output does not stream.** Expect a pause in the stream while the sub-inference runs. - **No built-in conversation-level cap on advisor calls.** Track and cap them client-side. - **`max_tokens` applies to executor output only.** It does not bound advisor tokens. - **[Priority Tier](/docs/en/api/service-tiers)** is honored for each model. Priority Tier on the executor model does not extend to the advisor; you need Priority Tier on the advisor model specifically. --- # Bash tool URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool # Bash tool --- This feature is eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned. The bash tool enables Claude to execute shell commands in a persistent bash session, allowing system operations, script execution, and command-line automation. Shell access is a foundational agent capability. On [Terminal-Bench 2.0](https://github.com/terminal-bench/terminal-bench), a benchmark that evaluates real-world terminal tasks using shell-only validation, Claude shows strong performance gains with access to a persistent bash session. ## Overview The bash tool provides Claude with: - Persistent bash session that maintains state - Ability to run any shell command - Access to environment variables and working directory - Command chaining and scripting capabilities For model support, see the [Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference). ## Use cases - **Development workflows:** Run build commands, tests, and development tools - **System automation:** Execute scripts, manage files, automate tasks - **Data processing:** Process files, run analysis scripts, manage datasets - **Environment setup:** Install packages, configure environments ## Quick start ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "content-type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-opus-4-7", "max_tokens": 1024, "tools": [ { "type": "bash_20250124", "name": "bash" } ], "messages": [ { "role": "user", "content": "List all Python files in the current directory." } ] }' ``` ```bash CLI ant messages create \ --model claude-opus-4-7 \ --max-tokens 1024 \ --tool '{type: bash_20250124, name: bash}' \ --message '{role: user, content: List all Python files in the current directory.}' ``` ```python Python import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-4-7", max_tokens=1024, tools=[{"type": "bash_20250124", "name": "bash"}], messages=[ {"role": "user", "content": "List all Python files in the current directory."} ], ) print(response) ``` ## How it works The bash tool maintains a persistent session: 1. Claude determines what command to run 2. You execute the command in a bash shell 3. Return the output (stdout and stderr) to Claude 4. Session state persists between commands (environment variables, working directory) ## Parameters | Parameter | Required | Description | |-----------|----------|-------------| | `command` | Yes* | The bash command to run | | `restart` | No | Set to `true` to restart the bash session | *Required unless using `restart`

Run a command: ```json { "command": "ls -la *.py" } ``` Restart the session: ```json { "restart": true } ```

## Example: Multi-step automation Claude can chain commands to complete complex tasks: ```text User request: "Install the requests library and create a simple Python script that fetches a joke from an API, then run it." Claude's tool uses: 1. Install package {"command": "pip install requests"} 2. Create script {"command": "cat > fetch_joke.py << 'EOF'\nimport requests\nresponse = requests.get('https://official-joke-api.appspot.com/random_joke')\njoke = response.json()\nprint(f\"Setup: {joke['setup']}\")\nprint(f\"Punchline: {joke['punchline']}\")\nEOF"} 3. Run script {"command": "python fetch_joke.py"} ``` The session maintains state between commands, so files created in step 2 are available in step 3. ## Implement the bash tool The bash tool is implemented as a schema-less tool. When using this tool, you don't need to provide an input schema as with other tools; the schema is built into Claude's model and can't be modified. Create a persistent bash session that Claude can interact with: ```python hidelines={-2..-1} import subprocess import threading import queue class BashSession: def __init__(self): self.process = subprocess.Popen( ["/bin/bash"], stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, bufsize=0, ) self.output_queue = queue.Queue() self.error_queue = queue.Queue() self._start_readers() def _start_readers(self): ... ``` Create a function to execute commands and capture output: ```python hidelines={1..2,-1} class BashSession: def _read_output(self, timeout): ... def execute_command(self, command): # Send command to bash self.process.stdin.write(command + "\n") self.process.stdin.flush() # Capture output with timeout output = self._read_output(timeout=10) return output process = None ``` Extract and execute commands from Claude's responses: ```python hidelines={1..6} from types import SimpleNamespace as _SN response = _SN( content=[_SN(type="tool_use", name="bash", input={"command": "ls"}, id="toolu_01")] ) bash_session = _SN(restart=lambda: None, execute_command=lambda c: "output") for content in response.content: if content.type == "tool_use" and content.name == "bash": if content.input.get("restart"): bash_session.restart() result = "Bash session restarted" else: command = content.input.get("command") result = bash_session.execute_command(command) # Return result to Claude tool_result = { "type": "tool_result", "tool_use_id": content.id, "content": result, } ``` Add validation and restrictions. Use an allowlist rather than a blocklist, since blocklists are easy to bypass. Reject shell operators so chained commands can't slip past the allowlist: ```python import shlex ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"} SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"} def validate_command(command): # Allow only commands from an explicit allowlist try: tokens = shlex.split(command) except ValueError: return False, "Could not parse command" if not tokens: return False, "Empty command" executable = tokens[0] if executable not in ALLOWED_COMMANDS: return False, f"Command '{executable}' is not in the allowlist" # Reject shell operators that would chain additional commands for token in tokens[1:]: if token in SHELL_OPERATORS or token.startswith(("$", "`")): return False, f"Shell operator '{token}' is not allowed" return True, None ``` This check is a first line of defense. For stronger isolation, run validated commands with `shell=False` and pass `shlex.split(command)` as the argument list, so the shell never interprets the string. ### Handle errors When implementing the bash tool, handle various error scenarios:

If a command takes too long to execute: ```json { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "Error: Command timed out after 30 seconds", "is_error": true } ] } ```

If a command doesn't exist: ```json { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "bash: nonexistentcommand: command not found", "is_error": true } ] } ```

If there are permission issues: ```json { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "bash: /root/sensitive-file: Permission denied", "is_error": true } ] } ```

### Follow implementation best practices

Implement timeouts to prevent hanging commands: ```python hidelines={1..3} import subprocess def execute_with_timeout(command, timeout=30): try: result = subprocess.run( command, shell=True, capture_output=True, text=True, timeout=timeout ) return result.stdout + result.stderr except subprocess.TimeoutExpired: return f"Command timed out after {timeout} seconds" ```

Keep the bash session persistent to maintain environment variables and working directory: ```python # Commands run in the same session maintain state commands = [ "cd /tmp", "echo 'Hello' > test.txt", "cat test.txt", # This works because we're still in /tmp ] ```

Truncate very large outputs to prevent token limit issues: ```python def truncate_output(output, max_lines=100): lines = output.split("\n") if len(lines) > max_lines: truncated = "\n".join(lines[:max_lines]) return f"{truncated}\n\n... Output truncated ({len(lines)} total lines) ..." return output ```

Keep an audit trail of executed commands: ```python import logging def log_command(command, output, user_id): logging.info(f"User {user_id} executed: {command}") logging.info(f"Output: {output[:200]}...") # Log first 200 chars ```

Remove sensitive information from command outputs: ```python def sanitize_output(output): # Remove potential secrets or credentials import re # Example: Remove AWS credentials output = re.sub(r"aws_access_key_id\s*=\s*\S+", "aws_access_key_id=***", output) output = re.sub( r"aws_secret_access_key\s*=\s*\S+", "aws_secret_access_key=***", output ) return output ```

## Security The bash tool provides direct system access. Implement these essential safety measures: - Running in isolated environments (Docker/VM) - Implementing command filtering and allowlists - Setting resource limits (CPU, memory, disk) - Logging all executed commands ### Key recommendations - Use `ulimit` to set resource constraints - Filter dangerous commands (`sudo`, `rm -rf`, etc.) - Run with minimal user permissions - Monitor and log all command execution ## Pricing The bash tool adds **245 input tokens** to your API calls. Additional tokens are consumed by: - Command outputs (stdout/stderr) - Error messages - Large file contents See [tool use pricing](/docs/en/agents-and-tools/tool-use/overview#pricing) for complete pricing details. ## Common patterns ### Development workflows - Running tests: `pytest && coverage report` - Building projects: `npm install && npm run build` - Git operations: `git status && git add . && git commit -m "message"` #### Git-based checkpointing Git serves as a structured recovery mechanism in long-running agent workflows, not just a way to save changes: - **Capture a baseline:** Before any agent work begins, commit the current state. This is the known-good starting point. - **Commit per feature:** Each completed feature gets its own commit. These serve as rollback points if something goes wrong later. - **Reconstruct state at session start:** Read `git log` alongside a progress file to understand what has already been done and what comes next. - **Revert on failure:** If work goes sideways, `git checkout` reverts to the last good commit instead of trying to debug a broken state. ### File operations - Processing data: `wc -l *.csv && ls -lh *.csv` - Searching files: `find . -name "*.py" | xargs grep "pattern"` - Creating backups: `tar -czf backup.tar.gz ./data` ### System tasks - Checking resources: `df -h && free -m` - Process management: `ps aux | grep python` - Environment setup: `export PATH=$PATH:/new/path && echo $PATH` ## Limitations - **No interactive commands:** Cannot handle `vim`, `less`, or password prompts - **No GUI applications:** Command-line only - **Session scope:** Bash session state is client-side. The API is stateless. Your application is responsible for maintaining the shell session between turns. - **Output limits:** Large outputs may be truncated - **No streaming:** Results returned after completion ## Combining with other tools The bash tool is most powerful when combined with the [text editor](/docs/en/agents-and-tools/tool-use/text-editor-tool) and other tools. If you're also using the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool), Claude has access to two separate execution environments: your local bash session and Anthropic's sandboxed container. State is not shared between them. See [Using code execution with other execution tools](/docs/en/agents-and-tools/tool-use/code-execution-tool#using-code-execution-with-other-execution-tools) for guidance on prompting Claude to distinguish between environments. ## Next steps Learn about tool use with Claude View and edit text files with Claude --- # Code execution tool URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool # Code execution tool Run Python and bash code in a sandboxed container to analyze data, generate files, and iterate on solutions. --- Claude can analyze data, create visualizations, perform complex calculations, run system commands, create and edit files, and process uploaded files directly within the API conversation. The code execution tool allows Claude to run Bash commands and manipulate files, including writing code, in a secure, sandboxed environment. **Code execution is free when used with web search or web fetch.** When `web_search_20260209` or `web_fetch_20260209` is included in your request, there are no additional charges for code execution tool calls beyond the standard input and output token costs. Standard code execution charges apply when these tools are not included. Code execution is a core primitive for building high-performance agents. It enables dynamic filtering in web search and web fetch tools, allowing Claude to process results before they reach the context window, improving accuracy while reducing token consumption. Reach out through the [feedback form](https://forms.gle/LTAU6Xn2puCJMi1n6) to share your feedback on this feature. This feature is **not** eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). Data is retained according to the feature's standard retention policy. ## Model compatibility The code execution tool is available on the following models: | Model | Tool versions | |-------|--------------| | Claude Opus 4.7 (`claude-opus-4-7`) | `code_execution_20250825`, `code_execution_20260120` | | Claude Opus 4.6 (`claude-opus-4-6`) | `code_execution_20250825`, `code_execution_20260120` | | Claude Sonnet 4.6 (`claude-sonnet-4-6`) | `code_execution_20250825`, `code_execution_20260120` | | Claude Opus 4.5 (`claude-opus-4-5-20251101`) | `code_execution_20250825`, `code_execution_20260120` | | Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`) | `code_execution_20250825`, `code_execution_20260120` | | Claude Haiku 4.5 (`claude-haiku-4-5-20251001`) | `code_execution_20250825` | | Claude Opus 4.1 (`claude-opus-4-1-20250805`) | `code_execution_20250825` | | Claude Opus 4 (`claude-opus-4-20250514`) ([deprecated](/docs/en/about-claude/model-deprecations)) | `code_execution_20250825` | | Claude Sonnet 4 (`claude-sonnet-4-20250514`) ([deprecated](/docs/en/about-claude/model-deprecations)) | `code_execution_20250825` | `code_execution_20250825` supports Bash commands and file operations and is available on every model listed above. `code_execution_20260120` adds REPL state persistence and [programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) from within the sandbox, and is available on Opus 4.5+ and Sonnet 4.5+ only. If you're still using the legacy `code_execution_20250522` (Python only), see [Upgrade to latest tool version](#upgrade-to-latest-tool-version) to migrate from it. Older tool versions are not guaranteed to be backwards-compatible with newer models. Always use the tool version that corresponds to your model version. ## Platform availability Code execution is available on: - **Claude API** (Anthropic) - **[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)** - **[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)** Code execution is not currently available on Amazon Bedrock or Vertex AI. For [Claude Mythos Preview](https://anthropic.com/glasswing), code execution is supported on the Claude API and Microsoft Foundry only. It is not available for Mythos Preview on Amazon Bedrock, Vertex AI, or Claude Platform on AWS. ## Quick start Here's a simple example that asks Claude to perform a calculation: ```bash cURL curl https://api.anthropic.com/v1/messages \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --data '{ "model": "claude-opus-4-7", "max_tokens": 4096, "messages": [ { "role": "user", "content": "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]" } ], "tools": [{ "type": "code_execution_20250825", "name": "code_execution" }] }' ``` ```bash CLI ant messages create \ --model claude-opus-4-7 \ --max-tokens 4096 \ --message '{role: user, content: "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"}' \ --tool '{type: code_execution_20250825, name: code_execution}' ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-4-7", max_tokens=4096, messages=[ { "role": "user", "content": "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]", } ], tools=[{"type": "code_execution_20250825", "name": "code_execution"}], ) print(response) ``` ```typescript TypeScript hidelines={1..5,-3..-1} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); async function main() { const response = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 4096, messages: [ { role: "user", content: "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]" } ], tools: [ { type: "code_execution_20250825", name: "code_execution" } ] }); console.log(response); } main().catch(console.error); ``` ```csharp C# hidelines={1..11,-2..} using System; using System.Threading.Tasks; using Anthropic; using Anthropic.Models.Messages; class Program { static async Task Main(string[] args) { AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 4096, Messages = [ new() { Role = Role.User, Content = "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]" } ], Tools = [new ToolUnion(new CodeExecutionTool20250825())] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); } } ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: []anthropic.BetaMessageParam{ anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]")), }, Tools: []anthropic.BetaToolUnionParam{ {OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}}, }, Betas: []anthropic.AnthropicBeta{"code-execution-2025-08-25"}, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```java Java hidelines={1..5,7..9,-2..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.Model; import com.anthropic.models.messages.CodeExecutionTool20250825; public class CodeExecution { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(4096L) .addUserMessage("Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]") .addTool(CodeExecutionTool20250825.builder().build()) .build(); Message response = client.messages().create(params); System.out.println(response); } } ``` ```php PHP hidelines={1..4} messages->create( maxTokens: 4096, messages: [ [ 'role' => 'user', 'content' => 'Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]' ] ], model: 'claude-opus-4-7', tools: [ [ 'type' => 'code_execution_20250825', 'name' => 'code_execution' ] ], ); echo $message; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-7", max_tokens: 4096, messages: [ { role: "user", content: "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]" } ], tools: [ { type: "code_execution_20250825", name: "code_execution" } ] ) puts message ``` ## How code execution works When you add the code execution tool to your API request: 1. Claude evaluates whether code execution would help answer your question 2. The tool automatically provides Claude with the following capabilities: - **Bash commands**: Execute shell commands for system operations and package management - **File operations**: Create, view, and edit files directly, including writing code 3. Claude can use any combination of these capabilities in a single request 4. All operations run in a secure sandbox environment 5. Claude provides results with any generated charts, calculations, or analysis ## Using code execution with other execution tools When you provide code execution alongside client-provided tools that also run code (such as a [bash tool](/docs/en/agents-and-tools/tool-use/bash-tool) or custom REPL), Claude is operating in a multi-computer environment. The code execution tool runs in Anthropic's sandboxed container, while your client-provided tools run in a separate environment that you control. Claude can sometimes confuse these environments, attempting to use the wrong tool or assuming state is shared between them. To avoid this, add instructions to your system prompt that clarify the distinction: ```text When multiple code execution environments are available, be aware that: - Variables, files, and state do NOT persist between different execution environments - Use the code_execution tool for general-purpose computation in Anthropic's sandboxed environment - Use client-provided execution tools (e.g., bash) when you need access to the user's local system, files, or data - If you need to pass results between environments, explicitly include outputs in subsequent tool calls rather than assuming shared state ``` This is especially important when combining code execution with [web search](/docs/en/agents-and-tools/tool-use/web-search-tool) or [web fetch](/docs/en/agents-and-tools/tool-use/web-fetch-tool), which enable code execution automatically. If your application already provides a client-side shell tool, the automatic code execution creates a second execution environment that Claude needs to distinguish between. ## How to use the tool ### Upload and analyze your own files To analyze your own data files (such as CSV, Excel, or images), upload them through the Files API and reference them in your request: Using the Files API with Code Execution requires the Files API beta header: `"anthropic-beta": "files-api-2025-04-14"` The Python environment can process various file types uploaded through the Files API, including: - CSV - Excel (.xlsx, .xls) - JSON - XML - Images (JPEG, PNG, GIF, WebP) - Text files (.txt, .md, .py, and others) #### Upload and analyze files 1. **Upload your file** using the [Files API](/docs/en/build-with-claude/files) 2. **Reference the file** in your message using a `container_upload` content block 3. **Include the code execution tool** in your API request ```bash cURL hidelines={1..2} cd "$(mktemp -d)" printf 'name,value\nfoo,1\nbar,2\n' > data.csv # First, upload a file curl https://api.anthropic.com/v1/files \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "anthropic-beta: files-api-2025-04-14" \ --form 'file=@"data.csv"' # Then use the file_id with code execution curl https://api.anthropic.com/v1/messages \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "anthropic-beta: files-api-2025-04-14" \ --header "content-type: application/json" \ --data '{ "model": "claude-opus-4-7", "max_tokens": 4096, "messages": [{ "role": "user", "content": [ {"type": "text", "text": "Analyze this CSV data"}, {"type": "container_upload", "file_id": "file_abc123"} ] }], "tools": [{ "type": "code_execution_20250825", "name": "code_execution" }] }' ``` ```bash CLI hidelines={1} printf 'name,value\nfoo,1\nbar,2\n' > data.csv # Upload a file FILE_ID=$(ant beta:files upload \ --file ./data.csv \ --transform id --raw-output) # Use the file_id with code execution ant beta:messages create \ --beta files-api-2025-04-14 <beta->files->upload( file: FileParam::fromResource(fopen('data.csv', 'r')), ); // Use the file_id with code execution $response = $client->beta->messages->create( maxTokens: 4096, messages: [ [ 'role' => 'user', 'content' => [ ['type' => 'text', 'text' => 'Analyze this CSV data'], ['type' => 'container_upload', 'file_id' => $fileObject->id], ], ], ], model: 'claude-opus-4-7', betas: ['files-api-2025-04-14'], tools: [ ['type' => 'code_execution_20250825', 'name' => 'code_execution'], ], ); echo $response; ``` ```ruby Ruby nocheck hidelines={1..2} require "anthropic" client = Anthropic::Client.new # Upload a file file_object = client.beta.files.upload( file: File.open("data.csv", "rb") ) # Use the file_id with code execution response = client.beta.messages.create( model: "claude-opus-4-7", betas: ["files-api-2025-04-14"], max_tokens: 4096, messages: [ { role: "user", content: [ { type: "text", text: "Analyze this CSV data" }, { type: "container_upload", file_id: file_object.id } ] } ], tools: [ { type: "code_execution_20250825", name: "code_execution" } ] ) puts response ``` ### Retrieve generated files When Claude creates files during code execution, you can retrieve these files using the Files API: ```bash CLI nocheck # Request code execution that creates files; extract file_ids from tool results TOOL_RESULT='content.#(type=="bash_code_execution_tool_result")#' FILE_IDS=$(ant beta:messages create \ --beta files-api-2025-04-14 \ --transform "${TOOL_RESULT}.content.content|@flatten|#.file_id" \ --format yaml \ --model claude-opus-4-7 \ --max-tokens 4096 \ --message '{role: user, content: Create a matplotlib visualization and save it as output.png}' \ --tool '{type: code_execution_20250825, name: code_execution}' ) # Download each created file while IFS= read -r LINE; do [[ "$LINE" != "- "* ]] && continue FILE_ID="${LINE#- }" FILENAME=$(ant beta:files retrieve-metadata \ --file-id "$FILE_ID" \ --transform filename --raw-output) ant beta:files download \ --file-id "$FILE_ID" \ --output "$FILENAME" > /dev/null printf 'Downloaded: %s\n' "$FILENAME" done <<< "$FILE_IDS" ``` ```python Python nocheck hidelines={1..2} from anthropic import Anthropic # Initialize the client client = Anthropic() # Request code execution that creates files response = client.beta.messages.create( model="claude-opus-4-7", betas=["files-api-2025-04-14"], max_tokens=4096, messages=[ { "role": "user", "content": "Create a matplotlib visualization and save it as output.png", } ], tools=[{"type": "code_execution_20250825", "name": "code_execution"}], ) # Extract file IDs from the response def extract_file_ids(response): file_ids = [] for item in response.content: if item.type == "bash_code_execution_tool_result": content_item = item.content if content_item.type == "bash_code_execution_result": # concrete-typed list: List[BashCodeExecutionOutputBlock] for file in content_item.content: file_ids.append(file.file_id) return file_ids # Download the created files for file_id in extract_file_ids(response): file_metadata = client.beta.files.retrieve_metadata(file_id) file_content = client.beta.files.download(file_id) file_content.write_to_file(file_metadata.filename) print(f"Downloaded: {file_metadata.filename}") ``` ```typescript TypeScript nocheck hidelines={5..6,-3..-1} import Anthropic from "@anthropic-ai/sdk"; import { writeFile } from "fs/promises"; const client = new Anthropic(); async function main() { // Request code execution that creates files const response = await client.beta.messages.create({ model: "claude-opus-4-7", betas: ["files-api-2025-04-14"], max_tokens: 4096, messages: [ { role: "user", content: "Create a matplotlib visualization and save it as output.png" } ], tools: [ { type: "code_execution_20250825", name: "code_execution" } ] }); // Extract file IDs from the response for (const item of response.content) { if (item.type === "bash_code_execution_tool_result") { const contentItem = item.content; if (contentItem.type === "bash_code_execution_result" && contentItem.content) { // concrete-typed list: BashCodeExecutionOutputBlock for (const file of contentItem.content) { const fileMetadata = await client.beta.files.retrieveMetadata(file.file_id); const fileResponse = await client.beta.files.download(file.file_id); const fileBytes = Buffer.from(await fileResponse.arrayBuffer()); await writeFile(fileMetadata.filename, fileBytes); console.log(`Downloaded: ${fileMetadata.filename}`); } } } } } main().catch(console.error); ``` ```csharp C# nocheck hidelines={1..14,-2..} using System; using System.IO; using System.Linq; using System.Threading.Tasks; using System.Collections.Generic; using Anthropic; using Anthropic.Models.Messages; public class Program { static async Task Main(string[] args) { var client = new AnthropicClient(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 4096, Messages = [ new() { Role = Role.User, Content = "Create a matplotlib visualization and save it as output.png" } ], Tools = [new ToolUnion(new CodeExecutionTool20250825())] }; var response = await client.Beta.Messages.Create(parameters, ["files-api-2025-04-14"]); var fileIds = ExtractFileIds(response); foreach (var fileId in fileIds) { var fileMetadata = await client.Beta.Files.RetrieveMetadata(fileId); var fileContent = await client.Beta.Files.Download(fileId); await File.WriteAllBytesAsync(fileMetadata.Filename, fileContent); Console.WriteLine($"Downloaded: {fileMetadata.Filename}"); } } static List ExtractFileIds(dynamic response) { var fileIds = new List(); foreach (var item in response.Content) { if (item.Type == "bash_code_execution_tool_result") { var contentItem = item.Content; if (contentItem.Type == "bash_code_execution_result") { // concrete-typed list: BetaBashCodeExecutionOutputBlock foreach (var file in contentItem.Content) { if (file.FileId != null) { fileIds.Add(file.FileId); } } } } } return fileIds; } } ``` ```go Go nocheck hidelines={1..13,61..62} package main import ( "context" "fmt" "io" "log" "os" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: []anthropic.BetaMessageParam{ anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Create a matplotlib visualization and save it as output.png")), }, Tools: []anthropic.BetaToolUnionParam{ {OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}}, }, Betas: []anthropic.AnthropicBeta{ "code-execution-2025-08-25", anthropic.AnthropicBetaFilesAPI2025_04_14, }, }) if err != nil { log.Fatal(err) } fileIDs := extractFileIDs(response) for _, fileID := range fileIDs { fileMetadata, err := client.Beta.Files.GetMetadata(context.TODO(), fileID, anthropic.BetaFileGetMetadataParams{}) if err != nil { log.Fatal(err) } fileContent, err := client.Beta.Files.Download(context.TODO(), fileID, anthropic.BetaFileDownloadParams{}) if err != nil { log.Fatal(err) } outFile, err := os.Create(fileMetadata.Filename) if err != nil { log.Fatal(err) } _, err = io.Copy(outFile, fileContent.Body) if err != nil { log.Fatal(err) } outFile.Close() fileContent.Body.Close() fmt.Printf("Downloaded: %s\n", fileMetadata.Filename) } } func extractFileIDs(response *anthropic.BetaMessage) []string { var fileIDs []string for _, item := range response.Content { switch variant := item.AsAny().(type) { case anthropic.BetaBashCodeExecutionToolResultBlock: // concrete-typed list: BashCodeExecutionOutputBlock for _, file := range variant.Content.Content { if file.FileID != "" { fileIDs = append(fileIDs, file.FileID) } } } } return fileIDs } ``` ```java Java nocheck hidelines={1..6,11..15,39..40} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.core.http.HttpResponse; import com.anthropic.models.beta.messages.MessageCreateParams; import com.anthropic.models.beta.messages.BetaMessage; import com.anthropic.models.beta.messages.BetaContentBlock; import com.anthropic.models.beta.messages.BetaCodeExecutionTool20250825; import com.anthropic.models.beta.messages.BetaBashCodeExecutionResultBlock; import com.anthropic.models.beta.messages.BetaBashCodeExecutionOutputBlock; import com.anthropic.models.beta.files.FileMetadata; import java.io.FileOutputStream; import java.util.ArrayList; import java.util.List; void main() throws Exception { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model("claude-opus-4-7") .addBeta("files-api-2025-04-14") .maxTokens(4096L) .addUserMessage("Create a matplotlib visualization and save it as output.png") .addTool(BetaCodeExecutionTool20250825.builder().build()) .build(); BetaMessage response = client.beta().messages().create(params); List fileIds = extractFileIds(response); for (String fileId : fileIds) { FileMetadata fileMetadata = client.beta().files().retrieveMetadata(fileId); try (HttpResponse fileContent = client.beta().files().download(fileId)) { try (FileOutputStream fos = new FileOutputStream(fileMetadata.filename())) { fileContent.body().transferTo(fos); } } IO.println("Downloaded: " + fileMetadata.filename()); } } List extractFileIds(BetaMessage response) { List fileIds = new ArrayList<>(); // .ifPresent() is the discriminator guard (not concrete-typed; scanner can't see lambda guards) for (BetaContentBlock item : response.content()) { item.bashCodeExecutionToolResult().ifPresent(toolResult -> { if (toolResult.content().isBetaBashCodeExecutionResultBlock()) { BetaBashCodeExecutionResultBlock result = toolResult.content().asBetaBashCodeExecutionResultBlock(); // concrete-typed list: BetaBashCodeExecutionOutputBlock for (BetaBashCodeExecutionOutputBlock output : result.content()) { fileIds.add(output.fileId()); } } }); } return fileIds; } ``` ```php PHP hidelines={1..2,4..5} nocheck beta->messages->create( maxTokens: 4096, messages: [ [ 'role' => 'user', 'content' => 'Create a matplotlib visualization and save it as output.png', ], ], model: 'claude-opus-4-7', betas: ['files-api-2025-04-14'], tools: [ [ 'type' => 'code_execution_20250825', 'name' => 'code_execution', ], ], ); function extractFileIds(BetaMessage $response): array { $fileIds = []; foreach ($response->content as $item) { if ($item->type !== 'bash_code_execution_tool_result') { continue; } $contentItem = $item->content; if ($contentItem->type !== 'bash_code_execution_result') { continue; } // concrete-typed list: BashCodeExecutionOutputBlock foreach ($contentItem->content as $file) { $fileIds[] = $file->fileID; } } return $fileIds; } foreach (extractFileIds($response) as $fileId) { $fileMetadata = $client->beta->files->retrieveMetadata($fileId); $fileContent = $client->beta->files->download($fileId); file_put_contents($fileMetadata->filename, $fileContent); echo "Downloaded: {$fileMetadata->filename}\n"; } ``` ```ruby Ruby nocheck hidelines={1..2} require "anthropic" client = Anthropic::Client.new response = client.beta.messages.create( model: "claude-opus-4-7", betas: ["files-api-2025-04-14"], max_tokens: 4096, messages: [ { role: "user", content: "Create a matplotlib visualization and save it as output.png" } ], tools: [ { type: "code_execution_20250825", name: "code_execution" } ] ) def extract_file_ids(response) file_ids = [] response.content.each do |item| if item.type == :bash_code_execution_tool_result content_item = item.content if content_item.type == :bash_code_execution_result # concrete-typed list: BashCodeExecutionOutputBlock content_item.content.each do |file| file_ids << file.file_id end end end end file_ids end extract_file_ids(response).each do |file_id| file_metadata = client.beta.files.retrieve_metadata(file_id) file_content = client.beta.files.download(file_id) File.open(file_metadata.filename, "wb") do |f| f.write(file_content.read) end puts "Downloaded: #{file_metadata.filename}" end ``` ## Tool definition The code execution tool requires no additional parameters: ```json JSON { "type": "code_execution_20250825", "name": "code_execution" } ``` When this tool is provided, Claude automatically gains access to two sub-tools: - `bash_code_execution`: Run shell commands - `text_editor_code_execution`: View, create, and edit files, including writing code ## Response format The code execution tool can return two types of results depending on the operation: ### Bash command response ```json Output hidelines={1,-1} [ { "type": "server_tool_use", "id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3", "name": "bash_code_execution", "input": { "command": "ls -la | head -5" } }, { "type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3", "content": { "type": "bash_code_execution_result", "stdout": "total 24\ndrwxr-xr-x 2 user user 4096 Jan 1 12:00 .\ndrwxr-xr-x 3 user user 4096 Jan 1 11:00 ..\n-rw-r--r-- 1 user user 220 Jan 1 12:00 data.csv\n-rw-r--r-- 1 user user 180 Jan 1 12:00 config.json", "stderr": "", "return_code": 0 } } ] ``` ### File operation responses **View file:** ```json Output hidelines={1,-1} [ { "type": "server_tool_use", "id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4", "name": "text_editor_code_execution", "input": { "command": "view", "path": "config.json" } }, { "type": "text_editor_code_execution_tool_result", "tool_use_id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4", "content": { "type": "text_editor_code_execution_result", "file_type": "text", "content": "{\n \"setting\": \"value\",\n \"debug\": true\n}", "numLines": 4, "startLine": 1, "totalLines": 4 } } ] ``` **Create file:** ```json Output hidelines={1,-1} [ { "type": "server_tool_use", "id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5", "name": "text_editor_code_execution", "input": { "command": "create", "path": "new_file.txt", "file_text": "Hello, World!" } }, { "type": "text_editor_code_execution_tool_result", "tool_use_id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5", "content": { "type": "text_editor_code_execution_result", "is_file_update": false } } ] ``` **Edit file (str_replace):** ```json Output hidelines={1,-1} [ { "type": "server_tool_use", "id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6", "name": "text_editor_code_execution", "input": { "command": "str_replace", "path": "config.json", "old_str": "\"debug\": true", "new_str": "\"debug\": false" } }, { "type": "text_editor_code_execution_tool_result", "tool_use_id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6", "content": { "type": "text_editor_code_execution_result", "oldStart": 3, "oldLines": 1, "newStart": 3, "newLines": 1, "lines": ["- \"debug\": true", "+ \"debug\": false"] } } ] ``` ### Results All execution results include: - `stdout`: Output from successful execution - `stderr`: Error messages if execution fails - `return_code`: 0 for success, non-zero for failure Additional fields for file operations: - **View**: `file_type`, `content`, `numLines`, `startLine`, `totalLines` - **Create**: `is_file_update` (whether file already existed) - **Edit**: `oldStart`, `oldLines`, `newStart`, `newLines`, `lines` (diff format) ### Errors Each tool type can return specific errors: **Common errors (all tools):** ```json Output { "type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR", "content": { "type": "bash_code_execution_tool_result_error", "error_code": "unavailable" } } ``` **Error codes by tool type:** | Tool | Error Code | Description | |------|-----------|-------------| | All tools | `unavailable` | The tool is temporarily unavailable | | All tools | `execution_time_exceeded` | Execution exceeded maximum time limit | | All tools | `container_expired` | Container expired and is no longer available | | All tools | `invalid_tool_input` | Invalid parameters provided to the tool | | All tools | `too_many_requests` | Rate limit exceeded for tool usage | | bash | `output_file_too_large` | Command output exceeded the maximum size | | text_editor | `file_not_found` | File doesn't exist (for view/edit operations) | | text_editor | `string_not_found` | The `old_str` not found in file (for str_replace) | #### `pause_turn` stop reason The response may include a `pause_turn` stop reason, which indicates that the API paused a long-running turn. You may provide the response back as-is in a subsequent request to let Claude continue its turn, or modify the content if you wish to interrupt the conversation. ## Containers The code execution tool runs in a secure, containerized environment designed specifically for code execution, with a higher focus on Python. ### Runtime environment - **Python version**: 3.11.12 - **Operating system**: Linux-based container - **Architecture**: x86_64 (AMD64) ### Resource limits - **Memory**: 5GiB RAM - **Disk space**: 5GiB workspace storage - **CPU**: 1 CPU ### Networking and security - **Internet access**: Completely disabled for security - **External connections**: No outbound network requests permitted - **Sandbox isolation**: Full isolation from host system and other containers - **File access**: Limited to workspace directory only - **Workspace scoping**: Like [Files](/docs/en/build-with-claude/files), containers are scoped to the workspace of the API key - **Expiration**: Containers expire 30 days after creation ### Pre-installed libraries The sandboxed Python environment includes these commonly used libraries: - **Data Science**: pandas, numpy, scipy, scikit-learn, statsmodels - **Visualization**: matplotlib, seaborn - **File Processing**: pyarrow, openpyxl, xlsxwriter, xlrd, pillow, python-pptx, python-docx, pypdf, pdfplumber, pypdfium2, pdf2image, pdfkit, tabula-py, reportlab[pycairo], Img2pdf - **Math & Computing**: sympy, mpmath - **Utilities**: tqdm, python-dateutil, pytz, joblib, unzip, unrar, 7zip, bc, rg (ripgrep), fd, sqlite ## Container reuse You can reuse an existing container across multiple API requests by providing the container ID from a previous response. This allows you to maintain created files between requests. ### Example ```bash cURL hidelines={1} cd "$(mktemp -d)" # First request: Create a file with a random number curl https://api.anthropic.com/v1/messages \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --data '{ "model": "claude-opus-4-7", "max_tokens": 4096, "messages": [{ "role": "user", "content": "Write a file with a random number and save it to \"/tmp/number.txt\"" }], "tools": [{ "type": "code_execution_20250825", "name": "code_execution" }] }' > response1.json # Extract container ID from the response (using jq) CONTAINER_ID=$(jq -r '.container.id' response1.json) # Second request: Reuse the container to read the file curl https://api.anthropic.com/v1/messages \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --data '{ "container": "'$CONTAINER_ID'", "model": "claude-opus-4-7", "max_tokens": 4096, "messages": [{ "role": "user", "content": "Read the number from \"/tmp/number.txt\" and calculate its square" }], "tools": [{ "type": "code_execution_20250825", "name": "code_execution" }] }' ``` ```bash CLI # First request: Create a file with a random number CONTAINER_ID=$(ant messages create \ --transform container.id --raw-output \ --model claude-opus-4-7 \ --max-tokens 4096 \ --message '{role: user, content: Write a file with a random number and save it to "/tmp/number.txt"}' \ --tool '{type: code_execution_20250825, name: code_execution}' ) # Second request: Reuse the container to read the file ant messages create --container "$CONTAINER_ID" \ --model claude-opus-4-7 \ --max-tokens 4096 \ --message '{role: user, content: Read the number from "/tmp/number.txt" and calculate its square}' \ --tool '{type: code_execution_20250825, name: code_execution}' ``` ```python Python hidelines={1..6} import os from anthropic import Anthropic # Initialize the client client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY")) # First request: Create a file with a random number response1 = client.messages.create( model="claude-opus-4-7", max_tokens=4096, messages=[ { "role": "user", "content": "Write a file with a random number and save it to '/tmp/number.txt'", } ], tools=[{"type": "code_execution_20250825", "name": "code_execution"}], ) # Extract the container ID from the first response container_id = response1.container.id # Second request: Reuse the container to read the file response2 = client.messages.create( container=container_id, # Reuse the same container model="claude-opus-4-7", max_tokens=4096, messages=[ { "role": "user", "content": "Read the number from '/tmp/number.txt' and calculate its square", } ], tools=[{"type": "code_execution_20250825", "name": "code_execution"}], ) print(response2) ``` ```typescript TypeScript hidelines={1..5,-3..-1} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); async function main() { // First request: Create a file with a random number const response1 = await client.beta.messages.create({ model: "claude-opus-4-7", betas: ["code-execution-2025-08-25"], max_tokens: 4096, messages: [ { role: "user", content: "Write a file with a random number and save it to '/tmp/number.txt'" } ], tools: [ { type: "code_execution_20250825", name: "code_execution" } ] }); // Extract the container ID from the first response const containerId = response1.container!.id; // Second request: Reuse the container to read the file const response2 = await client.beta.messages.create({ container: containerId, model: "claude-opus-4-7", betas: ["code-execution-2025-08-25"], max_tokens: 4096, messages: [ { role: "user", content: "Read the number from '/tmp/number.txt' and calculate its square" } ], tools: [ { type: "code_execution_20250825", name: "code_execution" } ] }); console.log(response2.content); } main().catch(console.error); ``` ```csharp C# hidelines={1..11,-2..} using Anthropic; using Anthropic.Models.Messages; using System; using System.Threading.Tasks; class Program { static async Task Main() { AnthropicClient client = new(); var parameters1 = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 4096, Messages = [new() { Role = Role.User, Content = "Write a file with a random number and save it to '/tmp/number.txt'" }], Tools = [new ToolUnion(new CodeExecutionTool20250825())] }; var response1 = await client.Messages.Create(parameters1); var containerId = response1.Container!.ID; var parameters2 = new MessageCreateParams { Container = containerId, Model = Model.ClaudeOpus4_7, MaxTokens = 4096, Messages = [new() { Role = Role.User, Content = "Read the number from '/tmp/number.txt' and calculate its square" }], Tools = [new ToolUnion(new CodeExecutionTool20250825())] }; var response2 = await client.Messages.Create(parameters2); Console.WriteLine(response2); } } ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response1, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: []anthropic.BetaMessageParam{ anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Write a file with a random number and save it to '/tmp/number.txt'")), }, Tools: []anthropic.BetaToolUnionParam{ {OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}}, }, Betas: []anthropic.AnthropicBeta{"code-execution-2025-08-25"}, }) if err != nil { log.Fatal(err) } containerID := response1.Container.ID response2, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Container: anthropic.BetaMessageNewParamsContainerUnion{ OfString: anthropic.String(containerID), }, Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: []anthropic.BetaMessageParam{ anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Read the number from '/tmp/number.txt' and calculate its square")), }, Tools: []anthropic.BetaToolUnionParam{ {OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}}, }, Betas: []anthropic.AnthropicBeta{"code-execution-2025-08-25"}, }) if err != nil { log.Fatal(err) } for _, block := range response2.Content { if block.Type == "text" { fmt.Println(block.Text) } } } ``` ```java Java hidelines={1..5,7..9,-2..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.Model; import com.anthropic.models.messages.CodeExecutionTool20250825; public class ContainerReuse { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params1 = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(4096L) .addUserMessage("Write a file with a random number and save it to '/tmp/number.txt'") .addTool(CodeExecutionTool20250825.builder().build()) .build(); Message response1 = client.messages().create(params1); String containerId = response1.container().get().id(); MessageCreateParams params2 = MessageCreateParams.builder() .container(containerId) .model(Model.CLAUDE_OPUS_4_7) .maxTokens(4096L) .addUserMessage("Read the number from '/tmp/number.txt' and calculate its square") .addTool(CodeExecutionTool20250825.builder().build()) .build(); Message response2 = client.messages().create(params2); System.out.println(response2); } } ``` ```php PHP hidelines={1..4} messages->create( maxTokens: 4096, messages: [ ['role' => 'user', 'content' => "Write a file with a random number and save it to '/tmp/number.txt'"] ], model: 'claude-opus-4-7', tools: [ ['type' => 'code_execution_20250825', 'name' => 'code_execution'] ], ); $containerId = $response1->container->id; $response2 = $client->messages->create( container: $containerId, maxTokens: 4096, messages: [ ['role' => 'user', 'content' => "Read the number from '/tmp/number.txt' and calculate its square"] ], model: 'claude-opus-4-7', tools: [ ['type' => 'code_execution_20250825', 'name' => 'code_execution'] ], ); ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new response1 = client.messages.create( model: "claude-opus-4-7", max_tokens: 4096, messages: [ { role: "user", content: "Write a file with a random number and save it to '/tmp/number.txt'" } ], tools: [ { type: "code_execution_20250825", name: "code_execution" } ] ) container_id = response1.container.id response2 = client.messages.create( container: container_id, model: "claude-opus-4-7", max_tokens: 4096, messages: [ { role: "user", content: "Read the number from '/tmp/number.txt' and calculate its square" } ], tools: [ { type: "code_execution_20250825", name: "code_execution" } ] ) puts response2.content ``` ## Streaming With streaming enabled, you'll receive code execution events as they occur: ```sse event: content_block_start data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "code_execution"}} // Code execution streamed event: content_block_delta data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"code\":\"import pandas as pd\\ndf = pd.read_csv('data.csv')\\nprint(df.head())\"}"}} // Pause while code executes // Execution results streamed event: content_block_start data: {"type": "content_block_start", "index": 2, "content_block": {"type": "code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"stdout": " A B C\n0 1 2 3\n1 4 5 6", "stderr": ""}}} ``` ## Batch requests You can include the code execution tool in the [Messages Batches API](/docs/en/build-with-claude/batch-processing). Code execution tool calls through the Messages Batches API are priced the same as those in regular Messages API requests. ## Usage and pricing **Code execution is free when used with web search or web fetch.** When `web_search_20260209` or `web_fetch_20260209` is included in your API request, there are no additional charges for code execution tool calls beyond the standard input and output token costs. When used without these tools, code execution is billed by execution time, tracked separately from token usage: - Execution time has a minimum of 5 minutes - Each organization receives **1,550 free hours** of usage per month - Additional usage beyond 1,550 hours is billed at **$0.05 per hour, per container** - If files are included in the request, execution time is billed even if the tool is not invoked, due to files being preloaded onto the container Code execution usage is tracked in the response: ```json "usage": { "input_tokens": 105, "output_tokens": 239, "server_tool_use": { "code_execution_requests": 1 } } ``` ## Upgrade to latest tool version By upgrading to `code-execution-2025-08-25`, you get access to file manipulation and Bash capabilities, including code in multiple languages. There is no price difference. ### What's changed | Component | Legacy | Current | |-----------|------------------|----------------------------| | Beta header | `code-execution-2025-05-22` | `code-execution-2025-08-25` | | Tool type | `code_execution_20250522` | `code_execution_20250825` | | Capabilities | Python only | Bash commands, file operations | | Response types | `code_execution_result` | `bash_code_execution_result`, `text_editor_code_execution_result` | ### Backward compatibility - All existing Python code execution continues to work exactly as before - No changes required to existing Python-only workflows ### Upgrade steps To upgrade, update the tool type in your API requests: ```diff - "type": "code_execution_20250522" + "type": "code_execution_20250825" ``` **Review response handling** (if parsing responses programmatically): - The previous blocks for Python execution responses will no longer be sent - Instead, new response types for Bash and file operations will be sent (see Response Format section) ## Programmatic tool calling For running tools inside the code execution container, see [Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling). ## Data retention Code execution runs in server-side sandbox containers. Container data, including execution artifacts, uploaded files, and outputs, is retained for up to 30 days. This retention applies to all data processed within the container environment. Files that code execution creates in the [Files API](/docs/en/build-with-claude/files) (retrievable via `client.beta.files.download()`) persist until explicitly deleted. For ZDR eligibility across all features, see [API and data retention](/docs/en/manage-claude/api-and-data-retention). ## Using code execution with Agent Skills The code execution tool enables Claude to use [Agent Skills](/docs/en/agents-and-tools/agent-skills/overview). Skills are modular capabilities consisting of instructions, scripts, and resources that extend Claude's functionality. Learn more in [Agent Skills](/docs/en/agents-and-tools/agent-skills/overview) and [Using Agent Skills with the API](/docs/en/build-with-claude/skills-guide). --- # Computer use tool URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool # Computer use tool --- Claude can interact with computer environments through the computer use tool, which provides screenshot capabilities and mouse/keyboard control for autonomous desktop interaction. On [WebArena](https://webarena.dev/), a benchmark for autonomous web navigation across real websites, Claude achieves state-of-the-art results among single-agent systems, demonstrating strong ability to complete multi-step browser tasks end to end. Computer use is in beta and requires a [beta header](/docs/en/api/beta-headers): - `"computer-use-2025-11-24"` for Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, and Claude Opus 4.5 - `"computer-use-2025-01-24"` for Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.1, Claude Sonnet 4 ([deprecated](/docs/en/about-claude/model-deprecations)), and Claude Opus 4 ([deprecated](/docs/en/about-claude/model-deprecations)) Reach out through the [feedback form](https://forms.gle/H6UFuXaaLywri9hz6) to share your feedback on this feature. This feature is eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned. ## Overview Computer use is a beta feature that enables Claude to interact with desktop environments. This tool provides: - **Screenshot capture**: See what's currently displayed on screen - **Mouse control**: Click, drag, and move the cursor - **Keyboard input**: Type text and use keyboard shortcuts - **Desktop automation**: Interact with any application or interface While computer use can be augmented with other tools like bash and text editor for more comprehensive automation workflows, computer use specifically refers to the computer use tool's capability to see and control desktop environments. For model support, see the [Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference). ## Security considerations Computer use is a beta feature with unique risks distinct from standard API features. These risks are heightened when interacting with the internet. To minimize risks, consider taking precautions such as: 1. Using a dedicated virtual machine or container with minimal privileges to prevent direct system attacks or accidents. 2. Avoiding giving the model access to sensitive data, such as account login information, to prevent information theft. 3. Limiting internet access to an allowlist of domains to reduce exposure to malicious content. 4. Asking a human to confirm decisions that may result in meaningful real-world consequences as well as any tasks requiring affirmative consent, such as accepting cookies, executing financial transactions, or agreeing to terms of service. In some circumstances, Claude will follow commands found in content even if it conflicts with the user's instructions. For example, Claude instructions on webpages or contained in images may override instructions or cause Claude to make mistakes. Take precautions to isolate Claude from sensitive data and actions to avoid risks related to prompt injection. The model has been trained to resist these prompt injections, and an extra layer of defense has been added. If you use the computer use tools, classifiers will automatically run on your prompts to flag potential instances of prompt injections. When these classifiers identify potential prompt injections in screenshots, they will automatically steer the model to ask for user confirmation before proceeding with the next action. This extra protection won't be ideal for every use case (for example, use cases without a human in the loop), so if you'd like to opt out and turn it off, please [contact support](https://support.claude.com/en/). These precautions remain important even with the classifier defense layer in place. Inform end users of relevant risks and obtain their consent prior to enabling computer use in your own products. Get started quickly with the computer use reference implementation that includes a web interface, Docker container, example tool implementations, and an agent loop. ## Quick start Here's how to get started with computer use: ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "content-type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: computer-use-2025-11-24" \ -d '{ "model": "claude-opus-4-7", "max_tokens": 1024, "tools": [ { "type": "computer_20251124", "name": "computer", "display_width_px": 1024, "display_height_px": 768, "display_number": 1 }, { "type": "text_editor_20250728", "name": "str_replace_based_edit_tool" }, { "type": "bash_20250124", "name": "bash" } ], "messages": [ { "role": "user", "content": "Save a picture of a cat to my desktop." } ] }' ``` ```bash CLI ant beta:messages create --beta computer-use-2025-11-24 <<'YAML' model: claude-opus-4-7 max_tokens: 1024 tools: - type: computer_20251124 name: computer display_width_px: 1024 display_height_px: 768 display_number: 1 - type: text_editor_20250728 name: str_replace_based_edit_tool - type: bash_20250124 name: bash messages: - role: user content: Save a picture of a cat to my desktop. YAML ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() response = client.beta.messages.create( model="claude-opus-4-7", # or another compatible model max_tokens=1024, tools=[ { "type": "computer_20251124", "name": "computer", "display_width_px": 1024, "display_height_px": 768, "display_number": 1, }, {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}, {"type": "bash_20250124", "name": "bash"}, ], messages=[{"role": "user", "content": "Save a picture of a cat to my desktop."}], betas=["computer-use-2025-11-24"], ) print(response) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const response = await client.beta.messages.create({ model: "claude-opus-4-7", max_tokens: 1024, tools: [ { type: "computer_20251124", name: "computer", display_width_px: 1024, display_height_px: 768, display_number: 1 }, { type: "text_editor_20250728", name: "str_replace_based_edit_tool" }, { type: "bash_20250124", name: "bash" } ], messages: [{ role: "user", content: "Save a picture of a cat to my desktop." }], betas: ["computer-use-2025-11-24"] }); console.log(response); ``` ```csharp C# using Anthropic; using Anthropic.Models.Beta.Messages; using Messages = Anthropic.Models.Messages; var client = new AnthropicClient(); var parameters = new MessageCreateParams { Model = Messages::Model.ClaudeOpus4_7, MaxTokens = 1024, Tools = new BetaToolUnion[] { new BetaToolComputerUse20251124 { DisplayWidthPx = 1024, DisplayHeightPx = 768, DisplayNumber = 1 }, new BetaToolTextEditor20250728(), new BetaToolBash20250124() }, Messages = [ new BetaMessageParam { Role = Role.User, Content = "Save a picture of a cat to my desktop." } ], Betas = ["computer-use-2025-11-24"] }; var response = await client.Beta.Messages.Create(parameters); Console.WriteLine(response); ``` ```go Go nocheck hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 1024, Tools: []anthropic.BetaToolUnionParam{ {OfComputerUseTool20251124: &anthropic.BetaToolComputerUse20251124Param{ DisplayWidthPx: 1024, DisplayHeightPx: 768, DisplayNumber: anthropic.Int(1), }}, {OfTextEditor20250728: &anthropic.BetaToolTextEditor20250728Param{}}, {OfBashTool20250124: &anthropic.BetaToolBash20250124Param{}}, }, Messages: []anthropic.BetaMessageParam{ anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Save a picture of a cat to my desktop.")), }, Betas: []anthropic.AnthropicBeta{ anthropic.AnthropicBetaComputerUse2025_11_24, }, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```java Java hidelines={1..3,7..10,-2..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.beta.messages.BetaMessage; import com.anthropic.models.beta.messages.BetaToolBash20250124; import com.anthropic.models.beta.messages.BetaToolComputerUse20251124; import com.anthropic.models.beta.messages.BetaToolTextEditor20250728; import com.anthropic.models.beta.messages.MessageCreateParams; public class ComputerUseExample { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model("claude-opus-4-7") .maxTokens(1024L) .addTool(BetaToolComputerUse20251124.builder() .displayWidthPx(1024L) .displayHeightPx(768L) .displayNumber(1L) .build()) .addTool(BetaToolTextEditor20250728.builder().build()) .addTool(BetaToolBash20250124.builder().build()) .addUserMessage("Save a picture of a cat to my desktop.") .addBeta("computer-use-2025-11-24") .build(); BetaMessage response = client.beta().messages().create(params); System.out.println(response); } } ``` ```php PHP hidelines={1..4} beta->messages->create( maxTokens: 1024, messages: [ ['role' => 'user', 'content' => 'Save a picture of a cat to my desktop.'], ], model: 'claude-opus-4-7', tools: [ [ 'type' => 'computer_20251124', 'name' => 'computer', 'display_width_px' => 1024, 'display_height_px' => 768, 'display_number' => 1, ], [ 'type' => 'text_editor_20250728', 'name' => 'str_replace_based_edit_tool', ], [ 'type' => 'bash_20250124', 'name' => 'bash', ], ], betas: ['computer-use-2025-11-24'], ); echo $response; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new response = client.beta.messages.create( model: "claude-opus-4-7", max_tokens: 1024, tools: [ { type: "computer_20251124", name: "computer", display_width_px: 1024, display_height_px: 768, display_number: 1 }, { type: "text_editor_20250728", name: "str_replace_based_edit_tool" }, { type: "bash_20250124", name: "bash" } ], messages: [ { role: "user", content: "Save a picture of a cat to my desktop." } ], betas: ["computer-use-2025-11-24"] ) puts response ``` A beta header is only required for the computer use tool. The example above shows all three tools being used together, which requires the beta header because it includes the computer use tool. --- ## How computer use works - Add the computer use tool (and optionally other tools) to your API request. - Include a user prompt that requires desktop interaction, for example, "Save a picture of a cat to my desktop." - Claude assesses if the computer use tool can help with the user's query. - If yes, Claude constructs a properly formatted tool use request. - The API response has a `stop_reason` of `tool_use`, signaling Claude's intent. - On your end, extract the tool name and input from Claude's request. - Use the tool on a container or Virtual Machine. - Continue the conversation with a new `user` message containing a `tool_result` content block. - Claude analyzes the tool results to determine if more tool use is needed or the task has been completed. - If Claude decides it needs another tool, it responds with another `tool_use` `stop_reason` and you should return to step 3. - Otherwise, it crafts a text response to the user. The repetition of steps 3 and 4 without user input is referred to as the "agent loop" (that is, Claude responding with a tool use request and your application responding to Claude with the results of evaluating that request). ### The computing environment Computer use requires a sandboxed computing environment where Claude can safely interact with applications and the web. This environment includes: 1. **Virtual display**: A virtual X11 display server (using Xvfb) that renders the desktop interface Claude will see through screenshots and control with mouse/keyboard actions. 2. **Desktop environment**: A lightweight UI with window manager (Mutter) and panel (Tint2) running on Linux, which provides a consistent graphical interface for Claude to interact with. 3. **Applications**: Pre-installed Linux applications like Firefox, LibreOffice, text editors, and file managers that Claude can use to complete tasks. 4. **Tool implementations**: Integration code that translates Claude's abstract tool requests (like "move mouse" or "take screenshot") into actual operations in the virtual environment. 5. **Agent loop**: A program that handles communication between Claude and the environment, sending Claude's actions to the environment and returning the results (screenshots, command outputs) back to Claude. When you use computer use, Claude doesn't directly connect to this environment. Instead, your application: 1. Receives Claude's tool use requests 2. Translates them into actions in your computing environment 3. Captures the results (screenshots, command outputs, etc.) 4. Returns these results to Claude For security and isolation, the reference implementation runs all of this inside a Docker container with appropriate port mappings for viewing and interacting with the environment. --- ## How to implement computer use ### Start with the reference implementation A [reference implementation](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo) is available that includes everything you need to get started quickly with computer use: - A [containerized environment](https://github.com/anthropics/anthropic-quickstarts/blob/main/computer-use-demo/Dockerfile) suitable for computer use with Claude - Implementations of [the computer use tools](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo/computer_use_demo/tools) - An [agent loop](https://github.com/anthropics/anthropic-quickstarts/blob/main/computer-use-demo/computer_use_demo/loop.py) that interacts with the Claude API and executes the computer use tools - A web interface to interact with the container, agent loop, and tools. ### Understanding the agentic loop The core of computer use is the "agent loop" - a cycle where Claude requests tool actions, your application executes them, and returns results to Claude. Here's a simplified example: ```python hidelines={1} from anthropic import Anthropic async def sampling_loop( *, model: str, messages: list[dict], api_key: str, max_tokens: int = 4096, tool_version: str, max_iterations: int = 10, # Add iteration limit to prevent infinite loops ): """ A simple agent loop for Claude computer use interactions. This function handles the back-and-forth between: 1. Sending user messages to Claude 2. Claude requesting to use tools 3. Your app executing those tools 4. Sending tool results back to Claude """ # Set up tools and API parameters client = Anthropic(api_key=api_key) beta_flag = ( "computer-use-2025-11-24" if "20251124" in tool_version else "computer-use-2025-01-24" ) # Configure tools - you should already have these initialized elsewhere tools = [ { "type": f"computer_{tool_version}", "name": "computer", "display_width_px": 1024, "display_height_px": 768, }, {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}, {"type": "bash_20250124", "name": "bash"}, ] # Main agent loop (with iteration limit to prevent runaway API costs) iterations = 0 while True and iterations < max_iterations: iterations += 1 # Call the Claude API response = client.beta.messages.create( model=model, max_tokens=max_tokens, messages=messages, tools=tools, betas=[beta_flag], ) # Add Claude's response to the conversation history response_content = response.content messages.append({"role": "assistant", "content": response_content}) # Check if Claude used any tools tool_results = [] for block in response_content: if block.type == "tool_use": # In a real app, you would execute the tool here # For example: result = run_tool(block.name, block.input) result = {"result": "Tool executed successfully"} # Format the result for Claude tool_results.append( {"type": "tool_result", "tool_use_id": block.id, "content": result} ) # If no tools were used, Claude is done - return the final messages if not tool_results: return messages # Add tool results to messages for the next iteration with Claude messages.append({"role": "user", "content": tool_results}) ``` The loop continues until either Claude responds without requesting any tools (task completion) or the maximum iteration limit is reached. This safeguard prevents potential infinite loops that could result in unexpected API costs. Try the reference implementation out before reading the rest of this documentation. ### Optimize model performance with prompting Here are some tips on how to get the best quality outputs: 1. Specify simple, well-defined tasks and provide explicit instructions for each step. 2. Claude sometimes assumes outcomes of its actions without explicitly checking their results. To prevent this you can prompt Claude with `After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. Explicitly show your thinking: "I have evaluated step X..." If not correct, try again. Only when you confirm a step was executed correctly should you move on to the next one.` 3. Some UI elements (like dropdowns and scrollbars) might be tricky for Claude to manipulate using mouse movements. If you experience this, try prompting the model to use keyboard shortcuts. 4. For repeatable tasks or UI interactions, include example screenshots and tool calls of successful outcomes in your prompt. 5. If you need the model to log in, provide it with the username and password in your prompt inside xml tags like ``. Using computer use within applications that require login increases the risk of bad outcomes as a result of prompt injection. Review the [guide on mitigating prompt injections](/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks) before providing the model with login credentials. If you repeatedly encounter a clear set of issues or know in advance the tasks Claude will need to complete, use the system prompt to provide Claude with explicit tips or instructions on how to do the tasks successfully. For agents that span multiple sessions, run end-to-end verification at the start of each session, not only after implementation. Browser-based checks catch regressions from prior sessions that code-level review alone misses. See [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) for details. ### System prompts When one of the Anthropic-schema tools is requested via the Claude API, a computer use-specific system prompt is generated. It's similar to the [tool use system prompt](/docs/en/agents-and-tools/tool-use/define-tools#tool-use-system-prompt) but starts with: > You have access to a set of functions you can use to answer the user's question. This includes access to a sandboxed computing environment. You do NOT currently have the ability to inspect files or interact with external resources, except by invoking the below functions. As with regular tool use, the user-provided `system_prompt` field is still respected and used in the construction of the combined system prompt. ### Available actions The computer use tool supports these actions: **Basic actions (all versions)** - **screenshot** - Capture the current display - **left_click** - Click at coordinates `[x, y]` - **type** - Type text string - **key** - Press key or key combination (for example, "ctrl+s") - **mouse_move** - Move cursor to coordinates **Enhanced actions (`computer_20250124`)** Available on all models that support computer use: - **scroll** - Scroll in any direction with amount control - **left_click_drag** - Click and drag between coordinates - **right_click**, **middle_click** - Additional mouse buttons - **double_click**, **triple_click** - Multiple clicks - **left_mouse_down**, **left_mouse_up** - Fine-grained click control - **hold_key** - Hold down a key for a specified duration (in seconds) - **wait** - Pause between actions **Enhanced actions (`computer_20251124`)** Available in Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, and Claude Opus 4.5: - All actions from `computer_20250124` - **zoom** - View a specific region of the screen at full resolution. Requires `enable_zoom: true` in tool definition. Takes a `region` parameter with coordinates `[x1, y1, x2, y2]` defining top-left and bottom-right corners of the area to inspect.

Take a screenshot: ```json { "action": "screenshot" } ``` Click at position: ```json { "action": "left_click", "coordinate": [500, 300] } ``` Type text: ```json { "action": "type", "text": "Hello, world!" } ``` Scroll down: ```json { "action": "scroll", "coordinate": [500, 400], "scroll_direction": "down", "scroll_amount": 3 } ``` Zoom to view region in detail (Opus 4.7, Opus 4.6, Sonnet 4.6, Opus 4.5): ```json { "action": "zoom", "region": [100, 200, 400, 350] } ```

To hold modifier keys (like Shift, Ctrl, or Alt) while performing click or scroll actions, use the `text` parameter on those actions. This is different from `hold_key`, which simply holds a key for a duration without performing other actions. Shift+click (e.g., for selecting a range of items): ```json { "action": "left_click", "coordinate": [500, 300], "text": "shift" } ``` Ctrl+click (e.g., for multi-select on Windows/Linux): ```json { "action": "left_click", "coordinate": [500, 300], "text": "ctrl" } ``` Cmd+click (e.g., for multi-select on macOS): ```json { "action": "left_click", "coordinate": [500, 300], "text": "super" } ``` Shift+scroll (e.g., for horizontal scrolling): ```json { "action": "scroll", "coordinate": [500, 400], "scroll_direction": "down", "scroll_amount": 3, "text": "shift" } ``` The `text` parameter in click/scroll actions accepts modifier keys like `shift`, `ctrl`, `alt`, and `super` (for the Command/Windows key).

### Tool parameters | Parameter | Required | Description | |-----------|----------|-------------| | `type` | Yes | Tool version (`computer_20251124` or `computer_20250124`) | | `name` | Yes | Must be "computer" | | `display_width_px` | Yes | Display width in pixels | | `display_height_px` | Yes | Display height in pixels | | `display_number` | No | Display number for X11 environments | | `enable_zoom` | No | Enable zoom action (`computer_20251124` only). Set to `true` to allow Claude to zoom into specific screen regions. Default: `false` | **Important:** The computer use tool must be explicitly executed by your application - Claude cannot execute it directly. You are responsible for implementing the screenshot capture, mouse movements, keyboard inputs, and other actions based on Claude's requests. ### Combining with extended thinking For combining computer use with extended thinking, see [Extended thinking](/docs/en/build-with-claude/extended-thinking). ### Augmenting computer use with other tools To add other tools alongside computer use, include them in the same `tools` array. The quick start above shows this pattern with the [bash tool](/docs/en/agents-and-tools/tool-use/bash-tool) and [text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool). You can add your own [custom tool definitions](/docs/en/agents-and-tools/tool-use/define-tools) the same way. ### Build a custom computer use environment The [reference implementation](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo) is meant to help you get started with computer use. It includes all of the components needed to have Claude use a computer. However, you can build your own environment for computer use to suit your needs. You'll need: - A virtualized or containerized environment suitable for computer use with Claude - An implementation of at least one of the Anthropic-schema computer use tools - An agent loop that interacts with the Claude API and executes the `tool_use` results using your tool implementations - An API or UI that allows user input to start the agent loop #### Implement the computer use tool The computer use tool is implemented as a schema-less tool. When using this tool, you don't need to provide an input schema as with other tools; the schema is built into Claude's model and can't be modified. Create a virtual display or connect to an existing display that Claude will interact with. This typically involves setting up Xvfb (X Virtual Framebuffer) or similar technology. Create functions to handle each action type that Claude might request: ```python hidelines={1..3} def capture_screenshot(): ... def click_at(x, y): ... def type_text(text): ... def handle_computer_action(action_type, params): if action_type == "screenshot": return capture_screenshot() elif action_type == "left_click": x, y = params["coordinate"] return click_at(x, y) elif action_type == "type": return type_text(params["text"]) # ... handle other actions ``` Extract and execute tool calls from Claude's responses: ```python hidelines={1..11} from types import SimpleNamespace as _SN response = _SN( content=[_SN(type="tool_use", input={"action": "screenshot"}, id="toolu_01")] ) def handle_computer_action(a, p): return "ok" for content in response.content: if content.type == "tool_use": action = content.input["action"] result = handle_computer_action(action, content.input) # Return result to Claude tool_result = { "type": "tool_result", "tool_use_id": content.id, "content": result, } ``` Create a loop that continues until Claude completes the task: ```python hidelines={1..18} import anthropic client = anthropic.Anthropic() messages = [{"role": "user", "content": "Take a screenshot"}] tools = [ { "type": "computer_20251124", "name": "computer", "display_width_px": 1024, "display_height_px": 768, } ] def process_tool_calls(r): return [] while True: response = client.beta.messages.create( model="claude-opus-4-7", max_tokens=4096, messages=messages, tools=tools, betas=["computer-use-2025-11-24"], ) # Check if Claude used any tools tool_results = process_tool_calls(response) if not tool_results: # No more tool use, task complete break # Continue conversation with tool results messages.append({"role": "user", "content": tool_results}) ``` #### Handle errors When implementing the computer use tool, various errors may occur. Here's how to handle them:

If screenshot capture fails, return an appropriate error message: ```json { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "Error: Failed to capture screenshot. Display may be locked or unavailable.", "is_error": true } ] } ```

If Claude provides coordinates outside the display bounds: ```json { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "Error: Coordinates (1200, 900) are outside display bounds (1024x768).", "is_error": true } ] } ```

If an action fails to execute: ```json { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "Error: Failed to perform click action. The application may be unresponsive.", "is_error": true } ] } ```

#### Handle coordinate scaling for higher resolutions Claude Opus 4.7 supports up to 2576 pixels on the long edge, and its coordinates are 1\:1 with image pixels (no scale-factor conversion required). The 1568-pixel guidance below applies to earlier models. The API constrains images to a maximum of 1568 pixels on the longest edge and approximately 1.15 megapixels total (see [image resizing](/docs/en/build-with-claude/vision#evaluate-image-size) for details). For example, a 1512x982 screen gets downsampled to approximately 1330x864. Claude analyzes this smaller image and returns coordinates in that space, but your tool executes clicks in the original screen space. This can cause Claude's click coordinates to miss their targets unless you handle the coordinate transformation. To fix this, resize screenshots yourself and scale Claude's coordinates back up: ```python Python hidelines={1..7} screen_width, screen_height = 1512, 982 def capture_and_resize(w, h): ... def perform_click(x, y): ... import math def get_scale_factor(width, height): """Calculate scale factor to meet API constraints.""" long_edge = max(width, height) total_pixels = width * height long_edge_scale = 1568 / long_edge total_pixels_scale = math.sqrt(1_150_000 / total_pixels) return min(1.0, long_edge_scale, total_pixels_scale) # When capturing screenshot scale = get_scale_factor(screen_width, screen_height) scaled_width = int(screen_width * scale) scaled_height = int(screen_height * scale) # Resize image to scaled dimensions before sending to Claude screenshot = capture_and_resize(scaled_width, scaled_height) # When handling Claude's coordinates, scale them back up def execute_click(x, y): screen_x = x / scale screen_y = y / scale perform_click(screen_x, screen_y) ``` ```typescript TypeScript hidelines={1..6} const screenWidth = 1512; const screenHeight = 982; function captureAndResize(w: number, h: number): string { return ""; } function performClick(x: number, y: number): void {} const MAX_LONG_EDGE = 1568; const MAX_PIXELS = 1_150_000; function getScaleFactor(width: number, height: number): number { const longEdge = Math.max(width, height); const totalPixels = width * height; const longEdgeScale = MAX_LONG_EDGE / longEdge; const totalPixelsScale = Math.sqrt(MAX_PIXELS / totalPixels); return Math.min(1.0, longEdgeScale, totalPixelsScale); } // When capturing screenshot const scale = getScaleFactor(screenWidth, screenHeight); const scaledWidth = Math.floor(screenWidth * scale); const scaledHeight = Math.floor(screenHeight * scale); // Resize image to scaled dimensions before sending to Claude const screenshot = captureAndResize(scaledWidth, scaledHeight); // When handling Claude's coordinates, scale them back up function executeClick(x: number, y: number): void { const screenX = x / scale; const screenY = y / scale; performClick(screenX, screenY); } ``` #### Follow implementation best practices

Set display dimensions that match your use case while staying within recommended limits: - For general desktop tasks: 1024x768 or 1280x720 - For web applications: 1280x800 or 1366x768 - Avoid resolutions above 1920x1080 to prevent performance issues

When returning screenshots to Claude: - Encode screenshots as base64 PNG or JPEG - Consider compressing large screenshots to improve performance - Include relevant metadata like timestamp or display state - If using higher resolutions, ensure coordinates are accurately scaled

Some applications need time to respond to actions: ```python hidelines={1..4} import time def click_at(x, y): ... def click_and_wait(x, y, wait_time=0.5): click_at(x, y) time.sleep(wait_time) # Allow UI to update ```

Check that requested actions are safe and valid: ```python hidelines={1} display_width, display_height = 1024, 768 def validate_action(action_type, params): if action_type == "left_click": x, y = params.get("coordinate", (0, 0)) if not (0 <= x < display_width and 0 <= y < display_height): return False, "Coordinates out of bounds" return True, None ```

Keep a log of all actions for troubleshooting: ```python import logging def log_action(action_type, params, result): logging.info(f"Action: {action_type}, Params: {params}, Result: {result}") ```

--- ## Understand computer use limitations The computer use functionality is in beta. While Claude's capabilities are cutting edge, developers should be aware of its limitations: 1. **Latency**: the current computer use latency for human-AI interactions may be too slow compared to regular human-directed computer actions. Focus on use cases where speed isn't critical (for example, background information gathering, automated software testing) in trusted environments. 2. **Computer vision accuracy and reliability**: Claude may make mistakes or hallucinate when outputting specific coordinates while generating actions. Extended thinking can help you understand the model's reasoning and identify potential issues. 3. **Tool selection accuracy and reliability**: Claude may make mistakes or hallucinate when selecting tools while generating actions or take unexpected actions to solve problems. Additionally, reliability may be lower when interacting with niche applications or multiple applications at once. Prompt the model carefully when requesting complex tasks. 4. **Scrolling reliability**: The scroll action supports direction control (up, down, left, right) and a specified amount. In applications where scrolling doesn't take effect, keyboard alternatives such as Page Down can help. 5. **Spreadsheet interaction**: Use the fine-grained mouse control actions (`left_mouse_down`, `left_mouse_up`) and modifier-key combinations to select individual cells. Complex spreadsheet operations may still require multiple attempts. 6. **Account creation and content generation on social and communications platforms**: While Claude will visit websites, Claude's ability to create accounts or generate and share content or otherwise engage in human impersonation across social media websites and platforms is limited. This capability may be updated in the future. 7. **Vulnerabilities**: Vulnerabilities like jailbreaking or prompt injection may persist across frontier AI systems, including the beta computer use API. In some circumstances, Claude will follow commands found in content, sometimes even in conflict with the user's instructions. For example, Claude instructions on webpages or contained in images may override instructions or cause Claude to make mistakes. Consider the following: a. Limiting computer use to trusted environments such as virtual machines or containers with minimal privileges b. Avoiding giving computer use access to sensitive accounts or data without strict oversight c. Informing end users of relevant risks and obtaining their consent before enabling or requesting permissions necessary for computer use features in your applications 8. **Inappropriate or illegal actions**: Per Anthropic's terms of service, you must not employ computer use to violate any laws or the Acceptable Use Policy. Always carefully review and verify Claude's computer use actions and logs. Do not use Claude for tasks requiring perfect precision or sensitive user information without human oversight. ## Data retention Computer use is a client-side tool. All screenshots, mouse actions, keyboard inputs, and any files involved in a session are captured and stored in your environment, not by Anthropic. Anthropic processes the screenshot images and action requests in real time as part of the API call but does not retain them after the response is returned. Because your application controls where and how computer use data is stored, computer use is ZDR eligible. For ZDR eligibility across all features, see [API and data retention](/docs/en/manage-claude/api-and-data-retention). ## Pricing Computer use follows the standard [tool use pricing](/docs/en/agents-and-tools/tool-use/overview#pricing). When using the computer use tool: **System prompt overhead**: The computer use beta adds 466-499 tokens to the system prompt **Computer use tool token usage**: | Model | Input tokens per tool definition | | ----- | -------------------------------- | | Claude 4.x models | 735 tokens | **Additional token consumption**: - Screenshot images (see [Vision pricing](/docs/en/build-with-claude/vision)) - Tool execution results returned to Claude If you're also using bash or text editor tools alongside computer use, those tools have their own token costs as documented in their respective pages. ## Next steps Get started quickly with the complete Docker-based implementation Learn more about tool use and creating custom tools --- # Define tools URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools # Define tools Specify tool schemas, write effective descriptions, and control when Claude calls your tools. --- ## Choosing a model Use the latest Claude Opus (4.7) model for complex tools and ambiguous queries; it handles multiple tools better and seeks clarification when needed. Use Claude Haiku models for straightforward tools, but note they may infer missing parameters. If using Claude with tool use and extended thinking, refer to the [extended thinking guide](/docs/en/build-with-claude/extended-thinking) for more information. ## Specifying client tools Client tools (both Anthropic-schema and user-defined) are specified in the `tools` top-level parameter of the API request. Each tool definition includes: | Parameter | Description | | :------------- | :-------------------------------------------------------------------------------------------------- | | `name` | The name of the tool. Must match the regex `^[a-zA-Z0-9_-]{1,64}$`. | | `description` | A detailed plaintext description of what the tool does, when it should be used, and how it behaves. | | `input_schema` | A [JSON Schema](https://json-schema.org/) object defining the expected parameters for the tool. | | `input_examples` | (Optional) An array of example input objects to help Claude understand how to use the tool. See [Providing tool use examples](#providing-tool-use-examples). | For the full set of optional properties available on any tool definition, including `cache_control`, `strict`, `defer_loading`, and `allowed_callers`, see the [Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference#tool-definition-properties).

```json JSON { "name": "get_weather", "description": "Get the current weather in a given location", "input_schema": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "The unit of temperature, either 'celsius' or 'fahrenheit'" } }, "required": ["location"] } } ``` This tool, named `get_weather`, expects an input object with a required `location` string and an optional `unit` string that must be either "celsius" or "fahrenheit".

### Tool use system prompt When you call the Claude API with the `tools` parameter, the API constructs a special system prompt from the tool definitions, tool configuration, and any user-specified system prompt. The constructed prompt is designed to instruct the model to use the specified tool(s) and provide the necessary context for the tool to operate properly: ```text In this environment you have access to a set of tools you can use to answer the user's question. {{ FORMATTING INSTRUCTIONS }} String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions. Here are the functions available in JSONSchema format: {{ TOOL DEFINITIONS IN JSON SCHEMA }} {{ USER SYSTEM PROMPT }} {{ TOOL CONFIGURATION }} ``` ### Best practices for tool definitions To get the best performance out of Claude when using tools, follow these guidelines: - **Provide extremely detailed descriptions.** This is by far the most important factor in tool performance. Your descriptions should explain every detail about the tool, including: - What the tool does - When it should be used (and when it shouldn't) - What each parameter means and how it affects the tool's behavior - Any important caveats or limitations, such as what information the tool does not return if the tool name is unclear. The more context you can give Claude about your tools, the better it will be at deciding when and how to use them. Aim for at least 3-4 sentences per tool description, more if the tool is complex. - **Prioritize descriptions, but consider using `input_examples` for complex tools.** Clear descriptions are most important, but for tools with complex inputs, nested objects, or format-sensitive parameters, you can use the `input_examples` field to provide schema-validated examples. See [Providing tool use examples](#providing-tool-use-examples) for details. - **Consolidate related operations into fewer tools.** Rather than creating a separate tool for every action (`create_pr`, `review_pr`, `merge_pr`), group them into a single tool with an `action` parameter. Fewer, more capable tools reduce selection ambiguity and make your tool surface easier for Claude to navigate. - **Use meaningful namespacing in tool names.** When your tools span multiple services or resources, prefix names with the service (e.g., `github_list_prs`, `slack_send_message`). This makes tool selection unambiguous as your library grows, and is especially important when using [tool search](/docs/en/agents-and-tools/tool-use/tool-search-tool). - **Design tool responses to return only high-signal information.** Return semantic, stable identifiers (e.g., slugs or UUIDs) rather than opaque internal references, and include only the fields Claude needs to reason about its next step. Bloated responses waste context and make it harder for Claude to extract what matters.

```json JSON { "name": "get_stock_price", "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.", "input_schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." } }, "required": ["ticker"] } } ```

```json JSON { "name": "get_stock_price", "description": "Gets the stock price for a ticker.", "input_schema": { "type": "object", "properties": { "ticker": { "type": "string" } }, "required": ["ticker"] } } ```

The good description clearly explains what the tool does, when to use it, what data it returns, and what the `ticker` parameter means. The poor description is too brief and leaves Claude with many open questions about the tool's behavior and usage. For deeper guidance on tool design (consolidation, naming, and response shaping), see [Writing tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents). ## Providing tool use examples You can provide concrete examples of valid tool inputs to help Claude understand how to use your tools more effectively. This is particularly useful for complex tools with nested objects, optional parameters, or format-sensitive inputs. ### Basic usage Add an optional `input_examples` field to your tool definition with an array of example input objects. Each example must be valid according to the tool's `input_schema`: ```bash CLI ant messages create <<'YAML' model: claude-opus-4-7 max_tokens: 1024 tools: - name: get_weather description: Get the current weather in a given location input_schema: type: object properties: location: type: string description: The city and state, e.g. San Francisco, CA unit: type: string enum: [celsius, fahrenheit] description: The unit of temperature required: [location] input_examples: - location: San Francisco, CA unit: fahrenheit - location: Tokyo, Japan unit: celsius - location: New York, NY # 'unit' is optional messages: - role: user content: What's the weather like in San Francisco? YAML ``` ```python Python import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-4-7", max_tokens=1024, tools=[ { "name": "get_weather", "description": "Get the current weather in a given location", "input_schema": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA", }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "The unit of temperature", }, }, "required": ["location"], }, "input_examples": [ {"location": "San Francisco, CA", "unit": "fahrenheit"}, {"location": "Tokyo, Japan", "unit": "celsius"}, { "location": "New York, NY" # 'unit' is optional }, ], } ], messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}], ) print(response) ``` ```typescript TypeScript hidelines={1..4} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const response = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 1024, tools: [ { name: "get_weather", description: "Get the current weather in a given location", input_schema: { type: "object", properties: { location: { type: "string", description: "The city and state, e.g. San Francisco, CA" }, unit: { type: "string", enum: ["celsius", "fahrenheit"], description: "The unit of temperature" } }, required: ["location"] }, input_examples: [ { location: "San Francisco, CA", unit: "fahrenheit" }, { location: "Tokyo, Japan", unit: "celsius" }, { location: "New York, NY" // Demonstrates that 'unit' is optional } ] } ], messages: [{ role: "user", content: "What's the weather like in San Francisco?" }] }); console.log(response); ``` ```csharp C# hidelines={1..7} using System; using System.Collections.Generic; using System.Text.Json; using System.Threading.Tasks; using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 1024, Tools = [ new ToolUnion(new Tool() { Name = "get_weather", Description = "Get the current weather in a given location", InputSchema = new InputSchema() { Properties = new Dictionary { ["location"] = JsonSerializer.SerializeToElement(new { type = "string", description = "The city and state, e.g. San Francisco, CA" }), ["unit"] = JsonSerializer.SerializeToElement(new { type = "string", @enum = new[] { "celsius", "fahrenheit" }, description = "The unit of temperature" }), }, Required = ["location"], }, InputExamples = [ new Dictionary() { { "location", JsonSerializer.SerializeToElement("San Francisco, CA") }, { "unit", JsonSerializer.SerializeToElement("fahrenheit") }, }, new Dictionary() { { "location", JsonSerializer.SerializeToElement("Tokyo, Japan") }, { "unit", JsonSerializer.SerializeToElement("celsius") }, }, new Dictionary() { { "location", JsonSerializer.SerializeToElement("New York, NY") }, }, ], }), ], Messages = [ new() { Role = Role.User, Content = "What's the weather like in San Francisco?" } ] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 1024, Tools: []anthropic.ToolUnionParam{ {OfTool: &anthropic.ToolParam{ Name: "get_weather", Description: anthropic.String("Get the current weather in a given location"), InputSchema: anthropic.ToolInputSchemaParam{ Properties: map[string]any{ "location": map[string]any{ "type": "string", "description": "The city and state, e.g. San Francisco, CA", }, "unit": map[string]any{ "type": "string", "enum": []string{"celsius", "fahrenheit"}, "description": "The unit of temperature", }, }, Required: []string{"location"}, }, InputExamples: []map[string]any{ { "location": "San Francisco, CA", "unit": "fahrenheit", }, { "location": "Tokyo, Japan", "unit": "celsius", }, { "location": "New York, NY", // Demonstrates that 'unit' is optional }, }, }}, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather like in San Francisco?")), }, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```java Java hidelines={1..6,9} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.core.JsonValue; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.Model; import com.anthropic.models.messages.Tool; import com.anthropic.models.messages.Tool.InputSchema; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(1024L) .addTool(Tool.builder() .name("get_weather") .description("Get the current weather in a given location") .inputSchema(InputSchema.builder() .properties(JsonValue.from(Map.of( "location", Map.of( "type", "string", "description", "The city and state, e.g. San Francisco, CA" ), "unit", Map.of( "type", "string", "enum", List.of("celsius", "fahrenheit"), "description", "The unit of temperature" ) ))) .required(List.of("location")) .build()) .putAdditionalProperty("input_examples", JsonValue.from(List.of( Map.of( "location", "San Francisco, CA", "unit", "fahrenheit" ), Map.of( "location", "Tokyo, Japan", "unit", "celsius" ), Map.of( "location", "New York, NY" ) ))) .build()) .addUserMessage("What's the weather like in San Francisco?") .build(); Message response = client.messages().create(params); IO.println(response); } ``` ```php PHP messages->create( maxTokens: 1024, messages: [ ['role' => 'user', 'content' => "What's the weather like in San Francisco?"] ], model: 'claude-opus-4-7', tools: [ [ 'name' => 'get_weather', 'description' => 'Get the current weather in a given location', 'input_schema' => [ 'type' => 'object', 'properties' => [ 'location' => [ 'type' => 'string', 'description' => 'The city and state, e.g. San Francisco, CA' ], 'unit' => [ 'type' => 'string', 'enum' => ['celsius', 'fahrenheit'], 'description' => 'The unit of temperature' ] ], 'required' => ['location'] ], 'input_examples' => [ [ 'location' => 'San Francisco, CA', 'unit' => 'fahrenheit' ], [ 'location' => 'Tokyo, Japan', 'unit' => 'celsius' ], [ 'location' => 'New York, NY' ] ] ] ], ); ``` ```ruby Ruby require "anthropic" client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-7", max_tokens: 1024, tools: [ { name: "get_weather", description: "Get the current weather in a given location", input_schema: { type: "object", properties: { location: { type: "string", description: "The city and state, e.g. San Francisco, CA" }, unit: { type: "string", enum: ["celsius", "fahrenheit"], description: "The unit of temperature" } }, required: ["location"] }, input_examples: [ { location: "San Francisco, CA", unit: "fahrenheit" }, { location: "Tokyo, Japan", unit: "celsius" }, { location: "New York, NY" } ] } ], messages: [ { role: "user", content: "What's the weather like in San Francisco?" } ] ) puts message ``` Examples are included in the prompt alongside your tool schema, showing Claude concrete patterns for well-formed tool calls. This helps Claude understand when to include optional parameters, what formats to use, and how to structure complex inputs. ### Requirements and limitations - **Schema validation** - Each example must be valid according to the tool's `input_schema`. Invalid examples return a 400 error - **Not supported for server-side tools** - Input examples work on user-defined and Anthropic-schema client tools, but not on server tools like web search or code execution - **Token cost** - Examples add to prompt tokens: ~20-50 tokens for simple examples, ~100-200 tokens for complex nested objects ## Controlling Claude's output ### Forcing tool use In some cases, you may want Claude to use a specific tool to answer the user's question, even if Claude would otherwise answer directly without calling a tool. You can do this by specifying the tool in the `tool_choice` field like so: ```text tool_choice = {"type": "tool", "name": "get_weather"} ``` When working with the tool_choice parameter, there are four possible options: - `auto` allows Claude to decide whether to call any provided tools or not. This is the default value when `tools` are provided. - `any` tells Claude that it must use one of the provided tools, but doesn't force a particular tool. - `tool` forces Claude to always use a particular tool. - `none` prevents Claude from using any tools. This is the default value when no `tools` are provided. When using [prompt caching](/docs/en/build-with-claude/prompt-caching#what-invalidates-the-cache), changes to the `tool_choice` parameter will invalidate cached message blocks. Tool definitions and system prompts remain cached, but message content must be reprocessed. This diagram illustrates how each option works: ![Diagram showing the four tool_choice options: auto, any, tool, and none](/docs/images/tool_choice.png) Note that when you have `tool_choice` as `any` or `tool`, the API prefills the assistant message to force a tool to be used. This means that the models will not emit a natural language response or explanation before `tool_use` content blocks, even if explicitly asked to do so. When using [extended thinking](/docs/en/build-with-claude/extended-thinking) with tool use, `tool_choice: {"type": "any"}` and `tool_choice: {"type": "tool", "name": "..."}` are not supported and will result in an error. Only `tool_choice: {"type": "auto"}` (the default) and `tool_choice: {"type": "none"}` are compatible with extended thinking. [Claude Mythos Preview](https://anthropic.com/glasswing) does not support forced tool use. Requests with `tool_choice: {"type": "any"}` or `tool_choice: {"type": "tool", "name": "..."}` return a 400 error on this model. Use `tool_choice: {"type": "auto"}` (the default) or `tool_choice: {"type": "none"}` and rely on prompting to influence tool selection. Testing has shown that this should not reduce performance. If you would like the model to provide natural language context or explanations while still requesting that the model use a specific tool, you can use `{"type": "auto"}` for `tool_choice` (the default) and add explicit instructions in a `user` message. For example: `What's the weather like in London? Use the get_weather tool in your response.` **Guaranteed tool calls with strict tools** Combine `tool_choice: {"type": "any"}` with [strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use) to guarantee both that one of your tools will be called AND that the tool inputs strictly follow your schema. Set `strict: true` on your tool definitions to enable schema validation. ### Model responses with tools When using tools, Claude will often comment on what it's doing or respond naturally to the user before invoking tools. For example, given the prompt "What's the weather like in San Francisco right now, and what time is it there?", Claude might respond with: ```json JSON { "role": "assistant", "content": [ { "type": "text", "text": "I'll help you check the current weather and time in San Francisco." }, { "type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "get_weather", "input": { "location": "San Francisco, CA" } } ] } ``` This natural response style helps users understand what Claude is doing and creates a more conversational interaction. You can guide the style and content of these responses through your system prompts and by providing `` in your prompts. It's important to note that Claude may use various phrasings and approaches when explaining its actions. Your code should treat these responses like any other assistant-generated text, and not rely on specific formatting conventions. ## Next steps Parse tool_use blocks and format tool_result responses. Let the SDK handle the agentic loop automatically. Directory of Anthropic-provided tools and optional properties. --- # Handle tool calls URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls # Handle tool calls Parse tool_use blocks, format tool_result responses, and handle errors with is_error. --- This page covers the tool-call lifecycle: reading `tool_use` blocks from Claude's response, formatting `tool_result` blocks in your reply, and signaling errors. For the SDK abstraction that handles this automatically, see [Tool Runner](/docs/en/agents-and-tools/tool-use/tool-runner). **Simpler with Tool Runner**: The manual tool handling described on this page is automatically managed by [Tool Runner](/docs/en/agents-and-tools/tool-use/tool-runner). Use this page when you need custom control over tool execution. Claude's response differs based on whether it uses a [client or server tool](/docs/en/agents-and-tools/tool-use/overview#how-tool-use-works). ## Handling results from client tools The response will have a `stop_reason` of `tool_use` and one or more `tool_use` content blocks that include: - `id`: A unique identifier for this particular tool use block. This will be used to match up the tool results later. - `name`: The name of the tool being used. - `input`: An object containing the input being passed to the tool, conforming to the tool's `input_schema`.

```json JSON { "id": "msg_01Aq9w938a90dw8q", "model": "claude-opus-4-7", "stop_reason": "tool_use", "role": "assistant", "content": [ { "type": "text", "text": "I'll check the current weather in San Francisco for you." }, { "type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "get_weather", "input": { "location": "San Francisco, CA", "unit": "celsius" } } ] } ```

When you receive a tool use response for a client tool, you should: 1. Extract the `name`, `id`, and `input` from the `tool_use` block. 2. Run the actual tool in your codebase corresponding to that tool name, passing in the tool `input`. 3. Continue the conversation by sending a new message with the `role` of `user`, and a `content` block containing the `tool_result` type and the following information: - `tool_use_id`: The `id` of the tool use request this is a result for. - `content` (optional): The result of the tool, as a string (for example, `"content": "15 degrees"`), a list of nested content blocks (for example, `"content": [{"type": "text", "text": "15 degrees"}]`), or a list of document blocks (for example, `"content": [{"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}}]`). These content blocks can use the `text`, `image`, or `document` types. - `is_error` (optional): Set to `true` if the tool execution resulted in an error. **Important formatting requirements**: - Tool result blocks must immediately follow their corresponding tool use blocks in the message history. You cannot include any messages between the assistant's tool use message and the user's tool result message. - In the user message containing tool results, the tool_result blocks must come FIRST in the content array. Any text must come AFTER all tool results. For example, this will cause a 400 error: ```json { "role": "user", "content": [ { "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ } ] } ``` This is correct: ```json { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }, { "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result ] } ``` If you receive an error like "tool_use ids were found without tool_result blocks immediately after", check that your tool results are formatted correctly.

```json JSON { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "15 degrees" } ] } ```

```json JSON { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": [ { "type": "text", "text": "15 degrees" }, { "type": "image", "source": { "type": "base64", "media_type": "image/jpeg", "data": "/9j/4AAQSkZJRg..." } } ] } ] } ```

```json JSON { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9" } ] } ```

```json JSON { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": [ { "type": "text", "text": "The weather is" }, { "type": "document", "source": { "type": "text", "media_type": "text/plain", "data": "15 degrees" } } ] } ] } ```

After receiving the tool result, Claude will use that information to continue generating a response to the original user prompt. ## Handling results from server tools Claude executes the tool internally and incorporates the results directly into its response without requiring additional user interaction. **Differences from other APIs** Unlike APIs that separate tool use or use special roles like `tool` or `function`, the Claude API integrates tools directly into the `user` and `assistant` message structure. Messages contain arrays of `text`, `image`, `tool_use`, and `tool_result` blocks. `user` messages include client content and `tool_result`, while `assistant` messages contain AI-generated content and `tool_use`. ## Handling errors with is_error There are a few different types of errors that can occur when using tools with Claude:

If the tool itself throws an error during execution (for example, a network error when fetching weather data), you can return the error message in the `content` along with `"is_error": true`: ```json JSON { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "ConnectionError: the weather service API is not available (HTTP 500)", "is_error": true } ] } ``` Claude will then incorporate this error into its response to the user. For example: "I'm sorry, I was unable to retrieve the current weather because the weather service API is not available. Please try again later." Write instructive error messages. Instead of generic errors like `"failed"`, include what went wrong and what Claude should try next, e.g., `"Rate limit exceeded. Retry after 60 seconds."` This gives Claude the context it needs to recover or adapt without guessing.

If Claude's attempted use of a tool is invalid (for example, missing required parameters), it usually means that there wasn't enough information for Claude to use the tool correctly. Your best bet during development is to try the request again with more-detailed `description` values in your tool definitions. However, you can also continue the conversation forward with a `tool_result` that indicates the error, and Claude will try to use the tool again with the missing information filled in: ```json JSON { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "Error: Missing required 'location' parameter", "is_error": true } ] } ``` If a tool request is invalid or missing parameters, Claude will retry 2-3 times with corrections before apologizing to the user. To eliminate invalid tool calls entirely, use [strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use) with `strict: true` on your tool definitions. This guarantees that tool inputs will always match your schema exactly, preventing missing parameters and type mismatches.

When server tools encounter errors (for example, network issues with Web Search), Claude will transparently handle these errors and attempt to provide an alternative response or explanation to the user. Unlike client tools, you do not need to handle `is_error` results for server tools. For web search specifically, possible error codes include: - `too_many_requests`: Rate limit exceeded - `invalid_input`: Invalid search query parameter - `max_uses_exceeded`: Maximum web search tool uses exceeded - `query_too_long`: Query exceeds maximum length - `unavailable`: An internal error occurred

## Next steps - For running multiple tools in one turn, see [Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use). - For the SDK abstraction that automates this loop, see [Tool Runner](/docs/en/agents-and-tools/tool-use/tool-runner). - For the full tool-use workflow, see [Define tools](/docs/en/agents-and-tools/tool-use/define-tools). --- # How tool use works URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works # How tool use works Understand the tool use loop, where tools execute, and when to use tools instead of prose. --- This page explains the concepts behind tool use: where tools run, how the agentic loop works, and when tool use is the right approach. For hands-on guidance, start with the [tutorial](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent) or the [implementation guide](/docs/en/agents-and-tools/tool-use/define-tools). ## The tool-use contract Tool use is a contract between your application and the model. You specify what operations are available and what shape their inputs and outputs take; Claude decides when and how to call them. The model never executes anything on its own. It emits a structured request, your code (or Anthropic's servers) runs the operation, and the result flows back into the conversation. This contract makes the model behave less like a text generator and more like a function you call. Engineers with classical API experience can integrate tool use the same way they would any other typed interface: define the schema, handle the callback, return a result. The difference is that the caller on the other side is a language model choosing which function to invoke based on the conversation. ## Where tools run The primary axis along which tools differ is where the code executes. Every tool falls into one of three buckets, and the bucket determines what your application is responsible for. ### User-defined tools (client-executed) You write the schema, you execute the code, you return the results. This is the main event: the vast majority of tool-use traffic is user-defined tools calling into application-specific logic. When Claude decides to use one of your tools, the API response contains a `tool_use` block with the tool name and a JSON object of arguments. Your application extracts those arguments, runs the operation (a database query, an HTTP call, a file write, whatever the tool does), and sends the output back in a `tool_result` block on the next request. Claude never sees your implementation; it only sees the schema you provided and the result you returned. ### Anthropic-schema tools (client-executed) For a handful of common operations (running shell commands, editing files, controlling a browser, managing scratchpad memory), Anthropic publishes the tool schema and your application handles execution. The tools in this category are `bash`, `text_editor`, `computer`, and `memory`. The execution model is identical to user-defined tools: the response contains a `tool_use` block, your code runs the operation, and you send back a `tool_result`. The reason to use an Anthropic-schema tool instead of defining your own equivalent is that these schemas are trained-in. Claude has been optimized on thousands of successful trajectories that use these exact tool signatures, so it calls them more reliably and recovers from errors more gracefully than it would with a custom tool that does the same thing. The schema is the interface the model already expects. ### Server-executed tools For `web_search`, `web_fetch`, `code_execution`, and `tool_search`, Anthropic runs the code. You enable the tool in your request and the server handles everything else. You never construct a `tool_result` block for these tools because the server-side loop executes the operation and feeds the output back to the model before the response reaches you. The response you receive contains `server_tool_use` blocks showing what ran and what came back, but by the time you see them, execution is already complete. Your application's job is to enable the tool and read the final answer, not to participate in the execution loop. ## The agentic loop (client tools) Client-executed tools (both user-defined and Anthropic-schema) require your application to drive a loop. The model can't run your code, so every tool call is a round trip: the model asks, you execute, you report back, the model continues. The canonical shape is a `while` loop keyed on `stop_reason`: 1. Send a request with your `tools` array and the user message. 2. Claude responds with `stop_reason: "tool_use"` and one or more `tool_use` blocks. 3. Execute each tool. Format the outputs as `tool_result` blocks. 4. Send a new request containing the original messages, the assistant's response, and a user message with the `tool_result` blocks. 5. Repeat from step 2 while `stop_reason` is `"tool_use"`. In practice this reads as: while `stop_reason == "tool_use"`, execute the tools and continue the conversation. The loop exits on any other stop reason (`"end_turn"`, `"max_tokens"`, `"stop_sequence"`, or `"refusal"`), which means Claude has either produced a final answer or stopped for another reason that your application should handle. For the mechanics of building requests, handling parallel tool calls, and formatting results, see [Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls). ## The server-side loop Server-executed tools run their own loop inside Anthropic's infrastructure. A single request from your application might trigger several web searches or code executions before a response comes back. The model searches, reads results, decides to search again, and iterates until it has what it needs, all without your application participating. This internal loop has an iteration limit. If the model is still iterating when it hits the cap, the response comes back with `stop_reason: "pause_turn"` instead of `"end_turn"`. A paused turn means the work isn't finished; re-send the conversation (including the paused response) to let the model continue where it left off. See [Server tools](/docs/en/agents-and-tools/tool-use/server-tools) for the continuation pattern. ## When to use tools (and when not to) Tool use fits when the task requires something the model can't do from text alone: - **Actions with side effects.** Sending an email, writing a file, updating a record. The model can describe these actions, but only a tool can perform them. - **Fresh or external data.** Current prices, today's weather, the contents of a database. Anything outside the training data or specific to your system needs a tool to fetch it. - **Structured, guaranteed-shape outputs.** When you need a JSON object with specific fields rather than prose that happens to contain the information, a tool schema enforces the shape. - **Calling into existing systems.** Databases, internal APIs, file systems. Tool use is the bridge between natural-language requests and the systems that fulfill them. The tell that you should be using tools: if you're writing a regex to extract a decision from model output, that decision should have been a tool call. Parsing free-form text to recover structured intent is a sign the structure belongs in the schema. Tool use doesn't fit when: - The model can answer from training alone. Summarization, translation, and general-knowledge questions don't need a tool round trip. - The interaction is one-shot Q&A with no side effects. If there's nothing to execute, there's nothing for a tool to do. - Tool-calling latency would dominate a trivial response. Every tool call is at least one extra round trip; for lightweight tasks the overhead can exceed the work. ## Choosing between approaches | Approach | When to use it | What to expect | Learn more | | --- | --- | --- | --- | | User-defined client tools | Custom business logic, internal APIs, proprietary data | You handle execution and the agentic loop | [Define tools](/docs/en/agents-and-tools/tool-use/define-tools) | | Anthropic-schema client tools | Standard dev operations (bash, file editing, browser control) | You handle execution; Claude calls the tool reliably because the schema is trained-in | [Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference) | | Server-executed tools | Web search, code sandbox, web fetch | Anthropic handles execution; you get results directly | [Server tools](/docs/en/agents-and-tools/tool-use/server-tools) | ## Next steps Build an agent step by step from a single tool call to production. Schema specification, descriptions, and tool_choice. Directory of Anthropic-provided tools. --- # Memory tool URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool # Memory tool --- The memory tool enables Claude to store and retrieve information across conversations through a memory file directory. Claude can create, read, update, and delete files that persist between sessions, allowing it to build knowledge over time without keeping everything in the context window. This is the key primitive for just-in-time context retrieval: rather than loading all relevant information upfront, agents store what they learn in memory and pull it back on demand. This keeps the active context focused on what's currently relevant, critical for long-running workflows where loading everything at once would overwhelm the context window. See [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) for the broader pattern. The memory tool operates client-side: you control where and how the data is stored through your own infrastructure. Reach out through the [feedback form](https://forms.gle/YXC2EKGMhjN1c4L88) to share your feedback on this feature. This feature is eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned. ## Use cases - Maintain project context across multiple agent executions - Learn from past interactions, decisions, and feedback - Build knowledge bases over time - Enable cross-conversation learning where Claude improves at recurring workflows ## How it works When enabled, Claude automatically checks its memory directory before starting tasks. Claude can create, read, update, and delete files in the `/memories` directory to store what it learns while working, then reference those memories in future conversations to handle similar tasks more effectively or pick up where it left off. Since this is a client-side tool, Claude makes tool calls to perform memory operations, and your application executes those operations locally. This gives you complete control over where and how the memory is stored. For security, you should restrict all memory operations to the `/memories` directory. ### Example: How memory tool calls work When you ask Claude to help with a task, Claude automatically checks its memory directory first. Here's what a typical interaction looks like: **1. User request:** ```text "Help me respond to this customer service ticket." ``` **2. Claude checks the memory directory:** ```text "I'll help you respond to the customer service ticket. Let me check my memory for any previous context." ``` Claude calls the memory tool: ```json { "type": "tool_use", "id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4", "name": "memory", "input": { "command": "view", "path": "/memories" } } ``` **3. Your application returns the directory contents:** ```json { "type": "tool_result", "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4", "content": "Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:\n4.0K\t/memories\n1.5K\t/memories/customer_service_guidelines.xml\n2.0K\t/memories/refund_policies.xml" } ``` **4. Claude reads relevant files:** ```json { "type": "tool_use", "id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5", "name": "memory", "input": { "command": "view", "path": "/memories/customer_service_guidelines.xml" } } ``` **5. Your application returns the file contents:** ```json { "type": "tool_result", "tool_use_id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5", "content": "Here's the content of /memories/customer_service_guidelines.xml with line numbers:\n 1\t\n 2\t\n 3\t- Always address customers by their first name\n 4\t- Use empathetic language\n..." } ``` **6. Claude uses the memory to help:** ```text "Based on your customer service guidelines, I can help you craft a response. Please share the ticket details..." ``` For model support, see the [Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference). ## Getting started To use the memory tool: 1. Add the memory tool to your request 2. Implement client-side handlers for memory operations To handle memory tool operations in your application, you need to implement handlers for each memory command. The SDKs provide memory tool helpers that handle the tool interface. You can subclass `BetaAbstractMemoryTool` (Python) or use `betaMemoryTool` (TypeScript) to implement your own memory backend (file-based, database, cloud storage, encrypted files, etc.). For working examples, see: - Python: [examples/memory/basic.py](https://github.com/anthropics/anthropic-sdk-python/blob/main/examples/memory/basic.py) - TypeScript: [examples/tools-helpers-memory.ts](https://github.com/anthropics/anthropic-sdk-typescript/blob/main/examples/tools-helpers-memory.ts) ## Basic usage ```bash cURL curl https://api.anthropic.com/v1/messages \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --data '{ "model": "claude-opus-4-7", "max_tokens": 2048, "messages": [ { "role": "user", "content": "I'\''m working on a Python web scraper that keeps crashing with a timeout error. Here'\''s the problematic function:\n\n```python\ndef fetch_page(url, retries=3):\n for i in range(retries):\n try:\n response = requests.get(url, timeout=5)\n return response.text\n except requests.exceptions.Timeout:\n if i == retries - 1:\n raise\n time.sleep(1)\n```\n\nPlease help me debug this." } ], "tools": [{ "type": "memory_20250818", "name": "memory" }] }' ``` ````bash CLI ant messages create <<'YAML' model: claude-opus-4-7 max_tokens: 2048 tools: - type: memory_20250818 name: memory messages: - role: user content: | I'm working on a Python web scraper that keeps crashing with a timeout error. Here's the problematic function: ```python def fetch_page(url, retries=3): for i in range(retries): try: response = requests.get(url, timeout=5) return response.text except requests.exceptions.Timeout: if i == retries - 1: raise time.sleep(1) ``` Please help me debug this. YAML ```` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() message = client.messages.create( model="claude-opus-4-7", max_tokens=2048, messages=[ { "role": "user", "content": "I'm working on a Python web scraper that keeps crashing with a timeout error. Here's the problematic function:\n\n```python\ndef fetch_page(url, retries=3):\n for i in range(retries):\n try:\n response = requests.get(url, timeout=5)\n return response.text\n except requests.exceptions.Timeout:\n if i == retries - 1:\n raise\n time.sleep(1)\n```\n\nPlease help me debug this.", } ], tools=[{"type": "memory_20250818", "name": "memory"}], ) print(message) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }); const message = await anthropic.messages.create({ model: "claude-opus-4-7", max_tokens: 2048, messages: [ { role: "user", content: "I'm working on a Python web scraper that keeps crashing with a timeout error. Here's the problematic function:\n\n```python\ndef fetch_page(url, retries=3):\n for i in range(retries):\n try:\n response = requests.get(url, timeout=5)\n return response.text\n except requests.exceptions.Timeout:\n if i == retries - 1:\n raise\n time.sleep(1)\n```\n\nPlease help me debug this." } ], tools: [{ type: "memory_20250818", name: "memory" }] }); console.log(message); ``` ```csharp C# using System; using System.Threading.Tasks; using Anthropic; using Anthropic.Models.Messages; public class Program { public static async Task Main(string[] args) { AnthropicClient client = new() { ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY") }; var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 2048, Messages = [ new() { Role = Role.User, Content = "I'm working on a Python web scraper that keeps crashing with a timeout error. Here's the problematic function:\n\n```python\ndef fetch_page(url, retries=3):\n for i in range(retries):\n try:\n response = requests.get(url, timeout=5)\n return response.text\n except requests.exceptions.Timeout:\n if i == retries - 1:\n raise\n time.sleep(1)\n```\n\nPlease help me debug this." } ], Tools = [new ToolUnion(new MemoryTool20250818())] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); } } ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 2048, Messages: []anthropic.BetaMessageParam{ anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("I'm working on a Python web scraper that keeps crashing with a timeout error. Here's the problematic function:\n\n```python\ndef fetch_page(url, retries=3):\n for i in range(retries):\n try:\n response = requests.get(url, timeout=5)\n return response.text\n except requests.exceptions.Timeout:\n if i == retries - 1:\n raise\n time.sleep(1)\n```\n\nPlease help me debug this.")), }, Tools: []anthropic.BetaToolUnionParam{ {OfMemoryTool20250818: &anthropic.BetaMemoryTool20250818Param{}}, }, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```java Java hidelines={1..2,4..9,-2..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.MemoryTool20250818; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; public class MemoryToolExample { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(2048L) .addUserMessage("I'm working on a Python web scraper that keeps crashing with a timeout error. Here's the problematic function:\n\n```python\ndef fetch_page(url, retries=3):\n for i in range(retries):\n try:\n response = requests.get(url, timeout=5)\n return response.text\n except requests.exceptions.Timeout:\n if i == retries - 1:\n raise\n time.sleep(1)\n```\n\nPlease help me debug this.") .addTool(MemoryTool20250818.builder().build()) .build(); Message response = client.messages().create(params); System.out.println(response); } } ``` ```php PHP hidelines={1..4} messages->create( maxTokens: 2048, messages: [ [ 'role' => 'user', 'content' => "I'm working on a Python web scraper that keeps crashing with a timeout error. Here's the problematic function:\n\n```python\ndef fetch_page(url, retries=3):\n for i in range(retries):\n try:\n response = requests.get(url, timeout=5)\n return response.text\n except requests.exceptions.Timeout:\n if i == retries - 1:\n raise\n time.sleep(1)\n```\n\nPlease help me debug this.", ], ], model: 'claude-opus-4-7', tools: [ [ 'type' => 'memory_20250818', 'name' => 'memory', ], ], ); ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-7", max_tokens: 2048, messages: [ { role: "user", content: "I'm working on a Python web scraper that keeps crashing with a timeout error. Here's the problematic function:\n\n```python\ndef fetch_page(url, retries=3):\n for i in range(retries):\n try:\n response = requests.get(url, timeout=5)\n return response.text\n except requests.exceptions.Timeout:\n if i == retries - 1:\n raise\n time.sleep(1)\n```\n\nPlease help me debug this." } ], tools: [ { type: "memory_20250818", name: "memory" } ] ) puts message ``` ## Tool commands Your client-side implementation needs to handle these memory tool commands. While these specifications describe the recommended behaviors that Claude is most familiar with, you can modify your implementation and return strings as needed for your use case. ### view Shows directory contents or file contents with optional line ranges: ```json { "command": "view", "path": "/memories", "view_range": [1, 10] // Optional: view specific lines } ``` #### Return values **For directories:** Return a listing that shows files and directories with their sizes: ```text Here're the files and directories up to 2 levels deep in {path}, excluding hidden items and node_modules: {size} {path} {size} {path}/{filename1} {size} {path}/{filename2} ``` - Lists files up to 2 levels deep - Shows human-readable sizes (for example, `5.5K`, `1.2M`) - Excludes hidden items (files starting with `.`) and `node_modules` - Uses tab character between size and path **For files:** Return file contents with a header and line numbers: ```text Here's the content of {path} with line numbers: {line_numbers}{tab}{content} ``` Line number formatting: - **Width**: 6 characters, right-aligned with space padding - **Separator**: Tab character between line number and content - **Indexing**: 1-indexed (first line is line 1) - **Line limit**: Files with more than 999,999 lines should return an error: `"File {path} exceeds maximum line limit of 999,999 lines."` **Example output:** ```text Here's the content of /memories/notes.txt with line numbers: 1 Hello World 2 This is line two 10 Line ten 100 Line one hundred ``` #### Error handling - **File/directory does not exist**: `"The path {path} does not exist. Please provide a valid path."` ### create Create a new file: ```json { "command": "create", "path": "/memories/notes.txt", "file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n" } ``` #### Return values - **Success**: `"File created successfully at: {path}"` #### Error handling - **File already exists**: `"Error: File {path} already exists"` ### str_replace Replace text in a file: ```json { "command": "str_replace", "path": "/memories/preferences.txt", "old_str": "Favorite color: blue", "new_str": "Favorite color: green" } ``` #### Return values - **Success**: `"The memory file has been edited."` followed by a snippet of the edited file with line numbers #### Error handling - **File does not exist**: `"Error: The path {path} does not exist. Please provide a valid path."` - **Text not found**: ``"No replacement was performed, old_str `{old_str}` did not appear verbatim in {path}."`` - **Duplicate text**: When `old_str` appears multiple times, return: ``"No replacement was performed. Multiple occurrences of old_str `{old_str}` in lines: {line_numbers}. Please ensure it is unique"`` #### Directory handling If the path is a directory, return a "file does not exist" error. ### insert Insert text at a specific line: ```json { "command": "insert", "path": "/memories/todo.txt", "insert_line": 2, "insert_text": "- Review memory tool documentation\n" } ``` #### Return values - **Success**: `"The file {path} has been edited."` #### Error handling - **File does not exist**: `"Error: The path {path} does not exist"` - **Invalid line number**: ``"Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]"`` #### Directory handling If the path is a directory, return a "file does not exist" error. ### delete Delete a file or directory: ```json { "command": "delete", "path": "/memories/old_file.txt" } ``` #### Return values - **Success**: `"Successfully deleted {path}"` #### Error handling - **File/directory does not exist**: `"Error: The path {path} does not exist"` #### Directory handling Deletes the directory and all its contents recursively. ### rename Rename or move a file/directory: ```json { "command": "rename", "old_path": "/memories/draft.txt", "new_path": "/memories/final.txt" } ``` #### Return values - **Success**: `"Successfully renamed {old_path} to {new_path}"` #### Error handling - **Source does not exist**: `"Error: The path {old_path} does not exist"` - **Destination already exists**: Return an error (do not overwrite): `"Error: The destination {new_path} already exists"` #### Directory handling Renames the directory. ## Prompting guidance This instruction is automatically included in the system prompt when the memory tool is enabled: ```text IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE. MEMORY PROTOCOL: 1. Use the `view` command of your `memory` tool to check for earlier progress. 2. ... (work on the task) ... - As you make progress, record status / progress / thoughts etc in your memory. ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory. ``` If you observe Claude creating cluttered memory files, you can include this instruction: > Note: when editing your memory folder, always try to keep its content up-to-date, coherent and organized. You can rename or delete files that are no longer relevant. Do not create new files unless necessary. You can also guide what Claude writes to memory. For example: "Only write down information relevant to \ in your memory system." ## Security considerations Here are important security concerns when implementing your memory store: ### Sensitive information Claude will usually refuse to write down sensitive information in memory files. However, you may want to implement stricter validation that strips out potentially sensitive information. ### File storage size Consider tracking memory file sizes and preventing files from growing too large. Consider adding a maximum number of characters the memory read command can return, and let Claude paginate through contents. ### Memory expiration Consider clearing out memory files periodically that haven't been accessed in an extended time. ### Path traversal protection Malicious path inputs could attempt to access files outside the `/memories` directory. Your implementation **MUST** validate all paths to prevent directory traversal attacks. Consider these safeguards: - Validate that all paths start with `/memories` - Resolve paths to their canonical form and verify they remain within the memory directory - Reject paths containing sequences like `../`, `..\\`, or other traversal patterns - Watch for URL-encoded traversal sequences (`%2e%2e%2f`) - Use your language's built-in path security utilities (for example, Python's `pathlib.Path.resolve()` and `relative_to()`) ## Error handling The memory tool uses similar error handling patterns to the [text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool#handle-errors). See the individual tool command sections above for detailed error messages and behaviors. Common errors include file not found, permission errors, invalid paths, and duplicate text matches. ## Context editing integration The memory tool pairs with context editing to manage long-running conversations. For details, see [Context editing](/docs/en/build-with-claude/context-editing). ## Using with Compaction The memory tool can also be paired with [compaction](/docs/en/build-with-claude/compaction), which provides server-side summarization of older conversation context. While context editing clears specific tool results on the client side, compaction automatically summarizes the entire conversation on the server side when it approaches the context window limit. For long-running agentic workflows, consider using both: compaction keeps the active context manageable without client-side bookkeeping, and memory persists important information across compaction boundaries so that nothing critical is lost in the summary. ## Multi-session software development pattern For long-running software projects that span multiple agent sessions, memory files need to be bootstrapped deliberately, not just written ad hoc as work progresses. The pattern below turns memory into a structured recovery mechanism, so each new session can pick up exactly where the last one left off. ### How it works 1. **Initializer session:** The first session sets up the memory artifacts before any substantive work begins. This includes a progress log (tracking what has been done and what comes next), a feature checklist (defining the scope of work), and a reference to any startup or initialization script the project needs. 2. **Subsequent sessions:** Each new session opens by reading those memory artifacts. This recovers the full state of the project in seconds, without needing to re-explore the codebase or retrace earlier decisions. 3. **End-of-session update:** Before a session ends, it updates the progress log with what was completed and what remains. This ensures the next session has an accurate starting point. ### Key principle Work on one feature at a time. Only mark a feature complete after end-to-end verification confirms it works, not just after the code is written. This keeps the progress log trustworthy and prevents scope creep from compounding across sessions. For a detailed case study of this pattern in practice, including the initializer script, progress file structure, and git-based recovery, see [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents). ## Next steps Directory of Anthropic-provided tools and their properties. Manage conversation length alongside memory. --- # Parallel tool use URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use # Parallel tool use Enable and format parallel tool calls, with message-history guidance and troubleshooting. --- This page covers parallel tool calls: when Claude calls multiple tools in one turn, how to format the message history so parallelism keeps working, and how to disable it. For the single-call flow, see [Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls). By default, Claude may use multiple tools to answer a user query. You can disable this behavior by: - Setting `disable_parallel_tool_use=true` when tool_choice type is `auto`, which ensures that Claude uses **at most one** tool - Setting `disable_parallel_tool_use=true` when tool_choice type is `any` or `tool`, which ensures that Claude uses **exactly one** tool ## Worked example **Simpler with Tool Runner**: The example below shows manual parallel tool handling. For most use cases, [Tool Runner](/docs/en/agents-and-tools/tool-use/tool-runner) automatically handles parallel tool execution with much less code. Here's a complete, runnable script to test and verify parallel tool calls are working correctly: ```python Python hidelines={1..9} #!/usr/bin/env python3 """Test script to verify parallel tool calls with the Claude API""" import os from anthropic import Anthropic # Initialize client client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY")) # Define tools tools = [ { "name": "get_weather", "description": "Get the current weather in a given location", "input_schema": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA", } }, "required": ["location"], }, }, { "name": "get_time", "description": "Get the current time in a given timezone", "input_schema": { "type": "object", "properties": { "timezone": { "type": "string", "description": "The timezone, e.g. America/New_York", } }, "required": ["timezone"], }, }, ] # Test conversation with parallel tool calls messages = [ { "role": "user", "content": "What's the weather in SF and NYC, and what time is it there?", } ] # Make initial request print("Requesting parallel tool calls...") response = client.messages.create( model="claude-opus-4-7", max_tokens=1024, messages=messages, tools=tools ) # Check for parallel tool calls tool_uses = [block for block in response.content if block.type == "tool_use"] print(f"\n✓ Claude made {len(tool_uses)} tool calls") if len(tool_uses) > 1: print("✓ Parallel tool calls detected!") for tool in tool_uses: print(f" - {tool.name}: {tool.input}") else: print("✗ No parallel tool calls detected") # Simulate tool execution and format results correctly tool_results = [] for tool_use in tool_uses: if tool_use.name == "get_weather": if "San Francisco" in str(tool_use.input): result = "San Francisco: 68°F, partly cloudy" else: result = "New York: 45°F, clear skies" else: # get_time if "Los_Angeles" in str(tool_use.input): result = "2:30 PM PST" else: result = "5:30 PM EST" tool_results.append( {"type": "tool_result", "tool_use_id": tool_use.id, "content": result} ) # Continue conversation with tool results messages.extend( [ {"role": "assistant", "content": response.content}, {"role": "user", "content": tool_results}, # All results in one message! ] ) # Get final response print("\nGetting final response...") final_response = client.messages.create( model="claude-opus-4-7", max_tokens=1024, messages=messages, tools=tools ) print(f"\nClaude's response:\n{final_response.content[0].text}") # Verify formatting print("\n--- Verification ---") print(f"✓ Tool results sent in single user message: {len(tool_results)} results") print("✓ No text before tool results in content array") print("✓ Conversation formatted correctly for future parallel tool use") ``` ```typescript TypeScript hidelines={1..4} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); // Define tools const tools: Anthropic.Tool[] = [ { name: "get_weather", description: "Get the current weather in a given location", input_schema: { type: "object" as const, properties: { location: { type: "string", description: "The city and state, e.g. San Francisco, CA" } }, required: ["location"] } }, { name: "get_time", description: "Get the current time in a given timezone", input_schema: { type: "object" as const, properties: { timezone: { type: "string", description: "The timezone, e.g. America/New_York" } }, required: ["timezone"] } } ]; async function testParallelTools() { // Make initial request console.log("Requesting parallel tool calls..."); const response = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 1024, messages: [ { role: "user", content: "What's the weather in SF and NYC, and what time is it there?" } ], tools: tools }); // Check for parallel tool calls const toolUses = response.content.filter((block) => block.type === "tool_use"); console.log(`\n✓ Claude made ${toolUses.length} tool calls`); if (toolUses.length > 1) { console.log("✓ Parallel tool calls detected!"); toolUses.forEach((tool) => { if (tool.type === "tool_use") { console.log(` - ${tool.name}: ${JSON.stringify(tool.input)}`); } }); } else { console.log("✗ No parallel tool calls detected"); } // Simulate tool execution and format results correctly const toolResults: Anthropic.ToolResultBlockParam[] = toolUses .filter((block): block is Anthropic.ToolUseBlock => block.type === "tool_use") .map((toolUse) => { const input = toolUse.input as Record; let result: string; if (toolUse.name === "get_weather") { result = input.location?.includes("San Francisco") ? "San Francisco: 68F, partly cloudy" : "New York: 45F, clear skies"; } else { result = input.timezone?.includes("Los_Angeles") ? "2:30 PM PST" : "5:30 PM EST"; } return { type: "tool_result" as const, tool_use_id: toolUse.id, content: result }; }); // Get final response with correct formatting console.log("\nGetting final response..."); const finalResponse = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 1024, messages: [ { role: "user", content: "What's the weather in SF and NYC, and what time is it there?" }, { role: "assistant", content: response.content }, { role: "user", content: toolResults } ], tools: tools }); for (const block of finalResponse.content) { if (block.type === "text") { console.log(`\nClaude's response:\n${block.text}`); } } // Verify formatting console.log("\n--- Verification ---"); console.log(`✓ Tool results sent in single user message: ${toolResults.length} results`); console.log("✓ No text before tool results in content array"); console.log("✓ Conversation formatted correctly for future parallel tool use"); } testParallelTools().catch(console.error); ``` ```csharp C# hidelines={1..12,-2..-1} using System; using System.Collections.Generic; using System.Linq; using System.Text.Json; using System.Threading.Tasks; using Anthropic; using Anthropic.Models.Messages; public class Program { public static async Task Main() { AnthropicClient client = new(); var tools = new List { new ToolUnion(new Tool() { Name = "get_weather", Description = "Get the current weather in a given location", InputSchema = new InputSchema() { Properties = new Dictionary { ["location"] = JsonSerializer.SerializeToElement(new { type = "string", description = "The city and state, e.g. San Francisco, CA" }), }, Required = ["location"], }, }), new ToolUnion(new Tool() { Name = "get_time", Description = "Get the current time in a given timezone", InputSchema = new InputSchema() { Properties = new Dictionary { ["timezone"] = JsonSerializer.SerializeToElement(new { type = "string", description = "The timezone, e.g. America/New_York" }), }, Required = ["timezone"], }, }), }; Console.WriteLine("Requesting parallel tool calls..."); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "What's the weather in SF and NYC, and what time is it there?" }], Tools = tools }; var response = await client.Messages.Create(parameters); var toolUses = new List(); foreach (var block in response.Content) { if (block.TryPickToolUse(out var toolUse)) { toolUses.Add(toolUse); } } Console.WriteLine($"\n\u2713 Claude made {toolUses.Count} tool calls"); if (toolUses.Count > 1) { Console.WriteLine("\u2713 Parallel tool calls detected!"); foreach (var tool in toolUses) { Console.WriteLine($" - {tool.Name}: {tool.Input}"); } } else { Console.WriteLine("\u2717 No parallel tool calls detected"); } var toolResults = new List(); foreach (var toolUse in toolUses) { string result; if (toolUse.Name == "get_weather") { result = toolUse.Input.ToString()!.Contains("San Francisco") ? "San Francisco: 68\u00b0F, partly cloudy" : "New York: 45\u00b0F, clear skies"; } else { result = toolUse.Input.ToString()!.Contains("Los_Angeles") ? "2:30 PM PST" : "5:30 PM EST"; } toolResults.Add(new ContentBlockParam(new ToolResultBlockParam() { ToolUseID = toolUse.ID, Content = result, })); } Console.WriteLine("\nGetting final response..."); var finalParameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 1024, Messages = [ new() { Role = Role.User, Content = "What's the weather in SF and NYC, and what time is it there?" }, new() { Role = Role.Assistant, Content = response.Content.Select(block => new ContentBlockParam(block.Json)).ToList() }, new() { Role = Role.User, Content = new MessageParamContent(toolResults) } ], Tools = tools }; var finalResponse = await client.Messages.Create(finalParameters); finalResponse.Content[0].TryPickText(out var text); Console.WriteLine($"\nClaude's response:\n{text?.Text}"); Console.WriteLine("\n--- Verification ---"); Console.WriteLine($"\u2713 Tool results sent in single user message: {toolResults.Count} results"); Console.WriteLine("\u2713 No text before tool results in content array"); Console.WriteLine("\u2713 Conversation formatted correctly for future parallel tool use"); } } ``` ```go Go hidelines={1..15,-1} package main import ( "context" "encoding/json" "fmt" "log" "strings" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() tools := []anthropic.ToolUnionParam{ {OfTool: &anthropic.ToolParam{ Name: "get_weather", Description: anthropic.String("Get the current weather in a given location"), InputSchema: anthropic.ToolInputSchemaParam{ Properties: map[string]any{ "location": map[string]any{ "type": "string", "description": "The city and state, e.g. San Francisco, CA", }, }, Required: []string{"location"}, }, }}, {OfTool: &anthropic.ToolParam{ Name: "get_time", Description: anthropic.String("Get the current time in a given timezone"), InputSchema: anthropic.ToolInputSchemaParam{ Properties: map[string]any{ "timezone": map[string]any{ "type": "string", "description": "The timezone, e.g. America/New_York", }, }, Required: []string{"timezone"}, }, }}, } fmt.Println("Requesting parallel tool calls...") response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in SF and NYC, and what time is it there?")), }, Tools: tools, }) if err != nil { log.Fatal(err) } // Find tool use blocks using type switch type toolUseInfo struct { ID string Name string Input json.RawMessage } var toolUses []toolUseInfo for _, block := range response.Content { switch variant := block.AsAny().(type) { case anthropic.ToolUseBlock: toolUses = append(toolUses, toolUseInfo{ ID: variant.ID, Name: variant.Name, Input: variant.Input, }) } } fmt.Printf("\n✓ Claude made %d tool calls\n", len(toolUses)) if len(toolUses) > 1 { fmt.Println("✓ Parallel tool calls detected!") for _, tool := range toolUses { fmt.Printf(" - %s: %s\n", tool.Name, string(tool.Input)) } } else { fmt.Println("✗ No parallel tool calls detected") } // Build tool results var toolResults []anthropic.ContentBlockParamUnion for _, toolUse := range toolUses { var result string inputStr := string(toolUse.Input) if toolUse.Name == "get_weather" { if strings.Contains(inputStr, "San Francisco") { result = "San Francisco: 68°F, partly cloudy" } else { result = "New York: 45°F, clear skies" } } else { if strings.Contains(inputStr, "Los_Angeles") { result = "2:30 PM PST" } else { result = "5:30 PM EST" } } toolResults = append(toolResults, anthropic.NewToolResultBlock(toolUse.ID, result, false)) } // Convert response content to param types for the assistant message var contentParams []anthropic.ContentBlockParamUnion for _, block := range response.Content { contentParams = append(contentParams, block.ToParam()) } fmt.Println("\nGetting final response...") finalResponse, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in SF and NYC, and what time is it there?")), anthropic.NewAssistantMessage(contentParams...), anthropic.NewUserMessage(toolResults...), }, Tools: tools, }) if err != nil { log.Fatal(err) } fmt.Printf("\nClaude's response:\n%s\n", finalResponse.Content[0].Text) fmt.Println("\n--- Verification ---") fmt.Printf("✓ Tool results sent in single user message: %d results\n", len(toolResults)) fmt.Println("✓ No text before tool results in content array") fmt.Println("✓ Conversation formatted correctly for future parallel tool use") } ``` ```java Java hidelines={1..17,-1} 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.MessageCreateParams; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.Model; 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.List; import java.util.ArrayList; import java.util.Map; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); Tool weatherTool = Tool.builder() .name("get_weather") .description("Get the current weather in a given location") .inputSchema(InputSchema.builder() .properties(JsonValue.from(Map.of( "location", Map.of( "type", "string", "description", "The city and state, e.g. San Francisco, CA" ) ))) .putAdditionalProperty("required", JsonValue.from(List.of("location"))) .build()) .build(); Tool timeTool = Tool.builder() .name("get_time") .description("Get the current time in a given timezone") .inputSchema(InputSchema.builder() .properties(JsonValue.from(Map.of( "timezone", Map.of( "type", "string", "description", "The timezone, e.g. America/New_York" ) ))) .putAdditionalProperty("required", JsonValue.from(List.of("timezone"))) .build()) .build(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(1024L) .addTool(weatherTool) .addTool(timeTool) .addUserMessage("What's the weather in SF and NYC, and what time is it there?") .build(); IO.println("Requesting parallel tool calls..."); Message response = client.messages().create(params); List toolUses = new ArrayList<>(); for (ContentBlock block : response.content()) { if (block.toolUse().isPresent()) { toolUses.add(block.toolUse().get()); } } IO.println("\n✓ Claude made " + toolUses.size() + " tool calls"); if (toolUses.size() > 1) { IO.println("✓ Parallel tool calls detected!"); for (ToolUseBlock tool : toolUses) { IO.println(" - " + tool.name() + ": " + tool._input()); } } else { IO.println("✗ No parallel tool calls detected"); } List toolResults = new ArrayList<>(); for (ToolUseBlock toolUse : toolUses) { String result; if (toolUse.name().equals("get_weather")) { String location = toolUse._input().toString(); result = location.contains("San Francisco") ? "San Francisco: 68°F, partly cloudy" : "New York: 45°F, clear skies"; } else { String timezone = toolUse._input().toString(); result = timezone.contains("Los_Angeles") ? "2:30 PM PST" : "5:30 PM EST"; } toolResults.add(ContentBlockParam.ofToolResult( ToolResultBlockParam.builder() .toolUseId(toolUse.id()) .content(result) .build() )); } IO.println("\nGetting final response..."); MessageCreateParams finalParams = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(1024L) .addTool(weatherTool) .addTool(timeTool) .addUserMessage("What's the weather in SF and NYC, and what time is it there?") .addMessage(response) .addUserMessageOfBlockParams(toolResults) .build(); Message finalResponse = client.messages().create(finalParams); finalResponse.content().stream() .flatMap(block -> block.text().stream()) .forEach(textBlock -> IO.println("\nClaude's response:\n" + textBlock.text())); IO.println("\n--- Verification ---"); IO.println("✓ Tool results sent in single user message: " + toolResults.size() + " results"); IO.println("✓ No text before tool results in content array"); IO.println("✓ Conversation formatted correctly for future parallel tool use"); } ``` ```php PHP hidelines={1..6} 'get_weather', 'description' => 'Get the current weather in a given location', 'input_schema' => [ 'type' => 'object', 'properties' => [ 'location' => [ 'type' => 'string', 'description' => 'The city and state, e.g. San Francisco, CA' ] ], 'required' => ['location'] ] ], [ 'name' => 'get_time', 'description' => 'Get the current time in a given timezone', 'input_schema' => [ 'type' => 'object', 'properties' => [ 'timezone' => [ 'type' => 'string', 'description' => 'The timezone, e.g. America/New_York' ] ], 'required' => ['timezone'] ] ] ]; echo "Requesting parallel tool calls...\n"; $response = $client->messages->create( maxTokens: 1024, messages: [ ['role' => 'user', 'content' => "What's the weather in SF and NYC, and what time is it there?"] ], model: 'claude-opus-4-7', tools: $tools, ); $toolUses = array_filter($response->content, fn($block) => $block->type === 'tool_use'); echo "\n✓ Claude made " . count($toolUses) . " tool calls\n"; if (count($toolUses) > 1) { echo "✓ Parallel tool calls detected!\n"; foreach ($toolUses as $tool) { echo " - {$tool->name}: " . json_encode($tool->input) . "\n"; } } else { echo "✗ No parallel tool calls detected\n"; } $toolResults = []; foreach ($toolUses as $toolUse) { if ($toolUse->name === 'get_weather') { $result = str_contains(json_encode($toolUse->input), 'San Francisco') ? 'San Francisco: 68°F, partly cloudy' : 'New York: 45°F, clear skies'; } else { $result = str_contains(json_encode($toolUse->input), 'Los_Angeles') ? '2:30 PM PST' : '5:30 PM EST'; } $toolResults[] = [ 'type' => 'tool_result', 'tool_use_id' => $toolUse->id, 'content' => $result ]; } echo "\nGetting final response...\n"; $finalResponse = $client->messages->create( maxTokens: 1024, messages: [ ['role' => 'user', 'content' => "What's the weather in SF and NYC, and what time is it there?"], ['role' => 'assistant', 'content' => $response->content], ['role' => 'user', 'content' => $toolResults] ], model: 'claude-opus-4-7', tools: $tools, ); echo "\nClaude's response:\n{$finalResponse->content[0]->text}\n"; echo "\n--- Verification ---\n"; echo "✓ Tool results sent in single user message: " . count($toolResults) . " results\n"; echo "✓ No text before tool results in content array\n"; echo "✓ Conversation formatted correctly for future parallel tool use\n"; ``` ```ruby Ruby require "anthropic" client = Anthropic::Client.new tools = [ { name: "get_weather", description: "Get the current weather in a given location", input_schema: { type: "object", properties: { location: { type: "string", description: "The city and state, e.g. San Francisco, CA" } }, required: ["location"] } }, { name: "get_time", description: "Get the current time in a given timezone", input_schema: { type: "object", properties: { timezone: { type: "string", description: "The timezone, e.g. America/New_York" } }, required: ["timezone"] } } ] puts "Requesting parallel tool calls..." response = client.messages.create( model: "claude-opus-4-7", max_tokens: 1024, messages: [ { role: "user", content: "What's the weather in SF and NYC, and what time is it there?" } ], tools: tools ) tool_uses = response.content.select { |block| block.type == :tool_use } puts "\n✓ Claude made #{tool_uses.length} tool calls" if tool_uses.length > 1 puts "✓ Parallel tool calls detected!" tool_uses.each do |tool| puts " - #{tool.name}: #{tool.input}" end else puts "✗ No parallel tool calls detected" end tool_results = tool_uses.map do |tool_use| result = if tool_use.name == "get_weather" location = tool_use.input["location"].to_s location.include?("San Francisco") ? "San Francisco: 68°F, partly cloudy" : "New York: 45°F, clear skies" else timezone = tool_use.input["timezone"].to_s timezone.include?("Los_Angeles") ? "2:30 PM PST" : "5:30 PM EST" end { type: "tool_result", tool_use_id: tool_use.id, content: result } end puts "\nGetting final response..." final_response = client.messages.create( model: "claude-opus-4-7", max_tokens: 1024, messages: [ { role: "user", content: "What's the weather in SF and NYC, and what time is it there?" }, { role: "assistant", content: response.content }, { role: "user", content: tool_results } ], tools: tools ) puts "\nClaude's response:\n#{final_response.content.first.text}" puts "\n--- Verification ---" puts "✓ Tool results sent in single user message: #{tool_results.length} results" puts "✓ No text before tool results in content array" puts "✓ Conversation formatted correctly for future parallel tool use" ``` This script demonstrates: - How to properly format parallel tool calls and results - How to verify that parallel calls are being made - The correct message structure that encourages future parallel tool use - Common mistakes to avoid (like text before tool results) Run this script to test your implementation and ensure Claude is making parallel tool calls effectively. ## Maximizing parallel tool use While Claude 4 models have excellent parallel tool use capabilities by default, you can increase the likelihood of parallel tool execution across all models with targeted prompting:

For Claude 4 models, add this to your system prompt: ```text For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. ``` For even stronger parallel tool use (recommended if the default isn't sufficient), use: ```text For maximum efficiency, whenever you perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. Prioritize calling tools in parallel whenever possible. For example, when reading 3 files, run 3 tool calls in parallel to read all 3 files into context at the same time. When running multiple read-only commands like `ls` or `list_dir`, always run all of the commands in parallel. Err on the side of maximizing parallel tool calls rather than running too many tools sequentially. ```

You can also encourage parallel tool use within specific user messages: ```text Instead of: "What's the weather in Paris? Also check London." Use: "Check the weather in Paris and London simultaneously." Or be explicit: "Please use parallel tool calls to get the weather for Paris, London, and Tokyo at the same time." ```

## Troubleshooting If Claude isn't making parallel tool calls when expected, check these common issues: **1. Incorrect tool result formatting** The most common issue is formatting tool results incorrectly in the conversation history. This "teaches" Claude to avoid parallel calls. Specifically for parallel tool use: - ❌ **Wrong**: Sending separate user messages for each tool result - ✅ **Correct**: All tool results must be in a single user message ```json // ❌ This reduces parallel tool use [ {"role": "assistant", "content": [tool_use_1, tool_use_2]}, {"role": "user", "content": [tool_result_1]}, {"role": "user", "content": [tool_result_2]} // Separate message ] // ✅ This maintains parallel tool use [ {"role": "assistant", "content": [tool_use_1, tool_use_2]}, {"role": "user", "content": [tool_result_1, tool_result_2]} // Single message ] ``` See [Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls) for other formatting rules. **2. Weak prompting** Default prompting may not be sufficient. Use the stronger system prompt from the [Maximizing parallel tool use](#maximizing-parallel-tool-use) section above. **3. Measuring parallel tool usage** To verify parallel tool calls are working: ```python hidelines={1} messages = [] # Your conversation history of assistant Message objects # Calculate average tools per tool-calling message tool_call_messages = [ msg for msg in messages if any(block.type == "tool_use" for block in msg.content) ] total_tool_calls = sum( len([b for b in msg.content if b.type == "tool_use"]) for msg in tool_call_messages ) avg_tools_per_message = ( total_tool_calls / len(tool_call_messages) if tool_call_messages else 0.0 ) print(f"Average tools per message: {avg_tools_per_message}") # Should be > 1.0 if parallel calls are working ``` ## Next steps - For the single-tool-call flow and `tool_result` formatting rules, see [Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls). - For the SDK abstraction that handles parallel execution automatically, see [Tool Runner](/docs/en/agents-and-tools/tool-use/tool-runner). - For the full tool-use workflow, see [Define tools](/docs/en/agents-and-tools/tool-use/define-tools). --- # Server tools URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools # Server tools Work with Anthropic-executed tools: server_tool_use blocks, pause_turn continuation, and domain filtering. --- This page covers the shared mechanics of server-executed tools: the `server_tool_use` block, `pause_turn` continuation, ZDR considerations, and domain filtering. For individual tools, see the [tool reference](/docs/en/agents-and-tools/tool-use/tool-reference). ## The server_tool_use block The `server_tool_use` block appears in Claude's response when a server-executed tool runs. Its `id` field uses the `srvtoolu_` prefix to distinguish it from client tool calls: ```json { "type": "server_tool_use", "id": "srvtoolu_01A2B3C4D5E6F7G8H9", "name": "web_search", "input": { "query": "latest quantum computing breakthroughs" } } ``` The API executes the tool internally. You see the call and its result in the response, but you don't handle execution. Unlike client `tool_use` blocks, you don't need to respond with a `tool_result`. The result block appears immediately after the `server_tool_use` block in the same assistant turn. ## The server-side loop and pause_turn When using server tools like web search, the API may return a `pause_turn` stop reason, indicating that the API has paused a long-running turn. Here's how to handle the `pause_turn` stop reason: ```python Python hidelines={1..4} import anthropic client = anthropic.Anthropic() # Initial request with web search response = client.messages.create( model="claude-opus-4-7", max_tokens=1024, messages=[ { "role": "user", "content": "Search for comprehensive information about quantum computing breakthroughs in 2025", } ], tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}], ) # Check if the response has pause_turn stop reason if response.stop_reason == "pause_turn": # Continue the conversation with the paused content messages = [ { "role": "user", "content": "Search for comprehensive information about quantum computing breakthroughs in 2025", }, {"role": "assistant", "content": response.content}, ] # Send the continuation request continuation = client.messages.create( model="claude-opus-4-7", max_tokens=1024, messages=messages, tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}], ) print(continuation) else: print(response) ``` ```typescript TypeScript hidelines={1..4} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); async function main() { // Initial request with web search const response = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 1024, messages: [ { role: "user", content: "Search for comprehensive information about quantum computing breakthroughs in 2025" } ], tools: [ { type: "web_search_20250305", name: "web_search", max_uses: 10 } ] }); // Check if the response has pause_turn stop reason if (response.stop_reason === "pause_turn") { // Continue the conversation with the paused content const messages: Anthropic.MessageParam[] = [ { role: "user", content: "Search for comprehensive information about quantum computing breakthroughs in 2025" }, { role: "assistant", content: response.content } ]; // Send the continuation request const continuation = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 1024, messages: messages, tools: [ { type: "web_search_20250305", name: "web_search", max_uses: 10 } ] }); console.log(continuation); } else { console.log(response); } } main().catch(console.error); ``` ```csharp C# using Anthropic; using Anthropic.Models.Messages; using System; using System.Linq; using System.Threading.Tasks; class Program { static async Task Main(string[] args) { AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = "claude-opus-4-7", MaxTokens = 1024, Messages = [ new() { Role = Role.User, Content = "Search for comprehensive information about quantum computing breakthroughs in 2025" } ], Tools = [new ToolUnion(new WebSearchTool20250305() { MaxUses = 10 })] }; var response = await client.Messages.Create(parameters); if (response.StopReason == "pause_turn") { var continuationParams = new MessageCreateParams { Model = "claude-opus-4-7", MaxTokens = 1024, Messages = [ new() { Role = Role.User, Content = "Search for comprehensive information about quantum computing breakthroughs in 2025" }, new() { Role = Role.Assistant, Content = response.Content.Select(block => new ContentBlockParam(block.Json)).ToList() } ], Tools = [new ToolUnion(new WebSearchTool20250305() { MaxUses = 10 })] }; var continuation = await client.Messages.Create(continuationParams); Console.WriteLine(continuation); } else { Console.WriteLine(response); } } } ``` ```go Go hidelines={1..13,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() webSearchTool := []anthropic.ToolUnionParam{ {OfWebSearchTool20250305: &anthropic.WebSearchTool20250305Param{ MaxUses: anthropic.Int(10), }}, } response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Search for comprehensive information about quantum computing breakthroughs in 2025")), }, Tools: webSearchTool, }) if err != nil { log.Fatal(err) } if response.StopReason == "pause_turn" { // Convert response content to param types for the assistant message var contentParams []anthropic.ContentBlockParamUnion for _, block := range response.Content { contentParams = append(contentParams, block.ToParam()) } continuation, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Search for comprehensive information about quantum computing breakthroughs in 2025")), anthropic.NewAssistantMessage(contentParams...), }, Tools: webSearchTool, }) if err != nil { log.Fatal(err) } fmt.Println(continuation) } else { fmt.Println(response) } } ``` ```java Java hidelines={1..4,7..8,-1..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.StopReason; import com.anthropic.models.messages.WebSearchTool20250305; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model("claude-opus-4-7") .maxTokens(1024L) .addUserMessage("Search for comprehensive information about quantum computing breakthroughs in 2025") .addTool(WebSearchTool20250305.builder() .maxUses(10L) .build()) .build(); Message response = client.messages().create(params); if (response.stopReason().isPresent() && response.stopReason().get().equals(StopReason.PAUSE_TURN)) { MessageCreateParams continuationParams = MessageCreateParams.builder() .model("claude-opus-4-7") .maxTokens(1024L) .addUserMessage("Search for comprehensive information about quantum computing breakthroughs in 2025") .addMessage(response) .addTool(WebSearchTool20250305.builder() .maxUses(10L) .build()) .build(); Message continuation = client.messages().create(continuationParams); IO.println(continuation); } else { IO.println(response); } } ``` ```php PHP hidelines={1..6} messages->create( maxTokens: 1024, messages: [ [ 'role' => 'user', 'content' => 'Search for comprehensive information about quantum computing breakthroughs in 2025' ] ], model: 'claude-opus-4-7', tools: [ [ 'type' => 'web_search_20250305', 'name' => 'web_search', 'max_uses' => 10 ] ], ); if ($response->stopReason === 'pause_turn') { $messages = [ [ 'role' => 'user', 'content' => 'Search for comprehensive information about quantum computing breakthroughs in 2025' ], [ 'role' => 'assistant', 'content' => $response->content ] ]; $continuation = $client->messages->create( maxTokens: 1024, messages: $messages, model: 'claude-opus-4-7', tools: [ [ 'type' => 'web_search_20250305', 'name' => 'web_search', 'max_uses' => 10 ] ], ); echo $continuation; } else { echo $response; } ``` ```ruby Ruby require "anthropic" client = Anthropic::Client.new response = client.messages.create( model: "claude-opus-4-7", max_tokens: 1024, messages: [ { role: "user", content: "Search for comprehensive information about quantum computing breakthroughs in 2025" } ], tools: [ { type: "web_search_20250305", name: "web_search", max_uses: 10 } ] ) if response.stop_reason == :pause_turn messages = [ { role: "user", content: "Search for comprehensive information about quantum computing breakthroughs in 2025" }, { role: "assistant", content: response.content } ] continuation = client.messages.create( model: "claude-opus-4-7", max_tokens: 1024, messages: messages, tools: [ { type: "web_search_20250305", name: "web_search", max_uses: 10 } ] ) puts continuation else puts response end ``` When handling `pause_turn`: - **Continue the conversation:** Pass the paused response back as-is in a subsequent request to let Claude continue its turn - **Modify if needed:** You can optionally modify the content before continuing if you want to interrupt or redirect the conversation - **Preserve tool state:** Include the same tools in the continuation request to maintain functionality ## ZDR and allowed_callers The basic versions of web search (`web_search_20250305`) and web fetch (`web_fetch_20250910`) are eligible for [Zero Data Retention (ZDR)](/docs/en/manage-claude/api-and-data-retention). The `_20260209` versions with dynamic filtering are **not** ZDR-eligible by default because dynamic filtering relies on code execution internally. To use a `_20260209` server tool with ZDR, disable dynamic filtering by setting `"allowed_callers": ["direct"]` on the tool: ```json { "type": "web_search_20260209", "name": "web_search", "allowed_callers": ["direct"] } ``` This restricts the tool to direct invocation only, bypassing the internal code execution step. Even when web fetch is used in a ZDR-eligible configuration, website publishers may retain any parameters passed to the URL if Claude fetches content from their site. ## Domain filtering Server tools that access the web accept `allowed_domains` and `blocked_domains` parameters to control which domains Claude can reach. When using domain filters: - Domains should not include the HTTP/HTTPS scheme (use `example.com` instead of `https://example.com`) - Subdomains are automatically included (`example.com` covers `docs.example.com`) - Specific subdomains restrict results to only that subdomain (`docs.example.com` returns only results from that subdomain, not from `example.com` or `api.example.com`) - Subpaths are supported and match anything after the path (`example.com/blog` matches `example.com/blog/post-1`) - You can use either `allowed_domains` or `blocked_domains`, but not both in the same request **Wildcard support:** - Only one wildcard (`*`) is allowed per domain entry, and it must appear after the domain part (in the path) - Valid: `example.com/*`, `example.com/*/articles` - Invalid: `*.example.com`, `ex*.com`, `example.com/*/news/*` Invalid domain formats return an `invalid_tool_input` tool error. Request-level domain restrictions must be compatible with organization-level domain restrictions configured in Claude Console. Request-level domains can only further restrict domains, not override or expand beyond the organization-level list. If your request includes domains that conflict with organization settings, the API returns a validation error. Be aware that Unicode characters in domain names can create security vulnerabilities through homograph attacks, where visually similar characters from different scripts can bypass domain filters. For example, `аmazon.com` (using Cyrillic 'а') may appear identical to `amazon.com` but represents a different domain. When configuring domain allow/block lists: - Use ASCII-only domain names when possible - Consider that URL parsers may handle Unicode normalization differently - Test your domain filters with potential homograph variations - Regularly audit your domain configurations for suspicious Unicode characters ## Dynamic filtering with code execution The `_20260209` versions of web search and web fetch use code execution internally to apply dynamic filters against search results. Including a standalone `code_execution` tool alongside `_20260209` versions of web tools creates two execution environments, which can confuse the model. Use one or the other, or pin both to the same version. ## Streaming server-tool events Server-tool events stream as part of the normal SSE flow. The `server_tool_use` block and its result arrive as `content_block_start` and `content_block_delta` events, the same way text and client tool calls stream. See [Streaming](/docs/en/build-with-claude/streaming) for the full event reference. Individual tool pages document tool-specific event names where they differ. ## Batch requests All server tools support batch processing. See [Batch processing](/docs/en/build-with-claude/batch-processing). ## Next steps Search the web and cite results. Retrieve content from specific URLs. Run Python in a sandboxed container. Discover and load tools on demand. --- # Strict tool use URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use # Strict tool use Enforce JSON Schema compliance on Claude's tool inputs with grammar-constrained sampling. --- Setting `strict: true` on a tool definition guarantees Claude's tool inputs match your JSON Schema by constraining the model's token sampling to schema-valid outputs (a technique called grammar-constrained sampling). This page covers why strict mode matters for agents, how to enable it, and common use cases. For the supported JSON Schema subset, see [JSON Schema limitations](/docs/en/build-with-claude/structured-outputs#json-schema-limitations). For non-strict schema guidance, see [Define tools](/docs/en/agents-and-tools/tool-use/define-tools). Strict tool use validates tool parameters, ensuring Claude calls your functions with correctly-typed arguments. Use strict tool use when you need to: - Validate tool parameters - Build agentic workflows - Ensure type-safe function calls - Handle complex tools with nested properties ## Why strict tool use matters for agents Building reliable agentic systems requires guaranteed schema conformance. Without strict mode, Claude might return incompatible types (`"2"` instead of `2`) or missing required fields, breaking your functions and causing runtime errors. Strict tool use guarantees type-safe parameters: - Functions receive correctly-typed arguments every time - No need to validate and retry tool calls - Production-ready agents that work consistently at scale For example, suppose a booking system needs `passengers: int`. Without strict mode, Claude might provide `passengers: "two"` or `passengers: "2"`. With `strict: true`, the response always contains `passengers: 2`. ## Quick start ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "content-type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-opus-4-7", "max_tokens": 1024, "messages": [ {"role": "user", "content": "What is the weather in San Francisco?"} ], "tools": [{ "name": "get_weather", "description": "Get the current weather in a given location", "strict": true, "input_schema": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] } }, "required": ["location"], "additionalProperties": false } }] }' ``` ```bash CLI ant messages create --transform content <<'YAML' model: claude-opus-4-7 max_tokens: 1024 messages: - role: user content: What is the weather in San Francisco? tools: - name: get_weather description: Get the current weather in a given location strict: true input_schema: type: object properties: location: type: string description: The city and state, e.g. San Francisco, CA unit: type: string enum: [celsius, fahrenheit] required: [location] additionalProperties: false YAML ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-4-7", max_tokens=1024, messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}], tools=[ { "name": "get_weather", "description": "Get the current weather in a given location", "strict": True, # Enable strict mode "input_schema": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA", }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "The unit of temperature, either 'celsius' or 'fahrenheit'", }, }, "required": ["location"], "additionalProperties": False, }, } ], ) print(response.content) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }); const response = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 1024, messages: [ { role: "user", content: "What's the weather like in San Francisco?" } ], tools: [ { name: "get_weather", description: "Get the current weather in a given location", strict: true, // Enable strict mode input_schema: { type: "object", properties: { location: { type: "string", description: "The city and state, e.g. San Francisco, CA" }, unit: { type: "string", enum: ["celsius", "fahrenheit"] } }, required: ["location"], additionalProperties: false } } ] }); console.log(response.content); ``` ```csharp C# using System.Text.Json; using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "What's the weather like in San Francisco?" }], Tools = [ new ToolUnion(new Tool() { Name = "get_weather", Description = "Get the current weather in a given location", Strict = true, InputSchema = new InputSchema(new Dictionary { ["properties"] = JsonSerializer.SerializeToElement(new Dictionary { ["location"] = new { type = "string", description = "The city and state, e.g. San Francisco, CA" }, ["unit"] = new { type = "string", @enum = new[] { "celsius", "fahrenheit" } }, }), ["required"] = JsonSerializer.SerializeToElement(new[] { "location" }), ["additionalProperties"] = JsonSerializer.SerializeToElement(false), }), }), ] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather like in San Francisco?")), }, Tools: []anthropic.ToolUnionParam{ {OfTool: &anthropic.ToolParam{ Name: "get_weather", Description: anthropic.String("Get the current weather in a given location"), Strict: anthropic.Bool(true), InputSchema: anthropic.ToolInputSchemaParam{ Properties: map[string]any{ "location": map[string]any{ "type": "string", "description": "The city and state, e.g. San Francisco, CA", }, "unit": map[string]any{ "type": "string", "enum": []string{"celsius", "fahrenheit"}, }, }, Required: []string{"location"}, ExtraFields: map[string]any{ "additionalProperties": false, }, }}}, }, }) if err != nil { log.Fatal(err) } fmt.Println(response.Content) } ``` ```java Java hidelines={1..12,-1..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.core.JsonValue; 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 java.util.List; import java.util.Map; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); InputSchema schema = InputSchema.builder() .properties( JsonValue.from( Map.of( "location", Map.of( "type", "string", "description", "The city and state, e.g. San Francisco, CA" ), "unit", Map.of( "type", "string", "enum", List.of("celsius", "fahrenheit") ) ) ) ) .putAdditionalProperty("required", JsonValue.from(List.of("location"))) .putAdditionalProperty("additionalProperties", JsonValue.from(false)) .build(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(1024L) .addUserMessage("What's the weather like in San Francisco?") .addTool( Tool.builder() .name("get_weather") .description("Get the current weather in a given location") .strict(true) .inputSchema(schema) .build() ) .build(); Message response = client.messages().create(params); IO.println(response.content()); } ``` ```php PHP hidelines={1..4} messages->create( maxTokens: 1024, messages: [ ['role' => 'user', 'content' => "What's the weather like in San Francisco?"] ], model: 'claude-opus-4-7', tools: [ [ 'name' => 'get_weather', 'description' => 'Get the current weather in a given location', 'strict' => true, 'input_schema' => [ 'type' => 'object', 'properties' => [ 'location' => [ 'type' => 'string', 'description' => 'The city and state, e.g. San Francisco, CA' ], 'unit' => [ 'type' => 'string', 'enum' => ['celsius', 'fahrenheit'] ] ], 'required' => ['location'], 'additionalProperties' => false ] ] ], ); echo $message; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-7", max_tokens: 1024, messages: [ { role: "user", content: "What's the weather like in San Francisco?" } ], tools: [ { name: "get_weather", description: "Get the current weather in a given location", strict: true, input_schema: { type: "object", properties: { location: { type: "string", description: "The city and state, e.g. San Francisco, CA" }, unit: { type: "string", enum: ["celsius", "fahrenheit"] } }, required: ["location"], additionalProperties: false } } ] ) puts message.content ``` **Response format:** Tool use blocks with validated inputs in `response.content[x].input` ```json Output { "type": "tool_use", "name": "get_weather", "input": { "location": "San Francisco, CA" } } ``` **Guarantees:** - Tool `input` strictly follows the `input_schema` - Tool `name` is always valid (from provided tools or server tools) ## How it works Create a JSON schema for your tool's `input_schema`. The schema uses standard JSON Schema format with some limitations (see [JSON Schema limitations](/docs/en/build-with-claude/structured-outputs#json-schema-limitations)). Set `"strict": true` as a top-level property in your tool definition, alongside `name`, `description`, and `input_schema`. When Claude uses the tool, the `input` field in the tool_use block strictly follows your `input_schema`, and the `name` is always valid. ## Common use cases

Ensure tool parameters exactly match your schema: ```bash CLI ant messages create <<'YAML' model: claude-opus-4-7 max_tokens: 1024 messages: - role: user content: Search for flights to Tokyo departing June 1, 2026 tools: - name: search_flights strict: true input_schema: type: object properties: destination: type: string departure_date: type: string format: date passengers: type: integer enum: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] required: [destination, departure_date] additionalProperties: false YAML ``` ```python Python hidelines={1..2} from anthropic import Anthropic client = Anthropic() response = client.messages.create( model="claude-opus-4-7", max_tokens=1024, messages=[ { "role": "user", "content": "Search for flights to Tokyo departing June 1, 2026", } ], tools=[ { "name": "search_flights", "strict": True, "input_schema": { "type": "object", "properties": { "destination": {"type": "string"}, "departure_date": {"type": "string", "format": "date"}, "passengers": { "type": "integer", "enum": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], }, }, "required": ["destination", "departure_date"], "additionalProperties": False, }, } ], ) print(response) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const searchFlightsTool: Anthropic.Tool = { name: "search_flights", strict: true, input_schema: { type: "object", properties: { destination: { type: "string" }, departure_date: { type: "string", format: "date" }, passengers: { type: "integer", enum: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] } }, required: ["destination", "departure_date"], additionalProperties: false } }; const response = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 1024, messages: [{ role: "user", content: "Search for flights to Tokyo departing June 1, 2026" }], tools: [searchFlightsTool] }); console.log(response); ``` ```csharp C# using System.Text.Json; using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "Search for flights to Tokyo departing June 1, 2026" }], Tools = [ new ToolUnion(new Tool() { Name = "search_flights", Strict = true, InputSchema = new InputSchema(new Dictionary { ["properties"] = JsonSerializer.SerializeToElement(new Dictionary { ["destination"] = new { type = "string" }, ["departure_date"] = new { type = "string", format = "date" }, ["passengers"] = new { type = "integer", @enum = new[] { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 } }, }), ["required"] = JsonSerializer.SerializeToElement(new[] { "destination", "departure_date" }), ["additionalProperties"] = JsonSerializer.SerializeToElement(false), }), }), ] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Search for flights to Tokyo departing June 1, 2026")), }, Tools: []anthropic.ToolUnionParam{ {OfTool: &anthropic.ToolParam{ Name: "search_flights", Strict: anthropic.Bool(true), InputSchema: anthropic.ToolInputSchemaParam{ Properties: map[string]any{ "destination": map[string]any{ "type": "string", }, "departure_date": map[string]any{ "type": "string", "format": "date", }, "passengers": map[string]any{ "type": "integer", "enum": []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}, }, }, Required: []string{"destination", "departure_date"}, ExtraFields: map[string]any{ "additionalProperties": false, }, }}}, }, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```java Java hidelines={1..12,-1..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.core.JsonValue; 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 java.util.List; import java.util.Map; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); InputSchema schema = InputSchema.builder() .properties( JsonValue.from( Map.of( "destination", Map.of("type", "string"), "departure_date", Map.of("type", "string", "format", "date"), "passengers", Map.of( "type", "integer", "enum", List.of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) ) ) ) ) .putAdditionalProperty("required", JsonValue.from(List.of("destination", "departure_date"))) .putAdditionalProperty("additionalProperties", JsonValue.from(false)) .build(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(1024L) .addUserMessage("Search for flights to Tokyo departing June 1, 2026") .addTool( Tool.builder() .name("search_flights") .strict(true) .inputSchema(schema) .build() ) .build(); Message response = client.messages().create(params); IO.println(response); } ``` ```php PHP hidelines={1..4} messages->create( maxTokens: 1024, messages: [ ['role' => 'user', 'content' => 'Search for flights to Tokyo departing June 1, 2026'] ], model: 'claude-opus-4-7', tools: [ [ 'name' => 'search_flights', 'strict' => true, 'input_schema' => [ 'type' => 'object', 'properties' => [ 'destination' => ['type' => 'string'], 'departure_date' => ['type' => 'string', 'format' => 'date'], 'passengers' => [ 'type' => 'integer', 'enum' => [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] ] ], 'required' => ['destination', 'departure_date'], 'additionalProperties' => false ] ] ], ); echo $message; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-7", max_tokens: 1024, messages: [ { role: "user", content: "Search for flights to Tokyo departing June 1, 2026" } ], tools: [ { name: "search_flights", strict: true, input_schema: { type: "object", properties: { destination: { type: "string" }, departure_date: { type: "string", format: "date" }, passengers: { type: "integer", enum: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] } }, required: ["destination", "departure_date"], additionalProperties: false } } ] ) puts message ```

Build reliable multi-step agents with guaranteed tool parameters: ```bash CLI ant messages create <<'YAML' model: claude-opus-4-7 max_tokens: 1024 messages: - role: user content: >- Help me plan a trip from New York to Paris for 2 people, departing June 1, 2026 tools: - name: search_flights strict: true input_schema: type: object properties: origin: {type: string} destination: {type: string} departure_date: {type: string, format: date} travelers: {type: integer, enum: [1, 2, 3, 4, 5, 6]} required: [origin, destination, departure_date] additionalProperties: false - name: search_hotels strict: true input_schema: type: object properties: city: {type: string} check_in: {type: string, format: date} guests: {type: integer, enum: [1, 2, 3, 4]} required: [city, check_in] additionalProperties: false YAML ``` ```python Python hidelines={1..2} from anthropic import Anthropic client = Anthropic() response = client.messages.create( model="claude-opus-4-7", max_tokens=1024, messages=[ { "role": "user", "content": "Help me plan a trip from New York to Paris for 2 people, departing June 1, 2026", } ], tools=[ { "name": "search_flights", "strict": True, "input_schema": { "type": "object", "properties": { "origin": {"type": "string"}, "destination": {"type": "string"}, "departure_date": {"type": "string", "format": "date"}, "travelers": {"type": "integer", "enum": [1, 2, 3, 4, 5, 6]}, }, "required": ["origin", "destination", "departure_date"], "additionalProperties": False, }, }, { "name": "search_hotels", "strict": True, "input_schema": { "type": "object", "properties": { "city": {"type": "string"}, "check_in": {"type": "string", "format": "date"}, "guests": {"type": "integer", "enum": [1, 2, 3, 4]}, }, "required": ["city", "check_in"], "additionalProperties": False, }, }, ], ) print(response) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const tools: Anthropic.Tool[] = [ { name: "search_flights", strict: true, input_schema: { type: "object", properties: { origin: { type: "string" }, destination: { type: "string" }, departure_date: { type: "string", format: "date" }, travelers: { type: "integer", enum: [1, 2, 3, 4, 5, 6] } }, required: ["origin", "destination", "departure_date"], additionalProperties: false } }, { name: "search_hotels", strict: true, input_schema: { type: "object", properties: { city: { type: "string" }, check_in: { type: "string", format: "date" }, guests: { type: "integer", enum: [1, 2, 3, 4] } }, required: ["city", "check_in"], additionalProperties: false } } ]; const response = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 1024, messages: [ { role: "user", content: "Help me plan a trip from New York to Paris for 2 people, departing June 1, 2026" } ], tools: tools }); console.log(response); ``` ```csharp C# using System.Text.Json; using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "Help me plan a trip from New York to Paris for 2 people, departing June 1, 2026" }], Tools = [ new ToolUnion(new Tool() { Name = "search_flights", Strict = true, InputSchema = new InputSchema(new Dictionary { ["properties"] = JsonSerializer.SerializeToElement(new Dictionary { ["origin"] = new { type = "string" }, ["destination"] = new { type = "string" }, ["departure_date"] = new { type = "string", format = "date" }, ["travelers"] = new { type = "integer", @enum = new[] { 1, 2, 3, 4, 5, 6 } }, }), ["required"] = JsonSerializer.SerializeToElement(new[] { "origin", "destination", "departure_date" }), ["additionalProperties"] = JsonSerializer.SerializeToElement(false), }), }), new ToolUnion(new Tool() { Name = "search_hotels", Strict = true, InputSchema = new InputSchema(new Dictionary { ["properties"] = JsonSerializer.SerializeToElement(new Dictionary { ["city"] = new { type = "string" }, ["check_in"] = new { type = "string", format = "date" }, ["guests"] = new { type = "integer", @enum = new[] { 1, 2, 3, 4 } }, }), ["required"] = JsonSerializer.SerializeToElement(new[] { "city", "check_in" }), ["additionalProperties"] = JsonSerializer.SerializeToElement(false), }), }), ] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Help me plan a trip from New York to Paris for 2 people, departing June 1, 2026")), }, Tools: []anthropic.ToolUnionParam{ {OfTool: &anthropic.ToolParam{ Name: "search_flights", Strict: anthropic.Bool(true), InputSchema: anthropic.ToolInputSchemaParam{ Properties: map[string]any{ "origin": map[string]any{"type": "string"}, "destination": map[string]any{"type": "string"}, "departure_date": map[string]any{"type": "string", "format": "date"}, "travelers": map[string]any{"type": "integer", "enum": []int{1, 2, 3, 4, 5, 6}}, }, Required: []string{"origin", "destination", "departure_date"}, ExtraFields: map[string]any{ "additionalProperties": false, }, }}}, {OfTool: &anthropic.ToolParam{ Name: "search_hotels", Strict: anthropic.Bool(true), InputSchema: anthropic.ToolInputSchemaParam{ Properties: map[string]any{ "city": map[string]any{"type": "string"}, "check_in": map[string]any{"type": "string", "format": "date"}, "guests": map[string]any{"type": "integer", "enum": []int{1, 2, 3, 4}}, }, Required: []string{"city", "check_in"}, ExtraFields: map[string]any{ "additionalProperties": false, }, }}}, }, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```java Java hidelines={1..12,-1..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.core.JsonValue; 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 java.util.List; import java.util.Map; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); InputSchema flightsSchema = InputSchema.builder() .properties( JsonValue.from( Map.of( "origin", Map.of("type", "string"), "destination", Map.of("type", "string"), "departure_date", Map.of("type", "string", "format", "date"), "travelers", Map.of("type", "integer", "enum", List.of(1, 2, 3, 4, 5, 6)) ) ) ) .putAdditionalProperty("required", JsonValue.from(List.of("origin", "destination", "departure_date"))) .putAdditionalProperty("additionalProperties", JsonValue.from(false)) .build(); InputSchema hotelsSchema = InputSchema.builder() .properties( JsonValue.from( Map.of( "city", Map.of("type", "string"), "check_in", Map.of("type", "string", "format", "date"), "guests", Map.of("type", "integer", "enum", List.of(1, 2, 3, 4)) ) ) ) .putAdditionalProperty("required", JsonValue.from(List.of("city", "check_in"))) .putAdditionalProperty("additionalProperties", JsonValue.from(false)) .build(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(1024L) .addUserMessage("Help me plan a trip from New York to Paris for 2 people, departing June 1, 2026") .addTool( Tool.builder() .name("search_flights") .strict(true) .inputSchema(flightsSchema) .build() ) .addTool( Tool.builder() .name("search_hotels") .strict(true) .inputSchema(hotelsSchema) .build() ) .build(); Message response = client.messages().create(params); IO.println(response); } ``` ```php PHP hidelines={1..4} messages->create( maxTokens: 1024, messages: [ ['role' => 'user', 'content' => 'Help me plan a trip from New York to Paris for 2 people, departing June 1, 2026'] ], model: 'claude-opus-4-7', tools: [ [ 'name' => 'search_flights', 'strict' => true, 'input_schema' => [ 'type' => 'object', 'properties' => [ 'origin' => ['type' => 'string'], 'destination' => ['type' => 'string'], 'departure_date' => ['type' => 'string', 'format' => 'date'], 'travelers' => ['type' => 'integer', 'enum' => [1, 2, 3, 4, 5, 6]] ], 'required' => ['origin', 'destination', 'departure_date'], 'additionalProperties' => false ] ], [ 'name' => 'search_hotels', 'strict' => true, 'input_schema' => [ 'type' => 'object', 'properties' => [ 'city' => ['type' => 'string'], 'check_in' => ['type' => 'string', 'format' => 'date'], 'guests' => ['type' => 'integer', 'enum' => [1, 2, 3, 4]] ], 'required' => ['city', 'check_in'], 'additionalProperties' => false ] ] ], ); echo $message; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-7", max_tokens: 1024, messages: [ { role: "user", content: "Help me plan a trip from New York to Paris for 2 people, departing June 1, 2026" } ], tools: [ { name: "search_flights", strict: true, input_schema: { type: "object", properties: { origin: { type: "string" }, destination: { type: "string" }, departure_date: { type: "string", format: "date" }, travelers: { type: "integer", enum: [1, 2, 3, 4, 5, 6] } }, required: ["origin", "destination", "departure_date"], additionalProperties: false } }, { name: "search_hotels", strict: true, input_schema: { type: "object", properties: { city: { type: "string" }, check_in: { type: "string", format: "date" }, guests: { type: "integer", enum: [1, 2, 3, 4] } }, required: ["city", "check_in"], additionalProperties: false } } ] ) puts message ```

## Data retention Strict tool use compiles tool `input_schema` definitions into grammars using the same pipeline as [structured outputs](/docs/en/build-with-claude/structured-outputs). Tool schemas are temporarily cached for up to 24 hours since last use. Prompts and responses are not retained beyond the API response. Strict tool use is HIPAA eligible, but **PHI must not be included in tool schema definitions**. The API caches compiled schemas separately from message content, and these cached schemas do not receive the same PHI protections as prompts and responses. Do not include PHI in `input_schema` property names, `enum` values, `const` values, or `pattern` regular expressions. PHI should only appear in message content (prompts and responses), where it is protected under HIPAA safeguards. For ZDR and HIPAA eligibility across all features, see [API and data retention](/docs/en/manage-claude/api-and-data-retention). --- # Text editor tool URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool # Text editor tool --- This feature is eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned. Claude can use an Anthropic-schema text editor tool to view and modify text files, helping you debug, fix, and improve your code or other text documents. This allows Claude to directly interact with your files, providing hands-on assistance rather than just suggesting changes. For model support, see the [Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference). ## When to use the text editor tool Some examples of when to use the text editor tool are: - **Code debugging:** Have Claude identify and fix bugs in your code, from syntax errors to logic issues. - **Code refactoring:** Let Claude improve your code structure, readability, and performance through targeted edits. - **Documentation generation:** Ask Claude to add docstrings, comments, or README files to your codebase. - **Test creation:** Have Claude create unit tests for your code based on its understanding of the implementation. ## Use the text editor tool Provide the text editor tool (named `str_replace_based_edit_tool`) to Claude using the Messages API. You can optionally specify a `max_characters` parameter to control truncation when viewing large files. `max_characters` is only compatible with `text_editor_20250728` and later versions of the text editor tool. ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "content-type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-opus-4-7", "max_tokens": 1024, "tools": [ { "type": "text_editor_20250728", "name": "str_replace_based_edit_tool", "max_characters": 10000 } ], "messages": [ { "role": "user", "content": "There'\''s a syntax error in my primes.py file. Can you help me fix it?" } ] }' ``` ```bash CLI ant messages create \ --model claude-opus-4-7 \ --max-tokens 1024 \ --tool '{type: text_editor_20250728, name: str_replace_based_edit_tool, max_characters: 10000}' \ --message '{role: user, content: There is a syntax error in my primes.py file. Can you help me fix it?}' ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-4-7", max_tokens=1024, tools=[ { "type": "text_editor_20250728", "name": "str_replace_based_edit_tool", "max_characters": 10000, } ], messages=[ { "role": "user", "content": "There's a syntax error in my primes.py file. Can you help me fix it?", } ], ) print(response) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const anthropic = new Anthropic(); const response = await anthropic.messages.create({ model: "claude-opus-4-7", max_tokens: 1024, tools: [ { type: "text_editor_20250728", name: "str_replace_based_edit_tool", max_characters: 10000 } ], messages: [ { role: "user", content: "There's a syntax error in my primes.py file. Can you help me fix it?" } ] }); console.log(response); ``` ```java Java hidelines={1..5,7..8,-1..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; import com.anthropic.models.messages.ToolTextEditor20250728; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); ToolTextEditor20250728 editorTool = ToolTextEditor20250728.builder() .maxCharacters(10000L) .build(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(1024) .addTool(editorTool) .addUserMessage("There's a syntax error in my primes.py file. Can you help me fix it?") .build(); Message message = client.messages().create(params); IO.println(message); } ``` The text editor tool can be used in the following way: - Include the text editor tool in your API request - Provide a user prompt that may require examining or modifying files, such as "Can you fix the syntax error in my code?" - Claude assesses what it needs to look at and uses the `view` command to examine file contents or list directory contents - The API response will contain a `tool_use` content block with the `view` command - Extract the file or directory path from Claude's tool use request - Read the file's contents or list the directory contents - If a `max_characters` parameter was specified in the tool configuration, truncate the file contents to that length - Return the results to Claude by continuing the conversation with a new `user` message containing a `tool_result` content block - After examining the file or directory, Claude may use a command such as `str_replace` to make changes or `insert` to add text at a specific line number. - If Claude uses the `str_replace` command, Claude constructs a properly formatted tool use request with the old text and new text to replace it with - Extract the file path, old text, and new text from Claude's tool use request - Perform the text replacement in the file - Return the results to Claude - After examining and possibly editing the files, Claude provides a complete explanation of what it found and what changes it made ### Text editor tool commands The text editor tool supports several commands for viewing and modifying files: #### view The `view` command allows Claude to examine the contents of a file or list the contents of a directory. It can read the entire file or a specific range of lines. Parameters: - `command`: Must be "view" - `path`: The path to the file or directory to view - `view_range` (optional): An array of two integers specifying the start and end line numbers to view. Line numbers are 1-indexed, and -1 for the end line means read to the end of the file. This parameter only applies when viewing files, not directories.

Example for viewing a file: ```json { "type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "str_replace_based_edit_tool", "input": { "command": "view", "path": "primes.py" } } ``` Example for viewing a directory: ```json { "type": "tool_use", "id": "toolu_02B19r91rw91mr917835mr9", "name": "str_replace_based_edit_tool", "input": { "command": "view", "path": "src/" } } ```

#### str_replace The `str_replace` command allows Claude to replace a specific string in a file with a new string. This is used for making precise edits. Parameters: - `command`: Must be "str_replace" - `path`: The path to the file to modify - `old_str`: The text to replace (must match exactly, including whitespace and indentation) - `new_str`: The new text to insert in place of the old text

```json { "type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "str_replace_based_edit_tool", "input": { "command": "str_replace", "path": "primes.py", "old_str": "for num in range(2, limit + 1)", "new_str": "for num in range(2, limit + 1):" } } ```

#### create The `create` command allows Claude to create a new file with specified content. Parameters: - `command`: Must be "create" - `path`: The path where the new file should be created - `file_text`: The content to write to the new file

```json { "type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "str_replace_based_edit_tool", "input": { "command": "create", "path": "test_primes.py", "file_text": "import unittest\nimport primes\n\nclass TestPrimes(unittest.TestCase):\n def test_is_prime(self):\n self.assertTrue(primes.is_prime(2))\n self.assertTrue(primes.is_prime(3))\n self.assertFalse(primes.is_prime(4))\n\nif __name__ == '__main__':\n unittest.main()" } } ```

#### insert The `insert` command allows Claude to insert text at a specific location in a file. Parameters: - `command`: Must be "insert" - `path`: The path to the file to modify - `insert_line`: The line number after which to insert the text (0 for beginning of file) - `insert_text`: The text to insert

```json { "type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "str_replace_based_edit_tool", "input": { "command": "insert", "path": "primes.py", "insert_line": 0, "insert_text": "\"\"\"Module for working with prime numbers.\n\nThis module provides functions to check if a number is prime\nand to generate a list of prime numbers up to a given limit.\n\"\"\"\n" } } ```

### Example: Fixing a syntax error with the text editor tool This example demonstrates how Claude uses the text editor tool to fix a syntax error in a Python file. First, your application provides Claude with the text editor tool and a prompt to fix a syntax error: ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "content-type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-opus-4-7", "max_tokens": 1024, "tools": [ { "type": "text_editor_20250728", "name": "str_replace_based_edit_tool" } ], "messages": [ { "role": "user", "content": "There'\''s a syntax error in my primes.py file. Can you help me fix it?" } ] }' ``` ```bash CLI ant messages create \ --model claude-opus-4-7 \ --max-tokens 1024 \ --tool '{type: text_editor_20250728, name: str_replace_based_edit_tool}' \ --message '{role: user, content: There is a syntax error in my primes.py file. Can you help me fix it?}' ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-4-7", max_tokens=1024, tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}], messages=[ { "role": "user", "content": "There's a syntax error in my primes.py file. Can you help me fix it?", } ], ) print(response) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const anthropic = new Anthropic(); const response = await anthropic.messages.create({ model: "claude-opus-4-7", max_tokens: 1024, tools: [ { type: "text_editor_20250728", name: "str_replace_based_edit_tool" } ], messages: [ { role: "user", content: "There's a syntax error in my primes.py file. Can you help me fix it?" } ] }); console.log(response); ``` ```java Java hidelines={1..5,7..8,-1..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; import com.anthropic.models.messages.ToolTextEditor20250728; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); ToolTextEditor20250728 editorTool = ToolTextEditor20250728.builder().build(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(1024) .addTool(editorTool) .addUserMessage("There's a syntax error in my primes.py file. Can you help me fix it?") .build(); Message message = client.messages().create(params); IO.println(message); } ``` Claude uses the text editor tool first to view the file: ```json Output { "id": "msg_01XAbCDeFgHiJkLmNoPQrStU", "model": "claude-opus-4-7", "stop_reason": "tool_use", "role": "assistant", "content": [ { "type": "text", "text": "I'll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue." }, { "type": "tool_use", "id": "toolu_01AbCdEfGhIjKlMnOpQrStU", "name": "str_replace_based_edit_tool", "input": { "command": "view", "path": "primes.py" } } ] } ``` Your application should then read the file and return its contents to Claude: ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "content-type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-opus-4-7", "max_tokens": 1024, "tools": [ { "type": "text_editor_20250728", "name": "str_replace_based_edit_tool" } ], "messages": [ { "role": "user", "content": "There'\''s a syntax error in my primes.py file. Can you help me fix it?" }, { "role": "assistant", "content": [ { "type": "text", "text": "I'\''ll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue." }, { "type": "tool_use", "id": "toolu_01AbCdEfGhIjKlMnOpQrStU", "name": "str_replace_based_edit_tool", "input": { "command": "view", "path": "primes.py" } } ] }, { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01AbCdEfGhIjKlMnOpQrStU", "content": "1: def is_prime(n):\n2: \"\"\"Check if a number is prime.\"\"\"\n3: if n <= 1:\n4: return False\n5: if n <= 3:\n6: return True\n7: if n % 2 == 0 or n % 3 == 0:\n8: return False\n9: i = 5\n10: while i * i <= n:\n11: if n % i == 0 or n % (i + 2) == 0:\n12: return False\n13: i += 6\n14: return True\n15: \n16: def get_primes(limit):\n17: \"\"\"Generate a list of prime numbers up to the given limit.\"\"\"\n18: primes = []\n19: for num in range(2, limit + 1)\n20: if is_prime(num):\n21: primes.append(num)\n22: return primes\n23: \n24: def main():\n25: \"\"\"Main function to demonstrate prime number generation.\"\"\"\n26: limit = 100\n27: prime_list = get_primes(limit)\n28: print(f\"Prime numbers up to {limit}:\")\n29: print(prime_list)\n30: print(f\"Found {len(prime_list)} prime numbers.\")\n31: \n32: if __name__ == \"__main__\":\n33: main()" } ] } ] }' ``` ```bash CLI ant messages create <<'YAML' model: claude-opus-4-7 max_tokens: 1024 tools: - type: text_editor_20250728 name: str_replace_based_edit_tool messages: - role: user content: There's a syntax error in my primes.py file. Can you help me fix it? - role: assistant content: - type: text text: >- I'll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue. - type: tool_use id: toolu_01AbCdEfGhIjKlMnOpQrStU name: str_replace_based_edit_tool input: command: view path: primes.py - role: user content: - type: tool_result tool_use_id: toolu_01AbCdEfGhIjKlMnOpQrStU content: |- 1: def is_prime(n): 2: """Check if a number is prime.""" 3: if n <= 1: 4: return False 5: if n <= 3: 6: return True 7: if n % 2 == 0 or n % 3 == 0: 8: return False 9: i = 5 10: while i * i <= n: 11: if n % i == 0 or n % (i + 2) == 0: 12: return False 13: i += 6 14: return True 15: 16: def get_primes(limit): 17: """Generate a list of prime numbers up to the given limit.""" 18: primes = [] 19: for num in range(2, limit + 1) 20: if is_prime(num): 21: primes.append(num) 22: return primes 23: 24: def main(): 25: """Main function to demonstrate prime number generation.""" 26: limit = 100 27: prime_list = get_primes(limit) 28: print(f"Prime numbers up to {limit}:") 29: print(prime_list) 30: print(f"Found {len(prime_list)} prime numbers.") 31: 32: if __name__ == "__main__": 33: main() YAML ``` ```python Python response = client.messages.create( model="claude-opus-4-7", max_tokens=1024, tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}], messages=[ { "role": "user", "content": "There's a syntax error in my primes.py file. Can you help me fix it?", }, { "role": "assistant", "content": [ { "type": "text", "text": "I'll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue.", }, { "type": "tool_use", "id": "toolu_01AbCdEfGhIjKlMnOpQrStU", "name": "str_replace_based_edit_tool", "input": {"command": "view", "path": "primes.py"}, }, ], }, { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01AbCdEfGhIjKlMnOpQrStU", "content": '1: def is_prime(n):\n2: """Check if a number is prime."""\n3: if n <= 1:\n4: return False\n5: if n <= 3:\n6: return True\n7: if n % 2 == 0 or n % 3 == 0:\n8: return False\n9: i = 5\n10: while i * i <= n:\n11: if n % i == 0 or n % (i + 2) == 0:\n12: return False\n13: i += 6\n14: return True\n15: \n16: def get_primes(limit):\n17: """Generate a list of prime numbers up to the given limit."""\n18: primes = []\n19: for num in range(2, limit + 1)\n20: if is_prime(num):\n21: primes.append(num)\n22: return primes\n23: \n24: def main():\n25: """Main function to demonstrate prime number generation."""\n26: limit = 100\n27: prime_list = get_primes(limit)\n28: print(f"Prime numbers up to {limit}:")\n29: print(prime_list)\n30: print(f"Found {len(prime_list)} prime numbers.")\n31: \n32: if __name__ == "__main__":\n33: main()', } ], }, ], ) print(response) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const anthropic = new Anthropic(); const response = await anthropic.messages.create({ model: "claude-opus-4-7", max_tokens: 1024, tools: [ { type: "text_editor_20250728", name: "str_replace_based_edit_tool" } ], messages: [ { role: "user", content: "There's a syntax error in my primes.py file. Can you help me fix it?" }, { role: "assistant", content: [ { type: "text", text: "I'll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue." }, { type: "tool_use", id: "toolu_01AbCdEfGhIjKlMnOpQrStU", name: "str_replace_based_edit_tool", input: { command: "view", path: "primes.py" } } ] }, { role: "user", content: [ { type: "tool_result", tool_use_id: "toolu_01AbCdEfGhIjKlMnOpQrStU", content: '1: def is_prime(n):\n2: """Check if a number is prime."""\n3: if n <= 1:\n4: return False\n5: if n <= 3:\n6: return True\n7: if n % 2 == 0 or n % 3 == 0:\n8: return False\n9: i = 5\n10: while i * i <= n:\n11: if n % i == 0 or n % (i + 2) == 0:\n12: return False\n13: i += 6\n14: return True\n15: \n16: def get_primes(limit):\n17: """Generate a list of prime numbers up to the given limit."""\n18: primes = []\n19: for num in range(2, limit + 1)\n20: if is_prime(num):\n21: primes.append(num)\n22: return primes\n23: \n24: def main():\n25: """Main function to demonstrate prime number generation."""\n26: limit = 100\n27: prime_list = get_primes(limit)\n28: print(f"Prime numbers up to {limit}:")\n29: print(prime_list)\n30: print(f"Found {len(prime_list)} prime numbers.")\n31: \n32: if __name__ == "__main__":\n33: main()' } ] } ] }); console.log(response); ``` ```java Java hidelines={1..9,11..16,-2..} 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.TextBlockParam; import com.anthropic.models.messages.ToolResultBlockParam; import com.anthropic.models.messages.ToolTextEditor20250728; import com.anthropic.models.messages.ToolUseBlockParam; import java.util.List; public class TextEditorToolResultExample { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(1024) .addTool(ToolTextEditor20250728.builder().build()) .addUserMessage("There's a syntax error in my primes.py file. Can you help me fix it?") .addAssistantMessageOfBlockParams( List.of( ContentBlockParam.ofText( TextBlockParam.builder() .text("I'll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue.") .build() ), ContentBlockParam.ofToolUse( ToolUseBlockParam.builder() .id("toolu_01AbCdEfGhIjKlMnOpQrStU") .name("str_replace_based_edit_tool") .input( ToolUseBlockParam.Input.builder() .putAdditionalProperty("command", JsonValue.from("view")) .putAdditionalProperty("path", JsonValue.from("primes.py")) .build() ) .build() ) ) ) .addUserMessageOfBlockParams( List.of( ContentBlockParam.ofToolResult( ToolResultBlockParam.builder() .toolUseId("toolu_01AbCdEfGhIjKlMnOpQrStU") .content("1: def is_prime(n):\n2: \"\"\"Check if a number is prime.\"\"\"\n3: if n <= 1:\n4: return False\n5: if n <= 3:\n6: return True\n7: if n % 2 == 0 or n % 3 == 0:\n8: return False\n9: i = 5\n10: while i * i <= n:\n11: if n % i == 0 or n % (i + 2) == 0:\n12: return False\n13: i += 6\n14: return True\n15: \n16: def get_primes(limit):\n17: \"\"\"Generate a list of prime numbers up to the given limit.\"\"\"\n18: primes = []\n19: for num in range(2, limit + 1)\n20: if is_prime(num):\n21: primes.append(num)\n22: return primes\n23: \n24: def main():\n25: \"\"\"Main function to demonstrate prime number generation.\"\"\"\n26: limit = 100\n27: prime_list = get_primes(limit)\n28: print(f\"Prime numbers up to {limit}:\")\n29: print(prime_list)\n30: print(f\"Found {len(prime_list)} prime numbers.\")\n31: \n32: if __name__ == \"__main__\":\n33: main()") .build() ) ) ) .build(); Message message = client.messages().create(params); System.out.println(message); } } ``` **Line numbers** In the example above, the `view` tool result includes file contents with line numbers prepended to each line (e.g., "1: def is_prime(n):"). Line numbers are not required, but they are essential for successfully using the `view_range` parameter to examine specific sections of files and the `insert_line` parameter to add content at precise locations. Claude identifies the syntax error and uses the `str_replace` command to fix it: ```json Output { "id": "msg_01VwXyZAbCdEfGhIjKlMnO", "model": "claude-opus-4-7", "stop_reason": "tool_use", "role": "assistant", "content": [ { "type": "text", "text": "I found the syntax error in your primes.py file. In the `get_primes` function, there is a missing colon (:) at the end of the for loop line. Let me fix that for you." }, { "type": "tool_use", "id": "toolu_01PqRsTuVwXyZAbCdEfGh", "name": "str_replace_based_edit_tool", "input": { "command": "str_replace", "path": "primes.py", "old_str": " for num in range(2, limit + 1)", "new_str": " for num in range(2, limit + 1):" } } ] } ``` Your application should then make the edit and return the result: ```bash CLI nocheck ant messages create <<'YAML' model: claude-opus-4-7 max_tokens: 1024 tools: - type: text_editor_20250728 name: str_replace_based_edit_tool messages: # Previous messages... - role: assistant content: - type: text text: >- I found the syntax error in your primes.py file. In the `get_primes` function, there is a missing colon (:) at the end of the for loop line. Let me fix that for you. - type: tool_use id: toolu_01PqRsTuVwXyZAbCdEfGh name: str_replace_based_edit_tool input: command: str_replace path: primes.py old_str: " for num in range(2, limit + 1)" new_str: " for num in range(2, limit + 1):" - role: user content: - type: tool_result tool_use_id: toolu_01PqRsTuVwXyZAbCdEfGh content: Successfully replaced text at exactly one location. YAML ``` ```python Python response = client.messages.create( model="claude-opus-4-7", max_tokens=1024, tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}], messages=[ # Previous messages... { "role": "assistant", "content": [ { "type": "text", "text": "I found the syntax error in your primes.py file. In the `get_primes` function, there is a missing colon (:) at the end of the for loop line. Let me fix that for you.", }, { "type": "tool_use", "id": "toolu_01PqRsTuVwXyZAbCdEfGh", "name": "str_replace_based_edit_tool", "input": { "command": "str_replace", "path": "primes.py", "old_str": " for num in range(2, limit + 1)", "new_str": " for num in range(2, limit + 1):", }, }, ], }, { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01PqRsTuVwXyZAbCdEfGh", "content": "Successfully replaced text at exactly one location.", } ], }, ], ) print(response) ``` ```typescript TypeScript const response = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 1024, tools: [ { type: "text_editor_20250728", name: "str_replace_based_edit_tool" } ], messages: [ // Previous messages... { role: "assistant", content: [ { type: "text", text: "I found the syntax error in your primes.py file. In the `get_primes` function, there is a missing colon (:) at the end of the for loop line. Let me fix that for you." }, { type: "tool_use", id: "toolu_01PqRsTuVwXyZAbCdEfGh", name: "str_replace_based_edit_tool", input: { command: "str_replace", path: "primes.py", old_str: " for num in range(2, limit + 1)", new_str: " for num in range(2, limit + 1):" } } ] }, { role: "user", content: [ { type: "tool_result", tool_use_id: "toolu_01PqRsTuVwXyZAbCdEfGh", content: "Successfully replaced text at exactly one location." } ] } ] }); console.log(response); ``` ```java Java hidelines={1..9,11..16,-2..} 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.TextBlockParam; import com.anthropic.models.messages.ToolResultBlockParam; import com.anthropic.models.messages.ToolTextEditor20250728; import com.anthropic.models.messages.ToolUseBlockParam; import java.util.List; public class TextEditorConversationExample { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(1024) .addTool(ToolTextEditor20250728.builder().build()) // Previous messages would go here .addAssistantMessageOfBlockParams( List.of( ContentBlockParam.ofText( TextBlockParam.builder() .text( "I found the syntax error in your primes.py file. In the `get_primes` function, there is a missing colon (:) at the end of the for loop line. Let me fix that for you." ) .build() ), ContentBlockParam.ofToolUse( ToolUseBlockParam.builder() .id("toolu_01PqRsTuVwXyZAbCdEfGh") .name("str_replace_based_edit_tool") .input( ToolUseBlockParam.Input.builder() .putAdditionalProperty("command", JsonValue.from("str_replace")) .putAdditionalProperty("path", JsonValue.from("primes.py")) .putAdditionalProperty( "old_str", JsonValue.from(" for num in range(2, limit + 1)") ) .putAdditionalProperty( "new_str", JsonValue.from(" for num in range(2, limit + 1):") ) .build() ) .build() ) ) ) .addUserMessageOfBlockParams( List.of( ContentBlockParam.ofToolResult( ToolResultBlockParam.builder() .toolUseId("toolu_01PqRsTuVwXyZAbCdEfGh") .content("Successfully replaced text at exactly one location.") .build() ) ) ) .build(); Message message = client.messages().create(params); System.out.println(message); } } ``` Finally, Claude provides a complete explanation of the fix: ```json Output { "id": "msg_01IjKlMnOpQrStUvWxYzAb", "model": "claude-opus-4-7", "stop_reason": "end_turn", "role": "assistant", "content": [ { "type": "text", "text": "I've fixed the syntax error in your primes.py file. The issue was in the `get_primes` function at line 19. There was a missing colon (:) at the end of the for loop line.\n\nHere's what I changed:\n\nFrom:\n```python\nfor num in range(2, limit + 1)\n```\n\nTo:\n```python\nfor num in range(2, limit + 1):\n```\n\nIn Python, a colon is required at the end of statements that start a new code block, such as for loops, if statements, function definitions, etc. Without the colon, Python raises a syntax error because it doesn't know where the code block begins.\n\nYour code should now run correctly. The function will properly generate a list of prime numbers up to the specified limit." } ] } ``` ## Implement the text editor tool The text editor tool is implemented as a schema-less tool. When using this tool, you don't need to provide an input schema as with other tools; the schema is built into Claude's model and can't be modified. The tool type is `type: "text_editor_20250728"` for Claude 4 models. Create helper functions to handle file operations like reading, writing, and modifying files. Consider implementing backup functionality to recover from mistakes. Create a function that processes tool calls from Claude based on the command type: ```python def handle_editor_tool(tool_call): input_params = tool_call.input command = input_params.get("command", "") file_path = input_params.get("path", "") if command == "view": # Read and return file contents pass elif command == "str_replace": # Replace text in file pass elif command == "create": # Create new file pass elif command == "insert": # Insert text at location pass ``` Add validation and security checks: - Validate file paths to prevent directory traversal - Create backups before making changes - Handle errors gracefully - Implement permissions checks Extract and handle tool calls from Claude's responses: ```python hidelines={1..15} from types import SimpleNamespace as _SN response = _SN( content=[ _SN( type="tool_use", name="str_replace_based_edit_tool", input={}, id="toolu_01" ) ] ) def handle_editor_tool(tc): return "ok" # Process tool use in Claude's response for content in response.content: if content.type == "tool_use": # Execute the tool based on command result = handle_editor_tool(content) # Return result to Claude tool_result = { "type": "tool_result", "tool_use_id": content.id, "content": result, } ``` When implementing the text editor tool, keep in mind: 1. **Security:** The tool has access to your local filesystem, so implement proper security measures. 2. **Backup:** Always create backups before allowing edits to important files. 3. **Validation:** Validate all inputs to prevent unintended changes. 4. **Unique matching:** Make sure replacements match exactly one location to avoid unintended edits. ### Handle errors When using the text editor tool, various errors may occur. Here is guidance on how to handle them:

If Claude tries to view or modify a file that doesn't exist, return an appropriate error message in the `tool_result`: ```json { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "Error: File not found", "is_error": true } ] } ```

If Claude's `str_replace` command matches multiple locations in the file, return an appropriate error message: ```json { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "Error: Found 3 matches for replacement text. Please provide more context to make a unique match.", "is_error": true } ] } ```

If Claude's `str_replace` command doesn't match any text in the file, return an appropriate error message: ```json { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "Error: No match found for replacement. Please check your text and try again.", "is_error": true } ] } ```

If there are permission issues with creating, reading, or modifying files, return an appropriate error message: ```json { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "Error: Permission denied. Cannot write to file.", "is_error": true } ] } ```

### Follow implementation best practices

When asking Claude to fix or modify code, be specific about what files need to be examined or what issues need to be addressed. Clear context helps Claude identify the right files and make appropriate changes. **Less helpful prompt**: "Can you fix my code?" **Better prompt**: "There's a syntax error in my primes.py file that prevents it from running. Can you fix it?"

Specify file paths clearly when needed, especially if you're working with multiple files or files in different directories. **Less helpful prompt**: "Review my helper file" **Better prompt**: "Can you check my utils/helpers.py file for any performance issues?"

Implement a backup system in your application that creates copies of files before allowing Claude to edit them, especially for important or production code. ```python hidelines={1} import os def backup_file(file_path): """Create a backup of a file before editing.""" backup_path = f"{file_path}.backup" if os.path.exists(file_path): with open(file_path, "r") as src, open(backup_path, "w") as dst: dst.write(src.read()) ```

The `str_replace` command requires an exact match for the text to be replaced. Your application should ensure that there is exactly one match for the old text or provide appropriate error messages. ```python def safe_replace(file_path, old_text, new_text): """Replace text only if there's exactly one match.""" with open(file_path, "r") as f: content = f.read() count = content.count(old_text) if count == 0: return "Error: No match found" elif count > 1: return f"Error: Found {count} matches" else: new_content = content.replace(old_text, new_text) with open(file_path, "w") as f: f.write(new_content) return "Successfully replaced text" ```

After Claude makes changes to a file, verify the changes by running tests or checking that the code still works as expected. ```python def verify_changes(file_path): """Run tests or checks after making changes.""" try: # For Python files, check for syntax errors if file_path.endswith(".py"): import ast with open(file_path, "r") as f: ast.parse(f.read()) return "Syntax check passed" except Exception as e: return f"Verification failed: {str(e)}" ```

--- ## Pricing and token usage The text editor tool uses the same pricing structure as other tools used with Claude. It follows the standard input and output token pricing based on the Claude model you're using. In addition to the base tokens, the following additional input tokens are needed for the text editor tool: | Tool | Additional input tokens | | ----------------------------------------- | --------------------------------------- | | `text_editor_20250429` (Claude 4.x) | 700 tokens | For more detailed information about tool pricing, see [Tool use pricing](/docs/en/agents-and-tools/tool-use/overview#pricing). ## Integrate the text editor tool with other tools The text editor tool can be used alongside other Claude tools. When combining tools, ensure you: - Match the tool version with the model you're using - Account for the additional token usage for all tools included in your request ## Change log | Date | Version | Changes | | ---- | ------- | ------- | | July 28, 2025 | `text_editor_20250728` | Release of an updated text editor Tool that fixes some issues and adds an optional `max_characters` parameter. It is otherwise identical to `text_editor_20250429`. | | April 29, 2025 | `text_editor_20250429` | Release of the text editor Tool for Claude 4. This version removes the `undo_edit` command but maintains all other capabilities. The tool name has been updated to reflect its str_replace-based architecture. | | March 13, 2025 | `text_editor_20250124` | Introduction of standalone text editor Tool documentation. This version is optimized for Claude Sonnet 3.7 but has identical capabilities to the previous version. | | October 22, 2024 | `text_editor_20241022` | Initial release of the text editor Tool with Claude Sonnet 3.5 ([retired](/docs/en/about-claude/model-deprecations)). Provides capabilities for viewing, creating, and editing files through the `view`, `create`, `str_replace`, `insert`, and `undo_edit` commands. | ## Next steps Here are some ideas for how to use the text editor tool in more convenient and powerful ways: - **Integrate with your development workflow**: Build the text editor tool into your development tools or IDE - **Create a code review system**: Have Claude review your code and make improvements - **Build a debugging assistant**: Create a system where Claude can help you diagnose and fix issues in your code - **Implement file format conversion**: Let Claude help you convert files from one format to another - **Automate documentation**: Set up workflows for Claude to automatically document your code The text editor tool enables Claude to work directly with your codebase, supporting workflows from debugging to automated documentation. Learn how to implement tool workflows for use with Claude. Execute shell commands with Claude. --- # Tool Runner (SDK) URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner # Tool Runner (SDK) Use the SDK's Tool Runner abstraction to handle the agentic loop, error wrapping, and type safety automatically. --- Tool Runner handles the agentic loop, error wrapping, and type safety so you don't have to. Use the [manual loop](/docs/en/agents-and-tools/tool-use/handle-tool-calls) only when you need human-in-the-loop approval, custom logging, or conditional execution. Available in Python, TypeScript, and Ruby SDKs. The tool runner provides an out-of-the-box solution for executing tools with Claude. Instead of manually handling tool calls, tool results, and conversation management, the tool runner automatically: - Executes tools when Claude calls them - Handles the request/response cycle - Manages conversation state - Provides type safety and validation Use the tool runner for most tool use implementations. The tool runner is currently in beta and available in the [Python](https://github.com/anthropics/anthropic-sdk-python/blob/main/tools.md), [TypeScript](https://github.com/anthropics/anthropic-sdk-typescript/blob/main/helpers.md#tool-helpers), and [Ruby](https://github.com/anthropics/anthropic-sdk-ruby/blob/main/helpers.md#3-auto-looping-tool-runner-beta) SDKs. **Automatic context management with compaction** The tool runner supports automatic [compaction](/docs/en/build-with-claude/context-editing#client-side-compaction-sdk), which generates summaries when token usage exceeds a threshold. This allows long-running agentic tasks to continue beyond context window limits. ## Basic usage Define tools using the SDK helpers, then use the tool runner to execute them. Use the `@beta_tool` decorator to define tools with type hints and docstrings. If you're using the async client, replace `@beta_tool` with `@beta_async_tool` and define the function with `async def`. ```python import json from anthropic import Anthropic, beta_tool client = Anthropic() @beta_tool def get_weather(location: str, unit: str = "fahrenheit") -> str: """Get the current weather in a given location. Args: location: The city and state, e.g. San Francisco, CA unit: Temperature unit, either 'celsius' or 'fahrenheit' """ return json.dumps({"temperature": "20°C", "condition": "Sunny"}) @beta_tool def calculate_sum(a: int, b: int) -> str: """Add two numbers together. Args: a: First number b: Second number """ return str(a + b) runner = client.beta.messages.tool_runner( model="claude-opus-4-7", max_tokens=1024, tools=[get_weather, calculate_sum], messages=[ { "role": "user", "content": "What's the weather like in Paris? Also, what's 15 + 27?", } ], ) for message in runner: print(message) ``` The `@beta_tool` decorator inspects the function arguments and docstring to extract a JSON schema representation. For example, `calculate_sum` becomes: ```json { "name": "calculate_sum", "description": "Add two numbers together.", "input_schema": { "additionalProperties": false, "properties": { "a": { "description": "First number", "title": "A", "type": "integer" }, "b": { "description": "Second number", "title": "B", "type": "integer" } }, "required": ["a", "b"], "type": "object" } } ``` Use `betaZodTool()` for type-safe tool definitions with Zod validation, or `betaTool()` for JSON Schema-based definitions. TypeScript offers two approaches for defining tools: **Using Zod (recommended)** - Use `betaZodTool()` for type-safe tool definitions with Zod validation (requires Zod 3.25.0 or higher): ```typescript hidelines={1} import Anthropic from "@anthropic-ai/sdk"; import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod"; import { z } from "zod"; const client = new Anthropic(); const getWeatherTool = betaZodTool({ name: "get_weather", description: "Get the current weather in a given location", inputSchema: z.object({ location: z.string().describe("The city and state, e.g. San Francisco, CA"), unit: z.enum(["celsius", "fahrenheit"]).default("fahrenheit").describe("Temperature unit") }), run: async (input) => { return JSON.stringify({ temperature: "20°C", condition: "Sunny" }); } }); const finalMessage = await client.beta.messages.toolRunner({ model: "claude-opus-4-7", max_tokens: 1024, tools: [getWeatherTool], messages: [{ role: "user", content: "What's the weather like in Paris?" }] }); for (const block of finalMessage.content) { if (block.type === "text") { console.log(block.text); } } ``` **Using JSON Schema** - Use `betaTool()` for type-safe tool definitions without Zod: The input generated by Claude is not validated at runtime. Perform validation inside the `run` function if needed. ```typescript hidelines={1} import Anthropic from "@anthropic-ai/sdk"; import { betaTool } from "@anthropic-ai/sdk/helpers/beta/json-schema"; const client = new Anthropic(); const calculateSumTool = betaTool({ name: "calculate_sum", description: "Add two numbers together", inputSchema: { type: "object", properties: { a: { type: "number", description: "First number" }, b: { type: "number", description: "Second number" } }, required: ["a", "b"] }, run: async (input) => { return String(input.a + input.b); } }); const finalMessage = await client.beta.messages.toolRunner({ model: "claude-opus-4-7", max_tokens: 1024, tools: [calculateSumTool], messages: [{ role: "user", content: "What's 15 + 27?" }] }); for (const block of finalMessage.content) { if (block.type === "text") { console.log(block.text); } } ``` Use the `Anthropic::BaseTool` class to define tools with typed input schemas. ```ruby require "anthropic" # Initialize client client = Anthropic::Client.new # Define input schema class GetWeatherInput < Anthropic::BaseModel required :location, String, doc: "The city and state, e.g. San Francisco, CA" optional :unit, Anthropic::InputSchema::EnumOf["celsius", "fahrenheit"], doc: "Temperature unit" end # Define tool class GetWeather < Anthropic::BaseTool doc "Get the current weather in a given location" input_schema GetWeatherInput def call(input) # In a full implementation, you'd call a weather API here JSON.generate({temperature: "20°C", condition: "Sunny"}) end end class CalculateSumInput < Anthropic::BaseModel required :a, Integer, doc: "First number" required :b, Integer, doc: "Second number" end class CalculateSum < Anthropic::BaseTool doc "Add two numbers together" input_schema CalculateSumInput def call(input) (input.a + input.b).to_s end end # Use the tool runner runner = client.beta.messages.tool_runner( model: "claude-opus-4-7", max_tokens: 1024, tools: [GetWeather.new, CalculateSum.new], messages: [ {role: "user", content: "What's the weather like in Paris? Also, what's 15 + 27?"} ] ) runner.each_message do |message| message.content.each do |block| puts block.text if block.type == :text end end ``` The `Anthropic::BaseTool` class uses the `doc` method for the tool description and `input_schema` to define the expected parameters. The SDK automatically converts this to the appropriate JSON schema format. The tool function must return a content block or content block array, including text, images, or document blocks. This allows tools to return rich, multimodal responses. Returned strings are converted to a text content block. If you want to return a structured JSON object to Claude, encode it to a JSON string before returning it. Numbers, booleans, or other non-string primitives must also be converted to strings. ## Iterating over the tool runner The tool runner is an iterable that yields messages from Claude. This is often referred to as a "tool call loop". Each iteration, the runner checks if Claude requested a tool use. If so, it calls the tool and sends the result back to Claude automatically, then yields the next message from Claude to continue your loop. You can end the loop at any iteration with a `break` statement. The runner loops until Claude returns a message without a tool use. If you don't need intermediate messages, you can get the final message directly: Use `runner.until_done()` to get the final message. ```python hidelines={1..16} import anthropic from anthropic import beta_tool client = anthropic.Anthropic() @beta_tool def get_weather(location: str) -> str: """Get the current weather in a given location.""" return "20°C, Sunny" @beta_tool def calculate_sum(a: int, b: int) -> str: """Add two numbers together.""" return str(a + b) runner = client.beta.messages.tool_runner( model="claude-opus-4-7", max_tokens=1024, tools=[get_weather, calculate_sum], messages=[ { "role": "user", "content": "What's the weather like in Paris? Also, what's 15 + 27?", } ], ) final_message = runner.until_done() for block in final_message.content: if block.type == "text": print(block.text) ``` Simply `await` the runner to get the final message. ```typescript hidelines={1..13} import Anthropic from "@anthropic-ai/sdk"; import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod"; import { z } from "zod"; const client = new Anthropic(); const getWeatherTool = betaZodTool({ name: "get_weather", description: "Get the current weather in a given location", inputSchema: z.object({ location: z.string() }), run: async () => JSON.stringify({ temperature: "20°C", condition: "Sunny" }) }); const runner = client.beta.messages.toolRunner({ model: "claude-opus-4-7", max_tokens: 1024, tools: [getWeatherTool], messages: [{ role: "user", content: "What's the weather like in Paris?" }] }); const finalMessage = await runner; for (const block of finalMessage.content) { if (block.type === "text") { console.log(block.text); } } ``` Use `runner.run_until_finished` to get all messages. ```ruby hidelines={1..29} require "anthropic" client = Anthropic::Client.new class GetWeatherInput < Anthropic::BaseModel required :location, String end class GetWeather < Anthropic::BaseTool doc "Get the current weather in a given location" input_schema GetWeatherInput def call(input) "Weather in #{input.location}: 20°C, Sunny" end end class CalculateSumInput < Anthropic::BaseModel required :a, Integer required :b, Integer end class CalculateSum < Anthropic::BaseTool doc "Add two numbers together" input_schema CalculateSumInput def call(input) (input.a + input.b).to_s end end runner = client.beta.messages.tool_runner( model: "claude-opus-4-7", max_tokens: 1024, tools: [GetWeather.new, CalculateSum.new], messages: [ {role: "user", content: "What's the weather like in Paris? Also, what's 15 + 27?"} ] ) all_messages = runner.run_until_finished all_messages.each { |msg| puts msg.content } ``` ## Advanced usage Within the loop, you can fully customize the tool runner's next request to the Messages API. The runner automatically appends tool results to the message history, so you don't need to manually manage them. You can optionally inspect the tool result for logging or debugging, and modify the request parameters before the next API call. Use `generate_tool_call_response()` to optionally inspect the tool result (the runner appends it automatically). Use `set_messages_params()` and `append_messages()` to modify the request. ```python nocheck runner = client.beta.messages.tool_runner( model="claude-opus-4-7", max_tokens=1024, tools=[get_weather], messages=[{"role": "user", "content": "What's the weather in San Francisco?"}], ) for message in runner: # Optional: inspect the tool response (automatically appended by the runner) tool_response = runner.generate_tool_call_response() if tool_response: print(f"Tool result: {tool_response}") # Customize the next request runner.set_messages_params( lambda params: { **params, "max_tokens": 2048, # Increase tokens for next request } ) # Or add additional messages runner.append_messages( {"role": "user", "content": "Please be concise in your response."} ) ``` Use `generateToolResponse()` to optionally inspect the tool result (the runner appends it automatically). Use `setMessagesParams()` and `pushMessages()` to modify the request. ```typescript nocheck const runner = client.beta.messages.toolRunner({ model: "claude-opus-4-7", max_tokens: 1024, tools: [getWeatherTool], messages: [{ role: "user", content: "What's the weather in San Francisco?" }] }); for await (const message of runner) { // Optional: inspect the tool result message (automatically appended by the runner) const toolResultMessage = await runner.generateToolResponse(); if (toolResultMessage) { console.log("Tool result:", toolResultMessage); } // Customize the next request runner.setMessagesParams((params) => ({ ...params, max_tokens: 2048 // Increase tokens for next request })); // Or add additional messages runner.pushMessages({ role: "user", content: "Please be concise in your response." }); } ``` Use `next_message` for step-by-step control. Use `feed_messages` to inject messages and `params` to access parameters. ```ruby hidelines={1..16} require "anthropic" client = Anthropic::Client.new class GetWeatherInput < Anthropic::BaseModel required :location, String end class GetWeather < Anthropic::BaseTool doc "Get the current weather in a given location" input_schema GetWeatherInput def call(input) "Weather in #{input.location}: 20°C, Sunny" end end runner = client.beta.messages.tool_runner( model: "claude-opus-4-7", max_tokens: 1024, tools: [GetWeather.new], messages: [{role: "user", content: "What's the weather in San Francisco?"}] ) # Manual step-by-step control message = runner.next_message puts message.content # Inject follow-up messages runner.feed_messages([ {role: "user", content: "Also check Boston"} ]) # Access current parameters puts runner.params ``` ### Debugging tool execution When a tool throws an exception, the tool runner catches it and returns the error to Claude as a tool result with `is_error: true`. By default, only the exception message is included, not the full stack trace. To view full stack traces and debug information, set the `ANTHROPIC_LOG` environment variable: ```bash # View info-level logs including tool errors export ANTHROPIC_LOG=info # View debug-level logs for more verbose output export ANTHROPIC_LOG=debug ``` When enabled, the SDK logs full exception details (using Python's `logging` module, the console in TypeScript, or Ruby's logger), including the complete stack trace when a tool fails. ### Intercepting tool errors By default, tool errors are passed back to Claude, which can then respond appropriately. However, you may want to detect errors and handle them differently, for example, to stop execution early or implement custom error handling. Use the tool response method to intercept tool results and check for errors before they're sent to Claude: ```python hidelines={1..11} import anthropic import json from anthropic import beta_tool client = anthropic.Anthropic() @beta_tool def my_tool(query: str) -> str: """A sample tool.""" return f"Result for: {query}" runner = client.beta.messages.tool_runner( model="claude-opus-4-7", max_tokens=1024, tools=[my_tool], messages=[{"role": "user", "content": "Run the tool"}], ) for message in runner: tool_response = runner.generate_tool_call_response() if tool_response is not None: # tool_response is a dict: {"role": "user", "content": [...]} # Check if any tool result has an error for block in tool_response["content"]: if block.get("is_error"): # Option 1: Raise an exception to stop the loop raise RuntimeError(f"Tool failed: {json.dumps(block['content'])}") # Option 2: Log and continue (let Claude handle it) # logger.error(f"Tool error: {json.dumps(block['content'])}") # Process the message normally print(message.content) ``` ```typescript hidelines={1..13} import Anthropic from "@anthropic-ai/sdk"; import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod"; import { z } from "zod"; const client = new Anthropic(); const myTool = betaZodTool({ name: "my_tool", description: "A sample tool", inputSchema: z.object({ query: z.string() }), run: async (input) => `Result for: ${input.query}` }); const runner = client.beta.messages.toolRunner({ model: "claude-opus-4-7", max_tokens: 1024, tools: [myTool], messages: [{ role: "user", content: "Run the tool" }] }); for await (const message of runner) { const toolResultMessage = await runner.generateToolResponse(); if (toolResultMessage) { // Check if any tool result has an error for (const block of toolResultMessage.content) { if (block.type === "tool_result" && block.is_error) { // Option 1: Throw to stop the loop throw new Error(`Tool failed: ${JSON.stringify(block.content)}`); // Option 2: Log and continue (let Claude handle it) // console.error(`Tool error: ${JSON.stringify(block.content)}`); } } } // Process the message normally console.log(message.content); } ``` ```ruby hidelines={1..16} require "anthropic" client = Anthropic::Client.new class MyToolInput < Anthropic::BaseModel required :query, String end class MyTool < Anthropic::BaseTool doc "A sample tool" input_schema MyToolInput def call(input) "Result for: #{input.query}" end end runner = client.beta.messages.tool_runner( model: "claude-opus-4-7", max_tokens: 1024, tools: [MyTool.new], messages: [{role: "user", content: "Run the tool"}] ) runner.each_message do |message| # Get the tool response to check for errors # Note: The runner automatically handles tool execution and appends results # This is just for error checking/logging purposes tool_results = runner.params[:messages].last if tool_results && tool_results[:role] == :user && tool_results[:content].is_a?(Array) tool_results[:content].each do |block| if block[:type] == :tool_result && block[:is_error] # Option 1: Raise an exception to stop the loop raise "Tool failed: #{block[:content]}" # Option 2: Log and continue (let Claude handle it) # logger.error("Tool error: #{block[:content]}") end end end puts message.content end ``` ### Modifying tool results You can modify tool results before they're sent back to Claude. This is useful for adding metadata such as `cache_control` to enable [prompt caching](/docs/en/build-with-claude/prompt-caching) on tool results, or for transforming the tool output. Use the tool response method to get the tool result, then modify it before the runner proceeds. Whether you explicitly append the modified result or mutate it in place depends on the SDK; see the code comments in each tab. ```python hidelines={1..10} import anthropic from anthropic import beta_tool client = anthropic.Anthropic() @beta_tool def search_documents(query: str) -> str: """Search documents for relevant information.""" return f"Found 3 documents matching: {query}" runner = client.beta.messages.tool_runner( model="claude-opus-4-7", max_tokens=1024, tools=[search_documents], messages=[ { "role": "user", "content": "Search for information about the climate of San Francisco", } ], ) for message in runner: tool_response = runner.generate_tool_call_response() if tool_response is not None: # tool_response is a dict: {"role": "user", "content": [...]} # Modify the tool result to add cache control for block in tool_response["content"]: if block["type"] == "tool_result": # Add cache_control to cache this tool result block["cache_control"] = {"type": "ephemeral"} # Append the modified response (this prevents auto-append of the original) runner.append_messages(message, tool_response) print(message.content) ``` ```typescript hidelines={1..13} import Anthropic from "@anthropic-ai/sdk"; import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod"; import { z } from "zod"; const client = new Anthropic(); const searchDocuments = betaZodTool({ name: "search_documents", description: "Search documents for relevant information", inputSchema: z.object({ query: z.string() }), run: async (input) => `Found 3 documents matching: ${input.query}` }); const runner = client.beta.messages.toolRunner({ model: "claude-opus-4-7", max_tokens: 1024, tools: [searchDocuments], messages: [ { role: "user", content: "Search for information about the climate of San Francisco" } ] }); for await (const message of runner) { const toolResultMessage = await runner.generateToolResponse(); if (toolResultMessage && typeof toolResultMessage.content !== "string") { // Modify the tool result to add cache control for (const block of toolResultMessage.content) { if (block.type === "tool_result") { // Add cache_control to cache this tool result block.cache_control = { type: "ephemeral" }; } } // No pushMessages call needed: the runner auto-appends both the assistant // message and the (now-mutated) cached tool response. } console.log(message.content); } ``` ```ruby hidelines={1..16} require "anthropic" client = Anthropic::Client.new class SearchDocumentsInput < Anthropic::BaseModel required :query, String end class SearchDocuments < Anthropic::BaseTool doc "Search documents for relevant information" input_schema SearchDocumentsInput def call(input) "Found 3 documents matching: #{input.query}" end end runner = client.beta.messages.tool_runner( model: "claude-opus-4-7", max_tokens: 1024, tools: [SearchDocuments.new], messages: [{role: "user", content: "Search for information about the climate of San Francisco"}] ) loop do message = runner.next_message break unless message # Access the most recent tool results from the messages array # The runner automatically adds tool results, but you can modify them tool_results_message = runner.params[:messages].last if tool_results_message && tool_results_message[:role] == :user && tool_results_message[:content].is_a?(Array) tool_results_message[:content].each do |block| if block[:type] == :tool_result # Modify the tool result to add cache control block[:cache_control] = {type: "ephemeral"} end end end puts message.content break if message.stop_reason != :tool_use end ``` Adding `cache_control` to tool results is particularly useful when tools return large amounts of data (such as document search results) that you want to cache for subsequent API calls. See [Prompt caching](/docs/en/build-with-claude/prompt-caching) for more details on caching strategies. ## Streaming Enable streaming to receive events as they arrive. Each iteration yields a stream object that you can iterate for events. Set `stream=True` and use `get_final_message()` to get the accumulated message. ```python hidelines={1..10} import anthropic from anthropic import beta_tool client = anthropic.Anthropic() @beta_tool def calculate_sum(a: int, b: int) -> str: """Add two numbers together.""" return str(a + b) runner = client.beta.messages.tool_runner( model="claude-opus-4-7", max_tokens=1024, tools=[calculate_sum], messages=[{"role": "user", "content": "What is 15 + 27?"}], stream=True, ) # When streaming, the runner returns BetaMessageStream for message_stream in runner: for event in message_stream: print("event:", event) print("message:", message_stream.get_final_message()) print(runner.until_done()) ``` Set `stream: true` and use `finalMessage()` to get the accumulated message. ```typescript hidelines={1..13} import Anthropic from "@anthropic-ai/sdk"; import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod"; import { z } from "zod"; const client = new Anthropic(); const getWeatherTool = betaZodTool({ name: "get_weather", description: "Get the current weather in a given location", inputSchema: z.object({ location: z.string() }), run: async () => JSON.stringify({ temperature: "20°C", condition: "Sunny" }) }); const runner = client.beta.messages.toolRunner({ model: "claude-opus-4-7", max_tokens: 1024, messages: [{ role: "user", content: "What is the weather in San Francisco?" }], tools: [getWeatherTool], stream: true }); // When streaming, the runner returns BetaMessageStream for await (const messageStream of runner) { for await (const event of messageStream) { console.log("event:", event); } console.log("message:", await messageStream.finalMessage()); } console.log(await runner); ``` Use `each_streaming` to iterate over streaming events. ```ruby hidelines={1..17} require "anthropic" client = Anthropic::Client.new class CalculateSumInput < Anthropic::BaseModel required :a, Integer required :b, Integer end class CalculateSum < Anthropic::BaseTool doc "Add two numbers together" input_schema CalculateSumInput def call(input) (input.a + input.b).to_s end end runner = client.beta.messages.tool_runner( model: "claude-opus-4-7", max_tokens: 1024, tools: [CalculateSum.new], messages: [{role: "user", content: "What is 15 + 27?"}] ) runner.each_streaming do |event| case event when Anthropic::Streaming::TextEvent print event.text when Anthropic::Streaming::InputJsonEvent puts "\nTool input: #{event.partial_json}" end end ``` ## Next steps - For manual control over the tool-call loop, see [Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls). - For running multiple tools concurrently, see [Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use). - For the full tool-use workflow, see [Define tools](/docs/en/agents-and-tools/tool-use/define-tools). --- # Tool use with prompt caching URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching # Tool use with prompt caching Cache tool definitions across turns and understand what invalidates your cache. --- This page covers prompt caching for tool definitions: where to place `cache_control` breakpoints, how `defer_loading` preserves your cache, and what invalidates it. For general prompt caching, see [Prompt caching](/docs/en/build-with-claude/prompt-caching). ## cache_control on tool definitions Place `cache_control: {"type": "ephemeral"}` on the last tool in your `tools` array. This caches the entire tool-definitions prefix, from the first tool through the marked breakpoint: ```json { "tools": [ { "name": "get_weather", "description": "Get the current weather in a given location", "input_schema": { "type": "object", "properties": { "location": { "type": "string" } }, "required": ["location"] } }, { "name": "get_time", "description": "Get the current time in a given time zone", "input_schema": { "type": "object", "properties": { "timezone": { "type": "string" } }, "required": ["timezone"] }, "cache_control": { "type": "ephemeral" } } ] } ``` For `mcp_toolset`, the `cache_control` breakpoint lands on the last tool in the set. You don't control tool order within an MCP toolset, so place the breakpoint on the `mcp_toolset` entry itself and the API applies it to the final expanded tool. ## defer_loading and cache preservation Deferred tools are not included in the system-prompt prefix. When the model discovers a deferred tool through [tool search](/docs/en/agents-and-tools/tool-use/tool-search-tool), the definition is appended inline as a `tool_reference` block in the conversation history. The prefix is untouched, so prompt caching is preserved. This means adding tools dynamically through tool search does not break your cache. You can start a conversation with a small set of always-loaded tools (cached), let the model discover additional tools as needed, and keep the same cache hit across every turn. `defer_loading` also acts independently of grammar construction for [strict mode](/docs/en/agents-and-tools/tool-use/strict-tool-use). The grammar builds from the full toolset regardless of which tools are deferred, so prompt caching and grammar caching are both preserved when tools load dynamically. ## What invalidates your cache The cache follows a prefix hierarchy (`tools` → `system` → `messages`), so a change at one level invalidates that level and everything after it: | Change | Invalidates | |---|---| | Modifying tool definitions | Entire cache (tools, system, messages) | | Toggling web search or citations | System and messages caches | | Changing `tool_choice` | Messages cache | | Changing `disable_parallel_tool_use` | Messages cache | | Toggling images present/absent | Messages cache | | Changing thinking parameters | Messages cache | If you need to vary `tool_choice` mid-conversation, consider placing cache breakpoints before the variation point. ## Per-tool interaction table | Tool | Caching considerations | |---|---| | [Web search](/docs/en/agents-and-tools/tool-use/web-search-tool) | Enabling or disabling invalidates the system and messages caches | | [Web fetch](/docs/en/agents-and-tools/tool-use/web-fetch-tool) | Enabling or disabling invalidates the system and messages caches | | [Code execution](/docs/en/agents-and-tools/tool-use/code-execution-tool) | Container state is independent of prompt cache | | [Tool search](/docs/en/agents-and-tools/tool-use/tool-search-tool) | Discovered tools load as `tool_reference` blocks, preserving prefix cache | | [Computer use](/docs/en/agents-and-tools/tool-use/computer-use-tool) | Screenshot presence affects messages cache | | [Text editor](/docs/en/agents-and-tools/tool-use/text-editor-tool) | Standard client tool, no special caching interaction | | [Bash](/docs/en/agents-and-tools/tool-use/bash-tool) | Standard client tool, no special caching interaction | | [Memory](/docs/en/agents-and-tools/tool-use/memory-tool) | Standard client tool, no special caching interaction | ## Next steps Learn the full prompt caching model, including TTLs and pricing. Load tools on demand without breaking your cache. Browse all available tools and their parameters. --- # Troubleshooting tool use URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use # Troubleshooting tool use Fix the most common tool-use errors with symptom-to-fix diagnostic tables. --- Symptom-to-fix tables for the most common tool-use errors. Each fix cross-references the page that owns the feature. ## Claude calls the wrong tool | Symptom | Likely cause | Fix | |---|---|---| | Claude calls tool A when you wanted tool B | Description ambiguity | Sharpen descriptions. Differentiate tools by WHEN to use them, not only WHAT they do. See [Define tools](/docs/en/agents-and-tools/tool-use/define-tools). | | Claude never calls your tool | Tool name collision or overly-generic schema | Check for duplicate names across your tool list. Add `input_examples` to make the intended use concrete. | | Claude calls with wrong parameter types | Model guessing at ambiguous schema | Add `strict: true` (if your schema is in the supported subset) or add `input_examples`. | ## Claude invents tool parameters | Symptom | Likely cause | Fix | |---|---|---| | Parameter that doesn't exist in your schema | Model over-generation without strict mode | Add `strict: true` if your schema is in the [supported subset](/docs/en/agents-and-tools/tool-use/strict-tool-use). | | Parameter values outside your enum | Missing strict mode or too-large enum | Shrink the enum or add `input_examples` showing valid choices. | ## Parallel tool calls don't work | Symptom | Likely cause | Fix | |---|---|---| | Claude calls tools sequentially when parallel would be better | Message history formatting | Send multiple `tool_result` blocks in ONE user message, not one per turn. See [Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use). | | `disable_parallel_tool_use` seems ignored | Set too late in the conversation | Must be set on the request that returns `tool_use`. Setting it on a later request has no effect on earlier tool calls. | ## Cache keeps invalidating | Symptom | Likely cause | Fix | |---|---|---| | Every request is a cache miss | `tool_choice` varying between requests | Keep `tool_choice` stable or place the `cache_control` breakpoint before the variation point. See [Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching). | | Adding a tool mid-conversation breaks cache | Tool prepended to the tools array | Use `defer_loading: true` with tool search to append the tool inline instead of modifying the array head. | ## Errors at request time | Error | Cause | Fix | |---|---|---| | `tool_use ids were found without tool_result blocks immediately after` | Missing `tool_result` for some `tool_use` ids, or `tool_result` is not the first content block in the user message | Return one `tool_result` for every `tool_use` block in the assistant response. Put `tool_result` blocks before any text. See [Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls) and [Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use). | | `Input schema is not compatible with strict mode: string patterns are not supported` | Using `pattern` with `strict: true` | Remove the pattern or drop `strict: true`. The `pattern` keyword is not in the supported JSON Schema subset yet. | | `All tools have defer_loading: true` | No tools visible to the model | At least one tool must be immediately loaded. The tool search tool itself must never have `defer_loading: true`. | ## JSON escaping differences (Opus 4.6+) | Symptom | Cause | Fix | |---|---|---| | String comparison on tool inputs fails with newer models | Unicode and forward-slash escaping differs between model versions | Parse with `json.loads()` or `JSON.parse()`. Never do raw string matching on serialized input. | ## Next steps Write schemas and descriptions that steer Claude toward the right tool. Execute tools and return results in the required message format. Full directory of Anthropic-schema tools and their version strings. --- # Tutorial: Build a tool-using agent URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent # Tutorial: Build a tool-using agent A guided walkthrough from a single tool call to a production-ready agentic loop. --- This tutorial builds a calendar-management agent in five concentric rings. Each ring is a complete, runnable program that adds exactly one concept to the ring before it. By the end you will have written the agentic loop by hand and then replaced it with the Tool Runner SDK abstraction. The example tool is `create_calendar_event`. Its schema uses nested objects, arrays, and optional fields, so you will see how Claude handles realistic input shapes rather than a single flat string. Every ring runs standalone. Copy any ring into a fresh file and it will execute without the code from earlier rings. ## Ring 1: Single tool, single turn The smallest possible tool-using program: one tool, one user message, one tool call, one result. The code is heavily commented so you can map each line to the [tool use lifecycle](/docs/en/agents-and-tools/tool-use/how-tool-use-works). The request sends a `tools` array alongside the user message. When Claude decides to call a tool, the response comes back with `stop_reason: "tool_use"` and a `tool_use` content block containing the tool name, a unique `id`, and the structured `input`. Your code executes the tool, then sends the result back in a `tool_result` block whose `tool_use_id` matches the `id` from the call. ````bash #!/bin/bash # Ring 1: Single tool, single turn. # Source for in build-a-tool-using-agent.mdx. # Define one tool as a JSON fragment. The input_schema is a JSON Schema # object describing the arguments Claude should pass when it calls this # tool. This schema includes nested objects (recurrence), arrays # (attendees), and optional fields, which is closer to real-world tools # than a flat string argument. 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_MSG="Schedule a 30-minute sync with alice@example.com and bob@example.com next Monday at 10am." # Send the user's request along with the tool definition. Claude decides # whether to call the tool based on the request and the tool description. RESPONSE=$(curl -s https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d "$(jq -n \ --argjson tools "$TOOLS" \ --arg msg "$USER_MSG" \ '{ model: "claude-opus-4-6", max_tokens: 1024, tools: $tools, tool_choice: {type: "auto", disable_parallel_tool_use: true}, messages: [{role: "user", content: $msg}] }')") # When Claude calls a tool, the response has stop_reason "tool_use" # and the content array contains a tool_use block alongside any text. echo "stop_reason: $(echo "$RESPONSE" | jq -r '.stop_reason')" # Find the tool_use block. A response may contain text blocks before the # tool_use block, so filter by type rather than assuming position. TOOL_USE=$(echo "$RESPONSE" | jq '.content[] | select(.type == "tool_use")') TOOL_USE_ID=$(echo "$TOOL_USE" | jq -r '.id') echo "Tool: $(echo "$TOOL_USE" | jq -r '.name')" echo "Input: $(echo "$TOOL_USE" | jq -c '.input')" # Execute the tool. In a real system this would call your calendar API. # Here the result is hardcoded to keep the example self-contained. RESULT='{"event_id": "evt_123", "status": "created"}' # Send the result back. The tool_result block goes in a user message and # its tool_use_id must match the id from the tool_use block above. The # assistant's previous response is included so Claude has the full history. ASSISTANT_CONTENT=$(echo "$RESPONSE" | jq '.content') FOLLOWUP=$(curl -s https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d "$(jq -n \ --argjson tools "$TOOLS" \ --arg msg "$USER_MSG" \ --argjson assistant "$ASSISTANT_CONTENT" \ --arg tool_use_id "$TOOL_USE_ID" \ --arg result "$RESULT" \ '{ model: "claude-opus-4-6", max_tokens: 1024, tools: $tools, tool_choice: {type: "auto", disable_parallel_tool_use: true}, messages: [ {role: "user", content: $msg}, {role: "assistant", content: $assistant}, {role: "user", content: [ {type: "tool_result", tool_use_id: $tool_use_id, content: $result} ]} ] }')") # With the tool result in hand, Claude produces a final natural-language # answer and stop_reason becomes "end_turn". echo "stop_reason: $(echo "$FOLLOWUP" | jq -r '.stop_reason')" echo "$FOLLOWUP" | jq -r '.content[] | select(.type == "text") | .text' ```` ````bash #!/usr/bin/env bash # Ring 1: Single tool, single turn. # Uses jq for cross-turn message-array state — building an agentic loop in shell # requires JSON manipulation beyond ant's single-call --transform scope. # Source for in build-a-tool-using-agent.mdx. set -euo pipefail USER_MSG="Schedule a 30-minute sync with alice@example.com and bob@example.com next Monday at 10am." MESSAGES=$(jq -n --arg msg "$USER_MSG" '[{role: "user", content: $msg}]') # Define one tool. The input_schema is a JSON Schema object describing # the arguments Claude should pass when it calls this tool. This schema # includes nested objects (recurrence), arrays (attendees), and optional # fields, which is closer to real-world tools than a flat string argument. call_api() { # ant reads the request body as YAML on stdin: no auth headers, no # hand-built JSON envelope. The static keys (model, tools, tool_choice) # live in a quoted heredoc; the growing messages array is appended as # JSON, which YAML accepts as flow syntax. { cat <<'YAML' model: claude-opus-4-6 max_tokens: 1024 tool_choice: {type: auto, disable_parallel_tool_use: true} 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] YAML printf 'messages: %s\n' "$MESSAGES" } | ant messages create --format json } # Send the user's request along with the tool definition. Claude decides # whether to call the tool based on the request and the tool description. RESPONSE=$(call_api) # When Claude calls a tool, the response has stop_reason "tool_use" # and the content array contains a tool_use block alongside any text. echo "stop_reason: $(jq -r '.stop_reason' <<<"$RESPONSE")" # Find the tool_use block. A response may contain text blocks before the # tool_use block, so filter by type rather than assuming position. TOOL_USE=$(jq '.content[] | select(.type == "tool_use")' <<<"$RESPONSE") TOOL_USE_ID=$(jq -r '.id' <<<"$TOOL_USE") echo "Tool: $(jq -r '.name' <<<"$TOOL_USE")" echo "Input: $(jq -c '.input' <<<"$TOOL_USE")" # Execute the tool. In a real system this would call your calendar API. # Here the result is hardcoded to keep the example self-contained. RESULT='{"event_id": "evt_123", "status": "created"}' # Send the result back. The tool_result block goes in a user message and # its tool_use_id must match the id from the tool_use block above. The # assistant's previous response is included so Claude has the full history. MESSAGES=$(jq \ --argjson assistant "$(jq '.content' <<<"$RESPONSE")" \ --arg tool_use_id "$TOOL_USE_ID" \ --arg result "$RESULT" \ '. + [ {role: "assistant", content: $assistant}, {role: "user", content: [ {type: "tool_result", tool_use_id: $tool_use_id, content: $result} ]} ]' <<<"$MESSAGES") FOLLOWUP=$(call_api) # With the tool result in hand, Claude produces a final natural-language # answer and stop_reason becomes "end_turn". echo "stop_reason: $(jq -r '.stop_reason' <<<"$FOLLOWUP")" jq -r '.content[] | select(.type == "text") | .text' <<<"$FOLLOWUP" ```` ````python # Ring 1: Single tool, single turn. # Source for in build-a-tool-using-agent.mdx. import json import anthropic # Create a client. It reads ANTHROPIC_API_KEY from the environment. client = anthropic.Anthropic() # Define one tool. The input_schema is a JSON Schema object describing # the arguments Claude should pass when it calls this tool. This schema # includes nested objects (recurrence), arrays (attendees), and optional # fields, which is closer to real-world tools than a flat string argument. 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"], }, } ] # Send the user's request along with the tool definition. Claude decides # whether to call the tool based on the request and the tool description. response = client.messages.create( model="claude-opus-4-6", 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 next Monday at 10am.", } ], ) # When Claude calls a tool, the response has stop_reason "tool_use" # and the content array contains a tool_use block alongside any text. print(f"stop_reason: {response.stop_reason}") # Find the tool_use block. A response may contain text blocks before the # tool_use block, so scan the content array rather than assuming position. 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}") # Execute the tool. In a real system this would call your calendar API. # Here the result is hardcoded to keep the example self-contained. result = {"event_id": "evt_123", "status": "created"} # Send the result back. The tool_result block goes in a user message and # its tool_use_id must match the id from the tool_use block above. The # assistant's previous response is included so Claude has the full history. followup = client.messages.create( model="claude-opus-4-6", 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 next Monday at 10am.", }, {"role": "assistant", "content": response.content}, { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": tool_use.id, "content": json.dumps(result), } ], }, ], ) # With the tool result in hand, Claude produces a final natural-language # answer and stop_reason becomes "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 // Ring 1: Single tool, single turn. // Source for in build-a-tool-using-agent.mdx. import Anthropic from "@anthropic-ai/sdk"; // Create a client. It reads ANTHROPIC_API_KEY from the environment. const client = new Anthropic(); // Define one tool. The input_schema is a JSON Schema object describing // the arguments Claude should pass when it calls this tool. This schema // includes nested objects (recurrence), arrays (attendees), and optional // fields, which is closer to real-world tools than a flat string argument. 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"], }, }, ]; // Send the user's request along with the tool definition. Claude decides // whether to call the tool based on the request and the tool description. const response = await client.messages.create({ model: "claude-opus-4-6", 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 next Monday at 10am.", }, ], }); // When Claude calls a tool, the response has stop_reason "tool_use" // and the content array contains a tool_use block alongside any text. console.log(`stop_reason: ${response.stop_reason}`); // Find the tool_use block. A response may contain text blocks before the // tool_use block, so scan the content array rather than assuming position. const toolUse = response.content.find( (block): block is Anthropic.ToolUseBlock => block.type === "tool_use", )!; console.log(`Tool: ${toolUse.name}`); console.log(`Input: ${JSON.stringify(toolUse.input)}`); // Execute the tool. In a real system this would call your calendar API. // Here the result is hardcoded to keep the example self-contained. const result = { event_id: "evt_123", status: "created" }; // Send the result back. The tool_result block goes in a user message and // its tool_use_id must match the id from the tool_use block above. The // assistant's previous response is included so Claude has the full history. const followup = await client.messages.create({ model: "claude-opus-4-6", 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 next Monday at 10am.", }, { role: "assistant", content: response.content }, { role: "user", content: [ { type: "tool_result", tool_use_id: toolUse.id, content: JSON.stringify(result), }, ], }, ], }); // With the tool result in hand, Claude produces a final natural-language // answer and stop_reason becomes "end_turn". console.log(`stop_reason: ${followup.stop_reason}`); for (const block of followup.content) { if (block.type === "text") { console.log(block.text); } } ```` **What to expect** ```text Output 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 next Monday at 10am. ``` The first `stop_reason` is `tool_use` because Claude is waiting for the calendar result. After you send the result, the second `stop_reason` is `end_turn` and the content is natural language for the user. ## Ring 2: The agentic loop Ring 1 assumed Claude would call the tool exactly once. Real tasks often need several calls: Claude might create an event, read the confirmation, then create another. The fix is a `while` loop that keeps running tools and feeding results back until `stop_reason` is no longer `"tool_use"`. The other change is conversation history. Instead of rebuilding the `messages` array from scratch on each request, keep a running list and append to it. Every turn sees the complete prior context. ````bash #!/bin/bash # Ring 2: The agentic loop. # Source for in build-a-tool-using-agent.mdx. 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"] } } ]' run_tool() { local name="$1" local input="$2" if [ "$name" = "create_calendar_event" ]; then local title=$(echo "$input" | jq -r '.title') jq -n --arg title "$title" '{event_id: "evt_123", status: "created", title: $title}' else echo "{\"error\": \"Unknown tool: $name\"}" fi } # Keep the full conversation history in a JSON array so each turn sees prior context. MESSAGES='[{"role": "user", "content": "Schedule a weekly team standup every Monday at 9am for the next 4 weeks. Invite the whole team: alice@example.com, bob@example.com, carol@example.com."}]' call_api() { curl -s https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d "$(jq -n --argjson tools "$TOOLS" --argjson messages "$MESSAGES" \ '{model: "claude-opus-4-6", max_tokens: 1024, tools: $tools, tool_choice: {type: "auto", disable_parallel_tool_use: true}, messages: $messages}')" } RESPONSE=$(call_api) # Loop until Claude stops asking for tools. Each iteration runs the requested # tool, appends the result to history, and asks Claude to continue. while [ "$(echo "$RESPONSE" | jq -r '.stop_reason')" = "tool_use" ]; do TOOL_USE=$(echo "$RESPONSE" | jq '.content[] | select(.type == "tool_use")') TOOL_NAME=$(echo "$TOOL_USE" | jq -r '.name') TOOL_INPUT=$(echo "$TOOL_USE" | jq -c '.input') TOOL_USE_ID=$(echo "$TOOL_USE" | jq -r '.id') RESULT=$(run_tool "$TOOL_NAME" "$TOOL_INPUT") ASSISTANT_CONTENT=$(echo "$RESPONSE" | jq '.content') MESSAGES=$(echo "$MESSAGES" | jq \ --argjson assistant "$ASSISTANT_CONTENT" \ --arg tool_use_id "$TOOL_USE_ID" \ --arg result "$RESULT" \ '. + [ {role: "assistant", content: $assistant}, {role: "user", content: [{type: "tool_result", tool_use_id: $tool_use_id, content: $result}]} ]') RESPONSE=$(call_api) done echo "$RESPONSE" | jq -r '.content[] | select(.type == "text") | .text' ```` ````bash #!/usr/bin/env bash # Ring 2: The agentic loop. # Uses jq for cross-turn message-array state — building an agentic loop in shell # requires JSON manipulation beyond ant's single-call --transform scope. # Source for in build-a-tool-using-agent.mdx. set -euo pipefail run_tool() { local name="$1" input="$2" if [ "$name" = "create_calendar_event" ]; then jq -n --arg title "$(jq -r '.title' <<<"$input")" \ '{event_id: "evt_123", status: "created", title: $title}' else printf '{"error": "Unknown tool: %s"}' "$name" fi } # Keep the full conversation history in a JSON array so each turn sees # prior context. MESSAGES='[{"role": "user", "content": "Schedule a weekly team standup every Monday at 9am for the next 4 weeks. Invite the whole team: alice@example.com, bob@example.com, carol@example.com."}]' call_api() { # ant reads the request body as YAML on stdin: no auth headers, no # hand-built JSON envelope. The static keys (model, tools, tool_choice) # live in a quoted heredoc; the growing messages array is appended as # JSON, which YAML accepts as flow syntax. { cat <<'YAML' model: claude-opus-4-6 max_tokens: 1024 tool_choice: {type: auto, disable_parallel_tool_use: true} 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] YAML printf 'messages: %s\n' "$MESSAGES" } | ant messages create --format json } RESPONSE=$(call_api) # Loop until Claude stops asking for tools. Each iteration runs the # requested tool, appends the result to history, and asks Claude to # continue. while [ "$(jq -r '.stop_reason' <<<"$RESPONSE")" = "tool_use" ]; do TOOL_USE=$(jq '.content[] | select(.type == "tool_use")' <<<"$RESPONSE") TOOL_NAME=$(jq -r '.name' <<<"$TOOL_USE") TOOL_INPUT=$(jq -c '.input' <<<"$TOOL_USE") TOOL_USE_ID=$(jq -r '.id' <<<"$TOOL_USE") RESULT=$(run_tool "$TOOL_NAME" "$TOOL_INPUT") MESSAGES=$(jq \ --argjson assistant "$(jq '.content' <<<"$RESPONSE")" \ --arg tool_use_id "$TOOL_USE_ID" \ --arg result "$RESULT" \ '. + [ {role: "assistant", content: $assistant}, {role: "user", content: [ {type: "tool_result", tool_use_id: $tool_use_id, content: $result} ]} ]' <<<"$MESSAGES") RESPONSE=$(call_api) done jq -r '.content[] | select(.type == "text") | .text' <<<"$RESPONSE" ```` ````python # Ring 2: The agentic loop. # Source for in build-a-tool-using-agent.mdx. 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}"} # Keep the full conversation history in a list so each turn sees prior context. messages = [ { "role": "user", "content": "Schedule a weekly team standup every Monday at 9am for the next 4 weeks. Invite the whole team: alice@example.com, bob@example.com, carol@example.com.", } ] response = client.messages.create( model="claude-opus-4-6", max_tokens=1024, tools=tools, tool_choice={"type": "auto", "disable_parallel_tool_use": True}, messages=messages, ) # Loop until Claude stops asking for tools. Each iteration runs the requested # tool, appends the result to history, and asks Claude to continue. 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-4-6", 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 // Ring 2: The agentic loop. // Source for in build-a-tool-using-agent.mdx. 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}` }; } // Keep the full conversation history so each turn sees prior context. const messages: Anthropic.MessageParam[] = [ { role: "user", content: "Schedule a weekly team standup every Monday at 9am for the next 4 weeks. Invite the whole team: alice@example.com, bob@example.com, carol@example.com.", }, ]; let response = await client.messages.create({ model: "claude-opus-4-6", max_tokens: 1024, tools, tool_choice: { type: "auto", disable_parallel_tool_use: true }, messages, }); // Loop until Claude stops asking for tools. Each iteration runs the requested // tool, appends the result to history, and asks Claude to continue. while (response.stop_reason === "tool_use") { const toolUse = response.content.find( (block): block is Anthropic.ToolUseBlock => 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-4-6", 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); } } ```` **What to expect** ```text Output I've set up your weekly team standup for the next 4 Mondays at 9am with Alice, Bob, and Carol invited. ``` The loop may run once or several times depending on how Claude breaks down the task. Your code no longer needs to know in advance. ## Ring 3: Multiple tools, parallel calls Agents rarely have just one capability. Add a second tool, `list_calendar_events`, so Claude can check the existing schedule before creating something new. When Claude has multiple independent tool calls to make, it may return several `tool_use` blocks in a single response. Your loop needs to process all of them and send back all results together in one user message. Iterate over every `tool_use` block in `response.content`, not just the first. ````bash #!/bin/bash # Ring 3: Multiple tools, parallel calls. # Source for in build-a-tool-using-agent.mdx. 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"] } } ]' run_tool() { case "$1" in create_calendar_event) jq -n --arg title "$(echo "$2" | jq -r '.title')" '{event_id: "evt_123", status: "created", title: $title}' ;; list_calendar_events) echo '{"events": [{"title": "Existing meeting", "start": "14:00", "end": "15:00"}]}' ;; *) echo "{\"error\": \"Unknown tool: $1\"}" ;; esac } MESSAGES='[{"role": "user", "content": "Check what I have next Monday, then schedule a planning session that avoids any conflicts."}]' call_api() { curl -s https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d "$(jq -n --argjson tools "$TOOLS" --argjson messages "$MESSAGES" \ '{model: "claude-opus-4-6", max_tokens: 1024, tools: $tools, messages: $messages}')" } RESPONSE=$(call_api) while [ "$(echo "$RESPONSE" | jq -r '.stop_reason')" = "tool_use" ]; do # A single response can contain multiple tool_use blocks. Process all of # them and return all results together in one user message. TOOL_RESULTS='[]' while read -r block; do NAME=$(echo "$block" | jq -r '.name') INPUT=$(echo "$block" | jq -c '.input') ID=$(echo "$block" | jq -r '.id') RESULT=$(run_tool "$NAME" "$INPUT") TOOL_RESULTS=$(echo "$TOOL_RESULTS" | jq --arg id "$ID" --arg result "$RESULT" \ '. + [{type: "tool_result", tool_use_id: $id, content: $result}]') done < <(echo "$RESPONSE" | jq -c '.content[] | select(.type == "tool_use")') MESSAGES=$(echo "$MESSAGES" | jq \ --argjson assistant "$(echo "$RESPONSE" | jq '.content')" \ --argjson results "$TOOL_RESULTS" \ '. + [{role: "assistant", content: $assistant}, {role: "user", content: $results}]') RESPONSE=$(call_api) done echo "$RESPONSE" | jq -r '.content[] | select(.type == "text") | .text' ```` ````bash #!/usr/bin/env bash # Ring 3: Multiple tools, parallel calls. # Uses jq for cross-turn message-array state — building an agentic loop in shell # requires JSON manipulation beyond ant's single-call --transform scope. # Source for in build-a-tool-using-agent.mdx. set -euo pipefail run_tool() { case "$1" in create_calendar_event) jq -n --arg title "$(jq -r '.title' <<<"$2")" \ '{event_id: "evt_123", status: "created", title: $title}' ;; list_calendar_events) echo '{"events": [{"title": "Existing meeting", "start": "14:00", "end": "15:00"}]}' ;; *) printf '{"error": "Unknown tool: %s"}' "$1" ;; esac } MESSAGES='[{"role": "user", "content": "Check what I have next Monday, then schedule a planning session that avoids any conflicts."}]' call_api() { # ant reads the request body as YAML on stdin: no auth headers, no # hand-built JSON envelope. The static keys (model, tools) live in a # quoted heredoc; the growing messages array is appended as JSON, # which YAML accepts as flow syntax. { cat <<'YAML' model: claude-opus-4-6 max_tokens: 1024 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] YAML printf 'messages: %s\n' "$MESSAGES" } | ant messages create --format json } RESPONSE=$(call_api) while [ "$(jq -r '.stop_reason' <<<"$RESPONSE")" = "tool_use" ]; do # A single response can contain multiple tool_use blocks. Process all # of them and return all results together in one user message. TOOL_RESULTS='[]' while read -r block; do NAME=$(jq -r '.name' <<<"$block") INPUT=$(jq -c '.input' <<<"$block") ID=$(jq -r '.id' <<<"$block") RESULT=$(run_tool "$NAME" "$INPUT") TOOL_RESULTS=$(jq --arg id "$ID" --arg result "$RESULT" \ '. + [{type: "tool_result", tool_use_id: $id, content: $result}]' \ <<<"$TOOL_RESULTS") done < <(jq -c '.content[] | select(.type == "tool_use")' <<<"$RESPONSE") MESSAGES=$(jq \ --argjson assistant "$(jq '.content' <<<"$RESPONSE")" \ --argjson results "$TOOL_RESULTS" \ '. + [ {role: "assistant", content: $assistant}, {role: "user", content: $results} ]' <<<"$MESSAGES") RESPONSE=$(call_api) done jq -r '.content[] | select(.type == "text") | .text' <<<"$RESPONSE" ```` ````python # Ring 3: Multiple tools, parallel calls. # Source for in build-a-tool-using-agent.mdx. 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 next Monday, then schedule a planning session that avoids any conflicts.", } ] response = client.messages.create( model="claude-opus-4-6", max_tokens=1024, tools=tools, messages=messages, ) while response.stop_reason == "tool_use": # A single response can contain multiple tool_use blocks. Process all of # them and return all results together in one user message. 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-4-6", 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 // Ring 3: Multiple tools, parallel calls. // Source for in build-a-tool-using-agent.mdx. 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 next Monday, then schedule a planning session that avoids any conflicts.", }, ]; let response = await client.messages.create({ model: "claude-opus-4-6", max_tokens: 1024, tools, messages, }); while (response.stop_reason === "tool_use") { // A single response can contain multiple tool_use blocks. Process all of // them and return all results together in one user message. 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-4-6", max_tokens: 1024, tools, messages, }); } for (const block of response.content) { if (block.type === "text") { console.log(block.text); } } ```` **What to expect** ```text Output I checked your calendar for next Monday and found an existing meeting from 2pm to 3pm. I've scheduled the planning session for 10am to 11am to avoid the conflict. ``` For more on concurrent execution and ordering guarantees, see [Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use). ## Ring 4: Error handling Tools fail. A calendar API might reject an event with too many attendees, or a date might be malformed. When a tool raises an error, send the error message back with `is_error: true` instead of crashing. Claude reads the error and can retry with corrected input, ask the user for clarification, or explain the limitation. ````bash #!/bin/bash # Ring 4: Error handling. # Source for in build-a-tool-using-agent.mdx. 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"] } } ]' run_tool() { case "$1" in create_calendar_event) local count=$(echo "$2" | jq '.attendees | length // 0') if [ "$count" -gt 10 ]; then echo "ERROR: Too many attendees (max 10)" return 1 fi jq -n --arg title "$(echo "$2" | jq -r '.title')" '{event_id: "evt_123", status: "created", title: $title}' ;; list_calendar_events) echo '{"events": [{"title": "Existing meeting", "start": "14:00", "end": "15:00"}]}' ;; *) echo "ERROR: Unknown tool: $1" return 1 ;; esac } EMAILS=$(seq 0 14 | sed 's/.*/user&@example.com/' | paste -sd, -) MESSAGES="[{\"role\": \"user\", \"content\": \"Schedule an all-hands with everyone: $EMAILS\"}]" call_api() { curl -s https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d "$(jq -n --argjson tools "$TOOLS" --argjson messages "$MESSAGES" \ '{model: "claude-opus-4-6", max_tokens: 1024, tools: $tools, messages: $messages}')" } RESPONSE=$(call_api) while [ "$(echo "$RESPONSE" | jq -r '.stop_reason')" = "tool_use" ]; do TOOL_RESULTS='[]' while read -r block; do NAME=$(echo "$block" | jq -r '.name') INPUT=$(echo "$block" | jq -c '.input') ID=$(echo "$block" | jq -r '.id') if OUTPUT=$(run_tool "$NAME" "$INPUT"); then TOOL_RESULTS=$(echo "$TOOL_RESULTS" | jq --arg id "$ID" --arg result "$OUTPUT" \ '. + [{type: "tool_result", tool_use_id: $id, content: $result}]') else # Signal failure so Claude can retry or ask for clarification. TOOL_RESULTS=$(echo "$TOOL_RESULTS" | jq --arg id "$ID" --arg result "$OUTPUT" \ '. + [{type: "tool_result", tool_use_id: $id, content: $result, is_error: true}]') fi done < <(echo "$RESPONSE" | jq -c '.content[] | select(.type == "tool_use")') MESSAGES=$(echo "$MESSAGES" | jq \ --argjson assistant "$(echo "$RESPONSE" | jq '.content')" \ --argjson results "$TOOL_RESULTS" \ '. + [{role: "assistant", content: $assistant}, {role: "user", content: $results}]') RESPONSE=$(call_api) done echo "$RESPONSE" | jq -r '.content[] | select(.type == "text") | .text' ```` ````bash #!/usr/bin/env bash # Ring 4: Error handling. # Uses jq for cross-turn message-array state — building an agentic loop in shell # requires JSON manipulation beyond ant's single-call --transform scope. # Source for in build-a-tool-using-agent.mdx. set -euo pipefail run_tool() { case "$1" in create_calendar_event) local count count=$(jq '.attendees | length // 0' <<<"$2") if [ "$count" -gt 10 ]; then echo "ERROR: Too many attendees (max 10)" return 1 fi jq -n --arg title "$(jq -r '.title' <<<"$2")" \ '{event_id: "evt_123", status: "created", title: $title}' ;; list_calendar_events) echo '{"events": [{"title": "Existing meeting", "start": "14:00", "end": "15:00"}]}' ;; *) echo "ERROR: Unknown tool: $1" return 1 ;; esac } EMAILS=$(seq 0 14 | sed 's/.*/user&@example.com/' | paste -sd, -) MESSAGES=$(jq -n --arg msg "Schedule an all-hands with everyone: $EMAILS" \ '[{role: "user", content: $msg}]') call_api() { # ant reads the request body as YAML on stdin: no auth headers, no # hand-built JSON envelope. The static keys (model, tools) live in a # quoted heredoc; the growing messages array is appended as JSON, # which YAML accepts as flow syntax. { cat <<'YAML' model: claude-opus-4-6 max_tokens: 1024 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] YAML printf 'messages: %s\n' "$MESSAGES" } | ant messages create --format json } RESPONSE=$(call_api) while [ "$(jq -r '.stop_reason' <<<"$RESPONSE")" = "tool_use" ]; do TOOL_RESULTS='[]' while read -r block; do NAME=$(jq -r '.name' <<<"$block") INPUT=$(jq -c '.input' <<<"$block") ID=$(jq -r '.id' <<<"$block") if OUTPUT=$(run_tool "$NAME" "$INPUT"); then TOOL_RESULTS=$(jq --arg id "$ID" --arg result "$OUTPUT" \ '. + [{type: "tool_result", tool_use_id: $id, content: $result}]' \ <<<"$TOOL_RESULTS") else # Signal failure so Claude can retry or ask for clarification. TOOL_RESULTS=$(jq --arg id "$ID" --arg result "$OUTPUT" \ '. + [{type: "tool_result", tool_use_id: $id, content: $result, is_error: true}]' \ <<<"$TOOL_RESULTS") fi done < <(jq -c '.content[] | select(.type == "tool_use")' <<<"$RESPONSE") MESSAGES=$(jq \ --argjson assistant "$(jq '.content' <<<"$RESPONSE")" \ --argjson results "$TOOL_RESULTS" \ '. + [ {role: "assistant", content: $assistant}, {role: "user", content: $results} ]' <<<"$MESSAGES") RESPONSE=$(call_api) done jq -r '.content[] | select(.type == "text") | .text' <<<"$RESPONSE" ```` ````python # Ring 4: Error handling. # Source for in build-a-tool-using-agent.mdx. 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 an all-hands with everyone: " + ", ".join(f"user{i}@example.com" for i in range(15)), } ] response = client.messages.create( model="claude-opus-4-6", 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: # Signal failure so Claude can retry or ask for clarification. 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-4-6", 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 // Ring 4: Error handling. // Source for in build-a-tool-using-agent.mdx. 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`); const messages: Anthropic.MessageParam[] = [ { role: "user", content: `Schedule an all-hands with everyone: ${emails.join(", ")}`, }, ]; let response = await client.messages.create({ model: "claude-opus-4-6", 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) { // Signal failure so Claude can retry or ask for clarification. 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-4-6", max_tokens: 1024, tools, messages, }); } for (const block of response.content) { if (block.type === "text") { console.log(block.text); } } ```` **What to expect** ```text Output 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. ``` The `is_error` flag is the only difference from a successful result. Claude sees the flag and the error text, and responds accordingly. See [Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls) for the full error-handling reference. ## Ring 5: The Tool Runner SDK abstraction Rings 2 through 4 wrote the same loop by hand: call the API, check `stop_reason`, run tools, append results, repeat. The Tool Runner does this for you. Define each tool as a function, pass the list to `tool_runner`, and retrieve the final message once the loop completes. Error wrapping, result formatting, and conversation management are handled internally. The Python SDK uses the `@beta_tool` decorator to infer the schema from type hints and the docstring. The TypeScript SDK uses `betaZodTool` with a Zod schema. Tool Runner is available in the Python, TypeScript, and Ruby SDKs. The cURL and CLI tabs show a note instead of code; keep the Ring 4 loop for curl- or CLI-based scripts. ````bash #!/bin/bash # Ring 5: The Tool Runner SDK abstraction. # Source for in build-a-tool-using-agent.mdx. # The Tool Runner SDK abstraction is available in the Python, TypeScript, # and Ruby SDKs. There is no equivalent for raw curl requests. Switch to # the Python or TypeScript tab to see Ring 5, or keep the Ring 4 loop as # your shell implementation. ```` ````bash #!/usr/bin/env bash # Ring 5: The Tool Runner SDK abstraction. # Source for in build-a-tool-using-agent.mdx. set -euo pipefail # The Tool Runner SDK abstraction is available in the Python, TypeScript, # and Ruby SDKs. The ant CLI exposes the Messages API directly and has # no equivalent helper. Switch to the Python or TypeScript tab to see # Ring 5, or keep the Ring 4 loop as your CLI implementation. ```` ````python # Ring 5: The Tool Runner SDK abstraction. # Source for in build-a-tool-using-agent.mdx. 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-4-6", max_tokens=1024, tools=[create_calendar_event, list_calendar_events], messages=[ { "role": "user", "content": "Check what I have next Monday, then schedule a planning session that avoids any conflicts.", } ], ).until_done() for block in final_message.content: if block.type == "text": print(block.text) ```` ````typescript // Ring 5: The Tool Runner SDK abstraction. // Source for in build-a-tool-using-agent.mdx. 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-4-6", max_tokens: 1024, tools: [createCalendarEvent, listCalendarEvents], messages: [ { role: "user", content: "Check what I have next Monday, then schedule a planning session that avoids any conflicts.", }, ], }); for (const block of finalMessage.content) { if (block.type === "text") { console.log(block.text); } } ```` **What to expect** ```text Output I checked your calendar for next Monday and found an existing meeting from 2pm to 3pm. I've scheduled the planning session for 10am to 11am to avoid the conflict. ``` The output is identical to Ring 3. The difference is in the code: roughly half the lines, no manual loop, and the schema lives next to the implementation. ## What you built You started with a single hardcoded tool call and ended with a production-shaped agent that handles multiple tools, parallel calls, and errors, then collapsed all of that into the Tool Runner. Along the way you saw every piece of the tool-use protocol: `tool_use` blocks, `tool_result` blocks, `tool_use_id` matching, `stop_reason` checking, and `is_error` signaling. ## Next steps Schema specification and best practices. The full SDK abstraction reference. Fix common tool-use errors. --- # Web fetch tool URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool # Web fetch tool Fetch and read content from specific URLs to augment Claude's context with live web content. --- The web fetch tool allows Claude to retrieve full content from specified web pages and PDF documents. The latest web fetch tool version (`web_fetch_20260209`) supports **dynamic filtering** with [Claude Mythos Preview](https://anthropic.com/glasswing), Claude Opus 4.7, Claude Opus 4.6, and Claude Sonnet 4.6. Claude can write and execute code to filter fetched content before it reaches the context window, keeping only relevant information and discarding the rest. This reduces token consumption while maintaining response quality. The previous tool version (`web_fetch_20250910`) remains available without dynamic filtering. For [Claude Mythos Preview](https://anthropic.com/glasswing), web fetch is supported on the Claude API and Microsoft Foundry only. It is not available for Mythos Preview on Amazon Bedrock or Vertex AI. Use the [feedback form](https://forms.gle/NhWcgmkcvPCMmPE86) to provide feedback on the quality of the model responses, the API itself, or the quality of the documentation. For Zero Data Retention eligibility and the `allowed_callers` workaround, see [Server tools](/docs/en/agents-and-tools/tool-use/server-tools#zdr-and-allowed-callers). Enabling the web fetch tool in environments where Claude processes untrusted input alongside sensitive data poses data exfiltration risks. Only use this tool in trusted environments or when handling non-sensitive data. To minimize exfiltration risks, Claude is not allowed to dynamically construct URLs. Claude can only fetch URLs that have been explicitly provided by the user or that come from previous web search or web fetch results. However, there is still residual risk that should be carefully considered when using this tool. If data exfiltration is a concern, consider: - Disabling the web fetch tool entirely - Using the `max_uses` parameter to limit the number of requests - Using the `allowed_domains` parameter to restrict to known safe domains For model support, see the [Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference). ## How web fetch works When you add the web fetch tool to your API request: 1. Claude decides when to fetch content based on the prompt and available URLs. 2. The API retrieves the full text content from the specified URL. 3. For PDFs, automatic text extraction is performed. 4. Claude analyzes the fetched content and provides a response with optional citations. The web fetch tool currently does not support websites dynamically rendered with JavaScript. ### Dynamic filtering Fetching full web pages and PDFs can quickly consume tokens, especially when only specific information is needed from large documents. With the `web_fetch_20260209` tool version, Claude can write and execute code to filter the fetched content before loading it into context. This dynamic filtering is particularly useful for: - Extracting specific sections from long documents - Processing structured data from web pages - Filtering relevant information from PDFs - Reducing token costs when working with large documents Dynamic filtering requires the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool) to be enabled. The web fetch tool (with and without dynamic filtering) is available on the Claude API, [Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws), and [Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry). It is not available on Amazon Bedrock or Vertex AI. To enable dynamic filtering, use the `web_fetch_20260209` tool version: ```bash cURL curl https://api.anthropic.com/v1/messages \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --data '{ "model": "claude-opus-4-7", "max_tokens": 4096, "messages": [ { "role": "user", "content": "Fetch the content at https://example.com/research-paper and extract the key findings." } ], "tools": [{ "type": "web_fetch_20260209", "name": "web_fetch" }] }' ``` ```bash CLI ant messages create <<'YAML' model: claude-opus-4-7 max_tokens: 4096 messages: - role: user content: >- Fetch the content at https://example.com/research-paper and extract the key findings. tools: - type: web_fetch_20260209 name: web_fetch YAML ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-4-7", max_tokens=4096, messages=[ { "role": "user", "content": "Fetch the content at https://example.com/research-paper and extract the key findings.", } ], tools=[{"type": "web_fetch_20260209", "name": "web_fetch"}], ) print(response) ``` ```typescript TypeScript hidelines={1..5,-3..-1} import { Anthropic } from "@anthropic-ai/sdk"; const anthropic = new Anthropic(); async function main() { const response = await anthropic.messages.create({ model: "claude-opus-4-7", max_tokens: 4096, messages: [ { role: "user", content: "Fetch the content at https://example.com/research-paper and extract the key findings." } ], tools: [{ type: "web_fetch_20260209", name: "web_fetch" }] }); console.log(response); } main().catch(console.error); ``` ```csharp C# hidelines={1..3} using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 4096, Messages = [new() { Role = Role.User, Content = "Fetch the content at https://example.com/research-paper and extract the key findings." }], Tools = [new ToolUnion(new WebFetchTool20260209())] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Fetch the content at https://example.com/research-paper and extract the key findings.")), }, Tools: []anthropic.ToolUnionParam{ {OfWebFetchTool20260209: &anthropic.WebFetchTool20260209Param{}}, }, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```java Java hidelines={1..5} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; import com.anthropic.models.messages.WebFetchTool20260209; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(4096L) .addUserMessage("Fetch the content at https://example.com/research-paper and extract the key findings.") .addTool(WebFetchTool20260209.builder().build()) .build(); Message response = client.messages().create(params); IO.println(response); } ``` ```php PHP hidelines={1..4} messages->create( maxTokens: 4096, messages: [ ['role' => 'user', 'content' => 'Fetch the content at https://example.com/research-paper and extract the key findings.'] ], model: 'claude-opus-4-7', tools: [[ 'type' => 'web_fetch_20260209', 'name' => 'web_fetch', ]], ); echo $message; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-7", max_tokens: 4096, messages: [ { role: "user", content: "Fetch the content at https://example.com/research-paper and extract the key findings." } ], tools: [{ type: "web_fetch_20260209", name: "web_fetch" }] ) puts message ``` ## How to use web fetch Provide the web fetch tool in your API request: ```bash cURL curl https://api.anthropic.com/v1/messages \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --data '{ "model": "claude-opus-4-7", "max_tokens": 1024, "messages": [ { "role": "user", "content": "Please analyze the content at https://example.com/article" } ], "tools": [{ "type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5 }] }' ``` ```bash CLI ant messages create \ --model claude-opus-4-7 \ --max-tokens 1024 \ --message '{role: user, content: "Please analyze the content at https://example.com/article"}' \ --tool '{type: web_fetch_20250910, name: web_fetch, max_uses: 5}' ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-4-7", max_tokens=1024, messages=[ { "role": "user", "content": "Please analyze the content at https://example.com/article", } ], tools=[{"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5}], ) print(response) ``` ```typescript TypeScript hidelines={1..5,-3..-1} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); async function main() { const response = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 1024, messages: [ { role: "user", content: "Please analyze the content at https://example.com/article" } ], tools: [ { type: "web_fetch_20250910", name: "web_fetch", max_uses: 5 } ] }); console.log(response); } main().catch(console.error); ``` ```csharp C# hidelines={1..3} using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "Please analyze the content at https://example.com/article" }], Tools = [new ToolUnion(new WebFetchTool20250910() { MaxUses = 5 })] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Please analyze the content at https://example.com/article")), }, Tools: []anthropic.ToolUnionParam{ {OfWebFetchTool20250910: &anthropic.WebFetchTool20250910Param{ MaxUses: anthropic.Int(5), }}, }, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```java Java hidelines={1..5} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; import com.anthropic.models.messages.WebFetchTool20250910; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(1024L) .addUserMessage("Please analyze the content at https://example.com/article") .addTool(WebFetchTool20250910.builder() .maxUses(5L) .build()) .build(); Message response = client.messages().create(params); IO.println(response); } ``` ```php PHP hidelines={1..4} messages->create( maxTokens: 1024, messages: [ ['role' => 'user', 'content' => 'Please analyze the content at https://example.com/article'] ], model: 'claude-opus-4-7', tools: [[ 'type' => 'web_fetch_20250910', 'name' => 'web_fetch', 'max_uses' => 5, ]], ); echo $message; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-7", max_tokens: 1024, messages: [ { role: "user", content: "Please analyze the content at https://example.com/article" } ], tools: [{ type: "web_fetch_20250910", name: "web_fetch", max_uses: 5 }] ) puts message ``` ### Tool definition The web fetch tool supports the following parameters: ```json JSON { "type": "web_fetch_20250910", "name": "web_fetch", // Optional: Limit the number of fetches per request "max_uses": 10, // Optional: Only fetch from these domains "allowed_domains": ["example.com", "docs.example.com"], // Optional: Never fetch from these domains "blocked_domains": ["private.example.com"], // Optional: Enable citations for fetched content "citations": { "enabled": true }, // Optional: Maximum content length in tokens "max_content_tokens": 100000 } ``` #### Max uses The `max_uses` parameter limits the number of web fetches performed. If Claude attempts more fetches than allowed, the `web_fetch_tool_result` is an error with the `max_uses_exceeded` error code. There is currently no default limit. #### Domain filtering For domain filtering with `allowed_domains` and `blocked_domains`, see [Server tools](/docs/en/agents-and-tools/tool-use/server-tools#domain-filtering). #### Content limits The `max_content_tokens` parameter limits the amount of content included in the context. If the fetched content exceeds this limit, the tool truncates it. This helps control token usage when fetching large documents. The `max_content_tokens` parameter limit is approximate. The actual number of input tokens used can vary by a small amount. #### Citations Unlike web search where citations are always enabled, citations are optional for web fetch. Set `"citations": {"enabled": true}` to enable Claude to cite specific passages from fetched documents. When displaying API outputs directly to end users, citations must be included to the original source. If you are making modifications to API outputs, including by reprocessing and/or combining them with your own material before displaying them to end users, display citations as appropriate based on consultation with your legal team. ### Response Here's an example response structure: ```json Output { "role": "assistant", "content": [ // 1. Claude's decision to fetch { "type": "text", "text": "I'll fetch the content from the article to analyze it." }, // 2. The fetch request { "type": "server_tool_use", "id": "srvtoolu_01234567890abcdef", "name": "web_fetch", "input": { "url": "https://example.com/article" } }, // 3. Fetch results { "type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_01234567890abcdef", "content": { "type": "web_fetch_result", "url": "https://example.com/article", "content": { "type": "document", "source": { "type": "text", "media_type": "text/plain", "data": "Full text content of the article..." }, "title": "Article Title", "citations": { "enabled": true } }, "retrieved_at": "2025-08-25T10:30:00Z" } }, // 4. Claude's analysis with citations (if enabled) { "text": "Based on the article, ", "type": "text" }, { "text": "the main argument presented is that artificial intelligence will transform healthcare", "type": "text", "citations": [ { "type": "char_location", "document_index": 0, "document_title": "Article Title", "start_char_index": 1234, "end_char_index": 1456, "cited_text": "Artificial intelligence is poised to revolutionize healthcare delivery..." } ] } ], "id": "msg_a930390d3a", "usage": { "input_tokens": 25039, "output_tokens": 931, "server_tool_use": { "web_fetch_requests": 1 } }, "stop_reason": "end_turn" } ``` #### Fetch results Fetch results include: - `url`: The URL that was fetched - `content`: A document block containing the fetched content - `retrieved_at`: Timestamp when the content was retrieved The web fetch tool caches results to improve performance and reduce redundant requests. The content returned may not always reflect the latest version available at the URL. The cache behavior is managed automatically and may change over time to optimize for different content types and usage patterns. For PDF documents, content is returned as base64-encoded data: ```json Output { "type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_02", "content": { "type": "web_fetch_result", "url": "https://example.com/paper.pdf", "content": { "type": "document", "source": { "type": "base64", "media_type": "application/pdf", "data": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmo..." }, "citations": { "enabled": true } }, "retrieved_at": "2025-08-25T10:30:02Z" } } ``` #### Errors When the web fetch tool encounters an error, the Claude API returns a 200 (success) response with the error represented in the response body: ```json Output { "type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_a93jad", "content": { "type": "web_fetch_tool_error", "error_code": "url_not_accessible" } } ``` These are the possible error codes: - `invalid_input`: Invalid URL format - `url_too_long`: URL exceeds maximum length (250 characters) - `url_not_allowed`: URL blocked by domain filtering rules and model restrictions - `url_not_accessible`: Failed to fetch content (HTTP error) - `too_many_requests`: Rate limit exceeded - `unsupported_content_type`: Content type not supported (only text and PDF) - `max_uses_exceeded`: Maximum web fetch tool uses exceeded - `unavailable`: An internal error occurred ## URL validation For security reasons, the web fetch tool can only fetch URLs that have previously appeared in the conversation context. This includes: - URLs in user messages - URLs in client-side tool results - URLs from previous web search or web fetch results The tool cannot fetch arbitrary URLs that Claude generates or URLs from container-based server tools (Code Execution, Bash, etc.). ## Combined search and fetch Web fetch works seamlessly with web search for comprehensive information gathering: ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-4-7", max_tokens=4096, messages=[ { "role": "user", "content": "Find recent articles about quantum computing and analyze the most relevant one in detail", } ], tools=[ {"type": "web_search_20250305", "name": "web_search", "max_uses": 3}, { "type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5, "citations": {"enabled": True}, }, ], ) print(response) ``` In this workflow, Claude will: 1. Use web search to find relevant articles 2. Select the most promising results 3. Use web fetch to retrieve full content 4. Provide detailed analysis with citations ## Prompt caching For caching tool definitions across turns, see [Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching). ## Streaming With streaming enabled, fetch events are part of the stream with a pause during content retrieval: ```sse Output event: message_start data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}} event: content_block_start data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}} // Claude's decision to fetch event: content_block_start data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_fetch"}} // Fetch URL streamed event: content_block_delta data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"url\":\"https://example.com/article\"}"}} // Pause while fetch executes // Fetch results streamed event: content_block_start data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "web_fetch_result", "url": "https://example.com/article", "content": {"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "Article content..."}}}}} // Claude's response continues... ``` ## Batch requests You can include the web fetch tool in the [Messages Batches API](/docs/en/build-with-claude/batch-processing). Web fetch tool calls through the Messages Batches API are priced the same as those in regular Messages API requests. ## Usage and pricing Web fetch usage has **no additional charges** beyond standard token costs: ```json "usage": { "input_tokens": 25039, "output_tokens": 931, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0, "server_tool_use": { "web_fetch_requests": 1 } } ``` The web fetch tool is available on the Claude API at **no additional cost**. You only pay standard token costs for the fetched content that becomes part of your conversation context. To protect against inadvertently fetching large content that would consume excessive tokens, use the `max_content_tokens` parameter to set appropriate limits based on your use case and budget considerations. Example token usage for typical content: - Average web page (10 kB): ~2,500 tokens - Large documentation page (100 kB): ~25,000 tokens - Research paper PDF (500 kB): ~125,000 tokens ## Next steps Shared mechanics for Anthropic-executed tools. Directory of all Anthropic-provided tools. --- # Web search tool URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool # Web search tool --- The web search tool gives Claude direct access to real-time web content, allowing it to answer questions with up-to-date information beyond its knowledge cutoff. The response includes citations for sources drawn from search results. The latest web search tool version (`web_search_20260209`) supports **dynamic filtering** with [Claude Mythos Preview](https://anthropic.com/glasswing), Claude Opus 4.7, Claude Opus 4.6, and Claude Sonnet 4.6. Claude can write and execute code to filter search results before they reach the context window, keeping only relevant information and discarding the rest. This leads to more accurate responses while reducing token consumption. The previous tool version (`web_search_20250305`) remains available without dynamic filtering. For [Claude Mythos Preview](https://anthropic.com/glasswing), web search is supported on the Claude API, Microsoft Foundry, and Vertex AI. Web search is not available for Mythos Preview on Amazon Bedrock or [Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws). For Zero Data Retention eligibility and the `allowed_callers` workaround, see [Server tools](/docs/en/agents-and-tools/tool-use/server-tools#zdr-and-allowed-callers). For model support, see the [Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference). ## How web search works When you add the web search tool to your API request: 1. Claude decides when to search based on the prompt. 2. The API executes the searches and provides Claude with the results. This process may repeat multiple times throughout a single request. 3. At the end of its turn, Claude provides a final response with cited sources. ### Dynamic filtering Web search is a token-intensive task. With basic web search, Claude needs to pull search results into context, fetch full HTML from multiple websites, and reason over all of it before arriving at an answer. Often, much of this content is irrelevant, which can degrade response quality. With the `web_search_20260209` tool version, Claude can write and execute code to post-process query results. Instead of reasoning over full HTML files, Claude dynamically filters search results before loading them into context, keeping only what's relevant and discarding the rest. Dynamic filtering is particularly effective for: - Searching through technical documentation - Literature review and citation verification - Technical research - Response grounding and verification Dynamic filtering requires the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool) to be enabled. The web search tool (with and without dynamic filtering) is available on the Claude API, [Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws), and [Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry). On Vertex AI, only the basic web search tool (without dynamic filtering) is available. Web search is not available on Amazon Bedrock. To enable dynamic filtering, use the `web_search_20260209` tool version: ```bash cURL curl https://api.anthropic.com/v1/messages \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --data '{ "model": "claude-opus-4-7", "max_tokens": 4096, "messages": [ { "role": "user", "content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio." } ], "tools": [{ "type": "web_search_20260209", "name": "web_search" }] }' ``` ```bash CLI ant messages create <<'YAML' model: claude-opus-4-7 max_tokens: 4096 messages: - role: user content: >- Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio. tools: - type: web_search_20260209 name: web_search YAML ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-4-7", max_tokens=4096, messages=[ { "role": "user", "content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.", } ], tools=[{"type": "web_search_20260209", "name": "web_search"}], ) print(response) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const anthropic = new Anthropic(); const response = await anthropic.messages.create({ model: "claude-opus-4-7", max_tokens: 4096, messages: [ { role: "user", content: "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio." } ], tools: [{ type: "web_search_20260209", name: "web_search" }] }); console.log(response); ``` ```csharp C# hidelines={1..3} using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 4096, Messages = [new() { Role = Role.User, Content = "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio." }], Tools = [new ToolUnion(new WebSearchTool20260209())] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.")), }, Tools: []anthropic.ToolUnionParam{ {OfWebSearchTool20260209: &anthropic.WebSearchTool20260209Param{}}, }, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```java Java hidelines={1..5} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; import com.anthropic.models.messages.WebSearchTool20260209; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(4096L) .addUserMessage("Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.") .addTool(WebSearchTool20260209.builder().build()) .build(); Message response = client.messages().create(params); IO.println(response); } ``` ```php PHP hidelines={1..4} messages->create( maxTokens: 4096, messages: [ ['role' => 'user', 'content' => 'Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.'], ], model: 'claude-opus-4-7', tools: [ [ 'type' => 'web_search_20260209', 'name' => 'web_search', ], ], ); echo $message; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-7", max_tokens: 4096, messages: [ { role: "user", content: "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio." } ], tools: [{ type: "web_search_20260209", name: "web_search" }] ) puts message ``` ## How to use web search Your organization's administrator must enable web search in the [Claude Console](/settings/privacy). Provide the web search tool in your API request: ```bash cURL curl https://api.anthropic.com/v1/messages \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --data '{ "model": "claude-opus-4-7", "max_tokens": 1024, "messages": [ { "role": "user", "content": "What is the weather in NYC?" } ], "tools": [{ "type": "web_search_20250305", "name": "web_search", "max_uses": 5 }] }' ``` ```bash CLI ant messages create \ --model claude-opus-4-7 \ --max-tokens 1024 \ --message '{role: user, content: What is the weather in NYC?}' \ --tool '{type: web_search_20250305, name: web_search, max_uses: 5}' ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-4-7", max_tokens=1024, messages=[{"role": "user", "content": "What's the weather in NYC?"}], tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}], ) print(response) ``` ```typescript TypeScript hidelines={1..5,-3..-1} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); async function main() { const response = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 1024, messages: [ { role: "user", content: "What's the weather in NYC?" } ], tools: [ { type: "web_search_20250305", name: "web_search", max_uses: 5 } ] }); console.log(response); } main().catch(console.error); ``` ```csharp C# hidelines={1..3} using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "What's the weather in NYC?" }], Tools = [new ToolUnion(new WebSearchTool20250305() { MaxUses = 5 })] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in NYC?")), }, Tools: []anthropic.ToolUnionParam{ {OfWebSearchTool20250305: &anthropic.WebSearchTool20250305Param{ MaxUses: anthropic.Int(5), }}, }, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```java Java hidelines={1..5} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; import com.anthropic.models.messages.WebSearchTool20250305; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(1024L) .addUserMessage("What's the weather in NYC?") .addTool(WebSearchTool20250305.builder() .maxUses(5L) .build()) .build(); Message response = client.messages().create(params); IO.println(response); } ``` ```php PHP hidelines={1..4} messages->create( maxTokens: 1024, messages: [ ['role' => 'user', 'content' => "What's the weather in NYC?"], ], model: 'claude-opus-4-7', tools: [ [ 'type' => 'web_search_20250305', 'name' => 'web_search', 'max_uses' => 5, ], ], ); echo $message; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-7", max_tokens: 1024, messages: [ { role: "user", content: "What's the weather in NYC?" } ], tools: [{ type: "web_search_20250305", name: "web_search", max_uses: 5 }] ) puts message ``` ### Tool definition The web search tool supports the following parameters: ```json JSON { "type": "web_search_20250305", "name": "web_search", // Optional: Limit the number of searches per request "max_uses": 5, // Optional: Only include results from these domains "allowed_domains": ["example.com", "trusteddomain.org"], // Optional: Never include results from these domains "blocked_domains": ["untrustedsource.com"], // Optional: Localize search results "user_location": { "type": "approximate", "city": "San Francisco", "region": "California", "country": "US", "timezone": "America/Los_Angeles" } } ``` #### Max uses The `max_uses` parameter limits the number of searches performed. If Claude attempts more searches than allowed, the `web_search_tool_result` is an error with the `max_uses_exceeded` error code. #### Domain filtering For domain filtering with `allowed_domains` and `blocked_domains`, see [Server tools](/docs/en/agents-and-tools/tool-use/server-tools#domain-filtering). #### Localization The `user_location` parameter allows you to localize search results based on a user's location. - `type`: The type of location (must be `approximate`) - `city`: The city name - `region`: The region or state - `country`: The country - `timezone`: The [IANA timezone ID](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). ### Response Here's an example response structure: ```json Output { "role": "assistant", "content": [ // 1. Claude's decision to search { "type": "text", "text": "I'll search for when Claude Shannon was born." }, // 2. The search query used { "type": "server_tool_use", "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE", "name": "web_search", "input": { "query": "claude shannon birth date" } }, // 3. Search results { "type": "web_search_tool_result", "tool_use_id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE", "content": [ { "type": "web_search_result", "url": "https://en.wikipedia.org/wiki/Claude_Shannon", "title": "Claude Shannon - Wikipedia", "encrypted_content": "EqgfCioIARgBIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...", "page_age": "April 30, 2025" } ] }, { "text": "Based on the search results, ", "type": "text" }, // 4. Claude's response with citations { "text": "Claude Shannon was born on April 30, 1916, in Petoskey, Michigan", "type": "text", "citations": [ { "type": "web_search_result_location", "url": "https://en.wikipedia.org/wiki/Claude_Shannon", "title": "Claude Shannon - Wikipedia", "encrypted_index": "Eo8BCioIAhgBIiQyYjQ0OWJmZi1lNm..", "cited_text": "Claude Elwood Shannon (April 30, 1916 – February 24, 2001) was an American mathematician, electrical engineer, computer scientist, cryptographer and i..." } ] } ], "id": "msg_a930390d3a", "usage": { "input_tokens": 6039, "output_tokens": 931, "server_tool_use": { "web_search_requests": 1 } }, "stop_reason": "end_turn" } ``` #### Search results Search results include: - `url`: The URL of the source page - `title`: The title of the source page - `page_age`: When the site was last updated - `encrypted_content`: Encrypted content that must be passed back in multi-turn conversations for citations #### Citations Citations are always enabled for web search, and each `web_search_result_location` includes: - `url`: The URL of the cited source - `title`: The title of the cited source - `encrypted_index`: A reference that must be passed back for multi-turn conversations. - `cited_text`: Up to 150 characters of the cited content The web search citation fields `cited_text`, `title`, and `url` do not count towards input or output token usage. When displaying API outputs directly to end users, citations must be included to the original source. If you are making modifications to API outputs, including by reprocessing and/or combining them with your own material before displaying them to end users, display citations as appropriate based on consultation with your legal team. #### Errors When the web search tool encounters an error (such as hitting rate limits), the Claude API still returns a 200 (success) response. The error is represented within the response body using the following structure: ```json Output { "type": "web_search_tool_result", "tool_use_id": "srvtoolu_a93jad", "content": { "type": "web_search_tool_result_error", "error_code": "max_uses_exceeded" } } ``` These are the possible error codes: - `too_many_requests`: Rate limit exceeded - `invalid_input`: Invalid search query parameter - `max_uses_exceeded`: Maximum web search tool uses exceeded - `query_too_long`: Query exceeds maximum length - `unavailable`: An internal error occurred #### `pause_turn` stop reason For continuing after a `pause_turn` stop reason, see [Server tools](/docs/en/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn). ## Prompt caching For caching tool definitions across turns, see [Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching). ## Streaming With streaming enabled, you'll receive search events as part of the stream. There will be a pause while the search executes: ```sse Output event: message_start data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}} event: content_block_start data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}} // Claude's decision to search event: content_block_start data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}} // Search query streamed event: content_block_delta data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}} // Pause while search executes // Search results streamed event: content_block_start data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "web_search_result", "title": "Quantum Computing Breakthroughs in 2025", "url": "https://example.com"}]}} // Claude's response with citations (omitted in this example) ``` ## Batch requests You can include the web search tool in the [Messages Batches API](/docs/en/build-with-claude/batch-processing). Web search tool calls through the Messages Batches API are priced the same as those in regular Messages API requests. ## Usage and pricing Web search usage is charged in addition to token usage: ```json "usage": { "input_tokens": 105, "output_tokens": 6039, "cache_read_input_tokens": 7123, "cache_creation_input_tokens": 7345, "server_tool_use": { "web_search_requests": 1 } } ``` Web search is available on the Claude API for **$10 per 1,000 searches**, plus standard token costs for search-generated content. Web search results retrieved throughout a conversation are counted as input tokens, in search iterations executed during a single turn and in subsequent conversation turns. Each web search counts as one use, regardless of the number of results returned. If an error occurs during web search, the web search will not be billed. ## Next steps Shared mechanics for Anthropic-executed tools. Directory of all Anthropic-provided tools. ### Tool infrastructure --- # Fine-grained tool streaming URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming # Fine-grained tool streaming Stream tool inputs character-by-character for latency-sensitive applications. --- This feature is eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned. Fine-grained tool streaming is available on all models and all platforms. It enables [streaming](/docs/en/build-with-claude/streaming) of tool use parameter values without buffering or JSON validation, reducing the latency to begin receiving large parameters. When using fine-grained tool streaming, you may potentially receive invalid or partial JSON inputs. Make sure to account for these edge cases in your code. ## How to use fine-grained tool streaming Fine-grained tool streaming is supported on the Claude API, [Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws), [Amazon Bedrock](/docs/en/build-with-claude/claude-in-amazon-bedrock), [Vertex AI](/docs/en/build-with-claude/claude-on-vertex-ai), and [Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry). To use it, set `eager_input_streaming` to `true` on any user-defined tool where you want fine-grained streaming enabled, and enable streaming on your request. Here's an example of how to use fine-grained tool streaming with the API: ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "content-type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-opus-4-7", "max_tokens": 65536, "tools": [ { "name": "make_file", "description": "Write text to a file", "eager_input_streaming": true, "input_schema": { "type": "object", "properties": { "filename": { "type": "string", "description": "The filename to write text to" }, "lines_of_text": { "type": "array", "description": "An array of lines of text to write to the file" } }, "required": ["filename", "lines_of_text"] } } ], "messages": [ { "role": "user", "content": "Can you write a long poem and make a file called poem.txt?" } ], "stream": true }' ``` ```bash CLI ant messages create --stream \ --transform usage <<'YAML' model: claude-opus-4-7 max_tokens: 65536 tools: - name: make_file description: Write text to a file eager_input_streaming: true input_schema: type: object properties: filename: type: string description: The filename to write text to lines_of_text: type: array description: An array of lines of text to write to the file required: - filename - lines_of_text messages: - role: user content: Can you write a long poem and make a file called poem.txt? YAML ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() with client.messages.stream( max_tokens=65536, model="claude-opus-4-7", tools=[ { "name": "make_file", "description": "Write text to a file", "eager_input_streaming": True, "input_schema": { "type": "object", "properties": { "filename": { "type": "string", "description": "The filename to write text to", }, "lines_of_text": { "type": "array", "description": "An array of lines of text to write to the file", }, }, "required": ["filename", "lines_of_text"], }, } ], messages=[ { "role": "user", "content": "Can you write a long poem and make a file called poem.txt?", } ], ) as stream: for event in stream: pass final_message = stream.get_final_message() print(final_message.usage) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const anthropic = new Anthropic(); const stream = anthropic.messages.stream({ model: "claude-opus-4-7", max_tokens: 65536, tools: [ { name: "make_file", description: "Write text to a file", eager_input_streaming: true, input_schema: { type: "object", properties: { filename: { type: "string", description: "The filename to write text to" }, lines_of_text: { type: "array", description: "An array of lines of text to write to the file" } }, required: ["filename", "lines_of_text"] } } ], messages: [ { role: "user", content: "Can you write a long poem and make a file called poem.txt?" } ] }); const message = await stream.finalMessage(); console.log(message.usage); ``` In this example, fine-grained tool streaming enables Claude to stream the lines of a long poem into the tool call `make_file` without buffering to validate if the `lines_of_text` parameter is valid JSON. This means you can see the parameter stream as it arrives, without having to wait for the entire parameter to buffer and validate. With fine-grained tool streaming, tool use chunks start streaming faster, and are often longer and contain fewer word breaks. This is because of differences in chunking behavior. Example: Without fine-grained streaming (15s delay): ```text Chunk 1: '{"' Chunk 2: 'query": "Ty' Chunk 3: 'peScri' Chunk 4: 'pt 5.0 5.1 ' Chunk 5: '5.2 5' Chunk 6: '.3' Chunk 7: ' new f' Chunk 8: 'eatur' ... ``` With fine-grained streaming (3s delay): ```text Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3' Chunk 2: ' new features comparison' ``` Because fine-grained streaming sends parameters without buffering or JSON validation, there is no guarantee that the resulting stream will complete in a valid JSON string. Particularly, if the [stop reason](/docs/en/build-with-claude/handling-stop-reasons) `max_tokens` is reached, the stream may end midway through a parameter and may be incomplete. You generally have to write specific support to handle when `max_tokens` is reached. ## Accumulating tool input deltas When a `tool_use` content block streams, the initial `content_block_start` event contains `input: {}` (an empty object). This is a placeholder. The actual input arrives as a series of `input_json_delta` events, each carrying a `partial_json` string fragment. Your code must concatenate these fragments and parse the result once the block closes. The accumulation contract: 1. On `content_block_start` with `type: "tool_use"`, initialize an empty string: `input_json = ""` 2. For each `content_block_delta` with `type: "input_json_delta"`, append: `input_json += event.delta.partial_json` 3. On `content_block_stop`, parse the accumulated string: `json.loads(input_json)` The type mismatch between the initial `input: {}` (object) and `partial_json` (string) is by design. The empty object marks the slot in the content array; the delta strings build the real value. ```python Python import json import anthropic client = anthropic.Anthropic() tool_inputs = {} # index -> accumulated JSON string with client.messages.stream( model="claude-opus-4-7", max_tokens=1024, tools=[ { "name": "get_weather", "description": "Get current weather for a city", "eager_input_streaming": True, "input_schema": { "type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"], }, } ], messages=[{"role": "user", "content": "Weather in Paris?"}], ) as stream: for event in stream: if ( event.type == "content_block_start" and event.content_block.type == "tool_use" ): tool_inputs[event.index] = "" elif ( event.type == "content_block_delta" and event.delta.type == "input_json_delta" ): tool_inputs[event.index] += event.delta.partial_json elif event.type == "content_block_stop" and event.index in tool_inputs: parsed = json.loads(tool_inputs[event.index]) print(f"Tool input: {parsed}") ``` ```typescript TypeScript hidelines={1..4} import Anthropic from "@anthropic-ai/sdk"; const anthropic = new Anthropic(); const toolInputs: Record = {}; const stream = anthropic.messages.stream({ model: "claude-opus-4-7", max_tokens: 1024, tools: [ { name: "get_weather", description: "Get current weather for a city", eager_input_streaming: true, input_schema: { type: "object", properties: { city: { type: "string" } }, required: ["city"] } } ], messages: [{ role: "user", content: "Weather in Paris?" }] }); for await (const event of stream) { if (event.type === "content_block_start" && event.content_block.type === "tool_use") { toolInputs[event.index] = ""; } else if (event.type === "content_block_delta" && event.delta.type === "input_json_delta") { toolInputs[event.index] += event.delta.partial_json; } else if (event.type === "content_block_stop" && event.index in toolInputs) { const parsed = JSON.parse(toolInputs[event.index]); console.log("Tool input:", parsed); } } ``` The Python and TypeScript SDKs provide higher-level stream helpers (`stream.get_final_message()`, `stream.finalMessage()`) that perform this accumulation for you. Use the preceding manual pattern only when you need to react to partial input before the block closes, such as rendering a progress indicator or starting a downstream request early. ## Handling invalid JSON in tool responses When using fine-grained tool streaming, you may receive invalid or incomplete JSON from the model. If you need to pass this invalid JSON back to the model in an error response block, you may wrap it in a JSON object to ensure proper handling (with a reasonable key). For example: ```json { "INVALID_JSON": "" } ``` This approach helps the model understand that the content is invalid JSON while preserving the original malformed data for debugging purposes. When wrapping invalid JSON, make sure to properly escape any quotes or special characters in the invalid JSON string to maintain valid JSON structure in the wrapper object. ## Next steps Full reference for server-sent events and stream event types. Execute tools and return results in the required message format. Full directory of Anthropic-schema tools and their version strings. --- # Manage tool context URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/manage-tool-context # Manage tool context Choose between tool search, programmatic tool calling, prompt caching, and context editing to manage context bloat. --- Tool definitions and accumulated `tool_result` blocks consume your context window. Long-running agents with many tools or many turns can exhaust available context before the task is finished. Four approaches address this at different points in the pipeline. ## The four approaches Each approach targets a different source of context pressure. Pick the one that matches where your tokens are going. | Approach | What it reduces | When it fits | Learn more | | --- | --- | --- | --- | | Tool search | Tool definitions loaded upfront | Large toolsets (20+ tools) where most tools aren't needed every turn | [Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool) | | Programmatic tool calling | `tool_result` roundtrips | Chains of tool calls that can execute as a single script | [Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) | | Prompt caching | Token cost of repeated tool definitions | Stable toolsets across many requests | [Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching) | | Context editing | Old `tool_result` blocks in history | Long conversations where early results are no longer relevant | [Context editing](/docs/en/build-with-claude/context-editing) | ### Tool search Tool search keeps tool definitions out of the context window until Claude asks for them. Instead of sending 50 tool schemas upfront, you send a single `tool_search` tool and let Claude discover the rest on demand. This trades a small amount of latency (one extra turn to look up a tool) for a large reduction in baseline context usage. ### Programmatic tool calling Programmatic tool calling collapses a sequence of tool calls into a single code block that Claude writes and Anthropic's code execution sandbox runs. Rather than five roundtrips of `tool_use` and `tool_result`, Claude emits one script that calls all five functions from within the sandbox. The intermediate results never enter the conversation history. ### Prompt caching Prompt caching doesn't reduce the number of tokens in context, but it reduces what you pay for them on subsequent requests. If your tool definitions are stable, cache them once and reuse the cached prefix across thousands of requests. This is the right choice when the toolset is large but fixed. ### Context editing Context editing removes old `tool_result` blocks from the conversation history once they've served their purpose. A long agent loop might produce hundreds of intermediate results that were useful at the time but are now dead weight. Context editing lets you trim them without restarting the conversation. ## Combining approaches These approaches compose. A long-running agent might use tool search to keep the toolset lean, prompt caching to amortize the cost of the remaining definitions, and context editing to trim stale results as the conversation grows. Each solves a different part of the problem, so there's no conflict in using them together. A reasonable starting point for a high-volume agent: 1. Enable prompt caching on your tool definitions from day one. Cache writes carry a 25% markup over base input pricing, which pays back on the second request that hits the cache. 2. Add tool search once your toolset grows past roughly 20 tools or your baseline context usage becomes noticeable. 3. Add context editing once individual conversations start running long enough that early results become irrelevant. 4. Consider programmatic tool calling if you notice repetitive chains of small tool calls that could run as a single batch. ## Next steps Load tool definitions on demand instead of upfront. Collapse tool-call chains into a single executable script. Cache tool definitions across requests to cut token costs. Trim stale tool results from long-running conversations. --- # Programmatic tool calling URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling # Programmatic tool calling --- Programmatic tool calling allows Claude to write code that calls your tools programmatically within a [code execution](/docs/en/agents-and-tools/tool-use/code-execution-tool) container, rather than requiring round trips through the model for each tool invocation. This reduces latency for multi-tool workflows and decreases token consumption by allowing Claude to filter or process data before it reaches the model's context window. On agentic search benchmarks like [BrowseComp](https://arxiv.org/abs/2504.12516) and [DeepSearchQA](https://github.com/google-deepmind/deepsearchqa), which test multi-step web research and complex information retrieval, adding programmatic tool calling on top of basic search tools was the key factor that fully unlocked agent performance. The difference compounds fast in real workflows. Consider checking budget compliance across 20 employees: the traditional approach requires 20 separate model round-trips, pulling thousands of expense line items into the context along the way. With programmatic tool calling, a single script runs all 20 lookups, filters the results, and returns only the employees who exceeded their limits, shrinking what Claude needs to reason over from hundreds of kilobytes down to a handful of lines. For a deeper look at the inference and context costs that programmatic tool calling addresses, see [Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use). This feature requires the code execution tool to be enabled. This feature is **not** eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). Data is retained according to the feature's standard retention policy. ## Model compatibility Programmatic tool calling requires `code_execution_20260120`, which is supported on the following models: | Model | |-------| | Claude Opus 4.7 (`claude-opus-4-7`) | | Claude Opus 4.6 (`claude-opus-4-6`) | | Claude Sonnet 4.6 (`claude-sonnet-4-6`) | | Claude Opus 4.5 (`claude-opus-4-5-20251101`) | | Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`) | For the full code execution tool version matrix, see the [code execution tool model compatibility table](/docs/en/agents-and-tools/tool-use/code-execution-tool#model-compatibility). Programmatic tool calling is available on the Claude API, [Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws), and [Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry). It is not currently available on Amazon Bedrock or Vertex AI. ## Quick start Here's a simple example where Claude programmatically queries a database multiple times and aggregates results: ```bash cURL curl https://api.anthropic.com/v1/messages \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --data '{ "model": "claude-opus-4-7", "max_tokens": 4096, "messages": [ { "role": "user", "content": "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue" } ], "tools": [ { "type": "code_execution_20260120", "name": "code_execution" }, { "name": "query_database", "description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.", "input_schema": { "type": "object", "properties": { "sql": { "type": "string", "description": "SQL query to execute" } }, "required": ["sql"] }, "allowed_callers": ["code_execution_20260120"] } ] }' ``` ```bash CLI ant messages create <<'YAML' model: claude-opus-4-7 max_tokens: 4096 messages: - role: user content: >- Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue tools: - type: code_execution_20260120 name: code_execution - name: query_database description: >- Execute a SQL query against the sales database. Returns a list of rows as JSON objects. input_schema: type: object properties: sql: type: string description: SQL query to execute required: - sql allowed_callers: - code_execution_20260120 YAML ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-4-7", max_tokens=4096, messages=[ { "role": "user", "content": "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue", } ], tools=[ {"type": "code_execution_20260120", "name": "code_execution"}, { "name": "query_database", "description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.", "input_schema": { "type": "object", "properties": { "sql": {"type": "string", "description": "SQL query to execute"} }, "required": ["sql"], }, "allowed_callers": ["code_execution_20260120"], }, ], ) print(response) ``` ```typescript TypeScript hidelines={1..5,-3..-1} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); async function main() { const response = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 4096, messages: [ { role: "user", content: "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue" } ], tools: [ { type: "code_execution_20260120", name: "code_execution" }, { name: "query_database", description: "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.", input_schema: { type: "object" as const, properties: { sql: { type: "string", description: "SQL query to execute" } }, required: ["sql"] }, allowed_callers: ["code_execution_20260120"] } ] }); console.log(response); } main().catch(console.error); ``` ```csharp C# hidelines={1..13,-2..} using Anthropic; using Anthropic.Models.Messages; using System; using System.Collections.Generic; using System.Text.Json; using System.Threading.Tasks; class Program { static async Task Main(string[] args) { AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 4096, Messages = [ new() { Role = Role.User, Content = "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue" } ], Tools = [ new CodeExecutionTool20260120(), new ToolUnion(new Tool() { Name = "query_database", Description = "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.", InputSchema = new InputSchema() { Properties = new Dictionary { ["sql"] = JsonSerializer.SerializeToElement(new { type = "string", description = "SQL query to execute" }), }, Required = ["sql"], }, AllowedCallers = ["code_execution_20260120"] }), ] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); } } ``` ```go Go hidelines={1..13,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue")), }, Tools: []anthropic.ToolUnionParam{ {OfCodeExecutionTool20260120: &anthropic.CodeExecutionTool20260120Param{}}, {OfTool: &anthropic.ToolParam{ Name: "query_database", Description: anthropic.String("Execute a SQL query against the sales database. Returns a list of rows as JSON objects."), InputSchema: anthropic.ToolInputSchemaParam{ Properties: map[string]any{ "sql": map[string]any{ "type": "string", "description": "SQL query to execute", }, }, Required: []string{"sql"}, }, AllowedCallers: []string{"code_execution_20260120"}, }}, }, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```java Java hidelines={1..7,9..13,-2..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.core.JsonValue; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Tool; import com.anthropic.models.messages.Tool.InputSchema; import com.anthropic.models.messages.CodeExecutionTool20260120; import java.util.List; import java.util.Map; public class Main { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model("claude-opus-4-7") .maxTokens(4096L) .addUserMessage("Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue") .addTool(CodeExecutionTool20260120.builder().build()) .addTool(Tool.builder() .name("query_database") .description("Execute a SQL query against the sales database. Returns a list of rows as JSON objects.") .inputSchema(InputSchema.builder() .properties(JsonValue.from(Map.of( "sql", Map.of( "type", "string", "description", "SQL query to execute" ) ))) .putAdditionalProperty("required", JsonValue.from(List.of("sql"))) .build()) .allowedCallers(List.of(Tool.AllowedCaller.of("code_execution_20260120"))) .build()) .build(); Message response = client.messages().create(params); System.out.println(response); } } ``` ```php PHP hidelines={1..4} messages->create( maxTokens: 4096, messages: [ ['role' => 'user', 'content' => 'Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue'], ], model: 'claude-opus-4-7', tools: [ [ 'type' => 'code_execution_20260120', 'name' => 'code_execution', ], [ 'name' => 'query_database', 'description' => 'Execute a SQL query against the sales database. Returns a list of rows as JSON objects.', 'input_schema' => [ 'type' => 'object', 'properties' => [ 'sql' => [ 'type' => 'string', 'description' => 'SQL query to execute', ], ], 'required' => ['sql'], ], 'allowed_callers' => ['code_execution_20260120'], ], ], ); echo $message; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-7", max_tokens: 4096, messages: [ { role: "user", content: "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue" } ], tools: [ { type: "code_execution_20260120", name: "code_execution" }, { name: "query_database", description: "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.", input_schema: { type: "object", properties: { sql: { type: "string", description: "SQL query to execute" } }, required: ["sql"] }, allowed_callers: ["code_execution_20260120"] } ] ) puts message ``` ## How programmatic tool calling works When you configure a tool to be callable from code execution and Claude decides to use that tool: 1. Claude writes Python code that invokes the tool as a function, potentially including multiple tool calls and pre/post-processing logic 2. Claude runs this code in a sandboxed container through code execution 3. When a tool function is called, code execution pauses and the API returns a `tool_use` block 4. You provide the tool result, and code execution continues (intermediate results are not loaded into Claude's context window) 5. Once all code execution completes, Claude receives the final output and continues working on the task This approach is particularly useful for: - **Large data processing:** Filter or aggregate tool results before they reach Claude's context - **Multi-step workflows:** Save tokens and latency by calling tools serially or in a loop without sampling Claude in-between tool calls - **Conditional logic:** Make decisions based on intermediate tool results Custom tools are converted to async Python functions to support parallel tool calling. When Claude writes code that calls your tools, it uses `await` (e.g., `result = await query_database("")`) and automatically includes the appropriate async wrapper function. The async wrapper is omitted from code examples in this documentation for clarity. ## Core concepts ### The `allowed_callers` field The `allowed_callers` field specifies which contexts can invoke a tool: ```json { "name": "query_database", "description": "Execute a SQL query against the database", "input_schema": { // ... }, "allowed_callers": ["code_execution_20260120"] } ``` **Possible values:** - `["direct"]` - Only Claude can call this tool directly (default if omitted) - `["code_execution_20260120"]` - Only callable from within code execution - `["direct", "code_execution_20260120"]` - Callable both directly and from code execution Choose either `["direct"]` or `["code_execution_20260120"]` for each tool rather than enabling both, as this provides clearer guidance to Claude for how best to use the tool. ### The `caller` field in responses Every tool use block includes a `caller` field indicating how it was invoked: **Direct invocation (traditional tool use):** ```json { "type": "tool_use", "id": "toolu_abc123", "name": "query_database", "input": { "sql": "" }, "caller": { "type": "direct" } } ``` **Programmatic invocation:** ```json { "type": "tool_use", "id": "toolu_xyz789", "name": "query_database", "input": { "sql": "" }, "caller": { "type": "code_execution_20260120", "tool_id": "srvtoolu_abc123" } } ``` The `tool_id` references the code execution tool that made the programmatic call. ### Container lifecycle Programmatic tool calling uses the same containers as code execution: - **Container creation:** A new container is created for each request unless you reuse an existing one - **Expiration:** Containers have a 30-day maximum lifetime and are cleaned up after 4.5 minutes of idle time - **Container ID:** Returned in responses in the `container` field - **Reuse:** Pass the container ID to maintain state across requests When a tool is called programmatically and the container is waiting for your tool result, you must respond before the container expires. Monitor the `expires_at` field. If the container expires, Claude may treat the tool call as timed out and retry it. ## Example workflow Here's how a complete programmatic tool calling flow works: ### Step 1: Initial request Send a request with code execution and a tool that allows programmatic calling. To enable programmatic calling, add the `allowed_callers` field to your tool definition. Provide detailed descriptions of your tool's output format in the tool description. If you specify that the tool returns JSON, Claude attempts to deserialize and process the result in code. The more detail you provide about the output schema, the better Claude can handle the response programmatically. The request shape is identical to the [Quick start](#quick-start) example: include `code_execution` in your tools list, add `allowed_callers: ["code_execution_20260120"]` to any tool you want Claude to invoke from code, and send your user message. The remaining steps in this workflow use the user message `"Query customer purchase history from the last quarter and identify our top 5 customers by revenue"`. ### Step 2: API response with tool call Claude writes code that calls your tool. The API pauses and returns: ```json Output { "role": "assistant", "content": [ { "type": "text", "text": "I'll query the purchase history and analyze the results." }, { "type": "server_tool_use", "id": "srvtoolu_abc123", "name": "code_execution", "input": { "code": "results = await query_database('')\ntop_customers = sorted(results, key=lambda x: x['revenue'], reverse=True)[:5]\nprint(f'Top 5 customers: {top_customers}')" } }, { "type": "tool_use", "id": "toolu_def456", "name": "query_database", "input": { "sql": "" }, "caller": { "type": "code_execution_20260120", "tool_id": "srvtoolu_abc123" } } ], "container": { "id": "container_xyz789", "expires_at": "2026-01-20T14:30:00Z" }, "stop_reason": "tool_use" } ``` ### Step 3: Provide tool result Include the full conversation history plus your tool result: ```bash CLI nocheck ant messages create <<'YAML' model: claude-opus-4-7 max_tokens: 4096 container: container_xyz789 messages: - role: user content: >- Query customer purchase history from the last quarter and identify our top 5 customers by revenue - role: assistant content: - type: text text: I'll query the purchase history and analyze the results. - type: server_tool_use id: srvtoolu_abc123 name: code_execution input: code: "..." - type: tool_use id: toolu_def456 name: query_database input: sql: "" caller: type: code_execution_20260120 tool_id: srvtoolu_abc123 - role: user content: - type: tool_result tool_use_id: toolu_def456 content: >- [{"customer_id": "C1", "revenue": 45000}, {"customer_id": "C2", "revenue": 38000}, ...] tools: [...] YAML ``` ```python Python nocheck response = client.messages.create( model="claude-opus-4-7", max_tokens=4096, container="container_xyz789", # Reuse the container messages=[ { "role": "user", "content": "Query customer purchase history from the last quarter and identify our top 5 customers by revenue", }, { "role": "assistant", "content": [ { "type": "text", "text": "I'll query the purchase history and analyze the results.", }, { "type": "server_tool_use", "id": "srvtoolu_abc123", "name": "code_execution", "input": {"code": "..."}, }, { "type": "tool_use", "id": "toolu_def456", "name": "query_database", "input": {"sql": ""}, "caller": { "type": "code_execution_20260120", "tool_id": "srvtoolu_abc123", }, }, ], }, { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_def456", "content": '[{"customer_id": "C1", "revenue": 45000}, {"customer_id": "C2", "revenue": 38000}, ...]', } ], }, ], tools=[...], ) print(response) ``` ```typescript TypeScript nocheck const response = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 4096, container: "container_xyz789", // Reuse the container messages: [ { role: "user", content: "Query customer purchase history from the last quarter and identify our top 5 customers by revenue" }, { role: "assistant", content: [ { type: "text", text: "I'll query the purchase history and analyze the results." }, { type: "server_tool_use", id: "srvtoolu_abc123", name: "code_execution", input: { code: "..." } }, { type: "tool_use", id: "toolu_def456", name: "query_database", input: { sql: "" }, caller: { type: "code_execution_20260120", tool_id: "srvtoolu_abc123" } } ] }, { role: "user", content: [ { type: "tool_result", tool_use_id: "toolu_def456", content: '[{"customer_id": "C1", "revenue": 45000}, {"customer_id": "C2", "revenue": 38000}, ...]' } ] } ], tools: [ /* ... */ ] }); console.log(response); ``` ```csharp C# nocheck using System; using System.Threading.Tasks; using Anthropic; using Anthropic.Models.Messages; class Program { static async Task Main(string[] args) { AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 4096, Container = "container_xyz789", Messages = [ new() { Role = Role.User, Content = "Query customer purchase history from the last quarter and identify our top 5 customers by revenue" }, new() { Role = Role.Assistant, Content = new ContentBlock[] { new TextBlock { Text = "I'll query the purchase history and analyze the results." }, new ServerToolUseBlock { Id = "srvtoolu_abc123", Name = "code_execution", Input = new { code = "..." } }, new ToolUseBlock { Id = "toolu_def456", Name = "query_database", Input = new { sql = "" }, Caller = new ToolCaller { Type = "code_execution_20260120", ToolId = "srvtoolu_abc123" } } } }, new() { Role = Role.User, Content = new ContentBlockParam[] { new ToolResultBlockParam { ToolUseID = "toolu_def456", Content = "[{\"customer_id\": \"C1\", \"revenue\": 45000}, {\"customer_id\": \"C2\", \"revenue\": 38000}, ...]" } } } ], Tools = [] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); } } ``` ```go Go nocheck hidelines={1..13,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Container: anthropic.MessageNewParamsContainerUnion{ OfString: anthropic.String("container_xyz789"), }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Query customer purchase history from the last quarter and identify our top 5 customers by revenue")), { Role: anthropic.MessageParamRoleAssistant, Content: []anthropic.ContentBlockParamUnion{ anthropic.NewTextBlock("I'll query the purchase history and analyze the results."), {OfServerToolUse: &anthropic.ServerToolUseBlockParam{ ID: "srvtoolu_abc123", Name: anthropic.ServerToolUseBlockParamNameCodeExecution, Input: map[string]any{"code": "..."}, }}, {OfToolUse: &anthropic.ToolUseBlockParam{ ID: "toolu_def456", Name: "query_database", Input: map[string]any{"sql": ""}, Caller: anthropic.ServerToolUseBlockParamCallerUnion{ OfCodeExecution20260120: &anthropic.ServerToolCaller20260120Param{ ToolID: "srvtoolu_abc123", }, }, }}, }, }, { Role: anthropic.MessageParamRoleUser, Content: []anthropic.ContentBlockParamUnion{ {OfToolResult: &anthropic.ToolResultBlockParam{ ToolUseID: "toolu_def456", Content: []anthropic.ToolResultBlockParamContentUnion{ {OfText: &anthropic.TextBlockParam{ Text: `[{"customer_id": "C1", "revenue": 45000}, {"customer_id": "C2", "revenue": 38000}, ...]`, }}, }, }}, }, }, }, Tools: []anthropic.ToolUnionParam{ {OfCodeExecutionTool20260120: &anthropic.CodeExecutionTool20260120Param{}}, }, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```java Java nocheck hidelines={1..3,5..8,10..17,-2..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.core.JsonValue; import com.anthropic.models.messages.CodeExecutionTool20260120; 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.ServerToolUseBlockParam; import com.anthropic.models.messages.TextBlockParam; import com.anthropic.models.messages.ToolResultBlockParam; import com.anthropic.models.messages.ToolUseBlockParam; import java.util.List; import java.util.Map; public class ContainerReuse { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(4096L) .container("container_xyz789") .addUserMessage("Query customer purchase history from the last quarter and identify our top 5 customers by revenue") .addAssistantMessageOfBlockParams(List.of( ContentBlockParam.ofText( TextBlockParam.builder() .text("I'll query the purchase history and analyze the results.") .build()), ContentBlockParam.ofServerToolUse( ServerToolUseBlockParam.builder() .id("srvtoolu_abc123") .name("code_execution") .input(JsonValue.from(Map.of("code", "..."))) .build()), ContentBlockParam.ofToolUse( ToolUseBlockParam.builder() .id("toolu_def456") .name("query_database") .input(JsonValue.from(Map.of("sql", ""))) .codeExecution20260120Caller("srvtoolu_abc123") .build()) )) .addUserMessageOfBlockParams(List.of( ContentBlockParam.ofToolResult( ToolResultBlockParam.builder() .toolUseId("toolu_def456") .content("[{\"customer_id\": \"C1\", \"revenue\": 45000}, {\"customer_id\": \"C2\", \"revenue\": 38000}, ...]") .build()) )) .addTool(CodeExecutionTool20260120.builder().build()) .build(); Message response = client.messages().create(params); System.out.println(response); } } ``` ```php PHP hidelines={1..6} nocheck messages->create( maxTokens: 4096, messages: [ [ 'role' => 'user', 'content' => 'Query customer purchase history from the last quarter and identify our top 5 customers by revenue', ], [ 'role' => 'assistant', 'content' => [ [ 'type' => 'text', 'text' => "I'll query the purchase history and analyze the results.", ], [ 'type' => 'server_tool_use', 'id' => 'srvtoolu_abc123', 'name' => 'code_execution', 'input' => ['code' => '...'], ], [ 'type' => 'tool_use', 'id' => 'toolu_def456', 'name' => 'query_database', 'input' => ['sql' => ''], 'caller' => [ 'type' => 'code_execution_20260120', 'tool_id' => 'srvtoolu_abc123', ], ], ], ], [ 'role' => 'user', 'content' => [ [ 'type' => 'tool_result', 'tool_use_id' => 'toolu_def456', 'content' => '[{"customer_id": "C1", "revenue": 45000}, {"customer_id": "C2", "revenue": 38000}, ...]', ], ], ], ], model: 'claude-opus-4-7', container: 'container_xyz789', tools: [], ); echo $message; ``` ```ruby Ruby nocheck require "anthropic" client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-7", max_tokens: 4096, container: "container_xyz789", messages: [ { role: "user", content: "Query customer purchase history from the last quarter and identify our top 5 customers by revenue" }, { role: "assistant", content: [ { type: "text", text: "I'll query the purchase history and analyze the results." }, { type: "server_tool_use", id: "srvtoolu_abc123", name: "code_execution", input: { code: "..." } }, { type: "tool_use", id: "toolu_def456", name: "query_database", input: { sql: "" }, caller: { type: "code_execution_20260120", tool_id: "srvtoolu_abc123" } } ] }, { role: "user", content: [ { type: "tool_result", tool_use_id: "toolu_def456", content: '[{"customer_id": "C1", "revenue": 45000}, {"customer_id": "C2", "revenue": 38000}, ...]' } ] } ], tools: [ { type: "code_execution_20260120", name: "code_execution" } ] ) puts message ``` ### Step 4: Next tool call or completion The code execution continues and processes the results. If additional tool calls are needed, repeat Step 3 until all tool calls are satisfied. ### Step 5: Final response Once the code execution completes, Claude provides the final response: ```json Output { "content": [ { "type": "code_execution_tool_result", "tool_use_id": "srvtoolu_abc123", "content": { "type": "code_execution_result", "stdout": "Top 5 customers: [{'customer_id': 'C1', 'revenue': 45000}, {'customer_id': 'C2', 'revenue': 38000}, {'customer_id': 'C5', 'revenue': 32000}, {'customer_id': 'C8', 'revenue': 28500}, {'customer_id': 'C3', 'revenue': 24000}]", "stderr": "", "return_code": 0, "content": [] } }, { "type": "text", "text": "I've analyzed the purchase history from last quarter. Your top 5 customers generated $167,500 in total revenue, with Customer C1 leading at $45,000." } ], "stop_reason": "end_turn" } ``` ## Advanced patterns ### Batch processing with loops Claude can write code that processes multiple items efficiently: ```python hidelines={1..4,-1} async def query_database(sql): return [{"revenue": 100}] async def _claude_code(): regions = ["West", "East", "Central", "North", "South"] results = {} for region in regions: data = await query_database(f"") results[region] = sum(row["revenue"] for row in data) # Process results programmatically top_region = max(results.items(), key=lambda x: x[1]) print(f"Top region: {top_region[0]} with ${top_region[1]:,} in revenue") _ = _claude_code ``` This pattern: - Reduces model round-trips from N (one per region) to 1 - Processes large result sets programmatically before returning to Claude - Saves tokens by only returning aggregated conclusions instead of raw data ### Early termination Claude can stop processing as soon as success criteria are met: ```python hidelines={1..4,-1} async def check_health(ep): return "healthy" async def _claude_code(): endpoints = ["us-east", "eu-west", "apac"] for endpoint in endpoints: status = await check_health(endpoint) if status == "healthy": print(f"Found healthy endpoint: {endpoint}") break # Stop early, don't check remaining _ = _claude_code ``` ### Conditional tool selection ```python hidelines={1..15,-1} async def get_file_info(p): return {"size": 500} async def read_full_file(p): return "content" async def read_file_summary(p): return "summary" path = "/tmp/example.txt" async def _claude_code(): file_info = await get_file_info(path) if file_info["size"] < 10000: content = await read_full_file(path) else: content = await read_file_summary(path) print(content) _ = _claude_code ``` ### Data filtering ```python hidelines={1..7,-1} async def fetch_logs(sid): return ["INFO: ok", "ERROR: failed"] server_id = "srv-01" async def _claude_code(): logs = await fetch_logs(server_id) errors = [log for log in logs if "ERROR" in log] print(f"Found {len(errors)} errors") for error in errors[-10:]: # Only return last 10 errors print(error) _ = _claude_code ``` ## Response format ### Programmatic tool call When code execution calls a tool: ```json { "type": "tool_use", "id": "toolu_abc123", "name": "query_database", "input": { "sql": "" }, "caller": { "type": "code_execution_20260120", "tool_id": "srvtoolu_xyz789" } } ``` ### Tool result handling Your tool result is passed back to the running code: ```json { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_abc123", "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000, \"orders\": 23}, {\"customer_id\": \"C2\", \"revenue\": 38000, \"orders\": 18}, ...]" } ] } ``` ### Code execution completion When all tool calls are satisfied and code completes: ```json { "type": "code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": { "type": "code_execution_result", "stdout": "Analysis complete. Top 5 customers identified from 847 total records.", "stderr": "", "return_code": 0, "content": [] } } ``` ## Error handling ### Common errors | Error | Description | Solution | |-------|-------------|----------| | `invalid_tool_input` | Tool input doesn't match schema | Validate your tool's input_schema | | `tool_not_allowed` | Tool doesn't allow the requested caller type | Check `allowed_callers` includes the right contexts | ### Container expiration during tool call If your tool takes too long to respond, the code execution receives a `TimeoutError`. Claude sees this in stderr and typically retries: ```json { "type": "code_execution_tool_result", "tool_use_id": "srvtoolu_abc123", "content": { "type": "code_execution_result", "stdout": "", "stderr": "TimeoutError: Calling tool ['query_database'] timed out.", "return_code": 0, "content": [] } } ``` To prevent timeouts: - Monitor the `expires_at` field in responses - Implement timeouts for your tool execution - Consider breaking long operations into smaller chunks ### Tool execution errors If your tool returns an error: ```json { "type": "tool_result", "tool_use_id": "toolu_abc123", "content": "Error: Query timeout - table lock exceeded 30 seconds" } ``` Claude's code receives this error and can handle it appropriately. ## Constraints and limitations ### Feature incompatibilities - **Structured outputs:** Tools with `strict: true` are not supported with programmatic calling - **Tool choice:** You cannot force programmatic calling of a specific tool through `tool_choice` - **Parallel tool use:** `disable_parallel_tool_use: true` is not supported with programmatic calling ### Tool restrictions The following tools cannot be called programmatically: - Tools provided by an [MCP connector](/docs/en/agents-and-tools/mcp-connector) ### Message formatting restrictions When responding to programmatic tool calls, there are strict formatting requirements: **Tool result only responses:** If there are pending programmatic tool calls waiting for results, your response message must contain **only** `tool_result` blocks. You cannot include any text content, even after the tool results. Invalid - Cannot include text when responding to programmatic tool calls: ```json { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01", "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]" }, { "type": "text", "text": "What should I do next?" } ] } ``` Valid - Only tool results when responding to programmatic tool calls: ```json { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01", "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]" } ] } ``` This restriction only applies when responding to programmatic (code execution) tool calls. For regular client-side tool calls, you can include text content after tool results. ### Rate limits Programmatic tool calls are subject to the same rate limits as regular tool calls. Each tool call from code execution counts as a separate invocation. ### Validate tool results before use When implementing user-defined tools that will be called programmatically: - **Tool results are returned as strings:** They can contain any content, including code snippets or executable commands that may be processed by the execution environment. - **Validate external tool results:** If your tool returns data from external sources or accepts user input, be aware of code injection risks if the output will be interpreted or executed as code. ## Token efficiency Programmatic tool calling can significantly reduce token consumption: - **Tool results from programmatic calls are not added to Claude's context** - only the final code output is - **Intermediate processing happens in code** - filtering, aggregation, etc. don't consume model tokens - **Multiple tool calls in one code execution** - reduces overhead compared to separate model turns For example, calling 10 tools directly uses ~10x the tokens of calling them programmatically and returning a summary. ## Usage and pricing Programmatic tool calling uses the same pricing as code execution. See the [code execution pricing](/docs/en/agents-and-tools/tool-use/code-execution-tool#usage-and-pricing) for details. Token counting for programmatic tool calls: Tool results from programmatic invocations do not count toward your input/output token usage. Only the final code execution result and Claude's response count. ## Best practices ### Tool design - **Provide detailed output descriptions:** Since Claude deserializes tool results in code, clearly document the format (JSON structure, field types, etc.) - **Return structured data:** JSON or other easily parseable formats work best for programmatic processing - **Keep responses concise:** Return only necessary data to minimize processing overhead ### When to use programmatic calling **Good use cases:** - Processing large datasets where you only need aggregates or summaries - Multi-step workflows with 3+ dependent tool calls - Operations requiring filtering, sorting, or transformation of tool results - Tasks where intermediate data shouldn't influence Claude's reasoning - Parallel operations across many items (e.g., checking 50 endpoints) **Less ideal use cases:** - Single tool calls with simple responses - Tools that need immediate user feedback - Very fast operations where code execution overhead would outweigh the benefit ### Performance optimization - **Reuse containers** when making multiple related requests to maintain state - **Batch similar operations** in a single code execution when possible ## Troubleshooting ### Common issues **"Tool not allowed" error** - Verify your tool definition includes `"allowed_callers": ["code_execution_20260120"]` **Container expiration** - Ensure you respond to tool calls before the container idles out (4.5 minutes of inactivity; 30-day hard maximum) - Monitor the `expires_at` field in responses - Consider implementing faster tool execution **Tool result not parsed correctly** - Ensure your tool returns string data that Claude can deserialize - Provide clear output format documentation in your tool description ### Debugging tips 1. **Log all tool calls and results** to track the flow 2. **Check the `caller` field** to confirm programmatic invocation 3. **Monitor container IDs** to ensure proper reuse 4. **Test tools independently** before enabling programmatic calling ## Why programmatic tool calling works Claude's training includes extensive exposure to code, making it effective at reasoning through and chaining function calls. When tools are presented as callable functions within a code execution environment, Claude can leverage this strength to: - **Reason naturally about tool composition:** Chain operations and handle dependencies as naturally as writing any Python code - **Process large results efficiently:** Filter down large tool outputs, extract only relevant data, or write intermediate results to files before returning summaries to the context window - **Reduce latency significantly:** Eliminate the overhead of re-sampling Claude between each tool call in multi-step workflows This approach enables workflows that would be impractical with traditional tool use (such as processing files over 1M tokens) by allowing Claude to work with data programmatically rather than loading everything into the conversation context. ## Alternative implementations Programmatic tool calling is a generalizable pattern that can also be implemented on your own infrastructure. Here's how the approaches compare: ### Client-side direct execution Provide Claude with a code execution tool and describe what functions are available in that environment. When Claude invokes the tool with code, your application executes it locally where those functions are defined. **Advantages:** - Simple to implement with minimal re-architecting - Full control over the environment and instructions **Disadvantages:** - Executes untrusted code outside of a sandbox - Tool invocations can be vectors for code injection **Use when:** Your application can safely execute arbitrary code, you want a simple solution, and Anthropic's managed offering doesn't fit your needs. ### Self-managed sandboxed execution Same approach from Claude's perspective, but code runs in a sandboxed container with security restrictions (e.g., no network egress). If your tools require external resources, you'll need a protocol for executing tool calls outside the sandbox. **Advantages:** - Safe programmatic tool calling on your own infrastructure - Full control over the execution environment **Disadvantages:** - Complex to build and maintain - Requires managing both infrastructure and inter-process communication **Use when:** Security is critical and Anthropic's managed solution doesn't fit your requirements. ### Anthropic-managed execution Anthropic's programmatic tool calling is a managed version of sandboxed execution with an opinionated Python environment tuned for Claude. Anthropic handles container management, code execution, and secure tool invocation communication. **Advantages:** - Safe and secure by default - Easy to enable with minimal configuration - Environment and instructions optimized for Claude Consider using Anthropic's managed solution if you're using the Claude API, [Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws), or [Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry). ## Data retention Programmatic tool calling is built on the code execution infrastructure and uses the same sandbox containers. Container data, including execution artifacts and outputs, is retained for up to 30 days. For ZDR eligibility across all features, see [API and data retention](/docs/en/manage-claude/api-and-data-retention). ## Related features Learn about the underlying code execution capability that powers programmatic tool calling. Understand the fundamentals of tool use with Claude. Step-by-step guide for defining tools. --- # Tool combinations URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-combinations # Tool combinations Common Anthropic tool pairings for research agents, coding agents, and long-running agents. --- Anthropic-provided tools are designed to work together. Common agent patterns pair tools that cover complementary stages of a workflow: one tool gathers or discovers, another processes or acts. The combinations below are starting points, not prescriptions. Mix them to fit your task. Each snippet shows only the `tools` array. See [Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls) for the full request shape. ## Research agent: web_search + code_execution Search finds sources; code execution analyzes and synthesizes. Claude searches for data, then writes Python to process, tabulate, or visualize it. This pairing is a good fit for questions that require both up-to-date information and nontrivial computation over that information, such as "compare this quarter's earnings across the top five cloud providers." ```json { "tools": [ { "type": "web_search_20260209", "name": "web_search" }, { "type": "code_execution_20250825", "name": "code_execution" } ] } ``` The flow is typically search, then execute, then optionally search again if the first pass surfaced a gap. Code execution runs server-side, so there's no client-side sandbox to manage. ## Coding agent: text_editor + bash The text editor reads and modifies files; bash runs tests and build commands. This is the canonical software-development loop: inspect the code, make an edit, run the tests, repeat. Both tools are client-executed, so your application controls which files and commands are accessible. ```json { "tools": [ { "type": "text_editor_20250728", "name": "str_replace_based_edit_tool" }, { "type": "bash_20250124", "name": "bash" } ] } ``` Pair this with a constrained working directory and a command allowlist if the agent operates on untrusted code. See [Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool) and [Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool) for the execution contracts. ## Cite-then-fetch: web_search + web_fetch Search surfaces candidate URLs; fetch retrieves full page content for the relevant ones. This avoids fetching everything upfront. Claude runs a search, inspects the snippets, picks the two or three results that actually look relevant, and fetches only those. ```json { "tools": [ { "type": "web_search_20260209", "name": "web_search" }, { "type": "web_fetch_20260209", "name": "web_fetch" } ] } ``` This pairing is useful when the answer lives in long-form content (documentation pages, articles, specifications) that a search snippet can't fully capture. Fetch pulls the complete page so Claude can cite specific passages. ## Long-running agent: memory + any toolset Memory persists state across conversations; the other tools do the work. Add memory to any agent that needs to remember prior sessions, such as a support agent that recalls a customer's earlier issues or a project assistant that tracks decisions made last week. ```json { "tools": [{ "type": "memory_20250818", "name": "memory" }] } ``` Add your other tools alongside `memory` in the same array. Memory is orthogonal to the rest of your toolset. It doesn't change how other tools behave; it gives Claude a place to write down and later retrieve facts that would otherwise be lost when the context window resets. See [Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool) for the storage model. ## All-in-one: computer_use The computer use tool subsumes most others by operating a full desktop. Claude sees screenshots and issues mouse and keyboard actions, which means it can drive any application a human can. Use this when the task requires arbitrary GUI interaction that more specific tools can't reach: legacy software without an API, visual verification steps, or workflows that span multiple desktop apps. ```json { "tools": [ { "type": "computer_20250124", "name": "computer", "display_width_px": 1280, "display_height_px": 800 } ] } ``` Computer use is the most general option and also the slowest, since every action requires a screenshot roundtrip. Prefer narrower tools when they cover your use case, and reach for computer use when nothing else fits. See [Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool) for the sandbox setup. ## Next steps Full catalog of Anthropic-provided tools with type strings and parameters. How tool use works and when to use Anthropic tools versus defining your own. --- # Tool reference URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference # Tool reference Directory of Anthropic-provided tools and reference for optional tool definition properties. --- This page is a reference for the tools Anthropic provides and the optional properties you can set on any tool definition. For a conceptual introduction to tool use, see [Tool use with Claude](/docs/en/agents-and-tools/tool-use/overview). For guidance on implementing tool use in your application, see [Define tools](/docs/en/agents-and-tools/tool-use/define-tools). ## Anthropic-provided tools Anthropic provides two kinds of tools: **server tools** that execute on Anthropic's infrastructure, and **client tools** where Anthropic defines the schema but your application handles execution. Both kinds appear in your request's `tools` array alongside any user-defined tools. | Tool | `type` | Execution | Status | | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------- | ------------------------------------------------------------- | | [Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool) | `web_search_20260209`
`web_search_20250305` | Server | GA | | [Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool) | `web_fetch_20260209`
`web_fetch_20250910` | Server | GA | | [Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool) | `code_execution_20260120`
`code_execution_20250825` | Server | GA | | [Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool) | `advisor_20260301` | Server | Beta: `advisor-tool-2026-03-01` | | [Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool) | `tool_search_tool_regex_20251119`
`tool_search_tool_bm25_20251119` | Server | GA | | [MCP connector](/docs/en/agents-and-tools/mcp-connector) | `mcp_toolset` | Server | Beta: `mcp-client-2025-11-20` | | [Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool) | `memory_20250818` | Client | GA | | [Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool) | `bash_20250124` | Client | GA | | [Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool) | `text_editor_20250728`
`text_editor_20250124` | Client | GA | | [Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool) | `computer_20251124`
`computer_20250124` | Client | Beta: `computer-use-2025-11-24`
`computer-use-2025-01-24` | For model compatibility, see each tool's page. Supported models vary by tool and by tool version. The tool search `type` values also accept undated aliases: `tool_search_tool_regex` and `tool_search_tool_bm25`. These resolve to the latest dated version. ### Tool versioning Most Anthropic-provided tools carry a `_YYYYMMDD` suffix in the `type` string. A new version is released when the tool's behavior, schema, or model support changes. Older versions remain available so that existing integrations continue to work. When a tool has multiple active versions, the relationship between them varies: - **Capability-keyed:** `web_search_20260209` and `web_fetch_20260209` add dynamic content filtering over their predecessors. `code_execution_20260120` adds [programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) from within the sandbox. In each case, both the new and old versions are current; which one you use depends on whether you need the new capability. - **Model-keyed:** `text_editor_20250728` is for Claude 4 models and `text_editor_20250124` is for earlier models. The version you use depends on the model you target. - **Variant, not version:** `tool_search_tool_regex_20251119` and `tool_search_tool_bm25_20251119` are two search algorithms released together. Neither supersedes the other. - **Legacy:** `code_execution_20250522` supports only Python. `code_execution_20250825` adds Bash and file operations. The `mcp_toolset` type is not date-versioned; versioning is carried in the `anthropic-beta` header instead. ## Tool definition properties Every tool in the `tools` array, including user-defined tools, accepts optional properties that control how the tool is loaded, who can call it, and how its inputs are validated. These properties compose: you can set `defer_loading` and `cache_control` and `strict` on the same tool. | Property | Purpose | Available on | Detailed guide | | ----------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `cache_control` | Set a prompt-cache breakpoint at this tool definition | All tools | [Prompt caching](/docs/en/build-with-claude/prompt-caching) | | `strict` | Guarantee schema validation on tool names and inputs | All tools except `mcp_toolset` | [Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use) | | `defer_loading` | Exclude the tool from the initial system prompt; load it on demand when tool search returns a `tool_reference` for it | All tools (for `mcp_toolset`, see [tool configuration](/docs/en/agents-and-tools/mcp-connector#mcp-toolset-configuration)) | [Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool) | | `allowed_callers` | Restrict which callers can call the tool | All tools except `mcp_toolset` | [Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling#the-allowed-callers-field) | | `input_examples` | Provide example input objects to help Claude understand how to call the tool | User-defined and Anthropic-schema client tools. Not available on server tools. | [Define tools](/docs/en/agents-and-tools/tool-use/define-tools#providing-tool-use-examples) | | `eager_input_streaming` | Enable fine-grained input streaming (`true`) or keep standard buffered streaming (`false`) for this tool | User-defined tools only | [Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming) | ### `allowed_callers` values `allowed_callers` is an array that accepts any combination of: | Value | Meaning | | --------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `"direct"` | The model can call this tool directly in a `tool_use` block. This is the default if `allowed_callers` is omitted. | | `"code_execution_20260120"` | Code running inside a `code_execution_20260120` sandbox can call this tool. | Omitting `"direct"` from the array (for example, `"allowed_callers": ["code_execution_20260120"]`) means the tool is callable only from within code execution. The response's `tool_use` block includes a `caller` field that identifies which caller called the tool. See [Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling#the-allowed-callers-field) for the full treatment, including the `caller` response shape and error behavior. ### `defer_loading` and prompt caching Tools with `defer_loading: true` are stripped from the rendered tools section before the cache key is computed. They don't appear in the system-prompt prefix at all. When tool search discovers a deferred tool and returns a `tool_reference` for it, the tool's full definition is expanded inline at that point in the conversation body, not in the prefix. This means `defer_loading: true` preserves your prompt cache. You can add deferred tools to a request without invalidating an existing cache entry, and the cache remains valid across the turn where the tool is discovered and the turn where it's called. For how to combine `defer_loading` with `cache_control` breakpoints, see the [Tool search tool prompt caching guidance](/docs/en/agents-and-tools/tool-use/tool-search-tool#prompt-caching). --- # Tool search tool URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool # Tool search tool --- The tool search tool enables Claude to work with hundreds or thousands of tools by dynamically discovering and loading them on-demand. Instead of loading all tool definitions into the context window upfront, Claude searches your tool catalog (including tool names, descriptions, argument names, and argument descriptions) and loads only the tools it needs. This approach solves two problems that compound quickly as tool libraries scale: - **Context bloat:** Tool definitions eat into your context budget fast. A typical multi-server setup (GitHub, Slack, Sentry, Grafana, Splunk) can consume ~55k tokens in definitions before Claude does any actual work. Tool search typically reduces this by over 85%, loading only the 3–5 tools Claude actually needs for a given request. - **Tool selection accuracy:** Claude's ability to correctly pick the right tool degrades significantly once you exceed 30–50 available tools. By surfacing a focused set of relevant tools on demand, tool search keeps selection accuracy high even across thousands of tools. For background on the scaling challenges that tool search solves, see [Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use). Tool search's on-demand loading is also an instance of the broader just-in-time retrieval principle described in [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents). Although this is provided as a server-side tool, you can also implement your own client-side tool search functionality. See [Custom tool search implementation](#custom-tool-search-implementation) for details. Share feedback on this feature through the [feedback form](https://forms.gle/MhcGFFwLxuwnWTkYA). This feature is eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned. On Amazon Bedrock, server-side tool search is available only through the [InvokeModel API](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-runtime_example_bedrock-runtime_InvokeModel_AnthropicClaude_section.html), not the Converse API. On [Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws), server-side tool search works identically to the Claude API. Claude Platform on AWS uses the Anthropic Messages API directly, so there is no InvokeModel or Converse distinction. ## How tool search works There are two tool search variants: - **Regex** (`tool_search_tool_regex_20251119`): Claude constructs regex patterns to search for tools - **BM25** (`tool_search_tool_bm25_20251119`): Claude uses natural language queries to search for tools When you enable the tool search tool: 1. You include a tool search tool (for example, `tool_search_tool_regex_20251119` or `tool_search_tool_bm25_20251119`) in your tools list. 2. You provide all tool definitions with `defer_loading: true` for tools that shouldn't be loaded immediately. 3. Claude sees only the tool search tool and any non-deferred tools initially. 4. When Claude needs additional tools, it searches using a tool search tool. 5. The API returns 3-5 most relevant `tool_reference` blocks. 6. These references are automatically expanded into full tool definitions. 7. Claude selects from the discovered tools and calls them. This keeps your context window efficient while maintaining high tool selection accuracy. ## Quick start Here's a simple example with deferred tools: ```bash cURL curl https://api.anthropic.com/v1/messages \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --data '{ "model": "claude-opus-4-7", "max_tokens": 2048, "messages": [ { "role": "user", "content": "What is the weather in San Francisco?" } ], "tools": [ { "type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex" }, { "name": "get_weather", "description": "Get the weather at a specific location", "input_schema": { "type": "object", "properties": { "location": {"type": "string"}, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] } }, "required": ["location"] }, "defer_loading": true }, { "name": "search_files", "description": "Search through files in the workspace", "input_schema": { "type": "object", "properties": { "query": {"type": "string"}, "file_types": { "type": "array", "items": {"type": "string"} } }, "required": ["query"] }, "defer_loading": true } ] }' ``` ```bash CLI ant messages create <<'YAML' model: claude-opus-4-7 max_tokens: 2048 messages: - role: user content: What is the weather in San Francisco? tools: - type: tool_search_tool_regex_20251119 name: tool_search_tool_regex - name: get_weather description: Get the weather at a specific location input_schema: type: object properties: location: type: string unit: type: string enum: [celsius, fahrenheit] required: [location] defer_loading: true - name: search_files description: Search through files in the workspace input_schema: type: object properties: query: type: string file_types: type: array items: type: string required: [query] defer_loading: true YAML ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-4-7", max_tokens=2048, messages=[{"role": "user", "content": "What is the weather in San Francisco?"}], tools=[ {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"}, { "name": "get_weather", "description": "Get the weather at a specific location", "input_schema": { "type": "object", "properties": { "location": {"type": "string"}, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, }, "required": ["location"], }, "defer_loading": True, }, { "name": "search_files", "description": "Search through files in the workspace", "input_schema": { "type": "object", "properties": { "query": {"type": "string"}, "file_types": {"type": "array", "items": {"type": "string"}}, }, "required": ["query"], }, "defer_loading": True, }, ], ) print(response) ``` ```typescript TypeScript hidelines={1..4} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const response = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 2048, messages: [ { role: "user", content: "What is the weather in San Francisco?" } ], tools: [ { type: "tool_search_tool_regex_20251119", name: "tool_search_tool_regex" }, { name: "get_weather", description: "Get the weather at a specific location", input_schema: { type: "object" as const, properties: { location: { type: "string" }, unit: { type: "string", enum: ["celsius", "fahrenheit"] } }, required: ["location"] }, defer_loading: true }, { name: "search_files", description: "Search through files in the workspace", input_schema: { type: "object" as const, properties: { query: { type: "string" }, file_types: { type: "array", items: { type: "string" } } }, required: ["query"] }, defer_loading: true } ] }); console.log(response); ``` ```csharp C# hidelines={1..5} using System; using System.Text.Json; using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_7, MaxTokens = 2048, Messages = [ new() { Role = Role.User, Content = "What is the weather in San Francisco?" } ], Tools = [ new ToolUnion(new ToolSearchToolRegex20251119 { Type = ToolSearchToolRegex20251119Type.ToolSearchToolRegex20251119 }), new ToolUnion(new Tool() { Name = "get_weather", Description = "Get the weather at a specific location", InputSchema = new InputSchema() { Properties = new Dictionary { ["location"] = JsonSerializer.SerializeToElement(new { type = "string" }), ["unit"] = JsonSerializer.SerializeToElement(new { type = "string", @enum = new[] { "celsius", "fahrenheit" } }), }, Required = ["location"], }, DeferLoading = true, }), new ToolUnion(new Tool() { Name = "search_files", Description = "Search through files in the workspace", InputSchema = new InputSchema() { Properties = new Dictionary { ["query"] = JsonSerializer.SerializeToElement(new { type = "string" }), ["file_types"] = JsonSerializer.SerializeToElement(new { type = "array", items = new { type = "string" } }), }, Required = ["query"], }, DeferLoading = true, }), ] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 2048, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("What is the weather in San Francisco?")), }, Tools: []anthropic.ToolUnionParam{ {OfToolSearchToolRegex20251119: &anthropic.ToolSearchToolRegex20251119Param{ Type: anthropic.ToolSearchToolRegex20251119TypeToolSearchToolRegex20251119, }}, {OfTool: &anthropic.ToolParam{ Name: "get_weather", Description: anthropic.String("Get the weather at a specific location"), InputSchema: anthropic.ToolInputSchemaParam{ Properties: map[string]any{ "location": map[string]any{"type": "string"}, "unit": map[string]any{ "type": "string", "enum": []string{"celsius", "fahrenheit"}, }, }, Required: []string{"location"}, }, DeferLoading: anthropic.Bool(true), }}, {OfTool: &anthropic.ToolParam{ Name: "search_files", Description: anthropic.String("Search through files in the workspace"), InputSchema: anthropic.ToolInputSchemaParam{ Properties: map[string]any{ "query": map[string]any{"type": "string"}, "file_types": map[string]any{"type": "array", "items": map[string]any{"type": "string"}}, }, Required: []string{"query"}, }, DeferLoading: anthropic.Bool(true), }}, }, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```java Java hidelines={1..8} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.core.JsonValue; 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.ToolSearchToolRegex20251119; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); InputSchema weatherSchema = InputSchema.builder() .properties(JsonValue.from(Map.of( "location", Map.of("type", "string"), "unit", Map.of( "type", "string", "enum", List.of("celsius", "fahrenheit") ) ))) .putAdditionalProperty("required", JsonValue.from(List.of("location"))) .build(); InputSchema searchSchema = InputSchema.builder() .properties(JsonValue.from(Map.of( "query", Map.of("type", "string"), "file_types", Map.of( "type", "array", "items", Map.of("type", "string") ) ))) .putAdditionalProperty("required", JsonValue.from(List.of("query"))) .build(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(2048L) .addUserMessage("What is the weather in San Francisco?") .addTool(ToolSearchToolRegex20251119.builder() .type(ToolSearchToolRegex20251119.Type.TOOL_SEARCH_TOOL_REGEX_20251119) .build()) .addTool(Tool.builder() .name("get_weather") .description("Get the weather at a specific location") .inputSchema(weatherSchema) .deferLoading(true) .build()) .addTool(Tool.builder() .name("search_files") .description("Search through files in the workspace") .inputSchema(searchSchema) .deferLoading(true) .build()) .build(); Message response = client.messages().create(params); IO.println(response); } ``` ```php PHP hidelines={1..4} messages->create( maxTokens: 2048, messages: [ ['role' => 'user', 'content' => 'What is the weather in San Francisco?'], ], model: 'claude-opus-4-7', tools: [ [ 'type' => 'tool_search_tool_regex_20251119', 'name' => 'tool_search_tool_regex', ], [ 'name' => 'get_weather', 'description' => 'Get the weather at a specific location', 'input_schema' => [ 'type' => 'object', 'properties' => [ 'location' => ['type' => 'string'], 'unit' => [ 'type' => 'string', 'enum' => ['celsius', 'fahrenheit'], ], ], 'required' => ['location'], ], 'defer_loading' => true, ], [ 'name' => 'search_files', 'description' => 'Search through files in the workspace', 'input_schema' => [ 'type' => 'object', 'properties' => [ 'query' => ['type' => 'string'], 'file_types' => [ 'type' => 'array', 'items' => ['type' => 'string'], ], ], 'required' => ['query'], ], 'defer_loading' => true, ], ], ); echo $message; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-7", max_tokens: 2048, messages: [ { role: "user", content: "What is the weather in San Francisco?" } ], tools: [ { type: "tool_search_tool_regex_20251119", name: "tool_search_tool_regex" }, { name: "get_weather", description: "Get the weather at a specific location", input_schema: { type: "object", properties: { location: { type: "string" }, unit: { type: "string", enum: ["celsius", "fahrenheit"] } }, required: ["location"] }, defer_loading: true }, { name: "search_files", description: "Search through files in the workspace", input_schema: { type: "object", properties: { query: { type: "string" }, file_types: { type: "array", items: { type: "string" } } }, required: ["query"] }, defer_loading: true } ] ) puts message ``` ## Tool definition The tool search tool has two variants: ```json JSON { "type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex" } ``` ```json JSON { "type": "tool_search_tool_bm25_20251119", "name": "tool_search_tool_bm25" } ``` **Regex variant query format: Python regex, NOT natural language** When using `tool_search_tool_regex_20251119`, Claude constructs regex patterns using Python's `re.search()` syntax, not natural language queries. Common patterns: - `"weather"` - matches tool names/descriptions containing "weather" - `"get_.*_data"` - matches tools like `get_user_data`, `get_weather_data` - `"database.*query|query.*database"` - OR patterns for flexibility - `"(?i)slack"` - case-insensitive search Maximum query length: 200 characters **BM25 variant query format: Natural language** When using `tool_search_tool_bm25_20251119`, Claude uses natural language queries to search for tools. ### Deferred tool loading Mark tools for on-demand loading by adding `defer_loading: true`: ```json JSON { "name": "get_weather", "description": "Get current weather for a location", "input_schema": { "type": "object", "properties": { "location": { "type": "string" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] } }, "required": ["location"] }, "defer_loading": true } ``` **Key points:** - Tools without `defer_loading` are loaded into context immediately - Tools with `defer_loading: true` are only loaded when Claude discovers them through search - The tool search tool itself should **never** have `defer_loading: true` - Keep your 3-5 most frequently used tools as non-deferred for optimal performance Both tool search variants (`regex` and `bm25`) search tool names, descriptions, argument names, and argument descriptions. **How deferral works internally:** Deferred tools are not included in the system-prompt prefix. When the model discovers a deferred tool through tool search, the API appends a `tool_reference` block inline in the conversation, then expands it into the full tool definition before passing it to Claude. The prefix is untouched, so prompt caching is preserved. The grammar for [strict mode](/docs/en/agents-and-tools/tool-use/strict-tool-use) (the rules that constrain tool-call output to match your schemas) builds from the full toolset, so `defer_loading` and strict mode compose without grammar recompilation. ## Response format When Claude uses the tool search tool, the response includes new block types: ```json JSON { "role": "assistant", "content": [ { "type": "text", "text": "I'll search for tools to help with the weather information." }, { "type": "server_tool_use", "id": "srvtoolu_01ABC123", "name": "tool_search_tool_regex", "input": { "query": "weather" } }, { "type": "tool_search_tool_result", "tool_use_id": "srvtoolu_01ABC123", "content": { "type": "tool_search_tool_search_result", "tool_references": [{ "type": "tool_reference", "tool_name": "get_weather" }] } }, { "type": "text", "text": "I found a weather tool. Let me get the weather for San Francisco." }, { "type": "tool_use", "id": "toolu_01XYZ789", "name": "get_weather", "input": { "location": "San Francisco", "unit": "fahrenheit" } } ], "stop_reason": "tool_use" } ``` ### Understanding the response - **`server_tool_use`:** Indicates Claude is calling the tool search tool - **`tool_search_tool_result`:** Contains the search results with a nested `tool_search_tool_search_result` object - **`tool_references`:** Array of `tool_reference` objects pointing to discovered tools - **`tool_use`:** Claude calling the discovered tool The `tool_reference` blocks are automatically expanded into full tool definitions before being shown to Claude. You don't need to handle this expansion yourself. It happens automatically in the API as long as you provide all matching tool definitions in the `tools` parameter. ## MCP integration For configuring `mcp_toolset` with `defer_loading`, see [MCP connector](/docs/en/agents-and-tools/mcp-connector). ## Custom tool search implementation You can implement your own tool search logic (for example, using embeddings or semantic search) by returning `tool_reference` blocks from a custom tool. When Claude calls your custom search tool, return a standard `tool_result` with `tool_reference` blocks in the content array: ```json JSON { "type": "tool_result", "tool_use_id": "toolu_your_tool_id", "content": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }] } ``` Every tool referenced must have a corresponding tool definition in the top-level `tools` parameter with `defer_loading: true`. This approach lets you use more sophisticated search algorithms while maintaining compatibility with the tool search system. The `tool_search_tool_result` format shown in the [Response format](#response-format) section is the server-side format used internally by Anthropic's built-in tool search. For custom client-side implementations, always use the standard `tool_result` format with `tool_reference` content blocks as shown in the preceding example. For a complete example using embeddings, see the [tool search with embeddings cookbook](https://platform.claude.com/cookbooks/tool_use). ## Error handling The tool search tool is not compatible with [tool use examples](/docs/en/agents-and-tools/tool-use/define-tools#providing-tool-use-examples). If you need to provide examples of tool usage, use standard tool calling without tool search. ### HTTP errors (400 status) These errors prevent the request from being processed: **All tools deferred:** ```json { "type": "error", "error": { "type": "invalid_request_error", "message": "All tools have defer_loading set. At least one tool must be non-deferred." } } ``` **Missing tool definition:** ```json { "type": "error", "error": { "type": "invalid_request_error", "message": "Tool reference 'unknown_tool' has no corresponding tool definition" } } ``` ### Tool result errors (200 status) Errors during tool execution return a 200 response with error information in the body: ```json JSON { "type": "tool_search_tool_result", "tool_use_id": "srvtoolu_01ABC123", "content": { "type": "tool_search_tool_result_error", "error_code": "invalid_pattern" } } ``` **Error codes:** - `too_many_requests`: Rate limit exceeded for tool search operations - `invalid_pattern`: Malformed regex pattern - `pattern_too_long`: Pattern exceeds 200 character limit - `unavailable`: Tool search service temporarily unavailable ### Common mistakes

**Cause:** You set `defer_loading: true` on ALL tools including the search tool **Fix:** Remove `defer_loading` from the tool search tool: ```json { "type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex" } ```

**Cause:** A `tool_reference` points to a tool not in your `tools` array **Fix:** Ensure every tool that could be discovered has a complete definition: ```json { "name": "my_tool", "description": "Full description here", "input_schema": { "type": "object" }, "defer_loading": true } ```

**Cause:** Tool name, description, argument names, or argument descriptions don't match the regex pattern **Debugging steps:** 1. Check tool name, description, argument names, and argument descriptions. Claude searches all of these fields. 2. Test your pattern: `import re; re.search(r"your_pattern", "tool_name")`. 3. Remember searches are case-sensitive by default (use `(?i)` for case-insensitive). 4. Claude uses broad patterns such as `".*weather.*"` not exact matches. **Tip:** Add common keywords to tool descriptions to improve discoverability

## Prompt caching For how `defer_loading` preserves prompt caching, see [Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching). The system automatically expands `tool_reference` blocks throughout the entire conversation history, so Claude can reuse discovered tools in subsequent turns without re-searching. ## Streaming With streaming enabled, you'll receive tool search events as part of the stream: ```sse event: content_block_start data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "tool_search_tool_regex"}} // Search query streamed event: content_block_delta data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}} // Pause while search executes // Search results streamed event: content_block_start data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "tool_search_tool_search_result", "tool_references": [{"type": "tool_reference", "tool_name": "get_weather"}]}}} // Claude continues with discovered tools ``` ## Batch requests You can include the tool search tool in the [Messages Batches API](/docs/en/build-with-claude/batch-processing). Tool search operations through the Messages Batches API are priced the same as those in regular Messages API requests. ## Limits and best practices ### Limits - **Maximum tools:** 10,000 tools in your catalog - **Search results:** Returns 3-5 most relevant tools per search - **Pattern length:** Maximum 200 characters for regex patterns - **Model support:** [Claude Mythos Preview](https://anthropic.com/glasswing), Sonnet 4.0+, Opus 4.0+, Haiku 4.5+ ### When to use tool search **Good use cases:** - 10+ tools available in your system - Tool definitions consuming >10k tokens - Experiencing tool selection accuracy issues with large tool sets - Building MCP-powered systems with multiple servers (200+ tools) - Tool library growing over time **When traditional tool calling might be better:** - Less than 10 tools total - All tools are frequently used in every request - Very small tool definitions (\<100 tokens total) ### Optimization tips - Keep 3-5 most frequently used tools as non-deferred - Write clear, descriptive tool names and descriptions - Use consistent namespacing in tool names: prefix by service or resource (for example, `github_`, `slack_`) so that search queries naturally surface the right tool group - Use semantic keywords in descriptions that match how users describe tasks - Add a system prompt section describing available tool categories: "You can search for tools to interact with Slack, GitHub, and Jira" - Monitor which tools Claude discovers to refine descriptions ## Usage Tool search tool usage is tracked in the response usage object: ```json JSON { "usage": { "input_tokens": 1024, "output_tokens": 256, "server_tool_use": { "tool_search_requests": 2 } } } ``` ## Next steps Full tool catalog with model compatibility and parameters. Configure MCP toolsets with deferred loading. Combine tool search with cached tool definitions. Step-by-step guide for defining tools. ### Context management --- # Compaction URL: https://platform.claude.com/docs/en/build-with-claude/compaction # Compaction Server-side context compaction for managing long conversations that approach context window limits. --- This feature is eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned. Server-side compaction is the recommended strategy for managing context in long-running conversations and agentic workflows. It handles context management automatically with minimal integration work. Compaction extends the effective context length for long-running conversations and tasks by automatically summarizing older context when approaching the context window limit. This isn't just about staying under a token cap. As conversations get longer, models struggle to maintain focus across the full history. Compaction keeps the active context focused and performant by replacing stale content with concise summaries. For a deeper look at why long contexts degrade and how compaction helps, see [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents). This is ideal for: - Chat-based, multi-turn conversations where you want users to use one chat for a long period of time - Task-oriented prompts that require a lot of follow-up work (often tool use) that may exceed the context window Compaction is in beta. Include the [beta header](/docs/en/api/beta-headers) `compact-2026-01-12` in your API requests to use this feature. ## Supported models Compaction is supported on the following models: - [Claude Mythos Preview](https://anthropic.com/glasswing) (`claude-mythos-preview`) - Claude Opus 4.7 (`claude-opus-4-7`) - Claude Opus 4.6 (`claude-opus-4-6`) - Claude Sonnet 4.6 (`claude-sonnet-4-6`) ## How compaction works When compaction is enabled, Claude automatically summarizes your conversation when it approaches the configured token threshold. The API: 1. Detects when input tokens exceed your specified trigger threshold. 2. Generates a summary of the current conversation. 3. Creates a `compaction` block containing the summary. 4. Continues the response with the compacted context. On subsequent requests, append the response to your messages. The API automatically drops all message blocks prior to the `compaction` block, continuing the conversation from the summary. ![Flow diagram showing the compaction process: when input tokens exceed the trigger threshold, Claude generates a summary in a compaction block and continues the response with the compacted context](/docs/images/compaction-flow.svg) ## Basic usage Enable compaction by adding the `compact_20260112` strategy to `context_management.edits` in your Messages API request. ```bash cURL curl https://api.anthropic.com/v1/messages \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "anthropic-beta: compact-2026-01-12" \ --header "content-type: application/json" \ --data \ '{ "model": "claude-opus-4-7", "max_tokens": 4096, "messages": [ { "role": "user", "content": "Help me build a website" } ], "context_management": { "edits": [ { "type": "compact_20260112" } ] } }' ``` ```bash CLI ant beta:messages create --beta compact-2026-01-12 <<'YAML' model: claude-opus-4-7 max_tokens: 4096 messages: - role: user content: Help me build a website context_management: edits: - type: compact_20260112 YAML ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() messages = [{"role": "user", "content": "Help me build a website"}] response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-4-7", max_tokens=4096, messages=messages, context_management={"edits": [{"type": "compact_20260112"}]}, ) # Append the response (including any compaction block) to continue the conversation messages.append({"role": "assistant", "content": response.content}) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [ { role: "user", content: "Help me build a website" } ]; const response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages, context_management: { edits: [ { type: "compact_20260112" } ] } }); // Append the response (including any compaction block) to continue the conversation messages.push({ role: "assistant", content: response.content }); ``` ```csharp C# using System; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; using Anthropic; using Anthropic.Models.Beta.Messages; class Program { static async Task Main(string[] args) { AnthropicClient client = new(); var messages = new List { new() { Role = Role.User, Content = "Help me build a website" } }; var parameters = new MessageCreateParams { Betas = ["compact-2026-01-12"], Model = "claude-opus-4-7", MaxTokens = 4096, Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit()] } }; var response = await client.Beta.Messages.Create(parameters); // Append the response (including any compaction block) to continue the conversation messages.Add(new BetaMessageParam { Role = Role.Assistant, Content = response.Content.Select(b => new BetaContentBlockParam(b.Json)).ToList() }); Console.WriteLine(response); } } ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() messages := []anthropic.BetaMessageParam{ anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Help me build a website")), } response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: messages, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } // Append the response (including any compaction block) to continue the conversation messages = append(messages, response.ToParam()) fmt.Println(response) } ``` ```java Java hidelines={1..4,7..9,-2..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.beta.messages.MessageCreateParams; import com.anthropic.models.beta.messages.BetaMessage; import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; public class CompactionExample { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .addBeta("compact-2026-01-12") .model("claude-opus-4-7") .maxTokens(4096L) .addUserMessage("Help me build a website") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder().build()) .build()) .build(); BetaMessage response = client.beta().messages().create(params); // Append the response (including any compaction block) to continue the conversation // by including it in the next request's messages System.out.println(response); } } ``` ```php PHP hidelines={1..4} 'user', 'content' => 'Help me build a website'] ]; $response = $client->beta->messages->create( maxTokens: 4096, messages: $messages, model: 'claude-opus-4-7', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ ['type' => 'compact_20260112'] ] ] ); // Append the response (including any compaction block) to continue the conversation $messages[] = ['role' => 'assistant', 'content' => $response->content]; echo $response->content[0]->text; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new messages = [ { role: "user", content: "Help me build a website" } ] response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages: messages, context_management: { edits: [{ type: "compact_20260112" }] } ) # Append the response (including any compaction block) to continue the conversation messages << { role: "assistant", content: response.content } puts response ``` ## Parameters | Parameter | Type | Default | Description | |:----------|:-----|:--------|:------------| | `type` | string | Required | Must be `"compact_20260112"` | | `trigger` | object | 150,000 tokens | When to trigger compaction. Must be at least 50,000 tokens. | | `pause_after_compaction` | boolean | `false` | Whether to pause after generating the compaction summary | | `instructions` | string | `null` | Custom summarization prompt. Completely replaces the default prompt when provided. | ### Trigger configuration Configure when compaction triggers using the `trigger` parameter: ```bash CLI ant beta:messages create --beta compact-2026-01-12 <<'YAML' model: claude-opus-4-7 max_tokens: 4096 messages: - role: user content: Hello, Claude context_management: edits: - type: compact_20260112 trigger: type: input_tokens value: 150000 YAML ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() messages = [{"role": "user", "content": "Hello, Claude"}] response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-4-7", max_tokens=4096, messages=messages, context_management={ "edits": [ { "type": "compact_20260112", "trigger": {"type": "input_tokens", "value": 150000}, } ] }, ) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const messages: Anthropic.Beta.Messages.BetaMessageParam[] = []; const response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages, context_management: { edits: [ { type: "compact_20260112", trigger: { type: "input_tokens", value: 150000 } } ] } }); ``` ```csharp C# hidelines={1..13,-2..} using System; using System.Collections.Generic; using System.Threading.Tasks; using Anthropic; using Anthropic.Models.Beta.Messages; class Program { static async Task Main(string[] args) { AnthropicClient client = new(); List messages = [new() { Role = Role.User, Content = "Hello" }]; var parameters = new MessageCreateParams { Model = "claude-opus-4-7", MaxTokens = 4096, Betas = ["compact-2026-01-12"], Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit { Trigger = new BetaInputTokensTrigger(150000) }] } }; var message = await client.Beta.Messages.Create(parameters); Console.WriteLine(message); } } ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))} response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: messages, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{ Trigger: anthropic.BetaInputTokensTriggerParam{Value: 150000}, }}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```java Java hidelines={1..4,8..10,-2..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.beta.messages.MessageCreateParams; import com.anthropic.models.beta.messages.BetaMessage; import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; import com.anthropic.models.beta.messages.BetaInputTokensTrigger; public class CompactionExample { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model("claude-opus-4-7") .maxTokens(4096L) .addBeta("compact-2026-01-12") .addUserMessage("Hello, Claude") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder() .trigger(BetaInputTokensTrigger.builder() .value(150000L) .build()) .build()) .build()) .build(); BetaMessage response = client.beta().messages().create(params); System.out.println(response); } } ``` ```php PHP hidelines={1..4} 'user', 'content' => 'Hello, Claude']]; $message = $client->beta->messages->create( maxTokens: 4096, messages: $messages, model: 'claude-opus-4-7', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ [ 'type' => 'compact_20260112', 'trigger' => [ 'type' => 'input_tokens', 'value' => 150000 ] ] ] ] ); echo $message; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new messages = [{ role: "user", content: "Hello, Claude" }] response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages: messages, context_management: { edits: [ { type: "compact_20260112", trigger: { type: "input_tokens", value: 150000 } } ] } ) puts response ``` ### Custom summarization instructions By default, compaction uses the following summarization prompt: ```text You have written a partial transcript for the initial task above. Please write a summary of the transcript. The purpose of this summary is to provide continuity so you can continue to make progress towards solving the task in a future context, where the raw history above may not be accessible and will be replaced with this summary. Write down anything that would be helpful, including the state, next steps, learnings etc. You must wrap your summary in a

block. ``` You can provide custom instructions via the `instructions` parameter to replace this prompt entirely. Custom instructions don't supplement the default; they completely replace it: ```bash CLI ant beta:messages create --beta compact-2026-01-12 <<'YAML' model: claude-opus-4-7 max_tokens: 4096 messages: - role: user content: Hello, Claude context_management: edits: - type: compact_20260112 instructions: >- Focus on preserving code snippets, variable names, and technical decisions. YAML ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() messages = [{"role": "user", "content": "Hello, Claude"}] response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-4-7", max_tokens=4096, messages=messages, context_management={ "edits": [ { "type": "compact_20260112", "instructions": "Focus on preserving code snippets, variable names, and technical decisions.", } ] }, ) ``` ```typescript TypeScript nocheck hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const messages: Anthropic.Beta.Messages.BetaMessageParam[] = []; const response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages, context_management: { edits: [ { type: "compact_20260112", instructions: "Focus on preserving code snippets, variable names, and technical decisions." } ] } }); ``` ```csharp C# using System; using System.Threading.Tasks; using Anthropic; using Anthropic.Models.Beta.Messages; class Program { static async Task Main(string[] args) { AnthropicClient client = new(); var parameters = new MessageCreateParams { Betas = ["compact-2026-01-12"], Model = "claude-opus-4-7", MaxTokens = 4096, Messages = [ new BetaMessageParam { Role = Role.User, Content = "Help me build a Python web scraper" }, new BetaMessageParam { Role = Role.Assistant, Content = "I'll help you build a web scraper..." }, new BetaMessageParam { Role = Role.User, Content = "Add support for JavaScript-rendered pages" } ], ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit { Instructions = "Focus on preserving code snippets, variable names, and technical decisions." }] } }; var message = await client.Beta.Messages.Create(parameters); Console.WriteLine(message); } } ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: []anthropic.BetaMessageParam{ anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Help me build a Python web scraper")), {Role: anthropic.BetaMessageParamRoleAssistant, Content: []anthropic.BetaContentBlockParamUnion{anthropic.NewBetaTextBlock("I'll help you build a web scraper...")}}, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Add support for JavaScript-rendered pages")), }, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{ Instructions: anthropic.String("Focus on preserving code snippets, variable names, and technical decisions."), }}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```java Java hidelines={1..4,7..9,-2..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.beta.messages.MessageCreateParams; import com.anthropic.models.beta.messages.BetaMessage; import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; public class CompactionExample { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .addBeta("compact-2026-01-12") .model("claude-opus-4-7") .maxTokens(4096L) .addUserMessage("Help me build a Python web scraper") .addAssistantMessage("I'll help you build a web scraper...") .addUserMessage("Add support for JavaScript-rendered pages") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder() .instructions("Focus on preserving code snippets, variable names, and technical decisions.") .build()) .build()) .build(); BetaMessage response = client.beta().messages().create(params); System.out.println(response); } } ``` ```php PHP hidelines={1..3} beta->messages->create( maxTokens: 4096, messages: [ ['role' => 'user', 'content' => 'Help me build a Python web scraper'], ['role' => 'assistant', 'content' => "I'll help you build a web scraper..."], ['role' => 'user', 'content' => 'Add support for JavaScript-rendered pages'] ], model: 'claude-opus-4-7', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ [ 'type' => 'compact_20260112', 'instructions' => 'Focus on preserving code snippets, variable names, and technical decisions.' ] ] ] ); echo $response->content[0]->text; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages: [ { role: "user", content: "Help me build a Python web scraper" }, { role: "assistant", content: "I'll help you build a web scraper..." }, { role: "user", content: "Add support for JavaScript-rendered pages" } ], context_management: { edits: [ { type: "compact_20260112", instructions: "Focus on preserving code snippets, variable names, and technical decisions." } ] } ) puts response ``` ### Pausing after compaction Use `pause_after_compaction` to pause the API after generating the compaction summary. This allows you to add additional content blocks (such as preserving recent messages or specific instruction-oriented messages) before the API continues with the response. When enabled, the API returns a message with the `compaction` stop reason after generating the compaction block: ```bash CLI ant beta:messages create --beta compact-2026-01-12 \ --transform '{stop_reason,content}' --format jsonl <<'YAML' > resp.json model: claude-opus-4-7 max_tokens: 4096 messages: - role: user content: "Hello, Claude" context_management: edits: - type: compact_20260112 pause_after_compaction: true YAML # Check if compaction triggered a pause if grep -q '"stop_reason":"compaction"' resp.json; then # Response contains only the compaction block RESP=$(cat resp.json) CONTENT="${RESP#*\"content\":}" printf '%s' "${CONTENT%\}}" > content.json # Continue the request ant beta:messages create --beta compact-2026-01-12 < /dev/null model: claude-opus-4-7 max_tokens: 4096 messages: - role: user content: "Hello, Claude" - role: assistant content: $(cat content.json) context_management: edits: - type: compact_20260112 YAML fi ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() messages = [{"role": "user", "content": "Hello, Claude"}] response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-4-7", max_tokens=4096, messages=messages, context_management={ "edits": [{"type": "compact_20260112", "pause_after_compaction": True}] }, ) # Check if compaction triggered a pause if response.stop_reason == "compaction": # Response contains only the compaction block messages.append({"role": "assistant", "content": response.content}) # Continue the request response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-4-7", max_tokens=4096, messages=messages, context_management={"edits": [{"type": "compact_20260112"}]}, ) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [ { role: "user", content: "Hello, Claude" } ]; let response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages, context_management: { edits: [ { type: "compact_20260112", pause_after_compaction: true } ] } }); // Check if compaction triggered a pause if (response.stop_reason === "compaction") { // Response contains only the compaction block messages.push({ role: "assistant", content: response.content }); // Continue the request response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages, context_management: { edits: [{ type: "compact_20260112" }] } }); } ``` ```csharp C# using Anthropic; using Anthropic.Models.Beta.Messages; using System; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; class Program { static async Task Main(string[] args) { var client = new AnthropicClient(); var messages = new List { new() { Role = Role.User, Content = "Hello, Claude" } }; var parameters = new MessageCreateParams { Model = "claude-opus-4-7", MaxTokens = 4096, Betas = ["compact-2026-01-12"], Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit { PauseAfterCompaction = true }] } }; var response = await client.Beta.Messages.Create(parameters); if (response.StopReason == BetaStopReason.Compaction) { messages.Add(new BetaMessageParam { Role = Role.Assistant, Content = response.Content.Select(b => new BetaContentBlockParam(b.Json)).ToList() }); parameters = new() { Model = "claude-opus-4-7", MaxTokens = 4096, Betas = ["compact-2026-01-12"], Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit()] } }; response = await client.Beta.Messages.Create(parameters); } Console.WriteLine(response); } } ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))} compactEdit := anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{ PauseAfterCompaction: anthropic.Bool(true), }}, }, } response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: messages, ContextManagement: compactEdit, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } if response.StopReason == "compaction" { messages = append(messages, response.ToParam()) response, err = client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: messages, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } } fmt.Println(response) } ``` ```java Java hidelines={1..4,8..10,-2..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.beta.messages.MessageCreateParams; import com.anthropic.models.beta.messages.BetaMessage; import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; import com.anthropic.models.beta.messages.BetaStopReason; public class CompactionPauseExample { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model("claude-opus-4-7") .maxTokens(4096L) .addBeta("compact-2026-01-12") .addUserMessage("Help me build a website") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder() .pauseAfterCompaction(true) .build()) .build()) .build(); BetaMessage response = client.beta().messages().create(params); // Check if compaction triggered a pause if (response.stopReason().isPresent() && response.stopReason().get().equals(BetaStopReason.COMPACTION)) { // Append the compaction block and continue the request // by building a new request with the compacted context MessageCreateParams continueParams = MessageCreateParams.builder() .model("claude-opus-4-7") .maxTokens(4096L) .addBeta("compact-2026-01-12") .addUserMessage("Help me build a website") .addMessage(response) .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder().build()) .build()) .build(); response = client.beta().messages().create(continueParams); } System.out.println(response); } } ``` ```php PHP nocheck hidelines={1..4} 'user', 'content' => 'Hello, Claude']]; $response = $client->beta->messages->create( maxTokens: 4096, messages: $messages, model: 'claude-opus-4-7', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ [ 'type' => 'compact_20260112', 'pause_after_compaction' => true ] ] ] ); if ($response->stopReason === 'compaction') { $messages[] = [ 'role' => 'assistant', 'content' => $response->content ]; $response = $client->beta->messages->create( maxTokens: 4096, messages: $messages, model: 'claude-opus-4-7', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ ['type' => 'compact_20260112'] ] ] ); } echo $response; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new messages = [{ role: "user", content: "Hello, Claude" }] response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages: messages, context_management: { edits: [ { type: "compact_20260112", pause_after_compaction: true } ] } ) if response.stop_reason == :compaction messages << { role: "assistant", content: response.content } response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages: messages, context_management: { edits: [{ type: "compact_20260112" }] } ) end puts response ``` #### Enforcing a total token budget When a model works on long tasks with many tool-use iterations, total token consumption can grow significantly. You can combine `pause_after_compaction` with a compaction counter to estimate cumulative usage and gracefully wrap up the task once a budget is reached: ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() messages = [{"role": "user", "content": "Hello, Claude"}] TRIGGER_THRESHOLD = 100_000 TOTAL_TOKEN_BUDGET = 3_000_000 n_compactions = 0 response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-4-7", max_tokens=4096, messages=messages, context_management={ "edits": [ { "type": "compact_20260112", "trigger": {"type": "input_tokens", "value": TRIGGER_THRESHOLD}, "pause_after_compaction": True, } ] }, ) if response.stop_reason == "compaction": n_compactions += 1 messages.append({"role": "assistant", "content": response.content}) # Estimate total tokens consumed; prompt wrap-up if over budget if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET: messages.append( { "role": "user", "content": "Please wrap up your current work and summarize the final state.", } ) ``` ## Working with compaction blocks When compaction is triggered, the API returns a `compaction` block at the start of the assistant response. A long-running conversation may result in multiple compactions. The last compaction block reflects the final state of the prompt, replacing content prior to it with the generated summary. ```json Output { "content": [ { "type": "compaction", "content": "Summary of the conversation: The user requested help building a web scraper..." }, { "type": "text", "text": "Based on our conversation so far..." } ] } ``` ### Passing compaction blocks back You must pass the `compaction` block back to the API on subsequent requests to continue the conversation with the shortened prompt. The simplest approach is to append the entire response content to your messages: ```bash CLI ant beta:messages create --beta compact-2026-01-12 \ --transform content --format jsonl <<'YAML' > content.json model: claude-opus-4-7 max_tokens: 4096 messages: - role: user content: Hello, Claude context_management: edits: - type: compact_20260112 YAML # After receiving a response with a compaction block, append it as the # assistant turn and continue the conversation ant beta:messages create --beta compact-2026-01-12 < { new() { Role = Role.User, Content = "Help me build a web scraper" } }; var response = await client.Beta.Messages.Create(new() { Betas = ["compact-2026-01-12"], Model = "claude-opus-4-7", MaxTokens = 4096, Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit()] } }); messages.Add(new BetaMessageParam { Role = Role.Assistant, Content = response.Content.Select(b => new BetaContentBlockParam(b.Json)).ToList() }); messages.Add(new BetaMessageParam { Role = Role.User, Content = "Now add error handling" }); var nextResponse = await client.Beta.Messages.Create(new() { Betas = ["compact-2026-01-12"], Model = "claude-opus-4-7", MaxTokens = 4096, Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit()] } }); Console.WriteLine(nextResponse); } } ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() messages := []anthropic.BetaMessageParam{ anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Help me build a web scraper")), } compactEdit := anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}}, }, } response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: messages, ContextManagement: compactEdit, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } messages = append(messages, response.ToParam()) messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Now add error handling"))) nextResponse, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: messages, ContextManagement: compactEdit, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } fmt.Println(nextResponse) } ``` ```java Java hidelines={1..4,7..9,-2..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.beta.messages.MessageCreateParams; import com.anthropic.models.beta.messages.BetaMessage; import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; public class CompactionExample { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); // First request BetaMessage response = client.beta().messages().create( MessageCreateParams.builder() .addBeta("compact-2026-01-12") .model("claude-opus-4-7") .maxTokens(4096L) .addUserMessage("Help me build a web scraper") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder().build()) .build()) .build()); // After receiving a response with a compaction block, append the full // content (including compaction blocks) and continue the conversation BetaMessage nextResponse = client.beta().messages().create( MessageCreateParams.builder() .addBeta("compact-2026-01-12") .model("claude-opus-4-7") .maxTokens(4096L) .addUserMessage("Help me build a web scraper") .addMessage(response) .addUserMessage("Now add error handling") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder().build()) .build()) .build()); System.out.println(nextResponse); } } ``` ```php PHP hidelines={1..4} 'user', 'content' => 'Help me build a web scraper'] ]; $response = $client->beta->messages->create( maxTokens: 4096, messages: $messages, model: 'claude-opus-4-7', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [['type' => 'compact_20260112']] ] ); $messages[] = ['role' => 'assistant', 'content' => $response->content]; $messages[] = ['role' => 'user', 'content' => 'Now add error handling']; $nextResponse = $client->beta->messages->create( maxTokens: 4096, messages: $messages, model: 'claude-opus-4-7', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [['type' => 'compact_20260112']] ] ); echo $nextResponse->content[0]->text; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new messages = [ { role: "user", content: "Help me build a web scraper" } ] response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages: messages, context_management: { edits: [{ type: "compact_20260112" }] } ) messages << { role: "assistant", content: response.content } messages << { role: "user", content: "Now add error handling" } next_response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages: messages, context_management: { edits: [{ type: "compact_20260112" }] } ) puts next_response.content ``` When the API receives a `compaction` block, all content blocks before it are ignored. You can either: - Keep the original messages in your list and let the API handle removing the compacted content - Manually drop the compacted messages and only include the compaction block onwards ### Streaming When streaming responses with compaction enabled, you'll receive a `content_block_start` event when compaction begins. The compaction block streams differently from text blocks. You'll receive a `content_block_start` event, followed by a single `content_block_delta` with the complete summary content (no intermediate streaming), and then a `content_block_stop` event. ```bash CLI nocheck ant beta:messages create --stream --format jsonl \ --beta compact-2026-01-12 <<'YAML' model: claude-opus-4-7 max_tokens: 4096 messages: - role: user content: Hello, Claude context_management: edits: - type: compact_20260112 YAML ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() messages = [{"role": "user", "content": "Hello, Claude"}] with client.beta.messages.stream( betas=["compact-2026-01-12"], model="claude-opus-4-7", max_tokens=4096, messages=messages, context_management={"edits": [{"type": "compact_20260112"}]}, ) as stream: for event in stream: if event.type == "content_block_start": if event.content_block.type == "compaction": print("Compaction started...") elif event.content_block.type == "text": print("Text response started...") elif event.type == "content_block_delta": if event.delta.type == "compaction_delta": print(f"Compaction complete: {len(event.delta.content or '')} chars") elif event.delta.type == "text_delta": print(event.delta.text, end="", flush=True) # Get the final accumulated message message = stream.get_final_message() messages.append({"role": "assistant", "content": message.content}) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const messages: Anthropic.Beta.Messages.BetaMessageParam[] = []; const stream = await client.beta.messages.stream({ betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages, context_management: { edits: [{ type: "compact_20260112" }] } }); for await (const event of stream) { if (event.type === "content_block_start") { if (event.content_block.type === "compaction") { console.log("Compaction started..."); } else if (event.content_block.type === "text") { console.log("Text response started..."); } } else if (event.type === "content_block_delta") { if (event.delta.type === "compaction_delta") { console.log(`Compaction complete: ${event.delta.content?.length ?? 0} chars`); } else if (event.delta.type === "text_delta") { process.stdout.write(event.delta.text); } } } // Get the final accumulated message const message = await stream.finalMessage(); messages.push({ role: "assistant", content: message.content }); ``` ```csharp C# hidelines={1..13,-2..} using System; using System.Collections.Generic; using System.Threading.Tasks; using Anthropic; using Anthropic.Models.Beta.Messages; class Program { static async Task Main(string[] args) { var client = new AnthropicClient(); List messages = [new() { Role = Role.User, Content = "Hello" }]; var parameters = new MessageCreateParams { Betas = ["compact-2026-01-12"], Model = "claude-opus-4-7", MaxTokens = 4096, Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit()] } }; await foreach (var streamEvent in client.Beta.Messages.CreateStreaming(parameters)) { if (streamEvent.TryPickContentBlockStart(out var startEvent)) { if (startEvent.ContentBlock.TryPickBetaCompaction(out _)) { Console.WriteLine("Compaction started..."); } else if (startEvent.ContentBlock.TryPickBetaText(out _)) { Console.WriteLine("Text response started..."); } } else if (streamEvent.TryPickContentBlockDelta(out var deltaEvent)) { if (deltaEvent.Delta.TryPickCompaction(out var compactionDelta)) { Console.WriteLine($"Compaction complete: {compactionDelta.Content?.Length ?? 0} chars"); } else if (deltaEvent.Delta.TryPickText(out var textDelta)) { Console.Write(textDelta.Text); } } } } } ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))} stream := client.Beta.Messages.NewStreaming(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: messages, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) for stream.Next() { event := stream.Current() switch eventVariant := event.AsAny().(type) { case anthropic.BetaRawContentBlockStartEvent: switch eventVariant.ContentBlock.AsAny().(type) { case anthropic.BetaCompactionBlock: fmt.Println("Compaction started...") case anthropic.BetaTextBlock: fmt.Println("Text response started...") } case anthropic.BetaRawContentBlockDeltaEvent: switch deltaVariant := eventVariant.Delta.AsAny().(type) { case anthropic.BetaCompactionContentBlockDelta: fmt.Printf("Compaction complete: %d chars\n", len(deltaVariant.Content)) case anthropic.BetaTextDelta: fmt.Print(deltaVariant.Text) } } } if err := stream.Err(); err != nil { log.Fatal(err) } } ``` ```java Java hidelines={1..3,6..8,-2..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.beta.messages.MessageCreateParams; import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; public class CompactionStreamingExample { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model("claude-opus-4-7") .maxTokens(4096L) .addBeta("compact-2026-01-12") .addUserMessage("Hello, Claude") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder().build()) .build()) .build(); try (var streamResponse = client.beta().messages().createStreaming(params)) { streamResponse.stream().forEach(event -> { event.contentBlockStart().ifPresent(startEvent -> { startEvent.contentBlock().compaction().ifPresent(c -> System.out.println("Compaction started...") ); startEvent.contentBlock().text().ifPresent(t -> System.out.println("Text response started...") ); }); event.contentBlockDelta().ifPresent(deltaEvent -> { deltaEvent.delta().compaction().ifPresent(cd -> System.out.println("Compaction complete: " + cd.content().map(String::length).orElse(0) + " chars") ); deltaEvent.delta().text().ifPresent(td -> System.out.print(td.text()) ); }); }); } } } ``` ```php PHP hidelines={1..4} 'user', 'content' => 'Hello, Claude']]; $stream = $client->beta->messages->createStream( maxTokens: 4096, messages: $messages, model: 'claude-opus-4-7', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ ['type' => 'compact_20260112'] ] ] ); foreach ($stream as $event) { if ($event->type === 'content_block_start') { if ($event->contentBlock->type === 'compaction') { echo "Compaction started...\n"; } elseif ($event->contentBlock->type === 'text') { echo "Text response started...\n"; } } elseif ($event->type === 'content_block_delta') { if ($event->delta->type === 'compaction_delta') { echo "Compaction complete: " . strlen($event->delta->content ?? '') . " chars\n"; } elseif ($event->delta->type === 'text_delta') { echo $event->delta->text; } } } ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new messages = [{ role: "user", content: "Hello, Claude" }] stream = client.beta.messages.stream( betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages: messages, context_management: { edits: [{ type: "compact_20260112" }] } ) stream.each do |event| case event.type when :content_block_start if event.content_block.type == :compaction puts "Compaction started..." elsif event.content_block.type == :text puts "Text response started..." end when :content_block_delta if event.delta.type == :compaction_delta puts "Compaction complete: #{(event.delta.content || "").length} chars" elsif event.delta.type == :text_delta print event.delta.text end end end ``` ### Prompt caching Compaction works well with [prompt caching](/docs/en/build-with-claude/prompt-caching). You can add a `cache_control` breakpoint on compaction blocks to cache the summarized content. The original compacted content is ignored. ```json { "role": "assistant", "content": [ { "type": "compaction", "content": "[summary text]", "cache_control": { "type": "ephemeral" } }, { "type": "text", "text": "Based on our conversation..." } ] } ``` #### Maximizing cache hits with system prompts When compaction occurs, the summary becomes new content that needs to be written to the cache. Without additional cache breakpoints, this would also invalidate any cached system prompt, requiring it to be re-cached along with the compaction summary. To maximize cache hit rates, add a `cache_control` breakpoint at the end of your system prompt. This keeps the system prompt cached separately from the conversation, so when compaction occurs: - The system prompt cache remains valid and is read from cache - Only the compaction summary needs to be written as a new cache entry ```bash CLI ant beta:messages create --beta compact-2026-01-12 <<'YAML' model: claude-opus-4-7 max_tokens: 4096 system: - type: text text: You are a helpful coding assistant... cache_control: type: ephemeral messages: - role: user content: Hello, Claude context_management: edits: - type: compact_20260112 YAML ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() messages = [{"role": "user", "content": "Hello, Claude"}] response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-4-7", max_tokens=4096, system=[ { "type": "text", "text": "You are a helpful coding assistant...", "cache_control": { "type": "ephemeral" }, # Cache the system prompt separately } ], messages=messages, context_management={"edits": [{"type": "compact_20260112"}]}, ) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const messages: Anthropic.Beta.Messages.BetaMessageParam[] = []; const response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, system: [ { type: "text", text: "You are a helpful coding assistant...", cache_control: { type: "ephemeral" } // Cache the system prompt separately } ], messages, context_management: { edits: [{ type: "compact_20260112" }] } }); ``` ```csharp C# using System; using System.Collections.Generic; using System.Threading.Tasks; using Anthropic; using Anthropic.Models.Beta.Messages; class Program { static async Task Main(string[] args) { var client = new AnthropicClient(); var parameters = new MessageCreateParams { Betas = ["compact-2026-01-12"], Model = "claude-opus-4-7", MaxTokens = 4096, System = new List { new() { Text = "You are a helpful coding assistant...", CacheControl = new BetaCacheControlEphemeral() } }, Messages = [], ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit()] } }; var response = await client.Beta.Messages.Create(parameters); Console.WriteLine(response); } } ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, System: []anthropic.BetaTextBlockParam{ { Text: "You are a helpful coding assistant...", CacheControl: anthropic.NewBetaCacheControlEphemeralParam(), }, }, Messages: []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))}, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```java Java hidelines={1..5,9..12,-2..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.beta.messages.MessageCreateParams; import com.anthropic.models.beta.messages.BetaMessage; import com.anthropic.models.beta.messages.BetaTextBlockParam; import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; import com.anthropic.models.beta.messages.BetaCacheControlEphemeral; import java.util.List; public class CompactionExample { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model("claude-opus-4-7") .maxTokens(4096L) .addBeta("compact-2026-01-12") .systemOfBetaTextBlockParams(List.of( BetaTextBlockParam.builder() .text("You are a helpful coding assistant...") .cacheControl(BetaCacheControlEphemeral.builder().build()) .build() )) .addUserMessage("Hello, Claude") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder().build()) .build()) .build(); BetaMessage response = client.beta().messages().create(params); System.out.println(response); } } ``` ```php PHP hidelines={1..3} beta->messages->create( maxTokens: 4096, messages: [['role' => 'user', 'content' => 'Hello, Claude']], model: 'claude-opus-4-7', betas: ['compact-2026-01-12'], system: [ [ 'type' => 'text', 'text' => 'You are a helpful coding assistant...', 'cache_control' => [ 'type' => 'ephemeral' ] ] ], contextManagement: [ 'edits' => [ ['type' => 'compact_20260112'] ] ] ); echo $response->content[0]->text; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, system: [ { type: "text", text: "You are a helpful coding assistant...", cache_control: { type: "ephemeral" } } ], messages: [], context_management: { edits: [{ type: "compact_20260112" }] } ) puts response ``` This approach is particularly beneficial for long system prompts, as they remain cached even across multiple compaction events throughout a conversation. ## Understanding usage Compaction requires an additional sampling step, which contributes to rate limits and billing. The API returns detailed usage information in the response: ```json Output { "usage": { "input_tokens": 23000, "output_tokens": 1000, "iterations": [ { "type": "compaction", "input_tokens": 180000, "output_tokens": 3500 }, { "type": "message", "input_tokens": 23000, "output_tokens": 1000 } ] } } ``` The `iterations` array shows usage for each sampling iteration. When compaction occurs, you'll see a `compaction` iteration followed by the main `message` iteration. The top-level `input_tokens` and `output_tokens` match the `message` iteration exactly in this example because there is only one non-compaction iteration. The final iteration's token counts reflect the effective context size after compaction. The top-level `input_tokens` and `output_tokens` do not include compaction iteration usage. They reflect the sum of all non-compaction iterations. To calculate total tokens consumed and billed for a request, sum across all entries in the `usage.iterations` array. If you previously relied on `usage.input_tokens` and `usage.output_tokens` for cost tracking or auditing, you'll need to update your tracking logic to aggregate across `usage.iterations` when compaction is enabled. The `iterations` array is only populated when a new compaction is triggered during the request. Re-applying a previous `compaction` block incurs no additional compaction cost, and the top-level usage fields remain accurate in that case. ## Combining with other features ### Server tools When using server tools (like web search), the compaction trigger is checked at the start of each sampling iteration. Compaction may occur multiple times within a single request depending on your trigger threshold and the amount of output generated. ### Token counting The token counting endpoint (`/v1/messages/count_tokens`) applies existing `compaction` blocks in your prompt but does not trigger new compactions. Use it to check your effective token count after previous compactions: ```bash CLI cat > request.yaml <<'YAML' model: claude-opus-4-7 messages: - role: user content: Hello, Claude context_management: edits: - type: compact_20260112 YAML CURRENT=$(ant beta:messages count-tokens \ --beta compact-2026-01-12 \ --transform input_tokens --raw-output < request.yaml) ORIGINAL=$(ant beta:messages count-tokens \ --beta compact-2026-01-12 \ --transform context_management.original_input_tokens \ --raw-output < request.yaml) printf 'Current tokens: %s\n' "$CURRENT" printf 'Original tokens: %s\n' "$ORIGINAL" ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() messages = [{"role": "user", "content": "Hello, Claude"}] count_response = client.beta.messages.count_tokens( betas=["compact-2026-01-12"], model="claude-opus-4-7", messages=messages, context_management={"edits": [{"type": "compact_20260112"}]}, ) print(f"Current tokens: {count_response.input_tokens}") print(f"Original tokens: {count_response.context_management.original_input_tokens}") ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [ { role: "user", content: "Summarize the key points of our conversation so far." } ]; const countResponse = await client.beta.messages.countTokens({ betas: ["compact-2026-01-12"], model: "claude-opus-4-7", messages, context_management: { edits: [{ type: "compact_20260112" }] } }); console.log(`Current tokens: ${countResponse.input_tokens}`); console.log(`Original tokens: ${countResponse.context_management!.original_input_tokens}`); ``` ```csharp C# hidelines={1..13,-2..} using System; using System.Collections.Generic; using System.Threading.Tasks; using Anthropic; using Anthropic.Models.Beta.Messages; class Program { static async Task Main(string[] args) { AnthropicClient client = new(); List messages = [new() { Role = Role.User, Content = "Hello" }]; var countParams = new MessageCountTokensParams { Model = "claude-opus-4-7", Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit()] }, Betas = ["compact-2026-01-12"] }; var countResponse = await client.Beta.Messages.CountTokens(countParams); Console.WriteLine($"Current tokens: {countResponse.InputTokens}"); Console.WriteLine($"Original tokens: {countResponse.ContextManagement?.OriginalInputTokens}"); } } ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))} countResponse, err := client.Beta.Messages.CountTokens(context.TODO(), anthropic.BetaMessageCountTokensParams{ Model: anthropic.ModelClaudeOpus4_7, Messages: messages, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } fmt.Printf("Current tokens: %d\n", countResponse.InputTokens) fmt.Printf("Original tokens: %d\n", countResponse.ContextManagement.OriginalInputTokens) } ``` ```java Java hidelines={1..2,7..9,-2..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.beta.messages.BetaMessageTokensCount; import com.anthropic.models.beta.messages.MessageCountTokensParams; import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; public class Main { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCountTokensParams params = MessageCountTokensParams.builder() .model("claude-opus-4-7") .addUserMessage("Hello, Claude") .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder().build()) .build()) .addBeta("compact-2026-01-12") .build(); BetaMessageTokensCount countResponse = client.beta().messages().countTokens(params); System.out.println("Current tokens: " + countResponse.inputTokens()); System.out.println("Original tokens: " + countResponse.contextManagement().get().originalInputTokens()); } } ``` ```php PHP hidelines={1..4} 'user', 'content' => 'Hello, Claude']]; $countResponse = $client->beta->messages->countTokens( messages: $messages, model: 'claude-opus-4-7', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ ['type' => 'compact_20260112'] ] ] ); echo "Current tokens: " . $countResponse->inputTokens . "\n"; echo "Original tokens: " . $countResponse->contextManagement->originalInputTokens . "\n"; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new messages = [{ role: "user", content: "Hello, Claude" }] count_response = client.beta.messages.count_tokens( betas: ["compact-2026-01-12"], model: "claude-opus-4-7", messages: messages, context_management: { edits: [{ type: "compact_20260112" }] } ) puts "Current tokens: #{count_response.input_tokens}" puts "Original tokens: #{count_response.context_management.original_input_tokens}" ``` ## Examples Here's a complete example of a long-running conversation with compaction: ```bash CLI # The CLI handles individual turns; maintain the messages array in the # calling script. See the SDK tabs for the full chat() loop. Single-turn # request shape: ant beta:messages create --beta compact-2026-01-12 \ --transform 'content.#(type=="text").text' --raw-output <<'YAML' model: claude-opus-4-7 max_tokens: 4096 messages: - role: user content: Help me build a Python web scraper context_management: edits: - type: compact_20260112 trigger: type: input_tokens value: 100000 YAML ``` ```python Python hidelines={1..2} import anthropic client = anthropic.Anthropic() messages: list[dict] = [] def chat(user_message: str) -> str: messages.append({"role": "user", "content": user_message}) response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-4-7", max_tokens=4096, messages=messages, context_management={ "edits": [ { "type": "compact_20260112", "trigger": {"type": "input_tokens", "value": 100000}, } ] }, ) # Append response (compaction blocks are automatically included) messages.append({"role": "assistant", "content": response.content}) # Return the text content return next(block.text for block in response.content if block.type == "text") # Run a long conversation print(chat("Help me build a Python web scraper")) print(chat("Add support for JavaScript-rendered pages")) print(chat("Now add rate limiting and error handling")) # ... continue as long as needed ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const messages: Anthropic.Beta.BetaMessageParam[] = []; async function chat(userMessage: string): Promise { messages.push({ role: "user", content: userMessage }); const response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages, context_management: { edits: [ { type: "compact_20260112", trigger: { type: "input_tokens", value: 100000 } } ] } }); // Append response (compaction blocks are automatically included) messages.push({ role: "assistant", content: response.content }); // Return the text content const textBlock = response.content.find((block) => block.type === "text"); return textBlock?.text ?? ""; } // Run a long conversation console.log(await chat("Help me build a Python web scraper")); console.log(await chat("Add support for JavaScript-rendered pages")); console.log(await chat("Now add rate limiting and error handling")); // ... continue as long as needed ``` ```csharp C# using System; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; using Anthropic; using Anthropic.Models.Beta.Messages; public class Program { static async Task Main(string[] args) { AnthropicClient client = new(); List messages = new(); Console.WriteLine(await Chat(client, messages, "Help me build a Python web scraper")); Console.WriteLine(await Chat(client, messages, "Add support for JavaScript-rendered pages")); Console.WriteLine(await Chat(client, messages, "Now add rate limiting and error handling")); } static async Task Chat(AnthropicClient client, List messages, string userMessage) { messages.Add(new() { Role = Role.User, Content = userMessage }); var parameters = new MessageCreateParams { Betas = ["compact-2026-01-12"], Model = "claude-opus-4-7", MaxTokens = 4096, Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit { Trigger = new BetaInputTokensTrigger(100000) }] } }; var response = await client.Beta.Messages.Create(parameters); messages.Add(new() { Role = Role.Assistant, Content = response.Content.Select(b => new BetaContentBlockParam(b.Json)).ToList() }); return response.Content .Select(b => b.Value) .OfType() .Select(tb => tb.Text) .FirstOrDefault() ?? ""; } } ``` ```go Go package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) var ( client = anthropic.NewClient() messages []anthropic.BetaMessageParam ) func chat(userMessage string) string { messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(userMessage))) response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: messages, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{ Trigger: anthropic.BetaInputTokensTriggerParam{Value: 100000}, }}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } messages = append(messages, response.ToParam()) for _, block := range response.Content { if variant, ok := block.AsAny().(anthropic.BetaTextBlock); ok { return variant.Text } } return "" } func main() { fmt.Println(chat("Help me build a Python web scraper")) fmt.Println(chat("Add support for JavaScript-rendered pages")) fmt.Println(chat("Now add rate limiting and error handling")) } ``` ```java Java hidelines={1..5,9..12,-1} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.beta.messages.MessageCreateParams; import com.anthropic.models.beta.messages.BetaMessage; import com.anthropic.models.beta.messages.BetaMessageParam; import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; import com.anthropic.models.beta.messages.BetaInputTokensTrigger; import java.util.ArrayList; import java.util.List; public class CompactionExample { private static final AnthropicClient client = AnthropicOkHttpClient.fromEnv(); private static final List messages = new ArrayList<>(); public static void main(String[] args) { System.out.println(chat("Help me build a Python web scraper")); System.out.println(chat("Add support for JavaScript-rendered pages")); System.out.println(chat("Now add rate limiting and error handling")); } private static String chat(String userMessage) { messages.add(BetaMessageParam.builder() .role(BetaMessageParam.Role.USER) .content(userMessage) .build()); MessageCreateParams params = MessageCreateParams.builder() .addBeta("compact-2026-01-12") .model("claude-opus-4-7") .maxTokens(4096L) .messages(messages) .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder() .trigger(BetaInputTokensTrigger.builder() .value(100000L) .build()) .build()) .build()) .build(); BetaMessage response = client.beta().messages().create(params); // Append response (compaction blocks are automatically included) messages.add(response.toParam()); return response.content().stream() .filter(block -> block.text().isPresent()) .map(block -> block.text().get().text()) .findFirst() .orElse(""); } } ``` ```php PHP hidelines={1..3} 'user', 'content' => $userMessage]; $response = $client->beta->messages->create( maxTokens: 4096, messages: $messages, model: 'claude-opus-4-7', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ [ 'type' => 'compact_20260112', 'trigger' => ['type' => 'input_tokens', 'value' => 100000] ] ] ] ); $messages[] = ['role' => 'assistant', 'content' => $response->content]; foreach ($response->content as $block) { if ($block->type === 'text') { return $block->text; } } return ''; } echo chat($client, $messages, "Help me build a Python web scraper") . "\n"; echo chat($client, $messages, "Add support for JavaScript-rendered pages") . "\n"; echo chat($client, $messages, "Now add rate limiting and error handling") . "\n"; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new messages = [] def chat(client, messages, user_message) messages << { role: "user", content: user_message } response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages: messages, context_management: { edits: [ { type: "compact_20260112", trigger: { type: "input_tokens", value: 100000 } } ] } ) messages << { role: "assistant", content: response.content } response.content.find { |block| block.type == :text }&.text || "" end puts chat(client, messages, "Help me build a Python web scraper") puts chat(client, messages, "Add support for JavaScript-rendered pages") puts chat(client, messages, "Now add rate limiting and error handling") ``` Here's an example that uses `pause_after_compaction` to preserve the prior exchange and the current user message (three messages total) verbatim instead of summarizing them: ```bash CLI # The CLI handles individual turns; maintain the messages array in the # calling script. See the SDK tabs for the full chat() loop with # pause-and-preserve handling. Single-turn request shape: ant beta:messages create --beta compact-2026-01-12 \ --transform 'content.#(type=="text").text' --raw-output <<'YAML' model: claude-opus-4-7 max_tokens: 4096 messages: - role: user content: Help me build a Python web scraper context_management: edits: - type: compact_20260112 trigger: type: input_tokens value: 100000 pause_after_compaction: true YAML ``` ```python Python hidelines={1} import anthropic from typing import Any client = anthropic.Anthropic() messages: list[dict[str, Any]] = [] def chat(user_message: str) -> str: messages.append({"role": "user", "content": user_message}) response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-4-7", max_tokens=4096, messages=messages, context_management={ "edits": [ { "type": "compact_20260112", "trigger": {"type": "input_tokens", "value": 100000}, "pause_after_compaction": True, } ] }, ) # Check if compaction occurred and paused if response.stop_reason == "compaction": # Get the compaction block from the response compaction_block = response.content[0] # Preserve the prior exchange + current user message (3 messages) # by including them after the compaction block preserved_messages = messages[-3:] if len(messages) >= 3 else messages # Build new message list: compaction + preserved messages new_assistant_content = [compaction_block] messages_after_compaction = [ {"role": "assistant", "content": new_assistant_content} ] + preserved_messages # Continue the request with the compacted context + preserved messages response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-4-7", max_tokens=4096, messages=messages_after_compaction, context_management={"edits": [{"type": "compact_20260112"}]}, ) # Update our message list to reflect the compaction messages.clear() messages.extend(messages_after_compaction) # Append the final response messages.append({"role": "assistant", "content": response.content}) # Return the text content return next(block.text for block in response.content if block.type == "text") # Run a long conversation print(chat("Help me build a Python web scraper")) print(chat("Add support for JavaScript-rendered pages")) print(chat("Now add rate limiting and error handling")) # ... continue as long as needed ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); let messages: Anthropic.Beta.BetaMessageParam[] = []; async function chat(userMessage: string): Promise { messages.push({ role: "user", content: userMessage }); let response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages, context_management: { edits: [ { type: "compact_20260112", trigger: { type: "input_tokens", value: 100000 }, pause_after_compaction: true } ] } }); // Check if compaction occurred and paused if (response.stop_reason === "compaction") { // Get the compaction block from the response const compactionBlock = response.content[0]; // Preserve the prior exchange + current user message (3 messages) // by including them after the compaction block const preservedMessages = messages.length >= 3 ? messages.slice(-3) : [...messages]; // Build new message list: compaction + preserved messages const messagesAfterCompaction: Anthropic.Beta.BetaMessageParam[] = [ { role: "assistant", content: [compactionBlock] }, ...preservedMessages ]; // Continue the request with the compacted context + preserved messages response = await client.beta.messages.create({ betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages: messagesAfterCompaction, context_management: { edits: [{ type: "compact_20260112" }] } }); // Update our message list to reflect the compaction messages = messagesAfterCompaction; } // Append the final response messages.push({ role: "assistant", content: response.content }); // Return the text content const textBlock = response.content.find((block) => block.type === "text"); return textBlock?.text ?? ""; } // Run a long conversation console.log(await chat("Help me build a Python web scraper")); console.log(await chat("Add support for JavaScript-rendered pages")); console.log(await chat("Now add rate limiting and error handling")); // ... continue as long as needed ``` ```csharp C# using System; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; using Anthropic; using Anthropic.Models.Beta.Messages; public class CompactionExample { private static AnthropicClient client = new(); private static List messages = new(); static async Task Chat(string userMessage) { messages.Add(new() { Role = Role.User, Content = userMessage }); var response = await client.Beta.Messages.Create(new() { Betas = ["compact-2026-01-12"], Model = "claude-opus-4-7", MaxTokens = 4096, Messages = messages, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit { Trigger = new BetaInputTokensTrigger(100000), PauseAfterCompaction = true }] } }); if (response.StopReason == BetaStopReason.Compaction) { if (!response.Content[0].TryPickCompaction(out var cb)) throw new InvalidOperationException("Expected compaction block"); var preserved = messages.Count >= 3 ? messages.Skip(messages.Count - 3).ToList() : new List(messages); var messagesAfterCompaction = new List { new() { Role = Role.Assistant, Content = new List { new BetaCompactionBlockParam(cb.Content) } } }; messagesAfterCompaction.AddRange(preserved); response = await client.Beta.Messages.Create(new() { Betas = ["compact-2026-01-12"], Model = "claude-opus-4-7", MaxTokens = 4096, Messages = messagesAfterCompaction, ContextManagement = new BetaContextManagementConfig { Edits = [new BetaCompact20260112Edit()] } }); messages = messagesAfterCompaction; } messages.Add(new() { Role = Role.Assistant, Content = response.Content.Select(b => new BetaContentBlockParam(b.Json)).ToList() }); return response.Content .Select(b => b.Value) .OfType() .Select(tb => tb.Text) .FirstOrDefault() ?? ""; } static async Task Main() { Console.WriteLine(await Chat("Help me build a Python web scraper")); Console.WriteLine(await Chat("Add support for JavaScript-rendered pages")); Console.WriteLine(await Chat("Now add rate limiting and error handling")); } } ``` ```go Go package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) var ( client = anthropic.NewClient() messages []anthropic.BetaMessageParam ) func chat(userMessage string) string { messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(userMessage))) compactEdit := anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{ Trigger: anthropic.BetaInputTokensTriggerParam{Value: 100000}, PauseAfterCompaction: anthropic.Bool(true), }}, }, } response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: messages, ContextManagement: compactEdit, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } if response.StopReason == "compaction" { compactionParam := response.Content[0].ToParam() var preserved []anthropic.BetaMessageParam if len(messages) >= 3 { preserved = messages[len(messages)-3:] } else { preserved = messages } messagesAfterCompaction := []anthropic.BetaMessageParam{ {Role: anthropic.BetaMessageParamRoleAssistant, Content: []anthropic.BetaContentBlockParamUnion{compactionParam}}, } messagesAfterCompaction = append(messagesAfterCompaction, preserved...) response, err = client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: messagesAfterCompaction, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}}, }, }, Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, }) if err != nil { log.Fatal(err) } messages = messagesAfterCompaction } messages = append(messages, response.ToParam()) for _, block := range response.Content { if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok { return textBlock.Text } } return "" } func main() { fmt.Println(chat("Help me build a Python web scraper")) fmt.Println(chat("Add support for JavaScript-rendered pages")) fmt.Println(chat("Now add rate limiting and error handling")) } ``` ```java Java hidelines={1..5,10..13,-1} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.beta.messages.MessageCreateParams; import com.anthropic.models.beta.messages.BetaMessage; import com.anthropic.models.beta.messages.BetaMessageParam; import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaCompact20260112Edit; import com.anthropic.models.beta.messages.BetaInputTokensTrigger; import com.anthropic.models.beta.messages.BetaStopReason; import java.util.ArrayList; import java.util.List; public class CompactionExample { private static final AnthropicClient client = AnthropicOkHttpClient.fromEnv(); private static final List messages = new ArrayList<>(); public static String chat(String userMessage) { messages.add(BetaMessageParam.builder() .role(BetaMessageParam.Role.USER) .content(userMessage) .build()); MessageCreateParams params = MessageCreateParams.builder() .addBeta("compact-2026-01-12") .model("claude-opus-4-7") .maxTokens(4096L) .messages(messages) .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder() .trigger(BetaInputTokensTrigger.builder() .value(100000L) .build()) .pauseAfterCompaction(true) .build()) .build()) .build(); BetaMessage response = client.beta().messages().create(params); // Check if compaction occurred and paused if (response.stopReason().isPresent() && response.stopReason().get().equals(BetaStopReason.COMPACTION)) { // Preserve the prior exchange + current user message (3 messages) List preservedMessages = messages.size() >= 3 ? new ArrayList<>(messages.subList(messages.size() - 3, messages.size())) : new ArrayList<>(messages); // Build new message list: compaction + preserved messages List messagesAfterCompaction = new ArrayList<>(); messagesAfterCompaction.add(response.toParam()); messagesAfterCompaction.addAll(preservedMessages); // Continue the request with the compacted context + preserved messages MessageCreateParams continueParams = MessageCreateParams.builder() .addBeta("compact-2026-01-12") .model("claude-opus-4-7") .maxTokens(4096L) .messages(messagesAfterCompaction) .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaCompact20260112Edit.builder().build()) .build()) .build(); response = client.beta().messages().create(continueParams); // Update our message list to reflect the compaction messages.clear(); messages.addAll(messagesAfterCompaction); } // Append the final response messages.add(response.toParam()); return response.content().stream() .filter(block -> block.text().isPresent()) .map(block -> block.text().get().text()) .findFirst() .orElse(""); } public static void main(String[] args) { System.out.println(chat("Help me build a Python web scraper")); System.out.println(chat("Add support for JavaScript-rendered pages")); System.out.println(chat("Now add rate limiting and error handling")); } } ``` ```php PHP nocheck hidelines={1..4} 'user', 'content' => $userMessage]; $response = $client->beta->messages->create( maxTokens: 4096, messages: $messages, model: 'claude-opus-4-7', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [ [ 'type' => 'compact_20260112', 'trigger' => ['type' => 'input_tokens', 'value' => 100000], 'pause_after_compaction' => true ] ] ] ); if ($response->stopReason === 'compaction') { $compactionBlock = $response->content[0]; $preserved = count($messages) >= 3 ? array_slice($messages, -3) : $messages; $messagesAfterCompaction = array_merge( [['role' => 'assistant', 'content' => [$compactionBlock]]], $preserved ); $response = $client->beta->messages->create( maxTokens: 4096, messages: $messagesAfterCompaction, model: 'claude-opus-4-7', betas: ['compact-2026-01-12'], contextManagement: [ 'edits' => [['type' => 'compact_20260112']] ] ); $messages = $messagesAfterCompaction; } $messages[] = ['role' => 'assistant', 'content' => $response->content]; foreach ($response->content as $block) { if ($block->type === 'text') { return $block->text; } } return ''; } echo chat($client, $messages, "Help me build a Python web scraper") . "\n"; echo chat($client, $messages, "Add support for JavaScript-rendered pages") . "\n"; echo chat($client, $messages, "Now add rate limiting and error handling") . "\n"; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new messages = [] def chat(client, messages, user_message) messages << { role: "user", content: user_message } response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages: messages, context_management: { edits: [ { type: "compact_20260112", trigger: { type: "input_tokens", value: 100000 }, pause_after_compaction: true } ] } ) if response.stop_reason == :compaction compaction_block = response.content[0] preserved = messages.length >= 3 ? messages[-3..-1] : messages.dup messages_after_compaction = [ { role: "assistant", content: [compaction_block] } ] + preserved response = client.beta.messages.create( betas: ["compact-2026-01-12"], model: "claude-opus-4-7", max_tokens: 4096, messages: messages_after_compaction, context_management: { edits: [{ type: "compact_20260112" }] } ) messages.clear messages.concat(messages_after_compaction) end messages << { role: "assistant", content: response.content } response.content.find { |block| block.type == :text }&.text || "" end puts chat(client, messages, "Help me build a Python web scraper") puts chat(client, messages, "Add support for JavaScript-rendered pages") puts chat(client, messages, "Now add rate limiting and error handling") ``` ## Current limitations - **Same model for summarization:** The model specified in your request is used for summarization. There is no option to use a different (for example, cheaper) model for the summary. ## Next steps Explore a practical implementation that manages long-running conversations with instant session memory compaction using background threading and prompt caching. Learn about context window sizes and management strategies. Explore other strategies for managing conversation context like tool result clearing and thinking block clearing. --- # Context editing URL: https://platform.claude.com/docs/en/build-with-claude/context-editing # Context editing Automatically manage conversation context as it grows with context editing. --- This feature is eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned. ## Overview For most use cases, [server-side compaction](/docs/en/build-with-claude/compaction) is the primary strategy for managing context in long-running conversations. The strategies on this page are useful for specific scenarios where you need more fine-grained control over what content is cleared. Context editing allows you to selectively clear specific content from conversation history as it grows. Beyond optimizing costs and staying within limits, this is about actively curating what Claude sees: context is a finite resource with diminishing returns, and irrelevant content degrades model focus. Context editing gives you fine-grained runtime control over that curation. For the broader principles behind context management, see [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents). This page covers: - **Tool result clearing** - Best for agentic workflows with heavy tool use where old tool results are no longer needed - **Thinking block clearing** - For managing thinking blocks when using extended thinking, with options to preserve recent thinking for context continuity - **Client-side SDK compaction** - An SDK-based alternative for summary-based context management (server-side compaction is generally preferred) | Approach | Where it runs | Strategies | How it works | |----------|---------------|------------|--------------| | **Server-side** | API | Tool result clearing (`clear_tool_uses_20250919`)
Thinking block clearing (`clear_thinking_20251015`) | Applied before the prompt reaches Claude. Clears specific content from conversation history. Each strategy can be configured independently. | | **Client-side** | SDK | Compaction | Available in [Python, TypeScript, and Ruby SDKs](/docs/en/api/client-sdks) when using [`tool_runner`](/docs/en/agents-and-tools/tool-use/tool-runner). Generates a summary and replaces full conversation history. See [Client-side compaction](#client-side-compaction-sdk) below. | ## Server-side strategies Context editing is in beta with support for tool result clearing and thinking block clearing. To enable it, use the beta header `context-management-2025-06-27` in your API requests. Share feedback on this feature through the [feedback form](https://forms.gle/YXC2EKGMhjN1c4L88). ### Tool result clearing The `clear_tool_uses_20250919` strategy clears tool results when conversation context grows beyond your configured threshold. This is particularly useful for agentic workflows with heavy tool use. Older tool results (like file contents or search results) are no longer needed once Claude has processed them. When activated, the API automatically clears the oldest tool results in chronological order. The API replaces each cleared result with placeholder text so Claude knows it was removed. By default, only tool results are cleared. You can optionally clear both tool results and tool calls (the tool use parameters) by setting `clear_tool_inputs` to true. ### Thinking block clearing The `clear_thinking_20251015` strategy manages `thinking` blocks in conversations when extended thinking is enabled. This strategy gives you control over thinking preservation: you can choose to keep more thinking blocks to maintain reasoning continuity, or clear them more aggressively to save context space. **Default behavior:** The default varies by model class. | Model class | Keep all prior thinking | Keep only the last turn's thinking | | --- | --- | --- | | Opus | Claude Opus 4.5 and later | Claude Opus 4.1 and earlier | | Sonnet | Claude Sonnet 4.6 and later | Claude Sonnet 4.5 and earlier | | Haiku | (none) | All models through Claude Haiku 4.5 | Use this strategy to override the default. If your code runs across multiple model tiers, set `keep` explicitly rather than relying on the per-model default. An assistant conversation turn may include multiple content blocks (e.g. when using tools) and multiple thinking blocks (e.g. with [interleaved thinking](/docs/en/build-with-claude/extended-thinking#interleaved-thinking)). ### Context editing happens server-side Context editing is applied server-side before the prompt reaches Claude. Your client application maintains the full, unmodified conversation history. You do not need to sync your client state with the edited version. Continue managing your full conversation history locally as you normally would. ### Context editing and prompt caching Context editing's interaction with [prompt caching](/docs/en/build-with-claude/prompt-caching) varies by strategy: - **Tool result clearing**: Invalidates cached prompt prefixes when content is cleared. To account for this, clear enough tokens to make the cache invalidation worthwhile. Use the `clear_at_least` parameter to ensure a minimum number of tokens is cleared each time. You'll incur cache write costs each time content is cleared, but subsequent requests can reuse the newly cached prefix. - **Thinking block clearing**: When thinking blocks are **kept** in context (not cleared), the prompt cache is preserved, enabling cache hits and reducing input token costs. When thinking blocks are **cleared**, the cache is invalidated at the point where clearing occurs. Configure the `keep` parameter based on whether you want to prioritize cache performance or context window availability. ## Supported models Context editing is available on all supported Claude models. ## Tool result clearing usage The simplest way to enable tool result clearing is to specify only the strategy type. All other [configuration options](#configuration-options-for-tool-result-clearing) use their default values: ```bash cURL curl https://api.anthropic.com/v1/messages \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --header "anthropic-beta: context-management-2025-06-27" \ --data '{ "model": "claude-opus-4-7", "max_tokens": 4096, "messages": [ { "role": "user", "content": "Search for recent developments in AI" } ], "tools": [ { "type": "web_search_20250305", "name": "web_search" } ], "context_management": { "edits": [ {"type": "clear_tool_uses_20250919"} ] } }' ``` ```bash CLI ant beta:messages create --beta context-management-2025-06-27 <<'YAML' model: claude-opus-4-7 max_tokens: 4096 messages: - role: user content: Search for recent developments in AI tools: - type: web_search_20250305 name: web_search context_management: edits: - type: clear_tool_uses_20250919 YAML ``` ```python Python response = client.beta.messages.create( model="claude-opus-4-7", max_tokens=4096, messages=[{"role": "user", "content": "Search for recent developments in AI"}], tools=[{"type": "web_search_20250305", "name": "web_search"}], betas=["context-management-2025-06-27"], context_management={"edits": [{"type": "clear_tool_uses_20250919"}]}, ) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }); const response = await anthropic.beta.messages.create({ model: "claude-opus-4-7", max_tokens: 4096, messages: [ { role: "user", content: "Search for recent developments in AI" } ], tools: [ { type: "web_search_20250305", name: "web_search" } ], context_management: { edits: [{ type: "clear_tool_uses_20250919" }] }, betas: ["context-management-2025-06-27"] }); ``` ```csharp C# nocheck using Anthropic; using Anthropic.Models.Beta.Messages; AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = "claude-opus-4-7", MaxTokens = 4096, Messages = [ new() { Role = Role.User, Content = "Search for recent developments in AI" } ], Tools = [ new() { Type = "web_search_20250305", Name = "web_search" } ], ContextManagement = new BetaContextManagementConfig() { Edits = [new BetaClearToolUses20250919Edit()] }, Betas = ["context-management-2025-06-27"] }; var response = await client.Beta.Messages.Create(parameters); Console.WriteLine(response); ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeOpus4_7, MaxTokens: 4096, Messages: []anthropic.BetaMessageParam{ anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Search for recent developments in AI")), }, Tools: []anthropic.BetaToolUnionParam{ {OfWebSearchTool20250305: &anthropic.BetaWebSearchTool20250305Param{}}, }, ContextManagement: anthropic.BetaContextManagementConfigParam{ Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ {OfClearToolUses20250919: &anthropic.BetaClearToolUses20250919EditParam{}}, }, }, Betas: []anthropic.AnthropicBeta{ anthropic.AnthropicBetaContextManagement2025_06_27, }, }) if err != nil { log.Fatal(err) } fmt.Println(response) } ``` ```java Java hidelines={1..4,9..12,-2..} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.beta.messages.MessageCreateParams; import com.anthropic.models.beta.messages.BetaMessage; import com.anthropic.models.beta.messages.BetaWebSearchTool20250305; import com.anthropic.models.beta.messages.BetaContextManagementConfig; import com.anthropic.models.beta.messages.BetaClearToolUses20250919Edit; import com.anthropic.models.beta.AnthropicBeta; import com.anthropic.models.messages.Model; public class WebSearchExample { public static void main(String[] args) { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_7) .maxTokens(4096L) .addUserMessage("Search for recent developments in AI") .addTool(BetaWebSearchTool20250305.builder().build()) .contextManagement(BetaContextManagementConfig.builder() .addEdit(BetaClearToolUses20250919Edit.builder().build()) .build()) .addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27) .build(); BetaMessage response = client.beta().messages().create(params); System.out.println(response); } } ``` ```php PHP hidelines={1..4} beta->messages->create( maxTokens: 4096, messages: [ ['role' => 'user', 'content' => 'Search for recent developments in AI'] ], model: 'claude-opus-4-7', betas: ['context-management-2025-06-27'], tools: [ ['type' => 'web_search_20250305', 'name' => 'web_search'] ], contextManagement: [ 'edits' => [ ['type' => 'clear_tool_uses_20250919'] ] ], ); echo $response; ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new response = client.beta.messages.create( model: "claude-opus-4-7", max_tokens: 4096, messages: [ { role: "user", content: "Search for recent developments in AI" } ], tools: [ { type: "web_search_20250305", name: "web_search" } ], context_management: { edits: [ { type: "clear_tool_uses_20250919" } ] }, betas: ["context-management-2025-06-27"] ) puts response ``` ### Advanced configuration You can customize the tool result clearing behavior with additional parameters: ```bash cURL curl https://api.anthropic.com/v1/messages \ --header "x-api-key: $ANTHROPIC_API_KEY" \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --header "anthropic-beta: context-management-2025-06-27" \ --data '{ "model": "claude-opus-4-7", "max_tokens": 4096, "messages": [ { "role": "user", "content": "Create a simple command line calculator app using Python" } ], "tools": [ { "type": "text_editor_20250728", "name": "str_replace_based_edit_tool", "max_characters": 10000 }, { "type": "web_search_20250305", "name": "web_search", "max_uses": 3 } ], "context_management": { "edits": [ { "type": "clear_tool_uses_20250919", "trigger": { "type": "input_tokens", "value": 30000 }, "keep": { "type": "tool_uses", "value": 3 }, "clear_at_least": { "type": "input_tokens", "value": 5000 }, "exclude_tools": ["web_search"] } ] } }' ``` ```bash CLI ant beta:messages create --beta context-management-2025-06-27 <<'YAML' model: claude-opus-4-7 max_tokens: 4096 messages: - role: user content: Create a simple command line calculator app using Python tools: - type: text_editor_20250728 name: str_replace_based_edit_tool max_characters: 10000 - type: web_search_20250305 name: web_search max_uses: 3 context_management: edits: - type: clear_tool_uses_20250919 trigger: type: input_tokens value: 30000 keep: type: tool_uses value: 3 clear_at_least: type: input_tokens value: 5000 exclude_tools: - web_search YAML ``` ```python Python response = client.beta.messages.create( model="claude-opus-4-7", max_tokens=4096, messages=[ { "role": "user", "content": "Create a simple command line calculator app using Python", } ], tools=[ { "type": "text_editor_20250728", "name": "str_replace_based_edit_tool", "max_characters": 10000, }, {"type": "web_search_20250305", "name": "web_search", "max_uses": 3}, ], betas=["context-management-2025-06-27"], context_management={ "edits": [ { "type": "clear_tool_uses_20250919", # Trigger clearing when threshold is exceeded "trigger": {"type": "input_tokens", "value": 30000}, # Number of tool uses to keep after clearing "keep": {"type": "tool_uses", "value": 3}, # Optional: Clear at least this many tokens "clear_at_least": {"type": "input_tokens", "value": 5000}, # Exclude these tools from being cleared "exclude_tools": ["web_search"], } ] }, ) ``` ```typescript TypeScript hidelines={1..2} import Anthropic from "@anthropic-ai/sdk"; const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }); const response = await anthropic.beta.messages.create({ model: "claude-opus-4-7", max_tokens: 4096, messages: [ { role: "user", content: "Create a simple command line calculator app using Python" } ], tools: [ { type: "text_editor_20250728", name: "str_replace_based_edit_tool", max_characters: 10000 }, { type: "web_search_20250305", name: "web_search", max_uses: 3 } ], betas: ["context-management-2025-06-27"], context_management: { edits: [ { type: "clear_tool_uses_20250919", // Trigger clearing when threshold is exceeded trigger: { type: "input_tokens", value: 30000 }, // Number of tool uses to keep after clearing keep: { type: "tool_uses", value: 3 }, // Optional: Clear at least this many tokens clear_at_least: { type: "input_tokens", value: 5000 }, // Exclude these tools from being cleared exclude_tools: ["web_search"] } ] } }); ``` ```csharp C# nocheck using System; using System.Collections.Generic; using System.Threading.Tasks; using Anthropic; using Anthropic.Models.Beta.Messages; class Program { static async Task Main(string[] args) { AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = "claude-opus-4-7", MaxTokens = 4096, Messages = new List { new() { Role = Role.User, Content = "Create a simple command line calculator app using Python" } }, Tools = new List