Claude API — C#

Note: The C# SDK is the official Anthropic SDK for C#. Tool use is supported via the Messages API. A class-annotation-based tool runner is not available; use raw tool definitions with JSON schema. The SDK also supports Microsoft.Extensions.AI IChatClient integration with function invocation.

Installation

dotnet add package Anthropic

Client Initialization

using Anthropic;

// Default (uses ANTHROPIC_API_KEY env var)
AnthropicClient client = new();

// Explicit API key (use environment variables — never hardcode keys)
AnthropicClient client = new() {
    ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};

Basic Message Request

using Anthropic.Models.Messages;

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus4_6,
    MaxTokens = 1024,
    Messages = [new() { Role = Role.User, Content = "What is the capital of France?" }]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);

Streaming

using Anthropic.Models.Messages;

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus4_6,
    MaxTokens = 1024,
    Messages = [new() { Role = Role.User, Content = "Write a haiku" }]
};

await foreach (RawMessageStreamEvent streamEvent in client.Messages.CreateStreaming(parameters))
{
    if (streamEvent.TryPickContentBlockDelta(out var delta) &&
        delta.Delta.TryPickText(out var text))
    {
        Console.Write(text.Text);
    }
}

Tool Use (Manual Loop)

The C# SDK supports raw tool definitions via JSON schema. See the shared tool use concepts for the tool definition format and agentic loop pattern.

Claude API — cURL / Raw HTTP

Use these examples when the user needs raw HTTP requests or is working in a language without an official SDK.

Setup

export ANTHROPIC_API_KEY="your-api-key"

Basic Message Request

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-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'

Streaming (SSE)

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-6",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "Write a haiku"}]
  }'

The response is a stream of Server-Sent Events:

event: message_start
data: {"type":"message_start","message":{"id":"msg_...","type":"message",...}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}}

event: message_stop
data: {"type":"message_stop"}

Tool Use

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-6",
    "max_tokens": 1024,
    "tools": [{
      "name": "get_weather",
      "description": "Get current weather for a location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {"type": "string", "description": "City name"}
        },
        "required": ["location"]
      }
    }],
    "messages": [{"role": "user", "content": "What is the weather in Paris?"}]
  }'

When Claude responds with a tool_use block, send the result back:

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-6",
    "max_tokens": 1024,
    "tools": [{
      "name": "get_weather",
      "description": "Get current weather for a location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {"type": "string", "description": "City name"}
        },
        "required": ["location"]
      }
    }],
    "messages": [
      {"role": "user", "content": "What is the weather in Paris?"},
      {"role": "assistant", "content": [
        {"type": "text", "text": "Let me check the weather."},
        {"type": "tool_use", "id": "toolu_abc123", "name": "get_weather", "input": {"location": "Paris"}}
      ]},
      {"role": "user", "content": [
        {"type": "tool_result", "tool_use_id": "toolu_abc123", "content": "72°F and sunny"}
      ]}
    ]
  }'

Extended Thinking

Opus 4.6 and Sonnet 4.6: Use adaptive thinking. budget_tokens is deprecated on both Opus 4.6 and Sonnet 4.6. Older models: Use "type": "enabled" with "budget_tokens": N (must be < max_tokens, min 1024).

# Opus 4.6: adaptive thinking (recommended)
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-6",
    "max_tokens": 16000,
    "thinking": {
      "type": "adaptive"
    },
    "output_config": {
      "effort": "high"
    },
    "messages": [{"role": "user", "content": "Solve this step by step..."}]
  }'

Required Headers

Claude API — Go

Note: The Go SDK supports the Claude API and beta tool use with BetaToolRunner. Agent SDK is not yet available for Go.

Installation

go get github.com/anthropics/anthropic-sdk-go

Client Initialization

import (
    "github.com/anthropics/anthropic-sdk-go"
    "github.com/anthropics/anthropic-sdk-go/option"
)

// Default (uses ANTHROPIC_API_KEY env var)
client := anthropic.NewClient()

// Explicit API key
client := anthropic.NewClient(
    option.WithAPIKey("your-api-key"),
)

Basic Message Request

response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
    Model:     anthropic.ModelClaudeOpus4_6,
    MaxTokens: 1024,
    Messages: []anthropic.MessageParam{
        anthropic.NewUserMessage(anthropic.NewTextBlock("What is the capital of France?")),
    },
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(response.Content[0].Text)

Streaming

stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{
    Model:     anthropic.ModelClaudeOpus4_6,
    MaxTokens: 1024,
    Messages: []anthropic.MessageParam{
        anthropic.NewUserMessage(anthropic.NewTextBlock("Write a haiku")),
    },
})

for stream.Next() {
    event := stream.Current()
    switch eventVariant := event.AsAny().(type) {
    case anthropic.ContentBlockDeltaEvent:
        switch deltaVariant := eventVariant.Delta.AsAny().(type) {
        case anthropic.TextDelta:
            fmt.Print(deltaVariant.Text)
        }
    }
}
if err := stream.Err(); err != nil {
    log.Fatal(err)
}

Tool Use

Tool Runner (Beta — Recommended)

Beta: The Go SDK provides BetaToolRunner for automatic tool use loops via the toolrunner package.

import (
    "context"
    "fmt"
    "log"

    "github.com/anthropics/anthropic-sdk-go"
    "github.com/anthropics/anthropic-sdk-go/toolrunner"
)

// Define tool input with jsonschema tags for automatic schema generation
type GetWeatherInput struct {
    City string `json:"city" jsonschema:"required,description=The city name"`
}

// Create a tool with automatic schema generation from struct tags
weatherTool, err := toolrunner.NewBetaToolFromJSONSchema(
    "get_weather",
    "Get current weather for a city",
    func(ctx context.Context, input GetWeatherInput) (anthropic.BetaToolResultBlockParamContentUnion, error) {
        return anthropic.BetaToolResultBlockParamContentUnion{
            OfText: &anthropic.BetaTextBlockParam{
                Text: fmt.Sprintf("The weather in %s is sunny, 72°F", input.City),
            },
        }, nil
    },
)
if err != nil {
    log.Fatal(err)
}

// Create a tool runner that handles the conversation loop automatically
runner := client.Beta.Messages.NewToolRunner(
    []anthropic.BetaTool{weatherTool},
    anthropic.BetaToolRunnerParams{
        BetaMessageNewParams: anthropic.BetaMessageNewParams{
            Model:     anthropic.ModelClaudeOpus4_6,
            MaxTokens: 1024,
            Messages: []anthropic.BetaMessageParam{
                anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What's the weather in Paris?")),
            },
        },
        MaxIterations: 5,
    },
)

// Run until Claude produces a final response
message, err := runner.RunToCompletion(context.Background())
if err != nil {
    log.Fatal(err)
}
fmt.Println(message.Content[0].Text)

Key features of the Go tool runner:

• Automatic schema generation from Go structs via jsonschema tags
• RunToCompletion() for simple one-shot usage
• All() iterator for processing each message in the conversation
• NextMessage() for step-by-step iteration
• Streaming variant via NewToolRunnerStreaming() with AllStreaming()

Manual Loop

For fine-grained control, use raw tool definitions via JSON schema. See the shared tool use concepts for the tool definition format and agentic loop pattern.

Claude API — Java

Note: The Java SDK supports the Claude API and beta tool use with annotated classes. Agent SDK is not yet available for Java.

Installation

Maven:

<dependency>
    <groupId>com.anthropic</groupId>
    <artifactId>anthropic-java</artifactId>
    <version>2.15.0</version>
</dependency>

Gradle:

implementation("com.anthropic:anthropic-java:2.15.0")

Client Initialization

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;

// Default (reads ANTHROPIC_API_KEY from environment)
AnthropicClient client = AnthropicOkHttpClient.fromEnv();

// Explicit API key
AnthropicClient client = AnthropicOkHttpClient.builder()
    .apiKey("your-api-key")
    .build();

Basic Message Request

import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.Model;

MessageCreateParams params = MessageCreateParams.builder()
    .model(Model.CLAUDE_OPUS_4_6)
    .maxTokens(1024L)
    .addUserMessage("What is the capital of France?")
    .build();

Message response = client.messages().create(params);
response.content().stream()
    .flatMap(block -> block.text().stream())
    .forEach(textBlock -> System.out.println(textBlock.text()));

Streaming

import com.anthropic.core.http.StreamResponse;
import com.anthropic.models.messages.RawMessageStreamEvent;

MessageCreateParams params = MessageCreateParams.builder()
    .model(Model.CLAUDE_OPUS_4_6)
    .maxTokens(1024L)
    .addUserMessage("Write a haiku")
    .build();

try (StreamResponse<RawMessageStreamEvent> streamResponse = client.messages().createStreaming(params)) {
    streamResponse.stream()
        .flatMap(event -> event.contentBlockDelta().stream())
        .flatMap(deltaEvent -> deltaEvent.delta().text().stream())
        .forEach(textDelta -> System.out.print(textDelta.text()));
}

Tool Use (Beta)

The Java SDK supports beta tool use with annotated classes. Tool classes implement Supplier<String> for automatic execution via BetaToolRunner.

Tool Runner (automatic loop)

import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.helpers.BetaToolRunner;
import com.fasterxml.jackson.annotation.JsonClassDescription;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;
import java.util.function.Supplier;

@JsonClassDescription("Get the weather in a given location")
static class GetWeather implements Supplier<String> {
    @JsonPropertyDescription("The city and state, e.g. San Francisco, CA")
    public String location;

    @Override
    public String get() {
        return "The weather in " + location + " is sunny and 72°F";
    }
}

BetaToolRunner toolRunner = client.beta().messages().toolRunner(
    MessageCreateParams.builder()
        .model("claude-opus-4-6")
        .maxTokens(1024L)
        .putAdditionalHeader("anthropic-beta", "structured-outputs-2025-11-13")
        .addTool(GetWeather.class)
        .addUserMessage("What's the weather in San Francisco?")
        .build());

for (BetaMessage message : toolRunner) {
    System.out.println(message);
}

Non-Beta Tool Use

Tool use is also available through the non-beta com.anthropic.models.messages.MessageCreateParams with addTool(Tool) for manually defined JSON schemas, without needing the beta namespace. The beta namespace is only needed for the class-annotation convenience layer (@JsonClassDescription, BetaToolRunner).

Manual Loop

For manual tool loops, define tools as JSON schema in the request, handle tool_use blocks in the response, send tool_result back, and loop until stop_reason is "end_turn". See the shared tool use concepts for the agentic loop pattern.

Claude API — PHP

Note: The PHP SDK is the official Anthropic SDK for PHP. Tool runner and Agent SDK are not available. Bedrock, Vertex AI, and Foundry clients are supported.

Installation

composer require "anthropic-ai/sdk"

Client Initialization

use Anthropic\Client;

// Using API key from environment variable
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));

Amazon Bedrock

use Anthropic\BedrockClient;

$client = new BedrockClient(
    region: 'us-east-1',
);

Google Vertex AI

use Anthropic\VertexClient;

$client = new VertexClient(
    region: 'us-east5',
    projectId: 'my-project-id',
);

Anthropic Foundry

use Anthropic\FoundryClient;

$client = new FoundryClient(
    authToken: getenv("ANTHROPIC_AUTH_TOKEN"),
);

Basic Message Request

$message = $client->messages->create(
    model: 'claude-opus-4-6',
    maxTokens: 1024,
    messages: [
        ['role' => 'user', 'content' => 'What is the capital of France?'],
    ],
);
echo $message->content[0]->text;

Streaming

$stream = $client->messages->createStream(
    model: 'claude-opus-4-6',
    maxTokens: 1024,
    messages: [
        ['role' => 'user', 'content' => 'Write a haiku'],
    ],
);

foreach ($stream as $event) {
    echo $event;
}

Tool Use (Manual Loop)

The PHP SDK supports raw tool definitions via JSON schema. See the shared tool use concepts for the tool definition format and agentic loop pattern.

Claude API — Ruby

Note: The Ruby SDK supports the Claude API. A tool runner is available in beta via client.beta.messages.tool_runner(). Agent SDK is not yet available for Ruby.

Installation

gem install anthropic

Client Initialization

require "anthropic"

# Default (uses ANTHROPIC_API_KEY env var)
client = Anthropic::Client.new

# Explicit API key
client = Anthropic::Client.new(api_key: "your-api-key")

Basic Message Request

message = client.messages.create(
  model: :"claude-opus-4-6",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "What is the capital of France?" }
  ]
)
puts message.content.first.text

Streaming

stream = client.messages.stream(
  model: :"claude-opus-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Write a haiku" }]
)

stream.text.each { |text| print(text) }

Tool Use

The Ruby SDK supports tool use via raw JSON schema definitions and also provides a beta tool runner for automatic tool execution.

Tool Runner (Beta)

class GetWeatherInput < Anthropic::BaseModel
  required :location, String, doc: "City and state, e.g. San Francisco, CA"
end

class GetWeather < Anthropic::BaseTool
  doc "Get the current weather for a location"

  input_schema GetWeatherInput

  def call(input)
    "The weather in #{input.location} is sunny and 72°F."
  end
end

client.beta.messages.tool_runner(
  model: :"claude-opus-4-6",
  max_tokens: 1024,
  tools: [GetWeather.new],
  messages: [{ role: "user", content: "What's the weather in San Francisco?" }]
).each_message do |message|
  puts message.content
end

Manual Loop

See the shared tool use concepts for the tool definition format and agentic loop pattern.

HTTP Error Codes Reference

This file documents HTTP error codes returned by the Claude API, their common causes, and how to handle them. For language-specific error handling examples, see the python/ or typescript/ folders.

Error Code Summary

Detailed Error Information

400 Bad Request

Causes:

• Malformed JSON in request body
• Missing required parameters (model, max_tokens, messages)
• Invalid parameter types (e.g., string where integer expected)
• Empty messages array
• Messages not alternating user/assistant

Example error:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "messages: roles must alternate between \"user\" and \"assistant\""
  }
}

Fix: Validate request structure before sending. Check that:

• model is a valid model ID
• max_tokens is a positive integer
• messages array is non-empty and alternates correctly

401 Unauthorized

Causes:

• Missing x-api-key header or Authorization header
• Invalid API key format
• Revoked or deleted API key

Fix: Ensure ANTHROPIC_API_KEY environment variable is set correctly.

403 Forbidden

Causes:

• API key doesn't have access to the requested model
• Organization-level restrictions
• Attempting to access beta features without beta access

Fix: Check your API key permissions in the Console. You may need a different API key or to request access to specific features.

404 Not Found

Causes:

• Typo in model ID (e.g., claude-sonnet-4.6 instead of claude-sonnet-4-6)
• Using deprecated model ID
• Invalid API endpoint

Fix: Use exact model IDs from the models documentation. You can use aliases (e.g., claude-opus-4-6).

413 Request Too Large

Causes:

• Request body exceeds maximum size
• Too many tokens in input
• Image data too large

Fix: Reduce input size — truncate conversation history, compress/resize images, or split large documents into chunks.

400 Validation Errors

Some 400 errors are specifically related to parameter validation:

• max_tokens exceeds model's limit
• Invalid temperature value (must be 0.0-1.0)
• budget_tokens >= max_tokens in extended thinking
• Invalid tool definition schema

Common mistake with extended thinking:

# Wrong: budget_tokens must be < max_tokens
thinking: budget_tokens=10000, max_tokens=1000  → Error!

# Correct
thinking: budget_tokens=10000, max_tokens=16000

429 Rate Limited

Causes:

• Exceeded requests per minute (RPM)
• Exceeded tokens per minute (TPM)
• Exceeded tokens per day (TPD)

Headers to check:

• retry-after: Seconds to wait before retrying
• x-ratelimit-limit-*: Your limits
• x-ratelimit-remaining-*: Remaining quota

Fix: The Anthropic SDKs automatically retry 429 and 5xx errors with exponential backoff (default: max_retries=2). For custom retry behavior, see the language-specific error handling examples.

500 Internal Server Error

Causes:

• Temporary Anthropic service issue
• Bug in API processing

Fix: Retry with exponential backoff. If persistent, check status.anthropic.com.

529 Overloaded

Causes:

• High API demand
• Service capacity reached

Fix: Retry with exponential backoff. Consider using a different model (Haiku is often less loaded), spreading requests over time, or implementing request queuing.

Common Mistakes and Fixes

Typed Exceptions in SDKs

Always use the SDK's typed exception classes instead of checking error messages with string matching. Each HTTP error code maps to a specific exception class:

// ✅ Correct: use typed exceptions
try {
  const response = await client.messages.create({...});
} catch (error) {
  if (error instanceof Anthropic.RateLimitError) {
    // Handle rate limiting
  } else if (error instanceof Anthropic.APIError) {
    console.error(`API error ${error.status}:`, error.message);
  }
}

// ❌ Wrong: don't check error messages with string matching
try {
  const response = await client.messages.create({...});
} catch (error) {
  const msg = error instanceof Error ? error.message : String(error);
  if (msg.includes("429") || msg.includes("rate_limit")) { ... }
}

All exception classes extend Anthropic.APIError, which has a status property. Use instanceof checks from most specific to least specific (e.g., check RateLimitError before APIError).

Live Documentation Sources

This file contains WebFetch URLs for fetching current information from platform.claude.com and Agent SDK repositories. Use these when users need the latest data that may have changed since the cached content was last updated.

When to Use WebFetch

• User explicitly asks for "latest" or "current" information
• Cached data seems incorrect
• User asks about features not covered in cached content
• User needs specific API details or examples

Claude API Documentation URLs

Models & Pricing

Core Features

Media & Files

API Operations

Tools

Advanced Features

Claude API SDK Repositories

Agent SDK Documentation URLs

Core Documentation

SDK Reference (GitHub READMEs)

npm/PyPI Packages

GitHub Repositories

Fallback Strategy

If WebFetch fails (network issues, URL changed):

1. Use cached content from the language-specific files (note the cache date)
2. Inform user the data may be outdated
3. Suggest they check platform.claude.com or the GitHub repos directly

Claude Model Catalog

Only use exact model IDs listed in this file. Never guess or construct model IDs — incorrect IDs will cause API errors. Use aliases wherever available. For the latest information, WebFetch the Models Overview URL in shared/live-sources.md.

Current Models (recommended)

Model Descriptions

• Claude Opus 4.6 — Our most intelligent model for building agents and coding. Supports adaptive thinking (recommended), 128K max output tokens (requires streaming for large outputs). 1M context window available in beta via context-1m-2025-08-07 header.
• Claude Sonnet 4.6 — Our best combination of speed and intelligence. Supports adaptive thinking (recommended). 1M context window available in beta via context-1m-2025-08-07 header. 64K max output tokens.
• Claude Haiku 4.5 — Fastest and most cost-effective model for simple tasks.

Legacy Models (still active)

Deprecated Models (retiring soon)

Retired Models (no longer available)

Resolving User Requests

When a user asks for a model by name, use this table to find the correct model ID:

Tool Use Concepts

This file covers the conceptual foundations of tool use with the Claude API. For language-specific code examples, see the python/, typescript/, or other language folders.

User-Defined Tools

Tool Definition Structure

Note: When using the Tool Runner (beta), tool schemas are generated automatically from your function signatures (Python), Zod schemas (TypeScript), annotated classes (Java), jsonschema struct tags (Go), or BaseTool subclasses (Ruby). The raw JSON schema format below is for the manual approach or SDKs without tool runner support.

Each tool requires a name, description, and JSON Schema for its inputs:

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City and state, e.g., San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Temperature unit"
      }
    },
    "required": ["location"]
  }
}

Best practices for tool definitions:

• Use clear, descriptive names (e.g., get_weather, search_database, send_email)
• Write detailed descriptions — Claude uses these to decide when to use the tool
• Include descriptions for each property
• Use enum for parameters with a fixed set of values
• Mark truly required parameters in required; make others optional with defaults

Tool Choice Options

Control when Claude uses tools:

Any tool_choice value can also include "disable_parallel_tool_use": true to force Claude to use at most one tool per response. By default, Claude may request multiple tool calls in a single response.

Tool Runner vs Manual Loop

Tool Runner (Recommended): The SDK's tool runner handles the agentic loop automatically — it calls the API, detects tool use requests, executes your tool functions, feeds results back to Claude, and repeats until Claude stops calling tools. Available in Python, TypeScript, Java, Go, and Ruby SDKs (beta). The Python SDK also provides MCP conversion helpers (anthropic.lib.tools.mcp) to convert MCP tools, prompts, and resources for use with the tool runner — see python/claude-api/tool-use.md for details.

Manual Agentic Loop: Use when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval). Loop until stop_reason == "end_turn", always append the full response.content to preserve tool_use blocks, and ensure each tool_result includes the matching tool_use_id.

Stop reasons for server-side tools: When using server-side tools (code execution, web search, etc.), the API runs a server-side sampling loop. If this loop reaches its default limit of 10 iterations, the response will have stop_reason: "pause_turn". To continue, re-send the user message and assistant response and make another API request — the server will resume where it left off. Do NOT add an extra user message like "Continue." — the API detects the trailing server_tool_use block and knows to resume automatically.

# Handle pause_turn in your agentic loop
if response.stop_reason == "pause_turn":
    messages = [
        {"role": "user", "content": user_query},
        {"role": "assistant", "content": response.content},
    ]
    # Make another API request — server resumes automatically
    response = client.messages.create(
        model="claude-opus-4-6", messages=messages, tools=tools
    )

Set a max_continuations limit (e.g., 5) to prevent infinite loops. For the full guide, see: https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons

Security: The tool runner executes your tool functions automatically whenever Claude requests them. For tools with side effects (sending emails, modifying databases, financial transactions), validate inputs within your tool functions and consider requiring confirmation for destructive operations. Use the manual agentic loop if you need human-in-the-loop approval before each tool execution.

Handling Tool Results

When Claude uses a tool, the response contains a tool_use block. You must:

1. Execute the tool with the provided input
2. Send the result back in a tool_result message
3. Continue the conversation

Error handling in tool results: When a tool execution fails, set "is_error": true and provide an informative error message. Claude will typically acknowledge the error and either try a different approach or ask for clarification.

Multiple tool calls: Claude can request multiple tools in a single response. Handle them all before continuing — send all results back in a single user message.

Server-Side Tools: Code Execution

The code execution tool lets Claude run code in a secure, sandboxed container. Unlike user-defined tools, server-side tools run on Anthropic's infrastructure — you don't execute anything client-side. Just include the tool definition and Claude handles the rest.

Key Facts

• Runs in an isolated container (1 CPU, 5 GiB RAM, 5 GiB disk)
• No internet access (fully sandboxed)
• Python 3.11 with data science libraries pre-installed
• Containers persist for 30 days and can be reused across requests
• Free when used with web search/web fetch tools; otherwise $0.05/hour after 1,550 free hours/month per organization

Tool Definition

The tool requires no schema — just declare it in the tools array:

{
  "type": "code_execution_20260120",
  "name": "code_execution"
}

Claude automatically gains access to bash_code_execution (run shell commands) and text_editor_code_execution (create/view/edit files).

Pre-installed Python Libraries

• Data science: pandas, numpy, scipy, scikit-learn, statsmodels
• Visualization: matplotlib, seaborn
• File processing: openpyxl, xlsxwriter, pillow, pypdf, pdfplumber, python-docx, python-pptx
• Math: sympy, mpmath
• Utilities: tqdm, python-dateutil, pytz, sqlite3

Additional packages can be installed at runtime via pip install.

Supported File Types for Upload

Container Reuse

Reuse containers across requests to maintain state (files, installed packages, variables). Extract the container_id from the first response and pass it to subsequent requests.

Response Structure

The response contains interleaved text and tool result blocks:

• text — Claude's explanation
• server_tool_use — What Claude is doing
• bash_code_execution_tool_result — Code execution output (check return_code for success/failure)
• text_editor_code_execution_tool_result — File operation results

Security: Always sanitize filenames with os.path.basename() / path.basename() before writing downloaded files to disk to prevent path traversal attacks. Write files to a dedicated output directory.

Server-Side Tools: Web Search and Web Fetch

Web search and web fetch let Claude search the web and retrieve page content. They run server-side — just include the tool definitions and Claude handles queries, fetching, and result processing automatically.

Tool Definitions

[
  { "type": "web_search_20260209", "name": "web_search" },
  { "type": "web_fetch_20260209", "name": "web_fetch" }
]

Dynamic Filtering (Opus 4.6 / Sonnet 4.6)

The web_search_20260209 and web_fetch_20260209 versions support dynamic filtering — Claude writes and executes code to filter search results before they reach the context window, improving accuracy and token efficiency. Dynamic filtering is built into these tool versions and activates automatically; you do not need to separately declare the code_execution tool or pass any beta header.

{
  "tools": [
    { "type": "web_search_20260209", "name": "web_search" },
    { "type": "web_fetch_20260209", "name": "web_fetch" }
  ]
}

Without dynamic filtering, the previous web_search_20250305 version is also available.

Note: Only include the standalone code_execution tool when your application needs code execution for its own purposes (data analysis, file processing, visualization) independent of web search. Including it alongside _20260209 web tools creates a second execution environment that can confuse the model.

Server-Side Tools: Programmatic Tool Calling

Programmatic tool calling lets Claude execute complex multi-tool workflows in code, keeping intermediate results out of the context window. Claude writes code that calls your tools directly, reducing token usage for multi-step operations.

For full documentation, use WebFetch:

• URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling

Server-Side Tools: Tool Search

The tool search tool lets Claude dynamically discover tools from large libraries without loading all definitions into the context window. Useful when you have many tools but only a few are relevant to any given query.

For full documentation, use WebFetch:

• URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool

Tool Use Examples

You can provide sample tool calls directly in your tool definitions to demonstrate usage patterns and reduce parameter errors. This helps Claude understand how to correctly format tool inputs, especially for tools with complex schemas.

For full documentation, use WebFetch:

• URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use

Server-Side Tools: Computer Use

Computer use lets Claude interact with a desktop environment (screenshots, mouse, keyboard). It can be Anthropic-hosted (server-side, like code execution) or self-hosted (you provide the environment and execute actions client-side).

For full documentation, use WebFetch:

• URL: https://platform.claude.com/docs/en/agents-and-tools/computer-use/overview

Client-Side Tools: Memory

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.

Key Facts

• Client-side tool — you control storage via your implementation
• Supports commands: view, create, str_replace, insert, delete, rename
• Operates on files in a /memories directory
• The SDKs provide helper classes/functions for implementing the memory backend

Security: Never store API keys, passwords, tokens, or other secrets in memory files. Be cautious with personally identifiable information (PII) — check data privacy regulations (GDPR, CCPA) before persisting user data. The reference implementations have no built-in access control; in multi-user systems, implement per-user memory directories and authentication in your tool handlers.

For full implementation examples, use WebFetch:

• Docs: https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md

Structured Outputs

Structured outputs constrain Claude's responses to follow a specific JSON schema, guaranteeing valid, parseable output. This is not a separate tool — it enhances the Messages API response format and/or tool parameter validation.

Two features are available:

• JSON outputs (output_config.format): Control Claude's response format
• Strict tool use (strict: true): Guarantee valid tool parameter schemas

Supported models: Claude Opus 4.6, Claude Sonnet 4.6, and Claude Haiku 4.5. Legacy models (Claude Opus 4.5, Claude Opus 4.1) also support structured outputs.

Recommended: Use client.messages.parse() which automatically validates responses against your schema. When using messages.create() directly, use output_config: {format: {...}}. The output_format convenience parameter is also accepted by some SDK methods (e.g., .parse()), but output_config.format is the canonical API-level parameter.

JSON Schema Limitations

Supported:

• Basic types: object, array, string, integer, number, boolean, null
• enum, const, anyOf, allOf, $ref/$def
• String formats: date-time, time, date, duration, email, hostname, uri, ipv4, ipv6, uuid
• additionalProperties: false (required for all objects)

Not supported:

• Recursive schemas
• Numerical constraints (minimum, maximum, multipleOf)
• String constraints (minLength, maxLength)
• Complex array constraints
• additionalProperties set to anything other than false

The Python and TypeScript SDKs automatically handle unsupported constraints by removing them from the schema sent to the API and validating them client-side.

Important Notes

• First request latency: New schemas incur a one-time compilation cost. Subsequent requests with the same schema use a 24-hour cache.
• Refusals: If Claude refuses for safety reasons (stop_reason: "refusal"), the output may not match your schema.
• Token limits: If stop_reason: "max_tokens", output may be incomplete. Increase max_tokens.
• Incompatible with: Citations (returns 400 error), message prefilling.
• Works with: Batches API, streaming, token counting, extended thinking.

Tips for Effective Tool Use

1. Provide detailed descriptions: Claude relies heavily on descriptions to understand when and how to use tools
2. Use specific tool names: get_current_weather is better than weather
3. Validate inputs: Always validate tool inputs before execution
4. Handle errors gracefully: Return informative error messages so Claude can adapt
5. Limit tool count: Too many tools can confuse the model — keep the set focused
6. Test tool interactions: Verify Claude uses tools correctly in various scenarios

For detailed tool use documentation, use WebFetch:

• URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview