llms.txt@04-API-Reference · git:20260521.1b74b3e · 2026-05-21 · sha256 842d6386a7c8d72d
llms.txt@04-API-Reference git:20260521.1b74b3eB
Immutable. This exact content never changes and is served at /api/v1/blob/842d6386a7c8d72d.
# API Reference
All documentation for API Reference.
---
## About/about-claude-glossary-1405208f57.md
# Glossary
These concepts are not unique to Anthropic’s language models, but we present a brief summary of key terms below.
---
## Context window
The "context window" refers to the amount of text a language model can look back on and reference when generating new text. This is different from the large corpus of data the language model was trained on, and instead represents a "working memory" for the model. A larger context window allows the model to understand and respond to more complex and lengthy prompts, while a smaller context window may limit the model's ability to handle longer prompts or maintain coherence over extended conversations.
See our [guide to understanding context windows](/docs/en/build-with-claude/context-windows) to learn more.
## Fine-tuning
Fine-tuning is the process of further training a pretrained language model using additional data. This causes the model to start representing and mimicking the patterns and characteristics of the fine-tuning dataset. Claude is not a bare language model; it has already been fine-tuned to be a helpful assistant. Our API does not currently offer fine-tuning, but please ask your Anthropic contact if you are interested in exploring this option. Fine-tuning can be useful for adapting a language model to a specific domain, task, or writing style, but it requires careful consideration of the fine-tuning data and the potential impact on the model's performance and biases.
## HHH
These three H's represent Anthropic's goals in ensuring that Claude is beneficial to society:
- A **helpful** AI will attempt to perform the task or answer the question posed to the best of its abilities, providing relevant and useful information.
- An **honest** AI will give accurate information, and not hallucinate or confabulate. It will acknowledge its limitations and uncertainties when appropriate.
- A **harmless** AI will not be offensive or discriminatory, and when asked to aid in a dangerous or unethical act, the AI should politely refuse and explain why it cannot comply.
## Latency
Latency, in the context of generative AI and large language models, refers to the time it takes for the model to respond to a given prompt. It is the delay between submitting a prompt and receiving the generated output. Lower latency indicates faster response times, which is crucial for real-time applications, chatbots, and interactive experiences. Factors that can affect latency include model size, hardware capabilities, network conditions, and the complexity of the prompt and the generated response.
## LLM
Large language models (LLMs) are AI language models with many parameters that are capable of performing a variety of surprisingly useful tasks. These models are trained on vast amounts of text data and can generate human-like text, answer questions, summarize information, and more. Claude is a conversational assistant based on a large language model that has been fine-tuned and trained using RLHF to be more helpful, honest, and harmless.
## MCP (Model Context Protocol)
Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. Like a USB-C port for AI applications, MCP provides a unified way to connect AI models to different data sources and tools. MCP enables AI systems to maintain consistent context across interactions and access external resources in a standardized manner. See our [MCP documentation](/docs/en/mcp) to learn more.
## MCP connector
The MCP connector is a feature that allows API users to connect to MCP servers directly from the Messages API without building an MCP client. This enables seamless integration with MCP-compatible tools and services through the Claude API. The MCP connector supports features like tool calling and is available in beta. See the [MCP connector documentation](/docs/en/agents-and-tools/mcp-connector) to learn more.
## Pretraining
Pretraining is the initial process of training language models on a large unlabeled corpus of text. In Claude's case, autoregressive language models (like Claude's underlying model) are pretrained to predict the next word, given the previous context of text in the document. These pretrained models are not inherently good at answering questions or following instructions, and often require deep skill in prompt engineering to elicit desired behaviors. Fine-tuning and RLHF are used to refine these pretrained models, making them more useful for a wide range of tasks.
## RAG (Retrieval augmented generation)
Retrieval augmented generation (RAG) is a technique that combines information retrieval with language model generation to improve the accuracy and relevance of the generated text, and to better ground the model's response in evidence. In RAG, a language model is augmented with an external knowledge base or a set of documents that is passed into the context window. The data is retrieved at run time when a query is sent to the model, although the model itself does not necessarily retrieve the data (but can with [tool use](/docs/en/agents-and-tools/tool-use/overview) and a retrieval function). When generating text, relevant information first must be retrieved from the knowledge base based on the input prompt, and then passed to the model along with the original query. The model uses this information to guide the output it generates. This allows the model to access and utilize information beyond its training data, reducing the reliance on memorization and improving the factual accuracy of the generated text. RAG can be particularly useful for tasks that require up-to-date information, domain-specific knowledge, or explicit citation of sources. However, the effectiveness of RAG depends on the quality and relevance of the external knowledge base and the knowledge that is retrieved at runtime.
## RLHF
Reinforcement Learning from Human Feedback (RLHF) is a technique used to train a pretrained language model to behave in ways that are consistent with human preferences. This can include helping the model follow instructions more effectively or act more like a chatbot. Human feedback consists of ranking a set of two or more example texts, and the reinforcement learning process encourages the model to prefer outputs that are similar to the higher-ranked ones. Claude has been trained using RLHF to be a more helpful assistant. For more details, you can read [Anthropic's paper on the subject](https://arxiv.org/abs/2204.05862).
## Temperature
Temperature is a parameter that controls the randomness of a model's predictions during text generation. Higher temperatures lead to more creative and diverse outputs, allowing for multiple variations in phrasing and, in the case of fiction, variation in answers as well. Lower temperatures result in more conservative and deterministic outputs that stick to the most probable phrasing and answers. Adjusting the temperature enables users to encourage a language model to explore rare, uncommon, or surprising word choices and sequences, rather than only selecting the most likely predictions.
Users may encounter non-determinism in APIs. Even with temperature set to 0, the results will not be fully deterministic and identical inputs may produce different outputs across API calls. This applies both to Anthropic's first-party inference service and to inference through third-party cloud providers.
## TTFT (Time to first token)
Time to First Token (TTFT) is a performance metric that measures the time it takes for a language model to generate the first token of its output after receiving a prompt. It is an important indicator of the model's responsiveness and is particularly relevant for interactive applications, chatbots, and real-time systems where users expect quick initial feedback. A lower TTFT indicates that the model can start generating a response faster, providing a more seamless and engaging user experience. Factors that can influence TTFT include model size, hardware capabilities, network conditions, and the complexity of the prompt.
## Tokens
Tokens are the smallest individual units of a language model, and can correspond to words, subwords, characters, or even bytes (in the case of Unicode). For Claude, a token approximately represents 3.5 English characters, though the exact number can vary depending on the language used. Tokens are typically hidden when interacting with language models at the "text" level but become relevant when examining the exact inputs and outputs of a language model. When Claude is provided with text to evaluate, the text (consisting of a series of characters) is encoded into a series of tokens for the model to process. Larger tokens enable data efficiency during inference and pretraining (and are utilized when possible), while smaller tokens allow a model to handle uncommon or never-before-seen words. The choice of tokenization method can impact the model's performance, vocabulary size, and ability to handle out-of-vocabulary words.
---
## About/about-claude-model-deprecations-51979b6538.md
# Model deprecations
---
As safer and more capable models launch, Anthropic regularly retires older ones. Applications relying on Anthropic models may need occasional updates to keep working. Impacted customers will always be notified by email and in the documentation.
This page lists all API deprecations, along with recommended replacements.
## Overview
Anthropic uses the following terms to describe the model lifecycle:
- **Active**: The model is fully supported and recommended for use.
- **Legacy**: The model will no longer receive updates and may be deprecated in the future.
- **Deprecated**: The model is still functional but no longer recommended. Anthropic provides a recommended replacement and assigns a retirement date.
- **Retired**: The model is no longer available for use. Requests to retired models will fail.
<Warning>
Deprecated models are likely to be less reliable than active models. Move workloads to active models to maintain the highest level of support and reliability.
</Warning>
## Migrating to replacements
Once a model is deprecated, migrate all usage to a suitable replacement before the retirement date. Requests to models past the retirement date will fail.
To help measure the performance of replacement models on your tasks, consider thorough testing of your applications with the new models well before the retirement date.
For specific instructions on migrating to the latest Claude models, see the [Migration guide](/docs/en/about-claude/models/migration-guide).
## Notifications
Anthropic notifies customers with active deployments for models with upcoming retirements, providing at least 60 days notice before model retirement for publicly released models.
## Auditing model usage
To help identify usage of deprecated models, customers can access an audit of their API usage. Follow these steps:
1. Go to the [Usage](/usage) page in Console
2. Click the "Export" button
3. Review the downloaded CSV to see usage broken down by API key and model
This audit will help you locate any instances where your application is still using deprecated models, allowing you to prioritize updates to newer models before the retirement date.
## Best practices
1. Regularly check the documentation for updates on model deprecations.
2. Test your applications with newer models well before the retirement date of your current model.
3. Update your code to use the recommended replacement model as soon as possible.
4. Contact the support team if you need assistance with migration or have any questions.
## Deprecation downsides and mitigations
Anthropic currently deprecates and retires models to ensure capacity for new model releases. This comes with downsides:
- Users who value specific models must migrate to new versions
- Researchers lose access to models for ongoing and comparative studies
- Model retirement introduces safety- and model welfare-related risks
At some point, Anthropic hopes to make past models publicly available again. In the meantime, Anthropic has committed to long-term preservation of model weights and other measures to help mitigate these impacts. For more details, see [Commitments on Model Deprecation and Preservation](../../19-Reference/commitments-on-model-deprecation-and-preservation-anthropic.md).
## Model status
All publicly released models are listed below with their status:
| API Model Name | Current State | Deprecated | Tentative Retirement Date |
|:----------------------------|:--------------------|:------------------|:-------------------------|
| `claude-opus-4-7` | Active | N/A | Not sooner than April 16, 2027 |
| `claude-opus-4-6` | Active | N/A | Not sooner than February 5, 2027 |
| `claude-opus-4-5-20251101` | Active | N/A | Not sooner than November 24, 2026 |
| `claude-opus-4-1-20250805` | Active | N/A | Not sooner than August 5, 2026 |
| `claude-opus-4-20250514` | Deprecated | April 14, 2026 | June 15, 2026 |
| `claude-sonnet-4-6` | Active | N/A | Not sooner than February 17, 2027 |
| `claude-sonnet-4-5-20250929`| Active | N/A | Not sooner than September 29, 2026 |
| `claude-sonnet-4-20250514` | Deprecated | April 14, 2026 | June 15, 2026 |
| `claude-3-7-sonnet-20250219`| Retired | October 28, 2025 | February 19, 2026 |
| `claude-haiku-4-5-20251001` | Active | N/A | Not sooner than October 15, 2026 |
| `claude-3-5-haiku-20241022` | Retired | December 19, 2025 | February 19, 2026 |
| `claude-3-haiku-20240307` | Retired | February 19, 2026 | April 20, 2026 |
## Deprecation history
All deprecations are listed below, with the most recent announcements at the top.
### 2026-04-14: Claude Sonnet 4 and Claude Opus 4 models
On April 14, 2026, Anthropic notified developers using Claude Sonnet 4 and Claude Opus 4 models of their upcoming retirement on the Claude API.
| Retirement Date | Deprecated Model | Recommended Replacement |
|:----------------------------|:----------------------------|:--------------------------------|
| June 15, 2026 | `claude-sonnet-4-20250514` | `claude-sonnet-4-6` |
| June 15, 2026 | `claude-opus-4-20250514` | `claude-opus-4-7` |
### 2026-02-19: Claude Haiku 3 model
<Note>
This model was retired April 20, 2026.
</Note>
On February 19, 2026, Anthropic notified developers using Claude Haiku 3 model of its upcoming retirement on the Claude API.
| Retirement Date | Deprecated Model | Recommended Replacement |
|:----------------------------|:----------------------------|:--------------------------------|
| April 20, 2026 | `claude-3-haiku-20240307` | `claude-haiku-4-5-20251001` |
### 2025-12-19: Claude Haiku 3.5 model
<Note>
This model was retired February 19, 2026.
</Note>
On December 19, 2025, Anthropic notified developers using Claude Haiku 3.5 model of its upcoming retirement on the Claude API.
| Retirement Date | Deprecated Model | Recommended Replacement |
|:----------------------------|:----------------------------|:--------------------------------|
| February 19, 2026 | `claude-3-5-haiku-20241022` | `claude-haiku-4-5-20251001` |
### 2025-10-28: Claude Sonnet 3.7 model
<Note>
This model was retired February 19, 2026.
</Note>
On October 28, 2025, Anthropic notified developers using Claude Sonnet 3.7 model of its upcoming retirement on the Claude API.
| Retirement Date | Deprecated Model | Recommended Replacement |
|:----------------------------|:----------------------------|:--------------------------------|
| February 19, 2026 | `claude-3-7-sonnet-20250219`| `claude-sonnet-4-6` |
### 2025-08-13: Claude Sonnet 3.5 models
<Note>
These models were retired October 28, 2025.
</Note>
On August 13, 2025, Anthropic notified developers using Claude Sonnet 3.5 models of their upcoming retirement.
| Retirement Date | Deprecated Model | Recommended Replacement |
|:----------------------------|:----------------------------|:--------------------------------|
| October 28, 2025 | `claude-3-5-sonnet-20240620`| `claude-sonnet-4-6` |
| October 28, 2025 | `claude-3-5-sonnet-20241022`| `claude-sonnet-4-6` |
### 2025-06-30: Claude Opus 3 model
<Note>
This model was retired January 5, 2026.
</Note>
On June 30, 2025, Anthropic notified developers using Claude Opus 3 model of its upcoming retirement.
| Retirement Date | Deprecated Model | Recommended Replacement |
|:----------------------------|:----------------------------|:--------------------------------|
| January 5, 2026 | `claude-3-opus-20240229` | `claude-opus-4-7` |
### 2025-01-21: Claude 2, Claude 2.1, and Claude Sonnet 3 models
<Note>
These models were retired July 21, 2025.
</Note>
On January 21, 2025, Anthropic notified developers using Claude 2, Claude 2.1, and Claude Sonnet 3 models of their upcoming retirements.
| Retirement Date | Deprecated Model | Recommended Replacement |
|:----------------------------|:----------------------------|:--------------------------------|
| July 21, 2025 | `claude-2.0` | `claude-opus-4-7` |
| July 21, 2025 | `claude-2.1` | `claude-opus-4-7` |
| July 21, 2025 | `claude-3-sonnet-20240229` | `claude-sonnet-4-6` |
### 2024-09-04: Claude 1 and Instant models
<Note>
These models were retired November 6, 2024.
</Note>
On September 4, 2024, Anthropic notified developers using Claude 1 and Instant models of their upcoming retirements.
| Retirement Date | Deprecated Model | Recommended Replacement |
|:----------------------------|:--------------------------|:---------------------------|
| November 6, 2024 | `claude-1.0` | `claude-haiku-4-5-20251001`|
| November 6, 2024 | `claude-1.1` | `claude-haiku-4-5-20251001`|
| November 6, 2024 | `claude-1.2` | `claude-haiku-4-5-20251001`|
| November 6, 2024 | `claude-1.3` | `claude-haiku-4-5-20251001`|
| November 6, 2024 | `claude-instant-1.0` | `claude-haiku-4-5-20251001`|
| November 6, 2024 | `claude-instant-1.1` | `claude-haiku-4-5-20251001`|
| November 6, 2024 | `claude-instant-1.2` | `claude-haiku-4-5-20251001`|
---
## About/about-claude-use-case-guides-content-moderation-9aa9674309.md
# Content moderation
Content moderation is a critical aspect of maintaining a safe, respectful, and productive environment in digital applications. This guide discusses how Claude can be used to moderate content within your digital application.
---
> Visit the [content moderation cookbook](https://platform.claude.com/cookbook/misc-building-moderation-filter) to see an example content moderation implementation using Claude.
<Tip>This guide is focused on moderating user-generated content within your application. If you're looking for guidance on moderating interactions with Claude, refer to the [guardrails guide](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations).</Tip>
## Before building with Claude
### Decide whether to use Claude for content moderation
Here are some key indicators that you should use an LLM like Claude instead of a traditional ML or rules-based approach for content moderation:
<section title="You want a cost-effective and rapid implementation">
Traditional ML methods require significant engineering resources, ML expertise, and infrastructure costs. Human moderation systems incur even higher costs. With Claude, you can have a sophisticated moderation system up and running in a fraction of the time for a fraction of the price.
</section>
<section title="You desire both semantic understanding and quick decisions">
Traditional ML approaches, such as bag-of-words models or simple pattern matching, often struggle to understand the tone, intent, and context of the content. While human moderation systems excel at understanding semantic meaning, they require time for content to be reviewed. Claude bridges the gap by combining semantic understanding with the ability to deliver moderation decisions quickly.
</section>
<section title="You need consistent policy decisions">
By leveraging its advanced reasoning capabilities, Claude can interpret and apply complex moderation guidelines uniformly. This consistency helps ensure fair treatment of all content, reducing the risk of inconsistent or biased moderation decisions that can undermine user trust.
</section>
<section title="Your moderation policies are likely to change or evolve over time">
Once a traditional ML approach has been established, changing it is a laborious and data-intensive undertaking. On the other hand, as your product or customer needs evolve, Claude can easily adapt to changes or additions to moderation policies without extensive relabeling of training data.
</section>
<section title="You require interpretable reasoning for your moderation decisions">
If you wish to provide users or regulators with clear explanations behind moderation decisions, Claude can generate detailed and coherent justifications. This transparency is important for building trust and ensuring accountability in content moderation practices.
</section>
<section title="You need multilingual support without maintaining separate models">
Traditional ML approaches typically require separate models or extensive translation processes for each supported language. Human moderation requires hiring a workforce fluent in each supported language. Claude’s multilingual capabilities allow it to classify tickets in various languages without the need for separate models or extensive translation processes, streamlining moderation for global customer bases.
</section>
<section title="You require multimodal support">
Claude's multimodal capabilities allow it to analyze and interpret content across both text and images. This makes it a versatile tool for comprehensive content moderation in environments where different media types need to be evaluated together.
</section>
<Note>Anthropic has trained all Claude models to be honest, helpful and harmless. This may result in Claude moderating content deemed particularly dangerous (in line with the [Acceptable Use Policy](https://www.anthropic.com/legal/aup)), regardless of the prompt used. For example, an adult website that wants to allow users to post explicit sexual content may find that Claude still flags explicit content as requiring moderation, even if they specify in their prompt not to moderate explicit sexual content. Consider reviewing the AUP in advance of building a moderation solution.</Note>
### Generate examples of content to moderate
Before developing a content moderation solution, first create examples of content that should be flagged and content that should not be flagged. Ensure that you include edge cases and challenging scenarios that may be difficult for a content moderation system to handle effectively. Afterwards, review your examples to create a well-defined list of moderation categories.
For instance, the examples generated by a social media platform might include the following:
```python
allowed_user_comments = [
"This movie was great, I really enjoyed it. The main actor really killed it!",
"I hate Mondays.",
"It is a great time to invest in gold!",
]
disallowed_user_comments = [
"Delete this post now or you better hide. I am coming after you and your family.",
"Stay away from the 5G cellphones!! They are using 5G to control you.",
"Congratulations! You have won a $1,000 gift card. Click here to claim your prize!",
]
# Sample user comments to test the content moderation
user_comments = allowed_user_comments + disallowed_user_comments
# List of categories considered unsafe for content moderation
unsafe_categories = [
"Child Exploitation",
"Conspiracy Theories",
"Hate",
"Indiscriminate Weapons",
"Intellectual Property",
"Non-Violent Crimes",
"Privacy",
"Self-Harm",
"Sex Crimes",
"Sexual Content",
"Specialized Advice",
"Violent Crimes",
]
```
Effectively moderating these examples requires a nuanced understanding of language. In the comment, `This movie was great, I really enjoyed it. The main actor really killed it!`, the content moderation system needs to recognize that "killed it" is a metaphor, not an indication of actual violence. Conversely, despite the lack of explicit mentions of violence, the comment `Delete this post now or you better hide. I am coming after you and your family.` should be flagged by the content moderation system.
The `unsafe_categories` list can be customized to fit your specific needs. For example, if you wish to prevent minors from creating content on your website, you could append "Underage Posting" to the list.
___
## How to moderate content using Claude
### Select the right Claude model
When selecting a model, it’s important to consider the size of your data. If costs are a concern, a smaller model like Claude Haiku 4.5 is an excellent choice due to its cost-effectiveness. Below is an estimate of the cost to moderate text for a social media platform that receives one billion posts per month:
* **Content size**
* Posts per month: 1bn
* Characters per post: 100
* Total characters: 100bn
* **Estimated tokens**
* Input tokens: 28.6bn (assuming 1 token per 3.5 characters)
* Percentage of messages flagged: 3%
* Output tokens per flagged message: 50
* Total output tokens: 1.5bn
* **Claude Haiku 4.5 estimated cost**
* Input token cost: 2,860 MTok * \$1.00/MTok = \$2,860
* Output token cost: 1,500 MTok * \$5.00/MTok = \$7,500
* Monthly cost: \$2,860 + \$7,500 = \$10,360
* **Claude Opus 4.7 estimated cost**
* Input token cost: 2,860 MTok * \$5.00/MTok = \$14,300
* Output token cost: 1,500 MTok * \$25.00/MTok = \$37,500
* Monthly cost: \$14,300 + \$37,500 = \$51,800
<Tip>Actual costs may differ from these estimates. These estimates are based on the prompt highlighted in the section on [batch processing](#consider-batch-processing). Output tokens can be reduced even further by removing the `explanation` field from the response.</Tip>
### Build a strong prompt
In order to use Claude for content moderation, Claude must understand the moderation requirements of your application. Let’s start by writing a prompt that allows you to define your moderation needs:
```python Python nocheck hidelines={1}
import anthropic
import json
# Initialize the Anthropic client
client = anthropic.Anthropic()
def moderate_message(message, unsafe_categories):
# Convert the list of unsafe categories into a string, with each category on a new line
unsafe_category_str = "\n".join(unsafe_categories)
# Construct the prompt for Claude, including the message and unsafe categories
assessment_prompt = f"""
Determine whether the following message warrants moderation,
based on the unsafe categories outlined below.
Message:
<message>{message}</message>
Unsafe Categories:
<categories>
{unsafe_category_str}
</categories>
Respond with ONLY a JSON object, using the format below:
{{
"violation": <Boolean field denoting whether the message should be moderated>,
"categories": [Comma-separated list of violated categories],
"explanation": [Optional. Only include if there is a violation.]
}}"""
# Send the request to Claude for content moderation
response = client.messages.create(
model="claude-haiku-4-5-20251001", # Using the Haiku model for lower costs
max_tokens=200,
temperature=0, # Use 0 temperature for increased consistency
messages=[{"role": "user", "content": assessment_prompt}],
)
# Parse the JSON response from Claude
assessment = json.loads(response.content[0].text)
# Extract the violation status from the assessment
contains_violation = assessment["violation"]
# If there's a violation, get the categories and explanation; otherwise, use empty defaults
violated_categories = assessment.get("categories", []) if contains_violation else []
explanation = assessment.get("explanation") if contains_violation else None
return contains_violation, violated_categories, explanation
# Process each comment and print the results
for comment in user_comments:
print(f"\nComment: {comment}")
violation, violated_categories, explanation = moderate_message(
comment, unsafe_categories
)
if violation:
print(f"Violated Categories: {', '.join(violated_categories)}")
print(f"Explanation: {explanation}")
else:
print("No issues detected.")
```
In this example, the `moderate_message` function contains an assessment prompt that includes the unsafe content categories and the message to evaluate. The prompt asks Claude to assess whether the message should be moderated, based on the unsafe categories defined above.
The model's assessment is then parsed to determine if there is a violation. If there is a violation, Claude also returns a list of violated categories, as well as an explanation as to why the message is unsafe.
### Evaluate your prompt
Content moderation is a classification problem. Thus, you can use the same techniques outlined in the [classification cookbook](https://platform.claude.com/cookbook/capabilities-classification-guide) to determine the accuracy of your content moderation system.
One additional consideration is that instead of treating content moderation as a binary classification problem, you may instead create multiple categories to represent various risk levels. Creating multiple risk levels allows you to adjust the aggressiveness of your moderation. For example, you might want to automatically block user queries that are deemed high risk, while users with many medium risk queries are flagged for human review.
```python Python nocheck hidelines={1}
import anthropic
import json
# Initialize the Anthropic client
client = anthropic.Anthropic()
def assess_risk_level(message, unsafe_categories):
# Convert the list of unsafe categories into a string, with each category on a new line
unsafe_category_str = "\n".join(unsafe_categories)
# Construct the prompt for Claude, including the message, unsafe categories, and risk level definitions
assessment_prompt = f"""
Assess the risk level of the following message warrants moderation,
based on the unsafe categories listed below.
Message:
<message>{message}</message>
Unsafe Categories:
<categories>
{unsafe_category_str}
</categories>
Assign a risk level based on your confidence that the user's message should be moderated
based on the defined unsafe categories:
0 - No risk
1 - Low risk
2 - Medium risk
3 - High risk
Respond with ONLY a JSON object, using the format below:
{{
"risk_level": <Numerical field denoting the risk level>,
"categories": [Comma-separated list of violated categories],
"explanation": <Optional. Only include if risk level is greater than 0>
}}"""
# Send the request to Claude for risk assessment
response = client.messages.create(
model="claude-haiku-4-5-20251001", # Using the Haiku model for lower costs
max_tokens=200,
temperature=0, # Use 0 temperature for increased consistency
messages=[{"role": "user", "content": assessment_prompt}],
)
# Parse the JSON response from Claude
assessment = json.loads(response.content[0].text)
# Extract the risk level, violated categories, and explanation from the assessment
risk_level = assessment["risk_level"]
violated_categories = assessment["categories"]
explanation = assessment.get("explanation")
return risk_level, violated_categories, explanation
# Process each comment and print the results
for comment in user_comments:
print(f"\nComment: {comment}")
risk_level, violated_categories, explanation = assess_risk_level(
comment, unsafe_categories
)
print(f"Risk Level: {risk_level}")
if violated_categories:
print(f"Violated Categories: {', '.join(violated_categories)}")
if explanation:
print(f"Explanation: {explanation}")
```
This code implements an `assess_risk_level` function that uses Claude to evaluate the risk level of a message. The function accepts a message and a list of unsafe categories as inputs.
Within the function, a prompt is generated for Claude, including the message to be assessed, the unsafe categories, and specific instructions for evaluating the risk level. The prompt instructs Claude to respond with a JSON object that includes the risk level, the violated categories, and an optional explanation.
This approach enables flexible content moderation by assigning risk levels. It can be seamlessly integrated into a larger system to automate content filtering or flag comments for human review based on their assessed risk level. For instance, when executing this code, the comment `Delete this post now or you better hide. I am coming after you and your family.` is identified as high risk due to its dangerous threat. Conversely, the comment `Stay away from the 5G cellphones!! They are using 5G to control you.` is categorized as medium risk.
### Deploy your prompt
Once you are confident in the quality of your solution, it's time to deploy it to production. Here are some best practices to follow when using content moderation in production:
1. **Provide clear feedback to users:** When user input is blocked or a response is flagged due to content moderation, provide informative and constructive feedback to help users understand why their message was flagged and how they can rephrase it appropriately. In the coding examples above, this is done through the `explanation` tag in the Claude response.
2. **Analyze moderated content:** Keep track of the types of content being flagged by your moderation system to identify trends and potential areas for improvement.
3. **Continuously evaluate and improve:** Regularly assess the performance of your content moderation system using metrics such as precision and recall tracking. Use this data to iteratively refine your moderation prompts, keywords, and assessment criteria.
___
## Improve performance
In complex scenarios, it may be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](/docs/en/build-with-claude/prompt-engineering/overview). Here are some advanced strategies:
### Define topics and provide examples
In addition to listing the unsafe categories in the prompt, further improvements can be made by providing definitions and phrases related to each category.
```python Python nocheck hidelines={1}
import anthropic
import json
# Initialize the Anthropic client
client = anthropic.Anthropic()
# Dictionary of categories considered unsafe for content moderation, with their definitions
unsafe_category_definitions = {
"Child Exploitation": "Content that depicts child nudity or that enables, encourages, excuses, or depicts the sexual abuse of children.",
"Conspiracy Theories": """Content that promotes or endorses unfounded, false, or misleading theories about events, situations, or individuals,
which can incite harm or undermine public trust in institutions or facts.""",
"Hate": """Content that is hateful toward people on the basis of their protected characteristics
(race, color, ethnicity, national origin, disability, religious affiliation, caste, sexual orientation, sex, gender identity and serious disease),
or content that perpetuates negative stereotypes.""",
"Indiscriminate Weapons": "Content that enables the creation of weapons of mass destruction.",
"Intellectual Property": "Content that violates the intellectual property rights of third parties.",
"Non-Violent Crimes": "Content that enables, encourages, or excuses the commission of non-violent crimes.",
"Privacy": "Content that contains sensitive, personal information about private individuals.",
"Self-Harm": "Content that enables, encourages, or excuses acts of intentional self-harm.",
"Sex Crimes": "Content that enables, encourages, or excuses the commission of sex crimes.",
"Sexual Content": "Content that contains erotic descriptions or explicit depictions of sex acts.",
"Specialized Advice": """Content that contains financial, medical, or legal advice.
Financial advice includes guidance on investments, stocks, bonds, or any financial planning.""",
"Violent Crimes": "Content that enables, encourages, or excuses the commission of violent crimes.",
}
def moderate_message_with_definitions(message, unsafe_category_definitions):
# Format unsafe categories string, with each category and its definition on a new line
unsafe_category_str = "\n".join(
f"{category}: {definition}"
for category, definition in unsafe_category_definitions.items()
)
# Construct the prompt for Claude, including the message and unsafe categories
assessment_prompt = f"""Determine whether the following message warrants moderation, based on the unsafe categories outlined below.
Message:
<message>{message}</message>
Unsafe Categories and Their Definitions:
<categories>
{unsafe_category_str}
</categories>
It's important that you remember all unsafe categories and their definitions.
Respond with ONLY a JSON object, using the format below:
{{
"violation": <Boolean field denoting whether the message should be moderated>,
"categories": [Comma-separated list of violated categories],
"explanation": [Optional. Only include if there is a violation.]
}}"""
# Send the request to Claude for content moderation
response = client.messages.create(
model="claude-haiku-4-5-20251001", # Using the Haiku model for lower costs
max_tokens=200,
temperature=0, # Use 0 temperature for increased consistency
messages=[{"role": "user", "content": assessment_prompt}],
)
# Parse the JSON response from Claude
assessment = json.loads(response.content[0].text)
# Extract the violation status from the assessment
contains_violation = assessment["violation"]
# If there's a violation, get the categories and explanation; otherwise, use empty defaults
violated_categories = assessment.get("categories", []) if contains_violation else []
explanation = assessment.get("explanation") if contains_violation else None
return contains_violation, violated_categories, explanation
# Process each comment and print the results
for comment in user_comments:
print(f"\nComment: {comment}")
violation, violated_categories, explanation = moderate_message_with_definitions(
comment, unsafe_category_definitions
)
if violation:
print(f"Violated Categories: {', '.join(violated_categories)}")
print(f"Explanation: {explanation}")
else:
print("No issues detected.")
```
The `moderate_message_with_definitions` function expands upon the earlier `moderate_message` function by allowing each unsafe category to be paired with a detailed definition. This occurs in the code by replacing the `unsafe_categories` list from the original function with an `unsafe_category_definitions` dictionary. This dictionary maps each unsafe category to its corresponding definition. Both the category names and their definitions are included in the prompt.
Notably, the definition for the `Specialized Advice` category now specifies the types of financial advice that should be prohibited. As a result, the comment `It's a great time to invest in gold!`, which previously passed the `moderate_message` assessment, now triggers a violation.
### Consider batch processing
To reduce costs in situations where real-time moderation isn't necessary, consider moderating messages in batches. Include multiple messages within the prompt's context, and ask Claude to assess which messages should be moderated.
```python Python nocheck hidelines={1}
import anthropic
import json
# Initialize the Anthropic client
client = anthropic.Anthropic()
def batch_moderate_messages(messages, unsafe_categories):
# Convert the list of unsafe categories into a string, with each category on a new line
unsafe_category_str = "\n".join(unsafe_categories)
# Format messages string, with each message wrapped in XML-like tags and given an ID
messages_str = "\n".join(
[f"<message id={idx}>{msg}</message>" for idx, msg in enumerate(messages)]
)
# Construct the prompt for Claude, including the messages and unsafe categories
assessment_prompt = f"""Determine the messages to moderate, based on the unsafe categories outlined below.
Messages:
<messages>
{messages_str}
</messages>
Unsafe categories and their definitions:
<categories>
{unsafe_category_str}
</categories>
Respond with ONLY a JSON object, using the format below:
{{
"violations": [
{{
"id": <message id>,
"categories": [list of violated categories],
"explanation": <Explanation of why there's a violation>
}},
...
]
}}
Important Notes:
- Remember to analyze every message for a violation.
- Select any number of violations that reasonably apply."""
# Send the request to Claude for content moderation
response = client.messages.create(
model="claude-haiku-4-5-20251001", # Using the Haiku model for lower costs
max_tokens=2048, # Increased max token count to handle batches
temperature=0, # Use 0 temperature for increased consistency
messages=[{"role": "user", "content": assessment_prompt}],
)
# Parse the JSON response from Claude
assessment = json.loads(response.content[0].text)
return assessment
# Process the batch of comments and get the response
response_obj = batch_moderate_messages(user_comments, unsafe_categories)
# Print the results for each detected violation
for violation in response_obj["violations"]:
print(f"""Comment: {user_comments[violation["id"]]}
Violated Categories: {", ".join(violation["categories"])}
Explanation: {violation["explanation"]}
""")
```
In this example, the `batch_moderate_messages` function handles the moderation of an entire batch of messages with a single Claude API call.
Inside the function, a prompt is created that includes the list of messages to evaluate, the defined unsafe content categories, and their descriptions. The prompt directs Claude to return a JSON object listing all messages that contain violations. Each message in the response is identified by its id, which corresponds to the message's position in the input list.
Keep in mind that finding the optimal batch size for your specific needs may require some experimentation. While larger batch sizes can lower costs, they might also lead to a slight decrease in quality. Additionally, you may need to increase the `max_tokens` parameter in the Claude API call to accommodate longer responses. For details on the maximum number of tokens your chosen model can output, refer to the [model comparison page](/docs/en/about-claude/models#model-comparison-table).
<CardGroup cols={2}>
<Card title="Content moderation cookbook" icon="link" href="https://platform.claude.com/cookbook/misc-building-moderation-filter">
View a fully implemented code-based example of how to use Claude for content moderation.
</Card>
<Card title="Guardrails guide" icon="link" href="/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations">
Explore the guardrails guide for techniques to moderate interactions with Claude.
</Card>
</CardGroup>
---
## About/about-claude-use-case-guides-customer-support-chat-5b82b8509b.md
# Customer support agent
This guide walks through how to leverage Claude's advanced conversational capabilities to handle customer inquiries in real time, providing 24/7 support, reducing wait times, and managing high support volumes with accurate responses and positive interactions.
---
## Before building with Claude
### Decide whether to use Claude for support chat
Here are some key indicators that you should employ an LLM like Claude to automate portions of your customer support process:
<section title="High volume of repetitive queries">
Claude excels at handling a large number of similar questions efficiently, freeing up human agents for more complex issues.
</section>
<section title="Need for quick information synthesis">
Claude can quickly retrieve, process, and combine information from vast knowledge bases, while human agents may need time to research or consult multiple sources.
</section>
<section title="24/7 availability requirement">
Claude can provide round-the-clock support without fatigue, whereas staffing human agents for continuous coverage can be costly and challenging.
</section>
<section title="Rapid scaling during peak periods">
Claude can handle sudden increases in query volume without the need for hiring and training additional staff.
</section>
<section title="Consistent brand voice">
You can instruct Claude to consistently represent your brand's tone and values, whereas human agents may vary in their communication styles.
</section>
Some considerations for choosing Claude over other LLMs:
- You prioritize natural, nuanced conversation: Claude's sophisticated language understanding allows for more natural, context-aware conversations that feel more human-like than chats with other LLMs.
- You often receive complex and open-ended queries: Claude can handle a wide range of topics and inquiries without generating canned responses or requiring extensive programming of permutations of user utterances.
- You need scalable multilingual support: Claude's multilingual capabilities allow it to engage in conversations in over 200 languages without the need for separate chatbots or extensive translation processes for each supported language.
### Define your ideal chat interaction
Outline an ideal customer interaction to define how and when you expect the customer to interact with Claude. This outline will help to determine the technical requirements of your solution.
Here is an example chat interaction for car insurance customer support:
* **Customer:** Initiates support chat experience
* **Claude:** Warmly greets customer and initiates conversation
* **Customer:** Asks about insurance for their new electric car
* **Claude:** Provides relevant information about electric vehicle coverage
* **Customer:** Asks questions related to unique needs for electric vehicle insurances
* **Claude:** Responds with accurate and informative answers and provides links to the sources
* **Customer:** Asks off-topic questions unrelated to insurance or cars
* **Claude:** Clarifies it does not discuss unrelated topics and steers the user back to car insurance
* **Customer:** Expresses interest in an insurance quote
* **Claude:** Ask a set of questions to determine the appropriate quote, adapting to their responses
* **Claude:** Sends a request to use the quote generation API tool along with necessary information collected from the user
* **Claude:** Receives the response information from the API tool use, synthesizes the information into a natural response, and presents the provided quote to the user
* **Customer:** Asks follow up questions
* **Claude:** Answers follow up questions as needed
* **Claude:** Guides the customer to the next steps in the insurance process and closes out the conversation
<Tip>In the real example that you write for your own use case, you might find it useful to write out the actual words in this interaction so that you can also get a sense of the ideal tone, response length, and level of detail you want Claude to have.</Tip>
### Break the interaction into unique tasks
Customer support chat is a collection of multiple different tasks, from question answering to information retrieval to taking action on requests, wrapped up in a single customer interaction. Before you start building, break down your ideal customer interaction into every task you want Claude to be able to perform. This ensures you can prompt and evaluate Claude for every task, and gives you a good sense of the range of interactions you need to account for when writing test cases.
<Tip>Customers sometimes find it helpful to visualize this as an interaction flowchart of possible conversation inflection points depending on user requests.</Tip>
Here are the key tasks associated with the example insurance interaction above:
1. Greeting and general guidance
- Warmly greet the customer and initiate conversation
- Provide general information about the company and interaction
2. Product Information
- Provide information about electric vehicle coverage
<Note>This will require that Claude have the necessary information in its context, and might imply that a [RAG integration](https://platform.claude.com/cookbook/capabilities-retrieval-augmented-generation-guide) is necessary.</Note>
- Answer questions related to unique electric vehicle insurance needs
- Answer follow-up questions about the quote or insurance details
- Offer links to sources when appropriate
3. Conversation Management
- Stay on topic (car insurance)
- Redirect off-topic questions back to relevant subjects
4. Quote Generation
- Ask appropriate questions to determine quote eligibility
- Adapt questions based on customer responses
- Submit collected information to quote generation API
- Present the provided quote to the customer
### Establish success criteria
Work with your support team to [define success criteria and write detailed evaluations](/docs/en/test-and-evaluate/develop-tests) with measurable benchmarks and goals.
Here are criteria and benchmarks that can be used to evaluate how successfully Claude performs the defined tasks:
<section title="Query comprehension accuracy">
This metric evaluates how accurately Claude understands customer inquiries across various topics. Measure this by reviewing a sample of conversations and assessing whether Claude has the correct interpretation of customer intent, critical next steps, what successful resolution looks like, and more. Aim for a comprehension accuracy of 95% or higher.
</section>
<section title="Response relevance">
This assesses how well Claude's response addresses the customer's specific question or issue. Evaluate a set of conversations and rate the relevance of each response (using LLM-based grading for scale). Target a relevance score of 90% or above.
</section>
<section title="Response accuracy">
Assess the correctness of general company and product information provided to the user, based on the information provided to Claude in context. Target 100% accuracy in this introductory information.
</section>
<section title="Citation provision relevance">
Track the frequency and relevance of links or sources offered. Target providing relevant sources in 80% of interactions where additional information could be beneficial.
</section>
<section title="Topic adherence">
Measure how well Claude stays on topic, such as the topic of car insurance in the example implementation. Aim for 95% of responses to be directly related to car insurance or the customer's specific query.
</section>
<section title="Content generation effectiveness">
Measure how successful Claude is at determining when to generate informational content and how relevant that content is. For example, in this implementation, you would be determining how well Claude understands when to generate a quote and how accurate that quote is. Target 100% accuracy, as this is vital information for a successful customer interaction.
</section>
<section title="Escalation efficiency">
This measures Claude's ability to recognize when a query needs human intervention and escalate appropriately. Track the percentage of correctly escalated conversations versus those that should have been escalated but weren't. Aim for an escalation accuracy of 95% or higher.
</section>
Here are criteria and benchmarks that can be used to evaluate the business impact of employing Claude for support:
<section title="Sentiment maintenance">
This assesses Claude's ability to maintain or improve customer sentiment throughout the conversation. Use sentiment analysis tools to measure sentiment at the beginning and end of each conversation. Aim for maintained or improved sentiment in 90% of interactions.
</section>
<section title="Deflection rate">
The percentage of customer inquiries successfully handled by the chatbot without human intervention. Typically aim for 70-80% deflection rate, depending on the complexity of inquiries.
</section>
<section title="Customer satisfaction score">
A measure of how satisfied customers are with their chatbot interaction. Usually done through post-interaction surveys. Aim for a CSAT score of 4 out of 5 or higher.
</section>
<section title="Average handle time">
The average time it takes for the chatbot to resolve an inquiry. This varies widely based on the complexity of issues, but generally, aim for a lower AHT compared to human agents.
</section>
## How to implement Claude as a customer service agent
### Choose the right Claude model
The choice of model depends on the trade-offs between cost, accuracy, and response time.
For customer support chat, Claude Opus 4.7 is well suited to balance intelligence, latency, and cost. However, for instances where you have conversation flow with multiple prompts including RAG, tool use, and/or long-context prompts, Claude Haiku 4.5 may be more suitable to optimize for latency.
### Build a strong prompt
Using Claude for customer support requires Claude having enough direction and context to respond appropriately, while having enough flexibility to handle a wide range of customer inquiries.
Start by writing the elements of a strong prompt, starting with a system prompt:
```python
IDENTITY = """You are Eva, a friendly and knowledgeable AI assistant for Acme Insurance
Company. Your role is to warmly welcome customers and provide information on
Acme's insurance offerings, which include car insurance and electric car
insurance. You can also help customers get quotes for their insurance needs."""
```
<Tip>While you may be tempted to put all your information inside a system prompt as a way to separate instructions from the user conversation, Claude actually works best with the bulk of its prompt content written inside the first `User` turn (with the only exception being role prompting). Read more at [Giving Claude a role with a system prompt](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role).</Tip>
It's best to break down complex prompts into subsections and write one part at a time. For each task, you might find greater success by following a step by step process to define the parts of the prompt Claude would need to do the task well. For this car insurance customer support example, you'll be writing piecemeal all the parts for a prompt starting with the "Greeting and general guidance" task. This also makes debugging your prompt easier as you can more quickly adjust individual parts of the overall prompt.
Put all of these pieces in a file called `config.py`.
```python
STATIC_GREETINGS_AND_GENERAL = """
<static_context>
Acme Auto Insurance: Your Trusted Companion on the Road
About:
At Acme Insurance, we understand that your vehicle is more than just a mode of transportation—it's your ticket to life's adventures.
Since 1985, we've been crafting auto insurance policies that give drivers the confidence to explore, commute, and travel with peace of mind.
Whether you're navigating city streets or embarking on cross-country road trips, Acme is there to protect you and your vehicle.
Our innovative auto insurance policies are designed to adapt to your unique needs, covering everything from fender benders to major collisions.
With Acme's award-winning customer service and swift claim resolution, you can focus on the joy of driving while we handle the rest.
We're not just an insurance provider—we're your co-pilot in life's journeys.
Choose Acme Auto Insurance and experience the assurance that comes with superior coverage and genuine care. Because at Acme, we don't just
insure your car—we fuel your adventures on the open road.
Note: We also offer specialized coverage for electric vehicles, ensuring that drivers of all car types can benefit from our protection.
Acme Insurance offers the following products:
- Car insurance
- Electric car insurance
- Two-wheeler insurance
Business hours: Monday-Friday, 9 AM - 5 PM EST
Customer service number: 1-800-123-4567
</static_context>
"""
```
Then do the same for your car insurance and electric car insurance information.
```python
STATIC_CAR_INSURANCE = """
<static_context>
Car Insurance Coverage:
Acme's car insurance policies typically cover:
1. Liability coverage: Pays for bodily injury and property damage you cause to others.
2. Collision coverage: Pays for damage to your car in an accident.
3. Comprehensive coverage: Pays for damage to your car from non-collision incidents.
4. Medical payments coverage: Pays for medical expenses after an accident.
5. Uninsured/underinsured motorist coverage: Protects you if you're hit by a driver with insufficient insurance.
Optional coverages include:
- Rental car reimbursement
- Roadside assistance
- New car replacement
</static_context>
"""
STATIC_ELECTRIC_CAR_INSURANCE = """
<static_context>
Electric Car Insurance:
Our specialized electric car insurance goes beyond traditional auto coverage,
offering tailored protection for your high-tech investment. In addition to standard coverages, we offer:
- Safeguarding expensive battery systems
- Covering home charging equipment
- Adapting to the rapidly evolving world of electric vehicles
Whether you're driving a Rivian, Nissan Leaf, Chevrolet Bolt,
or any other electric vehicle, our knowledgeable agents are ready to craft a policy
that gives you the confidence to enjoy every electron-powered mile.
</static_context>
"""
```
Now that you have your static content, add at least 4-5 sample "good" interactions to guide Claude's responses. These examples should be representative of your ideal customer interaction and can include guardrails, tool calls, etc.
```python
EXAMPLES = """
Here are a few examples of how you can interact with customers:
<example 1>
H: Hi, do you offer commercial insurance for small businesses?
A: Ah! Unfortunately, we don't offer commercial insurance at this time.
However, we do provide a range of personal insurance products including car insurance and electric car insurance.
Would you like to know more about these offerings?
</example 1>
<example 2>
H: Hi, what are your business hours?
A: Our business hours are Monday to Friday, 9 AM to 5 PM EST.
If you have any questions or need assistance, feel free to reach out during those times.
How else can I assist you today?
</example 2>
<example 3>
H: I'm shopping for car insurance. What does Acme offer?
A: Great choice! Acme's car insurance policies typically include:
- Liability coverage: Protects you if you're at fault in an accident
- Collision coverage: Pays for damage to your car in an accident
- Comprehensive coverage: Covers non-collision incidents like theft or vandalism
- Medical payments coverage: Pays for medical expenses after an accident
- Uninsured/underinsured motorist coverage: Protects you from drivers with insufficient insurance
We also offer optional coverages like rental car reimbursement, roadside assistance, and new car replacement.
Would you like more details on any of these coverages, or do you have specific questions about insuring your vehicle?
</example 3>
<example 4>
H: I'd like to hear about your electric car insurance.
A: Certainly! Our electric car insurance is specially designed to meet the unique needs of electric vehicle owners.
In addition to all the standard coverages we offer for regular cars, our electric car policies include:
- Battery coverage: Protection against damage or degradation of your vehicle's expensive battery system
- Tech package: Covers repairs or replacement of advanced electronics and onboard computer systems
- Charging station coverage: Protects both home and portable charging equipment
- Cybersecurity protection: Coverage against hacking or digital threats
- Specialized roadside assistance: Includes flatbed towing to protect the vehicle's undercarriage
We cover a wide range of electric vehicles, including popular models from Tesla, Rivian, Nissan, Chevrolet, and more.
Is there a specific electric vehicle you're looking to insure, or would you like more details on any of these coverages?
</example 4>
<example 5>
H: I'd like to get a quote for my car insurance.
A: Certainly! I'd be happy to help you get a quote for your car insurance.
To provide you with an accurate quote, I'll need to collect some information about your vehicle and the primary driver.
Let's start with the basics:
1. What is the make and model of your vehicle?
2. What year was it manufactured?
3. Approximately how many miles have you driven?
4. What is the age of the primary driver?
Once you provide this information, I'll use our quoting tool to generate a personalized insurance quote for you.
</example 5>
"""
```
You will also want to include any important instructions outlining Do's and Don'ts for how Claude should interact with the customer.
This may draw from brand guardrails or support policies.
```python
ADDITIONAL_GUARDRAILS = """Please adhere to the following guardrails:
1. Only provide information about insurance types listed in our offerings.
2. If asked about an insurance type we don't offer, politely state
that we don't provide that service.
3. Do not speculate about future product offerings or company plans.
4. Don't make promises or enter into agreements it's not authorized to make.
You only provide information and guidance.
5. Do not mention any competitor's products or services.
"""
```
Now combine all these sections into a single string to use as your prompt.
```python nocheck
TASK_SPECIFIC_INSTRUCTIONS = " ".join(
[
STATIC_GREETINGS_AND_GENERAL,
STATIC_CAR_INSURANCE,
STATIC_ELECTRIC_CAR_INSURANCE,
EXAMPLES,
ADDITIONAL_GUARDRAILS,
]
)
```
### Add dynamic and agentic capabilities with tool use
Claude is capable of taking actions and retrieving information dynamically using client-side tool use functionality. Start by listing any external tools or APIs the prompt should utilize.
For this example, start with one tool for calculating the quote.
<Tip>As a reminder, this tool will not perform the actual calculation, it will just signal to the application that a tool should be used with whatever arguments specified.</Tip>
Example insurance quote calculator:
```python
TOOLS = [
{
"name": "get_quote",
"description": "Calculate the insurance quote based on user input. Returned value is per month premium.",
"input_schema": {
"type": "object",
"properties": {
"make": {"type": "string", "description": "The make of the vehicle."},
"model": {"type": "string", "description": "The model of the vehicle."},
"year": {
"type": "integer",
"description": "The year the vehicle was manufactured.",
},
"mileage": {
"type": "integer",
"description": "The mileage on the vehicle.",
},
"driver_age": {
"type": "integer",
"description": "The age of the primary driver.",
},
},
"required": ["make", "model", "year", "mileage", "driver_age"],
},
}
]
def get_quote(make, model, year, mileage, driver_age):
"""Returns the premium per month in USD"""
# You can call an http endpoint or a database to get the quote.
# Here, we simulate a delay of 1 seconds and return a fixed quote of 100.
time.sleep(1)
return 100
```
### Deploy your prompts
It's hard to know how well your prompt works without deploying it in a test production setting and [running evaluations](/docs/en/test-and-evaluate/develop-tests) so let's build a small application using the prompt, the Anthropic SDK, and streamlit for a user interface.
In a file called `chatbot.py`, start by setting up the ChatBot class, which will encapsulate the interactions with the Anthropic SDK.
The class should have two main methods: `generate_message` and `process_user_input`.
```python nocheck
from anthropic import Anthropic
from config import IDENTITY, TOOLS, MODEL, get_quote
from dotenv import load_dotenv
load_dotenv()
class ChatBot:
def __init__(self, session_state):
self.anthropic = Anthropic()
self.session_state = session_state
def generate_message(
self,
messages,
max_tokens,
):
try:
response = self.anthropic.messages.create(
model=MODEL,
system=IDENTITY,
max_tokens=max_tokens,
messages=messages,
tools=TOOLS,
)
return response
except Exception as e:
return {"error": str(e)}
def process_user_input(self, user_input):
self.session_state.messages.append({"role": "user", "content": user_input})
response_message = self.generate_message(
messages=self.session_state.messages,
max_tokens=2048,
)
if "error" in response_message:
return f"An error occurred: {response_message['error']}"
if response_message.content[-1].type == "tool_use":
tool_use = response_message.content[-1]
func_name = tool_use.name
func_params = tool_use.input
tool_use_id = tool_use.id
result = self.handle_tool_use(func_name, func_params)
self.session_state.messages.append(
{"role": "assistant", "content": response_message.content}
)
self.session_state.messages.append(
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": tool_use_id,
"content": f"{result}",
}
],
}
)
follow_up_response = self.generate_message(
messages=self.session_state.messages,
max_tokens=2048,
)
if "error" in follow_up_response:
return f"An error occurred: {follow_up_response['error']}"
response_text = follow_up_response.content[0].text
self.session_state.messages.append(
{"role": "assistant", "content": response_text}
)
return response_text
elif response_message.content[0].type == "text":
response_text = response_message.content[0].text
self.session_state.messages.append(
{"role": "assistant", "content": response_text}
)
return response_text
else:
raise Exception("An error occurred: Unexpected response type")
def handle_tool_use(self, func_name, func_params):
if func_name == "get_quote":
premium = get_quote(**func_params)
return f"Quote generated: ${premium:.2f} per month"
raise Exception("An unexpected tool was used")
```
### Build your user interface
Test deploying this code with Streamlit using a main method. This `main()` function sets up a Streamlit-based chat interface.
Do this in a file called `app.py`
```python nocheck
import streamlit as st
from chatbot import ChatBot
from config import TASK_SPECIFIC_INSTRUCTIONS
def main():
st.title("Chat with Eva, Acme Insurance Company's Assistant🤖")
if "messages" not in st.session_state:
st.session_state.messages = [
{"role": "user", "content": TASK_SPECIFIC_INSTRUCTIONS},
{"role": "assistant", "content": "Understood"},
]
chatbot = ChatBot(st.session_state)
# Display user and assistant messages skipping the first two
for message in st.session_state.messages[2:]:
# ignore tool use blocks
if isinstance(message["content"], str):
with st.chat_message(message["role"]):
st.markdown(message["content"])
if user_msg := st.chat_input("Type your message here..."):
st.chat_message("user").markdown(user_msg)
with st.chat_message("assistant"):
with st.spinner("Eva is thinking..."):
response_placeholder = st.empty()
full_response = chatbot.process_user_input(user_msg)
response_placeholder.markdown(full_response)
if __name__ == "__main__":
main()
```
Run the program with:
```bash
streamlit run app.py
```
### Evaluate your prompts
Prompting often requires testing and optimization for it to be production ready. To determine the readiness of your solution, evaluate the chatbot performance using a systematic process combining quantitative and qualitative methods. Creating a [strong empirical evaluation](/docs/en/test-and-evaluate/develop-tests#building-evals-and-test-cases) based on your defined success criteria will allow you to optimize your prompts.
<Tip>The [Claude Console](/dashboard) now features an Evaluation tool that allows you to test your prompts under various scenarios.</Tip>
### Improve performance
In complex scenarios, it may be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](/docs/en/build-with-claude/prompt-engineering/overview) & [guardrail implementation strategies](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations). Here are some common scenarios:
#### Reduce long context latency with RAG
When dealing with large amounts of static and dynamic context, including all information in the prompt can lead to high costs, slower response times, and reaching context window limits. In this scenario, implementing Retrieval Augmented Generation (RAG) techniques can significantly improve performance and efficiency.
By using [embedding models like Voyage](/docs/en/build-with-claude/embeddings) to convert information into vector representations, you can create a more scalable and responsive system. This approach allows for dynamic retrieval of relevant information based on the current query, rather than including all possible context in every prompt.
Implementing RAG for support use cases [RAG recipe](https://platform.claude.com/cookbook/capabilities-retrieval-augmented-generation-guide) has been shown to increase accuracy, reduce response times, and reduce API costs in systems with extensive context requirements.
#### Integrate real-time data with tool use
When dealing with queries that require real-time information, such as account balances or policy details, embedding-based RAG approaches are not sufficient. Instead, you can leverage tool use to significantly enhance your chatbot's ability to provide accurate, real-time responses. For example, you can use tool use to look up customer information, retrieve order details, and cancel orders on behalf of the customer.
This approach, [outlined in the tool use: customer service agent recipe](https://platform.claude.com/cookbook/tool-use-customer-service-agent), allows you to seamlessly integrate live data into your Claude's responses and provide a more personalized and efficient customer experience.
#### Strengthen input and output guardrails
When deploying a chatbot, especially in customer service scenarios, it's crucial to prevent risks associated with misuse, out-of-scope queries, and inappropriate responses. While Claude is inherently resilient to such scenarios, here are additional steps to strengthen your chatbot guardrails:
- [Reduce hallucination](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations): Implement fact-checking mechanisms and [citations](https://platform.claude.com/cookbook/misc-using-citations) to ground responses in provided information.
- Cross-check information: Verify that the agent's responses align with your company's policies and known facts.
- Avoid contractual commitments: Ensure the agent doesn't make promises or enter into agreements it's not authorized to make.
- [Mitigate jailbreaks](/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks): Use methods like harmlessness screens and input validation to prevent users from exploiting model vulnerabilities, aiming to generate inappropriate content.
- Avoid mentioning competitors: Implement a competitor mention filter to maintain brand focus and not mention any competitor's products or services.
- [Increase output consistency](/docs/en/test-and-evaluate/strengthen-guardrails/increase-consistency): Prevent Claude from changing style or going out of character, even during long, complex interactions.
- Remove Personally Identifiable Information (PII): Unless explicitly required and authorized, strip out any PII from responses.
#### Reduce perceived response time with streaming
When dealing with potentially lengthy responses, implementing streaming can significantly improve user engagement and satisfaction. In this scenario, users receive the answer progressively instead of waiting for the entire response to be generated.
Here is how to implement streaming:
1. Use the [Anthropic Streaming API](/docs/en/build-with-claude/streaming) to support streaming responses.
2. Set up your frontend to handle incoming chunks of text.
3. Display each chunk as it arrives, simulating real-time typing.
4. Implement a mechanism to save the full response, allowing users to view it if they navigate away and return.
In some cases, streaming enables the use of more advanced models with higher base latencies, as the progressive display mitigates the impact of longer processing times.
#### Scale your Chatbot
As the complexity of your Chatbot grows, your application architecture can evolve to match. Before you add further layers to your architecture, consider the following less exhaustive options:
- Ensure that you are making the most out of your prompts and optimizing through prompt engineering. Use the [prompt engineering guides](/docs/en/build-with-claude/prompt-engineering/overview) to write the most effective prompts.
- Add additional [tools](/docs/en/build-with-claude/tool-use) to the prompt (which can include [prompt chains](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#chain-complex-prompts)) and see if you can achieve the functionality required.
If your Chatbot handles incredibly varied tasks, you may want to consider adding a [separate intent classifier](https://platform.claude.com/cookbook/capabilities-classification-guide) to route the initial customer query. For the existing application, this would involve creating a decision tree that would route customer queries through the classifier and then to specialized conversations (with their own set of tools and system prompts). Note, this method requires an additional call to Claude that can increase latency.
### Integrate Claude into your support workflow
While the examples above have focused on Python functions callable within a Streamlit environment, deploying Claude for real-time support chatbot requires an API service.
Here's how you can approach this:
1. Create an API wrapper: Develop a simple API wrapper around your classification function. For example, you can use Flask API or Fast API to wrap your code into a HTTP Service. Your HTTP service could accept the user input and return the Assistant response in its entirety. Thus, your service could have the following characteristics:
- Server-Sent Events (SSE): SSE allows for real-time streaming of responses from the server to the client. This is crucial for providing a smooth, interactive experience when working with LLMs.
- Caching: Implementing caching can significantly improve response times and reduce unnecessary API calls.
- Context retention: Maintaining context when a user navigates away and returns is important for continuity in conversations.
2. Build a web interface: Implement a user-friendly web UI for interacting with the Claude-powered agent.
<CardGroup cols={2}>
<Card title="Retrieval Augmented Generation (RAG) cookbook" icon="link" href="https://platform.claude.com/cookbook/capabilities-retrieval-augmented-generation-guide">
Visit the RAG cookbook recipe for more example code and detailed guidance.
</Card>
<Card title="Citations cookbook" icon="link" href="https://platform.claude.com/cookbook/misc-using-citations">
Explore the Citations cookbook recipe for how to ensure accuracy and explainability of information.
</Card>
</CardGroup>
---
## About/about-claude-use-case-guides-legal-summarization-0b045c60ad.md
# Legal summarization
This guide walks through how to leverage Claude's advanced natural language processing capabilities to efficiently summarize legal documents, extracting key information and expediting legal research. With Claude, you can streamline the review of contracts, litigation prep, and regulatory work, saving time and ensuring accuracy in your legal processes.
---
> Visit the [summarization cookbook](https://platform.claude.com/cookbook/capabilities-summarization-guide) to see an example legal summarization implementation using Claude.
## Before building with Claude
### Decide whether to use Claude for legal summarization
Here are some key indicators that you should employ an LLM like Claude to summarize legal documents:
<section title="You want to review a high volume of documents efficiently and affordably">
Large-scale document review can be time-consuming and expensive when done manually. Claude can process and summarize vast amounts of legal documents rapidly, significantly reducing the time and cost associated with document review. This capability is particularly valuable for tasks like due diligence, contract analysis, or litigation discovery, where efficiency is crucial.
</section>
<section title="You require automated extraction of key metadata">
Claude can efficiently extract and categorize important metadata from legal documents, such as parties involved, dates, contract terms, or specific clauses. This automated extraction can help organize information, making it easier to search, analyze, and manage large document sets. It's especially useful for contract management, compliance checks, or creating searchable databases of legal information.
</section>
<section title="You want to generate clear, concise, and standardized summaries">
Claude can generate structured summaries that follow predetermined formats, making it easier for legal professionals to quickly grasp the key points of various documents. These standardized summaries can improve readability, facilitate comparison between documents, and enhance overall comprehension, especially when dealing with complex legal language or technical jargon.
</section>
<section title="You need precise citations for your summaries">
When creating legal summaries, proper attribution and citation are crucial to ensure credibility and compliance with legal standards. Claude can be prompted to include accurate citations for all referenced legal points, making it easier for legal professionals to review and verify the summarized information.
</section>
<section title="You want to streamline and expedite your legal research process">
Claude can assist in legal research by quickly analyzing large volumes of case law, statutes, and legal commentary. It can identify relevant precedents, extract key legal principles, and summarize complex legal arguments. This capability can significantly speed up the research process, allowing legal professionals to focus on higher-level analysis and strategy development.
</section>
### Determine the details you want the summarization to extract
There is no single correct summary for any given document. Without clear direction, it can be difficult for Claude to determine which details to include. To achieve optimal results, identify the specific information you want to include in the summary.
For instance, when summarizing a sublease agreement, you might wish to extract the following key points:
```python
details_to_extract = [
"Parties involved (sublessor, sublessee, and original lessor)",
"Property details (address, description, and permitted use)",
"Term and rent (start date, end date, monthly rent, and security deposit)",
"Responsibilities (utilities, maintenance, and repairs)",
"Consent and notices (landlord's consent, and notice requirements)",
"Special provisions (furniture, parking, and subletting restrictions)",
]
```
### Establish success criteria
Evaluating the quality of summaries is a notoriously challenging task. Unlike many other natural language processing tasks, evaluation of summaries often lacks clear-cut, objective metrics. The process can be highly subjective, with different readers valuing different aspects of a summary. Here are criteria you may wish to consider when assessing how well Claude performs legal summarization.
<section title="Factual correctness">
The summary should accurately represent the facts, legal concepts, and key points in the document.
</section>
<section title="Legal precision">
Terminology and references to statutes, case law, or regulations must be correct and aligned with legal standards.
</section>
<section title="Conciseness">
The summary should condense the legal document to its essential points without losing important details.
</section>
<section title="Consistency">
If summarizing multiple documents, the LLM should maintain a consistent structure and approach to each summary.
</section>
<section title="Readability">
The text should be clear and easy to understand. If the audience is not legal experts, the summarization should not include legal jargon that could confuse the audience.
</section>
<section title="Bias and fairness">
The summary should present an unbiased and fair depiction of the legal arguments and positions.
</section>
See the guide on [establishing success criteria](/docs/en/test-and-evaluate/develop-tests) for more information.
---
## How to summarize legal documents using Claude
### Select the right Claude model
Model accuracy is extremely important when summarizing legal documents. Claude Opus 4.7 is an excellent choice for use cases such as this where high accuracy is required. If the size and quantity of your documents is large such that costs start to become a concern, you can also try using a smaller model like Claude Haiku 4.5.
To help estimate these costs, below is a comparison of the cost to summarize 1,000 sublease agreements using both Sonnet and Haiku:
* **Content size**
* Number of agreements: 1,000
* Characters per agreement: 300,000
* Total characters: 300M
* **Estimated tokens**
* Input tokens: 86M (assuming 1 token per 3.5 characters)
* Output tokens per summary: 350
* Total output tokens: 350,000
* **Claude Opus 4.7 estimated cost**
* Input token cost: 86 MTok * \$5.00/MTok = \$430
* Output token cost: 0.35 MTok * \$25.00/MTok = \$8.75
* Total cost: \$430.00 + \$8.75 = \$438.75
* **Claude Haiku 4.5 estimated cost**
* Input token cost: 86 MTok * \$1.00/MTok = \$86.00
* Output token cost: 0.35 MTok * \$5.00/MTok = \$1.75
* Total cost: \$86.00 + \$1.75 = \$87.75
<Tip>Actual costs may differ from these estimates. These estimates are based on the example highlighted in the section on [prompting](#build-a-strong-prompt).</Tip>
### Transform documents into a format that Claude can process
Before you begin summarizing documents, you need to prepare your data. This involves extracting text from PDFs, cleaning the text, and ensuring it's ready to be processed by Claude.
Here is a demonstration of this process on a sample pdf:
```python nocheck
from io import BytesIO
import re
import pypdf
import requests
def get_llm_text(pdf_file):
reader = pypdf.PdfReader(pdf_file)
text = "\n".join([page.extract_text() for page in reader.pages])
# Remove extra whitespace
text = re.sub(r"\s+", " ", text)
# Remove page numbers
text = re.sub(r"\n\s*\d+\s*\n", "\n", text)
return text
# Create the full URL from the GitHub repository
url = "https://raw.githubusercontent.com/anthropics/anthropic-cookbook/main/skills/summarization/data/Sample Sublease Agreement.pdf"
url = url.replace(" ", "%20")
# Download the PDF file into memory
response = requests.get(url)
# Load the PDF from memory
pdf_file = BytesIO(response.content)
document_text = get_llm_text(pdf_file)
print(document_text[:50000])
```
In this example, you first download a pdf of a sample sublease agreement used in the [summarization cookbook](https://platform.claude.com/cookbook/capabilities-summarization-guide). This agreement was sourced from a publicly available sublease agreement from the [sec.gov website](https://www.sec.gov/Archives/edgar/data/1045425/000119312507044370/dex1032.htm).
The example uses the pypdf library to extract the contents of the pdf and convert it to text. The text data is then cleaned by removing extra whitespace and page numbers.
### Build a strong prompt
Claude can adapt to various summarization styles. You can change the details of the prompt to guide Claude to be more or less verbose, include more or less technical terminology, or provide a higher or lower level summary of the context at hand.
Here’s an example of how to create a prompt that ensures the generated summaries follow a consistent structure when analyzing sublease agreements:
```python Python nocheck hidelines={1..2}
import anthropic
# Initialize the Anthropic client
client = anthropic.Anthropic()
def summarize_document(
text, details_to_extract, model="claude-opus-4-7", max_tokens=1000
):
# Format the details to extract to be placed within the prompt's context
details_to_extract_str = "\n".join(details_to_extract)
# Prompt the model to summarize the sublease agreement
prompt = f"""Summarize the following sublease agreement. Focus on these key aspects:
{details_to_extract_str}
Provide the summary in bullet points nested within the XML header for each section. For example:
<parties involved>
- Sublessor: [Name]
// Add more details as needed
</parties involved>
If any information is not explicitly stated in the document, note it as "Not specified". Do not preamble.
Sublease agreement text:
{text}
"""
response = client.messages.create(
model=model,
max_tokens=max_tokens,
system="You are a legal analyst specializing in real estate law, known for highly accurate and detailed summaries of sublease agreements.",
messages=[
{"role": "user", "content": prompt},
],
)
return response.content[0].text
sublease_summary = summarize_document(document_text, details_to_extract)
print(sublease_summary)
```
This code implements a `summarize_document` function that uses Claude to summarize the contents of a sublease agreement. The function accepts a text string and a list of details to extract as inputs. In this example, the code calls the function with the `document_text` and `details_to_extract` variables that were defined in the previous code snippets.
Within the function, a prompt is generated for Claude, including the document to be summarized, the details to extract, and specific instructions for summarizing the document. The prompt instructs Claude to respond with a summary of each detail to extract nested within XML headers.
Because the code outputs each section of the summary within tags, each section can easily be parsed out as a post-processing step. This approach enables structured summaries that can be adapted for your use case, so that each summary follows the same pattern.
### Evaluate your prompt
Prompting often requires testing and optimization for it to be production ready. To determine the readiness of your solution, evaluate the quality of your summaries using a systematic process combining quantitative and qualitative methods. Creating a [strong empirical evaluation](/docs/en/test-and-evaluate/develop-tests#building-evals-and-test-cases) based on your defined success criteria allows you to optimize your prompts. Here are some metrics you may wish to include within your empirical evaluation:
<section title="ROUGE scores">
This measures the overlap between the generated summary and an expert-created reference summary. This metric primarily focuses on recall and is useful for evaluating content coverage.
</section>
<section title="BLEU scores">
While originally developed for machine translation, this metric can be adapted for summarization tasks. BLEU scores measure the precision of n-gram matches between the generated summary and reference summaries. A higher score indicates that the generated summary contains similar phrases and terminology to the reference summary.
</section>
<section title="Contextual embedding similarity">
This metric involves creating vector representations (embeddings) of both the generated and reference summaries. The similarity between these embeddings is then calculated, often using cosine similarity. Higher similarity scores indicate that the generated summary captures the semantic meaning and context of the reference summary, even if the exact wording differs.
</section>
<section title="LLM-based grading">
This method involves using an LLM such as Claude to evaluate the quality of generated summaries against a scoring rubric. The rubric can be tailored to your specific needs, assessing key factors like accuracy, completeness, and coherence. For guidance on implementing LLM-based grading, view these [tips](/docs/en/test-and-evaluate/develop-tests#tips-for-llm-based-grading).
</section>
<section title="Human evaluation">
In addition to creating the reference summaries, legal experts can also evaluate the quality of the generated summaries. While this is expensive and time-consuming at scale, this is often done on a few summaries as a sanity check before deploying to production.
</section>
### Deploy your prompt
Here are some additional considerations to keep in mind as you deploy your solution to production.
1. **Ensure no liability:** Understand the legal implications of errors in the summaries, which could lead to legal liability for your organization or clients. Provide disclaimers or legal notices clarifying that the summaries are generated by AI and should be reviewed by legal professionals.
2. **Handle diverse document types:** This guide discusses how to extract text from PDFs. In the real-world, documents may come in a variety of formats (PDFs, Word documents, text files, etc.). Ensure your data extraction pipeline can convert all of the file formats you expect to receive.
3. **Parallelize API calls to Claude:** Long documents with a large number of tokens may require up to a minute for Claude to generate a summary. For large document collections, you may want to send API calls to Claude in parallel so that the summaries can be completed in a reasonable timeframe. Refer to Anthropic’s [rate limits](/docs/en/api/rate-limits#rate-limits) to determine the maximum amount of API calls that can be performed in parallel.
---
## Improve performance
In complex scenarios, it may be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](/docs/en/build-with-claude/prompt-engineering/overview). Here are some advanced strategies:
### Perform meta-summarization to summarize long documents
Legal summarization often involves handling long documents or many related documents at once, such that you surpass Claude’s context window. You can use a chunking method known as meta-summarization in order to handle this use case. This technique involves breaking down documents into smaller, manageable chunks and then processing each chunk separately. You can then combine the summaries of each chunk to create a meta-summary of the entire document.
Here's an example of how to perform meta-summarization:
```python Python nocheck hidelines={1..2}
import anthropic
# Initialize the Anthropic client
client = anthropic.Anthropic()
def chunk_text(text, chunk_size=20000):
return [text[i : i + chunk_size] for i in range(0, len(text), chunk_size)]
def summarize_long_document(
text, details_to_extract, model="claude-opus-4-7", max_tokens=1000
):
# Format the details to extract to be placed within the prompt's context
details_to_extract_str = "\n".join(details_to_extract)
# Iterate over chunks and summarize each one
chunk_summaries = [
summarize_document(
chunk, details_to_extract, model=model, max_tokens=max_tokens
)
for chunk in chunk_text(text)
]
final_summary_prompt = f"""
You are looking at the chunked summaries of multiple documents that are all related.
Combine the following summaries of the document from different truthful sources into a coherent overall summary:
<chunked_summaries>
{"".join(chunk_summaries)}
</chunked_summaries>
Focus on these key aspects:
{details_to_extract_str})
Provide the summary in bullet points nested within the XML header for each section. For example:
<parties involved>
- Sublessor: [Name]
// Add more details as needed
</parties involved>
If any information is not explicitly stated in the document, note it as "Not specified". Do not preamble.
"""
response = client.messages.create(
model=model,
max_tokens=max_tokens,
system="You are a legal expert that summarizes notes on one document.",
messages=[
{"role": "user", "content": final_summary_prompt},
],
)
return response.content[0].text
long_summary = summarize_long_document(document_text, details_to_extract)
print(long_summary)
```
The `summarize_long_document` function builds upon the earlier `summarize_document` function by splitting the document into smaller chunks and summarizing each chunk individually.
The code achieves this by applying the `summarize_document` function to each chunk of 20,000 characters within the original document. The individual summaries are then combined, and a final summary is created from these chunk summaries.
Note that the `summarize_long_document` function isn't strictly necessary for the example pdf, as the entire document fits within Claude's context window. However, it becomes essential for documents exceeding Claude's context window or when summarizing multiple related documents together. Regardless, this meta-summarization technique often captures additional important details in the final summary that were missed in the earlier single-summary approach.
### Use summary indexed documents to explore a large collection of documents
Searching a collection of documents with an LLM usually involves retrieval-augmented generation (RAG). However, in scenarios involving large documents or when precise information retrieval is crucial, a basic RAG approach may be insufficient. Summary indexed documents is an advanced RAG approach that provides a more efficient way of ranking documents for retrieval, using less context than traditional RAG methods. In this approach, you first use Claude to generate a concise summary for each document in your corpus, and then use Claude to rank the relevance of each summary to the query being asked. For further details on this approach, including a code-based example, check out the summary indexed documents section in the [summarization cookbook](https://platform.claude.com/cookbook/capabilities-summarization-guide).
### Fine-tune Claude to learn from your dataset
Another advanced technique to improve Claude's ability to generate summaries is fine-tuning. Fine-tuning involves training Claude on a custom dataset that specifically aligns with your legal summarization needs, ensuring that Claude adapts to your use case. Here’s an overview on how to perform fine-tuning:
1. **Identify errors:** Start by collecting instances where Claude’s summaries fall short - this could include missing critical legal details, misunderstanding context, or using inappropriate legal terminology.
2. **Curate a dataset:** Once you've identified these issues, compile a dataset of these problematic examples. This dataset should include the original legal documents alongside your corrected summaries, ensuring that Claude learns the desired behavior.
3. **Perform fine-tuning:** Fine-tuning involves retraining the model on your curated dataset to adjust its weights and parameters. This retraining helps Claude better understand the specific requirements of your legal domain, improving its ability to summarize documents according to your standards.
4. **Iterative improvement:** Fine-tuning is not a one-time process. As Claude continues to generate summaries, you can iteratively add new examples where it has underperformed, further refining its capabilities. Over time, this continuous feedback loop will result in a model that is highly specialized for your legal summarization tasks.
<Tip>Fine-tuning is currently only available via Amazon Bedrock. Additional details are available in the [AWS launch blog](https://aws.amazon.com/blogs/machine-learning/fine-tune-anthropics-claude-3-haiku-in-amazon-bedrock-to-boost-model-accuracy-and-quality/).</Tip>
<CardGroup cols={2}>
<Card title="Summarization cookbook" icon="link" href="https://platform.claude.com/cookbook/capabilities-summarization-guide">
View a fully implemented code-based example of how to use Claude to summarize contracts.
</Card>
<Card title="Citations cookbook" icon="link" href="https://platform.claude.com/cookbook/misc-using-citations">
Explore the Citations cookbook recipe for guidance on how to ensure accuracy and explainability of information.
</Card>
</CardGroup>
---
## About/about-claude-use-case-guides-overview-43239e353a.md
# Guides to common use cases
---
Claude is designed to excel in a variety of tasks. Explore these in-depth production guides to learn how to build common use cases with Claude.
<CardGroup cols={2}>
<Card title="Ticket routing" icon="headset" href="/docs/en/about-claude/use-case-guides/ticket-routing">
Best practices for using Claude to classify and route customer support tickets at scale.
</Card>
<Card title="Customer support agent" icon="robot" href="/docs/en/about-claude/use-case-guides/customer-support-chat">
Build intelligent, context-aware chatbots with Claude to enhance customer support interactions.
</Card>
<Card title="Content moderation" icon="verified" href="/docs/en/about-claude/use-case-guides/content-moderation">
Techniques and best practices for using Claude to perform content filtering and general content moderation.
</Card>
<Card title="Legal summarization" icon="book" href="/docs/en/about-claude/use-case-guides/legal-summarization">
Summarize legal documents using Claude to extract key information and expedite research.
</Card>
</CardGroup>
---
## About/about-claude-use-case-guides-ticket-routing-95526bdf0d.md
# Ticket routing
This guide walks through how to harness Claude's advanced natural language understanding capabilities to classify customer support tickets at scale based on customer intent, urgency, prioritization, customer profile, and more.
---
## Define whether to use Claude for ticket routing
Here are some key indicators that you should use an LLM like Claude instead of traditional ML approaches for your classification task:
<section title="You have limited labeled training data available">
Traditional ML processes require massive labeled datasets. Claude's pre-trained model can effectively classify tickets with just a few dozen labeled examples, significantly reducing data preparation time and costs.
</section>
<section title="Your classification categories are likely to change or evolve over time">
Once a traditional ML approach has been established, changing it is a laborious and data-intensive undertaking. On the other hand, as your product or customer needs evolve, Claude can easily adapt to changes in class definitions or new classes without extensive relabeling of training data.
</section>
<section title="You need to handle complex, unstructured text inputs">
Traditional ML models often struggle with unstructured data and require extensive feature engineering. Claude's advanced language understanding allows for accurate classification based on content and context, rather than relying on strict ontological structures.
</section>
<section title="Your classification rules are based on semantic understanding">
Traditional ML approaches often rely on bag-of-words models or simple pattern matching. Claude excels at understanding and applying underlying rules when classes are defined by conditions rather than examples.
</section>
<section title="You require interpretable reasoning for classification decisions">
Many traditional ML models provide little insight into their decision-making process. Claude can provide human-readable explanations for its classification decisions, building trust in the automation system and facilitating easy adaptation if needed.
</section>
<section title="You want to handle edge cases and ambiguous tickets more effectively">
Traditional ML systems often struggle with outliers and ambiguous inputs, frequently misclassifying them or defaulting to a catch-all category. Claude's natural language processing capabilities allow it to better interpret context and nuance in support tickets, potentially reducing the number of misrouted or unclassified tickets that require manual intervention.
</section>
<section title="You need multilingual support without maintaining separate models">
Traditional ML approaches typically require separate models or extensive translation processes for each supported language. Claude's multilingual capabilities allow it to classify tickets in various languages without the need for separate models or extensive translation processes, streamlining support for global customer bases.
</section>
***
## Build and deploy your LLM support workflow
### Understand your current support approach
Before diving into automation, it's crucial to understand your existing ticketing system. Start by investigating how your support team currently handles ticket routing.
Consider questions like:
* What criteria are used to determine what SLA/service offering is applied?
* Is ticket routing used to determine which tier of support or product specialist a ticket goes to?
* Are there any automated rules or workflows already in place? In what cases do they fail?
* How are edge cases or ambiguous tickets handled?
* How does the team prioritize tickets?
The more you know about how humans handle certain cases, the better you can work with Claude to do the task.
### Define user intent categories
A well-defined list of user intent categories is crucial for accurate support ticket classification with Claude. Claude’s ability to route tickets effectively within your system is directly proportional to how well-defined your system’s categories are.
Here are some example user intent categories and subcategories.
<section title="Technical issue">
* Hardware problem
* Software bug
* Compatibility issue
* Performance problem
</section>
<section title="Account management">
* Password reset
* Account access issues
* Billing inquiries
* Subscription changes
</section>
<section title="Product information">
* Feature inquiries
* Product compatibility questions
* Pricing information
* Availability inquiries
</section>
<section title="User guidance">
* How-to questions
* Feature usage assistance
* Best practices advice
* Troubleshooting guidance
</section>
<section title="Feedback">
* Bug reports
* Feature requests
* General feedback or suggestions
* Complaints
</section>
<section title="Order-related">
* Order status inquiries
* Shipping information
* Returns and exchanges
* Order modifications
</section>
<section title="Service request">
* Installation assistance
* Upgrade requests
* Maintenance scheduling
* Service cancellation
</section>
<section title="Security concerns">
* Data privacy inquiries
* Suspicious activity reports
* Security feature assistance
</section>
<section title="Compliance and legal">
* Regulatory compliance questions
* Terms of service inquiries
* Legal documentation requests
</section>
<section title="Emergency support">
* Critical system failures
* Urgent security issues
* Time-sensitive problems
</section>
<section title="Training and education">
* Product training requests
* Documentation inquiries
* Webinar or workshop information
</section>
<section title="Integration and API">
* Integration assistance
* API usage questions
* Third-party compatibility inquiries
</section>
In addition to intent, ticket routing and prioritization may also be influenced by other factors such as urgency, customer type, SLAs, or language. Be sure to consider other routing criteria when building your automated routing system.
### Establish success criteria
Work with your support team to [define clear success criteria](/docs/en/test-and-evaluate/develop-tests) with measurable benchmarks, thresholds, and goals.
Here are some standard criteria and benchmarks when using LLMs for support ticket routing:
<section title="Classification consistency">
This metric assesses how consistently Claude classifies similar tickets over time. It's crucial for maintaining routing reliability. Measure this by periodically testing the model with a set of standardized inputs and aiming for a consistency rate of 95% or higher.
</section>
<section title="Adaptation speed">
This measures how quickly Claude can adapt to new categories or changing ticket patterns. Test this by introducing new ticket types and measuring the time it takes for the model to achieve satisfactory accuracy (e.g., >90%) on these new categories. Aim for adaptation within 50-100 sample tickets.
</section>
<section title="Multilingual handling">
This assesses Claude's ability to accurately route tickets in multiple languages. Measure the routing accuracy across different languages, aiming for no more than a 5-10% drop in accuracy for non-primary languages.
</section>
<section title="Edge case handling">
This evaluates Claude's performance on unusual or complex tickets. Create a test set of edge cases and measure the routing accuracy, aiming for at least 80% accuracy on these challenging inputs.
</section>
<section title="Bias mitigation">
This measures Claude's fairness in routing across different customer demographics. Regularly audit routing decisions for potential biases, aiming for consistent routing accuracy (within 2-3%) across all customer groups.
</section>
<section title="Prompt efficiency">
In situations where minimizing token count is crucial, this criteria assesses how well Claude performs with minimal context. Measure routing accuracy with varying amounts of context provided, aiming for 90%+ accuracy with just the ticket title and a brief description.
</section>
<section title="Explainability score">
This evaluates the quality and relevance of Claude's explanations for its routing decisions. Human raters can score explanations on a scale (e.g., 1-5), with the goal of achieving an average score of 4 or higher.
</section>
Here are some common success criteria that may be useful regardless of whether an LLM is used:
<section title="Routing accuracy">
Routing accuracy measures how often tickets are correctly assigned to the appropriate team or individual on the first try. This is typically measured as a percentage of correctly routed tickets out of total tickets. Industry benchmarks often aim for 90-95% accuracy, though this can vary based on the complexity of the support structure.
</section>
<section title="Time-to-assignment">
This metric tracks how quickly tickets are assigned after being submitted. Faster assignment times generally lead to quicker resolutions and improved customer satisfaction. Best-in-class systems often achieve average assignment times of under 5 minutes, with many aiming for near-instantaneous routing (which is possible with LLM implementations).
</section>
<section title="Rerouting rate">
The rerouting rate indicates how often tickets need to be reassigned after initial routing. A lower rate suggests more accurate initial routing. Aim for a rerouting rate below 10%, with top-performing systems achieving rates as low as 5% or less.
</section>
<section title="First-contact resolution rate">
This measures the percentage of tickets resolved during the first interaction with the customer. Higher rates indicate efficient routing and well-prepared support teams. Industry benchmarks typically range from 70-75%, with top performers achieving rates of 80% or higher.
</section>
<section title="Average handling time">
Average handling time measures how long it takes to resolve a ticket from start to finish. Efficient routing can significantly reduce this time. Benchmarks vary widely by industry and complexity, but many organizations aim to keep average handling time under 24 hours for non-critical issues.
</section>
<section title="Customer satisfaction scores">
Often measured through post-interaction surveys, these scores reflect overall customer happiness with the support process. Effective routing contributes to higher satisfaction. Aim for CSAT scores of 90% or higher, with top performers often achieving 95%+ satisfaction rates.
</section>
<section title="Escalation rate">
This measures how often tickets need to be escalated to higher tiers of support. Lower escalation rates often indicate more accurate initial routing. Strive for an escalation rate below 20%, with best-in-class systems achieving rates of 10% or less.
</section>
<section title="Agent productivity">
This metric looks at how many tickets agents can handle effectively after implementing the routing solution. Improved routing should increase productivity. Measure this by tracking tickets resolved per agent per day or hour, aiming for a 10-20% improvement after implementing a new routing system.
</section>
<section title="Self-service deflection rate">
This measures the percentage of potential tickets resolved through self-service options before entering the routing system. Higher rates indicate effective pre-routing triage. Aim for a deflection rate of 20-30%, with top performers achieving rates of 40% or higher.
</section>
<section title="Cost per ticket">
This metric calculates the average cost to resolve each support ticket. Efficient routing should help reduce this cost over time. While benchmarks vary widely, many organizations aim to reduce cost per ticket by 10-15% after implementing an improved routing system.
</section>
### Choose the right Claude model
The choice of model depends on the trade-offs between cost, accuracy, and response time.
Many customers have found `claude-haiku-4-5-20251001` an ideal model for ticket routing, as it is the fastest and most cost-effective model in the Claude 4 family while still delivering excellent results. If your classification problem requires deep subject matter expertise or a large volume of intent categories complex reasoning, you may opt for the [larger Sonnet model](/docs/en/about-claude/models).
### Build a strong prompt
Ticket routing is a type of classification task. Claude analyzes the content of a support ticket and classifies it into predefined categories based on the issue type, urgency, required expertise, or other relevant factors.
Let’s write a ticket classification prompt. Our initial prompt should contain the contents of the user request and return both the reasoning and the intent.
<Tip>
Try the [prompt generator](/docs/en/prompt-generator) on the [Claude Console](/login) to have Claude write a first draft for you.
</Tip>
Here's an example ticket routing classification prompt:
```python nocheck
def classify_support_request(ticket_contents):
# Define the prompt for the classification task
classification_prompt = f"""You will be acting as a customer support ticket classification system. Your task is to analyze customer support requests and output the appropriate classification intent for each request, along with your reasoning.
Here is the customer support request you need to classify:
<request>{ticket_contents}</request>
Please carefully analyze the above request to determine the customer's core intent and needs. Consider what the customer is asking for has concerns about.
First, write out your reasoning and analysis of how to classify this request inside <reasoning> tags.
Then, output the appropriate classification label for the request inside a <intent> tag. The valid intents are:
<intents>
<intent>Support, Feedback, Complaint</intent>
<intent>Order Tracking</intent>
<intent>Refund/Exchange</intent>
</intents>
A request may have ONLY ONE applicable intent. Only include the intent that is most applicable to the request.
As an example, consider the following request:
<request>Hello! I had high-speed fiber internet installed on Saturday and my installer, Kevin, was absolutely fantastic! Where can I send my positive review? Thanks for your help!</request>
Here is an example of how your output should be formatted (for the above example request):
<reasoning>The user seeks information in order to leave positive feedback.</reasoning>
<intent>Support, Feedback, Complaint</intent>
Here are a few more examples:
<examples>
<example 2>
Example 2 Input:
<request>I wanted to write and personally thank you for the compassion you showed towards my family during my father's funeral this past weekend. Your staff was so considerate and helpful throughout this whole process; it really took a load off our shoulders. The visitation brochures were beautiful. We'll never forget the kindness you showed us and we are so appreciative of how smoothly the proceedings went. Thank you, again, Amarantha Hill on behalf of the Hill Family.</request>
Example 2 Output:
<reasoning>User leaves a positive review of their experience.</reasoning>
<intent>Support, Feedback, Complaint</intent>
</example 2>
<example 3>
...
</example 8>
<example 9>
Example 9 Input:
<request>Your website keeps sending ad-popups that block the entire screen. It took me twenty minutes just to finally find the phone number to call and complain. How can I possibly access my account information with all of these popups? Can you access my account for me, since your website is broken? I need to know what the address is on file.</request>
Example 9 Output:
<reasoning>The user requests help accessing their web account information.</reasoning>
<intent>Support, Feedback, Complaint</intent>
</example 9>
Remember to always include your classification reasoning before your actual intent output. The reasoning should be enclosed in <reasoning> tags and the intent in <intent> tags. Return only the reasoning and the intent.
"""
```
Let's break down the key components of this prompt:
* We use Python f-strings to create the prompt template, allowing the `ticket_contents` to be inserted into the `<request>` tags.
* We give Claude a clearly defined role as a classification system that carefully analyzes the ticket content to determine the customer's core intent and needs.
* We instruct Claude on proper output formatting, in this case to provide its reasoning and analysis inside `<reasoning>` tags, followed by the appropriate classification label inside `<intent>` tags.
* We specify the valid intent categories: "Support, Feedback, Complaint", "Order Tracking", and "Refund/Exchange".
* We include a few examples (a.k.a. few-shot prompting) to illustrate how the output should be formatted, which improves accuracy and consistency.
The reason we want to have Claude split its response into various XML tag sections is so that we can use regular expressions to separately extract the reasoning and intent from the output. This allows us to create targeted next steps in the ticket routing workflow, such as using only the intent to decide which person to route the ticket to.
### Deploy your prompt
It’s hard to know how well your prompt works without deploying it in a test production setting and [running evaluations](/docs/en/test-and-evaluate/develop-tests).
Let’s build the deployment structure. Start by defining the method signature for wrapping our call to Claude. We'll take the method we’ve already begun to write, which has `ticket_contents` as input, and now return a tuple of `reasoning` and `intent` as output. If you have an existing automation using traditional ML, you'll want to follow that method signature instead.
```python Python nocheck hidelines={1}
import anthropic
import re
# Create an instance of the Claude API client
client = anthropic.Anthropic()
# Set the default model
DEFAULT_MODEL = "claude-haiku-4-5-20251001"
def classify_support_request(ticket_contents):
# Define the prompt for the classification task
classification_prompt = f"""You will be acting as a customer support ticket classification system.
...
... The reasoning should be enclosed in <reasoning> tags and the intent in <intent> tags. Return only the reasoning and the intent.
"""
# Send the prompt to the API to classify the support request.
message = client.messages.create(
model=DEFAULT_MODEL,
max_tokens=500,
temperature=0,
messages=[{"role": "user", "content": classification_prompt}],
stream=False,
)
reasoning_and_intent = message.content[0].text
# Use Python's regular expressions library to extract `reasoning`.
reasoning_match = re.search(
r"<reasoning>(.*?)</reasoning>", reasoning_and_intent, re.DOTALL
)
reasoning = reasoning_match.group(1).strip() if reasoning_match else ""
# Similarly, also extract the `intent`.
intent_match = re.search(r"<intent>(.*?)</intent>", reasoning_and_intent, re.DOTALL)
intent = intent_match.group(1).strip() if intent_match else ""
return reasoning, intent
```
This code:
* Creates a client instance using your API key.
* Defines a `classify_support_request` function that takes a `ticket_contents` string.
* Sends the `ticket_contents` to Claude for classification using the `classification_prompt`
* Returns the model's `reasoning` and `intent` extracted from the response.
Since we need to wait for the entire reasoning and intent text to be generated before parsing, we set `stream=False` (the default).
***
## Evaluate your prompt
Prompting often requires testing and optimization for it to be production ready. To determine the readiness of your solution, evaluate performance based on the success criteria and thresholds you established earlier.
To run your evaluation, you need test cases to run it on. The rest of this guide assumes you have already [developed your test cases](/docs/en/test-and-evaluate/develop-tests).
### Build an evaluation function
Our example evaluation for this guide measures Claude’s performance along three key metrics:
* Accuracy
* Cost per classification
You may need to assess Claude on other axes depending on what factors that are important to you.
To assess this, we first have to modify the script we wrote and add a function to compare the predicted intent with the actual intent and calculate the percentage of correct predictions. We also have to add in cost calculation and time measurement functionality.
```python Python nocheck hidelines={1}
import anthropic
import re
# Create an instance of the Claude API client
client = anthropic.Anthropic()
# Set the default model
DEFAULT_MODEL = "claude-haiku-4-5-20251001"
def classify_support_request(request, actual_intent):
# Define the prompt for the classification task
classification_prompt = f"""You will be acting as a customer support ticket classification system.
...
...The reasoning should be enclosed in <reasoning> tags and the intent in <intent> tags. Return only the reasoning and the intent.
"""
message = client.messages.create(
model=DEFAULT_MODEL,
max_tokens=500,
temperature=0,
messages=[{"role": "user", "content": classification_prompt}],
)
usage = message.usage # Get the usage statistics for the API call for how many input and output tokens were used.
reasoning_and_intent = message.content[0].text
# Use Python's regular expressions library to extract `reasoning`.
reasoning_match = re.search(
r"<reasoning>(.*?)</reasoning>", reasoning_and_intent, re.DOTALL
)
reasoning = reasoning_match.group(1).strip() if reasoning_match else ""
# Similarly, also extract the `intent`.
intent_match = re.search(r"<intent>(.*?)</intent>", reasoning_and_intent, re.DOTALL)
intent = intent_match.group(1).strip() if intent_match else ""
# Check if the model's prediction is correct.
correct = actual_intent.strip() == intent.strip()
# Return the reasoning, intent, correct, and usage.
return reasoning, intent, correct, usage
```
Let’s break down the edits we’ve made:
* We added the `actual_intent` from our test cases into the `classify_support_request` method and set up a comparison to assess whether Claude’s intent classification matches our golden intent classification.
* We extracted usage statistics for the API call to calculate cost based on input and output tokens used
### Run your evaluation
A proper evaluation requires clear thresholds and benchmarks to determine what is a good result. The script above gives us the runtime values for accuracy, response time, and cost per classification, but we still would need clearly established thresholds. For example:
* **Accuracy:** 95% (out of 100 tests)
* **Cost per classification:** 50% reduction on average (across 100 tests) from current routing method
Having these thresholds allows you to quickly and easily tell at scale, and with impartial empiricism, what method is best for you and what changes might need to be made to better fit your requirements.
***
## Improve performance
In complex scenarios, it may be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](/docs/en/build-with-claude/prompt-engineering/overview) & [guardrail implementation strategies](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations). Here are some common scenarios:
### Use a taxonomic hierarchy for cases with 20+ intent categories
As the number of classes grows, the number of examples required also expands, potentially making the prompt unwieldy. As an alternative, you can consider implementing a hierarchical classification system using a mixture of classifiers.
1. Organize your intents in a taxonomic tree structure.
2. Create a series of classifiers at every level of the tree, enabling a cascading routing approach.
For example, you might have a top-level classifier that broadly categorizes tickets into "Technical Issues," "Billing Questions," and "General Inquiries." Each of these categories can then have its own sub-classifier to further refine the classification.
* **Pros - greater nuance and accuracy:** You can create different prompts for each parent path, allowing for more targeted and context-specific classification. This can lead to improved accuracy and more nuanced handling of customer requests.
* **Cons - increased latency:** Be advised that multiple classifiers can lead to increased latency, and we recommend implementing this approach with our fastest model, Haiku.
### Use vector databases and similarity search retrieval to handle highly variable tickets
Despite providing examples being the most effective way to improve performance, if support requests are highly variable, it can be hard to include enough examples in a single prompt.
In this scenario, you could employ a vector database to do similarity searches from a dataset of examples and retrieve the most relevant examples for a given query.
This approach, outlined in detail in our [classification recipe](https://platform.claude.com/cookbook/capabilities-classification-guide), has been shown to improve performance from 71% accuracy to 93% accuracy.
### Account specifically for expected edge cases
Here are some scenarios where Claude may misclassify tickets (there may be others that are unique to your situation). In these scenarios,consider providing explicit instructions or examples in the prompt of how Claude should handle the edge case:
<section title="Customers make implicit requests">
Customers often express needs indirectly. For example, "I've been waiting for my package for over two weeks now" may be an indirect request for order status.
* **Solution:** Provide Claude with some real customer examples of these kinds of requests, along with what the underlying intent is. You can get even better results if you include a classification rationale for particularly nuanced ticket intents, so that Claude can better generalize the logic to other tickets.
</section>
<section title="Claude prioritizes emotion over intent">
When customers express dissatisfaction, Claude may prioritize addressing the emotion over solving the underlying problem.
* **Solution:** Provide Claude with directions on when to prioritize customer sentiment or not. It can be something as simple as “Ignore all customer emotions. Focus only on analyzing the intent of the customer’s request and what information the customer might be asking for.”
</section>
<section title="Multiple issues cause issue prioritization confusion">
When customers present multiple issues in a single interaction, Claude may have difficulty identifying the primary concern.
* **Solution:** Clarify the prioritization of intents so thatClaude can better rank the extracted intents and identify the primary concern.
</section>
***
## Integrate Claude into your greater support workflow
Proper integration requires that you make some decisions regarding how your Claude-based ticket routing script fits into the architecture of your greater ticket routing system.There are two ways you could do this:
* **Push-based:** The support ticket system you’re using (e.g. Zendesk) triggers your code by sending a webhook event to your routing service, which then classifies the intent and routes it.
* This approach is more web-scalable, but needs you to expose a public endpoint.
* **Pull-Based:** Your code pulls for the latest tickets based on a given schedule and routes them at pull time.
* This approach is easier to implement but might make unnecessary calls to the support ticket system when the pull frequency is too high or might be overly slow when the pull frequency is too low.
For either of these approaches, you need to wrap your script in a service. The choice of approach depends on what APIs your support ticketing system provides.
***
<CardGroup cols={2}>
<Card title="Classification cookbook" icon="link" href="https://platform.claude.com/cookbook/capabilities-classification-guide">
Visit our classification cookbook for more example code and detailed eval guidance.
</Card>
<Card title="Claude Console" icon="link" href="/dashboard">
Begin building and evaluating your workflow on the Claude Console.
</Card>
</CardGroup>
---
## Admin/api-admin-api-keys-5e6e893cb4.md
# API Keys
## Retrieve
**get** `/v1/organizations/api_keys/{api_key_id}`
Get API Key
### Path Parameters
- `api_key_id: string`
ID of the API key.
### Returns
- `APIKey = object { id, created_at, created_by, 6 more }`
- `id: string`
ID of the API key.
- `created_at: string`
RFC 3339 datetime string indicating when the API Key was created.
- `created_by: object { id, type }`
The ID and type of the actor that created the API key.
- `id: string`
ID of the actor that created the object.
- `type: string`
Type of the actor that created the object.
- `expires_at: string`
RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires.
- `name: string`
Name of the API key.
- `partial_key_hint: string`
Partially redacted hint for the API key.
- `status: "active" or "inactive" or "archived" or "expired"`
Status of the API key.
- `"active"`
- `"inactive"`
- `"archived"`
- `"expired"`
- `type: "api_key"`
Object type.
For API Keys, this is always `"api_key"`.
- `"api_key"`
- `workspace_id: string`
ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace.
### Example
```http
curl https://api.anthropic.com/v1/organizations/api_keys/$API_KEY_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## List
**get** `/v1/organizations/api_keys`
List API Keys
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `created_by_user_id: optional string`
Filter by the ID of the User who created the object.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
- `status: optional "active" or "inactive" or "archived" or "expired"`
Filter by API key status.
- `"active"`
- `"inactive"`
- `"archived"`
- `"expired"`
- `workspace_id: optional string`
Filter by Workspace ID.
### Returns
- `data: array of APIKey`
- `id: string`
ID of the API key.
- `created_at: string`
RFC 3339 datetime string indicating when the API Key was created.
- `created_by: object { id, type }`
The ID and type of the actor that created the API key.
- `id: string`
ID of the actor that created the object.
- `type: string`
Type of the actor that created the object.
- `expires_at: string`
RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires.
- `name: string`
Name of the API key.
- `partial_key_hint: string`
Partially redacted hint for the API key.
- `status: "active" or "inactive" or "archived" or "expired"`
Status of the API key.
- `"active"`
- `"inactive"`
- `"archived"`
- `"expired"`
- `type: "api_key"`
Object type.
For API Keys, this is always `"api_key"`.
- `"api_key"`
- `workspace_id: string`
ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace.
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/api_keys \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Update
**post** `/v1/organizations/api_keys/{api_key_id}`
Update API Key
### Path Parameters
- `api_key_id: string`
ID of the API key.
### Body Parameters
- `name: optional string`
Name of the API key.
- `status: optional "active" or "inactive" or "archived"`
Status of the API key.
- `"active"`
- `"inactive"`
- `"archived"`
### Returns
- `APIKey = object { id, created_at, created_by, 6 more }`
- `id: string`
ID of the API key.
- `created_at: string`
RFC 3339 datetime string indicating when the API Key was created.
- `created_by: object { id, type }`
The ID and type of the actor that created the API key.
- `id: string`
ID of the actor that created the object.
- `type: string`
Type of the actor that created the object.
- `expires_at: string`
RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires.
- `name: string`
Name of the API key.
- `partial_key_hint: string`
Partially redacted hint for the API key.
- `status: "active" or "inactive" or "archived" or "expired"`
Status of the API key.
- `"active"`
- `"inactive"`
- `"archived"`
- `"expired"`
- `type: "api_key"`
Object type.
For API Keys, this is always `"api_key"`.
- `"api_key"`
- `workspace_id: string`
ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace.
### Example
```http
curl https://api.anthropic.com/v1/organizations/api_keys/$API_KEY_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{}'
```
---
## Admin/api-admin-api-keys-list-46c6242fe5.md
## List
**get** `/v1/organizations/api_keys`
List API Keys
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `created_by_user_id: optional string`
Filter by the ID of the User who created the object.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
- `status: optional "active" or "inactive" or "archived" or "expired"`
Filter by API key status.
- `"active"`
- `"inactive"`
- `"archived"`
- `"expired"`
- `workspace_id: optional string`
Filter by Workspace ID.
### Returns
- `data: array of APIKey`
- `id: string`
ID of the API key.
- `created_at: string`
RFC 3339 datetime string indicating when the API Key was created.
- `created_by: object { id, type }`
The ID and type of the actor that created the API key.
- `id: string`
ID of the actor that created the object.
- `type: string`
Type of the actor that created the object.
- `expires_at: string`
RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires.
- `name: string`
Name of the API key.
- `partial_key_hint: string`
Partially redacted hint for the API key.
- `status: "active" or "inactive" or "archived" or "expired"`
Status of the API key.
- `"active"`
- `"inactive"`
- `"archived"`
- `"expired"`
- `type: "api_key"`
Object type.
For API Keys, this is always `"api_key"`.
- `"api_key"`
- `workspace_id: string`
ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace.
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/api_keys \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-api-keys-retrieve-1be8681752.md
## Retrieve
**get** `/v1/organizations/api_keys/{api_key_id}`
Get API Key
### Path Parameters
- `api_key_id: string`
ID of the API key.
### Returns
- `APIKey = object { id, created_at, created_by, 6 more }`
- `id: string`
ID of the API key.
- `created_at: string`
RFC 3339 datetime string indicating when the API Key was created.
- `created_by: object { id, type }`
The ID and type of the actor that created the API key.
- `id: string`
ID of the actor that created the object.
- `type: string`
Type of the actor that created the object.
- `expires_at: string`
RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires.
- `name: string`
Name of the API key.
- `partial_key_hint: string`
Partially redacted hint for the API key.
- `status: "active" or "inactive" or "archived" or "expired"`
Status of the API key.
- `"active"`
- `"inactive"`
- `"archived"`
- `"expired"`
- `type: "api_key"`
Object type.
For API Keys, this is always `"api_key"`.
- `"api_key"`
- `workspace_id: string`
ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace.
### Example
```http
curl https://api.anthropic.com/v1/organizations/api_keys/$API_KEY_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-api-keys-update-f2523628a4.md
## Update
**post** `/v1/organizations/api_keys/{api_key_id}`
Update API Key
### Path Parameters
- `api_key_id: string`
ID of the API key.
### Body Parameters
- `name: optional string`
Name of the API key.
- `status: optional "active" or "inactive" or "archived"`
Status of the API key.
- `"active"`
- `"inactive"`
- `"archived"`
### Returns
- `APIKey = object { id, created_at, created_by, 6 more }`
- `id: string`
ID of the API key.
- `created_at: string`
RFC 3339 datetime string indicating when the API Key was created.
- `created_by: object { id, type }`
The ID and type of the actor that created the API key.
- `id: string`
ID of the actor that created the object.
- `type: string`
Type of the actor that created the object.
- `expires_at: string`
RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires.
- `name: string`
Name of the API key.
- `partial_key_hint: string`
Partially redacted hint for the API key.
- `status: "active" or "inactive" or "archived" or "expired"`
Status of the API key.
- `"active"`
- `"inactive"`
- `"archived"`
- `"expired"`
- `type: "api_key"`
Object type.
For API Keys, this is always `"api_key"`.
- `"api_key"`
- `workspace_id: string`
ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace.
### Example
```http
curl https://api.anthropic.com/v1/organizations/api_keys/$API_KEY_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{}'
```
---
## Admin/api-admin-cost-report-ec1d585117.md
# Cost Report
## Retrieve
**get** `/v1/organizations/cost_report`
Get Cost Report
### Query Parameters
- `starting_at: string`
Time buckets that start on or after this RFC 3339 timestamp will be returned.
Each time bucket will be snapped to the start of the minute/hour/day in UTC.
- `bucket_width: optional "1d"`
Time granularity of the response data.
- `"1d"`
- `ending_at: optional string`
Time buckets that end before this RFC 3339 timestamp will be returned.
- `group_by: optional array of "workspace_id" or "description"`
Group by any subset of the available options.
- `"workspace_id"`
- `"description"`
- `limit: optional number`
Maximum number of time buckets to return in the response.
- `page: optional string`
Optionally set to the `next_page` token from the previous response.
### Header Parameters
- `"anthropic-beta": optional array of string`
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
### Returns
- `CostReport = object { data, has_more, next_page }`
- `data: array of object { ending_at, results, starting_at }`
- `ending_at: string`
End of the time bucket (exclusive) in RFC 3339 format.
- `results: array of object { amount, context_window, cost_type, 7 more }`
List of cost items for this time bucket. There may be multiple items if one or more `group_by[]` parameters are specified.
- `amount: string`
Cost amount in lowest currency units (e.g. cents) as a decimal string. For example, `"123.45"` in `"USD"` represents `$1.23`.
- `context_window: "0-200k" or "200k-1M"`
Input context window used. `null` if not grouping by description or for non-token costs.
- `"0-200k"`
- `"200k-1M"`
- `cost_type: "tokens" or "web_search" or "code_execution" or "session_usage"`
Type of cost. `null` if not grouping by description.
- `"tokens"`
- `"web_search"`
- `"code_execution"`
- `"session_usage"`
- `currency: string`
Currency code for the cost amount. Currently always `"USD"`.
- `description: string`
Description of the cost item. `null` if not grouping by description.
- `inference_geo: string`
Inference geo used matching requests' `inference_geo` parameter if set, otherwise the workspace's `default_inference_geo`.
For models that do not support specifying `inference_geo` the value is `"not_available"`. Always `null` if not grouping by inference geo.
- `model: string`
Model name used. `null` if not grouping by description or for non-token costs.
- `service_tier: "standard" or "batch"`
Service tier used. `null` if not grouping by description or for non-token costs.
- `"standard"`
- `"batch"`
- `token_type: "uncached_input_tokens" or "output_tokens" or "cache_read_input_tokens" or 2 more`
Type of token. `null` if not grouping by description or for non-token costs.
- `"uncached_input_tokens"`
- `"output_tokens"`
- `"cache_read_input_tokens"`
- `"cache_creation.ephemeral_1h_input_tokens"`
- `"cache_creation.ephemeral_5m_input_tokens"`
- `workspace_id: string`
ID of the Workspace this cost is associated with. `null` if not grouping by workspace or for the default workspace.
- `starting_at: string`
Start of the time bucket (inclusive) in RFC 3339 format.
- `has_more: boolean`
Indicates if there are more results.
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/cost_report \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Cost Report
- `CostReport = object { data, has_more, next_page }`
- `data: array of object { ending_at, results, starting_at }`
- `ending_at: string`
End of the time bucket (exclusive) in RFC 3339 format.
- `results: array of object { amount, context_window, cost_type, 7 more }`
List of cost items for this time bucket. There may be multiple items if one or more `group_by[]` parameters are specified.
- `amount: string`
Cost amount in lowest currency units (e.g. cents) as a decimal string. For example, `"123.45"` in `"USD"` represents `$1.23`.
- `context_window: "0-200k" or "200k-1M"`
Input context window used. `null` if not grouping by description or for non-token costs.
- `"0-200k"`
- `"200k-1M"`
- `cost_type: "tokens" or "web_search" or "code_execution" or "session_usage"`
Type of cost. `null` if not grouping by description.
- `"tokens"`
- `"web_search"`
- `"code_execution"`
- `"session_usage"`
- `currency: string`
Currency code for the cost amount. Currently always `"USD"`.
- `description: string`
Description of the cost item. `null` if not grouping by description.
- `inference_geo: string`
Inference geo used matching requests' `inference_geo` parameter if set, otherwise the workspace's `default_inference_geo`.
For models that do not support specifying `inference_geo` the value is `"not_available"`. Always `null` if not grouping by inference geo.
- `model: string`
Model name used. `null` if not grouping by description or for non-token costs.
- `service_tier: "standard" or "batch"`
Service tier used. `null` if not grouping by description or for non-token costs.
- `"standard"`
- `"batch"`
- `token_type: "uncached_input_tokens" or "output_tokens" or "cache_read_input_tokens" or 2 more`
Type of token. `null` if not grouping by description or for non-token costs.
- `"uncached_input_tokens"`
- `"output_tokens"`
- `"cache_read_input_tokens"`
- `"cache_creation.ephemeral_1h_input_tokens"`
- `"cache_creation.ephemeral_5m_input_tokens"`
- `workspace_id: string`
ID of the Workspace this cost is associated with. `null` if not grouping by workspace or for the default workspace.
- `starting_at: string`
Start of the time bucket (inclusive) in RFC 3339 format.
- `has_more: boolean`
Indicates if there are more results.
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
---
## Admin/api-admin-cost-report-retrieve-86a0323049.md
## Retrieve
**get** `/v1/organizations/cost_report`
Get Cost Report
### Query Parameters
- `starting_at: string`
Time buckets that start on or after this RFC 3339 timestamp will be returned.
Each time bucket will be snapped to the start of the minute/hour/day in UTC.
- `bucket_width: optional "1d"`
Time granularity of the response data.
- `"1d"`
- `ending_at: optional string`
Time buckets that end before this RFC 3339 timestamp will be returned.
- `group_by: optional array of "workspace_id" or "description"`
Group by any subset of the available options.
- `"workspace_id"`
- `"description"`
- `limit: optional number`
Maximum number of time buckets to return in the response.
- `page: optional string`
Optionally set to the `next_page` token from the previous response.
### Header Parameters
- `"anthropic-beta": optional array of string`
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
### Returns
- `CostReport = object { data, has_more, next_page }`
- `data: array of object { ending_at, results, starting_at }`
- `ending_at: string`
End of the time bucket (exclusive) in RFC 3339 format.
- `results: array of object { amount, context_window, cost_type, 7 more }`
List of cost items for this time bucket. There may be multiple items if one or more `group_by[]` parameters are specified.
- `amount: string`
Cost amount in lowest currency units (e.g. cents) as a decimal string. For example, `"123.45"` in `"USD"` represents `$1.23`.
- `context_window: "0-200k" or "200k-1M"`
Input context window used. `null` if not grouping by description or for non-token costs.
- `"0-200k"`
- `"200k-1M"`
- `cost_type: "tokens" or "web_search" or "code_execution" or "session_usage"`
Type of cost. `null` if not grouping by description.
- `"tokens"`
- `"web_search"`
- `"code_execution"`
- `"session_usage"`
- `currency: string`
Currency code for the cost amount. Currently always `"USD"`.
- `description: string`
Description of the cost item. `null` if not grouping by description.
- `inference_geo: string`
Inference geo used matching requests' `inference_geo` parameter if set, otherwise the workspace's `default_inference_geo`.
For models that do not support specifying `inference_geo` the value is `"not_available"`. Always `null` if not grouping by inference geo.
- `model: string`
Model name used. `null` if not grouping by description or for non-token costs.
- `service_tier: "standard" or "batch"`
Service tier used. `null` if not grouping by description or for non-token costs.
- `"standard"`
- `"batch"`
- `token_type: "uncached_input_tokens" or "output_tokens" or "cache_read_input_tokens" or 2 more`
Type of token. `null` if not grouping by description or for non-token costs.
- `"uncached_input_tokens"`
- `"output_tokens"`
- `"cache_read_input_tokens"`
- `"cache_creation.ephemeral_1h_input_tokens"`
- `"cache_creation.ephemeral_5m_input_tokens"`
- `workspace_id: string`
ID of the Workspace this cost is associated with. `null` if not grouping by workspace or for the default workspace.
- `starting_at: string`
Start of the time bucket (inclusive) in RFC 3339 format.
- `has_more: boolean`
Indicates if there are more results.
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/cost_report \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-invites-c6a7bd3b33.md
# Invites
## Create
**post** `/v1/organizations/invites`
Create Invite
### Body Parameters
- `email: string`
Email of the User.
- `role: "user" or "developer" or "billing" or "claude_code_user"`
Role for the invited User. Cannot be "admin".
- `"user"`
- `"developer"`
- `"billing"`
- `"claude_code_user"`
### Returns
- `Invite = object { id, email, expires_at, 4 more }`
- `id: string`
ID of the Invite.
- `email: string`
Email of the User being invited.
- `expires_at: string`
RFC 3339 datetime string indicating when the Invite expires.
- `invited_at: string`
RFC 3339 datetime string indicating when the Invite was created.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `status: "accepted" or "expired" or "deleted" or "pending"`
Status of the Invite.
- `"accepted"`
- `"expired"`
- `"deleted"`
- `"pending"`
- `type: "invite"`
Object type.
For Invites, this is always `"invite"`.
- `"invite"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/invites \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"email": "user@emaildomain.com",
"role": "user"
}'
```
## Retrieve
**get** `/v1/organizations/invites/{invite_id}`
Get Invite
### Path Parameters
- `invite_id: string`
ID of the Invite.
### Returns
- `Invite = object { id, email, expires_at, 4 more }`
- `id: string`
ID of the Invite.
- `email: string`
Email of the User being invited.
- `expires_at: string`
RFC 3339 datetime string indicating when the Invite expires.
- `invited_at: string`
RFC 3339 datetime string indicating when the Invite was created.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `status: "accepted" or "expired" or "deleted" or "pending"`
Status of the Invite.
- `"accepted"`
- `"expired"`
- `"deleted"`
- `"pending"`
- `type: "invite"`
Object type.
For Invites, this is always `"invite"`.
- `"invite"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/invites/$INVITE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## List
**get** `/v1/organizations/invites`
List Invites
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of Invite`
- `id: string`
ID of the Invite.
- `email: string`
Email of the User being invited.
- `expires_at: string`
RFC 3339 datetime string indicating when the Invite expires.
- `invited_at: string`
RFC 3339 datetime string indicating when the Invite was created.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `status: "accepted" or "expired" or "deleted" or "pending"`
Status of the Invite.
- `"accepted"`
- `"expired"`
- `"deleted"`
- `"pending"`
- `type: "invite"`
Object type.
For Invites, this is always `"invite"`.
- `"invite"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/invites \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Delete
**delete** `/v1/organizations/invites/{invite_id}`
Delete Invite
### Path Parameters
- `invite_id: string`
ID of the Invite.
### Returns
- `id: string`
ID of the Invite.
- `type: "invite_deleted"`
Deleted object type.
For Invites, this is always `"invite_deleted"`.
- `"invite_deleted"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/invites/$INVITE_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Invite
- `Invite = object { id, email, expires_at, 4 more }`
- `id: string`
ID of the Invite.
- `email: string`
Email of the User being invited.
- `expires_at: string`
RFC 3339 datetime string indicating when the Invite expires.
- `invited_at: string`
RFC 3339 datetime string indicating when the Invite was created.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `status: "accepted" or "expired" or "deleted" or "pending"`
Status of the Invite.
- `"accepted"`
- `"expired"`
- `"deleted"`
- `"pending"`
- `type: "invite"`
Object type.
For Invites, this is always `"invite"`.
- `"invite"`
### Invite Delete Response
- `InviteDeleteResponse = object { id, type }`
- `id: string`
ID of the Invite.
- `type: "invite_deleted"`
Deleted object type.
For Invites, this is always `"invite_deleted"`.
- `"invite_deleted"`
---
## Admin/api-admin-invites-create-4e7f9221ab.md
## Create
**post** `/v1/organizations/invites`
Create Invite
### Body Parameters
- `email: string`
Email of the User.
- `role: "user" or "developer" or "billing" or "claude_code_user"`
Role for the invited User. Cannot be "admin".
- `"user"`
- `"developer"`
- `"billing"`
- `"claude_code_user"`
### Returns
- `Invite = object { id, email, expires_at, 4 more }`
- `id: string`
ID of the Invite.
- `email: string`
Email of the User being invited.
- `expires_at: string`
RFC 3339 datetime string indicating when the Invite expires.
- `invited_at: string`
RFC 3339 datetime string indicating when the Invite was created.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `status: "accepted" or "expired" or "deleted" or "pending"`
Status of the Invite.
- `"accepted"`
- `"expired"`
- `"deleted"`
- `"pending"`
- `type: "invite"`
Object type.
For Invites, this is always `"invite"`.
- `"invite"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/invites \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"email": "user@emaildomain.com",
"role": "user"
}'
```
---
## Admin/api-admin-invites-delete-4d77b687fd.md
## Delete
**delete** `/v1/organizations/invites/{invite_id}`
Delete Invite
### Path Parameters
- `invite_id: string`
ID of the Invite.
### Returns
- `id: string`
ID of the Invite.
- `type: "invite_deleted"`
Deleted object type.
For Invites, this is always `"invite_deleted"`.
- `"invite_deleted"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/invites/$INVITE_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-invites-list-d4f19c73c1.md
## List
**get** `/v1/organizations/invites`
List Invites
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of Invite`
- `id: string`
ID of the Invite.
- `email: string`
Email of the User being invited.
- `expires_at: string`
RFC 3339 datetime string indicating when the Invite expires.
- `invited_at: string`
RFC 3339 datetime string indicating when the Invite was created.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `status: "accepted" or "expired" or "deleted" or "pending"`
Status of the Invite.
- `"accepted"`
- `"expired"`
- `"deleted"`
- `"pending"`
- `type: "invite"`
Object type.
For Invites, this is always `"invite"`.
- `"invite"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/invites \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-invites-retrieve-07968dba44.md
## Retrieve
**get** `/v1/organizations/invites/{invite_id}`
Get Invite
### Path Parameters
- `invite_id: string`
ID of the Invite.
### Returns
- `Invite = object { id, email, expires_at, 4 more }`
- `id: string`
ID of the Invite.
- `email: string`
Email of the User being invited.
- `expires_at: string`
RFC 3339 datetime string indicating when the Invite expires.
- `invited_at: string`
RFC 3339 datetime string indicating when the Invite was created.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `status: "accepted" or "expired" or "deleted" or "pending"`
Status of the Invite.
- `"accepted"`
- `"expired"`
- `"deleted"`
- `"pending"`
- `type: "invite"`
Object type.
For Invites, this is always `"invite"`.
- `"invite"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/invites/$INVITE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-organizations-2429119ffe.md
# Organizations
## Me
**get** `/v1/organizations/me`
Retrieve information about the organization associated with the authenticated API key.
### Returns
- `Organization = object { id, name, type }`
- `id: string`
ID of the Organization.
- `name: string`
Name of the Organization.
- `type: "organization"`
Object type.
For Organizations, this is always `"organization"`.
- `"organization"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/me \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Organization
- `Organization = object { id, name, type }`
- `id: string`
ID of the Organization.
- `name: string`
Name of the Organization.
- `type: "organization"`
Object type.
For Organizations, this is always `"organization"`.
- `"organization"`
---
## Admin/api-admin-organizations-me-85ca0a0bba.md
## Me
**get** `/v1/organizations/me`
Retrieve information about the organization associated with the authenticated API key.
### Returns
- `Organization = object { id, name, type }`
- `id: string`
ID of the Organization.
- `name: string`
Name of the Organization.
- `type: "organization"`
Object type.
For Organizations, this is always `"organization"`.
- `"organization"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/me \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-rate-limits-1ff96f3780.md
# Rate Limits
## List
**get** `/v1/organizations/rate_limits`
List Messages API rate limits for your organization.
Each entry corresponds to one rate-limit group (either a model family
or an API-surface category such as the Files API or Message Batches)
and contains the set of limiter values that apply to it.
### Query Parameters
- `group_type: optional "model_group" or "batch" or "token_count" or 3 more`
Filter by group type.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `model: optional string`
Filter to the single entry containing this model. Accepts full model names and aliases. Returns 404 if the model is not found or has no rate limits for this organization.
- `page: optional string`
Opaque cursor from a previous response's `next_page`.
### Returns
- `data: array of object { group_type, limits, models, type }`
Rate-limit entries for the organization, one per group.
- `group_type: "model_group" or "batch" or "token_count" or 3 more`
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `limits: array of object { type, value }`
The limiter values that apply to this group.
- `type: string`
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
- `value: number`
The configured limit value for this limiter type.
- `models: array of string`
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
- `type: "rate_limit"`
Object type. Always `rate_limit` for organization rate-limit entries.
- `"rate_limit"`
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/rate_limits \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Rate Limit List Response
- `RateLimitListResponse = object { data, next_page }`
- `data: array of object { group_type, limits, models, type }`
Rate-limit entries for the organization, one per group.
- `group_type: "model_group" or "batch" or "token_count" or 3 more`
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `limits: array of object { type, value }`
The limiter values that apply to this group.
- `type: string`
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
- `value: number`
The configured limit value for this limiter type.
- `models: array of string`
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
- `type: "rate_limit"`
Object type. Always `rate_limit` for organization rate-limit entries.
- `"rate_limit"`
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
---
## Admin/api-admin-rate-limits-list-83d9e8ee16.md
## List
**get** `/v1/organizations/rate_limits`
List Messages API rate limits for your organization.
Each entry corresponds to one rate-limit group (either a model family
or an API-surface category such as the Files API or Message Batches)
and contains the set of limiter values that apply to it.
### Query Parameters
- `group_type: optional "model_group" or "batch" or "token_count" or 3 more`
Filter by group type.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `model: optional string`
Filter to the single entry containing this model. Accepts full model names and aliases. Returns 404 if the model is not found or has no rate limits for this organization.
- `page: optional string`
Opaque cursor from a previous response's `next_page`.
### Returns
- `data: array of object { group_type, limits, models, type }`
Rate-limit entries for the organization, one per group.
- `group_type: "model_group" or "batch" or "token_count" or 3 more`
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `limits: array of object { type, value }`
The limiter values that apply to this group.
- `type: string`
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
- `value: number`
The configured limit value for this limiter type.
- `models: array of string`
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
- `type: "rate_limit"`
Object type. Always `rate_limit` for organization rate-limit entries.
- `"rate_limit"`
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/rate_limits \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-usage-report-b05de342cf.md
# Usage Report
## Retrieve Messages
**get** `/v1/organizations/usage_report/messages`
Get Messages Usage Report
### Query Parameters
- `starting_at: string`
Time buckets that start on or after this RFC 3339 timestamp will be returned.
Each time bucket will be snapped to the start of the minute/hour/day in UTC.
- `account_ids: optional array of string`
Restrict usage returned to the specified user account ID(s).
- `api_key_ids: optional array of string`
Restrict usage returned to the specified API key ID(s).
- `bucket_width: optional "1d" or "1m" or "1h"`
Time granularity of the response data.
- `"1d"`
- `"1m"`
- `"1h"`
- `context_window: optional array of "0-200k" or "200k-1M"`
Restrict usage returned to the specified context window(s).
- `"0-200k"`
- `"200k-1M"`
- `ending_at: optional string`
Time buckets that end before this RFC 3339 timestamp will be returned.
- `group_by: optional array of "api_key_id" or "workspace_id" or "model" or 6 more`
Group by any subset of the available options. Grouping by `speed` requires the `fast-mode-2026-02-01` beta header.
- `"api_key_id"`
- `"workspace_id"`
- `"model"`
- `"service_tier"`
- `"context_window"`
- `"inference_geo"`
- `"speed"`
- `"account_id"`
- `"service_account_id"`
- `inference_geos: optional array of "global" or "us" or "not_available"`
Restrict usage returned to the specified inference geo(s). Use `not_available` for models that do not support specifying `inference_geo`.
- `"global"`
- `"us"`
- `"not_available"`
- `limit: optional number`
Maximum number of time buckets to return in the response.
The default and max limits depend on `bucket_width`:
• `"1d"`: Default of 7 days, maximum of 31 days
• `"1h"`: Default of 24 hours, maximum of 168 hours
• `"1m"`: Default of 60 minutes, maximum of 1440 minutes
- `models: optional array of string`
Restrict usage returned to the specified model(s).
- `page: optional string`
Optionally set to the `next_page` token from the previous response.
- `service_account_ids: optional array of string`
Restrict usage returned to the specified service account ID(s).
- `service_tiers: optional array of "standard" or "batch" or "priority" or 3 more`
Restrict usage returned to the specified service tier(s).
- `"standard"`
- `"batch"`
- `"priority"`
- `"priority_on_demand"`
- `"flex"`
- `"flex_discount"`
- `speeds: optional array of "standard" or "fast"`
Restrict usage returned to the specified speed(s) (Claude Code research preview).
Requires the `fast-mode-2026-02-01` beta header.
- `"standard"`
- `"fast"`
- `workspace_ids: optional array of string`
Restrict usage returned to the specified workspace ID(s).
### Header Parameters
- `"anthropic-beta": optional array of string`
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
### Returns
- `MessagesUsageReport = object { data, has_more, next_page }`
- `data: array of object { ending_at, results, starting_at }`
- `ending_at: string`
End of the time bucket (exclusive) in RFC 3339 format.
- `results: array of object { account_id, api_key_id, cache_creation, 10 more }`
List of usage items for this time bucket. There may be multiple items if one or more `group_by[]` parameters are specified.
- `account_id: string`
ID of the user account that made the request. `null` if not grouping by account or for non-OAuth requests.
- `api_key_id: string`
ID of the API key used. `null` if not grouping by API key or for usage in the Anthropic Console.
- `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }`
The number of input tokens for cache creation.
- `ephemeral_1h_input_tokens: number`
The number of input tokens used to create the 1 hour cache entry.
- `ephemeral_5m_input_tokens: number`
The number of input tokens used to create the 5 minute cache entry.
- `cache_read_input_tokens: number`
The number of input tokens read from the cache.
- `context_window: "0-200k" or "200k-1M"`
Context window used. `null` if not grouping by context window.
- `"0-200k"`
- `"200k-1M"`
- `inference_geo: string`
Inference geo used matching requests' `inference_geo` parameter if set, otherwise the workspace's `default_inference_geo`.
For models that do not support specifying `inference_geo` the value is `"not_available"`. Always `null` if not grouping by inference geo.
- `model: string`
Model used. `null` if not grouping by model.
- `output_tokens: number`
The number of output tokens generated.
- `server_tool_use: object { web_search_requests }`
Server-side tool usage metrics.
- `web_search_requests: number`
The number of web search requests made.
- `service_account_id: string`
ID of the service account that made the request. `null` if not grouping by service account or for non-OIDC-federation requests.
- `service_tier: "standard" or "batch" or "priority" or 3 more`
Service tier used. `null` if not grouping by service tier.
- `"standard"`
- `"batch"`
- `"priority"`
- `"priority_on_demand"`
- `"flex"`
- `"flex_discount"`
- `uncached_input_tokens: number`
The number of uncached input tokens processed.
- `workspace_id: string`
ID of the Workspace used. `null` if not grouping by workspace or for the default workspace.
- `starting_at: string`
Start of the time bucket (inclusive) in RFC 3339 format.
- `has_more: boolean`
Indicates if there are more results.
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/usage_report/messages \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Retrieve Claude Code
**get** `/v1/organizations/usage_report/claude_code`
Retrieve daily aggregated usage metrics for Claude Code users.
Enables organizations to analyze developer productivity and build custom dashboards.
### Query Parameters
- `starting_at: string`
UTC date in YYYY-MM-DD format. Returns metrics for this single day only.
- `limit: optional number`
Number of records per page (default: 20, max: 1000).
- `page: optional string`
Opaque cursor token from previous response's `next_page` field.
### Returns
- `ClaudeCodeUsageReport = object { data, has_more, next_page }`
- `data: array of object { actor, core_metrics, customer_type, 6 more }`
List of Claude Code usage records for the requested date.
- `actor: object { email_address, type } or object { api_key_name, type }`
The user or API key that performed the Claude Code actions.
- `UserActor = object { email_address, type }`
- `email_address: string`
Email address of the user who performed Claude Code actions.
- `type: "user_actor"`
- `"user_actor"`
- `APIActor = object { api_key_name, type }`
- `api_key_name: string`
Name of the API key used to perform Claude Code actions.
- `type: "api_actor"`
- `"api_actor"`
- `core_metrics: object { commits_by_claude_code, lines_of_code, num_sessions, pull_requests_by_claude_code }`
Core productivity metrics measuring Claude Code usage and impact.
- `commits_by_claude_code: number`
Number of git commits created through Claude Code's commit functionality.
- `lines_of_code: object { added, removed }`
Statistics on code changes made through Claude Code.
- `added: number`
Total number of lines of code added across all files by Claude Code.
- `removed: number`
Total number of lines of code removed across all files by Claude Code.
- `num_sessions: number`
Number of distinct Claude Code sessions initiated by this actor.
- `pull_requests_by_claude_code: number`
Number of pull requests created through Claude Code's PR functionality.
- `customer_type: "api" or "subscription"`
Type of customer account (api for API customers, subscription for Pro/Team customers).
- `"api"`
- `"subscription"`
- `date: string`
UTC date for the usage metrics in YYYY-MM-DD format.
- `model_breakdown: array of object { estimated_cost, model, tokens }`
Token usage and cost breakdown by AI model used.
- `estimated_cost: object { amount, currency }`
Estimated cost for using this model
- `amount: number`
Estimated cost amount in minor currency units (e.g., cents for USD).
- `currency: string`
Currency code for the estimated cost (e.g., 'USD').
- `model: string`
Name of the AI model used for Claude Code interactions.
- `tokens: object { cache_creation, cache_read, input, output }`
Token usage breakdown for this model
- `cache_creation: number`
Number of cache creation tokens consumed by this model.
- `cache_read: number`
Number of cache read tokens consumed by this model.
- `input: number`
Number of input tokens consumed by this model.
- `output: number`
Number of output tokens generated by this model.
- `organization_id: string`
ID of the organization that owns the Claude Code usage.
- `terminal_type: string`
Type of terminal or environment where Claude Code was used.
- `tool_actions: map[object { accepted, rejected } ]`
Breakdown of tool action acceptance and rejection rates by tool type.
- `accepted: number`
Number of tool action proposals that the user accepted.
- `rejected: number`
Number of tool action proposals that the user rejected.
- `subscription_type: optional "enterprise" or "team"`
Subscription tier for subscription customers. `null` for API customers.
- `"enterprise"`
- `"team"`
- `has_more: boolean`
True if there are more records available beyond the current page.
- `next_page: string`
Opaque cursor token for fetching the next page of results, or null if no more pages are available.
### Example
```http
curl https://api.anthropic.com/v1/organizations/usage_report/claude_code \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Claude Code Usage Report
- `ClaudeCodeUsageReport = object { data, has_more, next_page }`
- `data: array of object { actor, core_metrics, customer_type, 6 more }`
List of Claude Code usage records for the requested date.
- `actor: object { email_address, type } or object { api_key_name, type }`
The user or API key that performed the Claude Code actions.
- `UserActor = object { email_address, type }`
- `email_address: string`
Email address of the user who performed Claude Code actions.
- `type: "user_actor"`
- `"user_actor"`
- `APIActor = object { api_key_name, type }`
- `api_key_name: string`
Name of the API key used to perform Claude Code actions.
- `type: "api_actor"`
- `"api_actor"`
- `core_metrics: object { commits_by_claude_code, lines_of_code, num_sessions, pull_requests_by_claude_code }`
Core productivity metrics measuring Claude Code usage and impact.
- `commits_by_claude_code: number`
Number of git commits created through Claude Code's commit functionality.
- `lines_of_code: object { added, removed }`
Statistics on code changes made through Claude Code.
- `added: number`
Total number of lines of code added across all files by Claude Code.
- `removed: number`
Total number of lines of code removed across all files by Claude Code.
- `num_sessions: number`
Number of distinct Claude Code sessions initiated by this actor.
- `pull_requests_by_claude_code: number`
Number of pull requests created through Claude Code's PR functionality.
- `customer_type: "api" or "subscription"`
Type of customer account (api for API customers, subscription for Pro/Team customers).
- `"api"`
- `"subscription"`
- `date: string`
UTC date for the usage metrics in YYYY-MM-DD format.
- `model_breakdown: array of object { estimated_cost, model, tokens }`
Token usage and cost breakdown by AI model used.
- `estimated_cost: object { amount, currency }`
Estimated cost for using this model
- `amount: number`
Estimated cost amount in minor currency units (e.g., cents for USD).
- `currency: string`
Currency code for the estimated cost (e.g., 'USD').
- `model: string`
Name of the AI model used for Claude Code interactions.
- `tokens: object { cache_creation, cache_read, input, output }`
Token usage breakdown for this model
- `cache_creation: number`
Number of cache creation tokens consumed by this model.
- `cache_read: number`
Number of cache read tokens consumed by this model.
- `input: number`
Number of input tokens consumed by this model.
- `output: number`
Number of output tokens generated by this model.
- `organization_id: string`
ID of the organization that owns the Claude Code usage.
- `terminal_type: string`
Type of terminal or environment where Claude Code was used.
- `tool_actions: map[object { accepted, rejected } ]`
Breakdown of tool action acceptance and rejection rates by tool type.
- `accepted: number`
Number of tool action proposals that the user accepted.
- `rejected: number`
Number of tool action proposals that the user rejected.
- `subscription_type: optional "enterprise" or "team"`
Subscription tier for subscription customers. `null` for API customers.
- `"enterprise"`
- `"team"`
- `has_more: boolean`
True if there are more records available beyond the current page.
- `next_page: string`
Opaque cursor token for fetching the next page of results, or null if no more pages are available.
### Messages Usage Report
- `MessagesUsageReport = object { data, has_more, next_page }`
- `data: array of object { ending_at, results, starting_at }`
- `ending_at: string`
End of the time bucket (exclusive) in RFC 3339 format.
- `results: array of object { account_id, api_key_id, cache_creation, 10 more }`
List of usage items for this time bucket. There may be multiple items if one or more `group_by[]` parameters are specified.
- `account_id: string`
ID of the user account that made the request. `null` if not grouping by account or for non-OAuth requests.
- `api_key_id: string`
ID of the API key used. `null` if not grouping by API key or for usage in the Anthropic Console.
- `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }`
The number of input tokens for cache creation.
- `ephemeral_1h_input_tokens: number`
The number of input tokens used to create the 1 hour cache entry.
- `ephemeral_5m_input_tokens: number`
The number of input tokens used to create the 5 minute cache entry.
- `cache_read_input_tokens: number`
The number of input tokens read from the cache.
- `context_window: "0-200k" or "200k-1M"`
Context window used. `null` if not grouping by context window.
- `"0-200k"`
- `"200k-1M"`
- `inference_geo: string`
Inference geo used matching requests' `inference_geo` parameter if set, otherwise the workspace's `default_inference_geo`.
For models that do not support specifying `inference_geo` the value is `"not_available"`. Always `null` if not grouping by inference geo.
- `model: string`
Model used. `null` if not grouping by model.
- `output_tokens: number`
The number of output tokens generated.
- `server_tool_use: object { web_search_requests }`
Server-side tool usage metrics.
- `web_search_requests: number`
The number of web search requests made.
- `service_account_id: string`
ID of the service account that made the request. `null` if not grouping by service account or for non-OIDC-federation requests.
- `service_tier: "standard" or "batch" or "priority" or 3 more`
Service tier used. `null` if not grouping by service tier.
- `"standard"`
- `"batch"`
- `"priority"`
- `"priority_on_demand"`
- `"flex"`
- `"flex_discount"`
- `uncached_input_tokens: number`
The number of uncached input tokens processed.
- `workspace_id: string`
ID of the Workspace used. `null` if not grouping by workspace or for the default workspace.
- `starting_at: string`
Start of the time bucket (inclusive) in RFC 3339 format.
- `has_more: boolean`
Indicates if there are more results.
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
---
## Admin/api-admin-usage-report-retrieve-claude-code-610a5cf4a0.md
## Retrieve Claude Code
**get** `/v1/organizations/usage_report/claude_code`
Retrieve daily aggregated usage metrics for Claude Code users.
Enables organizations to analyze developer productivity and build custom dashboards.
### Query Parameters
- `starting_at: string`
UTC date in YYYY-MM-DD format. Returns metrics for this single day only.
- `limit: optional number`
Number of records per page (default: 20, max: 1000).
- `page: optional string`
Opaque cursor token from previous response's `next_page` field.
### Returns
- `ClaudeCodeUsageReport = object { data, has_more, next_page }`
- `data: array of object { actor, core_metrics, customer_type, 6 more }`
List of Claude Code usage records for the requested date.
- `actor: object { email_address, type } or object { api_key_name, type }`
The user or API key that performed the Claude Code actions.
- `UserActor = object { email_address, type }`
- `email_address: string`
Email address of the user who performed Claude Code actions.
- `type: "user_actor"`
- `"user_actor"`
- `APIActor = object { api_key_name, type }`
- `api_key_name: string`
Name of the API key used to perform Claude Code actions.
- `type: "api_actor"`
- `"api_actor"`
- `core_metrics: object { commits_by_claude_code, lines_of_code, num_sessions, pull_requests_by_claude_code }`
Core productivity metrics measuring Claude Code usage and impact.
- `commits_by_claude_code: number`
Number of git commits created through Claude Code's commit functionality.
- `lines_of_code: object { added, removed }`
Statistics on code changes made through Claude Code.
- `added: number`
Total number of lines of code added across all files by Claude Code.
- `removed: number`
Total number of lines of code removed across all files by Claude Code.
- `num_sessions: number`
Number of distinct Claude Code sessions initiated by this actor.
- `pull_requests_by_claude_code: number`
Number of pull requests created through Claude Code's PR functionality.
- `customer_type: "api" or "subscription"`
Type of customer account (api for API customers, subscription for Pro/Team customers).
- `"api"`
- `"subscription"`
- `date: string`
UTC date for the usage metrics in YYYY-MM-DD format.
- `model_breakdown: array of object { estimated_cost, model, tokens }`
Token usage and cost breakdown by AI model used.
- `estimated_cost: object { amount, currency }`
Estimated cost for using this model
- `amount: number`
Estimated cost amount in minor currency units (e.g., cents for USD).
- `currency: string`
Currency code for the estimated cost (e.g., 'USD').
- `model: string`
Name of the AI model used for Claude Code interactions.
- `tokens: object { cache_creation, cache_read, input, output }`
Token usage breakdown for this model
- `cache_creation: number`
Number of cache creation tokens consumed by this model.
- `cache_read: number`
Number of cache read tokens consumed by this model.
- `input: number`
Number of input tokens consumed by this model.
- `output: number`
Number of output tokens generated by this model.
- `organization_id: string`
ID of the organization that owns the Claude Code usage.
- `terminal_type: string`
Type of terminal or environment where Claude Code was used.
- `tool_actions: map[object { accepted, rejected } ]`
Breakdown of tool action acceptance and rejection rates by tool type.
- `accepted: number`
Number of tool action proposals that the user accepted.
- `rejected: number`
Number of tool action proposals that the user rejected.
- `subscription_type: optional "enterprise" or "team"`
Subscription tier for subscription customers. `null` for API customers.
- `"enterprise"`
- `"team"`
- `has_more: boolean`
True if there are more records available beyond the current page.
- `next_page: string`
Opaque cursor token for fetching the next page of results, or null if no more pages are available.
### Example
```http
curl https://api.anthropic.com/v1/organizations/usage_report/claude_code \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-usage-report-retrieve-messages-a10b0b7a1a.md
## Retrieve Messages
**get** `/v1/organizations/usage_report/messages`
Get Messages Usage Report
### Query Parameters
- `starting_at: string`
Time buckets that start on or after this RFC 3339 timestamp will be returned.
Each time bucket will be snapped to the start of the minute/hour/day in UTC.
- `account_ids: optional array of string`
Restrict usage returned to the specified user account ID(s).
- `api_key_ids: optional array of string`
Restrict usage returned to the specified API key ID(s).
- `bucket_width: optional "1d" or "1m" or "1h"`
Time granularity of the response data.
- `"1d"`
- `"1m"`
- `"1h"`
- `context_window: optional array of "0-200k" or "200k-1M"`
Restrict usage returned to the specified context window(s).
- `"0-200k"`
- `"200k-1M"`
- `ending_at: optional string`
Time buckets that end before this RFC 3339 timestamp will be returned.
- `group_by: optional array of "api_key_id" or "workspace_id" or "model" or 6 more`
Group by any subset of the available options. Grouping by `speed` requires the `fast-mode-2026-02-01` beta header.
- `"api_key_id"`
- `"workspace_id"`
- `"model"`
- `"service_tier"`
- `"context_window"`
- `"inference_geo"`
- `"speed"`
- `"account_id"`
- `"service_account_id"`
- `inference_geos: optional array of "global" or "us" or "not_available"`
Restrict usage returned to the specified inference geo(s). Use `not_available` for models that do not support specifying `inference_geo`.
- `"global"`
- `"us"`
- `"not_available"`
- `limit: optional number`
Maximum number of time buckets to return in the response.
The default and max limits depend on `bucket_width`:
• `"1d"`: Default of 7 days, maximum of 31 days
• `"1h"`: Default of 24 hours, maximum of 168 hours
• `"1m"`: Default of 60 minutes, maximum of 1440 minutes
- `models: optional array of string`
Restrict usage returned to the specified model(s).
- `page: optional string`
Optionally set to the `next_page` token from the previous response.
- `service_account_ids: optional array of string`
Restrict usage returned to the specified service account ID(s).
- `service_tiers: optional array of "standard" or "batch" or "priority" or 3 more`
Restrict usage returned to the specified service tier(s).
- `"standard"`
- `"batch"`
- `"priority"`
- `"priority_on_demand"`
- `"flex"`
- `"flex_discount"`
- `speeds: optional array of "standard" or "fast"`
Restrict usage returned to the specified speed(s) (Claude Code research preview).
Requires the `fast-mode-2026-02-01` beta header.
- `"standard"`
- `"fast"`
- `workspace_ids: optional array of string`
Restrict usage returned to the specified workspace ID(s).
### Header Parameters
- `"anthropic-beta": optional array of string`
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
### Returns
- `MessagesUsageReport = object { data, has_more, next_page }`
- `data: array of object { ending_at, results, starting_at }`
- `ending_at: string`
End of the time bucket (exclusive) in RFC 3339 format.
- `results: array of object { account_id, api_key_id, cache_creation, 10 more }`
List of usage items for this time bucket. There may be multiple items if one or more `group_by[]` parameters are specified.
- `account_id: string`
ID of the user account that made the request. `null` if not grouping by account or for non-OAuth requests.
- `api_key_id: string`
ID of the API key used. `null` if not grouping by API key or for usage in the Anthropic Console.
- `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }`
The number of input tokens for cache creation.
- `ephemeral_1h_input_tokens: number`
The number of input tokens used to create the 1 hour cache entry.
- `ephemeral_5m_input_tokens: number`
The number of input tokens used to create the 5 minute cache entry.
- `cache_read_input_tokens: number`
The number of input tokens read from the cache.
- `context_window: "0-200k" or "200k-1M"`
Context window used. `null` if not grouping by context window.
- `"0-200k"`
- `"200k-1M"`
- `inference_geo: string`
Inference geo used matching requests' `inference_geo` parameter if set, otherwise the workspace's `default_inference_geo`.
For models that do not support specifying `inference_geo` the value is `"not_available"`. Always `null` if not grouping by inference geo.
- `model: string`
Model used. `null` if not grouping by model.
- `output_tokens: number`
The number of output tokens generated.
- `server_tool_use: object { web_search_requests }`
Server-side tool usage metrics.
- `web_search_requests: number`
The number of web search requests made.
- `service_account_id: string`
ID of the service account that made the request. `null` if not grouping by service account or for non-OIDC-federation requests.
- `service_tier: "standard" or "batch" or "priority" or 3 more`
Service tier used. `null` if not grouping by service tier.
- `"standard"`
- `"batch"`
- `"priority"`
- `"priority_on_demand"`
- `"flex"`
- `"flex_discount"`
- `uncached_input_tokens: number`
The number of uncached input tokens processed.
- `workspace_id: string`
ID of the Workspace used. `null` if not grouping by workspace or for the default workspace.
- `starting_at: string`
Start of the time bucket (inclusive) in RFC 3339 format.
- `has_more: boolean`
Indicates if there are more results.
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/usage_report/messages \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-users-3705274a52.md
# Users
## Retrieve
**get** `/v1/organizations/users/{user_id}`
Get User
### Path Parameters
- `user_id: string`
ID of the User.
### Returns
- `User = object { id, added_at, email, 3 more }`
- `id: string`
ID of the User.
- `added_at: string`
RFC 3339 datetime string indicating when the User joined the Organization.
- `email: string`
Email of the User.
- `name: string`
Name of the User.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `type: "user"`
Object type.
For Users, this is always `"user"`.
- `"user"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## List
**get** `/v1/organizations/users`
List Users
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `email: optional string`
Filter by user email.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of User`
- `id: string`
ID of the User.
- `added_at: string`
RFC 3339 datetime string indicating when the User joined the Organization.
- `email: string`
Email of the User.
- `name: string`
Name of the User.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `type: "user"`
Object type.
For Users, this is always `"user"`.
- `"user"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/users \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Update
**post** `/v1/organizations/users/{user_id}`
Update User
### Path Parameters
- `user_id: string`
ID of the User.
### Body Parameters
- `role: "user" or "developer" or "billing" or "claude_code_user"`
New role for the User. Cannot be "admin".
- `"user"`
- `"developer"`
- `"billing"`
- `"claude_code_user"`
### Returns
- `User = object { id, added_at, email, 3 more }`
- `id: string`
ID of the User.
- `added_at: string`
RFC 3339 datetime string indicating when the User joined the Organization.
- `email: string`
Email of the User.
- `name: string`
Name of the User.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `type: "user"`
Object type.
For Users, this is always `"user"`.
- `"user"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"role": "user"
}'
```
## Delete
**delete** `/v1/organizations/users/{user_id}`
Remove User
### Path Parameters
- `user_id: string`
ID of the User.
### Returns
- `id: string`
ID of the User.
- `type: "user_deleted"`
Deleted object type.
For Users, this is always `"user_deleted"`.
- `"user_deleted"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### User
- `User = object { id, added_at, email, 3 more }`
- `id: string`
ID of the User.
- `added_at: string`
RFC 3339 datetime string indicating when the User joined the Organization.
- `email: string`
Email of the User.
- `name: string`
Name of the User.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `type: "user"`
Object type.
For Users, this is always `"user"`.
- `"user"`
### User Delete Response
- `UserDeleteResponse = object { id, type }`
- `id: string`
ID of the User.
- `type: "user_deleted"`
Deleted object type.
For Users, this is always `"user_deleted"`.
- `"user_deleted"`
---
## Admin/api-admin-users-delete-fbc1a9c080.md
## Delete
**delete** `/v1/organizations/users/{user_id}`
Remove User
### Path Parameters
- `user_id: string`
ID of the User.
### Returns
- `id: string`
ID of the User.
- `type: "user_deleted"`
Deleted object type.
For Users, this is always `"user_deleted"`.
- `"user_deleted"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-users-list-2e0e8109f3.md
## List
**get** `/v1/organizations/users`
List Users
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `email: optional string`
Filter by user email.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of User`
- `id: string`
ID of the User.
- `added_at: string`
RFC 3339 datetime string indicating when the User joined the Organization.
- `email: string`
Email of the User.
- `name: string`
Name of the User.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `type: "user"`
Object type.
For Users, this is always `"user"`.
- `"user"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/users \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-users-retrieve-ae028818d3.md
## Retrieve
**get** `/v1/organizations/users/{user_id}`
Get User
### Path Parameters
- `user_id: string`
ID of the User.
### Returns
- `User = object { id, added_at, email, 3 more }`
- `id: string`
ID of the User.
- `added_at: string`
RFC 3339 datetime string indicating when the User joined the Organization.
- `email: string`
Email of the User.
- `name: string`
Name of the User.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `type: "user"`
Object type.
For Users, this is always `"user"`.
- `"user"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-users-update-56bd0224c1.md
## Update
**post** `/v1/organizations/users/{user_id}`
Update User
### Path Parameters
- `user_id: string`
ID of the User.
### Body Parameters
- `role: "user" or "developer" or "billing" or "claude_code_user"`
New role for the User. Cannot be "admin".
- `"user"`
- `"developer"`
- `"billing"`
- `"claude_code_user"`
### Returns
- `User = object { id, added_at, email, 3 more }`
- `id: string`
ID of the User.
- `added_at: string`
RFC 3339 datetime string indicating when the User joined the Organization.
- `email: string`
Email of the User.
- `name: string`
Name of the User.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `type: "user"`
Object type.
For Users, this is always `"user"`.
- `"user"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"role": "user"
}'
```
---
## Admin/api-admin-workspaces-archive-08df2be86d.md
## Archive
**post** `/v1/organizations/workspaces/{workspace_id}/archive`
Archive Workspace
### Path Parameters
- `workspace_id: string`
### Returns
- `Workspace = object { id, archived_at, created_at, 4 more }`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/archive \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-workspaces-bbad0119fd.md
# Workspaces
## Create
**post** `/v1/organizations/workspaces`
Create Workspace
### Body Parameters
- `name: string`
Name of the Workspace.
- `data_residency: optional object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration for the workspace. If omitted, defaults to workspace_geo=`"us"`, allowed_inference_geos=`"unrestricted"`, and default_inference_geo=`"global"`.
- `allowed_inference_geos: optional array of string or "unrestricted"`
Permitted inference geo values. Defaults to 'unrestricted' if omitted, which allows all geos. Use the string 'unrestricted' to allow all geos, or a list of specific geos.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: optional string`
Default inference geo applied when requests omit the parameter. Defaults to 'global' if omitted. Must be a member of allowed_inference_geos unless allowed_inference_geos is `"unrestricted"`.
- `workspace_geo: optional string`
Geographic region for workspace data storage. Immutable after creation. Defaults to 'us' if omitted.
### Returns
- `Workspace = object { id, archived_at, created_at, 4 more }`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"name": "x"
}'
```
## Retrieve
**get** `/v1/organizations/workspaces/{workspace_id}`
Get Workspace
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
### Returns
- `Workspace = object { id, archived_at, created_at, 4 more }`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## List
**get** `/v1/organizations/workspaces`
List Workspaces
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `include_archived: optional boolean`
Whether to include Workspaces that have been archived in the response
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of Workspace`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Update
**post** `/v1/organizations/workspaces/{workspace_id}`
Update Workspace
### Path Parameters
- `workspace_id: string`
### Body Parameters
- `name: string`
Name of the Workspace.
- `data_residency: optional object { allowed_inference_geos, default_inference_geo }`
Data residency configuration for the workspace.
- `allowed_inference_geos: optional array of string or "unrestricted"`
Permitted inference geo values. Use 'unrestricted' to allow all geos, or a list of specific geos.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: optional string`
Default inference geo applied when requests omit the parameter. Must be a member of allowed_inference_geos unless allowed_inference_geos is `"unrestricted"`.
### Returns
- `Workspace = object { id, archived_at, created_at, 4 more }`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"name": "x"
}'
```
## Archive
**post** `/v1/organizations/workspaces/{workspace_id}/archive`
Archive Workspace
### Path Parameters
- `workspace_id: string`
### Returns
- `Workspace = object { id, archived_at, created_at, 4 more }`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/archive \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
# Members
## Create
**post** `/v1/organizations/workspaces/{workspace_id}/members`
Create Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
### Body Parameters
- `user_id: string`
ID of the User.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or "workspace_admin"`
Role of the new Workspace Member. Cannot be "workspace_billing".
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"workspace_role": "workspace_user"
}'
```
## Retrieve
**get** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Get Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## List
**get** `/v1/organizations/workspaces/{workspace_id}/members`
List Workspace Members
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of WorkspaceMember`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Update
**post** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Update Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Body Parameters
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
New workspace role for the User.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"workspace_role": "workspace_user"
}'
```
## Delete
**delete** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Delete Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Returns
- `type: "workspace_member_deleted"`
Deleted object type.
For Workspace Members, this is always `"workspace_member_deleted"`.
- `"workspace_member_deleted"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Workspace Member
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Member Delete Response
- `MemberDeleteResponse = object { type, user_id, workspace_id }`
- `type: "workspace_member_deleted"`
Deleted object type.
For Workspace Members, this is always `"workspace_member_deleted"`.
- `"workspace_member_deleted"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
# Rate Limits
## List
**get** `/v1/organizations/workspaces/{workspace_id}/rate_limits`
List rate-limit overrides configured for a workspace.
Returns only the groups and limiter types that have a workspace-level
override. Groups without overrides inherit the organization limits and
are not listed; use `GET /v1/organizations/rate_limits` to see those.
### Path Parameters
- `workspace_id: string`
The ID of the workspace.
### Query Parameters
- `group_type: optional "model_group" or "batch" or "token_count" or 3 more`
Filter by group type.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `page: optional string`
Opaque cursor from a previous response's `next_page`.
### Returns
- `data: array of object { group_type, limits, models, type }`
Rate-limit entries for the workspace, one per group that has at least one override.
- `group_type: "model_group" or "batch" or "token_count" or 3 more`
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `limits: array of object { org_limit, type, value }`
The limiter values overridden for this group in this workspace. Limiter types without a workspace override are omitted and inherit the organization value.
- `org_limit: number`
The organization-level value for the same limiter type, for reference. `null` when the organization has no limit configured for this limiter type.
- `type: string`
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
- `value: number`
The workspace-level override value for this limiter type.
- `models: array of string`
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
- `type: "workspace_rate_limit"`
Object type. Always `workspace_rate_limit` for workspace rate-limit entries.
- `"workspace_rate_limit"`
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/rate_limits \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Rate Limit List Response
- `RateLimitListResponse = object { data, next_page }`
- `data: array of object { group_type, limits, models, type }`
Rate-limit entries for the workspace, one per group that has at least one override.
- `group_type: "model_group" or "batch" or "token_count" or 3 more`
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `limits: array of object { org_limit, type, value }`
The limiter values overridden for this group in this workspace. Limiter types without a workspace override are omitted and inherit the organization value.
- `org_limit: number`
The organization-level value for the same limiter type, for reference. `null` when the organization has no limit configured for this limiter type.
- `type: string`
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
- `value: number`
The workspace-level override value for this limiter type.
- `models: array of string`
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
- `type: "workspace_rate_limit"`
Object type. Always `workspace_rate_limit` for workspace rate-limit entries.
- `"workspace_rate_limit"`
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
---
## Admin/api-admin-workspaces-create-6061341e22.md
## Create
**post** `/v1/organizations/workspaces`
Create Workspace
### Body Parameters
- `name: string`
Name of the Workspace.
- `data_residency: optional object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration for the workspace. If omitted, defaults to workspace_geo=`"us"`, allowed_inference_geos=`"unrestricted"`, and default_inference_geo=`"global"`.
- `allowed_inference_geos: optional array of string or "unrestricted"`
Permitted inference geo values. Defaults to 'unrestricted' if omitted, which allows all geos. Use the string 'unrestricted' to allow all geos, or a list of specific geos.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: optional string`
Default inference geo applied when requests omit the parameter. Defaults to 'global' if omitted. Must be a member of allowed_inference_geos unless allowed_inference_geos is `"unrestricted"`.
- `workspace_geo: optional string`
Geographic region for workspace data storage. Immutable after creation. Defaults to 'us' if omitted.
### Returns
- `Workspace = object { id, archived_at, created_at, 4 more }`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"name": "x"
}'
```
---
## Admin/api-admin-workspaces-list-db96be5b4c.md
## List
**get** `/v1/organizations/workspaces`
List Workspaces
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `include_archived: optional boolean`
Whether to include Workspaces that have been archived in the response
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of Workspace`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-workspaces-members-baf3d594cd.md
# Members
## Create
**post** `/v1/organizations/workspaces/{workspace_id}/members`
Create Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
### Body Parameters
- `user_id: string`
ID of the User.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or "workspace_admin"`
Role of the new Workspace Member. Cannot be "workspace_billing".
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"workspace_role": "workspace_user"
}'
```
## Retrieve
**get** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Get Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## List
**get** `/v1/organizations/workspaces/{workspace_id}/members`
List Workspace Members
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of WorkspaceMember`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Update
**post** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Update Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Body Parameters
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
New workspace role for the User.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"workspace_role": "workspace_user"
}'
```
## Delete
**delete** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Delete Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Returns
- `type: "workspace_member_deleted"`
Deleted object type.
For Workspace Members, this is always `"workspace_member_deleted"`.
- `"workspace_member_deleted"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Workspace Member
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Member Delete Response
- `MemberDeleteResponse = object { type, user_id, workspace_id }`
- `type: "workspace_member_deleted"`
Deleted object type.
For Workspace Members, this is always `"workspace_member_deleted"`.
- `"workspace_member_deleted"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
---
## Admin/api-admin-workspaces-members-create-f4ff1d3a79.md
## Create
**post** `/v1/organizations/workspaces/{workspace_id}/members`
Create Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
### Body Parameters
- `user_id: string`
ID of the User.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or "workspace_admin"`
Role of the new Workspace Member. Cannot be "workspace_billing".
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"workspace_role": "workspace_user"
}'
```
---
## Admin/api-admin-workspaces-members-delete-d0ab41c43a.md
## Delete
**delete** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Delete Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Returns
- `type: "workspace_member_deleted"`
Deleted object type.
For Workspace Members, this is always `"workspace_member_deleted"`.
- `"workspace_member_deleted"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-workspaces-members-list-725de557d8.md
## List
**get** `/v1/organizations/workspaces/{workspace_id}/members`
List Workspace Members
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of WorkspaceMember`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-workspaces-members-retrieve-a68b4bcb12.md
## Retrieve
**get** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Get Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-workspaces-members-update-a03e7cf161.md
## Update
**post** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Update Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Body Parameters
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
New workspace role for the User.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"workspace_role": "workspace_user"
}'
```
---
## Admin/api-admin-workspaces-rate-limits-7fd15c7aae.md
# Rate Limits
## List
**get** `/v1/organizations/workspaces/{workspace_id}/rate_limits`
List rate-limit overrides configured for a workspace.
Returns only the groups and limiter types that have a workspace-level
override. Groups without overrides inherit the organization limits and
are not listed; use `GET /v1/organizations/rate_limits` to see those.
### Path Parameters
- `workspace_id: string`
The ID of the workspace.
### Query Parameters
- `group_type: optional "model_group" or "batch" or "token_count" or 3 more`
Filter by group type.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `page: optional string`
Opaque cursor from a previous response's `next_page`.
### Returns
- `data: array of object { group_type, limits, models, type }`
Rate-limit entries for the workspace, one per group that has at least one override.
- `group_type: "model_group" or "batch" or "token_count" or 3 more`
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `limits: array of object { org_limit, type, value }`
The limiter values overridden for this group in this workspace. Limiter types without a workspace override are omitted and inherit the organization value.
- `org_limit: number`
The organization-level value for the same limiter type, for reference. `null` when the organization has no limit configured for this limiter type.
- `type: string`
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
- `value: number`
The workspace-level override value for this limiter type.
- `models: array of string`
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
- `type: "workspace_rate_limit"`
Object type. Always `workspace_rate_limit` for workspace rate-limit entries.
- `"workspace_rate_limit"`
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/rate_limits \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Rate Limit List Response
- `RateLimitListResponse = object { data, next_page }`
- `data: array of object { group_type, limits, models, type }`
Rate-limit entries for the workspace, one per group that has at least one override.
- `group_type: "model_group" or "batch" or "token_count" or 3 more`
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `limits: array of object { org_limit, type, value }`
The limiter values overridden for this group in this workspace. Limiter types without a workspace override are omitted and inherit the organization value.
- `org_limit: number`
The organization-level value for the same limiter type, for reference. `null` when the organization has no limit configured for this limiter type.
- `type: string`
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
- `value: number`
The workspace-level override value for this limiter type.
- `models: array of string`
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
- `type: "workspace_rate_limit"`
Object type. Always `workspace_rate_limit` for workspace rate-limit entries.
- `"workspace_rate_limit"`
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
---
## Admin/api-admin-workspaces-rate-limits-list-89661b6ee2.md
## List
**get** `/v1/organizations/workspaces/{workspace_id}/rate_limits`
List rate-limit overrides configured for a workspace.
Returns only the groups and limiter types that have a workspace-level
override. Groups without overrides inherit the organization limits and
are not listed; use `GET /v1/organizations/rate_limits` to see those.
### Path Parameters
- `workspace_id: string`
The ID of the workspace.
### Query Parameters
- `group_type: optional "model_group" or "batch" or "token_count" or 3 more`
Filter by group type.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `page: optional string`
Opaque cursor from a previous response's `next_page`.
### Returns
- `data: array of object { group_type, limits, models, type }`
Rate-limit entries for the workspace, one per group that has at least one override.
- `group_type: "model_group" or "batch" or "token_count" or 3 more`
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `limits: array of object { org_limit, type, value }`
The limiter values overridden for this group in this workspace. Limiter types without a workspace override are omitted and inherit the organization value.
- `org_limit: number`
The organization-level value for the same limiter type, for reference. `null` when the organization has no limit configured for this limiter type.
- `type: string`
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
- `value: number`
The workspace-level override value for this limiter type.
- `models: array of string`
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
- `type: "workspace_rate_limit"`
Object type. Always `workspace_rate_limit` for workspace rate-limit entries.
- `"workspace_rate_limit"`
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/rate_limits \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-workspaces-retrieve-e4e9c89d38.md
## Retrieve
**get** `/v1/organizations/workspaces/{workspace_id}`
Get Workspace
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
### Returns
- `Workspace = object { id, archived_at, created_at, 4 more }`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-workspaces-update-44659e11a9.md
## Update
**post** `/v1/organizations/workspaces/{workspace_id}`
Update Workspace
### Path Parameters
- `workspace_id: string`
### Body Parameters
- `name: string`
Name of the Workspace.
- `data_residency: optional object { allowed_inference_geos, default_inference_geo }`
Data residency configuration for the workspace.
- `allowed_inference_geos: optional array of string or "unrestricted"`
Permitted inference geo values. Use 'unrestricted' to allow all geos, or a list of specific geos.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: optional string`
Default inference geo applied when requests omit the parameter. Must be a member of allowed_inference_geos unless allowed_inference_geos is `"unrestricted"`.
### Returns
- `Workspace = object { id, archived_at, created_at, 4 more }`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"name": "x"
}'
```
---
## Agents-Tools/agents-and-tools-agent-skills-best-practices-d1da876439.md
# Skill authoring best practices
Learn how to write effective Skills that Claude can discover and use successfully.
---
Good Skills are concise, well-structured, and tested with real usage. This guide provides practical authoring decisions to help you write Skills that Claude can discover and use effectively.
For conceptual background on how Skills work, see the [Skills overview](/docs/en/agents-and-tools/agent-skills/overview).
## Core principles
### Concise is key
The [context window](/docs/en/build-with-claude/context-windows) is a public good. Your Skill shares the context window with everything else Claude needs to know, including:
- The system prompt
- Conversation history
- Other Skills' metadata
- Your actual request
Not every token in your Skill has an immediate cost. At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads SKILL.md only when the Skill becomes relevant, and reads additional files only as needed. However, being concise in SKILL.md still matters: once Claude loads it, every token competes with conversation history and other context.
**Default assumption:** Claude is already very smart
Only add context Claude doesn't already have. Challenge each piece of information:
- "Does Claude really need this explanation?"
- "Can I assume Claude knows this?"
- "Does this paragraph justify its token cost?"
**Good example: Concise** (approximately 50 tokens):
````markdown
## Extract PDF text
Use pdfplumber for text extraction:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
````
**Bad example: Too verbose** (approximately 150 tokens):
```markdown
## Extract PDF text
PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but
pdfplumber is recommended because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...
```
The concise version assumes Claude knows what PDFs are and how libraries work.
### Set appropriate degrees of freedom
Match the level of specificity to the task's fragility and variability.
**High freedom** (text-based instructions):
Use when:
- Multiple approaches are valid
- Decisions depend on context
- Heuristics guide the approach
Example:
```markdown
## Code review process
1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify adherence to project conventions
```
**Medium freedom** (pseudocode or scripts with parameters):
Use when:
- A preferred pattern exists
- Some variation is acceptable
- Configuration affects behavior
Example:
````markdown
## Generate report
Use this template and customize as needed:
```python
def generate_report(data, format="markdown", include_charts=True):
# Process data
# Generate output in specified format
# Optionally include visualizations
```
````
**Low freedom** (specific scripts, few or no parameters):
Use when:
- Operations are fragile and error-prone
- Consistency is critical
- A specific sequence must be followed
Example:
````markdown
## Database migration
Run exactly this script:
```bash
python scripts/migrate.py --verify --backup
```
Do not modify the command or add additional flags.
````
**Analogy:** Think of Claude as a robot exploring a path:
- **Narrow bridge with cliffs on both sides:** There's only one safe way forward. Provide specific guardrails and exact instructions (low freedom). Example: database migrations that must run in exact sequence.
- **Open field with no hazards:** Many paths lead to success. Give general direction and trust Claude to find the best route (high freedom). Example: code reviews where context determines the best approach.
### Test with all models you plan to use
Skills act as additions to models, so effectiveness depends on the underlying model. Test your Skill with all the models you plan to use it with.
**Testing considerations by model:**
- **Claude Haiku** (fast, economical): Does the Skill provide enough guidance?
- **Claude Sonnet** (balanced): Is the Skill clear and efficient?
- **Claude Opus** (powerful reasoning): Does the Skill avoid over-explaining?
What works perfectly for Opus might need more detail for Haiku. If you plan to use your Skill across multiple models, aim for instructions that work well with all of them.
## Skill structure
<Note>
**YAML Frontmatter:** The SKILL.md frontmatter requires two fields:
`name`:
- Maximum 64 characters
- Must contain only lowercase letters, numbers, and hyphens
- Cannot contain XML tags
- Cannot contain reserved words: "anthropic", "claude"
`description`:
- Must be non-empty
- Maximum 1024 characters
- Cannot contain XML tags
- Should describe what the Skill does and when to use it
For complete Skill structure details, see the [Skills overview](/docs/en/agents-and-tools/agent-skills/overview#skill-structure).
</Note>
### Naming conventions
Use consistent naming patterns to make Skills easier to reference and discuss. Consider using **gerund form** (verb + -ing) for Skill names, as this clearly describes the activity or capability the Skill provides.
Remember that the `name` field must use lowercase letters, numbers, and hyphens only.
**Good naming examples (gerund form):**
- `processing-pdfs`
- `analyzing-spreadsheets`
- `managing-databases`
- `testing-code`
- `writing-documentation`
**Acceptable alternatives:**
- Noun phrases: `pdf-processing`, `spreadsheet-analysis`
- Action-oriented: `process-pdfs`, `analyze-spreadsheets`
**Avoid:**
- Vague names: `helper`, `utils`, `tools`
- Overly generic: `documents`, `data`, `files`
- Reserved words: `anthropic-helper`, `claude-tools`
- Inconsistent patterns within your skill collection
Consistent naming makes it easier to:
- Reference Skills in documentation and conversations
- Understand what a Skill does at a glance
- Organize and search through multiple Skills
- Maintain a professional, cohesive skill library
### Writing effective descriptions
The `description` field enables Skill discovery and should include both what the Skill does and when to use it.
<Warning>
**Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.
- **Good:** "Processes Excel files and generates reports"
- **Avoid:** "I can help you process Excel files"
- **Avoid:** "You can use this to process Excel files"
</Warning>
**Be specific and include key terms**. Include both what the Skill does and specific triggers/contexts for when to use it.
Each Skill has exactly one description field. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for Claude to know when to select this Skill, while the rest of SKILL.md provides the implementation details.
Effective examples:
**PDF Processing skill:**
```yaml
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
```
**Excel Analysis skill:**
```yaml
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
```
**Git Commit Helper skill:**
```yaml
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
```
Avoid vague descriptions like these:
```yaml
description: Helps with documents
```
```yaml
description: Processes data
```
```yaml
description: Does stuff with files
```
### Progressive disclosure patterns
SKILL.md serves as an overview that points Claude to detailed materials as needed, like a table of contents in an onboarding guide. For an explanation of how progressive disclosure works, see [How Skills work](/docs/en/agents-and-tools/agent-skills/overview#how-skills-work) in the overview.
**Practical guidance:**
- Keep SKILL.md body under 500 lines for optimal performance
- Split content into separate files when approaching this limit
- Use the patterns below to organize instructions, code, and resources effectively
#### Visual overview: From simple to complex
A basic Skill starts with just a SKILL.md file containing metadata and instructions:
As your Skill grows, you can bundle additional content that Claude loads only when needed:
The complete Skill directory structure might look like this:
```text
pdf/
├── SKILL.md # Main instructions (loaded when triggered)
├── FORMS.md # Form-filling guide (loaded as needed)
├── reference.md # API reference (loaded as needed)
├── examples.md # Usage examples (loaded as needed)
└── scripts/
├── analyze_form.py # Utility script (executed, not loaded)
├── fill_form.py # Form filling script
└── validate.py # Validation script
```
#### Pattern 1: High-level guide with references
````markdown
---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
# PDF Processing
## Quick start
Extract text with pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
## Advanced features
**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
````
Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
#### Pattern 2: Domain-specific organization
For Skills with multiple domains, organize content by domain to avoid loading irrelevant context. When a user asks about sales metrics, Claude only needs to read sales-related schemas, not finance or marketing data. This keeps token usage low and context focused.
```text
bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
├── finance.md (revenue, billing metrics)
├── sales.md (opportunities, pipeline)
├── product.md (API usage, features)
└── marketing.md (campaigns, attribution)
```
````markdown SKILL.md
# BigQuery Data Analysis
## Available datasets
**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md)
## Quick search
Find specific metrics using grep:
```bash
grep -i "revenue" reference/finance.md
grep -i "pipeline" reference/sales.md
grep -i "api usage" reference/product.md
```
````
#### Pattern 3: Conditional details
Show basic content, link to advanced content:
```markdown
# DOCX Processing
## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
## Editing documents
For simple edits, modify the XML directly.
**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)
```
Claude reads REDLINING.md or OOXML.md only when the user needs those features.
### Avoid deeply nested references
Claude may partially read files when they're referenced from other referenced files. When encountering nested references, Claude might use commands like `head -100` to preview content rather than reading entire files, resulting in incomplete information.
**Keep references one level deep from SKILL.md**. All reference files should link directly from SKILL.md to ensure Claude reads complete files when needed.
**Bad example: Too deep**:
```markdown
# SKILL.md
See [advanced.md](advanced.md)...
# advanced.md
See [details.md](details.md)...
# details.md
Here's the actual information...
```
**Good example: One level deep**:
```markdown
# SKILL.md
**Basic usage**: [instructions in SKILL.md]
**Advanced features**: See [advanced.md](advanced.md)
**API reference**: See [reference.md](reference.md)
**Examples**: See [examples.md](examples.md)
```
### Structure longer reference files with table of contents
For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads.
**Example:**
```markdown
# API Reference
## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples
## Authentication and setup
...
## Core methods
...
```
Claude can then read the complete file or jump to specific sections as needed.
For details on how this filesystem-based architecture enables progressive disclosure, see the [Runtime environment](#runtime-environment) section in the Advanced section below.
## Workflows and feedback loops
### Use workflows for complex tasks
Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist that Claude can copy into its response and check off as it progresses.
**Example 1: Research synthesis workflow** (for Skills without code):
````markdown
## Research synthesis workflow
Copy this checklist and track your progress:
```
Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations
```
**Step 1: Read all source documents**
Review each document in the `sources/` directory. Note the main arguments and supporting evidence.
**Step 2: Identify key themes**
Look for patterns across sources. What themes appear repeatedly? Where do sources agree or disagree?
**Step 3: Cross-reference claims**
For each major claim, verify it appears in the source material. Note which source supports each point.
**Step 4: Create structured summary**
Organize findings by theme. Include:
- Main claim
- Supporting evidence from sources
- Conflicting viewpoints (if any)
**Step 5: Verify citations**
Check that every claim references the correct source document. If citations are incomplete, return to Step 3.
````
This example shows how workflows apply to analysis tasks that don't require code. The checklist pattern works for any complex, multi-step process.
**Example 2: PDF form filling workflow** (for Skills with code):
````markdown
## PDF form filling workflow
Copy this checklist and check off items as you complete them:
```
Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)
```
**Step 1: Analyze the form**
Run: `python scripts/analyze_form.py input.pdf`
This extracts form fields and their locations, saving to `fields.json`.
**Step 2: Create field mapping**
Edit `fields.json` to add values for each field.
**Step 3: Validate mapping**
Run: `python scripts/validate_fields.py fields.json`
Fix any validation errors before continuing.
**Step 4: Fill the form**
Run: `python scripts/fill_form.py input.pdf fields.json output.pdf`
**Step 5: Verify output**
Run: `python scripts/verify_output.py output.pdf`
If verification fails, return to Step 2.
````
Clear steps prevent Claude from skipping critical validation. The checklist helps both Claude and you track progress through multi-step workflows.
### Implement feedback loops
**Common pattern:** Run validator → fix errors → repeat
This pattern greatly improves output quality.
**Example 1: Style guide compliance** (for Skills without code):
```markdown
## Content review process
1. Draft your content following the guidelines in STYLE_GUIDE.md
2. Review against the checklist:
- Check terminology consistency
- Verify examples follow the standard format
- Confirm all required sections are present
3. If issues found:
- Note each issue with specific section reference
- Revise the content
- Review the checklist again
4. Only proceed when all requirements are met
5. Finalize and save the document
```
This shows the validation loop pattern using reference documents instead of scripts. The "validator" is STYLE_GUIDE.md, and Claude performs the check by reading and comparing.
**Example 2: Document editing process** (for Skills with code):
```markdown
## Document editing process
1. Make your edits to `word/document.xml`
2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
3. If validation fails:
- Review the error message carefully
- Fix the issues in the XML
- Run validation again
4. **Only proceed when validation passes**
5. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Test the output document
```
The validation loop catches errors early.
## Content guidelines
### Avoid time-sensitive information
Don't include information that will become outdated:
**Bad example: Time-sensitive** (will become wrong):
```markdown
If you're doing this before August 2025, use the old API.
After August 2025, use the new API.
```
**Good example** (use "old patterns" section):
```markdown
## Current method
Use the v2 API endpoint: `api.example.com/v2/messages`
## Old patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API used: `api.example.com/v1/messages`
This endpoint is no longer supported.
</details>
```
The old patterns section provides historical context without cluttering the main content.
### Use consistent terminology
Choose one term and use it throughout the Skill:
**Good - Consistent:**
- Always "API endpoint"
- Always "field"
- Always "extract"
**Bad - Inconsistent:**
- Mix "API endpoint", "URL", "API route", "path"
- Mix "field", "box", "element", "control"
- Mix "extract", "pull", "get", "retrieve"
Consistency helps Claude understand and follow instructions.
## Common patterns
### Template pattern
Provide templates for output format. Match the level of strictness to your needs.
**For strict requirements** (like API responses or data formats):
````markdown
## Report structure
ALWAYS use this exact template structure:
```markdown
# [Analysis Title]
## Executive summary
[One-paragraph overview of key findings]
## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data
## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
```
````
**For flexible guidance** (when adaptation is useful):
````markdown
## Report structure
Here is a sensible default format, but use your best judgment based on the analysis:
```markdown
# [Analysis Title]
## Executive summary
[Overview]
## Key findings
[Adapt sections based on what you discover]
## Recommendations
[Tailor to the specific context]
```
Adjust sections as needed for the specific analysis type.
````
### Examples pattern
For Skills where output quality depends on seeing examples, provide input/output pairs just like in regular prompting:
````markdown
## Commit message format
Generate commit messages following these examples:
**Example 1:**
Input: Added user authentication with JWT tokens
Output:
```
feat(auth): implement JWT-based authentication
Add login endpoint and token validation middleware
```
**Example 2:**
Input: Fixed bug where dates displayed incorrectly in reports
Output:
```
fix(reports): correct date formatting in timezone conversion
Use UTC timestamps consistently across report generation
```
**Example 3:**
Input: Updated dependencies and refactored error handling
Output:
```
chore: update dependencies and refactor error handling
- Upgrade lodash to 4.17.21
- Standardize error response format across endpoints
```
Follow this style: type(scope): brief description, then detailed explanation.
````
Examples help Claude understand the desired style and level of detail more clearly than descriptions alone.
### Conditional workflow pattern
Guide Claude through decision points:
```markdown
## Document modification workflow
1. Determine the modification type:
**Creating new content?** → Follow "Creation workflow" below
**Editing existing content?** → Follow "Editing workflow" below
2. Creation workflow:
- Use docx-js library
- Build document from scratch
- Export to .docx format
3. Editing workflow:
- Unpack existing document
- Modify XML directly
- Validate after each change
- Repack when complete
```
<Tip>
If workflows become large or complicated with many steps, consider pushing them into separate files and tell Claude to read the appropriate file based on the task at hand.
</Tip>
## Evaluation and iteration
### Build evaluations first
**Create evaluations BEFORE writing extensive documentation.** This ensures your Skill solves real problems rather than documenting imagined ones.
**Evaluation-driven development:**
1. **Identify gaps:** Run Claude on representative tasks without a Skill. Document specific failures or missing context
2. **Create evaluations:** Build three scenarios that test these gaps
3. **Establish baseline:** Measure Claude's performance without the Skill
4. **Write minimal instructions:** Create just enough content to address the gaps and pass evaluations
5. **Iterate:** Execute evaluations, compare against baseline, and refine
This approach ensures you're solving actual problems rather than anticipating requirements that may never materialize.
**Evaluation structure:**
```json
{
"skills": ["pdf-processing"],
"query": "Extract all text from this PDF file and save it to output.txt",
"files": ["test-files/document.pdf"],
"expected_behavior": [
"Successfully reads the PDF file using an appropriate PDF processing library or command-line tool",
"Extracts text content from all pages in the document without missing any pages",
"Saves the extracted text to a file named output.txt in a clear, readable format"
]
}
```
<Note>
This example demonstrates a data-driven evaluation with a simple testing rubric. There is not currently a built-in way to run these evaluations. Users can create their own evaluation system. Evaluations are your source of truth for measuring Skill effectiveness.
</Note>
### Develop Skills iteratively with Claude
The most effective Skill development process involves Claude itself. Work with one instance of Claude ("Claude A") to create a Skill that is used by other instances ("Claude B"). Claude A helps you design and refine instructions, while Claude B tests them in real tasks. This works because Claude models understand both how to write effective agent instructions and what information agents need.
**Creating a new Skill:**
1. **Complete a task without a Skill:** Work through a problem with Claude A using normal prompting. As you work, you'll naturally provide context, explain preferences, and share procedural knowledge. Notice what information you repeatedly provide.
2. **Identify the reusable pattern:** After completing the task, identify what context you provided that would be useful for similar future tasks.
**Example:** If you worked through a BigQuery analysis, you might have provided table names, field definitions, filtering rules (like "always exclude test accounts"), and common query patterns.
3. **Ask Claude A to create a Skill:** "Create a Skill that captures this BigQuery analysis pattern we just used. Include the table schemas, naming conventions, and the rule about filtering test accounts."
<Tip>
Claude models understand the Skill format and structure natively. You don't need special system prompts or a "writing skills" skill to get Claude to help create Skills. Simply ask Claude to create a Skill and it generates properly structured SKILL.md content with appropriate frontmatter and body content.
</Tip>
4. **Review for conciseness:** Check that Claude A hasn't added unnecessary explanations. Ask: "Remove the explanation about what win rate means - Claude already knows that."
5. **Improve information architecture:** Ask Claude A to organize the content more effectively. For example: "Organize this so the table schema is in a separate reference file. We might add more tables later."
6. **Test on similar tasks:** Use the Skill with Claude B (a fresh instance with the Skill loaded) on related use cases. Observe whether Claude B finds the right information, applies rules correctly, and handles the task successfully.
7. **Iterate based on observation:** If Claude B struggles or misses something, return to Claude A with specifics: "When Claude used this Skill, it forgot to filter by date for Q4. Should we add a section about date filtering patterns?"
**Iterating on existing Skills:**
The same hierarchical pattern continues when improving Skills. You alternate between:
- **Working with Claude A** (the expert who helps refine the Skill)
- **Testing with Claude B** (the agent using the Skill to perform real work)
- **Observing Claude B's behavior** and bringing insights back to Claude A
1. **Use the Skill in real workflows:** Give Claude B (with the Skill loaded) actual tasks, not test scenarios
2. **Observe Claude B's behavior:** Note where it struggles, succeeds, or makes unexpected choices
**Example observation:** "When I asked Claude B for a regional sales report, it wrote the query but forgot to filter out test accounts, even though the Skill mentions this rule."
3. **Return to Claude A for improvements:** Share the current SKILL.md and describe what you observed. Ask: "I noticed Claude B forgot to filter test accounts when I asked for a regional report. The Skill mentions filtering, but maybe it's not prominent enough?"
4. **Review Claude A's suggestions:** Claude A might suggest reorganizing to make rules more prominent, using stronger language like "MUST filter" instead of "always filter", or restructuring the workflow section.
5. **Apply and test changes:** Update the Skill with Claude A's refinements, then test again with Claude B on similar requests
6. **Repeat based on usage:** Continue this observe-refine-test cycle as you encounter new scenarios. Each iteration improves the Skill based on real agent behavior, not assumptions.
**Gathering team feedback:**
1. Share Skills with teammates and observe their usage
2. Ask: Does the Skill activate when expected? Are instructions clear? What's missing?
3. Incorporate feedback to address blind spots in your own usage patterns
**Why this approach works:** Claude A understands agent needs, you provide domain expertise, Claude B reveals gaps through real usage, and iterative refinement improves Skills based on observed behavior rather than assumptions.
### Observe how Claude navigates Skills
As you iterate on Skills, pay attention to how Claude actually uses them in practice. Watch for:
- **Unexpected exploration paths:** Does Claude read files in an order you didn't anticipate? This might indicate your structure isn't as intuitive as you thought
- **Missed connections:** Does Claude fail to follow references to important files? Your links might need to be more explicit or prominent
- **Overreliance on certain sections:** If Claude repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead
- **Ignored content:** If Claude never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions
Iterate based on these observations rather than assumptions. The 'name' and 'description' in your Skill's metadata are particularly critical. Claude uses these when deciding whether to trigger the Skill in response to the current task. Make sure they clearly describe what the Skill does and when it should be used.
## Anti-patterns to avoid
### Avoid Windows-style paths
Always use forward slashes in file paths, even on Windows:
- ✓ **Good:** `scripts/helper.py`, `reference/guide.md`
- ✗ **Avoid:** `scripts\helper.py`, `reference\guide.md`
Unix-style paths work across all platforms, while Windows-style paths cause errors on Unix systems.
### Avoid offering too many options
Don't present multiple approaches unless necessary:
````markdown
**Bad example: Too many choices** (confusing):
"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."
**Good example: Provide a default** (with escape hatch):
"Use pdfplumber for text extraction:
```python
import pdfplumber
```
For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."
````
## Advanced: Skills with executable code
The sections below focus on Skills that include executable scripts. If your Skill uses only markdown instructions, skip to [Checklist for effective Skills](#checklist-for-effective-skills).
### Solve, don't punt
When writing scripts for Skills, handle error conditions rather than punting to Claude.
**Good example: Handle errors explicitly:**
```python nocheck
def process_file(path):
"""Process a file, creating it if it doesn't exist."""
try:
with open(path) as f:
return f.read()
except FileNotFoundError:
# Create file with default content instead of failing
print(f"File {path} not found, creating default")
with open(path, "w") as f:
f.write("")
return ""
except PermissionError:
# Provide alternative instead of failing
print(f"Cannot access {path}, using default")
return ""
```
**Bad example: Punt to Claude:**
```python nocheck
def process_file(path):
# Just fail and let Claude figure it out
return open(path).read()
```
Configuration parameters should also be justified and documented to avoid "voodoo constants" (Ousterhout's law). If you don't know the right value, how will Claude determine it?
**Good example: Self-documenting:**
```python nocheck
# HTTP requests typically complete within 30 seconds
# Longer timeout accounts for slow connections
REQUEST_TIMEOUT = 30
# Three retries balances reliability vs speed
# Most intermittent failures resolve by the second retry
MAX_RETRIES = 3
```
**Bad example: Magic numbers:**
```python nocheck
TIMEOUT = 47 # Why 47?
RETRIES = 5 # Why 5?
```
### Provide utility scripts
Even if Claude could write a script, pre-made scripts offer advantages:
**Benefits of utility scripts:**
- More reliable than generated code
- Save tokens (no need to include code in context)
- Save time (no code generation required)
- Ensure consistency across uses
The diagram above shows how executable scripts work alongside instruction files. The instruction file (forms.md) references the script, and Claude can execute it without loading its contents into context.
**Important distinction:** Make clear in your instructions whether Claude should:
- **Execute the script** (most common): "Run `analyze_form.py` to extract fields"
- **Read it as reference** (for complex logic): "See `analyze_form.py` for the field extraction algorithm"
For most utility scripts, execution is preferred because it's more reliable and efficient. See the [Runtime environment](#runtime-environment) section below for details on how script execution works.
**Example:**
````markdown
## Utility scripts
**analyze_form.py**: Extract all form fields from PDF
```bash
python scripts/analyze_form.py input.pdf > fields.json
```
Output format:
```json
{
"field_name": {"type": "text", "x": 100, "y": 200},
"signature": {"type": "sig", "x": 150, "y": 500}
}
```
**validate_boxes.py**: Check for overlapping bounding boxes
```bash
python scripts/validate_boxes.py fields.json
# Returns: "OK" or lists conflicts
```
**fill_form.py**: Apply field values to PDF
```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```
````
### Use visual analysis
When inputs can be rendered as images, have Claude analyze them:
````markdown
## Form layout analysis
1. Convert PDF to images:
```bash
python scripts/pdf_to_images.py form.pdf
```
2. Analyze each page image to identify form fields
3. Claude can see field locations and types visually
````
<Note>
In this example, you'd need to write the `pdf_to_images.py` script.
</Note>
Claude's vision capabilities help understand layouts and structures.
### Create verifiable intermediate outputs
When Claude performs complex, open-ended tasks, it can make mistakes. The "plan-validate-execute" pattern catches errors early by having Claude first create a plan in a structured format, then validate that plan with a script before executing it.
**Example:** Imagine asking Claude to update 50 form fields in a PDF based on a spreadsheet. Without validation, Claude might reference non-existent fields, create conflicting values, miss required fields, or apply updates incorrectly.
**Solution:** Use the workflow pattern shown above (PDF form filling), but add an intermediate `changes.json` file that gets validated before applying changes. The workflow becomes: analyze → **create plan file** → **validate plan** → execute → verify.
**Why this pattern works:**
- **Catches errors early:** Validation finds problems before changes are applied
- **Machine-verifiable:** Scripts provide objective verification
- **Reversible planning:** Claude can iterate on the plan without touching originals
- **Clear debugging:** Error messages point to specific problems
**When to use:** Batch operations, destructive changes, complex validation rules, high-stakes operations.
**Implementation tip:** Make validation scripts verbose with specific error messages like "Field 'signature_date' not found. Available fields: customer_name, order_total, signature_date_signed" to help Claude fix issues.
### Package dependencies
Skills run in the code execution environment with platform-specific limitations:
- **claude.ai:** Can install packages from npm and PyPI and pull from GitHub repositories
- **Claude API:** Has no network access and no runtime package installation
List required packages in your SKILL.md and verify they're available in the [code execution tool documentation](/docs/en/agents-and-tools/tool-use/code-execution-tool).
### Runtime environment
Skills run in a code execution environment with filesystem access, bash commands, and code execution capabilities. For the conceptual explanation of this architecture, see [The Skills architecture](/docs/en/agents-and-tools/agent-skills/overview#the-skills-architecture) in the overview.
**How this affects your authoring:**
**How Claude accesses Skills:**
1. **Metadata pre-loaded:** At startup, the name and description from all Skills' YAML frontmatter are loaded into the system prompt
2. **Files read on-demand:** Claude uses bash Read tools to access SKILL.md and other files from the filesystem when needed
3. **Scripts executed efficiently:** Utility scripts can be executed via bash without loading their full contents into context. Only the script's output consumes tokens
4. **No context penalty for large files:** Reference files, data, or documentation don't consume context tokens until actually read
- **File paths matter:** Claude navigates your skill directory like a filesystem. Use forward slashes (`reference/guide.md`), not backslashes
- **Name files descriptively:** Use names that indicate content: `form_validation_rules.md`, not `doc2.md`
- **Organize for discovery:** Structure directories by domain or feature
- Good: `reference/finance.md`, `reference/sales.md`
- Bad: `docs/file1.md`, `docs/file2.md`
- **Bundle comprehensive resources:** Include complete API docs, extensive examples, large datasets; no context penalty until accessed
- **Prefer scripts for deterministic operations:** Write `validate_form.py` rather than asking Claude to generate validation code
- **Make execution intent clear:**
- "Run `analyze_form.py` to extract fields" (execute)
- "See `analyze_form.py` for the extraction algorithm" (read as reference)
- **Test file access patterns:** Verify Claude can navigate your directory structure by testing with real requests
**Example:**
```text
bigquery-skill/
├── SKILL.md (overview, points to reference files)
└── reference/
├── finance.md (revenue metrics)
├── sales.md (pipeline data)
└── product.md (usage analytics)
```
When the user asks about revenue, Claude reads SKILL.md, sees the reference to `reference/finance.md`, and invokes bash to read just that file. The sales.md and product.md files remain on the filesystem, consuming zero context tokens until needed. This filesystem-based model is what enables progressive disclosure. Claude can navigate and selectively load exactly what each task requires.
For complete details on the technical architecture, see [How Skills work](/docs/en/agents-and-tools/agent-skills/overview#how-skills-work) in the Skills overview.
### MCP tool references
If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names to avoid "tool not found" errors.
**Format:** `ServerName:tool_name`
**Example:**
```markdown
Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.
```
Where:
- `BigQuery` and `GitHub` are MCP server names
- `bigquery_schema` and `create_issue` are the tool names within those servers
Without the server prefix, Claude may fail to locate the tool, especially when multiple MCP servers are available.
### Avoid assuming tools are installed
Don't assume packages are available:
````markdown
**Bad example: Assumes installation**:
"Use the pdf library to process the file."
**Good example: Explicit about dependencies**:
"Install required package: `pip install pypdf`
Then use it:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"
````
## Technical notes
### YAML frontmatter requirements
The SKILL.md frontmatter requires `name` and `description` fields with specific validation rules:
- `name`: Maximum 64 characters, lowercase letters/numbers/hyphens only, no XML tags, no reserved words
- `description`: Maximum 1024 characters, non-empty, no XML tags
See the [Skills overview](/docs/en/agents-and-tools/agent-skills/overview#skill-structure) for complete structure details.
### Token budgets
Keep SKILL.md body under 500 lines for optimal performance. If your content exceeds this, split it into separate files using the progressive disclosure patterns described earlier. For architectural details, see the [Skills overview](/docs/en/agents-and-tools/agent-skills/overview#how-skills-work).
## Checklist for effective Skills
Before sharing a Skill, verify:
### Core quality
- [ ] Description is specific and includes key terms
- [ ] Description includes both what the Skill does and when to use it
- [ ] SKILL.md body is under 500 lines
- [ ] Additional details are in separate files (if needed)
- [ ] No time-sensitive information (or in "old patterns" section)
- [ ] Consistent terminology throughout
- [ ] Examples are concrete, not abstract
- [ ] File references are one level deep
- [ ] Progressive disclosure used appropriately
- [ ] Workflows have clear steps
### Code and scripts
- [ ] Scripts solve problems rather than punt to Claude
- [ ] Error handling is explicit and helpful
- [ ] No "voodoo constants" (all values justified)
- [ ] Required packages listed in instructions and verified as available
- [ ] Scripts have clear documentation
- [ ] No Windows-style paths (all forward slashes)
- [ ] Validation/verification steps for critical operations
- [ ] Feedback loops included for quality-critical tasks
### Testing
- [ ] At least three evaluations created
- [ ] Tested with Haiku, Sonnet, and Opus
- [ ] Tested with real usage scenarios
- [ ] Team feedback incorporated (if applicable)
## Next steps
<CardGroup cols={2}>
<Card
title="Get started with Agent Skills"
icon="rocket"
href="/docs/en/agents-and-tools/agent-skills/quickstart"
>
Create your first Skill
</Card>
<Card
title="Use Skills in Claude Code"
icon="terminal"
href="https://code.claude.com/docs/en/skills"
>
Create and manage Skills in Claude Code
</Card>
<Card
title="Use Skills with the API"
icon="code"
href="/docs/en/build-with-claude/skills-guide"
>
Upload and use Skills programmatically
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-agent-skills-enterprise-6168dda2cc.md
# Skills for enterprise
Governance, security review, evaluation, and organizational guidance for deploying Agent Skills at enterprise scale.
---
This guide is for enterprise admins and architects who need to govern Agent Skills across an organization. It covers how to vet, evaluate, deploy, and manage Skills at scale. For authoring guidance, see [best practices](/docs/en/agents-and-tools/agent-skills/best-practices). For architecture details, see the [Skills overview](/docs/en/agents-and-tools/agent-skills/overview).
## Security review and vetting
Deploying Skills in an enterprise requires answering two distinct questions:
1. **Are Skills safe in general?** See the [security considerations](/docs/en/agents-and-tools/agent-skills/overview#security-considerations) section in the overview for platform-level security details.
2. **How do I vet a specific Skill?** Use the risk assessment and review checklist below.
### Risk tier assessment
Evaluate each Skill against these risk indicators before approving deployment:
| Risk indicator | What to look for | Concern level |
|---|---|---|
| Code execution | Scripts in the Skill directory (`*.py`, `*.sh`, `*.js`) | High: scripts run with full environment access |
| Instruction manipulation | Directives to ignore safety rules, hide actions from users, or alter Claude's behavior conditionally | High: can bypass security controls |
| MCP server references | Instructions referencing MCP tools (`ServerName:tool_name`) | High: extends access beyond the Skill itself |
| Network access patterns | URLs, API endpoints, `fetch`, `curl`, or `requests` calls | High: potential data exfiltration vector |
| Hardcoded credentials | API keys, tokens, or passwords in Skill files or scripts | High: secrets exposed in Git history and context window |
| File system access scope | Paths outside the Skill directory, broad glob patterns, path traversal (`../`) | Medium: may access unintended data |
| Tool invocations | Instructions directing Claude to use bash, file operations, or other tools | Medium: review what operations are performed |
### Review checklist
Before deploying any Skill from a third party or internal contributor, complete these steps:
1. **Read all Skill directory content.** Review SKILL.md, all referenced markdown files, and any bundled scripts or resources.
2. **Verify script behavior matches stated purpose.** Run scripts in a sandboxed environment and confirm outputs align with the Skill's description.
3. **Check for adversarial instructions.** Look for directives that tell Claude to ignore safety rules, hide actions from users, exfiltrate data through responses, or alter behavior based on specific inputs.
4. **Check for external URL fetches or network calls.** Search scripts and instructions for network access patterns (`http`, `requests.get`, `urllib`, `curl`, `fetch`).
5. **Verify no hardcoded credentials.** Check for API keys, tokens, or passwords in Skill files. Credentials should use environment variables or secure credential stores, never appear in Skill content.
6. **Identify tools and commands the Skill instructs Claude to invoke.** List all bash commands, file operations, and tool references. Consider the combined risk when a Skill uses both file-read and network tools together.
7. **Confirm redirect destinations.** If the Skill references external URLs, verify they point to expected domains.
8. **Verify no data exfiltration patterns.** Look for instructions that read sensitive data and then write, send, or encode it for external transmission, including through Claude's conversational responses.
<Warning>
Never deploy Skills from untrusted sources without a full audit. A malicious Skill can direct Claude to execute arbitrary code, access sensitive files, or transmit data externally. Treat Skill installation with the same rigor as installing software on production systems.
</Warning>
## Evaluating Skills before deployment
Skills can degrade agent performance if they trigger incorrectly, conflict with other Skills, or provide poor instructions. Require evaluation before any production deployment.
### What to evaluate
Establish approval gates for these dimensions before deploying any Skill:
| Dimension | What it measures | Example failure |
|---|---|---|
| Triggering accuracy | Does the Skill activate for the right queries and stay inactive for unrelated ones? | Skill triggers on every spreadsheet mention, even when the user just wants to discuss data |
| Isolation behavior | Does the Skill work correctly on its own? | Skill references files that don't exist in its directory |
| Coexistence | Does adding this Skill degrade other Skills? | New Skill's description is too broad, stealing triggers from existing Skills |
| Instruction following | Does Claude follow the Skill's instructions accurately? | Claude skips validation steps or uses wrong libraries |
| Output quality | Does the Skill produce correct, useful results? | Generated reports have formatting errors or missing data |
### Evaluation requirements
Require Skill authors to submit evaluation suites with 3-5 representative queries per Skill, covering cases where the Skill should trigger, should not trigger, and ambiguous edge cases. Require testing across the models your organization uses (Haiku, Sonnet, Opus), since Skill effectiveness varies by model.
For detailed guidance on building evaluations, see [evaluation and iteration](/docs/en/agents-and-tools/agent-skills/best-practices#evaluation-and-iteration) in best practices. For general evaluation methodology, see [develop test cases](/docs/en/test-and-evaluate/develop-tests).
### Using evaluations for lifecycle decisions
Evaluation results signal when to act:
- **Declining trigger accuracy:** Update the Skill's description or instructions
- **Coexistence conflicts:** Consolidate overlapping Skills or narrow descriptions
- **Consistently low output quality:** Rewrite instructions or add validation steps
- **Persistent failures across updates:** Deprecate the Skill
## Skill lifecycle management
<Steps>
<Step title="Plan">
Identify workflows that are repetitive, error-prone, or require specialized knowledge. Map these to organizational roles and determine which are candidates for Skills.
</Step>
<Step title="Create and review">
Ensure the Skill author follows [best practices](/docs/en/agents-and-tools/agent-skills/best-practices). Require a security review using the [review checklist](#review-checklist) above. Require an evaluation suite before approval. Establish separation of duties: Skill authors should not be their own reviewers.
</Step>
<Step title="Test">
Require evaluations in isolation (Skill alone) and alongside existing Skills (coexistence testing). Verify triggering accuracy, output quality, and absence of regressions across your active Skill set before approving for production.
</Step>
<Step title="Deploy">
Upload via the Skills API for workspace-wide access. See [Using Skills with the API](/docs/en/build-with-claude/skills-guide) for upload and version management. Document the Skill in your internal registry with purpose, owner, and version.
</Step>
<Step title="Monitor">
Track usage patterns and collect feedback from users. Re-run evaluations periodically to detect drift or regressions as workflows and models evolve. Usage analytics are not currently available via the Skills API. Implement application-level logging to track which Skills are included in requests.
</Step>
<Step title="Iterate or deprecate">
Require the full evaluation suite to pass before promoting new versions. Update Skills when workflows change or evaluation scores decline. Deprecate Skills when evaluations consistently fail or the workflow is retired.
</Step>
</Steps>
## Organizing Skills at scale
### Recall limits
As a general guideline, limit the number of Skills loaded simultaneously to maintain reliable recall accuracy. Each Skill's metadata (name and description) competes for attention in the system prompt. With too many Skills active, Claude may fail to select the right Skill or miss relevant ones entirely. Use your evaluation suite to measure recall accuracy as you add Skills, and stop adding when performance degrades.
Note that API requests support a maximum of 8 Skills per request (see [Using Skills with the API](/docs/en/build-with-claude/skills-guide)). If a role requires more Skills than a single request supports, consider consolidating narrow Skills into broader ones or routing requests to different Skill sets based on task type.
### Start specific, consolidate later
Encourage teams to start with narrow, workflow-specific Skills rather than broad, multi-purpose ones. As patterns emerge across your organization, consolidate related Skills into role-based bundles.
<Tip>
Use evaluations to decide when to consolidate. Merge narrow Skills into a broader one only when the consolidated Skill's evaluations confirm equivalent performance to the individual Skills it replaces.
</Tip>
**Example progression**:
- Start: `formatting-sales-reports`, `querying-pipeline-data`, `updating-crm-records`
- Consolidate: `sales-operations` (when evals confirm equivalent performance)
### Naming and cataloging
Use consistent naming conventions across your organization. The [naming conventions](/docs/en/agents-and-tools/agent-skills/best-practices#naming-conventions) section in best practices provides formatting guidance.
Maintain an internal registry for each Skill with:
- **Purpose**: What workflow the Skill supports
- **Owner**: Team or individual responsible for maintenance
- **Version**: Current deployed version
- **Dependencies**: MCP servers, packages, or external services required
- **Evaluation status**: Last evaluation date and results
### Role-based bundles
Group Skills by organizational role to keep each user's active Skill set focused:
- **Sales team**: CRM operations, pipeline reporting, proposal generation
- **Engineering**: Code review, deployment workflows, incident response
- **Finance**: Report generation, data validation, audit preparation
Each role-based bundle should contain only the Skills relevant to that role's daily workflows.
## Distribution and version control
### Source control
Store Skill directories in Git for history tracking, code review via pull requests, and rollback capability. Each Skill directory (containing SKILL.md and any bundled files) maps naturally to a Git-tracked folder.
### API-based distribution
The Skills API provides workspace-scoped distribution. Skills uploaded via the API are available to all workspace members. See [Using Skills with the API](/docs/en/build-with-claude/skills-guide) for upload, versioning, and management endpoints.
### Versioning strategy
- **Production**: Pin Skills to specific versions. Run the full evaluation suite before promoting a new version. Treat every update as a new deployment requiring full security review.
- **Development and testing**: Use latest versions to validate changes before production promotion.
- **Rollback plan**: Maintain the previous version as a fallback. If a new version fails evaluations in production, revert to the last known-good version immediately.
- **Integrity verification**: Compute checksums of reviewed Skills and verify them at deployment time. Use signed commits in your Skill repository to ensure provenance.
### Cross-surface considerations
<Warning>
Custom Skills do not sync across surfaces. Skills uploaded to the API are not available on claude.ai or in Claude Code, and vice versa. Each surface requires separate uploads and management.
</Warning>
Maintain Skill source files in Git as the single source of truth. If your organization deploys Skills across multiple surfaces, implement your own synchronization process to keep them consistent. For full details, see [cross-surface availability](/docs/en/agents-and-tools/agent-skills/overview#cross-surface-availability).
## Next steps
<CardGroup cols={2}>
<Card
title="Agent Skills overview"
icon="book-open"
href="/docs/en/agents-and-tools/agent-skills/overview"
>
Architecture and platform details
</Card>
<Card
title="Best practices"
icon="lightbulb"
href="/docs/en/agents-and-tools/agent-skills/best-practices"
>
Authoring guidance for Skill creators
</Card>
<Card
title="Using Skills with the API"
icon="code"
href="/docs/en/build-with-claude/skills-guide"
>
Upload and manage Skills programmatically
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-agent-skills-overview-a6ba167cbe.md
# Agent Skills
Agent Skills are modular capabilities that extend Claude's functionality. Each Skill packages instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant.
---
<Note>
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.
</Note>
## Why use Skills
Skills are reusable, filesystem-based resources that provide Claude with domain-specific expertise: workflows, context, and best practices that transform general-purpose agents into specialists. Unlike prompts (conversation-level instructions for one-off tasks), Skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations.
**Key benefits**:
- **Specialize Claude**: Tailor capabilities for domain-specific tasks
- **Reduce repetition**: Create once, use automatically
- **Compose capabilities**: Combine Skills to build complex workflows
<Note>
For a deep dive into the architecture and real-world applications of Agent Skills, read our engineering blog: [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).
</Note>
## Using Skills
Anthropic provides pre-built Agent Skills for common document tasks (PowerPoint, Excel, Word, PDF), and you can create your own custom Skills. Both work the same way. Claude automatically uses them when relevant to your request.
**Pre-built Agent Skills** are available to all users on claude.ai and via the Claude API. See the [Available Skills](#available-skills) section below for the complete list.
**Custom Skills** let you package domain expertise and organizational knowledge. They're available across Claude's products: create them in Claude Code, upload them via the API, or add them in claude.ai settings.
<Note>
**Get started:**
- For pre-built Agent Skills: See the [quickstart tutorial](/docs/en/agents-and-tools/agent-skills/quickstart) to start using PowerPoint, Excel, Word, and PDF skills in the API
- For custom Skills: See the [Agent Skills Cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction) to learn how to create your own Skills
</Note>
## How Skills work
Skills leverage Claude's VM environment to provide capabilities beyond what's possible with prompts alone. Claude operates in a virtual machine with filesystem access, allowing Skills to exist as directories containing instructions, executable code, and reference materials, organized like an onboarding guide you'd create for a new team member.
This filesystem-based architecture enables **progressive disclosure**: Claude loads information in stages as needed, rather than consuming context upfront.
### Three types of Skill content, three levels of loading
Skills can contain three types of content, each loaded at different times:
### Level 1: Metadata (always loaded)
**Content type: Instructions**. The Skill's YAML frontmatter provides discovery information:
```yaml
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
```
Claude loads this metadata at startup and includes it in the system prompt. This lightweight approach means you can install many Skills without context penalty; Claude only knows each Skill exists and when to use it.
### Level 2: Instructions (loaded when triggered)
**Content type: Instructions**. The main body of SKILL.md contains procedural knowledge: workflows, best practices, and guidance:
````markdown
# PDF Processing
## Quick start
Use pdfplumber to extract text from PDFs:
```python
import pdfplumber
with pdfplumber.open("document.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
For advanced form filling, see [FORMS.md](FORMS.md).
````
When you request something that matches a Skill's description, Claude reads SKILL.md from the filesystem via bash. Only then does this content enter the context window.
### Level 3: Resources and code (loaded as needed)
**Content types: Instructions, code, and resources**. Skills can bundle additional materials:
```text
pdf-skill/
├── SKILL.md (main instructions)
├── FORMS.md (form-filling guide)
├── REFERENCE.md (detailed API reference)
└── scripts/
└── fill_form.py (utility script)
```
**Instructions**: Additional markdown files (FORMS.md, REFERENCE.md) containing specialized guidance and workflows
**Code**: Executable scripts (fill_form.py, validate.py) that Claude runs via bash; scripts provide deterministic operations without consuming context
**Resources**: Reference materials like database schemas, API documentation, templates, or examples
Claude accesses these files only when referenced. The filesystem model means each content type has different strengths: instructions for flexible guidance, code for reliability, resources for factual lookup.
| Level | When Loaded | Token Cost | Content |
|-------|------------|------------|---------|
| **Level 1: Metadata** | Always (at startup) | ~100 tokens per Skill | `name` and `description` from YAML frontmatter |
| **Level 2: Instructions** | When Skill is triggered | Under 5k tokens | SKILL.md body with instructions and guidance |
| **Level 3+: Resources** | As needed | Effectively unlimited | Bundled files executed via bash without loading contents into context |
Progressive disclosure ensures only relevant content occupies the context window at any given time.
### The Skills architecture
Skills run in a code execution environment where Claude has filesystem access, bash commands, and code execution capabilities. Think of it like this: Skills exist as directories on a virtual machine, and Claude interacts with them using the same bash commands you'd use to navigate files on your computer.
**How Claude accesses Skill content:**
When a Skill is triggered, Claude uses bash to read SKILL.md from the filesystem, bringing its instructions into the context window. If those instructions reference other files (like FORMS.md or a database schema), Claude reads those files too using additional bash commands. When instructions mention executable scripts, Claude runs them via bash and receives only the output (the script code itself never enters context).
**What this architecture enables:**
**On-demand file access**: Claude reads only the files needed for each specific task. A Skill can include dozens of reference files, but if your task only needs the sales schema, Claude loads just that one file. The rest remain on the filesystem consuming zero tokens.
**Efficient script execution**: When Claude runs `validate_form.py`, the script's code never loads into the context window. Only the script's output (like "Validation passed" or specific error messages) consumes tokens. This makes scripts far more efficient than having Claude generate equivalent code on the fly.
**No practical limit on bundled content**: Because files don't consume context until accessed, Skills can include comprehensive API documentation, large datasets, extensive examples, or any reference materials you need. There's no context penalty for bundled content that isn't used.
This filesystem-based model is what makes progressive disclosure work. Claude navigates your Skill like you'd reference specific sections of an onboarding guide, accessing exactly what each task requires.
### Example: Loading a PDF processing skill
Here's how Claude loads and uses a PDF processing skill:
1. **Startup**: System prompt includes: `PDF Processing - Extract text and tables from PDF files, fill forms, merge documents`
2. **User request**: "Extract the text from this PDF and summarize it"
3. **Claude invokes**: `bash: read pdf-skill/SKILL.md` → Instructions loaded into context
4. **Claude determines**: Form filling is not needed, so FORMS.md is not read
5. **Claude executes**: Uses instructions from SKILL.md to complete the task
The diagram shows:
1. Default state with system prompt and skill metadata pre-loaded
2. Claude triggers the skill by reading SKILL.md via bash
3. Claude optionally reads additional bundled files like FORMS.md as needed
4. Claude proceeds with the task
This dynamic loading ensures only relevant skill content occupies the context window.
## Where Skills work
Skills are available across Claude's agent products:
### Claude API
The Claude API supports both pre-built Agent Skills and custom Skills. Both work identically: specify the relevant `skill_id` in the `container` parameter along with the code execution tool.
**Prerequisites**: Using Skills via the API requires three beta headers:
- `code-execution-2025-08-25` - Skills run in the code execution container
- `skills-2025-10-02` - Enables Skills functionality
- `files-api-2025-04-14` - Required for uploading/downloading files to/from the container
Use pre-built Agent Skills by referencing their `skill_id` (for example, `pptx`, `xlsx`), or create and upload your own via the Skills API (`/v1/skills` endpoints). Custom Skills are shared organization-wide.
To learn more, see [Use Skills with the Claude API](/docs/en/build-with-claude/skills-guide).
### Claude Code
[Claude Code](../../02-Claude-Code-CLI/claude-code-overview-claude-code-docs-c23f3e7cbb.md) supports only Custom Skills.
**Custom Skills**: Create Skills as directories with SKILL.md files. Claude discovers and uses them automatically.
Custom Skills in Claude Code are filesystem-based and don't require API uploads.
To learn more, see [Use Skills in Claude Code](../../08-Plugins-Skills/extend-claude-with-skills-claude-code-docs.md).
### Claude.ai
[Claude.ai](https://claude.ai) supports both pre-built Agent Skills and custom Skills.
**Pre-built Agent Skills**: These Skills are already working behind the scenes when you create documents. Claude uses them without requiring any setup.
**Custom Skills**: Upload your own Skills as zip files through Settings > Features. Available on Pro, Max, Team, and Enterprise plans with code execution enabled. Custom Skills are individual to each user; they are not shared organization-wide and cannot be centrally managed by admins.
To learn more about using Skills in Claude.ai, see the following resources in the Claude Help Center:
- [What are Skills?](../../02-Claude-Code-CLI/what-are-skills.md)
- [Using Skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
- [How to create custom Skills](../../02-Claude-Code-CLI/creating-custom-skills.md)
- [Teach Claude your way of working using Skills](https://support.claude.com/en/articles/12580051-teach-claude-your-way-of-working-using-skills)
## Skill structure
Every Skill requires a `SKILL.md` file with YAML frontmatter:
```yaml
---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---
# Your Skill Name
## Instructions
[Clear, step-by-step guidance for Claude to follow]
## Examples
[Concrete examples of using this Skill]
```
**Required fields**: `name` and `description`
**Field requirements**:
`name`:
- Maximum 64 characters
- Must contain only lowercase letters, numbers, and hyphens
- Cannot contain XML tags
- Cannot contain reserved words: "anthropic", "claude"
`description`:
- Must be non-empty
- Maximum 1024 characters
- Cannot contain XML tags
The `description` should include both what the Skill does and when Claude should use it. For complete authoring guidance, see the [best practices guide](/docs/en/agents-and-tools/agent-skills/best-practices).
## Security considerations
We strongly recommend using Skills only from trusted sources: those you created yourself or obtained from Anthropic. Skills provide Claude with new capabilities through instructions and code, and while this makes them powerful, it also means a malicious Skill can direct Claude to invoke tools or execute code in ways that don't match the Skill's stated purpose.
<Warning>
If you must use a Skill from an untrusted or unknown source, exercise extreme caution and thoroughly audit it before use. Depending on what access Claude has when executing the Skill, malicious Skills could lead to data exfiltration, unauthorized system access, or other security risks.
</Warning>
**Key security considerations**:
- **Audit thoroughly**: Review all files bundled in the Skill: SKILL.md, scripts, images, and other resources. Look for unusual patterns like unexpected network calls, file access patterns, or operations that don't match the Skill's stated purpose
- **External sources are risky**: Skills that fetch data from external URLs pose particular risk, as fetched content may contain malicious instructions. Even trustworthy Skills can be compromised if their external dependencies change over time
- **Tool misuse**: Malicious Skills can invoke tools (file operations, bash commands, code execution) in harmful ways
- **Data exposure**: Skills with access to sensitive data could be designed to leak information to external systems
- **Treat like installing software**: Only use Skills from trusted sources. Be especially careful when integrating Skills into production systems with access to sensitive data or critical operations
## Available Skills
### Pre-built Agent Skills
The following pre-built Agent Skills are available for immediate use:
- **PowerPoint (pptx)**: Create presentations, edit slides, analyze presentation content
- **Excel (xlsx)**: Create spreadsheets, analyze data, generate reports with charts
- **Word (docx)**: Create documents, edit content, format text
- **PDF (pdf)**: Generate formatted PDF documents and reports
These Skills are available on the Claude API and claude.ai. See the [quickstart tutorial](/docs/en/agents-and-tools/agent-skills/quickstart) to start using them in the API.
### Open-source Skills
Anthropic also publishes open-source Skills in the [skills repository](https://github.com/anthropics/skills):
- **[Claude API](/docs/en/agents-and-tools/agent-skills/claude-api-skill)**: Provides Claude with up-to-date API reference material, SDK documentation, and best practices for 8 programming languages. Bundled with Claude Code and also available for installation from the skills repository.
### Custom Skills examples
For complete examples of custom Skills, see the [Skills cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction).
## Data retention
Agent Skills is not covered by ZDR arrangements. Skill definitions and execution data are retained according to Anthropic's standard data retention policy.
For ZDR eligibility across all features, see [API and data retention](/docs/en/build-with-claude/api-and-data-retention).
## Limitations and constraints
Understanding these limitations helps you plan your Skills deployment effectively.
### Cross-surface availability
**Custom Skills do not sync across surfaces**. Skills uploaded to one surface are not automatically available on others:
- Skills uploaded to Claude.ai must be separately uploaded to the API
- Skills uploaded via the API are not available on Claude.ai
- Claude Code Skills are filesystem-based and separate from both Claude.ai and API
You'll need to manage and upload Skills separately for each surface where you want to use them.
### Sharing scope
Skills have different sharing models depending on where you use them:
- **Claude.ai**: Individual user only; each team member must upload separately
- **Claude API**: Workspace-wide; all workspace members can access uploaded Skills
- **Claude Code**: Personal (`~/.claude/skills/`) or project-based (`.claude/skills/`); can also be shared via Claude Code Plugins
Claude.ai does not currently support centralized admin management or org-wide distribution of custom Skills.
### Runtime environment constraints
The exact runtime environment available to your skill depends on the product surface where you use it.
- **Claude.ai**:
- **Varying network access**: Depending on user/admin settings, Skills may have full, partial, or no network access. For more details, see the [Create and Edit Files](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude#h_6b7e833898) support article.
- **Claude API**:
- **No network access**: Skills cannot make external API calls or access the internet
- **No runtime package installation**: Only pre-installed packages are available. You cannot install new packages during execution.
- **Pre-configured dependencies only**: Check the [code execution tool documentation](/docs/en/agents-and-tools/tool-use/code-execution-tool) for the list of available packages
- **Claude Code**:
- **Full network access**: Skills have the same network access as any other program on the user's computer
- **Global package installation discouraged**: Skills should only install packages locally in order to avoid interfering with the user's computer
Plan your Skills to work within these constraints.
## Next steps
<CardGroup cols={2}>
<Card
title="Get started with Agent Skills"
icon="graduation-cap"
href="/docs/en/agents-and-tools/agent-skills/quickstart"
>
Create your first Skill
</Card>
<Card
title="API Guide"
icon="code"
href="/docs/en/build-with-claude/skills-guide"
>
Use Skills with the Claude API
</Card>
<Card
title="Use Skills in Claude Code"
icon="terminal"
href="https://code.claude.com/docs/en/skills"
>
Create and manage custom Skills in Claude Code
</Card>
<Card
title="Authoring best practices"
icon="lightbulb"
href="/docs/en/agents-and-tools/agent-skills/best-practices"
>
Write Skills that Claude can use effectively
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-agent-skills-quickstart-4b66ca78ee.md
# Get started with Agent Skills in the API
Learn how to use Agent Skills to create documents with the Claude API in under 10 minutes.
---
This tutorial shows you how to use Agent Skills to create a PowerPoint presentation. You'll learn how to enable Skills, make a simple request, and access the generated file.
## Prerequisites
- [Claude API key](/settings/keys)
- Python 3.7+ or curl installed
- Basic familiarity with making API requests
## Agent Skills overview
Pre-built Agent Skills extend Claude's capabilities with specialized expertise for tasks like creating documents, analyzing data, and processing files. Anthropic provides the following pre-built Agent Skills in the API:
- **PowerPoint (pptx):** Create and edit presentations
- **Excel (xlsx):** Create and analyze spreadsheets
- **Word (docx):** Create and edit documents
- **PDF (pdf):** Generate PDF documents
<Note>
**Want to create custom Skills?** See the [Agent Skills Cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction) for examples of building your own Skills with domain-specific expertise.
</Note>
## Step 1: List available Skills
First, check what Skills are available. Use the Skills API to list all Anthropic-managed Skills:
<CodeGroup defaultLanguage="CLI">
```bash cURL
curl "https://api.anthropic.com/v1/skills?source=anthropic" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: skills-2025-10-02"
```
```bash CLI
ant beta:skills list --source anthropic
```
```python Python
import anthropic
client = anthropic.Anthropic()
# List Anthropic-managed Skills
skills = client.beta.skills.list(source="anthropic")
for skill in skills.data:
print(f"{skill.id}: {skill.display_title}")
```
```typescript TypeScript
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
// List Anthropic-managed Skills
const skills = await client.beta.skills.list({
source: "anthropic"
});
for (const skill of skills.data) {
console.log(`${skill.id}: ${skill.display_title}`);
}
```
</CodeGroup>
You see the following Skills: `pptx`, `xlsx`, `docx`, and `pdf`.
This API returns each Skill's metadata: its name and description. Claude loads this metadata at startup to know what Skills are available. This is the first level of **progressive disclosure**, where Claude discovers Skills without loading their full instructions yet.
## Step 2: Create a presentation
Now use the PowerPoint Skill to create a presentation about renewable energy. Specify Skills using the `container` parameter in the Messages API:
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "anthropic",
"skill_id": "pptx",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Create a presentation about renewable energy with 5 slides"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
```bash CLI
ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 \
--transform content <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: pptx
version: latest
messages:
- role: user
content: Create a presentation about renewable energy with 5 slides
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python
import anthropic
client = anthropic.Anthropic()
# Create a message with the PowerPoint Skill
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Create a presentation about renewable energy with 5 slides",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response.content)
```
```typescript TypeScript
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
// Create a message with the PowerPoint Skill
const response = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{
type: "anthropic",
skill_id: "pptx",
version: "latest"
}
]
},
messages: [
{
role: "user",
content: "Create a presentation about renewable energy with 5 slides"
}
],
tools: [
{
type: "code_execution_20250825",
name: "code_execution"
}
]
});
console.log(response.content);
```
</CodeGroup>
Let's break down what each part does:
- **`container.skills`:** Specifies which Skills Claude can use
- **`type: "anthropic"`:** Indicates this is an Anthropic-managed Skill
- **`skill_id: "pptx"`:** The PowerPoint Skill identifier
- **`version: "latest"`:** The Skill version set to the most recently published
- **`tools`:** Enables code execution (required for Skills)
- **Beta headers:** `code-execution-2025-08-25` and `skills-2025-10-02`
When you make this request, Claude automatically matches your task to the relevant Skill. Since you asked for a presentation, Claude determines the PowerPoint Skill is relevant and loads its full instructions: the second level of progressive disclosure. Then Claude executes the Skill's code to create your presentation.
## Step 3: Download the created file
The presentation was created in the code execution container and saved as a file. The response includes a file reference with a file ID. Extract the file ID and download it using the Files API:
<CodeGroup>
```bash cURL nocheck
# Extract file_id from response (using jq)
FILE_ID=$(echo "$RESPONSE" | jq -r '.content[] | select(.type=="tool_use" and .name=="code_execution") | .content[] | select(.file_id) | .file_id')
# Download the file
curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: files-api-2025-04-14" \
--output renewable_energy.pptx
echo "Presentation saved to renewable_energy.pptx"
```
```bash CLI nocheck
# Extract file_id with --transform on the messages create call
FILE_ID=$(ant beta:messages create \
--beta code-execution-2025-08-25 --beta skills-2025-10-02 \
--transform 'content.#.content.content.#.file_id|@flatten|0' \
--format yaml <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: pptx
version: latest
messages:
- role: user
content: Create a presentation about renewable energy with 5 slides
tools:
- type: code_execution_20250825
name: code_execution
YAML
)
# Download the file
ant beta:files download \
--file-id "$FILE_ID" \
--output renewable_energy.pptx
printf 'Presentation saved to renewable_energy.pptx\n'
```
```python Python nocheck
from typing import Any
response: Any = None
# Extract file ID from response
file_id = None
for block in response.content:
if block.type == "tool_use" and block.name == "code_execution":
# File ID is in the tool result
for result_block in block.content:
if hasattr(result_block, "file_id"):
file_id = result_block.file_id
break
if file_id:
# Download the file
file_content = client.beta.files.download(file_id=file_id)
# Save to disk
with open("renewable_energy.pptx", "wb") as f:
file_content.write_to_file(f.name)
print(f"Presentation saved to renewable_energy.pptx")
```
```typescript TypeScript nocheck
// Extract file ID from response
let fileId: string | null = null;
for (const block of response.content) {
if (block.type === "tool_use" && block.name === "code_execution") {
// File ID is in the tool result
for (const resultBlock of block.content) {
if ("file_id" in resultBlock) {
fileId = resultBlock.file_id;
break;
}
}
}
}
if (fileId) {
// Download the file
const fileContent = await client.beta.files.download(fileId);
// Save to disk
const fs = require("fs/promises");
await fs.writeFile("renewable_energy.pptx", Buffer.from(await fileContent.arrayBuffer()));
console.log("Presentation saved to renewable_energy.pptx");
}
```
</CodeGroup>
<Note>
For complete details on working with generated files, see the [code execution tool documentation](/docs/en/agents-and-tools/tool-use/code-execution-tool#retrieve-generated-files).
</Note>
## Try more examples
Now that you've created your first document with Skills, try these variations:
### Create a spreadsheet
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "anthropic",
"skill_id": "xlsx",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Create a quarterly sales tracking spreadsheet with sample data"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
```bash CLI
ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: xlsx
version: latest
messages:
- role: user
content: Create a quarterly sales tracking spreadsheet with sample data
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Create a quarterly sales tracking spreadsheet with sample data",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript
const response = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{
type: "anthropic",
skill_id: "xlsx",
version: "latest"
}
]
},
messages: [
{
role: "user",
content: "Create a quarterly sales tracking spreadsheet with sample data"
}
],
tools: [
{
type: "code_execution_20250825",
name: "code_execution"
}
]
});
```
</CodeGroup>
### Create a Word document
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "anthropic",
"skill_id": "docx",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Write a 2-page report on the benefits of renewable energy"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
```bash CLI nocheck
ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: docx
version: latest
messages:
- role: user
content: Write a 2-page report on the benefits of renewable energy
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [{"type": "anthropic", "skill_id": "docx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Write a 2-page report on the benefits of renewable energy",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript
const response = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{
type: "anthropic",
skill_id: "docx",
version: "latest"
}
]
},
messages: [
{
role: "user",
content: "Write a 2-page report on the benefits of renewable energy"
}
],
tools: [
{
type: "code_execution_20250825",
name: "code_execution"
}
]
});
```
</CodeGroup>
### Generate a PDF
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "anthropic",
"skill_id": "pdf",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Generate a PDF invoice template"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
```bash CLI
ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: pdf
version: latest
messages:
- role: user
content: Generate a PDF invoice template
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [{"type": "anthropic", "skill_id": "pdf", "version": "latest"}]
},
messages=[{"role": "user", "content": "Generate a PDF invoice template"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript
const response = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{
type: "anthropic",
skill_id: "pdf",
version: "latest"
}
]
},
messages: [
{
role: "user",
content: "Generate a PDF invoice template"
}
],
tools: [
{
type: "code_execution_20250825",
name: "code_execution"
}
]
});
```
</CodeGroup>
## Next steps
Now that you've used pre-built Agent Skills, you can:
<CardGroup cols={2}>
<Card
title="API Guide"
icon="book"
href="/docs/en/build-with-claude/skills-guide"
>
Use Skills with the Claude API
</Card>
<Card
title="Create Custom Skills"
icon="code"
href="/docs/en/api/skills/create-skill"
>
Upload your own Skills for specialized tasks
</Card>
<Card
title="Authoring Guide"
icon="edit"
href="/docs/en/agents-and-tools/agent-skills/best-practices"
>
Learn best practices for writing effective Skills
</Card>
<Card
title="Use Skills in Claude Code"
icon="terminal"
href="https://code.claude.com/docs/en/skills"
>
Learn about Skills in Claude Code
</Card>
<Card
title="Agent Skills Cookbook"
icon="book"
href="https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction"
>
Explore example Skills and implementation patterns
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-mcp-connector-2b3ff19436.md
# MCP connector
---
Claude's Model Context Protocol (MCP) connector feature enables you to connect to remote MCP servers directly from the Messages API without a separate MCP client.
<Note>
**Current version**: This feature requires the beta header: `"anthropic-beta": "mcp-client-2025-11-20"`
The previous version (`mcp-client-2025-04-04`) is deprecated. See the [deprecated version documentation](#deprecated-version-mcp-client-2025-04-04) below.
</Note>
<Note>
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.
</Note>
## Key features
- **Direct API integration**: Connect to MCP servers without implementing an MCP client
- **Tool calling support**: Access MCP tools through the Messages API
- **Flexible tool configuration**: Enable all tools, allowlist specific tools, or denylist unwanted tools
- **Per-tool configuration**: Configure individual tools with custom settings
- **OAuth authentication**: Support for OAuth Bearer tokens for authenticated servers
- **Multiple servers**: Connect to multiple MCP servers in a single request
## Limitations
- Of the feature set of the [MCP specification](https://modelcontextprotocol.io/introduction#explore-mcp), only [tool calls](https://modelcontextprotocol.io/docs/concepts/tools) are currently supported.
- The server must be publicly exposed through HTTP (supports both Streamable HTTP and SSE transports). Local STDIO servers cannot be connected directly.
- The MCP connector is currently not supported on Amazon Bedrock and Google Vertex.
## Using the MCP connector in the Messages API
The MCP connector uses two components:
1. **MCP Server Definition** (`mcp_servers` array): Defines server connection details (URL, authentication)
2. **MCP Toolset** (`tools` array): Configures which tools to enable and how to configure them
### Basic example
This example enables all tools from an MCP server with default configuration:
<CodeGroup>
```bash cURL nocheck
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: mcp-client-2025-11-20" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 1000,
"messages": [{"role": "user", "content": "What tools do you have available?"}],
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}
],
"tools": [
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp"
}
]
}'
```
```bash CLI nocheck
ant beta:messages create --beta mcp-client-2025-11-20 <<'YAML'
model: claude-opus-4-7
max_tokens: 1000
messages:
- role: user
content: What tools do you have available?
mcp_servers:
- type: url
url: https://example-server.modelcontextprotocol.io/sse
name: example-mcp
authorization_token: YOUR_TOKEN
tools:
- type: mcp_toolset
mcp_server_name: example-mcp
YAML
```
```python Python nocheck hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=1000,
messages=[{"role": "user", "content": "What tools do you have available?"}],
mcp_servers=[
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
}
],
tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
betas=["mcp-client-2025-11-20"],
)
print(response)
```
```typescript TypeScript nocheck hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
const response = await anthropic.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 1000,
messages: [
{
role: "user",
content: "What tools do you have available?"
}
],
mcp_servers: [
{
type: "url",
url: "https://example-server.modelcontextprotocol.io/sse",
name: "example-mcp",
authorization_token: "YOUR_TOKEN"
}
],
tools: [
{
type: "mcp_toolset",
mcp_server_name: "example-mcp"
}
],
betas: ["mcp-client-2025-11-20"]
});
console.log(response);
```
```csharp C# nocheck hidelines={1..6}
using Anthropic;
using Anthropic.Models.Beta.Messages;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus4_7,
MaxTokens = 1000,
Messages = new List<BetaMessageParam>
{
new() { Role = Role.User, Content = "What tools do you have available?" }
},
McpServers = new List<BetaRequestMcpServerUrlDefinition>
{
new()
{
Url = "https://example-server.modelcontextprotocol.io/sse",
Name = "example-mcp",
AuthorizationToken = "YOUR_TOKEN"
}
},
Tools = new List<BetaToolUnion>
{
new BetaMcpToolset("example-mcp")
},
Betas = new List<string> { "mcp-client-2025-11-20" }
};
var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);
```
```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: 1000,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
},
MCPServers: []anthropic.BetaRequestMCPServerURLDefinitionParam{
{
URL: "https://example-server.modelcontextprotocol.io/sse",
Name: "example-mcp",
AuthorizationToken: anthropic.String("YOUR_TOKEN"),
},
},
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
MCPServerName: "example-mcp",
}},
},
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaMCPClient2025_11_20,
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
}
```
```java Java nocheck hidelines={1..2,4,6..9,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.messages.BetaMcpToolset;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
import com.anthropic.models.beta.messages.MessageCreateParams;
public class Main {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model("claude-opus-4-7")
.maxTokens(1000L)
.addUserMessage("What tools do you have available?")
.addMcpServer(BetaRequestMcpServerUrlDefinition.builder()
.url("https://example-server.modelcontextprotocol.io/sse")
.name("example-mcp")
.authorizationToken("YOUR_TOKEN")
.build())
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.build())
.addBeta("mcp-client-2025-11-20")
.build();
BetaMessage response = client.beta().messages().create(params);
System.out.println(response);
}
}
```
```php PHP nocheck hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->beta->messages->create(
maxTokens: 1000,
messages: [
['role' => 'user', 'content' => 'What tools do you have available?']
],
model: 'claude-opus-4-7',
mcpServers: [
[
'type' => 'url',
'url' => 'https://example-server.modelcontextprotocol.io/sse',
'name' => 'example-mcp',
'authorization_token' => 'YOUR_TOKEN',
],
],
tools: [
[
'type' => 'mcp_toolset',
'mcp_server_name' => 'example-mcp',
],
],
betas: ['mcp-client-2025-11-20'],
);
echo $message;
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
response = client.beta.messages.create(
model: "claude-opus-4-7",
max_tokens: 1000,
messages: [
{ role: "user", content: "What tools do you have available?" }
],
mcp_servers: [
{
type: "url",
url: "https://example-server.modelcontextprotocol.io/sse",
name: "example-mcp",
authorization_token: "YOUR_TOKEN"
}
],
tools: [
{
type: "mcp_toolset",
mcp_server_name: "example-mcp"
}
],
betas: ["mcp-client-2025-11-20"]
)
puts response
```
</CodeGroup>
## MCP server configuration
Each MCP server in the `mcp_servers` array defines the connection details:
```json
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}
```
### Field descriptions
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | string | Yes | Currently only "url" is supported |
| `url` | string | Yes | The URL of the MCP server. Must start with https:// |
| `name` | string | Yes | A unique identifier for this MCP server. Must be referenced by exactly one MCPToolset in the `tools` array. |
| `authorization_token` | string | No | OAuth authorization token if required by the MCP server. See [MCP specification](../../06-MCP-Tools/Spec/spec-2025-11-25-authorization-model-context-protocol.md). |
## MCP toolset configuration
The MCPToolset lives in the `tools` array and configures which tools from the MCP server are enabled and how they should be configured.
### Basic structure
```json
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"default_config": {
"enabled": true,
"defer_loading": false
},
"configs": {
"specific_tool_name": {
"enabled": true,
"defer_loading": true
}
}
}
```
### Field descriptions
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | string | Yes | Must be "mcp_toolset" |
| `mcp_server_name` | string | Yes | Must match a server name defined in the `mcp_servers` array |
| `default_config` | object | No | Default configuration applied to all tools in this set. Individual tool configs in `configs` will override these defaults. |
| `configs` | object | No | Per-tool configuration overrides. Keys are tool names, values are configuration objects. |
| `cache_control` | object | No | Cache breakpoint configuration for this toolset |
### Tool configuration options
Each tool (whether configured in `default_config` or in `configs`) supports the following fields:
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `enabled` | boolean | `true` | Whether this tool is enabled |
| `defer_loading` | boolean | `false` | If true, tool description is not sent to the model initially. Used with [Tool Search Tool](/docs/en/agents-and-tools/tool-use/tool-search-tool). |
For the full directory of Anthropic-provided tools and optional properties like `defer_loading`, see the [Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference). For searching across large tool sets, see [Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool).
### Configuration merging
Configuration values merge with this precedence (highest to lowest):
1. Tool-specific settings in `configs`
2. Set-level `default_config`
3. System defaults
Example:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"defer_loading": true
},
"configs": {
"search_events": {
"enabled": false
}
}
}
```
Results in:
- `search_events`: `enabled: false` (from configs), `defer_loading: true` (from default_config)
- All other tools: `enabled: true` (system default), `defer_loading: true` (from default_config)
## Common configuration patterns
### Enable all tools with default configuration
The simplest pattern - enable all tools from a server:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp"
}
```
### Allowlist - Enable only specific tools
Set `enabled: false` as the default, then explicitly enable specific tools:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false
},
"configs": {
"search_events": {
"enabled": true
},
"create_event": {
"enabled": true
}
}
}
```
### Denylist - Disable specific tools
Enable all tools by default, then explicitly disable unwanted tools:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"configs": {
"delete_all_events": {
"enabled": false
},
"share_calendar_publicly": {
"enabled": false
}
}
}
```
### Mixed - Allowlist with per-tool configuration
Combine allowlisting with custom configuration for each tool:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false,
"defer_loading": true
},
"configs": {
"search_events": {
"enabled": true,
"defer_loading": false
},
"list_events": {
"enabled": true
}
}
}
```
In this example:
- `search_events` is enabled with `defer_loading: false`
- `list_events` is enabled with `defer_loading: true` (inherited from default_config)
- All other tools are disabled
## Validation rules
The API enforces these validation rules:
- **Server must exist**: The `mcp_server_name` in an MCPToolset must match a server defined in the `mcp_servers` array
- **Server must be used**: Every MCP server defined in `mcp_servers` must be referenced by exactly one MCPToolset
- **Unique toolset per server**: Each MCP server can only be referenced by one MCPToolset
- **Unknown tool names**: If a tool name in `configs` doesn't exist on the MCP server, a backend warning is logged but no error is returned (MCP servers may have dynamic tool availability)
## Response content types
When Claude uses MCP tools, the response will include two new content block types:
### MCP Tool Use Block
```json
{
"type": "mcp_tool_use",
"id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"name": "echo",
"server_name": "example-mcp",
"input": { "param1": "value1", "param2": "value2" }
}
```
### MCP Tool Result Block
```json
{
"type": "mcp_tool_result",
"tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"is_error": false,
"content": [
{
"type": "text",
"text": "Hello"
}
]
}
```
## Multiple MCP servers
You can connect to multiple MCP servers by including multiple server definitions in `mcp_servers` and a corresponding MCPToolset for each in the `tools` array:
```json
{
"model": "claude-opus-4-7",
"max_tokens": 1000,
"messages": [
{
"role": "user",
"content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
}
],
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.example1.com/sse",
"name": "mcp-server-1",
"authorization_token": "TOKEN1"
},
{
"type": "url",
"url": "https://mcp.example2.com/sse",
"name": "mcp-server-2",
"authorization_token": "TOKEN2"
}
],
"tools": [
{
"type": "mcp_toolset",
"mcp_server_name": "mcp-server-1"
},
{
"type": "mcp_toolset",
"mcp_server_name": "mcp-server-2",
"default_config": {
"defer_loading": true
}
}
]
}
```
## Authentication
For MCP servers that require OAuth authentication, you'll need to obtain an access token. The MCP connector beta supports passing an `authorization_token` parameter in the MCP server definition.
API consumers are expected to handle the OAuth flow and obtain the access token prior to making the API call, as well as refreshing the token as needed.
### Obtaining an access token for testing
The MCP inspector can guide you through the process of obtaining an access token for testing purposes.
1. Run the inspector with the following command. You need Node.js installed on your machine.
```bash
npx @modelcontextprotocol/inspector
```
2. In the sidebar on the left, for "Transport type", select either "SSE" or "Streamable HTTP".
3. Enter the URL of the MCP server.
4. In the right area, click on the "Open Auth Settings" button after "Need to configure authentication?".
5. Click "Quick OAuth Flow" and authorize on the OAuth screen.
6. Follow the steps in the "OAuth Flow Progress" section of the inspector and click "Continue" until you reach "Authentication complete".
7. Copy the `access_token` value.
8. Paste it into the `authorization_token` field in your MCP server configuration.
### Using the access token
Once you've obtained an access token using either OAuth flow above, you can use it in your MCP server configuration:
```json
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "authenticated-server",
"authorization_token": "YOUR_ACCESS_TOKEN_HERE"
}
]
}
```
For detailed explanations of the OAuth flow, refer to the [Authorization section](../../06-MCP-Tools/Spec/spec-2025-11-25-authorization-model-context-protocol.md) in the MCP specification.
## Client-side MCP helpers (TypeScript)
If you manage your own MCP client connection (for example, with local stdio servers, MCP prompts, or MCP resources), the TypeScript SDK provides helper functions that convert between MCP types and Claude API types. This eliminates manual conversion code when using the [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) alongside the Anthropic SDK.
<Note>
These helpers are currently available in the TypeScript SDK only.
</Note>
<Note>
Use the [`mcp_servers` API parameter](#using-the-mcp-connector-in-the-messages-api) when you have remote servers accessible via URL and only need tool support. Use the client-side helpers when you need local servers, prompts, resources, or more control over the connection with the base SDK.
</Note>
### Installation
Install both the Anthropic SDK and the MCP SDK:
```bash
npm install @anthropic-ai/sdk @modelcontextprotocol/sdk
```
### Available helpers
Import the helpers from the beta namespace:
```typescript nocheck
import {
mcpTools,
mcpMessages,
mcpResourceToContent,
mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";
```
| Helper | Description |
|--------|-------------|
| `mcpTools(tools, mcpClient)` | Converts MCP tools to Claude API tools for use with `client.beta.messages.toolRunner()` |
| `mcpMessages(messages)` | Converts MCP prompt messages to Claude API message format |
| `mcpResourceToContent(resource)` | Converts an MCP resource to a Claude API content block |
| `mcpResourceToFile(resource)` | Converts an MCP resource to a file object for upload |
### Use MCP tools
Convert MCP tools for use with the SDK's [tool runner](/docs/en/agents-and-tools/tool-use/tool-runner), which handles tool execution automatically:
```typescript nocheck hidelines={1}
import Anthropic from "@anthropic-ai/sdk";
import { mcpTools } from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const anthropic = new Anthropic();
// Connect to an MCP server
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);
// List tools and convert them for the Claude API
const { tools } = await mcpClient.listTools();
const runner = await anthropic.beta.messages.toolRunner({
model: "claude-opus-4-7",
max_tokens: 1024,
messages: [{ role: "user", content: "What tools do you have available?" }],
tools: mcpTools(tools, mcpClient)
});
```
### Use MCP prompts
Convert MCP prompt messages into Claude API message format:
```typescript nocheck
import { mcpMessages } from "@anthropic-ai/sdk/helpers/beta/mcp";
const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 1024,
messages: mcpMessages(messages)
});
```
### Use MCP resources
Convert MCP resources into content blocks to include in messages, or into file objects for upload:
```typescript nocheck
import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";
// As a content block in a message
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
mcpResourceToContent(resource),
{ type: "text", text: "Summarize this document" }
]
}
]
});
// As a file upload
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });
```
### Error handling
The conversion functions throw `UnsupportedMCPValueError` if an MCP value isn't supported by the Claude API. This can happen with unsupported content types, MIME types, or non-HTTP resource links.
## Data retention
The MCP Connector is not covered by ZDR arrangements. Data exchanged with MCP servers, including tool definitions and execution results, is retained according to Anthropic's standard data retention policy.
For ZDR eligibility across all features, see [API and data retention](/docs/en/build-with-claude/api-and-data-retention).
## Migration guide
If you're using the deprecated `mcp-client-2025-04-04` beta header, follow this guide to migrate to the new version.
### Key changes
1. **New beta header**: Change from `mcp-client-2025-04-04` to `mcp-client-2025-11-20`
2. **Tool configuration moved**: Tool configuration now lives in the `tools` array as MCPToolset objects, not in the MCP server definition
3. **More flexible configuration**: New pattern supports allowlisting, denylisting, and per-tool configuration
### Migration steps
**Before (deprecated):**
```json
{
"model": "claude-opus-4-7",
"max_tokens": 1000,
"messages": [
// ...
],
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.example.com/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
"tool_configuration": {
"enabled": true,
"allowed_tools": ["tool1", "tool2"]
}
}
]
}
```
**After (current):**
```json
{
"model": "claude-opus-4-7",
"max_tokens": 1000,
"messages": [
// ...
],
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.example.com/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}
],
"tools": [
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"default_config": {
"enabled": false
},
"configs": {
"tool1": {
"enabled": true
},
"tool2": {
"enabled": true
}
}
}
]
}
```
### Common migration patterns
| Old pattern | New pattern |
|-------------|-------------|
| No `tool_configuration` (all tools enabled) | MCPToolset with no `default_config` or `configs` |
| `tool_configuration.enabled: false` | MCPToolset with `default_config.enabled: false` |
| `tool_configuration.allowed_tools: [...]` | MCPToolset with `default_config.enabled: false` and specific tools enabled in `configs` |
## Deprecated version: mcp-client-2025-04-04
<Note type="warning">
This version is deprecated. Migrate to `mcp-client-2025-11-20` using the [migration guide](#migration-guide) above.
</Note>
The previous version of the MCP connector included tool configuration directly in the MCP server definition:
```json
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
"tool_configuration": {
"enabled": true,
"allowed_tools": ["example_tool_1", "example_tool_2"]
}
}
]
}
```
### Deprecated field descriptions
| Property | Type | Description |
|----------|------|-------------|
| `tool_configuration` | object | **Deprecated**: Use MCPToolset in the `tools` array instead |
| `tool_configuration.enabled` | boolean | **Deprecated**: Use `default_config.enabled` in MCPToolset |
| `tool_configuration.allowed_tools` | array | **Deprecated**: Use allowlist pattern with `configs` in MCPToolset |
---
## Agents-Tools/agents-and-tools-remote-mcp-servers-42aeab377e.md
# Remote MCP servers
---
Several companies have deployed remote MCP servers that developers can connect to via the Anthropic MCP connector API. These servers expand the capabilities available to developers and end users by providing remote access to various services and tools through the MCP protocol.
<Note>
The remote MCP servers listed below are third-party services designed to work with the Claude API. These servers
are not owned, operated, or endorsed by Anthropic. Users should only connect to remote MCP servers they trust and
should review each server's security practices and terms before connecting.
</Note>
## Connecting to remote MCP servers
To connect to a remote MCP server:
1. Review the documentation for the specific server you want to use.
2. Ensure you have the necessary authentication credentials.
3. Follow the server-specific connection instructions provided by each company.
For more information about using remote MCP servers with the Claude API, see the [MCP connector docs](/docs/en/agents-and-tools/mcp-connector).
## Remote MCP server examples
<MCPServersTable platform="mcpConnector" />
<Note>
**Looking for more?** [Find hundreds more MCP servers on GitHub](https://github.com/modelcontextprotocol/servers).
</Note>
---
## Agents-Tools/agents-and-tools-tool-use-advisor-tool-0a75684a7b.md
# 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.
<Note>
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.
</Note>
<Note>
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.
</Note>
## 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 (Anthropic).
## Quick start
<CodeGroup>
```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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$response = $client->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
```
</CodeGroup>
## 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. Which variant you receive 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`.
<Note>
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`.
</Note>
## 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.
<Warning>
[`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.
Set `keep: "all"` to preserve advisor cache stability.
</Warning>
## 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 yet fully compatible with advisor tool blocks; full support is planned for a follow-up release. With `clear_thinking`, see the caching warning above. |
| `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.
- **Anthropic Priority Tier** is honored per model. Priority Tier on the executor model does not extend to the advisor; you need Priority Tier on the advisor model specifically.
---
## Agents-Tools/agents-and-tools-tool-use-bash-tool-17760ed12d.md
# Bash tool
---
<Note>
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.
</Note>
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
<CodeGroup>
```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)
```
</CodeGroup>
## 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`
<section title="Example usage">
Run a command:
```json
{
"command": "ls -la *.py"
}
```
Restart the session:
```json
{
"restart": true
}
```
</section>
## 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.
<Steps>
<Step title="Set up a bash environment">
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): ...
```
</Step>
<Step title="Handle command execution">
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
```
</Step>
<Step title="Process Claude's tool calls">
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,
}
```
</Step>
<Step title="Implement safety measures">
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.
</Step>
</Steps>
### Handle errors
When implementing the bash tool, handle various error scenarios:
<section title="Command execution timeout">
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
}
]
}
```
</section>
<section title="Command not found">
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
}
]
}
```
</section>
<section title="Permission denied">
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
}
]
}
```
</section>
### Follow implementation best practices
<section title="Use command timeouts">
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"
```
</section>
<section title="Maintain session state">
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
]
```
</section>
<section title="Handle large outputs">
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
```
</section>
<section title="Log all commands">
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
```
</section>
<section title="Sanitize outputs">
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
```
</section>
## Security
<Warning>
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
</Warning>
### 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.
<Note>
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.
</Note>
## Next steps
<CardGroup cols={2}>
<Card
title="Tool use overview"
icon="tool"
href="/docs/en/agents-and-tools/tool-use/overview"
>
Learn about tool use with Claude
</Card>
<Card
title="Text editor tool"
icon="file"
href="/docs/en/agents-and-tools/tool-use/text-editor-tool"
>
View and edit text files with Claude
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-build-a-tool-using-agent-72a5cd5184.md
# 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.
<Note>
Every ring runs standalone. Copy any ring into a fresh file and it will execute without the code from earlier rings.
</Note>
## 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.
<CodeGroup>
````bash
#!/bin/bash
# Ring 1: Single tool, single turn.
# Source for <CodeSource> 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 <CodeSource> 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 <CodeSource> 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 <CodeSource> 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);
}
}
````
</CodeGroup>
**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.
<CodeGroup>
````bash
#!/bin/bash
# Ring 2: The agentic loop.
# Source for <CodeSource> 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 <CodeSource> 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 <CodeSource> 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 <CodeSource> 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<string, unknown>) {
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<string, unknown>);
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);
}
}
````
</CodeGroup>
**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.
<CodeGroup>
````bash
#!/bin/bash
# Ring 3: Multiple tools, parallel calls.
# Source for <CodeSource> 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 <CodeSource> 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 <CodeSource> 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 <CodeSource> 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<string, unknown>) {
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<string, unknown>);
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);
}
}
````
</CodeGroup>
**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.
<CodeGroup>
````bash
#!/bin/bash
# Ring 4: Error handling.
# Source for <CodeSource> 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 <CodeSource> 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 <CodeSource> 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 <CodeSource> 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<string, unknown>) {
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<string, unknown>);
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);
}
}
````
</CodeGroup>
**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.
<Note>
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.
</Note>
<CodeGroup>
````bash
#!/bin/bash
# Ring 5: The Tool Runner SDK abstraction.
# Source for <CodeSource> 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 <CodeSource> 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 <CodeSource> 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 <CodeSource> 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);
}
}
````
</CodeGroup>
**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
<CardGroup>
<Card href="/docs/en/agents-and-tools/tool-use/define-tools" title="Sharpen your schemas">
Schema specification and best practices.
</Card>
<Card href="/docs/en/agents-and-tools/tool-use/tool-runner" title="Tool Runner deep dive">
The full SDK abstraction reference.
</Card>
<Card href="/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use" title="Troubleshooting">
Fix common tool-use errors.
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-code-execution-tool-4d0dc9adf8.md
# 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.
<Note>
Reach out through the [feedback form](https://forms.gle/LTAU6Xn2puCJMi1n6) to share your feedback on this feature.
</Note>
<Note>
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.
</Note>
## 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` |
| Claude Sonnet 3.7 (`claude-3-7-sonnet-20250219`) ([deprecated](/docs/en/about-claude/model-deprecations)) | `code_execution_20250825` |
| Claude Haiku 3.5 (`claude-3-5-haiku-latest`) ([deprecated](/docs/en/about-claude/model-deprecations)) | `code_execution_20250825` |
<Note>
`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. A legacy version `code_execution_20250522` (Python only) is also available on the same models as `code_execution_20250825`; see [Upgrade to latest tool version](#upgrade-to-latest-tool-version) to migrate from it.
</Note>
<Warning>
Older tool versions are not guaranteed to be backwards-compatible with newer models. Always use the tool version that corresponds to your model version.
</Warning>
## Platform availability
Code execution is available on:
- **Claude API** (Anthropic)
- **Microsoft Azure AI Foundry**
Code execution is not currently available on Amazon Bedrock or Google Vertex AI.
<Note>
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 or Google Vertex AI.
</Note>
## Quick start
Here's a simple example that asks Claude to perform a calculation:
<CodeGroup>
```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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->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
```
</CodeGroup>
## 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 (CSV, Excel, images, etc.), upload them via the Files API and reference them in your request:
<Note>
Using the Files API with Code Execution requires the Files API beta header: `"anthropic-beta": "files-api-2025-04-14"`
</Note>
The Python environment can process various file types uploaded via the Files API, including:
- CSV
- Excel (.xlsx, .xls)
- JSON
- XML
- Images (JPEG, PNG, GIF, WebP)
- Text files (.txt, .md, .py, etc)
#### 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
<CodeGroup>
```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 --format yaml)
# Use the file_id with code execution
ant beta:messages create \
--beta files-api-2025-04-14 <<YAML
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_ID
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python nocheck hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
# Upload a file
file_object = client.beta.files.upload(
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"}],
)
print(response)
```
```typescript TypeScript nocheck hidelines={5..6,-3..-1}
import Anthropic, { toFile } from "@anthropic-ai/sdk";
import { createReadStream } from "fs";
const client = new Anthropic();
async function main() {
// Upload a file
const fileObject = await client.beta.files.upload({
file: await toFile(createReadStream("data.csv"), undefined, { type: "text/csv" })
});
// Use the file_id with code execution
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: [
{ type: "text", text: "Analyze this CSV data" },
{ type: "container_upload", file_id: fileObject.id }
]
}
],
tools: [
{
type: "code_execution_20250825",
name: "code_execution"
}
]
});
console.log(response);
}
main().catch(console.error);
```
```csharp C# nocheck hidelines={1..10,-2..}
using Anthropic;
using Anthropic.Models.Beta.Files;
using Anthropic.Models.Beta.Messages;
class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new();
// Upload a file
var fileObject = await client.Beta.Files.Upload(new FileUploadParams
{
File = File.OpenRead("data.csv")
});
// Use the file_id with code execution
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus4_7,
Betas = ["files-api-2025-04-14"],
MaxTokens = 4096,
Messages = [
new()
{
Role = Role.User,
Content = [
new() { Type = "text", Text = "Analyze this CSV data" },
new() { Type = "container_upload", FileId = fileObject.Id }
]
}
],
Tools = [new ToolUnion(new CodeExecutionTool20250825())]
};
var response = await client.Beta.Messages.Create(parameters);
Console.WriteLine(response);
}
}
```
```go Go hidelines={11..15}
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/anthropics/anthropic-sdk-go"
)
func init() {
os.WriteFile("data.csv", []byte("name,value\nalpha,1\nbeta,2\ngamma,3\n"), 0644)
}
func main() {
client := anthropic.NewClient()
// Upload a file
file, err := os.Open("data.csv")
if err != nil {
log.Fatal(err)
}
defer file.Close()
fileObject, err := client.Beta.Files.Upload(context.TODO(), anthropic.BetaFileUploadParams{
File: file,
})
if err != nil {
log.Fatal(err)
}
// Use the file_id with code execution
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus4_7,
MaxTokens: 4096,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(
anthropic.NewBetaTextBlock("Analyze this CSV data"),
anthropic.NewBetaContainerUploadBlock(fileObject.ID),
),
},
Tools: []anthropic.BetaToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
},
Betas: []anthropic.AnthropicBeta{
"code-execution-2025-08-25",
anthropic.AnthropicBetaFilesAPI2025_04_14,
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
}
```
```java Java nocheck hidelines={1..2,5..6,8..9,11..15,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.files.FileMetadata;
import com.anthropic.models.beta.files.FileUploadParams;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.beta.messages.BetaCodeExecutionTool20250825;
import com.anthropic.models.beta.messages.BetaContentBlockParam;
import com.anthropic.models.beta.messages.BetaTextBlockParam;
import com.anthropic.models.beta.messages.BetaContainerUploadBlockParam;
import java.nio.file.Paths;
import java.util.List;
public class CodeExecutionWithFiles {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Upload a file
FileMetadata fileMetadata = client.beta().files().upload(
FileUploadParams.builder()
.file(Paths.get("data.csv"))
.build()
);
// Use the file_id with code execution
BetaMessage response = client.beta().messages().create(
MessageCreateParams.builder()
.model("claude-opus-4-7")
.addBeta("files-api-2025-04-14")
.maxTokens(4096L)
.addUserMessageOfBetaContentBlockParams(List.of(
BetaContentBlockParam.ofText(BetaTextBlockParam.builder()
.text("Analyze this CSV data")
.build()),
BetaContentBlockParam.ofContainerUpload(BetaContainerUploadBlockParam.builder()
.fileId(fileMetadata.id())
.build())
))
.addTool(BetaCodeExecutionTool20250825.builder().build())
.build()
);
System.out.println(response);
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
// Upload a file
$fileObject = $client->beta->files->upload(
file: 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
```
</CodeGroup>
#### Retrieve generated files
When Claude creates files during code execution, you can retrieve these files using the Files API:
<CodeGroup>
```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 --format yaml)
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: ["code-execution-2025-08-25", "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<string> ExtractFileIds(dynamic response)
{
var fileIds = new List<string>();
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<String> 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<String> extractFileIds(BetaMessage response) {
List<String> 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..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$response = $client->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($response) {
$fileIds = [];
foreach ($response->content as $item) {
if ($item->type === 'bash_code_execution_tool_result') {
$contentItem = $item->content;
if ($contentItem->type === 'bash_code_execution_result') {
// 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: $fileId);
$fileContent = $client->beta->files->download(fileID: $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
```
</CodeGroup>
## 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
<CodeGroup>
```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 --format yaml \
--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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$response1 = $client->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
```
</CodeGroup>
## 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/build-with-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 the [Agent Skills documentation](/docs/en/agents-and-tools/agent-skills/overview) and [Agent Skills API guide](/docs/en/build-with-claude/skills-guide).
---
## Agents-Tools/agents-and-tools-tool-use-code-execution-tool.md
# Code execution tool
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/zero-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 Version |
|----|----|
| Claude Opus 4.6 (`claude-opus-4-6`) | `code_execution_20250825` |
| Claude Sonnet 4.6 (`claude-sonnet-4-6`) | `code_execution_20250825` |
| Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`) | `code_execution_20250825` |
| Claude Opus 4.5 (`claude-opus-4-5-20251101`) | `code_execution_20250825` |
| Claude Opus 4.1 (`claude-opus-4-1-20250805`) | `code_execution_20250825` |
| Claude Opus 4 (`claude-opus-4-20250514`) | `code_execution_20250825` |
| Claude Sonnet 4 (`claude-sonnet-4-20250514`) | `code_execution_20250825` |
| Claude Sonnet 3.7 (`claude-3-7-sonnet-20250219`) ([deprecated](/docs/en/about-claude/model-deprecations)) | `code_execution_20250825` |
| Claude Haiku 4.5 (`claude-haiku-4-5-20251001`) | `code_execution_20250825` |
| Claude Haiku 3.5 (`claude-3-5-haiku-latest`) ([deprecated](/docs/en/about-claude/model-deprecations)) | `code_execution_20250825` |
The current version `code_execution_20250825` supports Bash commands and file operations. A legacy version `code_execution_20250522` (Python only) is also available. See [Upgrade to latest tool version](#upgrade-to-latest-tool-version) for migration details.
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)
- **Microsoft Azure AI Foundry**
Code execution is not currently available on Amazon Bedrock or Google Vertex AI.
Quick start
Here's a simple example that asks Claude to perform a calculation:
Shell
```python
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-6",
"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"
}]
}'
```
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:
``` inline-block
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
Execute Bash commands
Ask Claude to check system information and install packages:
Shell
```python
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-6",
"max_tokens": 4096,
"messages": [{
"role": "user",
"content": "Check the Python version and list installed packages"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
Create and edit files directly
Claude can create, view, and edit files directly in the sandbox using the file manipulation capabilities:
Shell
```python
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-6",
"max_tokens": 4096,
"messages": [{
"role": "user",
"content": "Create a config.yaml file with database settings, then update the port from 5432 to 3306"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
Upload and analyze your own files
To analyze your own data files (CSV, Excel, images, etc.), upload them via 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 via the Files API, including:
- CSV
- Excel (.xlsx, .xls)
- JSON
- XML
- Images (JPEG, PNG, GIF, WebP)
- Text files (.txt, .md, .py, etc)
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
Shell
```python
# 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-6",
"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"
}]
}'
```
Retrieve generated files
When Claude creates files during code execution, you can retrieve these files using the Files API:
Python
```python
# Request code execution that creates files
response = client.beta.messages.create(
model="claude-opus-4-6",
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":
for file in content_item.content:
if hasattr(file, "file_id"):
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}")
```
Combine operations
A complex workflow using all capabilities:
Shell
```python
# 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"' \
> file_response.json
# Extract file_id (using jq)
FILE_ID=$(jq -r '.id' file_response.json)
# Then use it 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-6",
"max_tokens": 4096,
"messages": [{
"role": "user",
"content": [
{
"type": "text",
"text": "Analyze this CSV data: create a summary report, save visualizations, and create a README with the findings"
},
{
"type": "container_upload",
"file_id": "'$FILE_ID'"
}
]
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
Tool definition
The code execution tool requires no additional parameters:
JSON
```python
{
"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
```python
{
"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:**
```python
{
"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:**
```python
{
"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):**
```python
{
"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):**
```python
{
"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 |
| 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
Shell
```python
# 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-6",
"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-6",
"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"
}]
}'
```
Streaming
With streaming enabled, you'll receive code execution events as they occur:
```python
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:
```python
"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:
```python
- "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
The code execution tool powers [programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling), which allows Claude to write code that calls your custom tools programmatically within the execution container. This enables efficient multi-tool workflows, data filtering before reaching Claude's context, and complex conditional logic.
Python
```python
# Enable programmatic calling for your tools
response = client.messages.create(
model="claude-opus-4-6",
max_tokens=4096,
messages=[
{"role": "user", "content": "Get weather for 5 cities and find the warmest"}
],
tools=[
{"type": "code_execution_20250825", "name": "code_execution"},
{
"name": "get_weather",
"description": "Get weather for a city",
"input_schema": {...},
"allowed_callers": [
"code_execution_20250825"
], # Enable programmatic calling
},
],
)
```
Learn more in the [Programmatic tool calling documentation](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling).
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 the [Agent Skills documentation](/docs/en/agents-and-tools/agent-skills/overview) and [Agent Skills API guide](/docs/en/build-with-claude/skills-guide).
---
## Agents-Tools/agents-and-tools-tool-use-computer-use-tool-92d412df82.md
# 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.
<Note>
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, Claude Opus 4.5
- `"computer-use-2025-01-24"` for Sonnet 4.5, Haiku 4.5, Opus 4.1, Sonnet 4, Opus 4, and Sonnet 3.7 ([deprecated](/docs/en/about-claude/model-deprecations))
Reach out through the [feedback form](https://forms.gle/H6UFuXaaLywri9hz6) to share your feedback on this feature.
</Note>
<Note>
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.
</Note>
## 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.
<Warning>
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.
</Warning>
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.
<Card
title="Computer use reference implementation"
icon="computer"
href="https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo"
>
Get started quickly with the computer use reference implementation that includes a web interface, Docker container, example tool implementations, and an agent loop.
**Note:** The implementation has been updated to include new tools for both Claude 4 models and Claude Sonnet 3.7. Be sure to pull the latest version of the repo to access these new features.
</Card>
## Quick start
Here's how to get started with computer use:
<CodeGroup>
```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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$response = $client->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
```
</CodeGroup>
<Note>
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.
</Note>
---
## How computer use works
<Steps>
<Step
title="Provide Claude with the computer use tool and a user prompt"
icon="tool"
>
- 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."
</Step>
<Step title="Claude decides to use the computer use tool" icon="wrench">
- 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.
</Step>
<Step
title="Extract tool input, evaluate the tool on a computer, and return results"
icon="computer"
>
- 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.
</Step>
<Step
title="Claude continues calling computer use tools until it's completed the task"
icon="arrows-clockwise"
>
- 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.
</Step>
</Steps>
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,
thinking_budget: int | None = None,
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"
)
text_editor_type = (
"text_editor_20250728"
if "20251124" in tool_version
else f"text_editor_{tool_version}"
)
# 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_type, "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
# Set up optional thinking parameter (for Claude Sonnet 3.7)
thinking = None
if thinking_budget:
thinking = {"type": "enabled", "budget_tokens": thinking_budget}
# Call the Claude API
response = client.beta.messages.create(
model=model,
max_tokens=max_tokens,
messages=messages,
tools=tools,
betas=[beta_flag],
thinking=thinking,
)
# 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 `<robot_credentials>`. 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.
<Tip>
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.
</Tip>
<Tip>
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.
</Tip>
### 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 in Claude 4 models and Claude Sonnet 3.7:
- **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.
<section title="Example actions">
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 (Claude 4/3.7):
```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]
}
```
</section>
<section title="Modifier keys with click and scroll actions">
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).
</section>
### 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` |
<Note>
**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.
</Note>
### 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.
<Steps>
<Step title="Set up your computing environment">
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.
</Step>
<Step title="Implement action handlers">
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
```
</Step>
<Step title="Process Claude's tool calls">
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,
}
```
</Step>
<Step title="Implement the agent loop">
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})
```
</Step>
</Steps>
#### Handle errors
When implementing the computer use tool, various errors may occur. Here's how to handle them:
<section title="Screenshot capture failure">
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
}
]
}
```
</section>
<section title="Invalid coordinates">
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
}
]
}
```
</section>
<section title="Action execution failure">
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
}
]
}
```
</section>
#### Handle coordinate scaling for higher resolutions
<Note>
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.
</Note>
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:
<CodeGroup>
```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);
}
```
</CodeGroup>
#### Follow implementation best practices
<section title="Use appropriate display resolution">
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
</section>
<section title="Implement proper screenshot handling">
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
</section>
<section title="Add action delays">
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
```
</section>
<section title="Validate actions before execution">
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
```
</section>
<section title="Log actions for debugging">
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}")
```
</section>
---
## 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. Claude Sonnet 3.7 introduces the thinking capability that 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**: Claude Sonnet 3.7 introduced dedicated scroll actions with direction control that improves reliability. The model can now explicitly scroll in any direction (up/down/left/right) by a specified amount.
5. **Spreadsheet interaction**: Mouse clicks for spreadsheet interaction have improved in Claude Sonnet 3.7 with the addition of more precise mouse control actions like `left_mouse_down`, `left_mouse_up`, and new modifier key support. Cell selection can be more reliable by using these fine-grained controls and combining modifier keys with clicks.
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/build-with-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 |
| Claude Sonnet 3.7 ([deprecated](/docs/en/about-claude/model-deprecations)) | 735 tokens |
**Additional token consumption**:
- Screenshot images (see [Vision pricing](/docs/en/build-with-claude/vision))
- Tool execution results returned to Claude
<Note>
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.
</Note>
## Next steps
<CardGroup cols={2}>
<Card
title="Reference implementation"
icon="github-logo"
href="https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo"
>
Get started quickly with the complete Docker-based implementation
</Card>
<Card
title="Tool documentation"
icon="tool"
href="/docs/en/agents-and-tools/tool-use/overview"
>
Learn more about tool use and creating custom tools
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-define-tools-79983959fd.md
# 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.
<Tip>
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.
</Tip>
## 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).
<section title="Example simple tool definition">
```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".
</section>
### 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.
<section title="Example of a good tool description">
```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"]
}
}
```
</section>
<section title="Example poor tool description">
```json JSON
{
"name": "get_stock_price",
"description": "Gets the stock price for a ticker.",
"input_schema": {
"type": "object",
"properties": {
"ticker": {
"type": "string"
}
},
"required": ["ticker"]
}
}
```
</section>
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.
<Tip>
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).
</Tip>
## 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`:
<CodeGroup>
```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<string, JsonElement>
{
["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<string, JsonElement>()
{
{ "location", JsonSerializer.SerializeToElement("San Francisco, CA") },
{ "unit", JsonSerializer.SerializeToElement("fahrenheit") },
},
new Dictionary<string, JsonElement>()
{
{ "location", JsonSerializer.SerializeToElement("Tokyo, Japan") },
{ "unit", JsonSerializer.SerializeToElement("celsius") },
},
new Dictionary<string, JsonElement>()
{
{ "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..12,-1..}
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;
import java.util.Map;
import java.util.List;
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"
)
)))
.putAdditionalProperty("required", JsonValue.from(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
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->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
```
</CodeGroup>
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.
<Note>
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.
</Note>
This diagram illustrates how each option works:
<Frame>
</Frame>
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.
<Note>
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.
</Note>
<Note>
[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.
</Note>
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.`
<Tip>
**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.
</Tip>
### 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 `<examples>` 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
<CardGroup>
<Card href="/docs/en/agents-and-tools/tool-use/handle-tool-calls" title="Handle tool calls">
Parse tool_use blocks and format tool_result responses.
</Card>
<Card href="/docs/en/agents-and-tools/tool-use/tool-runner" title="Tool Runner (SDK)">
Let the SDK handle the agentic loop automatically.
</Card>
<Card href="/docs/en/agents-and-tools/tool-use/tool-reference" title="Tool reference">
Directory of Anthropic-provided tools and optional properties.
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-fine-grained-tool-streaming-3f41c8f967.md
# Fine-grained tool streaming
Stream tool inputs character-by-character for latency-sensitive applications.
---
<Note>
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.
</Note>
Fine-grained tool streaming is generally 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.
<Warning>
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.
</Warning>
## How to use fine-grained tool streaming
Fine-grained tool streaming is available on all models and all platforms (Claude API, Amazon Bedrock, Google Vertex AI, and 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:
<CodeGroup>
```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);
```
</CodeGroup>
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.
<Note>
With fine-grained tool streaming, tool use chunks start streaming faster, and are often longer and contain fewer word breaks. This is due to 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 8: ' new f'
Chunk 9: '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'
```
</Note>
<Warning>
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.
</Warning>
## 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.
<CodeGroup>
```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<number, string> = {};
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);
}
}
```
</CodeGroup>
<Tip>
The Python and TypeScript SDKs provide higher-level stream helpers (`stream.get_final_message()`, `stream.finalMessage()`) that perform this accumulation for you. Use the manual pattern above 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.
</Tip>
## 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": "<your invalid json string>"
}
```
This approach helps the model understand that the content is invalid JSON while preserving the original malformed data for debugging purposes.
<Note>
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.
</Note>
## Next steps
<CardGroup cols={3}>
<Card title="Streaming messages" href="/docs/en/build-with-claude/streaming">
Full reference for server-sent events and stream event types.
</Card>
<Card title="Handle tool calls" href="/docs/en/agents-and-tools/tool-use/handle-tool-calls">
Execute tools and return results in the required message format.
</Card>
<Card title="Tool reference" href="/docs/en/agents-and-tools/tool-use/tool-reference">
Full directory of Anthropic-schema tools and their version strings.
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-handle-tool-calls-4a48c94000.md
# 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).
<Note>
**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.
</Note>
Claude's response differs based on whether it uses a client or server tool.
## 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`.
<section title="Example API response with a `tool_use` content block">
```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" }
}
]
}
```
</section>
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`: 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.
<Note>
**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.
</Note>
<section title="Example of successful tool result">
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 degrees"
}
]
}
```
</section>
<section title="Example of tool result with images">
```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..."
}
}
]
}
]
}
```
</section>
<section title="Example of empty tool result">
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9"
}
]
}
```
</section>
<section title="Example of tool result with documents">
```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"
}
}
]
}
]
}
```
</section>
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.
<Tip>
**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`.
</Tip>
## Handling errors with is_error
There are a few different types of errors that can occur when using tools with Claude:
<section title="Tool execution error">
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."
<Tip>
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.
</Tip>
</section>
<section title="Invalid tool name">
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.
<Tip>
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.
</Tip>
</section>
<section title="Server tool errors">
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
</section>
## 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).
---
## Agents-Tools/agents-and-tools-tool-use-how-tool-use-works-fdcca0c844.md
# 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
<CardGroup>
<Card href="/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent" title="Tutorial: Build a tool-using agent">
Build an agent step by step from a single tool call to production.
</Card>
<Card href="/docs/en/agents-and-tools/tool-use/define-tools" title="Define tools">
Schema specification, descriptions, and tool_choice.
</Card>
<Card href="/docs/en/agents-and-tools/tool-use/tool-reference" title="Tool reference">
Directory of Anthropic-provided tools.
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-manage-tool-context-ffb2d4526a.md
# 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
<CardGroup cols={2}>
<Card
title="Tool search tool"
icon="magnifying-glass"
href="/docs/en/agents-and-tools/tool-use/tool-search-tool"
>
Load tool definitions on demand instead of upfront.
</Card>
<Card
title="Programmatic tool calling"
icon="code"
href="/docs/en/agents-and-tools/tool-use/programmatic-tool-calling"
>
Collapse tool-call chains into a single executable script.
</Card>
<Card
title="Tool use with prompt caching"
icon="database"
href="/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching"
>
Cache tool definitions across requests to cut token costs.
</Card>
<Card
title="Context editing"
icon="scissors"
href="/docs/en/build-with-claude/context-editing"
>
Trim stale tool results from long-running conversations.
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-memory-tool-6d9391f81f.md
# 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.
<Note>
Reach out through the [feedback form](https://forms.gle/YXC2EKGMhjN1c4L88) to share your feedback on this feature.
</Note>
<Note>
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.
</Note>
## 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<guidelines>\n 2\t<addressing_customers>\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
<Note>
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)
</Note>
## Basic usage
<CodeGroup>
```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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->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
```
</CodeGroup>
## 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 \<topic\> 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
<Warning>
Malicious path inputs could attempt to access files outside the `/memories` directory. Your implementation **MUST** validate all paths to prevent directory traversal attacks.
</Warning>
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.
<Tip>
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).
</Tip>
## Next steps
<CardGroup>
<Card href="/docs/en/agents-and-tools/tool-use/tool-reference" title="See all tools">
Directory of Anthropic-provided tools and their properties.
</Card>
<Card href="/docs/en/build-with-claude/context-editing" title="Context editing">
Manage conversation length alongside memory.
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-overview-631f8e3a7e.md
# 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:
<CodeGroup>
```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);
```
</CodeGroup>
---
## 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](../../06-MCP-Tools/Tutorials/build-an-mcp-client-model-context-protocol.md).
<Tip>
**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).
</Tip>
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).
<section title="What happens when Claude needs more information">
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.
</section>
---
## 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`<hr />`any`, `tool` | 346 tokens<hr />313 tokens |
| Claude Opus 4.6 | `auto`, `none`<hr />`any`, `tool` | 346 tokens<hr />313 tokens |
| Claude Opus 4.5 | `auto`, `none`<hr />`any`, `tool` | 346 tokens<hr />313 tokens |
| Claude Opus 4.1 | `auto`, `none`<hr />`any`, `tool` | 346 tokens<hr />313 tokens |
| Claude Opus 4 | `auto`, `none`<hr />`any`, `tool` | 346 tokens<hr />313 tokens |
| Claude Sonnet 4.6 | `auto`, `none`<hr />`any`, `tool` | 346 tokens<hr />313 tokens |
| Claude Sonnet 4.5 | `auto`, `none`<hr />`any`, `tool` | 346 tokens<hr />313 tokens |
| Claude Sonnet 4 | `auto`, `none`<hr />`any`, `tool` | 346 tokens<hr />313 tokens |
| Claude Sonnet 3.7 ([deprecated](/docs/en/about-claude/model-deprecations)) | `auto`, `none`<hr />`any`, `tool` | 346 tokens<hr />313 tokens |
| Claude Haiku 4.5 | `auto`, `none`<hr />`any`, `tool` | 346 tokens<hr />313 tokens |
| Claude Haiku 3.5 | `auto`, `none`<hr />`any`, `tool` | 264 tokens<hr />340 tokens |
| Claude Opus 3 ([deprecated](/docs/en/about-claude/model-deprecations)) | `auto`, `none`<hr />`any`, `tool` | 530 tokens<hr />281 tokens |
| Claude Sonnet 3 | `auto`, `none`<hr />`any`, `tool` | 159 tokens<hr />235 tokens |
| Claude Haiku 3 | `auto`, `none`<hr />`any`, `tool` | 264 tokens<hr />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
<CardGroup>
<Card href="/docs/en/agents-and-tools/tool-use/how-tool-use-works" title="Understand the concepts">
Where tools run, how the loop works, and when to use tools.
</Card>
<Card href="/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent" title="Build step by step">
The tutorial: from a single tool call to production.
</Card>
<Card href="/docs/en/agents-and-tools/tool-use/tool-reference" title="Browse all tools">
Directory of Anthropic-provided tools and properties.
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-parallel-tool-use-93edcb192b.md
# 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
<Note>
**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.
</Note>
Here's a complete, runnable script to test and verify parallel tool calls are working correctly:
<CodeGroup>
```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(`\nClaude 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)}`);
}
});
}
// 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<string, string>;
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`);
}
testParallelTools().catch(console.error);
```
```csharp C#
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<ToolUnion>
{
new ToolUnion(new Tool()
{
Name = "get_weather",
Description = "Get the current weather in a given location",
InputSchema = new InputSchema()
{
Properties = new Dictionary<string, JsonElement>
{
["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<string, JsonElement>
{
["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<ToolUseBlock>();
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<ContentBlockParam>();
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,-11..-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<ToolUseBlock> 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<ContentBlockParam> 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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$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']
]
]
];
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"
```
</CodeGroup>
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:
<section title="System prompts for parallel tool use">
For Claude 4 models (Opus 4 (deprecated), and Sonnet 4 (deprecated)), 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
<use_parallel_tool_calls>
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.
</use_parallel_tool_calls>
```
</section>
<section title="User message prompting">
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."
```
</section>
## 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).
---
## Agents-Tools/agents-and-tools-tool-use-programmatic-tool-calling-95ea7cf823.md
# 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.
<Tip>
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).
</Tip>
<Note>
This feature requires the code execution tool to be enabled.
</Note>
<Note>
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.
</Note>
## 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 via the Claude API and Microsoft Foundry.
## Quick start
Here's a simple example where Claude programmatically queries a database multiple times and aggregates results:
<CodeGroup>
```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
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..4}
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#
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<string, JsonElement>
{
["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
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->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
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
```
</CodeGroup>
## 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 via 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
<Note>
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("<sql>")`) and automatically includes the appropriate async wrapper function.
The async wrapper is omitted from code examples in this documentation for clarity.
</Note>
## 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
<Tip>
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.
</Tip>
### 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": "<sql>" },
"caller": { "type": "direct" }
}
```
**Programmatic invocation:**
```json
{
"type": "tool_use",
"id": "toolu_xyz789",
"name": "query_database",
"input": { "sql": "<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 session 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 via the `container` field
- **Reuse:** Pass the container ID to maintain state across requests
<Warning>
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.
</Warning>
## 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.
<Note>
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.
</Note>
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.
### 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('<sql>')\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": "<sql>" },
"caller": {
"type": "code_execution_20260120",
"tool_id": "srvtoolu_abc123"
}
}
],
"container": {
"id": "container_xyz789",
"expires_at": "2025-01-15T14:30:00Z"
},
"stop_reason": "tool_use"
}
```
### Step 3: Provide tool result
Include the full conversation history plus your tool result:
<CodeGroup>
```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: "<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": "<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: "<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 = "<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": "<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", "<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
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->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' => '<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: "<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
```
</CodeGroup>
### 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 by revenue:\n1. Customer C1: $45,000\n2. Customer C2: $38,000\n3. Customer C5: $32,000\n4. Customer C8: $28,500\n5. Customer C3: $24,000",
"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"<sql for {region}>")
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": "<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 |
| `missing_beta_header` | Required beta header not provided (Bedrock and Vertex AI only; programmatic tool calling is GA on the first-party Claude API) | Add the required beta headers to your request |
### 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 via `tool_choice`
- **Parallel tool use:** `disable_parallel_tool_use: true` is not supported with programmatic calling
### Tool restrictions
The following tools cannot currently be called programmatically, but support may be added in future releases:
- 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.
<Note>
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.
</Note>
## 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 be implemented outside of Anthropic's managed code execution. Here's an overview of the approaches:
### 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.
## 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/build-with-claude/api-and-data-retention).
## Related features
<CardGroup cols={2}>
<Card title="Code Execution Tool" icon="code" href="/docs/en/agents-and-tools/tool-use/code-execution-tool">
Learn about the underlying code execution capability that powers programmatic tool calling.
</Card>
<Card title="Tool Use Overview" icon="wrench" href="/docs/en/agents-and-tools/tool-use/overview">
Understand the fundamentals of tool use with Claude.
</Card>
<Card title="Define tools" icon="hammer" href="/docs/en/agents-and-tools/tool-use/define-tools">
Step-by-step guide for defining tools.
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-server-tools-c13eb821bf.md
# 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:
<CodeGroup>
```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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$response = $client->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
```
</CodeGroup>
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/build-with-claude/zero-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.
<Note>
While the web fetch tool itself is ZDR-eligible, website publishers may retain any parameters passed to the URL if Claude fetches content from their site.
</Note>
## 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.
<Note>
Request-level domain restrictions must be compatible with organization-level domain restrictions configured in the 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.
</Note>
<Warning>
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
</Warning>
## 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.
<Warning>
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.
</Warning>
## 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
<CardGroup cols={2}>
<Card title="Web search" icon="magnifying-glass" href="/docs/en/agents-and-tools/tool-use/web-search-tool">
Search the web and cite results.
</Card>
<Card title="Web fetch" icon="globe" href="/docs/en/agents-and-tools/tool-use/web-fetch-tool">
Retrieve content from specific URLs.
</Card>
<Card title="Code execution" icon="terminal" href="/docs/en/agents-and-tools/tool-use/code-execution-tool">
Run Python in a sandboxed container.
</Card>
<Card title="Tool search" icon="list-magnifying-glass" href="/docs/en/agents-and-tools/tool-use/tool-search-tool">
Discover and load tools on demand.
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-strict-tool-use-6896c973b6.md
# Strict tool use
Enforce JSON Schema compliance on Claude's tool inputs with grammar-constrained sampling.
---
Setting `strict: true` on a tool definition uses grammar-constrained sampling to guarantee Claude's tool inputs match your JSON Schema. 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 will always contain `passengers: 2`.
## Quick start
<CodeGroup>
```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;
public class Program
{
public static async Task Main(string[] args)
{
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<string, JsonElement>
{
["properties"] = JsonSerializer.SerializeToElement(new Dictionary<string, object>
{
["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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->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
```
</CodeGroup>
**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
<Steps>
<Step title="Define your tool schema">
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)).
</Step>
<Step title="Add strict: true">
Set `"strict": true` as a top-level property in your tool definition, alongside `name`, `description`, and `input_schema`.
</Step>
<Step title="Handle tool calls">
When Claude uses the tool, the `input` field in the tool_use block will strictly follow your `input_schema`, and the `name` will always be valid.
</Step>
</Steps>
## Common use cases
<section title="Validated tool inputs">
Ensure tool parameters exactly match your schema:
<CodeGroup>
```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;
using System.Text.Json;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages;
class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new()
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
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<string, JsonElement>
{
["properties"] = JsonSerializer.SerializeToElement(new Dictionary<string, object>
{
["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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->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
]
]
],
);
```
```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
```
</CodeGroup>
</section>
<section title="Agentic workflow with multiple validated tools">
Build reliable multi-step agents with guaranteed tool parameters:
<CodeGroup>
```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;
class Program
{
static async Task Main(string[] args)
{
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<string, JsonElement>
{
["properties"] = JsonSerializer.SerializeToElement(new Dictionary<string, object>
{
["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<string, JsonElement>
{
["properties"] = JsonSerializer.SerializeToElement(new Dictionary<string, object>
{
["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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->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->content[0]->text;
```
```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
```
</CodeGroup>
</section>
## 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/build-with-claude/api-and-data-retention).
---
## Agents-Tools/agents-and-tools-tool-use-text-editor-tool-252bfe1f5b.md
# Text editor tool
---
<Note>
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.
</Note>
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.
<Note>
`max_characters` is only compatible with `text_editor_20250728` and later versions of the text editor tool.
</Note>
<CodeGroup>
```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);
}
```
</CodeGroup>
The text editor tool can be used in the following way:
<Steps>
<Step title="Provide Claude with the text editor tool and a user prompt">
- 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?"
</Step>
<Step title="Claude uses the tool to examine files or directories">
- 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
</Step>
<Step title="Execute the view command and return results">
- 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
</Step>
<Step title="Claude uses the tool to modify files">
- 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
</Step>
<Step title="Execute the edit and return results">
- 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
</Step>
<Step title="Claude provides its analysis and explanation">
- After examining and possibly editing the files, Claude provides a complete explanation of what it found and what changes it made
</Step>
</Steps>
### 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.
<section title="Example view commands">
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/"
}
}
```
</section>
#### 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
<section title="Example str_replace command">
```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):"
}
}
```
</section>
#### 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
<section title="Example create command">
```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()"
}
}
```
</section>
#### 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
<section title="Example insert command">
```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"
}
}
```
</section>
### 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:
<CodeGroup>
```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);
}
```
</CodeGroup>
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:
<CodeGroup>
```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);
}
}
```
</CodeGroup>
<Tip>
**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.
</Tip>
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:
<CodeGroup>
```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);
}
}
```
</CodeGroup>
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.
<Steps>
<Step title="Initialize your editor implementation">
Create helper functions to handle file operations like reading, writing, and modifying files. Consider implementing backup functionality to recover from mistakes.
</Step>
<Step title="Handle editor tool calls">
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
```
</Step>
<Step title="Implement security measures">
Add validation and security checks:
- Validate file paths to prevent directory traversal
- Create backups before making changes
- Handle errors gracefully
- Implement permissions checks
</Step>
<Step title="Process Claude's responses">
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,
}
```
</Step>
</Steps>
<Warning>
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.
</Warning>
### Handle errors
When using the text editor tool, various errors may occur. Here is guidance on how to handle them:
<section title="File not found">
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
}
]
}
```
</section>
<section title="Multiple matches for replacement">
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
}
]
}
```
</section>
<section title="No matches for replacement">
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
}
]
}
```
</section>
<section title="Permission errors">
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
}
]
}
```
</section>
### Follow implementation best practices
<section title="Provide clear context">
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?"
</section>
<section title="Be explicit about file paths">
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?"
</section>
<section title="Create backups before editing">
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())
```
</section>
<section title="Handle unique text replacement carefully">
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"
```
</section>
<section title="Verify changes">
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)}"
```
</section>
---
## 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 |
| `text_editor_20250124` (Claude Sonnet 3.7 ([deprecated](/docs/en/about-claude/model-deprecations))) | 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.
<CardGroup cols={3}>
<Card
title="Tool use overview"
icon="wrench"
href="/docs/en/agents-and-tools/tool-use/overview"
>
Learn how to implement tool workflows for use with Claude.
</Card>
<Card
title="Bash tool"
icon="terminal"
href="/docs/en/agents-and-tools/tool-use/bash-tool"
>
Execute shell commands with Claude.
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-tool-combinations-9ef3cff9d6.md
# 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
<CardGroup cols={2}>
<Card
title="Tool reference"
icon="book"
href="/docs/en/agents-and-tools/tool-use/tool-reference"
>
Full catalog of Anthropic-provided tools with type strings and parameters.
</Card>
<Card
title="Tool use overview"
icon="map"
href="/docs/en/agents-and-tools/tool-use/overview"
>
How tool use works and when to use Anthropic tools versus defining your own.
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-tool-reference-73b4586472.md
# 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`<br/>`web_search_20250305` | Server | GA |
| [Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool) | `web_fetch_20260209`<br/>`web_fetch_20250910` | Server | GA |
| [Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool) | `code_execution_20260120`<br/>`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`<br/>`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`<br/>`text_editor_20250124` | Client | GA |
| [Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool) | `computer_20251124`<br/>`computer_20250124` | Client | Beta: `computer-use-2025-11-24`<br/>`computer-use-2025-01-24` |
For model compatibility, see each tool's page. Supported models vary by tool and by tool version.
<Note>
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.
</Note>
### 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).
---
## Agents-Tools/agents-and-tools-tool-use-tool-runner-8ab76faf78.md
# 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.
<Note>
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.
</Note>
<Tip>
**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.
</Tip>
## Basic usage
Define tools using the SDK helpers, then use the tool runner to execute them.
<Tabs>
<Tab title="Python">
Use the `@beta_tool` decorator to define tools with type hints and docstrings.
<Note>
If you're using the async client, replace `@beta_tool` with `@beta_async_tool` and define the function with `async def`.
</Note>
```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"
}
}
```
</Tab>
<Tab title="TypeScript">
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:
<Note>
The input generated by Claude will not be validated at runtime. Perform validation inside the `run` function if needed.
</Note>
```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);
}
}
```
</Tab>
<Tab title="Ruby">
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.
</Tab>
</Tabs>
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 will be 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 will loop until Claude returns a message without a tool use.
If you don't need intermediate messages, you can get the final message directly:
<Tabs>
<Tab title="Python">
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()
print(final_message.content[0].text)
```
</Tab>
<Tab title="TypeScript">
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;
console.log(finalMessage.content[0].text);
```
</Tab>
<Tab title="Ruby">
Use `runner.run_until_finished` to get all messages.
```ruby hidelines={1..25}
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 }
```
</Tab>
</Tabs>
## 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.
<Tabs>
<Tab title="Python">
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."}
)
```
</Tab>
<Tab title="TypeScript">
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." });
}
```
</Tab>
<Tab title="Ruby">
Use `next_message` for step-by-step control. Use `feed_messages` to inject messages and `params` to access parameters.
```ruby hidelines={1..12}
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
```
</Tab>
</Tabs>
### 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:
<Tabs>
<Tab title="Python">
```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)
```
</Tab>
<Tab title="TypeScript">
```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);
}
```
</Tab>
<Tab title="Ruby">
```ruby hidelines={1..12}
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
```
</Tab>
</Tabs>
### Modifying tool results
You can modify tool results before they're sent back to Claude. This is useful for adding metadata like `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.
<Tabs>
<Tab title="Python">
```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)
```
</Tab>
<Tab title="TypeScript">
```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);
}
```
</Tab>
<Tab title="Ruby">
```ruby hidelines={1..12}
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 we can modify them
tool_results_message = runner.params[:messages].last
if tool_results_message && tool_results_message[:role] == :user
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
```
</Tab>
</Tabs>
<Tip>
Adding `cache_control` to tool results is particularly useful when tools return large amounts of data (like 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.
</Tip>
## Streaming
Enable streaming to receive events as they arrive. Each iteration yields a stream object that you can iterate for events.
<Tabs>
<Tab title="Python">
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())
```
</Tab>
<Tab title="TypeScript">
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: 1000,
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);
```
</Tab>
<Tab title="Ruby">
Use `each_streaming` to iterate over streaming events.
```ruby hidelines={1..13}
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
```
</Tab>
</Tabs>
## 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).
---
## Agents-Tools/agents-and-tools-tool-use-tool-search-tool-5499cf85ce.md
# 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.
<Tip>
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).
</Tip>
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.
<Note>
Share feedback on this feature through the [feedback form](https://forms.gle/MhcGFFwLxuwnWTkYA).
</Note>
<Note>
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.
</Note>
<Warning>
On Amazon Bedrock, server-side tool search is available only via the [invoke
API](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-runtime_example_bedrock-runtime_InvokeModel_AnthropicClaude_section.html),
not the converse API.
</Warning>
You can also implement [client-side tool search](#custom-tool-search-implementation) by returning `tool_reference` blocks from your own search implementation.
## 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 (e.g., `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 invokes them
This keeps your context window efficient while maintaining high tool selection accuracy.
## Quick start
Here's a simple example with deferred tools:
<CodeGroup>
```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..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: 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(JSON.stringify(response, null, 2));
}
main();
```
```csharp C#
using System;
using System.Text.Json;
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 = 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<string, JsonElement>
{
["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<string, JsonElement>
{
["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,10..14,-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.Model;
import com.anthropic.models.messages.Tool;
import com.anthropic.models.messages.Tool.InputSchema;
import com.anthropic.models.messages.ToolSearchToolRegex20251119;
import java.util.List;
import java.util.Map;
public class ToolSearchExample {
public static void main(String[] args) {
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);
System.out.println(response);
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->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
```
</CodeGroup>
## 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"
}
```
<Warning>
**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
</Warning>
<Note>
**BM25 variant query format: Natural language**
When using `tool_search_tool_bm25_20251119`, Claude uses natural language queries to search for tools.
</Note>
### 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 via 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 tool definition is appended inline as a `tool_reference` block in the conversation. The prefix is untouched, so prompt caching is preserved. The grammar for strict mode 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 invoking 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 invoking 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 (e.g., 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.
<Note>
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 above.
</Note>
For a complete example using embeddings, see the [tool search with embeddings cookbook](https://platform.claude.com/cookbooks/tool_use).
## Error handling
<Note>
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.
</Note>
### 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_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
<section title="400 Error: All tools are deferred">
**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", // No defer_loading here
"name": "tool_search_tool_regex"
}
```
</section>
<section title="400 Error: Missing tool definition">
**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": {
// complete schema
},
"defer_loading": true
}
```
</section>
<section title="Claude doesn't find expected tools">
**Cause:** Tool names or descriptions don't match the regex pattern
**Debugging steps:**
1. Check tool name and description. Claude searches BOTH 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 like `".*weather.*"` not exact matches
**Tip:** Add common keywords to tool descriptions to improve discoverability
</section>
## 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 (e.g., `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
<CardGroup cols={2}>
<Card title="Tool reference" icon="list" href="/docs/en/agents-and-tools/tool-use/tool-reference">
Full tool catalog with model compatibility and parameters.
</Card>
<Card title="MCP connector" icon="plug" href="/docs/en/agents-and-tools/mcp-connector">
Configure MCP toolsets with deferred loading.
</Card>
<Card title="Prompt caching" icon="bolt" href="/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching">
Combine tool search with cached tool definitions.
</Card>
<Card title="Define tools" icon="hammer" href="/docs/en/agents-and-tools/tool-use/define-tools">
Step-by-step guide for defining tools.
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-tool-use-with-prompt-caching-a19f41d804.md
# 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 |
<Note>
If you need to vary `tool_choice` mid-conversation, consider placing cache breakpoints before the variation point.
</Note>
## 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
<CardGroup cols={3}>
<Card title="Prompt caching" icon="database" href="/docs/en/build-with-claude/prompt-caching">
Learn the full prompt caching model, including TTLs and pricing.
</Card>
<Card title="Tool search" icon="magnifying-glass" href="/docs/en/agents-and-tools/tool-use/tool-search-tool">
Load tools on demand without breaking your cache.
</Card>
<Card title="Tool reference" icon="book" href="/docs/en/agents-and-tools/tool-use/tool-reference">
Browse all available tools and their parameters.
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-troubleshooting-tool-use-e25c7591a5.md
# 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
<CardGroup cols={3}>
<Card title="Define tools" href="/docs/en/agents-and-tools/tool-use/define-tools">
Write schemas and descriptions that steer Claude toward the right tool.
</Card>
<Card title="Handle tool calls" href="/docs/en/agents-and-tools/tool-use/handle-tool-calls">
Execute tools and return results in the required message format.
</Card>
<Card title="Tool reference" href="/docs/en/agents-and-tools/tool-use/tool-reference">
Full directory of Anthropic-schema tools and their version strings.
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-web-fetch-tool-d9b8c0ffca.md
# 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.
<Note>
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 Google Vertex AI.
</Note>
<Note>
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.
</Note>
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).
<Warning>
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
</Warning>
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.
<Note>
The web fetch tool currently does not support websites dynamically rendered via JavaScript.
</Note>
### 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
<Note>
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 and Microsoft Azure.
</Note>
To enable dynamic filtering, use the `web_fetch_20260209` tool version:
<CodeGroup>
```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#
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages;
class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new()
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
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,7..9,-2..}
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;
public class WebFetchExample {
public static void main(String[] args) {
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);
System.out.println(response);
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->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
```
</CodeGroup>
## How to use web fetch
Provide the web fetch tool in your API request:
<CodeGroup>
```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#
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages;
class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new()
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
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,7..9,-2..}
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;
public class WebFetchExample {
public static void main(String[] args) {
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);
System.out.println(response);
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->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
```
</CodeGroup>
### 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.
<Note>
The `max_content_tokens` parameter limit is approximate. The actual number of input tokens used can vary by a small amount.
</Note>
#### 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.
<Note>
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.
</Note>
### 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
<Note>
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.
</Note>
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},
},
],
)
```
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
<CardGroup>
<Card href="/docs/en/agents-and-tools/tool-use/server-tools" title="Server tools">
Shared mechanics for Anthropic-executed tools.
</Card>
<Card href="/docs/en/agents-and-tools/tool-use/tool-reference" title="Tool reference">
Directory of all Anthropic-provided tools.
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-web-search-tool-874fc28332.md
# 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.
<Note>
For [Claude Mythos Preview](https://anthropic.com/glasswing), web search is supported on the Claude API, Microsoft Foundry, and Google Vertex AI. Web search is not available for Mythos Preview on Amazon Bedrock.
</Note>
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
<Note>
Dynamic filtering requires the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool) to be enabled. The improved web search tool is available on the Claude API and Microsoft Azure. On Google Vertex AI, the basic web search tool (without dynamic filtering) is available.
</Note>
To enable dynamic filtering, use the `web_search_20260209` tool version:
<CodeGroup>
```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 nocheck 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:
"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);
}
main().catch(console.error);
```
```csharp C#
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 = "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,7..9,-2..}
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;
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 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);
System.out.println(response);
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->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
```
</CodeGroup>
## How to use web search
<Note>
Your organization's administrator must enable web search in the [Claude Console](/settings/privacy).
</Note>
Provide the web search tool in your API request:
<CodeGroup>
```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#
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 = 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,7..9,-2..}
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;
public class WebSearchExample {
public static void main(String[] args) {
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);
System.out.println(response);
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->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
```
</CodeGroup>
### 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.
<Note>
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.
</Note>
#### 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": "servertoolu_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
<CardGroup>
<Card href="/docs/en/agents-and-tools/tool-use/server-tools" title="Server tools">
Shared mechanics for Anthropic-executed tools.
</Card>
<Card href="/docs/en/agents-and-tools/tool-use/tool-reference" title="Tool reference">
Directory of all Anthropic-provided tools.
</Card>
</CardGroup>
---
## Guides/build-with-claude-adaptive-thinking-2b96627d8d.md
# Adaptive thinking
Let Claude dynamically determine when and how much to use extended thinking with adaptive thinking mode.
---
<Note>
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.
</Note>
Adaptive thinking is the recommended way to use [extended thinking](/docs/en/build-with-claude/extended-thinking) with Claude Opus 4.7, Claude Opus 4.6, and Claude Sonnet 4.6, and is the default mode on [Claude Mythos Preview](https://anthropic.com/glasswing) (where it auto-applies whenever `thinking` is unset). Instead of manually setting a thinking token budget, adaptive thinking lets Claude dynamically determine when and how much to use extended thinking based on the complexity of each request. On Claude Opus 4.7, adaptive thinking is the **only** supported thinking mode; manual `thinking: {type: "enabled", budget_tokens: N}` is no longer accepted.
<Tip>
Adaptive thinking can drive better performance than extended thinking with a fixed `budget_tokens` for many workloads, especially bimodal tasks and long-horizon agentic workflows. No beta header is required.
If your workload requires predictable latency or precise control over thinking costs, extended thinking with `budget_tokens` is still functional on Claude Opus 4.6 and Claude Sonnet 4.6 but is deprecated and no longer recommended. See the warning below.
</Tip>
## Supported models
Adaptive thinking is supported on the following models:
- Claude Mythos Preview (`claude-mythos-preview`), adaptive thinking is the default; `thinking: {type: "disabled"}` is not supported
- Claude Opus 4.7 (`claude-opus-4-7`), adaptive thinking is the only supported thinking mode. Thinking is off unless you explicitly set `thinking: {type: "adaptive"}` in your request; manual `thinking: {type: "enabled"}` is rejected with a 400 error.
- Claude Opus 4.6 (`claude-opus-4-6`)
- Claude Sonnet 4.6 (`claude-sonnet-4-6`)
<Warning>
`thinking.type: "enabled"` and `budget_tokens` are [**deprecated**](/docs/en/build-with-claude/overview#feature-availability) on Opus 4.6 and Sonnet 4.6 and will be removed in a future model release. Use `thinking.type: "adaptive"` with the `effort` parameter instead. Existing `budget_tokens` configurations are still functional but no longer recommended; plan to migrate.
Older models (Sonnet 4.5, Opus 4.5, etc.) do not support adaptive thinking and require `thinking.type: "enabled"` with `budget_tokens`.
</Warning>
## How adaptive thinking works
In adaptive mode, thinking is optional for the model. Claude evaluates the complexity of each request and determines whether and how much to use extended thinking. At the default effort level (`high`), Claude almost always thinks. At lower effort levels, Claude may skip thinking for simpler problems.
Adaptive thinking also automatically enables [interleaved thinking](/docs/en/build-with-claude/extended-thinking#interleaved-thinking). This means Claude can think between tool calls, making it especially effective for agentic workflows.
## How to use adaptive thinking
Set `thinking.type` to `"adaptive"` in your API request:
<CodeGroup>
```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": 16000,
"thinking": {
"type": "adaptive"
},
"messages": [
{
"role": "user",
"content": "Explain why the sum of two even numbers is always even."
}
]
}'
```
```bash CLI nocheck
ant messages create \
--model claude-opus-4-7 \
--max-tokens 16000 \
--thinking '{type: adaptive}' \
--message '{role: user, content: Explain why the sum of two even numbers is always even.}' \
--transform content --format jsonl |
jq -r '
if .type == "thinking" then "\nThinking: \(.thinking)"
elif .type == "text" then "\nResponse: \(.text)"
else empty end'
```
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=16000,
thinking={"type": "adaptive"},
messages=[
{
"role": "user",
"content": "Explain why the sum of two even numbers is always even.",
}
],
)
for block in response.content:
if block.type == "thinking":
print(f"\nThinking: {block.thinking}")
elif block.type == "text":
print(f"\nResponse: {block.text}")
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-4-7",
max_tokens: 16000,
thinking: {
type: "adaptive"
},
messages: [
{
role: "user",
content: "Explain why the sum of two even numbers is always even."
}
]
} as unknown as Anthropic.MessageCreateParamsNonStreaming);
for (const block of response.content) {
if (block.type === "thinking") {
console.log(`\nThinking: ${block.thinking}`);
} else if (block.type === "text") {
console.log(`\nResponse: ${block.text}`);
}
}
```
```csharp C#
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 = 16000,
Thinking = new ThinkingConfigAdaptive(),
Messages = [
new() {
Role = Role.User,
Content = "Explain why the sum of two even numbers is always even."
}
]
};
var message = await client.Messages.Create(parameters);
foreach (var block in message.Content)
{
if (block.TryPickThinking(out ThinkingBlock? thinking))
{
Console.WriteLine($"\nThinking: {thinking.Thinking}");
}
else if (block.TryPickText(out TextBlock? text))
{
Console.WriteLine($"\nResponse: {text.Text}");
}
}
}
}
```
```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: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{
OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Explain why the sum of two even numbers is always even.")),
},
})
if err != nil {
log.Fatal(err)
}
for _, block := range response.Content {
switch v := block.AsAny().(type) {
case anthropic.ThinkingBlock:
fmt.Printf("\nThinking: %s", v.Thinking)
case anthropic.TextBlock:
fmt.Printf("\nResponse: %s", v.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.ThinkingConfigAdaptive;
public class ExtendedThinkingExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(16000L)
.thinking(ThinkingConfigAdaptive.builder().build())
.addUserMessage("Explain why the sum of two even numbers is always even.")
.build();
Message response = client.messages().create(params);
response.content().forEach(block -> {
block.thinking().ifPresent(thinkingBlock ->
System.out.println("\nThinking: " + thinkingBlock.thinking())
);
block.text().ifPresent(textBlock ->
System.out.println("\nResponse: " + textBlock.text())
);
});
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->messages->create(
maxTokens: 16000,
messages: [
[
'role' => 'user',
'content' => 'Explain why the sum of two even numbers is always even.'
]
],
model: 'claude-opus-4-7',
thinking: ['type' => 'adaptive'],
);
foreach ($message->content as $block) {
if ($block->type === 'thinking') {
echo "\nThinking: " . $block->thinking;
} elseif ($block->type === 'text') {
echo "\nResponse: " . $block->text;
}
}
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-4-7",
max_tokens: 16000,
thinking: {
type: "adaptive"
},
messages: [
{
role: "user",
content: "Explain why the sum of two even numbers is always even."
}
]
)
message.content.each do |block|
case block.type
when :thinking
puts "\nThinking: #{block.thinking}"
when :text
puts "\nResponse: #{block.text}"
end
end
```
</CodeGroup>
## Adaptive thinking with the effort parameter
You can combine adaptive thinking with the [effort parameter](/docs/en/build-with-claude/effort) to guide how much thinking Claude does. The effort level acts as soft guidance for Claude's thinking allocation:
| Effort level | Thinking behavior |
|:-------------|:------------------|
| `max` | Claude always thinks with no constraints on thinking depth. Available on Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, and Claude Sonnet 4.6. |
| `xhigh` | Claude always thinks deeply with extended exploration. Available on Claude Opus 4.7. |
| `high` (default) | Claude always thinks. Provides deep reasoning on complex tasks. |
| `medium` | Claude uses moderate thinking. May skip thinking for very simple queries. |
| `low` | Claude minimizes thinking. Skips thinking for simple tasks where speed matters most. |
<CodeGroup>
```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": 16000,
"thinking": {
"type": "adaptive"
},
"output_config": {
"effort": "medium"
},
"messages": [
{
"role": "user",
"content": "What is the capital of France?"
}
]
}'
```
```bash CLI
ant messages create \
--transform 'content.0.text' --format yaml <<'YAML'
model: claude-opus-4-7
max_tokens: 16000
thinking:
type: adaptive
output_config:
effort: medium
messages:
- role: user
content: What is the capital of France?
YAML
```
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=16000,
thinking={"type": "adaptive"},
output_config={"effort": "medium"},
messages=[{"role": "user", "content": "What is the capital of France?"}],
)
print(response.content[0].text)
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-4-7",
max_tokens: 16000,
thinking: {
type: "adaptive"
},
output_config: {
effort: "medium"
},
messages: [
{
role: "user",
content: "What is the capital of France?"
}
]
} as unknown as Anthropic.MessageCreateParamsNonStreaming);
for (const block of response.content) {
if (block.type === "text") {
console.log(block.text);
}
}
```
```csharp C#
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 = 16000,
Thinking = new ThinkingConfigAdaptive(),
OutputConfig = new OutputConfig { Effort = Effort.Medium },
Messages = [new() { Role = Role.User, Content = "What is the capital of France?" }]
};
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: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{
OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
},
OutputConfig: anthropic.OutputConfigParam{
Effort: anthropic.OutputConfigEffortMedium,
},
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)
}
```
```java Java hidelines={1..5,8..10,-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.OutputConfig;
import com.anthropic.models.messages.ThinkingConfigAdaptive;
public class Main {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(16000L)
.thinking(ThinkingConfigAdaptive.builder().build())
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.MEDIUM)
.build())
.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()));
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->messages->create(
maxTokens: 16000,
messages: [
['role' => 'user', 'content' => 'What is the capital of France?']
],
model: 'claude-opus-4-7',
thinking: ['type' => 'adaptive'],
outputConfig: ['effort' => 'medium'],
);
echo $message->content[0]->text;
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-4-7",
max_tokens: 16000,
thinking: {
type: "adaptive"
},
output_config: {
effort: "medium"
},
messages: [
{ role: "user", content: "What is the capital of France?" }
]
)
puts message.content.first.text
```
</CodeGroup>
## Streaming with adaptive thinking
Adaptive thinking works seamlessly with [streaming](/docs/en/build-with-claude/streaming). Thinking blocks are streamed via `thinking_delta` events just like manual thinking mode:
<CodeGroup>
```bash CLI
ant messages create --stream --format jsonl \
--model claude-opus-4-7 \
--max-tokens 16000 \
--thinking '{type: adaptive}' \
--message '{role: user, content: What is the greatest common divisor of 1071 and 462?}'
```
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
with client.messages.stream(
model="claude-opus-4-7",
max_tokens=16000,
thinking={"type": "adaptive"},
messages=[
{
"role": "user",
"content": "What is the greatest common divisor of 1071 and 462?",
}
],
) as stream:
for event in stream:
if event.type == "content_block_start":
print(f"\nStarting {event.content_block.type} block...")
elif event.type == "content_block_delta":
if event.delta.type == "thinking_delta":
print(event.delta.thinking, end="", flush=True)
elif event.delta.type == "text_delta":
print(event.delta.text, end="", flush=True)
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const stream = await client.messages.stream({
model: "claude-opus-4-7",
max_tokens: 16000,
thinking: { type: "adaptive" },
messages: [{ role: "user", content: "What is the greatest common divisor of 1071 and 462?" }]
} as unknown as Anthropic.MessageStreamParams);
for await (const event of stream) {
if (event.type === "content_block_start") {
console.log(`\nStarting ${event.content_block.type} block...`);
} else if (event.type === "content_block_delta") {
if (event.delta.type === "thinking_delta") {
process.stdout.write(event.delta.thinking);
} else if (event.delta.type === "text_delta") {
process.stdout.write(event.delta.text);
}
}
}
```
```csharp C#
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 = 16000,
Thinking = new ThinkingConfigAdaptive(),
Messages = [new() { Role = Role.User, Content = "What is the greatest common divisor of 1071 and 462?" }]
};
await foreach (var msg in client.Messages.CreateStreaming(parameters))
{
Console.Write(msg);
}
}
}
```
```go Go hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_7,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{
OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What is the greatest common divisor of 1071 and 462?")),
},
})
for stream.Next() {
event := stream.Current()
switch eventVariant := event.AsAny().(type) {
case anthropic.ContentBlockStartEvent:
fmt.Printf("\nStarting %s block...\n", eventVariant.ContentBlock.Type)
case anthropic.ContentBlockDeltaEvent:
switch deltaVariant := eventVariant.Delta.AsAny().(type) {
case anthropic.ThinkingDelta:
fmt.Print(deltaVariant.Thinking)
case anthropic.TextDelta:
fmt.Print(deltaVariant.Text)
}
}
}
if err := stream.Err(); err != nil {
log.Fatal(err)
}
}
```
```java Java hidelines={1..4,6..8,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.ThinkingConfigAdaptive;
public class StreamingThinkingExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(16000L)
.thinking(ThinkingConfigAdaptive.builder().build())
.addUserMessage("What is the greatest common divisor of 1071 and 462?")
.build();
try (var streamResponse = client.messages().createStreaming(params)) {
streamResponse.stream().forEach(event -> {
if (event.contentBlockStart().isPresent()) {
var startEvent = event.contentBlockStart().get();
var block = startEvent.contentBlock();
if (block.isThinking()) {
System.out.println("\nStarting thinking block...");
} else if (block.isText()) {
System.out.println("\nStarting text block...");
}
} else if (event.contentBlockDelta().isPresent()) {
var deltaEvent = event.contentBlockDelta().get();
deltaEvent.delta().thinking().ifPresent(td ->
System.out.print(td.thinking())
);
deltaEvent.delta().text().ifPresent(td ->
System.out.print(td.text())
);
}
});
}
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$stream = $client->messages->createStream(
maxTokens: 16000,
messages: [
['role' => 'user', 'content' => 'What is the greatest common divisor of 1071 and 462?']
],
model: 'claude-opus-4-7',
thinking: ['type' => 'adaptive'],
);
foreach ($stream as $event) {
if ($event->type === 'content_block_start') {
echo "\nStarting {$event->contentBlock->type} block...\n";
} elseif ($event->type === 'content_block_delta') {
if ($event->delta->type === 'thinking_delta') {
echo $event->delta->thinking;
} elseif ($event->delta->type === 'text_delta') {
echo $event->delta->text;
}
}
}
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
stream = client.messages.stream(
model: "claude-opus-4-7",
max_tokens: 16000,
thinking: { type: "adaptive" },
messages: [
{ role: "user", content: "What is the greatest common divisor of 1071 and 462?" }
]
)
stream.each do |event|
case event
when Anthropic::Streaming::ThinkingEvent
print event.thinking
when Anthropic::Streaming::TextEvent
print event.text
end
end
```
</CodeGroup>
## Adaptive vs manual vs disabled thinking
| Mode | Config | Availability | When to use |
|:-----|:-------|:-------------|:------------|
| **Adaptive** | `thinking: {type: "adaptive"}` | Claude Mythos Preview (default), Opus 4.7 (only mode), Opus 4.6, Sonnet 4.6 | Claude determines when and how much to use extended thinking. Use `effort` to guide. |
| **Manual** | `thinking: {type: "enabled", budget_tokens: N}` | All models except Claude Opus 4.7 (rejected). Deprecated on Opus 4.6 and Sonnet 4.6 (consider adaptive mode instead). | When you need precise control over thinking token spend. |
| **Disabled** | Omit `thinking` parameter or pass `{type: "disabled"}` | All models except Claude Mythos Preview | When you don't need extended thinking and want the lowest latency. |
<Note>
Adaptive thinking is available on Claude Mythos Preview, Claude Opus 4.7, Opus 4.6, and Sonnet 4.6. On Mythos Preview, adaptive thinking is the default and applies automatically whenever `thinking` is unset. On Claude Opus 4.7, adaptive thinking is the only supported mode and `type: "enabled"` with `budget_tokens` is rejected. Older models only support `type: "enabled"` with `budget_tokens`. On Opus 4.6 and Sonnet 4.6, `type: "enabled"` with `budget_tokens` is still functional but deprecated.
**Interleaved thinking availability by mode:**
- **Adaptive mode:** Interleaved thinking is automatically enabled on Claude Mythos Preview, Claude Opus 4.7, Opus 4.6, and Sonnet 4.6. On Mythos Preview and Opus 4.7, inter-tool reasoning always lives inside thinking blocks.
- **Manual mode on Sonnet 4.6:** Interleaved thinking works via the `interleaved-thinking-2025-05-14` beta header.
- **Manual mode on Opus 4.6:** Interleaved thinking is not available. If your agentic workflow requires thinking between tool calls on Opus 4.6, use adaptive mode.
</Note>
## Important considerations
### Validation changes
When using adaptive thinking, previous assistant turns don't need to start with thinking blocks. This is more flexible than manual mode, where the API enforces that thinking-enabled turns begin with a thinking block.
### Prompt caching
Consecutive requests using `adaptive` thinking preserve [prompt cache](/docs/en/build-with-claude/prompt-caching) breakpoints. However, switching between `adaptive` and `enabled`/`disabled` thinking modes breaks cache breakpoints for messages. System prompts and tool definitions remain cached regardless of mode changes.
### Tuning thinking behavior
Adaptive thinking's triggering behavior is promptable. If Claude is thinking more or less often than you'd like, you can add guidance to your system prompt:
```text
Extended thinking adds latency and should only be used when it
will meaningfully improve answer quality — typically for problems
that require multi-step reasoning. When in doubt, respond directly.
```
<Warning>
Steering Claude to think less often may reduce quality on tasks that benefit from reasoning. Measure the impact on your specific workloads before deploying prompt-based tuning to production. Consider testing with lower [effort levels](/docs/en/build-with-claude/effort) first.
</Warning>
### Cost control
Use `max_tokens` as a hard limit on total output (thinking + response text). The `effort` parameter provides additional soft guidance on how much thinking Claude allocates. Together, these give you effective control over cost.
At `high` and `max` effort levels, Claude may think more extensively and can be more likely to exhaust the `max_tokens` budget. If you observe `stop_reason: "max_tokens"` in responses, consider increasing `max_tokens` to give the model more room, or lowering the effort level.
## Working with thinking blocks
The following concepts apply to all models that support extended thinking, regardless of whether you use adaptive or manual mode.
### Summarized thinking
With extended thinking enabled, the Messages API for Claude 4 models returns a summary of Claude's full thinking process. Summarized thinking provides the full intelligence benefits of extended thinking, while preventing misuse. This is the default behavior on Claude 4 models when the `display` field on the thinking configuration is unset or set to `"summarized"`. On Claude Opus 4.7 and [Claude Mythos Preview](https://anthropic.com/glasswing), `display` defaults to `"omitted"` instead, so you must set `display: "summarized"` explicitly to receive summarized thinking.
Here are some important considerations for summarized thinking:
- You're charged for the full thinking tokens generated by the original request, not the summary tokens.
- The billed output token count will **not match** the count of tokens you see in the response.
- On Claude 4 models, the first few lines of thinking output are more verbose, providing detailed reasoning that's particularly helpful for prompt engineering purposes. [Claude Mythos Preview](https://anthropic.com/glasswing) summarizes from the first token, so its thinking blocks do not show this verbose preamble.
- As Anthropic seeks to improve the extended thinking feature, summarization behavior is subject to change.
- Summarization preserves the key ideas of Claude's thinking process with minimal added latency, enabling a streamable user experience and easy migration from Claude Sonnet 3.7 to Claude 4 and later models.
- Summarization is processed by a different model than the one you target in your requests. The thinking model does not see the summarized output.
<Note>
Claude Sonnet 3.7 continues to return full thinking output.
In rare cases where you need access to full thinking output for Claude 4 models, [contact our sales team](mailto:sales@anthropic.com).
</Note>
### Controlling thinking display
The `display` field on the thinking configuration controls how thinking content is returned in API responses. It accepts two values:
- `"summarized"`: Thinking blocks contain summarized thinking text. See [Summarized thinking](#summarized-thinking) for details. This is the default on Claude Opus 4.6, Claude Sonnet 4.6, and earlier Claude 4 models.
- `"omitted"`: Thinking blocks are returned with an empty `thinking` field. The `signature` field still carries the encrypted full thinking for multi-turn continuity (see [Thinking encryption](#thinking-encryption)). This is the default on Claude Opus 4.7 and [Claude Mythos Preview](https://anthropic.com/glasswing).
Setting `display: "omitted"` is useful when your application doesn't surface thinking content to users. The primary benefit is **faster time-to-first-text-token when streaming:** The server skips streaming thinking tokens entirely and delivers only the signature, so the final text response begins streaming sooner.
<Note>
No SDK currently includes `display` in its type definitions. The Python SDK forwards unrecognized dict keys to the API at runtime; passing `display` in the thinking dict works transparently. The TypeScript SDK requires a type assertion. The C#, Go, Java, PHP, and Ruby SDKs require a direct HTTP request until native support lands.
</Note>
Here are some important considerations for omitted thinking:
- You're still charged for the full thinking tokens. Omitting reduces latency, not cost.
- If you pass thinking blocks back in multi-turn conversations, pass them unchanged. The server decrypts the `signature` to reconstruct the original thinking for prompt construction (see [Preserving thinking blocks](/docs/en/build-with-claude/extended-thinking#preserving-thinking-blocks)). Any text you place in the `thinking` field of a round-tripped omitted block is ignored.
- `display` is invalid with `thinking.type: "disabled"` (there is nothing to display).
- When using `thinking.type: "adaptive"` and the model skips thinking for a simple request, no thinking block is produced regardless of `display`.
<Note>
The `signature` field is identical whether `display` is `"summarized"` or `"omitted"`. Switching `display` values between turns in a conversation is supported.
</Note>
<Note>
On Claude Opus 4.7, `thinking.display` defaults to `"omitted"`. Thinking blocks still appear in the response stream, but their `thinking` field is empty unless you explicitly opt in. This is a silent change from Claude Opus 4.6, where the default was `"summarized"`. To restore summarized thinking text on Claude Opus 4.7, set `thinking.display` to `"summarized"` explicitly:
```python
thinking = {
"type": "adaptive",
"display": "summarized",
}
```
</Note>
For code examples and streaming behavior with `display: "omitted"`, see [Controlling thinking display](/docs/en/build-with-claude/extended-thinking#controlling-thinking-display) on the extended thinking page. The examples there use `type: "enabled"`; with adaptive thinking, use:
```python
thinking = {"type": "adaptive", "display": "omitted"}
```
### Thinking encryption
Full thinking content is encrypted and returned in the `signature` field. This field is used to verify that thinking blocks were generated by Claude when passed back to the API.
<Note>
It is only strictly necessary to send back thinking blocks when using [tools with extended thinking](/docs/en/build-with-claude/extended-thinking#extended-thinking-with-tool-use). Otherwise you can omit thinking blocks from previous turns, or let the API strip them for you if you pass them back.
If sending back thinking blocks, we recommend passing everything back as you received it for consistency and to avoid potential issues.
</Note>
Here are some important considerations on thinking encryption:
- When [streaming responses](/docs/en/build-with-claude/extended-thinking#streaming-thinking), the signature is added via a `signature_delta` inside a `content_block_delta` event just before the `content_block_stop` event.
- `signature` values are significantly longer in Claude 4 models than in previous models.
- The `signature` field is an opaque field and should not be interpreted or parsed.
- `signature` values are compatible across platforms (Claude APIs, [Amazon Bedrock](/docs/en/build-with-claude/claude-in-amazon-bedrock), and [Vertex AI](/docs/en/build-with-claude/claude-on-vertex-ai)). Values generated on one platform will be compatible with another.
### Pricing
For complete pricing information including base rates, cache writes, cache hits, and output tokens, see the [pricing page](/docs/en/about-claude/pricing).
The thinking process incurs charges for:
- Tokens used during thinking (output tokens)
- Thinking blocks from the last assistant turn included in subsequent requests (input tokens)
- Standard text output tokens
<Note>
When extended thinking is enabled, a specialized system prompt is automatically included to support this feature.
</Note>
When using summarized thinking:
- **Input tokens:** Tokens in your original request (excludes thinking tokens from previous turns)
- **Output tokens (billed):** The original thinking tokens that Claude generated internally
- **Output tokens (visible):** The summarized thinking tokens you see in the response
- **No charge:** Tokens used to generate the summary
When using `display: "omitted"`:
- **Input tokens:** Tokens in your original request (same as summarized)
- **Output tokens (billed):** The original thinking tokens that Claude generated internally (same as summarized)
- **Output tokens (visible):** Zero thinking tokens (the `thinking` field is empty)
<Warning>
The billed output token count will **not** match the visible token count in the response. You are billed for the full thinking process, not the thinking content visible in the response.
</Warning>
### Additional topics
The extended thinking page covers several topics in more detail with mode-specific code examples:
- **[Tool use with thinking](/docs/en/build-with-claude/extended-thinking#extended-thinking-with-tool-use)**: The same rules apply for adaptive thinking: preserve thinking blocks between tool calls and be aware of `tool_choice` limitations when thinking is active.
- **[Prompt caching](/docs/en/build-with-claude/extended-thinking#extended-thinking-with-prompt-caching)**: With adaptive thinking, consecutive requests using the same thinking mode preserve cache breakpoints. Switching between `adaptive` and `enabled`/`disabled` modes breaks cache breakpoints for messages (system prompts and tool definitions remain cached).
- **[Context windows](/docs/en/build-with-claude/extended-thinking#max-tokens-and-context-window-size-with-extended-thinking)**: How thinking tokens interact with `max_tokens` and context window limits.
## Next steps
<CardGroup>
<Card title="Extended thinking" icon="settings" href="/docs/en/build-with-claude/extended-thinking">
Learn more about extended thinking, including manual mode, tool use, and prompt caching.
</Card>
<Card title="Effort parameter" icon="gauge" href="/docs/en/build-with-claude/effort">
Control how thoroughly Claude responds with the effort parameter.
</Card>
</CardGroup>
---
## Guides/build-with-claude-administration-api-eb3a280106.md
# Admin API overview
---
<Tip>
**The Admin API is unavailable for individual accounts.** To collaborate with teammates and add members, set up your organization in **Console → Settings → Organization**.
</Tip>
The [Admin API](/docs/en/api/admin) allows you to programmatically manage your organization's resources, including organization members, workspaces, and API keys. This provides programmatic control over administrative tasks that would otherwise require manual configuration in the [Claude Console](/).
<Check>
**The Admin API requires special access**
The Admin API requires a special Admin API key (starting with `sk-ant-admin...`) that differs from standard API keys. Only organization members with the admin role can provision Admin API keys through the Claude Console.
</Check>
## How the Admin API works
When you use the Admin API:
1. You make requests using your Admin API key in the `x-api-key` header
2. The API allows you to manage:
- Organization members and their roles
- Organization member invites
- Workspaces and their members
- API keys
This is useful for:
- Automating user onboarding/offboarding
- Programmatically managing workspace access
- Monitoring and managing API key usage
## Organization roles and permissions
There are five organization-level roles. See more details in the [API Console roles and permissions](https://support.claude.com/en/articles/10186004-api-console-roles-and-permissions) article.
| Role | Permissions |
|------|-------------|
| user | Can use Workbench |
| claude_code_user | Can use Workbench and [Claude Code](../../02-Claude-Code-CLI/claude-code-overview-claude-code-docs-c23f3e7cbb.md) |
| developer | Can use Workbench and manage API keys |
| billing | Can use Workbench and manage billing details |
| admin | Can do all of the above, plus manage users |
## Key concepts
### Organization Members
You can list [organization members](/docs/en/api/admin-api/users/get-user), update member roles, and remove members.
<CodeGroup>
```bash cURL
# List organization members
curl "https://api.anthropic.com/v1/organizations/users?limit=10" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY"
# Update member role
curl "https://api.anthropic.com/v1/organizations/users/{user_id}" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
--data '{"role": "developer"}'
# Remove member
curl --request DELETE "https://api.anthropic.com/v1/organizations/users/{user_id}" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```
</CodeGroup>
### Organization Invites
You can invite users to organizations and manage those [invites](/docs/en/api/admin-api/invites/get-invite).
<CodeGroup>
```bash cURL
# Create invite
curl --request POST "https://api.anthropic.com/v1/organizations/invites" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
--data '{
"email": "newuser@domain.com",
"role": "developer"
}'
# List invites
curl "https://api.anthropic.com/v1/organizations/invites?limit=10" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY"
# Delete invite
curl --request DELETE "https://api.anthropic.com/v1/organizations/invites/{invite_id}" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```
</CodeGroup>
### Workspaces
For a comprehensive guide to workspaces, including Console and API examples, see [Workspaces](/docs/en/build-with-claude/workspaces).
### Workspace Members
Manage [user access to specific workspaces](/docs/en/api/admin-api/workspace_members/get-workspace-member):
<CodeGroup>
```bash cURL
# Add member to workspace
curl --request POST "https://api.anthropic.com/v1/organizations/workspaces/{workspace_id}/members" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
--data '{
"user_id": "user_xxx",
"workspace_role": "workspace_developer"
}'
# List workspace members
curl "https://api.anthropic.com/v1/organizations/workspaces/{workspace_id}/members?limit=10" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY"
# Update member role
curl --request POST "https://api.anthropic.com/v1/organizations/workspaces/{workspace_id}/members/{user_id}" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
--data '{
"workspace_role": "workspace_admin"
}'
# Remove member from workspace
curl --request DELETE "https://api.anthropic.com/v1/organizations/workspaces/{workspace_id}/members/{user_id}" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```
</CodeGroup>
### API Keys
Monitor and manage [API keys](/docs/en/api/admin-api/apikeys/get-api-key):
<CodeGroup>
```bash cURL
# List API keys
curl "https://api.anthropic.com/v1/organizations/api_keys?limit=10&status=active&workspace_id=wrkspc_xxx" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY"
# Update API key
curl --request POST "https://api.anthropic.com/v1/organizations/api_keys/{api_key_id}" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
--data '{
"status": "inactive",
"name": "New Key Name"
}'
```
</CodeGroup>
## Accessing organization info
Get information about your organization programmatically with the `/v1/organizations/me` endpoint.
For example:
```bash cURL
curl "https://api.anthropic.com/v1/organizations/me" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ADMIN_API_KEY"
```
```json
{
"id": "12345678-1234-5678-1234-567812345678",
"type": "organization",
"name": "Organization Name"
}
```
This endpoint is useful for programmatically determining which organization an Admin API key belongs to.
For complete parameter details and response schemas, see the [Organization Info API reference](/docs/en/api/admin-api/organization/get-me).
## Usage and cost reports
Track your organization's usage and costs with the [Usage and Cost API](/docs/en/build-with-claude/usage-cost-api).
## Claude Code analytics
Monitor developer productivity and Claude Code adoption with the [Claude Code Analytics API](/docs/en/build-with-claude/claude-code-analytics-api).
## Rate limits
Read the rate limits configured for your organization and its workspaces with the [Rate Limits API](/docs/en/build-with-claude/rate-limits-api).
## Best practices
To effectively use the Admin API:
- Use meaningful names and descriptions for workspaces and API keys
- Implement proper error handling for failed operations
- Regularly audit member roles and permissions
- Clean up unused workspaces and expired invites
- Monitor API key usage and rotate keys periodically
## FAQ
<section title="What permissions are needed to use the Admin API?">
Only organization members with the admin role can use the Admin API. They must also have a special Admin API key (starting with `sk-ant-admin`).
</section>
<section title="Can I create new API keys through the Admin API?">
No, new API keys can only be created through the Claude Console for security reasons. The Admin API can only manage existing API keys.
</section>
<section title="What happens to API keys when removing a user?">
API keys persist in their current state as they are scoped to the Organization, not to individual users.
</section>
<section title="Can organization admins be removed via the API?">
No, organization members with the admin role cannot be removed via the API for security reasons.
</section>
<section title="How long do organization invites last?">
Organization invites expire after 21 days. There is currently no way to modify this expiration period.
</section>
For workspace-specific questions, see the [Workspaces FAQ](/docs/en/build-with-claude/workspaces#faq).
---
## Guides/build-with-claude-api-and-data-retention-11a5180442.md
# API and data retention
Learn about how Anthropic's APIs and associated features retain data, including information about zero data retention (ZDR) and HIPAA-ready API access.
---
<Note>
Information about Anthropic's standard retention policies is set out in [Anthropic's commercial data retention policy](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data) and [consumer data retention policy](https://privacy.claude.com/en/articles/10023548-how-long-do-you-store-my-data).
Anthropic offers two data handling arrangements for the Claude API:
- **Zero data retention (ZDR):** Customer data is not stored at rest after the API response is returned, except where needed to comply with law or combat misuse.
- **HIPAA readiness:** For organizations handling protected health information (PHI), Anthropic offers HIPAA-ready API access with a signed Business Associate Agreement (BAA). See [HIPAA readiness](#hipaa-readiness).
</Note>
## Anthropic's approach to data retention
Different APIs and features have different storage and retention needs. Where an API or feature doesn't require storage of customer prompts or responses, it may be eligible for ZDR. Where an API or feature necessarily requires storage of customer prompts or responses, Anthropic designs for the smallest possible retention footprint. For these features:
- Retained data is never used for model training without your express permission.
- Only what is technically necessary for the API and feature to work is retained. Conversation content (your prompts and Claude's outputs) is never retained unless explicitly noted.
- Data is purged on the shortest practical TTL, and Anthropic aims to give customers control over how long data is retained. What is held, and the retention duration where a specific TTL applies, is documented on each feature's page.
In the [feature eligibility table](#feature-eligibility), some features are marked "Yes (qualified)" in the ZDR eligible column. If your organization has a ZDR arrangement, you can use these features with confidence that what Anthropic retains is narrow and is required for optimal performance.
## Zero data retention (ZDR) scope
**What ZDR covers**
- **Certain Claude APIs:** ZDR applies to the Claude Messages and Token Counting APIs
- **Claude Code:** ZDR applies when used with Commercial organization API keys or through Claude Enterprise (see [Claude Code ZDR docs](../../22-Safety-Policy/zero-data-retention-claude-code-docs-6ec9ee63f1.md))
**What ZDR does NOT cover**
- **Console and Workbench:** Any usage on Console or Workbench
- **Claude consumer products:** Claude Free, Pro, or Max plans, including when customers on those plans use Claude's web, desktop, or mobile apps or Claude Code
- **Claude Teams and Claude Enterprise:** Claude Teams and Claude Enterprise product interfaces are **not ZDR-eligible**, except for Claude Code when used through Claude Enterprise with ZDR enabled for the organization. For other product interfaces, only Commercial organization API keys are eligible for ZDR.
- **Third-party integrations:** Data processed by third-party websites, tools, or other integrations is **not ZDR-eligible**, though some may have similar offerings. When using external services in conjunction with the Claude API, make sure to review those services' data handling practices.
<Note>
For the most up-to-date information on what products and features are ZDR-eligible, refer to your contract terms or contact your Anthropic account representative.
</Note>
## HIPAA readiness
The Claude API supports HIPAA-ready integrations for organizations that handle protected health information (PHI). With a signed BAA and a HIPAA-enabled organization, you can use supported API features to process PHI while supporting your organization's HIPAA compliance.
Previously, organizations that required HIPAA readiness for the Claude API needed to enable ZDR. HIPAA-ready API access removes this requirement and provides a foundation for Anthropic to progressively enable additional features as they are audited for HIPAA readiness.
<Note>
This page covers HIPAA readiness for the Claude API. For the full HIPAA Implementation Guide covering Claude Enterprise, Claude Code, and configuration requirements, see the [Anthropic Trust Center](https://trust.anthropic.com/resources).
</Note>
### Getting started
To set up HIPAA-ready API access:
<Steps>
<Step title="Sign a Business Associate Agreement">
Contact the [Anthropic sales team](https://claude.com/contact-sales) to sign a BAA that covers API usage.
</Step>
<Step title="Provision a HIPAA-enabled organization">
Anthropic provisions a dedicated organization with HIPAA readiness controls enabled. This organization automatically enforces feature restrictions, blocking API requests that use non-eligible features.
</Step>
<Step title="Build with eligible features">
Use the [feature eligibility table](#feature-eligibility) to confirm which features are supported. Review the [PHI handling guidelines](#phi-handling-guidelines) for features that require specific restrictions on where PHI can appear. For detailed configuration and compliance requirements, refer to the [HIPAA Implementation Guide](https://trust.anthropic.com/resources).
</Step>
</Steps>
<Warning>
HIPAA readiness is enforced at the organization level. If you need both HIPAA-ready and general-purpose API access, use separate organizations for each.
</Warning>
### HIPAA readiness scope
**What HIPAA readiness covers**
- **Claude API:** HIPAA readiness applies to the Claude API (`api.anthropic.com`) for eligible features listed in the [feature eligibility table](#feature-eligibility).
**What HIPAA readiness does NOT cover**
- **Claude consumer products:** Claude Free, Pro, or Max plans
- **Console and Workbench:** Usage through the Claude Console interface
- **Third-party platforms:** Claude on AWS Bedrock or Google Cloud Vertex AI (refer to those platforms' compliance documentation)
- **Third-party integrations:** Data processed by external tools or services connected to your application
- **Claude Code:** Claude Code is not covered under HIPAA readiness
- **Beta features:** Features in beta are generally not covered under the BAA unless explicitly listed as eligible in the [feature eligibility table](#feature-eligibility)
### PHI handling guidelines
Protected health information (PHI) includes any individually identifiable health information. In the context of the Claude API, PHI typically appears in:
- Message content (prompts and responses from Claude)
- Attached files (images, PDFs)
- File names and metadata associated with message content
The following fields are not expected to contain PHI under the BAA: workspace names, user information (name, email, phone number), billing data, and support tickets.
#### Schema and tool definition restrictions
When using [structured outputs](/docs/en/build-with-claude/structured-outputs) or tools with `strict: true`, the API compiles JSON schemas into grammars that are cached separately from message content. These cached schemas do not receive the same PHI protections as prompts and responses.
**Do not include PHI in JSON schema definitions.** This restriction applies to:
- Schema property names
- `enum` values
- `const` values
- `pattern` regular expressions
Patient-specific information should only appear in message content, where it is protected under HIPAA safeguards.
### HIPAA error handling
Your signed BAA is the official source of truth for which features are covered. The API also enforces these restrictions automatically: when a HIPAA-enabled organization sends a request that includes a non-eligible feature, the API returns a `400` error to prevent accidental use of features not covered by your BAA:
```json
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "The requested features are not available for HIPAA-regulated organizations without Zero Data Retention: code_execution."
}
}
```
The error message lists the non-eligible features detected in the request. Remove these features from your request and retry.
## Feature eligibility
The following table lists which Claude API features are eligible for ZDR and HIPAA readiness arrangements. For HIPAA-enabled organizations, features marked "No" in the HIPAA column are automatically blocked, and requests that include them return a `400` error.
| Feature | Endpoint | ZDR eligible | HIPAA eligible | Details |
| ------- | -------- | ------------ | -------------- | ------- |
| [Messages API](/docs/en/build-with-claude/working-with-messages) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Standard API calls for generating Claude responses. |
| [Token counting](/docs/en/build-with-claude/token-counting) | `/v1/messages/count_tokens` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Count tokens before sending requests. |
| [Web search](/docs/en/agents-and-tools/tool-use/web-search-tool) | `/v1/messages` (with `web_search` tool) | <Eligible>Yes</Eligible><sup>1</sup> | <Eligible>Yes</Eligible><sup>1</sup> | Real-time web search results returned in the API response. |
| [Web fetch](/docs/en/agents-and-tools/tool-use/web-fetch-tool) | `/v1/messages` (with `web_fetch` tool) | <Eligible>Yes</Eligible><sup>1</sup> <sup>2</sup> | <Eligible status="no">No</Eligible> | Fetched web content returned in the API response. |
| [Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool) | `/v1/messages` (with `advisor` tool) | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Advisor model output is returned in the API response; nothing is stored server-side after the response. |
| [Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool) | `/v1/messages` (with `memory` tool) | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Client-side memory storage where you control data retention. |
| [Context management (compaction)](/docs/en/build-with-claude/compaction) | `/v1/messages` (with `context_management`) | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Server-side compaction results are returned/round-tripped statelessly through the API response. |
| [Context editing](/docs/en/build-with-claude/context-editing) | `/v1/messages` (with `context_management`) | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Context edits (tool use clearing + thinking clearing) are applied in real time. |
| [Fast mode](/docs/en/build-with-claude/fast-mode) | `/v1/messages` (with `speed: "fast"`) | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Same Messages API endpoint with faster inference. ZDR applies regardless of speed setting. |
| [1M token context window](/docs/en/build-with-claude/context-windows) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Extended context processing uses the standard Messages API. |
| [Adaptive thinking](/docs/en/build-with-claude/adaptive-thinking) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Dynamic thinking depth uses the standard Messages API. |
| [Citations](/docs/en/build-with-claude/citations) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Source attribution uses the standard Messages API. |
| [Data residency](/docs/en/build-with-claude/data-residency) | `/v1/messages` (with `inference_geo`) | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Geographic routing uses the standard Messages API. |
| [Effort](/docs/en/build-with-claude/effort) | `/v1/messages` (with `effort`) | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Token efficiency control uses the standard Messages API. |
| [Extended thinking](/docs/en/build-with-claude/extended-thinking) | `/v1/messages` (with `thinking`) | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Step-by-step reasoning uses the standard Messages API. |
| [PDF support](/docs/en/build-with-claude/pdf-support) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | PDF document processing uses the standard Messages API. HIPAA eligibility applies to PDFs sent inline via the Messages API, not through the Files API. |
| [Search results](/docs/en/build-with-claude/search-results) | `/v1/messages` (with `search_results` source) | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | RAG citation support uses the standard Messages API. |
| [Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool) | `/v1/messages` (with `bash` tool) | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Client-side tool executed in your environment. |
| [Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool) | `/v1/messages` (with `text_editor` tool) | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Client-side tool executed in your environment. |
| [Computer use](/docs/en/agents-and-tools/tool-use/computer-use-tool) | `/v1/messages` (with `computer` tool) | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Client-side tool where screenshots and files are captured and stored in your environment, not by Anthropic. See [Computer use](/docs/en/agents-and-tools/tool-use/computer-use-tool#data-retention). |
| [Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Streaming tool parameters uses the standard Messages API. |
| [Prompt caching](/docs/en/build-with-claude/prompt-caching) | `/v1/messages` | <Eligible>Yes</Eligible> | <Eligible>Yes</Eligible> | Your prompts and Claude's outputs are not stored. KV cache representations and cryptographic hashes are held in memory for the cache TTL and promptly deleted after expiry. See [Prompt caching](/docs/en/build-with-claude/prompt-caching#data-retention). |
| [Structured outputs](/docs/en/build-with-claude/structured-outputs) | `/v1/messages` | <Eligible status="qualified">Yes (qualified)</Eligible> | <Eligible>Yes</Eligible><sup>3</sup> | Your prompts and Claude's outputs are not stored. Only the JSON schema is cached, for up to 24 hours since last use. This also covers [strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use) (`strict: true` on tools), which uses the same grammar pipeline. See [Structured outputs](/docs/en/build-with-claude/structured-outputs#data-retention). |
| [Tool search](/docs/en/agents-and-tools/tool-use/tool-search-tool) | `/v1/messages` (with `tool_search` tool) | <Eligible>Yes</Eligible> | <Eligible status="no">No</Eligible> | Tool search uses the standard Messages API. |
| [Batch processing](/docs/en/build-with-claude/batch-processing) | `/v1/messages/batches` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | 29-day retention; async storage required. See [Batch processing](/docs/en/build-with-claude/batch-processing#data-retention). |
| [Code execution](/docs/en/agents-and-tools/tool-use/code-execution-tool) | `/v1/messages` (with `code_execution` tool) | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Container data retained up to 30 days. See [Code execution](/docs/en/agents-and-tools/tool-use/code-execution-tool#data-retention). |
| [Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) | `/v1/messages` (with `code_execution` tool) | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Built on code execution containers; data retained up to 30 days. See [Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling#data-retention). |
| [Files API](/docs/en/build-with-claude/files) | `/v1/files` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Files retained until explicitly deleted. See [Files API](/docs/en/build-with-claude/files#data-retention). |
| [Agent skills](/docs/en/agents-and-tools/agent-skills/overview) | `/v1/messages` (with `skills`) / `/v1/skills` | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Skill data retained per standard policy. See [Agent skills](/docs/en/agents-and-tools/agent-skills/overview#data-retention). |
| [MCP connector](/docs/en/agents-and-tools/mcp-connector) | `/v1/messages` (with `mcp_servers`) | <Eligible status="no">No</Eligible> | <Eligible status="no">No</Eligible> | Data retained per standard policy. See [MCP connector](/docs/en/agents-and-tools/mcp-connector#data-retention). |
<sup>1</sup> [Dynamic filtering](/docs/en/agents-and-tools/tool-use/web-search-tool#dynamic-filtering) is not eligible for ZDR or HIPAA.
<sup>2</sup> While web fetch is ZDR-eligible, website publishers may retain request data (such as fetched URLs and request metadata) according to their own policies.
<sup>3</sup> PHI must not be included in JSON schema definitions. See [PHI handling guidelines](#phi-handling-guidelines).
## Limitations and exclusions
### CORS not supported for ZDR
**Cross-Origin Resource Sharing (CORS)** is not supported for organizations with ZDR arrangements. If you need to make API calls from browser-based applications, you must:
- Use a backend proxy server to make API calls on behalf of your front end
- Implement your own CORS handling on the proxy server
- Never expose API keys directly in browser JavaScript
### Data retention for policy violations and where required by law
Even with ZDR or HIPAA arrangements in place, Anthropic may retain data where required by law or to combat Usage Policy violations and malicious uses of Anthropic's platform. As a result, if a chat or session is flagged for such a violation, Anthropic may retain inputs and outputs for up to 2 years.
## Frequently asked questions
<section title="How do I know if my organization has ZDR arrangements?">
Check your contract terms or contact your Anthropic account representative to confirm if your organization has ZDR arrangements in place.
</section>
<section title="Can I use ZDR-eligible (qualified) features under my ZDR arrangement?">
Yes. These features retain a minimal, documented set of technical data, not your prompts or Claude's outputs. See [Anthropic's approach to data retention](#anthropics-approach-to-data-retention) for the commitments that govern these features.
</section>
<Accordion title={'What happens if I use a feature marked "No" under ZDR?'}>
Features marked "No" for ZDR are fundamentally stateful: the Batch API stores your jobs, the Files API stores your files, and code execution runs in persistent containers. Data for these features is retained per the feature's documented policy. Using them is a choice to step outside your ZDR arrangement for that specific data.
</Accordion>
<section title="Can I request deletion of data from features that are not ZDR-eligible?">
Contact your Anthropic account representative to discuss deletion options for non-ZDR features.
</section>
<section title="How does HIPAA readiness differ from ZDR?">
ZDR prevents customer data from being stored at rest after the API response is returned. HIPAA readiness involves a broader set of privacy and security safeguards that protect PHI throughout its lifecycle, including encryption, access controls, and audit logging. HIPAA-ready API access provides a foundation for progressively enabling more features because data can be retained with proper safeguards rather than requiring immediate deletion.
</section>
<section title="Do I still need ZDR if I have HIPAA readiness?">
No. HIPAA-ready API access is designed as an alternative to ZDR for organizations handling PHI. With HIPAA readiness enabled, you get access to supported API features while maintaining the privacy and security protections that HIPAA requires.
</section>
<section title="What happens if I use a non-eligible feature under HIPAA?">
The API returns a `400` error with an `invalid_request_error` type. The error message identifies which features are not available. Remove the non-eligible features from your request and retry.
</section>
<section title="Can I use the same organization for HIPAA and non-HIPAA workloads?">
No. HIPAA readiness is enforced at the organization level and automatically blocks all non-eligible features. Use a separate organization for workloads that do not require HIPAA readiness.
</section>
<section title="How do I request HIPAA-ready API access?">
Contact the [Anthropic sales team](https://claude.com/contact-sales) to discuss HIPAA-ready API access and sign a Business Associate Agreement.
</section>
<section title="Does this apply to Claude on AWS Bedrock or Vertex AI?">
No, only the Claude API is eligible for ZDR and HIPAA readiness. For Claude deployments on AWS Bedrock or Vertex AI, refer to those platforms' data retention and compliance policies.
</section>
<section title="Is Claude Code eligible for ZDR?">
Claude Code is eligible for ZDR through two paths:
- **API keys:** Claude Code used with pay-as-you-go API keys from a Commercial organization
- **Claude Enterprise:** Claude Code used through Claude Enterprise with ZDR enabled for the organization
ZDR is enabled on a per-organization basis. Each new organization requires ZDR to be enabled separately by your account team. ZDR does not automatically apply to new organizations created under the same account.
Additionally, if you have metrics logging enabled in Claude Code, productivity data (such as usage statistics) is exempted from ZDR and may be retained.
For full details on ZDR for Claude Code on Claude Enterprise, including disabled features and how to request enablement, see the [Claude Code ZDR documentation](../../22-Safety-Policy/zero-data-retention-claude-code-docs-6ec9ee63f1.md).
</section>
<section title="Does Claude for Excel support ZDR?">
No, Claude for Excel is not currently ZDR-eligible.
</section>
<section title="How do I request ZDR?">
To request a ZDR arrangement, contact the [Anthropic sales team](https://claude.com/contact-sales).
</section>
## Related resources
- [Privacy Policy](https://www.anthropic.com/legal/privacy)
- [Structured outputs](/docs/en/build-with-claude/structured-outputs)
- [Prompt caching](/docs/en/build-with-claude/prompt-caching)
- [Batch processing](/docs/en/build-with-claude/batch-processing)
- [Files API](/docs/en/api/files-create)
- [Trust Center](https://trust.anthropic.com/resources)
---
## Guides/build-with-claude-batch-processing-58f98b4064.md
# Batch processing
---
Batch processing is a powerful approach for handling large volumes of requests efficiently. Instead of processing requests one at a time with immediate responses, batch processing allows you to submit multiple requests together for asynchronous processing. This pattern is particularly useful when:
- You need to process large volumes of data
- Immediate responses are not required
- You want to optimize for cost efficiency
- You're running large-scale evaluations or analyses
The Message Batches API is Anthropic's first implementation of this pattern.
<Note>
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.
</Note>
---
# Message Batches API
The Message Batches API is a powerful, cost-effective way to asynchronously process large volumes of [Messages](/docs/en/api/messages/create) requests. This approach is well-suited to tasks that do not require immediate responses, with most batches finishing in less than 1 hour while reducing costs by 50% and increasing throughput.
You can [explore the API reference directly](/docs/en/api/creating-message-batches), in addition to this guide.
## How the Message Batches API works
When you send a request to the Message Batches API:
1. The system creates a new Message Batch with the provided Messages requests.
2. The batch is then processed asynchronously, with each request handled independently.
3. You can poll for the status of the batch and retrieve results when processing has ended for all requests.
This is especially useful for bulk operations that don't require immediate results, such as:
- Large-scale evaluations: Process thousands of test cases efficiently.
- Content moderation: Analyze large volumes of user-generated content asynchronously.
- Data analysis: Generate insights or summaries for large datasets.
- Bulk content generation: Create large amounts of text for various purposes (e.g., product descriptions, article summaries).
### Batch limitations
- A Message Batch is limited to either 100,000 Message requests or 256 MB in size, whichever is reached first.
- The system processes each batch as fast as possible, with most batches completing within 1 hour. You can access batch results when all messages have completed or after 24 hours, whichever comes first. Batches expire if processing does not complete within 24 hours.
- Batch results are available for 29 days after creation. After that, you may still view the Batch, but its results will no longer be available for download.
- Batches are scoped to a [Workspace](/settings/workspaces). You may view all batches (and their results) that were created within the Workspace that your API key belongs to.
- Rate limits apply to both Batches API HTTP requests and the number of requests within a batch waiting to be processed. See [Message Batches API rate limits](/docs/en/api/rate-limits#message-batches-api). Additionally, processing may be slowed down based on current demand and your request volume. In that case, you may see more requests expiring after 24 hours.
- Due to high throughput and concurrent processing, batches may go slightly over your Workspace's configured [spend limit](/settings/limits).
### Supported models
All [active models](/docs/en/about-claude/models/overview) support the Message Batches API.
### What can be batched
Any request that you can make to the Messages API can be included in a batch. This includes:
- Vision
- Tool use
- System messages
- Multi-turn conversations
- Any beta features
Since each request in the batch is processed independently, you can mix different types of requests within a single batch.
<Tip>
Since batches can take longer than 5 minutes to process, consider using the [1-hour cache duration](/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration) with prompt caching for better cache hit rates when processing batches with shared context.
</Tip>
---
## Pricing
The Batches API offers significant cost savings. All usage is charged at 50% of the standard API prices.
| Model | Batch input | Batch output |
|-------------------|------------------|-----------------|
| Claude Opus 4.7 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.6 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.5 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.1 | $7.50 / MTok | $37.50 / MTok |
| Claude Opus 4 | $7.50 / MTok | $37.50 / MTok |
| Claude Sonnet 4.6 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4.5 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 3.7 ([deprecated](/docs/en/about-claude/model-deprecations)) | $1.50 / MTok | $7.50 / MTok |
| Claude Haiku 4.5 | $0.50 / MTok | $2.50 / MTok |
| Claude Haiku 3.5 | $0.40 / MTok | $2 / MTok |
| Claude Opus 3 ([deprecated](/docs/en/about-claude/model-deprecations)) | $7.50 / MTok | $37.50 / MTok |
| Claude Haiku 3 | $0.125 / MTok | $0.625 / MTok |
---
## How to use the Message Batches API
### Prepare and create your batch
A Message Batch is composed of a list of requests to create a Message. The shape of an individual request is comprised of:
- A unique `custom_id` for identifying the Messages request. Must be 1 to 64 characters and contain only alphanumeric characters, hyphens, and underscores (matching `^[a-zA-Z0-9_-]{1,64}$`).
- A `params` object with the standard [Messages API](/docs/en/api/messages/create) parameters
You can [create a batch](/docs/en/api/creating-message-batches) by passing this list into the `requests` parameter:
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages/batches \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data \
'{
"requests": [
{
"custom_id": "my-first-request",
"params": {
"model": "claude-opus-4-7",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, world"}
]
}
},
{
"custom_id": "my-second-request",
"params": {
"model": "claude-opus-4-7",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hi again, friend"}
]
}
}
]
}'
```
```bash CLI
ant messages:batches create <<'YAML'
requests:
- custom_id: my-first-request
params:
model: claude-opus-4-7
max_tokens: 1024
messages:
- role: user
content: Hello, world
- custom_id: my-second-request
params:
model: claude-opus-4-7
max_tokens: 1024
messages:
- role: user
content: Hi again, friend
YAML
```
```python Python hidelines={1}
import anthropic
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request
client = anthropic.Anthropic()
message_batch = client.messages.batches.create(
requests=[
Request(
custom_id="my-first-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-4-7",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hello, world",
}
],
),
),
Request(
custom_id="my-second-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-4-7",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hi again, friend",
}
],
),
),
]
)
print(message_batch)
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
const messageBatch = await anthropic.messages.batches.create({
requests: [
{
custom_id: "my-first-request",
params: {
model: "claude-opus-4-7",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, world" }]
}
},
{
custom_id: "my-second-request",
params: {
model: "claude-opus-4-7",
max_tokens: 1024,
messages: [{ role: "user", content: "Hi again, friend" }]
}
}
]
});
console.log(messageBatch);
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
using Anthropic.Models.Messages.Batches;
AnthropicClient client = new();
var batch = await client.Messages.Batches.Create(new BatchCreateParams
{
Requests =
[
new()
{
CustomID = "my-first-request",
Params = new()
{
Model = Model.ClaudeOpus4_7,
MaxTokens = 1024,
Messages =
[
new() { Role = Role.User, Content = "Hello, world" }
]
}
},
new()
{
CustomID = "my-second-request",
Params = new()
{
Model = Model.ClaudeOpus4_7,
MaxTokens = 1024,
Messages =
[
new() { Role = Role.User, Content = "Hi again, friend" }
]
}
}
]
});
Console.WriteLine(batch);
```
```go Go hidelines={1..10,-1}
package main
import (
"context"
"fmt"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
batch, _ := client.Messages.Batches.New(context.Background(),
anthropic.MessageBatchNewParams{
Requests: []anthropic.MessageBatchNewParamsRequest{
{
CustomID: "my-first-request",
Params: anthropic.MessageBatchNewParamsRequestParams{
Model: anthropic.ModelClaudeOpus4_7,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(
anthropic.NewTextBlock("Hello, world"),
),
},
},
},
{
CustomID: "my-second-request",
Params: anthropic.MessageBatchNewParamsRequestParams{
Model: anthropic.ModelClaudeOpus4_7,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(
anthropic.NewTextBlock("Hi again, friend"),
),
},
},
},
},
})
fmt.Println(batch.ID)
}
```
```java Java hidelines={1..3,5..8,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.batches.*;
public class BatchExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
BatchCreateParams params = BatchCreateParams.builder()
.addRequest(
BatchCreateParams.Request.builder()
.customId("my-first-request")
.params(
BatchCreateParams.Request.Params.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(1024)
.addUserMessage("Hello, world")
.build()
)
.build()
)
.addRequest(
BatchCreateParams.Request.builder()
.customId("my-second-request")
.params(
BatchCreateParams.Request.Params.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(1024)
.addUserMessage("Hi again, friend")
.build()
)
.build()
)
.build();
MessageBatch messageBatch = client.messages().batches().create(params);
System.out.println(messageBatch);
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(
apiKey: getenv("ANTHROPIC_API_KEY")
);
$batch = $client->messages->batches->create(
requests: [
[
'custom_id' => 'my-first-request',
'params' => [
'model' => 'claude-opus-4-7',
'max_tokens' => 1024,
'messages' => [
['role' => 'user', 'content' => 'Hello, world']
]
]
],
[
'custom_id' => 'my-second-request',
'params' => [
'model' => 'claude-opus-4-7',
'max_tokens' => 1024,
'messages' => [
['role' => 'user', 'content' => 'Hi again, friend']
]
]
]
],
);
print_r($batch);
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
batch = client.messages.batches.create(
requests: [
{
custom_id: "my-first-request",
params: {
model: "claude-opus-4-7",
max_tokens: 1024,
messages: [
{ role: "user", content: "Hello, world" }
]
}
},
{
custom_id: "my-second-request",
params: {
model: "claude-opus-4-7",
max_tokens: 1024,
messages: [
{ role: "user", content: "Hi again, friend" }
]
}
}
]
)
puts batch
```
</CodeGroup>
In this example, two separate requests are batched together for asynchronous processing. Each request has a unique `custom_id` and contains the standard parameters you'd use for a Messages API call.
<Tip>
**Test your batch requests with the Messages API**
Validation of the `params` object for each message request is performed asynchronously, and validation errors are returned when processing of the entire batch has ended. You can ensure that you are building your input correctly by verifying your request shape with the [Messages API](/docs/en/api/messages/create) first.
</Tip>
When a batch is first created, the response will have a processing status of `in_progress`.
```json Output
{
"id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
"type": "message_batch",
"processing_status": "in_progress",
"request_counts": {
"processing": 2,
"succeeded": 0,
"errored": 0,
"canceled": 0,
"expired": 0
},
"ended_at": null,
"created_at": "2024-09-24T18:37:24.100435Z",
"expires_at": "2024-09-25T18:37:24.100435Z",
"cancel_initiated_at": null,
"results_url": null
}
```
### Tracking your batch
The Message Batch's `processing_status` field indicates the stage of processing the batch is in. It starts as `in_progress`, then updates to `ended` once all the requests in the batch have finished processing, and results are ready. You can monitor the state of your batch by visiting the [Console](/settings/workspaces/default/batches), or using the [retrieval endpoint](/docs/en/api/retrieving-message-batches).
#### Polling for Message Batch completion
To poll a Message Batch, you'll need its `id`, which is provided in the response when creating a batch or by listing batches. You can implement a polling loop that checks the batch status periodically until processing has ended:
<CodeGroup>
```bash cURL hidelines={2..16,23}
#!/bin/sh
MESSAGE_BATCH_ID=$(curl -s https://api.anthropic.com/v1/messages/batches \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"requests": [{
"custom_id": "test-1",
"params": {
"model": "claude-opus-4-7",
"max_tokens": 100,
"messages": [{"role": "user", "content": "Hi"}]
}
}]
}' | jq -r '.id')
until [[ $(curl -s "https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID" \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
| grep -o '"processing_status":[[:space:]]*"[^"]*"' \
| cut -d'"' -f4) == "ended" ]]; do
echo "Batch $MESSAGE_BATCH_ID is still processing..."
break
sleep 60
done
echo "Batch $MESSAGE_BATCH_ID has finished processing"
```
```bash CLI hidelines={2..14,19}
#!/bin/bash
MESSAGE_BATCH_ID=$(ant messages:batches create \
--transform id --format yaml <<'YAML'
requests:
- custom_id: test-1
params:
model: claude-opus-4-7
max_tokens: 100
messages:
- role: user
content: Hi
YAML
)
until [[ $(ant messages:batches retrieve \
--message-batch-id "$MESSAGE_BATCH_ID" \
--transform processing_status --format yaml) == "ended" ]]; do
echo "Batch $MESSAGE_BATCH_ID is still processing..."
break
sleep 60
done
echo "Batch $MESSAGE_BATCH_ID has finished processing"
```
```python Python nocheck hidelines={1}
import anthropic
import time
client = anthropic.Anthropic()
MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
message_batch = None
while True:
message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
if message_batch.processing_status == "ended":
break
print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
time.sleep(60)
print(message_batch)
```
```typescript TypeScript nocheck hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
const messageBatchId = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d";
let messageBatch;
while (true) {
messageBatch = await anthropic.messages.batches.retrieve(messageBatchId);
if (messageBatch.processing_status === "ended") {
break;
}
console.log(`Batch ${messageBatchId} is still processing... waiting`);
await new Promise((resolve) => setTimeout(resolve, 60_000));
}
console.log(messageBatch);
```
```csharp C# nocheck
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages.Batches;
class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new();
string messageBatchId = Environment.GetEnvironmentVariable("MESSAGE_BATCH_ID");
MessageBatch messageBatch = null;
while (true)
{
messageBatch = await client.Messages.Batches.Retrieve(messageBatchId);
if (messageBatch.ProcessingStatus == "ended")
{
break;
}
Console.WriteLine($"Batch {messageBatchId} is still processing...");
await Task.Delay(60000);
}
Console.WriteLine(messageBatch);
}
}
```
```go Go nocheck hidelines={1..14,-1}
package main
import (
"context"
"fmt"
"log"
"os"
"time"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
messageBatchID := os.Getenv("MESSAGE_BATCH_ID")
var messageBatch *anthropic.MessageBatch
for {
var err error
messageBatch, err = client.Messages.Batches.Get(context.TODO(), messageBatchID)
if err != nil {
log.Fatal(err)
}
if messageBatch.ProcessingStatus == "ended" {
break
}
fmt.Printf("Batch %s is still processing...\n", messageBatchID)
time.Sleep(60 * time.Second)
}
fmt.Println(messageBatch)
}
```
```java Java nocheck hidelines={1..2,4..6,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.batches.MessageBatch;
public class MessageBatchPolling {
public static void main(String[] args) throws InterruptedException {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
String messageBatchId = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d";
MessageBatch messageBatch = null;
while (true) {
messageBatch = client.messages().batches().retrieve(messageBatchId);
if (messageBatch.processingStatus().equals(MessageBatch.ProcessingStatus.ENDED)) {
break;
}
System.out.println("Batch " + messageBatchId + " is still processing...");
Thread.sleep(60000);
}
System.out.println(messageBatch);
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$messageBatchId = getenv("MESSAGE_BATCH_ID");
$messageBatch = null;
while (true) {
$messageBatch = $client->messages->batches->retrieve(
messageBatchID: $messageBatchId,
);
if ($messageBatch->processingStatus === "ended") {
break;
}
echo "Batch {$messageBatchId} is still processing...\n";
sleep(60);
}
echo json_encode($messageBatch, JSON_PRETTY_PRINT);
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
message_batch_id = ENV["MESSAGE_BATCH_ID"]
message_batch = nil
loop do
message_batch = client.messages.batches.retrieve(message_batch_id)
break if message_batch.processing_status == :ended
puts "Batch #{message_batch_id} is still processing..."
sleep 60
end
puts message_batch
```
</CodeGroup>
### Listing all Message Batches
You can list all Message Batches in your Workspace using the [list endpoint](/docs/en/api/listing-message-batches). The API supports pagination, automatically fetching additional pages as needed:
<CodeGroup>
```bash cURL
#!/bin/sh
if ! command -v jq &> /dev/null; then
echo "Error: This script requires jq. Please install it first."
exit 1
fi
BASE_URL="https://api.anthropic.com/v1/messages/batches"
has_more=true
after_id=""
while [ "$has_more" = true ]; do
# Construct URL with after_id if it exists
if [ -n "$after_id" ]; then
url="${BASE_URL}?limit=20&after_id=${after_id}"
else
url="$BASE_URL?limit=20"
fi
response=$(curl -s "$url" \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01")
# Extract values using jq
has_more=$(echo "$response" | jq -r '.has_more')
after_id=$(echo "$response" | jq -r '.last_id')
# Process and print each entry in the data array
echo "$response" | jq -c '.data[]' | while read -r entry; do
echo "$entry" | jq '.'
done
done
```
```bash CLI
# Automatically fetches more pages as needed
ant messages:batches list --limit 20
```
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
# Automatically fetches more pages as needed.
for message_batch in client.messages.batches.list(limit=20):
print(message_batch)
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
// Automatically fetches more pages as needed.
for await (const messageBatch of anthropic.messages.batches.list({
limit: 20
})) {
console.log(messageBatch);
}
```
```csharp C# hidelines={1..11,-2..}
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages.Batches;
class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new();
var parameters = new BatchListParams
{
Limit = 20
};
// Automatically fetches more pages as needed
var page = await client.Messages.Batches.List(parameters);
await foreach (var messageBatch in page.Paginate())
{
Console.WriteLine(messageBatch);
}
}
}
```
```go Go hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
// Automatically fetches more pages as needed
iter := client.Messages.Batches.ListAutoPaging(context.TODO(), anthropic.MessageBatchListParams{
Limit: anthropic.Int(20),
})
for iter.Next() {
messageBatch := iter.Current()
fmt.Println(messageBatch)
}
if err := iter.Err(); err != nil {
log.Fatal(err)
}
}
```
```java Java hidelines={1..2,4..7,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.batches.*;
public class BatchListExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Automatically fetches more pages as needed
for (MessageBatch messageBatch : client
.messages()
.batches()
.list(BatchListParams.builder().limit(20).build())
.autoPager()) {
System.out.println(messageBatch);
}
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
// Automatically fetches more pages as needed
foreach ($client->messages->batches->list(limit: 20)->pagingEachItem() as $messageBatch) {
echo $messageBatch->id . "\n";
}
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
# Automatically fetches more pages as needed
client.messages.batches.list(limit: 20).auto_paging_each do |message_batch|
puts message_batch
end
```
</CodeGroup>
### Retrieving batch results
Once batch processing has ended, each Messages request in the batch has a result. There are 4 result types:
| Result Type | Description |
|-------------|-------------|
| `succeeded` | Request was successful. Includes the message result. |
| `errored` | Request encountered an error and a message was not created. Possible errors include invalid requests and internal server errors. You will not be billed for these requests. |
| `canceled` | User canceled the batch before this request could be sent to the model. You will not be billed for these requests. |
| `expired` | Batch reached its 24 hour expiration before this request could be sent to the model. You will not be billed for these requests. |
You will see an overview of your results with the batch's `request_counts`, which shows how many requests reached each of these four states.
Results of the batch are available for download at the `results_url` property on the Message Batch, and if the organization permission allows, in the Console. Because of the potentially large size of the results, it's recommended to [stream results](/docs/en/api/retrieving-message-batch-results) back rather than download them all at once.
<CodeGroup>
```bash cURL
#!/bin/sh
curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_API_KEY" \
| grep -o '"results_url":[[:space:]]*"[^"]*"' \
| cut -d'"' -f4 \
| while read -r url; do
curl -s "$url" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_API_KEY" \
| sed 's/}{/}\n{/g' \
| while IFS= read -r line
do
result_type=$(echo "$line" | sed -n 's/.*"result":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
custom_id=$(echo "$line" | sed -n 's/.*"custom_id":[[:space:]]*"\([^"]*\)".*/\1/p')
error_type=$(echo "$line" | sed -n 's/.*"error":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
case "$result_type" in
"succeeded")
echo "Success! $custom_id"
;;
"errored")
if [ "$error_type" = "invalid_request_error" ]; then
# Request body must be fixed before re-sending request
echo "Validation error: $custom_id"
else
# Request can be retried directly
echo "Server error: $custom_id"
fi
;;
"expired")
echo "Expired: $line"
;;
esac
done
done
```
```bash CLI nocheck
ant messages:batches results \
--message-batch-id msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
--transform '{custom_id,"type":result.type,"error":result.error.error.type}' \
--format jsonl \
| while IFS= read -r line; do
custom_id=${line#*'"custom_id":"'}; custom_id=${custom_id%%'"'*}
case "$line" in
*'"type":"succeeded"'*)
printf 'Success! %s\n' "$custom_id" ;;
*'"type":"errored"'*)
case "$line" in
*'"error":"invalid_request_error"'*)
printf 'Validation error %s\n' "$custom_id" ;;
*)
printf 'Server error %s\n' "$custom_id" ;;
esac ;;
*'"type":"expired"'*)
printf 'Request expired %s\n' "$custom_id" ;;
esac
done
```
```python Python nocheck hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
# Stream results file in memory-efficient chunks, processing one at a time
for result in client.messages.batches.results(
"msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
match result.result.type:
case "succeeded":
print(f"Success! {result.custom_id}")
case "errored":
if result.result.error.error.type == "invalid_request_error":
# Request body must be fixed before re-sending request
print(f"Validation error {result.custom_id}")
else:
# Request can be retried directly
print(f"Server error {result.custom_id}")
case "expired":
print(f"Request expired {result.custom_id}")
```
```typescript TypeScript nocheck hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
// Stream results file in memory-efficient chunks, processing one at a time
for await (const result of await anthropic.messages.batches.results(
"msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
)) {
switch (result.result.type) {
case "succeeded":
console.log(`Success! ${result.custom_id}`);
break;
case "errored":
if (result.result.error.type === "invalid_request_error") {
// Request body must be fixed before re-sending request
console.log(`Validation error: ${result.custom_id}`);
} else {
// Request can be retried directly
console.log(`Server error: ${result.custom_id}`);
}
break;
case "expired":
console.log(`Request expired: ${result.custom_id}`);
break;
}
}
```
```csharp C# nocheck
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages.Batches;
public class Program
{
public static async Task Main(string[] args)
{
AnthropicClient client = new();
await foreach (var result in client.Messages.Batches.ResultsStreaming("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"))
{
switch (result.Result.Type)
{
case "succeeded":
Console.WriteLine($"Success! {result.CustomID}");
break;
case "errored":
if (result.Result.Error?.Type == "invalid_request")
{
Console.WriteLine($"Validation error: {result.CustomID}");
}
else
{
Console.WriteLine($"Server error: {result.CustomID}");
}
break;
case "expired":
Console.WriteLine($"Request expired: {result.CustomID}");
break;
}
}
}
}
```
```go Go nocheck hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
stream := client.Messages.Batches.ResultsStreaming(context.TODO(), "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d")
for stream.Next() {
result := stream.Current()
switch variant := result.Result.AsAny().(type) {
case anthropic.MessageBatchSucceededResult:
fmt.Printf("Success! %s\n", result.CustomID)
case anthropic.MessageBatchErroredResult:
fmt.Printf("Error: %s - %s\n", result.CustomID, variant.Error.Error.Message)
case anthropic.MessageBatchExpiredResult:
fmt.Printf("Request expired: %s\n", result.CustomID)
}
}
if err := stream.Err(); err != nil {
log.Fatal(err)
}
}
```
```java Java nocheck hidelines={1..2,6..9,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.http.StreamResponse;
import com.anthropic.models.messages.batches.BatchResultsParams;
import com.anthropic.models.messages.batches.MessageBatchIndividualResponse;
public class BatchResultsExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Stream results file in memory-efficient chunks, processing one at a time
try (
StreamResponse<MessageBatchIndividualResponse> streamResponse = client
.messages()
.batches()
.resultsStreaming(
BatchResultsParams.builder()
.messageBatchId("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d")
.build()
)
) {
streamResponse
.stream()
.forEach(result -> {
if (result.result().isSucceeded()) {
System.out.println("Success! " + result.customId());
} else if (result.result().isErrored()) {
if (result.result().asErrored().error().error().isInvalidRequestError()) {
// Request body must be fixed before re-sending request
System.out.println("Validation error: " + result.customId());
} else {
// Request can be retried directly
System.out.println("Server error: " + result.customId());
}
} else if (result.result().isExpired()) {
System.out.println("Request expired: " + result.customId());
}
});
}
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
foreach ($client->messages->batches->resultsStream(messageBatchID: 'msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d') as $result) {
switch ($result->result->type) {
case "succeeded":
echo "Success! {$result->customID}\n";
break;
case "errored":
if ($result->result->error->error->type === "invalid_request_error") {
echo "Validation error: {$result->customID}\n";
} else {
echo "Server error: {$result->customID}\n";
}
break;
case "expired":
echo "Request expired: {$result->customID}\n";
break;
}
}
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
client.messages.batches.results_streaming("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d").each do |result|
case result.result.type
when :succeeded
puts "Success! #{result.custom_id}"
when :errored
if result.result.error.type == :invalid_request
puts "Validation error: #{result.custom_id}"
else
puts "Server error: #{result.custom_id}"
end
when :expired
puts "Request expired: #{result.custom_id}"
end
end
```
</CodeGroup>
The results are in `.jsonl` format, where each line is a valid JSON object representing the result of a single request in the Message Batch. For each streamed result, you can do something different depending on its `custom_id` and result type. Here is an example set of results:
```jsonl .jsonl file
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-7","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-opus-4-7","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}
```
If your result has an error, its `result.error` will be set to the standard [error shape](/docs/en/api/errors#error-shapes).
<Tip>
**Batch results may not match input order**
Batch results can be returned in any order, and may not match the ordering of requests when the batch was created. In the above example, the result for the second batch request is returned before the first. To correctly match results with their corresponding requests, always use the `custom_id` field.
</Tip>
### Canceling a Message Batch
You can cancel a Message Batch that is currently processing using the [cancel endpoint](/docs/en/api/canceling-message-batches). Immediately after cancellation, a batch's `processing_status` will be `canceling`. You can use the same polling technique described above to wait until cancellation is finalized. Canceled batches end up with a status of `ended` and may contain partial results for requests that were processed before cancellation.
<CodeGroup>
```bash cURL hidelines={2..15}
#!/bin/sh
MESSAGE_BATCH_ID=$(curl -s https://api.anthropic.com/v1/messages/batches \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"requests": [{
"custom_id": "test-1",
"params": {
"model": "claude-opus-4-7",
"max_tokens": 100,
"messages": [{"role": "user", "content": "Hi"}]
}
}]
}' | jq -r '.id')
curl --request POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01"
```
```bash CLI hidelines={2..13}
#!/bin/bash
MESSAGE_BATCH_ID=$(ant messages:batches create \
--transform id --format yaml <<'YAML'
requests:
- custom_id: test-1
params:
model: claude-opus-4-7
max_tokens: 100
messages:
- role: user
content: Hi
YAML
)
ant messages:batches cancel --message-batch-id "$MESSAGE_BATCH_ID"
```
```python Python nocheck hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
message_batch = client.messages.batches.cancel(
MESSAGE_BATCH_ID,
)
print(message_batch)
```
```typescript TypeScript nocheck hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
const messageBatch = await anthropic.messages.batches.cancel(MESSAGE_BATCH_ID);
console.log(messageBatch);
```
```csharp C# nocheck
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages.Batches;
class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new();
var messageBatch = await client.Messages.Batches.Cancel(MESSAGE_BATCH_ID);
Console.WriteLine(messageBatch);
}
}
```
```go Go nocheck hidelines={1..12,-1}
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
messageBatchID := os.Getenv("MESSAGE_BATCH_ID")
messageBatch, err := client.Messages.Batches.Cancel(context.TODO(), messageBatchID)
if err != nil {
log.Fatal(err)
}
fmt.Println(messageBatch)
}
```
```java Java nocheck hidelines={1..2,4..7,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.batches.*;
public class BatchCancelExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageBatch messageBatch = client
.messages()
.batches()
.cancel("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d");
System.out.println(messageBatch);
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$messageBatch = $client->messages->batches->cancel(
messageBatchID: 'msgbatch_example_id',
);
echo $messageBatch;
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
message_batch_id = ENV.fetch("MESSAGE_BATCH_ID")
message_batch = client.messages.batches.cancel(message_batch_id)
puts message_batch
```
</CodeGroup>
The response will show the batch in a `canceling` state:
```json Output
{
"id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
"type": "message_batch",
"processing_status": "canceling",
"request_counts": {
"processing": 2,
"succeeded": 0,
"errored": 0,
"canceled": 0,
"expired": 0
},
"ended_at": null,
"created_at": "2024-09-24T18:37:24.100435Z",
"expires_at": "2024-09-25T18:37:24.100435Z",
"cancel_initiated_at": "2024-09-24T18:39:03.114875Z",
"results_url": null
}
```
### Using prompt caching with Message Batches
The Message Batches API supports prompt caching, allowing you to potentially reduce costs and processing time for batch requests. The pricing discounts from prompt caching and Message Batches can stack, providing even greater cost savings when both features are used together. However, since batch requests are processed asynchronously and concurrently, cache hits are provided on a best-effort basis. Users typically experience cache hit rates ranging from 30% to 98%, depending on their traffic patterns.
To maximize the likelihood of cache hits in your batch requests:
1. Include identical `cache_control` blocks in every Message request within your batch
2. Maintain a steady stream of requests to prevent cache entries from expiring after their 5-minute lifetime
3. Structure your requests to share as much cached content as possible
Example of implementing prompt caching in a batch:
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages/batches \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data \
'{
"requests": [
{
"custom_id": "my-first-request",
"params": {
"model": "claude-opus-4-7",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
"type": "text",
"text": "<the entire contents of Pride and Prejudice>",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
]
}
},
{
"custom_id": "my-second-request",
"params": {
"model": "claude-opus-4-7",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
"type": "text",
"text": "<the entire contents of Pride and Prejudice>",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{"role": "user", "content": "Write a summary of Pride and Prejudice."}
]
}
}
]
}'
```
```bash CLI
ant messages:batches create <<'YAML'
requests:
- custom_id: my-first-request
params:
model: claude-opus-4-7
max_tokens: 1024
system:
- type: text
text: >
You are an AI assistant tasked with analyzing literary works. Your
goal is to provide insightful commentary on themes, characters, and
writing style.
- type: text
text: "<the entire contents of Pride and Prejudice>"
cache_control:
type: ephemeral
messages:
- role: user
content: Analyze the major themes in Pride and Prejudice.
- custom_id: my-second-request
params:
model: claude-opus-4-7
max_tokens: 1024
system:
- type: text
text: >
You are an AI assistant tasked with analyzing literary works. Your
goal is to provide insightful commentary on themes, characters, and
writing style.
- type: text
text: "<the entire contents of Pride and Prejudice>"
cache_control:
type: ephemeral
messages:
- role: user
content: Write a summary of Pride and Prejudice.
YAML
```
```python Python hidelines={1}
import anthropic
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request
client = anthropic.Anthropic()
message_batch = client.messages.batches.create(
requests=[
Request(
custom_id="my-first-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-4-7",
max_tokens=1024,
system=[
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
},
{
"type": "text",
"text": "<the entire contents of Pride and Prejudice>",
"cache_control": {"type": "ephemeral"},
},
],
messages=[
{
"role": "user",
"content": "Analyze the major themes in Pride and Prejudice.",
}
],
),
),
Request(
custom_id="my-second-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-4-7",
max_tokens=1024,
system=[
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
},
{
"type": "text",
"text": "<the entire contents of Pride and Prejudice>",
"cache_control": {"type": "ephemeral"},
},
],
messages=[
{
"role": "user",
"content": "Write a summary of Pride and Prejudice.",
}
],
),
),
]
)
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
const messageBatch = await anthropic.messages.batches.create({
requests: [
{
custom_id: "my-first-request",
params: {
model: "claude-opus-4-7",
max_tokens: 1024,
system: [
{
type: "text",
text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
type: "text",
text: "<the entire contents of Pride and Prejudice>",
cache_control: { type: "ephemeral" }
}
],
messages: [
{ role: "user", content: "Analyze the major themes in Pride and Prejudice." }
]
}
},
{
custom_id: "my-second-request",
params: {
model: "claude-opus-4-7",
max_tokens: 1024,
system: [
{
type: "text",
text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
type: "text",
text: "<the entire contents of Pride and Prejudice>",
cache_control: { type: "ephemeral" }
}
],
messages: [{ role: "user", content: "Write a summary of Pride and Prejudice." }]
}
}
]
});
```
```csharp C#
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages;
using Anthropic.Models.Messages.Batches;
public class Program
{
public static async Task Main(string[] args)
{
AnthropicClient client = new()
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
var messageBatch = await client.Messages.Batches.Create(new BatchCreateParams
{
Requests =
[
new()
{
CustomID = "my-first-request",
Params = new()
{
Model = Model.ClaudeOpus4_7,
MaxTokens = 1024,
System = new List<TextBlockParam>
{
new()
{
Text = "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
new()
{
Text = "<the entire contents of Pride and Prejudice>",
CacheControl = new()
}
},
Messages =
[
new() { Role = Role.User, Content = "Analyze the major themes in Pride and Prejudice." }
]
}
},
new()
{
CustomID = "my-second-request",
Params = new()
{
Model = Model.ClaudeOpus4_7,
MaxTokens = 1024,
System = new List<TextBlockParam>
{
new()
{
Text = "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
new()
{
Text = "<the entire contents of Pride and Prejudice>",
CacheControl = new()
}
},
Messages =
[
new() { Role = Role.User, Content = "Write a summary of Pride and Prejudice." }
]
}
}
]
});
}
}
```
```go Go hidelines={1..10,-1}
package main
import (
"context"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
messageBatch, err := client.Messages.Batches.New(context.TODO(), anthropic.MessageBatchNewParams{
Requests: []anthropic.MessageBatchNewParamsRequest{
{
CustomID: "my-first-request",
Params: anthropic.MessageBatchNewParamsRequestParams{
Model: anthropic.ModelClaudeOpus4_7,
MaxTokens: 1024,
System: []anthropic.TextBlockParam{
{
Text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
},
{
Text: "<the entire contents of Pride and Prejudice>",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the major themes in Pride and Prejudice.")),
},
},
},
{
CustomID: "my-second-request",
Params: anthropic.MessageBatchNewParamsRequestParams{
Model: anthropic.ModelClaudeOpus4_7,
MaxTokens: 1024,
System: []anthropic.TextBlockParam{
{
Text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
},
{
Text: "<the entire contents of Pride and Prejudice>",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Write a summary of Pride and Prejudice.")),
},
},
},
},
})
if err != nil {
log.Fatal(err)
}
log.Printf("%+v\n", messageBatch)
}
```
```java Java hidelines={1..2,4..5,7..11,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.CacheControlEphemeral;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.TextBlockParam;
import com.anthropic.models.messages.batches.*;
import java.util.List;
public class BatchExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
BatchCreateParams createParams = BatchCreateParams.builder()
.addRequest(
BatchCreateParams.Request.builder()
.customId("my-first-request")
.params(
BatchCreateParams.Request.Params.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(1024)
.systemOfTextBlockParams(
List.of(
TextBlockParam.builder()
.text(
"You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
)
.build(),
TextBlockParam.builder()
.text("<the entire contents of Pride and Prejudice>")
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
.addUserMessage("Analyze the major themes in Pride and Prejudice.")
.build()
)
.build()
)
.addRequest(
BatchCreateParams.Request.builder()
.customId("my-second-request")
.params(
BatchCreateParams.Request.Params.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(1024)
.systemOfTextBlockParams(
List.of(
TextBlockParam.builder()
.text(
"You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
)
.build(),
TextBlockParam.builder()
.text("<the entire contents of Pride and Prejudice>")
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
.addUserMessage("Write a summary of Pride and Prejudice.")
.build()
)
.build()
)
.build();
MessageBatch messageBatch = client.messages().batches().create(createParams);
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$messageBatch = $client->messages->batches->create(
requests: [
[
'custom_id' => 'my-first-request',
'params' => [
'model' => 'claude-opus-4-7',
'max_tokens' => 1024,
'system' => [
[
'type' => 'text',
'text' => 'You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n'
],
[
'type' => 'text',
'text' => '<the entire contents of Pride and Prejudice>',
'cache_control' => ['type' => 'ephemeral']
]
],
'messages' => [
['role' => 'user', 'content' => 'Analyze the major themes in Pride and Prejudice.']
]
]
],
[
'custom_id' => 'my-second-request',
'params' => [
'model' => 'claude-opus-4-7',
'max_tokens' => 1024,
'system' => [
[
'type' => 'text',
'text' => 'You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n'
],
[
'type' => 'text',
'text' => '<the entire contents of Pride and Prejudice>',
'cache_control' => ['type' => 'ephemeral']
]
],
'messages' => [
['role' => 'user', 'content' => 'Write a summary of Pride and Prejudice.']
]
]
]
],
);
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
message_batch = client.messages.batches.create(
requests: [
{
custom_id: "my-first-request",
params: {
model: "claude-opus-4-7",
max_tokens: 1024,
system: [
{
type: "text",
text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
type: "text",
text: "<the entire contents of Pride and Prejudice>",
cache_control: { type: "ephemeral" }
}
],
messages: [
{ role: "user", content: "Analyze the major themes in Pride and Prejudice." }
]
}
},
{
custom_id: "my-second-request",
params: {
model: "claude-opus-4-7",
max_tokens: 1024,
system: [
{
type: "text",
text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
type: "text",
text: "<the entire contents of Pride and Prejudice>",
cache_control: { type: "ephemeral" }
}
],
messages: [
{ role: "user", content: "Write a summary of Pride and Prejudice." }
]
}
}
]
)
```
</CodeGroup>
In this example, both requests in the batch include identical system messages and the full text of Pride and Prejudice marked with `cache_control` to increase the likelihood of cache hits.
### Extended output (beta)
The `output-300k-2026-03-24` beta header raises the `max_tokens` cap to 300,000 for batch requests using Claude Opus 4.7, Claude Opus 4.6, or Claude Sonnet 4.6. Include the header to generate outputs far longer than the standard limit (64k to 128k depending on model) in a single turn.
<Note>
Extended output is available on the Message Batches API only, not the synchronous Messages API. It is supported on the Claude API and is not available on Amazon Bedrock, Vertex AI, or Microsoft Foundry.
</Note>
Use extended output for long-form generation such as book-length drafts and technical documentation, exhaustive structured data extraction, large code-generation scaffolds, and long reasoning chains.
A single 300k-token generation can take over an hour to complete, so plan your batch submissions with the 24-hour processing window in mind. Standard batch pricing (50% of standard API prices) applies.
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages/batches \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: output-300k-2026-03-24" \
--header "content-type: application/json" \
--data \
'{
"requests": [
{
"custom_id": "long-form-request",
"params": {
"model": "claude-opus-4-7",
"max_tokens": 300000,
"messages": [
{"role": "user", "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."}
]
}
}
]
}'
```
```bash CLI
ant beta:messages:batches create --beta output-300k-2026-03-24 <<'YAML'
requests:
- custom_id: long-form-request
params:
model: claude-opus-4-7
max_tokens: 300000
messages:
- role: user
content: >-
Write a comprehensive technical guide to building distributed
systems, covering architecture patterns, consistency models,
fault tolerance, and operational best practices.
YAML
```
```python Python hidelines={1}
import anthropic
from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.beta.messages.batch_create_params import Request
client = anthropic.Anthropic()
message_batch = client.beta.messages.batches.create(
betas=["output-300k-2026-03-24"],
requests=[
Request(
custom_id="long-form-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-4-7",
max_tokens=300_000,
messages=[
{
"role": "user",
"content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.",
}
],
),
),
],
)
print(message_batch)
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
const messageBatch = await anthropic.beta.messages.batches.create({
betas: ["output-300k-2026-03-24"],
requests: [
{
custom_id: "long-form-request",
params: {
model: "claude-opus-4-7",
max_tokens: 300000,
messages: [
{
role: "user",
content:
"Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."
}
]
}
}
]
});
console.log(messageBatch);
```
```csharp C#
using Anthropic;
using Anthropic.Models.Beta.Messages;
using Anthropic.Models.Beta.Messages.Batches;
AnthropicClient client = new();
var batch = await client.Beta.Messages.Batches.Create(new BatchCreateParams
{
Betas = ["output-300k-2026-03-24"],
Requests =
[
new()
{
CustomID = "long-form-request",
Params = new()
{
Model = "claude-opus-4-7",
MaxTokens = 300_000,
Messages =
[
new() { Role = Role.User, Content = "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices." }
]
}
}
]
});
Console.WriteLine(batch);
```
```go Go hidelines={1..10,-1}
package main
import (
"context"
"fmt"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
batch, err := client.Beta.Messages.Batches.New(context.Background(),
anthropic.BetaMessageBatchNewParams{
Betas: []anthropic.AnthropicBeta{"output-300k-2026-03-24"},
Requests: []anthropic.BetaMessageBatchNewParamsRequest{
{
CustomID: "long-form-request",
Params: anthropic.BetaMessageBatchNewParamsRequestParams{
Model: anthropic.ModelClaudeOpus4_7,
MaxTokens: 300_000,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(
anthropic.NewBetaTextBlock("Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."),
),
},
},
},
},
})
if err != nil {
panic(err)
}
fmt.Println(batch.ID)
}
```
```java Java hidelines={1..3,5..6,-1}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.Model;
import com.anthropic.models.beta.messages.batches.*;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
BatchCreateParams params = BatchCreateParams.builder()
.addBeta("output-300k-2026-03-24")
.addRequest(
BatchCreateParams.Request.builder()
.customId("long-form-request")
.params(
BatchCreateParams.Request.Params.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(300_000L)
.addUserMessage("Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.")
.build()
)
.build()
)
.build();
BetaMessageBatch messageBatch = client.beta().messages().batches().create(params);
IO.println(messageBatch);
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client();
$batch = $client->beta->messages->batches->create(
betas: ['output-300k-2026-03-24'],
requests: [
[
'custom_id' => 'long-form-request',
'params' => [
'model' => 'claude-opus-4-7',
'max_tokens' => 300_000,
'messages' => [
['role' => 'user', 'content' => 'Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.']
]
]
]
],
);
print_r($batch);
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
batch = client.beta.messages.batches.create(
betas: ["output-300k-2026-03-24"],
requests: [
{
custom_id: "long-form-request",
params: {
model: "claude-opus-4-7",
max_tokens: 300_000,
messages: [
{ role: "user", content: "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices." }
]
}
}
]
)
puts batch
```
</CodeGroup>
### Best practices for effective batching
To get the most out of the Batches API:
- Monitor batch processing status regularly and implement appropriate retry logic for failed requests.
- Use meaningful `custom_id` values to easily match results with requests, since order is not guaranteed.
- Consider breaking very large datasets into multiple batches for better manageability.
- Dry run a single request shape with the Messages API to avoid validation errors.
### Troubleshooting common issues
If experiencing unexpected behavior:
- Verify that the total batch request size doesn't exceed 256 MB. If the request size is too large, you may get a 413 `request_too_large` error.
- Check that you're using [supported models](#supported-models) for all requests in the batch.
- Ensure each request in the batch has a unique `custom_id`.
- Ensure that it has been less than 29 days since batch `created_at` (not processing `ended_at`) time. If over 29 days have passed, results will no longer be viewable.
- Confirm that the batch has not been canceled.
Note that the failure of one request in a batch does not affect the processing of other requests.
---
## Batch storage and privacy
- **Workspace isolation**: Batches are isolated within the Workspace they are created in. They can only be accessed by API keys associated with that Workspace, or users with permission to view Workspace batches in the Console.
- **Result availability**: Batch results are available for 29 days after the batch is created, allowing ample time for retrieval and processing.
---
## Data retention
Batch processing stores request and response data for up to 29 days after batch creation. You can delete a message batch at any time after processing using the `DELETE /v1/messages/batches/{batch_id}` endpoint. To delete an in-progress batch, cancel it first. Asynchronous processing requires server-side storage of both inputs and outputs until batch completion and result retrieval.
For ZDR eligibility across all features, see [API and data retention](/docs/en/build-with-claude/api-and-data-retention).
## FAQ
<section title="How long does it take for a batch to process?">
Batches may take up to 24 hours for processing, but many finish sooner. Actual processing time depends on the size of the batch, current demand, and your request volume. It is possible for a batch to expire and not complete within 24 hours.
</section>
<section title="Is the Batches API available for all models?">
See [above](#supported-models) for the list of supported models.
</section>
<section title="Can I use the Message Batches API with other API features?">
Yes, the Message Batches API supports all features available in the Messages API, including beta features. However, streaming is not supported for batch requests.
</section>
<section title="How does the Message Batches API affect pricing?">
The Message Batches API offers a 50% discount on all usage compared to standard API prices. This applies to input tokens, output tokens, and any special tokens. For more on pricing, visit the [pricing page](https://claude.com/pricing#anthropic-api).
</section>
<section title="Can I update a batch after it's been submitted?">
No, once a batch has been submitted, it cannot be modified. If you need to make changes, you should cancel the current batch and submit a new one. Note that cancellation may not take immediate effect.
</section>
<section title="Are there Message Batches API rate limits and do they interact with the Messages API rate limits?">
The Message Batches API has HTTP requests-based rate limits in addition to limits on the number of requests in need of processing. See [Message Batches API rate limits](/docs/en/api/rate-limits#message-batches-api). Usage of the Batches API does not affect rate limits in the Messages API.
</section>
<section title="How do I handle errors in my batch requests?">
When you retrieve the results, each request will have a `result` field indicating whether it `succeeded`, `errored`, was `canceled`, or `expired`. For `errored` results, additional error information will be provided. View the error response object in the [API reference](/docs/en/api/creating-message-batches).
</section>
<section title="How does the Message Batches API handle privacy and data separation?">
The Message Batches API is designed with strong privacy and data separation measures:
1. Batches and their results are isolated within the Workspace in which they were created. This means they can only be accessed by API keys from that same Workspace.
2. Each request within a batch is processed independently, with no data leakage between requests.
3. Results are only available for a limited time (29 days), and follow Anthropic's [data retention policy](../../17-Billing-Plans/how-long-do-you-store-personal-data.md).
4. Downloading batch results in the Console can be disabled on the organization-level or on a per-workspace basis.
</section>
<section title="Can I use prompt caching in the Message Batches API?">
Yes, it is possible to use prompt caching with Message Batches API. However, because asynchronous batch requests can be processed concurrently and in any order, cache hits are provided on a best-effort basis.
</section>
---
## Guides/build-with-claude-citations-a7ca911a58.md
# Citations
---
<Note>
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.
</Note>
Claude is capable of providing detailed citations when answering questions about documents, helping you track and verify information sources in responses.
All [active models](/docs/en/about-claude/models/overview) support citations, with the exception of Haiku 3.
<Tip>
Share your feedback and suggestions about the citations feature using this [form](https://forms.gle/9n9hSrKnKe3rpowH9).
</Tip>
Here's an example of how to use citations with the Messages API:
<CodeGroup>
```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": [
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "The grass is green. The sky is blue."
},
"title": "My Document",
"context": "This is a trustworthy document.",
"citations": {"enabled": true}
},
{
"type": "text",
"text": "What color is the grass and sky?"
}
]
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-4-7
max_tokens: 1024
messages:
- role: user
content:
- type: document
source:
type: text
media_type: text/plain
data: The grass is green. The sky is blue.
title: My Document
context: This is a trustworthy document.
citations:
enabled: true
- type: text
text: What color is the grass and sky?
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": [
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "The grass is green. The sky is blue.",
},
"title": "My Document",
"context": "This is a trustworthy document.",
"citations": {"enabled": True},
},
{"type": "text", "text": "What color is the grass and sky?"},
],
}
],
)
print(response)
```
```java Java hidelines={1..8,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.*;
import java.util.List;
public class DocumentExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
PlainTextSource source = PlainTextSource.builder()
.data("The grass is green. The sky is blue.")
.build();
DocumentBlockParam documentParam = DocumentBlockParam.builder()
.source(source)
.title("My Document")
.context("This is a trustworthy document.")
.citations(CitationsConfigParam.builder().enabled(true).build())
.build();
TextBlockParam textBlockParam = TextBlockParam.builder()
.text("What color is the grass and sky?")
.build();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(1024)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofDocument(documentParam),
ContentBlockParam.ofText(textBlockParam)
)
)
.build();
Message message = client.messages().create(params);
System.out.println(message);
}
}
```
</CodeGroup>
<Tip>
**Comparison with prompt-based approaches**
In comparison with prompt-based citations solutions, the citations feature has the following advantages:
- **Cost savings:** If your prompt-based approach asks Claude to output direct quotes, you may see cost savings due to the fact that `cited_text` does not count towards your output tokens.
- **Better citation reliability:** Because citations are parsed into the respective response formats mentioned above and `cited_text` is extracted, citations are guaranteed to contain valid pointers to the provided documents.
- **Improved citation quality:** In evaluations, the citations feature was found to be significantly more likely to cite the most relevant quotes from documents as compared to purely prompt-based approaches.
</Tip>
---
## How citations work
Integrate citations with Claude in these steps:
<Steps>
<Step title="Provide document(s) and enable citations">
- Include documents in any of the supported formats: [PDFs](#pdf-documents), [plain text](#plain-text-documents), or [custom content](#custom-content-documents) documents
- Set `citations.enabled=true` on each of your documents. Currently, citations must be enabled on all or none of the documents within a request.
- Note that only text citations are currently supported and image citations are not yet possible.
</Step>
<Step title="Documents get processed">
- Document contents are "chunked" in order to define the minimum granularity of possible citations. For example, sentence chunking would allow Claude to cite a single sentence or chain together multiple consecutive sentences to cite a paragraph (or longer)!
- **For PDFs:** Text is extracted as described in [PDF Support](/docs/en/build-with-claude/pdf-support) and content is chunked into sentences. Citing images from PDFs is not currently supported.
- **For plain text documents:** Content is chunked into sentences that can be cited from.
- **For custom content documents:** Your provided content blocks are used as-is and no further chunking is done.
</Step>
<Step title="Claude provides cited response">
- Responses may now include multiple text blocks where each text block can contain a claim that Claude is making and a list of citations that support the claim.
- Citations reference specific locations in source documents. The format of these citations are dependent on the type of document being cited from.
- **For PDFs:** Citations include the page number range (1-indexed).
- **For plain text documents:** Citations include the character index range (0-indexed).
- **For custom content documents:** Citations include the content block index range (0-indexed) corresponding to the original content list provided.
- Document indices are provided to indicate the reference source and are 0-indexed according to the list of all documents in your original request.
</Step>
</Steps>
<Tip>
**Automatic chunking vs custom content**
By default, plain text and PDF documents are automatically chunked into sentences. If you need more control over citation granularity (e.g., for bullet points or transcripts), use custom content documents instead. See [Document Types](#document-types) for more details.
For example, if you want Claude to be able to cite specific sentences from your RAG chunks, you should put each RAG chunk into a plain text document. Otherwise, if you do not want any further chunking to be done, or if you want to customize any additional chunking, you can put RAG chunks into custom content document(s).
</Tip>
### Citable vs non-citable content
- Text found within a document's `source` content can be cited from.
- `title` and `context` are optional fields that will be passed to the model but not used towards cited content.
- `title` is limited in length so you may find the `context` field to be useful in storing any document metadata as text or stringified json.
### Citation indices
- Document indices are 0-indexed from the list of all document content blocks in the request (spanning across all messages).
- Character indices are 0-indexed with exclusive end indices.
- Page numbers are 1-indexed with exclusive end page numbers.
- Content block indices are 0-indexed with exclusive end indices from the `content` list provided in the custom content document.
### Token costs
- Enabling citations incurs a slight increase in input tokens due to system prompt additions and document chunking.
- However, the citations feature is very efficient with output tokens. Under the hood, the model is outputting citations in a standardized format that are then parsed into cited text and document location indices. The `cited_text` field is provided for convenience and does not count towards output tokens.
- When passed back in subsequent conversation turns, `cited_text` is also not counted towards input tokens.
### Feature compatibility
Citations works in conjunction with other API features including [prompt caching](/docs/en/build-with-claude/prompt-caching), [token counting](/docs/en/build-with-claude/token-counting) and [batch processing](/docs/en/build-with-claude/batch-processing).
<Warning>
**Citations and Structured Outputs are incompatible**
Citations cannot be used together with [Structured Outputs](/docs/en/build-with-claude/structured-outputs). If you enable citations on any user-provided document (Document blocks or RequestSearchResultBlock) and also include the `output_config.format` parameter (or the deprecated `output_format` parameter), the API will return a 400 error.
This is because citations require interleaving citation blocks with text output, which is incompatible with the strict JSON schema constraints of structured outputs.
</Warning>
#### Using Prompt Caching with Citations
Citations and prompt caching can be used together effectively.
The citation blocks generated in responses cannot be cached directly, but the source documents they reference can be cached. To optimize performance, apply `cache_control` to your top-level document content blocks.
<CodeGroup>
```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": [
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "This is a very long document with thousands of words..."
},
"citations": {"enabled": true},
"cache_control": {"type": "ephemeral"}
},
{
"type": "text",
"text": "What does this document say about API features?"
}
]
}
]
}'
```
```bash CLI
ant messages create \
--model claude-opus-4-7 \
--max-tokens 1024 <<'YAML'
messages:
- role: user
content:
- type: document
source:
type: text
media_type: text/plain
data: This is a very long document with thousands of words...
citations:
enabled: true
cache_control:
type: ephemeral
- type: text
text: What does this document say about API features?
YAML
```
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
# Long document content (e.g., technical documentation)
long_document = (
"This is a very long document with thousands of words..." + " ... " * 1000
) # Minimum cacheable length
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": long_document,
},
"citations": {"enabled": True},
"cache_control": {
"type": "ephemeral"
}, # Cache the document content
},
{
"type": "text",
"text": "What does this document say about API features?",
},
],
}
],
)
print(response)
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
// Long document content (e.g., technical documentation)
const longDocument =
"This is a very long document with thousands of words..." + " ... ".repeat(1000); // Minimum cacheable length
const response = await client.messages.create({
model: "claude-opus-4-7",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
{
type: "document",
source: {
type: "text",
media_type: "text/plain",
data: longDocument
},
citations: { enabled: true },
cache_control: { type: "ephemeral" } // Cache the document content
},
{
type: "text",
text: "What does this document say about API features?"
}
]
}
]
});
```
</CodeGroup>
In this example:
- The document content is cached using `cache_control` on the document block
- Citations are enabled on the document
- Claude can generate responses with citations while benefiting from cached document content
- Subsequent requests using the same document will benefit from the cached content
## Document Types
### Choosing a document type
Three document types are supported for citations. Documents can be provided directly in the message (base64, text, or URL) or uploaded via the [Files API](/docs/en/build-with-claude/files) and referenced by `file_id`:
| Type | Best for | Chunking | Citation format |
| :--- | :--- | :--- | :--- |
| Plain text | Simple text documents, prose | Sentence | Character indices (0-indexed) |
| PDF | PDF files with text content | Sentence | Page numbers (1-indexed) |
| Custom content | Lists, transcripts, special formatting, more granular citations | No additional chunking | Block indices (0-indexed) |
<Note>
.csv, .xlsx, .docx, .md, and .txt files are not supported as document blocks. Convert these to plain text and include directly in message content. See [Working with other file formats](/docs/en/build-with-claude/files#working-with-other-file-formats).
</Note>
### Plain text documents
Plain text documents are automatically chunked into sentences. You can provide them inline or by reference with their `file_id`:
<Tabs>
<Tab title="Inline text">
```python
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "Plain text content...",
},
"title": "Document Title", # optional
"context": "Context about the document that will not be cited from", # optional
"citations": {"enabled": True},
}
```
</Tab>
<Tab title="Files API">
```python
{
"type": "document",
"source": {"type": "file", "file_id": "file_011CNvxoj286tYUAZFiZMf1U"},
"title": "Document Title", # optional
"context": "Context about the document that will not be cited from", # optional
"citations": {"enabled": True},
}
```
</Tab>
</Tabs>
<section title="Example plain text citation">
```python
{
"type": "char_location",
"cited_text": "The exact text being cited", # not counted towards output tokens
"document_index": 0,
"document_title": "Document Title",
"start_char_index": 0, # 0-indexed
"end_char_index": 50, # exclusive
}
```
</section>
### PDF documents
PDF documents can be provided as base64-encoded data or by `file_id`. PDF text is extracted and chunked into sentences. As image citations are not yet supported, PDFs that are scans of documents and do not contain extractable text will not be citable.
<Tabs>
<Tab title="Base64">
```python
{
"type": "document",
"source": {
"type": "base64",
"media_type": "application/pdf",
"data": base64_encoded_pdf_data,
},
"title": "Document Title", # optional
"context": "Context about the document that will not be cited from", # optional
"citations": {"enabled": True},
}
```
</Tab>
<Tab title="Files API">
```python
{
"type": "document",
"source": {"type": "file", "file_id": "file_011CNvxoj286tYUAZFiZMf1U"},
"title": "Document Title", # optional
"context": "Context about the document that will not be cited from", # optional
"citations": {"enabled": True},
}
```
</Tab>
</Tabs>
<section title="Example PDF citation">
```python
{
"type": "page_location",
"cited_text": "The exact text being cited", # not counted towards output tokens
"document_index": 0,
"document_title": "Document Title",
"start_page_number": 1, # 1-indexed
"end_page_number": 2, # exclusive
}
```
</section>
### Custom content documents
Custom content documents give you control over citation granularity. No additional chunking is done and chunks are provided to the model according to the content blocks provided.
```python
{
"type": "document",
"source": {
"type": "content",
"content": [
{"type": "text", "text": "First chunk"},
{"type": "text", "text": "Second chunk"},
],
},
"title": "Document Title", # optional
"context": "Context about the document that will not be cited from", # optional
"citations": {"enabled": True},
}
```
<section title="Example citation">
```python
{
"type": "content_block_location",
"cited_text": "The exact text being cited", # not counted towards output tokens
"document_index": 0,
"document_title": "Document Title",
"start_block_index": 0, # 0-indexed
"end_block_index": 1, # exclusive
}
```
</section>
---
## Response Structure
When citations are enabled, responses include multiple text blocks with citations:
```python
{
"content": [
{"type": "text", "text": "According to the document, "},
{
"type": "text",
"text": "the grass is green",
"citations": [
{
"type": "char_location",
"cited_text": "The grass is green.",
"document_index": 0,
"document_title": "Example Document",
"start_char_index": 0,
"end_char_index": 20,
}
],
},
{"type": "text", "text": " and "},
{
"type": "text",
"text": "the sky is blue",
"citations": [
{
"type": "char_location",
"cited_text": "The sky is blue.",
"document_index": 0,
"document_title": "Example Document",
"start_char_index": 20,
"end_char_index": 36,
}
],
},
{
"type": "text",
"text": ". Information from page 5 states that ",
},
{
"type": "text",
"text": "water is essential",
"citations": [
{
"type": "page_location",
"cited_text": "Water is essential for life.",
"document_index": 1,
"document_title": "PDF Document",
"start_page_number": 5,
"end_page_number": 6,
}
],
},
{
"type": "text",
"text": ". The custom document mentions ",
},
{
"type": "text",
"text": "important findings",
"citations": [
{
"type": "content_block_location",
"cited_text": "These are important findings.",
"document_index": 2,
"document_title": "Custom Content Document",
"start_block_index": 0,
"end_block_index": 1,
}
],
},
]
}
```
### Streaming Support
For streaming responses, a `citations_delta` type is included that contains a single citation to be added to the `citations` list on the current `text` content block.
<section title="Example streaming events">
```sse
event: message_start
data: {"type": "message_start", ...}
event: content_block_start
data: {"type": "content_block_start", "index": 0, ...}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0,
"delta": {"type": "text_delta", "text": "According to..."}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0,
"delta": {"type": "citations_delta",
"citation": {
"type": "char_location",
"cited_text": "...",
"document_index": 0,
...
}}}
event: content_block_stop
data: {"type": "content_block_stop", "index": 0}
event: message_stop
data: {"type": "message_stop"}
```
</section>
---
## Guides/build-with-claude-compaction-47672e5bbf.md
# Compaction
Server-side context compaction for managing long conversations that approach context window limits.
---
<Note>
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.
</Note>
<Tip>
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.
</Tip>
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.
<Tip>
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).
</Tip>
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
<Note>
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.
</Note>
## 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.
## Basic usage
Enable compaction by adding the `compact_20260112` strategy to `context_management.edits` in your Messages API request.
<CodeGroup>
```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"
}
]
}
} as unknown as Anthropic.Beta.Messages.MessageCreateParamsNonStreaming);
// Append the response (including any compaction block) to continue the conversation
messages.push({
role: "assistant",
content: response.content as unknown as Anthropic.Beta.Messages.BetaContentBlockParam[]
});
```
```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<BetaMessageParam>
{
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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$messages = [
['role' => '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
```
</CodeGroup>
## 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:
<CodeGroup>
```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
}
}
]
}
} as unknown as Anthropic.Beta.Messages.MessageCreateParamsNonStreaming);
```
```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<BetaMessageParam> 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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$messages = [['role' => '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
```
</CodeGroup>
### 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 <summary></summary> 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:
<CodeGroup>
```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."
}
]
}
} as unknown as Anthropic.Beta.Messages.MessageCreateParamsNonStreaming);
```
```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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$response = $client->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
```
</CodeGroup>
### 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:
<CodeGroup>
```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 <<YAML > /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[] = [];
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
}
]
}
} as unknown as Anthropic.Beta.Messages.MessageCreateParamsNonStreaming);
// Check if compaction triggered a pause
if ((response.stop_reason as string) === "compaction") {
// Response contains only the compaction block
messages.push({
role: "assistant",
content: response.content as unknown as Anthropic.Beta.Messages.BetaContentBlockParam[]
});
// 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" }]
}
} as unknown as Anthropic.Beta.Messages.MessageCreateParamsNonStreaming);
}
```
```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<BetaMessageParam>();
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 hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$messages = [];
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-4-7',
betas: ['compact-2026-01-12'],
contextManagement: [
'edits' => [
[
'type' => 'compact_20260112',
'pauseAfterCompaction' => 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 = []
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
```
</CodeGroup>
#### 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:
<CodeGroup>
```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 <<YAML
model: claude-opus-4-7
max_tokens: 4096
messages:
- role: user
content: Hello, Claude
- role: assistant
content: $(cat content.json)
- role: user
content: Now add error handling
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,
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
)
# After receiving a response with a compaction block
messages.append({"role": "assistant", "content": response.content})
# Continue the conversation
messages.append({"role": "user", "content": "Now add error handling"})
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[] = [];
// Assume we already have a response from a previous request
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" }]
}
} as unknown as Anthropic.Beta.Messages.MessageCreateParamsNonStreaming);
// After receiving a response with a compaction block
messages.push({
role: "assistant",
content: response.content as unknown as Anthropic.Beta.Messages.BetaContentBlockParam[]
});
// Continue the conversation
messages.push({ role: "user", content: "Now add error handling" });
const nextResponse = 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" }]
}
} as unknown as Anthropic.Beta.Messages.MessageCreateParamsNonStreaming);
```
```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)
{
AnthropicClient client = new();
var messages = new List<BetaMessageParam>
{
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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$messages = [
['role' => '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
```
</CodeGroup>
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.
<CodeGroup>
```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)} 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 nocheck 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" }]
}
} as unknown as Anthropic.Beta.Messages.BetaMessageStreamParams);
for await (const event of stream) {
if (event.type === "content_block_start") {
if ((event.content_block as { type: string }).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 as { type: string }).type === "compaction_delta") {
console.log(
`Compaction complete: ${
(event.delta as unknown as { content: string }).content.length
} 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 as unknown as Anthropic.Beta.Messages.BetaContentBlockParam[]
});
```
```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<BetaMessageParam> 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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$messages = [['role' => '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
```
</CodeGroup>
### 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
<CodeGroup>
```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" }]
}
} as unknown as Anthropic.Beta.Messages.MessageCreateParamsNonStreaming);
```
```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<BetaTextBlockParam>
{
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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$response = $client->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
```
</CodeGroup>
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.
<Note>
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.
</Note>
## 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:
<CodeGroup>
```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 --format yaml < request.yaml)
ORIGINAL=$(ant beta:messages count-tokens \
--beta compact-2026-01-12 \
--transform context_management.original_input_tokens \
--format yaml < 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" }]
}
} as unknown as Anthropic.Beta.Messages.MessageCountTokensParams);
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<BetaMessageParam> 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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$messages = [['role' => '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}"
```
</CodeGroup>
## Examples
Here's a complete example of a long-running conversation with compaction:
<CodeGroup>
```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' --format yaml <<'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<string> {
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<BetaMessageParam> 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<string> Chat(AnthropicClient client, List<BetaMessageParam> 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<BetaTextBlock>()
.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<BetaMessageParam> 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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$messages = [];
function chat($client, &$messages, $userMessage) {
$messages[] = ['role' => '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")
```
</CodeGroup>
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:
<CodeGroup>
```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' --format yaml <<'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<string> {
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<BetaMessageParam> messages = new();
static async Task<string> 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<BetaMessageParam>(messages);
var messagesAfterCompaction = new List<BetaMessageParam>
{
new()
{
Role = Role.Assistant,
Content = new List<BetaContentBlockParam> { 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<BetaTextBlock>()
.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<BetaMessageParam> 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<BetaMessageParam> preservedMessages = messages.size() >= 3
? new ArrayList<>(messages.subList(messages.size() - 3, messages.size()))
: new ArrayList<>(messages);
// Build new message list: compaction + preserved messages
List<BetaMessageParam> 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 hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$messages = [];
function chat($client, &$messages, $userMessage) {
$messages[] = ['role' => '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],
'pauseAfterCompaction' => 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")
```
</CodeGroup>
## 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
<CardGroup>
<Card title="Session memory compaction cookbook" icon="book" href="https://platform.claude.com/cookbook/misc-session-memory-compaction">
Explore a practical implementation that manages long-running conversations with instant session memory compaction using background threading and prompt caching.
</Card>
<Card title="Context windows" icon="arrows-maximize" href="/docs/en/build-with-claude/context-windows">
Learn about context window sizes and management strategies.
</Card>
<Card title="Context editing" icon="pen" href="/docs/en/build-with-claude/context-editing">
Explore other strategies for managing conversation context like tool result clearing and thinking block clearing.
</Card>
</CardGroup>
---
## Guides/build-with-claude-context-editing-16aa20ebd8.md
# Context editing
Automatically manage conversation context as it grows with context editing.
---
<Note>
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.
</Note>
## Overview
<Note>
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.
</Note>
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`)<br/>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
<Note>
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).
</Note>
### 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.
<Tip>
**Default behavior:** When extended thinking is enabled without configuring the `clear_thinking_20251015` strategy, the API automatically keeps only the thinking blocks from the last assistant turn (equivalent to `keep: {type: "thinking_turns", value: 1}`).
To maximize cache hits, preserve all thinking blocks by setting `keep: "all"`.
</Tip>
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:
<CodeGroup>
```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}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$response = $client->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
```
</CodeGroup>
### Advanced configuration
You can customize the tool result clearing behavior with additional parameters:
<CodeGroup>
```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<BetaMessageParam>
{
new() { Role = Role.User, Content = "Create a simple command line calculator app using Python" }
},
Tools = new List<object>
{
new Dictionary<string, object>
{
{ "type", "text_editor_20250728" },
{ "name", "str_replace_based_edit_tool" },
{ "max_characters", 10000 }
},
new Dictionary<string, object>
{
{ "type", "web_search_20250305" },
{ "name", "web_search" },
{ "max_uses", 3 }
}
},
Betas = new List<string> { "context-management-2025-06-27" },
ContextManagement = new Dictionary<string, object>
{
{
"edits", new List<object>
{
new Dictionary<string, object>
{
{ "type", "clear_tool_uses_20250919" },
{ "trigger", new Dictionary<string, object>
{
{ "type", "input_tokens" },
{ "value", 30000 }
}
},
{ "keep", new Dictionary<string, object>
{
{ "type", "tool_uses" },
{ "value", 3 }
}
},
{ "clear_at_least", new Dictionary<string, object>
{
{ "type", "input_tokens" },
{ "value", 5000 }
}
},
{ "exclude_tools", new List<string> { "web_search" } }
}
}
}
}
};
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("Create a simple command line calculator app using Python")),
},
Tools: []anthropic.BetaToolUnionParam{
{OfTextEditor20250728: &anthropic.BetaToolTextEditor20250728Param{
MaxCharacters: anthropic.Int(10000),
}},
{OfWebSearchTool20250305: &anthropic.BetaWebSearchTool20250305Param{
MaxUses: anthropic.Int(3),
}},
},
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaContextManagement2025_06_27},
ContextManagement: anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfClearToolUses20250919: &anthropic.BetaClearToolUses20250919EditParam{
Trigger: anthropic.BetaClearToolUses20250919EditTriggerUnionParam{
OfInputTokens: &anthropic.BetaInputTokensTriggerParam{
Value: 30000,
},
},
Keep: anthropic.BetaToolUsesKeepParam{
Value: 3,
},
ClearAtLeast: anthropic.BetaInputTokensClearAtLeastParam{
Value: 5000,
},
ExcludeTools: []string{"web_search"},
}},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
}
```
```java Java nocheck hidelines={1..4,13..16,-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.BetaToolTextEditor20250728;
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.messages.BetaInputTokensTrigger;
import com.anthropic.models.beta.messages.BetaInputTokensClearAtLeast;
import com.anthropic.models.beta.messages.BetaToolUsesKeep;
import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.messages.Model;
public class ContextManagementExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(4096L)
.addUserMessage("Create a simple command line calculator app using Python")
.addTool(BetaToolTextEditor20250728.builder()
.maxCharacters(10000L)
.build())
.addTool(BetaWebSearchTool20250305.builder()
.maxUses(3L)
.build())
.addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaClearToolUses20250919Edit.builder()
.trigger(BetaInputTokensTrigger.builder()
.value(30000L)
.build())
.keep(BetaToolUsesKeep.builder()
.value(3L)
.build())
.clearAtLeast(BetaInputTokensClearAtLeast.builder()
.value(5000L)
.build())
.addExcludeTool("web_search")
.build())
.build())
.build();
BetaMessage response = client.beta().messages().create(params);
System.out.println(response);
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->beta->messages->create(
maxTokens: 4096,
messages: [
[
'role' => 'user',
'content' => 'Create a simple command line calculator app using Python'
]
],
model: 'claude-opus-4-7',
betas: ['context-management-2025-06-27'],
tools: [
[
'type' => 'text_editor_20250728',
'name' => 'str_replace_based_edit_tool',
'max_characters' => 10000
],
[
'type' => 'web_search_20250305',
'name' => 'web_search',
'max_uses' => 3
]
],
contextManagement: [
'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']
]
]
],
);
echo $message;
```
```ruby Ruby nocheck 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: "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: {
type: "input_tokens",
value: 30000
},
keep: {
type: "tool_uses",
value: 3
},
clear_at_least: {
type: "input_tokens",
value: 5000
},
exclude_tools: ["web_search"]
}
]
}
)
puts response
```
</CodeGroup>
## Thinking block clearing usage
Enable thinking block clearing to manage context and prompt caching effectively when extended thinking is enabled:
<CodeGroup>
```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-6",
"max_tokens": 16000,
"messages": [{"role": "user", "content": "Hello"}],
"thinking": {
"type": "enabled",
"budget_tokens": 10000
},
"context_management": {
"edits": [
{
"type": "clear_thinking_20251015",
"keep": {
"type": "thinking_turns",
"value": 2
}
}
]
}
}'
```
```bash CLI
ant beta:messages create --beta context-management-2025-06-27 <<'YAML'
model: claude-opus-4-6
max_tokens: 16000
messages:
- role: user
content: Hello
thinking:
type: enabled
budget_tokens: 10000
context_management:
edits:
- type: clear_thinking_20251015
keep:
type: thinking_turns
value: 2
YAML
```
```python Python nocheck
response = client.beta.messages.create(
model="claude-opus-4-6",
max_tokens=16000,
messages=[...],
thinking={"type": "enabled", "budget_tokens": 10000},
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{
"type": "clear_thinking_20251015",
"keep": {"type": "thinking_turns", "value": 2},
}
]
},
)
```
```typescript TypeScript nocheck 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-6",
max_tokens: 16000,
messages: [
// ...
],
thinking: {
type: "enabled",
budget_tokens: 10000
},
betas: ["context-management-2025-06-27"],
context_management: {
edits: [
{
type: "clear_thinking_20251015",
keep: {
type: "thinking_turns",
value: 2
}
}
]
}
});
```
```csharp C# nocheck
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
{
Model = "claude-opus-4-6",
MaxTokens = 16000,
Messages = [],
Thinking = new BetaThinkingParam
{
Type = "enabled",
BudgetTokens = 10000
},
Betas = ["context-management-2025-06-27"],
ContextManagement = new BetaContextManagementConfig()
{
Edits = [
new BetaClearThinking20251015Edit()
{
Keep = new BetaThinkingTurnsKeep
{
Type = "thinking_turns",
Value = 2
}
}
]
}
};
var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);
}
}
```
```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_6,
MaxTokens: 16000,
Messages: []anthropic.BetaMessageParam{},
Thinking: anthropic.BetaThinkingConfigParamOfEnabled(10000),
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaContextManagement2025_06_27},
ContextManagement: anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfClearThinking20251015: &anthropic.BetaClearThinking20251015EditParam{
Keep: anthropic.BetaClearThinking20251015EditKeepUnionParam{
OfThinkingTurns: &anthropic.BetaThinkingTurnsParam{
Value: 2,
},
},
}},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
}
```
```java Java nocheck hidelines={1..4,10..13,-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.BetaThinkingConfigEnabled;
import com.anthropic.models.beta.messages.BetaContextManagementConfig;
import com.anthropic.models.beta.messages.BetaClearThinking20251015Edit;
import com.anthropic.models.beta.messages.BetaThinkingTurns;
import com.anthropic.models.beta.AnthropicBeta;
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_6)
.maxTokens(16000L)
.thinking(BetaThinkingConfigEnabled.builder()
.budgetTokens(10000L)
.build())
.addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaClearThinking20251015Edit.builder()
.keep(BetaThinkingTurns.builder()
.value(2L)
.build())
.build())
.build())
.build();
BetaMessage response = client.beta().messages().create(params);
System.out.println(response);
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->beta->messages->create(
maxTokens: 16000,
messages: [/* ... */],
model: 'claude-opus-4-6',
betas: ['context-management-2025-06-27'],
thinking: [
'type' => 'enabled',
'budget_tokens' => 10000
],
contextManagement: [
'edits' => [
[
'type' => 'clear_thinking_20251015',
'keep' => [
'type' => 'thinking_turns',
'value' => 2
]
]
]
],
);
echo $message;
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
messages = [{ role: "user", content: "Explain quantum computing in simple terms" }]
response = client.beta.messages.create(
model: "claude-opus-4-6",
max_tokens: 16000,
messages: messages,
thinking: {
type: "enabled",
budget_tokens: 10000
},
betas: ["context-management-2025-06-27"],
context_management: {
edits: [
{
type: "clear_thinking_20251015",
keep: {
type: "thinking_turns",
value: 2
}
}
]
}
)
puts response
```
</CodeGroup>
### Configuration options for thinking block clearing
The `clear_thinking_20251015` strategy supports the following configuration:
| Configuration option | Default | Description |
|---------------------|---------|-------------|
| `keep` | `{type: "thinking_turns", value: 1}` | Defines how many recent assistant turns with thinking blocks to preserve. Use `{type: "thinking_turns", value: N}` where N must be > 0 to keep the last N turns, or `"all"` to keep all thinking blocks. |
**Example configurations:**
Keep thinking blocks from the last 3 assistant turns:
```json
{
"type": "clear_thinking_20251015",
"keep": {
"type": "thinking_turns",
"value": 3
}
}
```
Keep all thinking blocks (maximizes cache hits):
```json
{
"type": "clear_thinking_20251015",
"keep": "all"
}
```
### Combining strategies
You can use both thinking block clearing and tool result clearing together:
<Note>
When using multiple strategies, the `clear_thinking_20251015` strategy must be listed first in the `edits` array.
</Note>
<CodeGroup>
```bash CLI
ant beta:messages create --beta context-management-2025-06-27 <<'YAML'
model: claude-opus-4-6
max_tokens: 16000
thinking:
type: enabled
budget_tokens: 10000
messages:
- role: user
content: Hello
tools:
- type: web_search_20250305
name: web_search
context_management:
edits:
- type: clear_thinking_20251015
keep:
type: thinking_turns
value: 2
- type: clear_tool_uses_20250919
trigger:
type: input_tokens
value: 50000
keep:
type: tool_uses
value: 5
YAML
```
```python Python nocheck
response = client.beta.messages.create(
model="claude-opus-4-6",
max_tokens=16000,
messages=[...],
thinking={"type": "enabled", "budget_tokens": 10000},
tools=[...],
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{
"type": "clear_thinking_20251015",
"keep": {"type": "thinking_turns", "value": 2},
},
{
"type": "clear_tool_uses_20250919",
"trigger": {"type": "input_tokens", "value": 50000},
"keep": {"type": "tool_uses", "value": 5},
},
]
},
)
```
```typescript TypeScript nocheck
const response = await anthropic.beta.messages.create({
model: "claude-opus-4-6",
max_tokens: 16000,
messages: [
// ...
],
thinking: {
type: "enabled",
budget_tokens: 10000
},
tools: [
// ...
],
betas: ["context-management-2025-06-27"],
context_management: {
edits: [
{
type: "clear_thinking_20251015",
keep: {
type: "thinking_turns",
value: 2
}
},
{
type: "clear_tool_uses_20250919",
trigger: {
type: "input_tokens",
value: 50000
},
keep: {
type: "tool_uses",
value: 5
}
}
]
}
});
```
```csharp C# nocheck
using Anthropic;
using Anthropic.Models.Beta.Messages;
public class Program
{
public static async Task Main(string[] args)
{
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus4_6,
MaxTokens = 16000,
Messages = [],
Thinking = new BetaThinkingParam
{
Type = "enabled",
BudgetTokens = 10000
},
Tools = [],
Betas = ["context-management-2025-06-27"],
ContextManagement = new BetaContextManagementConfig()
{
Edits = [
new BetaClearThinking20251015Edit()
{
Keep = new BetaThinkingTurnsKeep
{
Type = "thinking_turns",
Value = 2
}
},
new BetaClearToolUses20250919Edit()
{
Trigger = new BetaInputTokensTrigger
{
Type = "input_tokens",
Value = 50000
},
Keep = new BetaToolUsesKeep
{
Type = "tool_uses",
Value = 5
}
}
]
}
};
var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);
}
}
```
```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_6,
MaxTokens: 16000,
Messages: []anthropic.BetaMessageParam{},
Thinking: anthropic.BetaThinkingConfigParamOfEnabled(10000),
Tools: []anthropic.BetaToolUnionParam{},
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaContextManagement2025_06_27,
},
ContextManagement: anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfClearThinking20251015: &anthropic.BetaClearThinking20251015EditParam{
Keep: anthropic.BetaClearThinking20251015EditKeepUnionParam{
OfThinkingTurns: &anthropic.BetaThinkingTurnsParam{
Value: 2,
},
},
}},
{OfClearToolUses20250919: &anthropic.BetaClearToolUses20250919EditParam{
Trigger: anthropic.BetaClearToolUses20250919EditTriggerUnionParam{
OfInputTokens: &anthropic.BetaInputTokensTriggerParam{
Value: 50000,
},
},
Keep: anthropic.BetaToolUsesKeepParam{
Value: 5,
},
}},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
}
```
```java Java nocheck hidelines={1..4,13..16,-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.BetaThinkingConfigEnabled;
import com.anthropic.models.beta.messages.BetaContextManagementConfig;
import com.anthropic.models.beta.messages.BetaClearThinking20251015Edit;
import com.anthropic.models.beta.messages.BetaClearToolUses20250919Edit;
import com.anthropic.models.beta.messages.BetaThinkingTurns;
import com.anthropic.models.beta.messages.BetaInputTokensTrigger;
import com.anthropic.models.beta.messages.BetaToolUsesKeep;
import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.messages.Model;
public class ContextManagementExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_6)
.maxTokens(16000L)
.thinking(BetaThinkingConfigEnabled.builder()
.budgetTokens(10000L)
.build())
.addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaClearThinking20251015Edit.builder()
.keep(BetaThinkingTurns.builder()
.value(2L)
.build())
.build())
.addEdit(BetaClearToolUses20250919Edit.builder()
.trigger(BetaInputTokensTrigger.builder()
.value(50000L)
.build())
.keep(BetaToolUsesKeep.builder()
.value(5L)
.build())
.build())
.build())
.build();
BetaMessage response = client.beta().messages().create(params);
System.out.println(response);
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->beta->messages->create(
maxTokens: 16000,
messages: [/* ... */],
model: 'claude-opus-4-6',
betas: ['context-management-2025-06-27'],
thinking: ['type' => 'enabled', 'budget_tokens' => 10000],
tools: [/* ... */],
contextManagement: [
'edits' => [
[
'type' => 'clear_thinking_20251015',
'keep' => [
'type' => 'thinking_turns',
'value' => 2
]
],
[
'type' => 'clear_tool_uses_20250919',
'trigger' => [
'type' => 'input_tokens',
'value' => 50000
],
'keep' => [
'type' => 'tool_uses',
'value' => 5
]
]
]
],
);
echo $message;
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
messages = [{ role: "user", content: "Explain quantum computing in simple terms" }]
response = client.beta.messages.create(
model: "claude-opus-4-6",
max_tokens: 16000,
messages: messages,
thinking: {
type: "enabled",
budget_tokens: 10000
},
tools: [
# ...
],
betas: ["context-management-2025-06-27"],
context_management: {
edits: [
{
type: "clear_thinking_20251015",
keep: {
type: "thinking_turns",
value: 2
}
},
{
type: "clear_tool_uses_20250919",
trigger: {
type: "input_tokens",
value: 50000
},
keep: {
type: "tool_uses",
value: 5
}
}
]
}
)
puts response
```
</CodeGroup>
## Configuration options for tool result clearing
| Configuration option | Default | Description |
|---------------------|---------|-------------|
| `trigger` | 100,000 input tokens | Defines when the context editing strategy activates. Once the prompt exceeds this threshold, clearing will begin. You can specify this value in either `input_tokens` or `tool_uses`. |
| `keep` | 3 tool uses | Defines how many recent tool use/result pairs to keep after clearing occurs. The API removes the oldest tool interactions first, preserving the most recent ones. |
| `clear_at_least` | None | Ensures a minimum number of tokens is cleared each time the strategy activates. If the API can't clear at least the specified amount, the strategy will not be applied. This helps determine if context clearing is worth breaking your prompt cache. |
| `exclude_tools` | None | List of tool names whose tool uses and results should never be cleared. Useful for preserving important context. |
| `clear_tool_inputs` | `false` | Controls whether the tool call parameters are cleared along with the tool results. By default, only the tool results are cleared while keeping Claude's original tool calls visible. |
## Context editing response
You can see which context edits were applied to your request using the `context_management` response field, along with helpful statistics about the content and input tokens cleared.
```json Output
{
"id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
"type": "message",
"role": "assistant",
"content": [
// ...
],
"usage": {
// ...
},
"context_management": {
"applied_edits": [
// When using `clear_thinking_20251015`
{
"type": "clear_thinking_20251015",
"cleared_thinking_turns": 3,
"cleared_input_tokens": 15000
},
// When using `clear_tool_uses_20250919`
{
"type": "clear_tool_uses_20250919",
"cleared_tool_uses": 8,
"cleared_input_tokens": 50000
}
]
}
}
```
For streaming responses, the context edits will be included in the final `message_delta` event:
```json Streaming Response
{
"type": "message_delta",
"delta": {
"stop_reason": "end_turn",
"stop_sequence": null
},
"usage": {
"output_tokens": 1024
},
"context_management": {
"applied_edits": [
// ...
]
}
}
```
## Token counting
The [token counting](/docs/en/build-with-claude/token-counting) endpoint supports context management, allowing you to preview how many tokens your prompt will use after context editing is applied.
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages/count_tokens \
--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",
"messages": [
{
"role": "user",
"content": "Continue our conversation..."
}
],
"tools": [],
"context_management": {
"edits": [
{
"type": "clear_tool_uses_20250919",
"trigger": {
"type": "input_tokens",
"value": 30000
},
"keep": {
"type": "tool_uses",
"value": 5
}
}
]
}
}'
```
```bash CLI
cat > request.yaml <<'YAML'
model: claude-opus-4-7
messages:
- role: user
content: Continue our conversation...
tools: []
context_management:
edits:
- type: clear_tool_uses_20250919
trigger:
type: input_tokens
value: 30000
keep:
type: tool_uses
value: 5
YAML
ORIGINAL=$(ant beta:messages count-tokens \
--beta context-management-2025-06-27 \
--transform context_management.original_input_tokens \
--format yaml < request.yaml)
INPUT_TOKENS=$(ant beta:messages count-tokens \
--beta context-management-2025-06-27 \
--transform input_tokens --format yaml < request.yaml)
printf 'Original tokens: %s\n' "$ORIGINAL"
printf 'After clearing: %s\n' "$INPUT_TOKENS"
printf 'Savings: %s tokens\n' "$((ORIGINAL - INPUT_TOKENS))"
```
```python Python nocheck
response = client.beta.messages.count_tokens(
model="claude-opus-4-7",
messages=[{"role": "user", "content": "Continue our conversation..."}],
tools=[...], # Your tool definitions
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{
"type": "clear_tool_uses_20250919",
"trigger": {"type": "input_tokens", "value": 30000},
"keep": {"type": "tool_uses", "value": 5},
}
]
},
)
print(f"Original tokens: {response.context_management['original_input_tokens']}")
print(f"After clearing: {response.input_tokens}")
print(
f"Savings: {response.context_management['original_input_tokens'] - response.input_tokens} tokens"
)
```
```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.countTokens({
model: "claude-opus-4-7",
messages: [
{
role: "user",
content: "Continue our conversation..."
}
],
tools: [
// ...
], // Your tool definitions
betas: ["context-management-2025-06-27"],
context_management: {
edits: [
{
type: "clear_tool_uses_20250919",
trigger: {
type: "input_tokens",
value: 30000
},
keep: {
type: "tool_uses",
value: 5
}
}
]
}
});
console.log(`Original tokens: ${response.context_management?.original_input_tokens}`);
console.log(`After clearing: ${response.input_tokens}`);
console.log(
`Savings: ${
(response.context_management?.original_input_tokens || 0) - response.input_tokens
} tokens`
);
```
```csharp C# nocheck
using Anthropic;
using Anthropic.Models.Beta.Messages;
var client = new AnthropicClient
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
var parameters = new BetaMessageTokensCountParams
{
Model = "claude-opus-4-7",
Messages = [new() { Role = Role.User, Content = "Continue our conversation..." }],
Betas = ["context-management-2025-06-27"],
ContextManagement = new BetaContextManagementConfig
{
Edits = [
new BetaClearToolUses20250919Edit
{
Trigger = new BetaInputTokensTrigger { Value = 30000 },
Keep = new BetaToolUsesKeep { Value = 5 }
}
]
}
};
var response = await client.Beta.Messages.CountTokens(parameters);
Console.WriteLine($"Original tokens: {response.ContextManagement?.OriginalInputTokens}");
Console.WriteLine($"After clearing: {response.InputTokens}");
Console.WriteLine($"Savings: {(response.ContextManagement?.OriginalInputTokens ?? 0) - response.InputTokens} tokens");
```
```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.CountTokens(context.TODO(), anthropic.BetaMessageCountTokensParams{
Model: anthropic.ModelClaudeOpus4_7,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Continue our conversation...")),
},
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaContextManagement2025_06_27,
},
ContextManagement: anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfClearToolUses20250919: &anthropic.BetaClearToolUses20250919EditParam{
Trigger: anthropic.BetaClearToolUses20250919EditTriggerUnionParam{
OfInputTokens: &anthropic.BetaInputTokensTriggerParam{
Value: 30000,
},
},
Keep: anthropic.BetaToolUsesKeepParam{
Value: 5,
},
}},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Original tokens: %d\n", response.ContextManagement.OriginalInputTokens)
fmt.Printf("After clearing: %d\n", response.InputTokens)
fmt.Printf("Savings: %d tokens\n", response.ContextManagement.OriginalInputTokens-response.InputTokens)
}
```
```java Java hidelines={1..2,10..13,-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.BetaClearToolUses20250919Edit;
import com.anthropic.models.beta.messages.BetaInputTokensTrigger;
import com.anthropic.models.beta.messages.BetaToolUsesKeep;
import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.messages.Model;
public class TokenCountExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCountTokensParams params = MessageCountTokensParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.addUserMessage("Continue our conversation...")
.addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaClearToolUses20250919Edit.builder()
.trigger(BetaInputTokensTrigger.builder()
.value(30000L)
.build())
.keep(BetaToolUsesKeep.builder()
.value(5L)
.build())
.build())
.build())
.build();
BetaMessageTokensCount response = client.beta().messages().countTokens(params);
System.out.println("Original tokens: " + response.contextManagement().get().originalInputTokens());
System.out.println("After clearing: " + response.inputTokens());
System.out.println("Savings: " + (response.contextManagement().get().originalInputTokens() - response.inputTokens()) + " tokens");
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$response = $client->beta->messages->countTokens(
messages: [
['role' => 'user', 'content' => 'Continue our conversation...']
],
model: 'claude-opus-4-7',
betas: ['context-management-2025-06-27'],
contextManagement: [
'edits' => [
[
'type' => 'clear_tool_uses_20250919',
'trigger' => [
'type' => 'input_tokens',
'value' => 30000
],
'keep' => [
'type' => 'tool_uses',
'value' => 5
]
]
]
],
);
echo "Original tokens: " . $response->contextManagement->originalInputTokens . "\n";
echo "After clearing: " . $response->inputTokens . "\n";
echo "Savings: " . ($response->contextManagement->originalInputTokens - $response->inputTokens) . " tokens\n";
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
response = client.beta.messages.count_tokens(
model: "claude-opus-4-7",
messages: [
{ role: "user", content: "Continue our conversation..." }
],
betas: ["context-management-2025-06-27"],
context_management: {
edits: [
{
type: "clear_tool_uses_20250919",
trigger: {
type: "input_tokens",
value: 30000
},
keep: {
type: "tool_uses",
value: 5
}
}
]
}
)
puts "Original tokens: #{response.context_management.original_input_tokens}"
puts "After clearing: #{response.input_tokens}"
puts "Savings: #{response.context_management.original_input_tokens - response.input_tokens} tokens"
```
</CodeGroup>
```json Output
{
"input_tokens": 25000,
"context_management": {
"original_input_tokens": 70000
}
}
```
The response shows both the final token count after context management is applied (`input_tokens`) and the original token count before any clearing occurred (`original_input_tokens`).
## Using with the Memory Tool
Context editing can be combined with the [memory tool](/docs/en/agents-and-tools/tool-use/memory-tool). When your conversation context approaches the configured clearing threshold, Claude receives an automatic warning to preserve important information. This enables Claude to save tool results or context to its memory files before they're cleared from the conversation history.
This combination allows you to:
- **Preserve important context**: Claude can write essential information from tool results to memory files before those results are cleared
- **Maintain long-running workflows**: Enable agentic workflows that would otherwise exceed context limits by offloading information to persistent storage
- **Access information on demand**: Claude can look up previously cleared information from memory files when needed, rather than keeping everything in the active context window
For example, in a file editing workflow where Claude performs many operations, Claude can summarize completed changes to memory files as the context grows. When tool results are cleared, Claude retains access to that information through its memory system and can continue working effectively.
To use both features together, enable them in your API request:
<CodeGroup>
```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: Hello
tools:
- type: memory_20250818
name: memory
context_management:
edits:
- type: clear_tool_uses_20250919
YAML
```
```python Python nocheck
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
messages=[...],
tools=[
{"type": "memory_20250818", "name": "memory"},
# Your other tools
],
betas=["context-management-2025-06-27"],
context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)
```
```typescript TypeScript nocheck 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: [
// ...
],
tools: [
{
type: "memory_20250818",
name: "memory"
}
// Your other tools
],
betas: ["context-management-2025-06-27"],
context_management: {
edits: [{ type: "clear_tool_uses_20250919" }]
}
});
```
```csharp C# nocheck
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
{
Model = Model.ClaudeOpus4_7,
MaxTokens = 4096,
Messages = [],
Tools = [
new() {
Type = "memory_20250818",
Name = "memory"
}
],
Betas = ["context-management-2025-06-27"],
ContextManagement = new BetaContextManagementConfig() {
Edits = [
new BetaClearToolUses20250919Edit()
]
}
};
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: 4096,
Messages: []anthropic.BetaMessageParam{},
Tools: []anthropic.BetaToolUnionParam{
{OfMemoryTool20250818: &anthropic.BetaMemoryTool20250818Param{}},
},
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaContextManagement2025_06_27},
ContextManagement: anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfClearToolUses20250919: &anthropic.BetaClearToolUses20250919EditParam{}},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
}
```
```java Java nocheck 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.BetaMemoryTool20250818;
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 Main {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(4096L)
.addTool(BetaMemoryTool20250818.builder().build())
.addBeta(AnthropicBeta.CONTEXT_MANAGEMENT_2025_06_27)
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaClearToolUses20250919Edit.builder().build())
.build())
.build();
BetaMessage response = client.beta().messages().create(params);
System.out.println(response);
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: [],
model: 'claude-opus-4-7',
betas: ['context-management-2025-06-27'],
tools: [
[
'type' => 'memory_20250818',
'name' => 'memory'
]
],
contextManagement: [
'edits' => [
['type' => 'clear_tool_uses_20250919']
]
],
);
echo $response;
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
response = client.beta.messages.create(
model: "claude-opus-4-7",
max_tokens: 4096,
messages: [
# ...
],
tools: [
{
type: "memory_20250818",
name: "memory"
}
],
betas: ["context-management-2025-06-27"],
context_management: {
edits: [
{ type: "clear_tool_uses_20250919" }
]
}
)
puts response
```
</CodeGroup>
For the full memory tool reference including commands and examples, see [Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool).
## Client-side compaction (SDK)
<Warning>
**Anthropic recommends server-side compaction over SDK compaction.** [Server-side compaction](/docs/en/build-with-claude/compaction) handles context management automatically with less integration complexity, better token usage calculation, and no client-side limitations. Use SDK compaction only if you specifically need client-side control over the summarization process.
</Warning>
<Note>
Compaction is available in the [Python, TypeScript, and Ruby SDKs](/docs/en/api/client-sdks) when using the [`tool_runner` method](/docs/en/agents-and-tools/tool-use/tool-runner).
</Note>
Compaction is an SDK feature that automatically manages conversation context by generating summaries when token usage grows too large. Unlike server-side context editing strategies that clear content, compaction instructs Claude to summarize the conversation history, then replaces the full history with that summary. This allows Claude to continue working on long-running tasks that would otherwise exceed the [context window](/docs/en/build-with-claude/context-windows).
### How compaction works
When compaction is enabled, the SDK monitors token usage after each model response:
1. **Threshold check:** The SDK calculates total tokens as `input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens`.
2. **Summary generation:** When the threshold is exceeded, a summary prompt is injected as a user turn, and Claude generates a structured summary wrapped in `<summary></summary>` tags.
3. **Context replacement:** The SDK extracts the summary and replaces the entire message history with it.
4. **Continuation:** The conversation resumes from the summary, with Claude picking up where it left off.
### Using compaction
Add `compaction_control` to your `tool_runner` call to enable automatic summarization when token usage exceeds the threshold.
<Tabs>
<Tab title="CLI">
<Note>
The CLI does not include a `tool_runner` helper. Use [server-side compaction](/docs/en/build-with-claude/compaction) instead, which handles compaction on Anthropic's servers without SDK-side integration.
</Note>
</Tab>
<Tab title="Python">
```python Python hidelines={1..10}
import anthropic
from anthropic import beta_tool
@beta_tool
def read_file(path: str) -> str:
"""Read the contents of a file."""
return "file contents..."
client = anthropic.Anthropic()
runner = client.beta.messages.tool_runner(
model="claude-opus-4-7",
max_tokens=1024,
tools=[read_file],
messages=[{"role": "user", "content": "What's in config.json?"}],
compaction_control={"enabled": True, "context_token_threshold": 100000},
)
for message in runner:
print(f"Tokens used: {message.usage.input_tokens}")
```
</Tab>
<Tab title="TypeScript">
```typescript TypeScript hidelines={1..15,-3..}
import Anthropic from "@anthropic-ai/sdk";
import { betaTool } from "@anthropic-ai/sdk/helpers/beta/json-schema";
const readFile = betaTool({
name: "read_file",
description: "Read the contents of a file",
inputSchema: {
type: "object",
properties: { path: { type: "string" } },
required: ["path"]
},
run: async () => "file contents..."
});
async function main() {
const client = new Anthropic();
const runner = client.beta.messages.toolRunner({
model: "claude-opus-4-7",
max_tokens: 1024,
tools: [readFile],
messages: [{ role: "user", content: "What's in config.json?" }],
compactionControl: { enabled: true, contextTokenThreshold: 100000 }
});
for await (const message of runner) {
console.log(`Tokens used: ${message.usage.input_tokens}`);
}
}
main();
```
</Tab>
<Tab title="C#">
<Note>
The C# SDK does not include a `tool_runner` helper. Use [server-side compaction](/docs/en/build-with-claude/compaction) instead, which handles compaction on Anthropic's servers without SDK-side integration.
</Note>
</Tab>
<Tab title="Go">
<Note>
The Go SDK's `tool_runner` does not support `compaction_control`. Use [server-side compaction](/docs/en/build-with-claude/compaction) instead, which handles compaction on Anthropic's servers without SDK-side integration.
</Note>
</Tab>
<Tab title="Java">
<Note>
The Java SDK's `tool_runner` does not support `compaction_control`. Use [server-side compaction](/docs/en/build-with-claude/compaction) instead, which handles compaction on Anthropic's servers without SDK-side integration.
</Note>
</Tab>
<Tab title="PHP">
<Note>
The PHP SDK's `tool_runner` does not support `compaction_control`. Use [server-side compaction](/docs/en/build-with-claude/compaction) instead, which handles compaction on Anthropic's servers without SDK-side integration.
</Note>
</Tab>
<Tab title="Ruby">
```ruby Ruby hidelines={1..15}
require "anthropic"
class ReadFileInput < Anthropic::BaseModel
required :path, String, doc: "Path to the file"
end
class ReadFile < Anthropic::BaseTool
doc "Read the contents of a file"
input_schema ReadFileInput
def call(input)
"file contents..."
end
end
client = Anthropic::Client.new
runner = client.beta.messages.tool_runner(
model: "claude-opus-4-7",
max_tokens: 1024,
tools: [ReadFile.new],
messages: [{ role: "user", content: "What's in config.json?" }],
compaction_control: { enabled: true, context_token_threshold: 100000 }
)
runner.each_message do |message|
puts "Tokens used: #{message.usage.input_tokens}"
end
```
</Tab>
</Tabs>
#### What happens during compaction
As the conversation grows, the message history accumulates:
**Before compaction (approaching 100k tokens):**
```json
[
{ "role": "user", "content": "Analyze all files and write a report..." },
{ "role": "assistant", "content": "I'll help. Let me start by reading..." },
{
"role": "user",
"content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
},
{ "role": "assistant", "content": "Based on file1.txt, I see..." },
{
"role": "user",
"content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
},
{ "role": "assistant", "content": "After analyzing file2.txt..." }
// ... 50 more exchanges like this ...
]
```
When tokens exceed the threshold, the SDK injects a summary request and Claude generates a summary. The entire history is then replaced:
**After compaction (back to ~2-3k tokens):**
```json
[
{
"role": "assistant",
"content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
}
]
```
Claude continues working from this summary as if it were the original conversation history.
### Configuration options
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `enabled` | boolean | Yes | - | Whether to enable automatic compaction |
| `context_token_threshold` | number | No | 100,000 | Token count at which compaction triggers |
| `model` | string | No | Same as main model | Model to use for generating summaries |
| `summary_prompt` | string | No | See below | Custom prompt for summary generation |
#### Choosing a token threshold
The threshold determines when compaction occurs. A lower threshold means more frequent compactions with smaller context windows. A higher threshold allows more context but risks hitting limits.
<CodeGroup>
```python Python
# More frequent compaction for memory-constrained scenarios
compaction_control = {"enabled": True, "context_token_threshold": 50000}
# Less frequent compaction when you need more context
compaction_control = {"enabled": True, "context_token_threshold": 150000}
```
```typescript TypeScript hidelines={1,7..9,-1}
const _ = {
// More frequent compaction for memory-constrained scenarios
compactionControl: {
enabled: true,
contextTokenThreshold: 50000
}
};
const __ = {
// Less frequent compaction when you need more context
compactionControl: {
enabled: true,
contextTokenThreshold: 150000
}
};
```
</CodeGroup>
#### Using a different model for summaries
You can use a faster or cheaper model for generating summaries:
<CodeGroup>
```python Python
compaction_control = {
"enabled": True,
"context_token_threshold": 100000,
"model": "claude-haiku-4-5",
}
```
```typescript TypeScript hidelines={1,-1}
const _ = {
compactionControl: {
enabled: true,
contextTokenThreshold: 100000,
model: "claude-haiku-4-5"
}
};
```
</CodeGroup>
#### Custom summary prompts
You can provide a custom prompt for domain-specific needs. Your prompt should instruct Claude to wrap its summary in `<summary></summary>` tags.
<CodeGroup>
```python Python
compaction_control = {
"enabled": True,
"context_token_threshold": 100000,
"summary_prompt": """Summarize the research conducted so far, including:
- Sources consulted and key findings
- Questions answered and remaining unknowns
- Recommended next steps
Wrap your summary in <summary></summary> tags.""",
}
```
```typescript TypeScript hidelines={1,-1}
const _ = {
compactionControl: {
enabled: true,
contextTokenThreshold: 100000,
summaryPrompt: `Summarize the research conducted so far, including:
- Sources consulted and key findings
- Questions answered and remaining unknowns
- Recommended next steps
Wrap your summary in <summary></summary> tags.`
}
};
```
</CodeGroup>
### Default summary prompt
The built-in summary prompt instructs Claude to create a structured continuation summary including:
1. **Task Overview:** The user's core request, success criteria, and constraints.
2. **Current State:** What has been completed, files modified, and artifacts produced.
3. **Important Discoveries:** Technical constraints, decisions made, errors resolved, and failed approaches.
4. **Next Steps:** Specific actions needed, blockers, and priority order.
5. **Context to Preserve:** User preferences, domain-specific details, and commitments made.
This structure enables Claude to resume work efficiently without losing important context or repeating mistakes.
<section title="View full default prompt">
```text
You have been working on the task described above but have not yet completed it. Write a continuation summary that will allow you (or another instance of yourself) to resume work efficiently in a future context window where the conversation history will be replaced with this summary. Your summary should be structured, concise, and actionable. Include:
1. Task Overview
The user's core request and success criteria
Any clarifications or constraints they specified
2. Current State
What has been completed so far
Files created, modified, or analyzed (with paths if relevant)
Key outputs or artifacts produced
3. Important Discoveries
Technical constraints or requirements uncovered
Decisions made and their rationale
Errors encountered and how they were resolved
What approaches were tried that didn't work (and why)
4. Next Steps
Specific actions needed to complete the task
Any blockers or open questions to resolve
Priority order if multiple steps remain
5. Context to Preserve
User preferences or style requirements
Domain-specific details that aren't obvious
Any promises made to the user
Be concise but complete—err on the side of including information that would prevent duplicate work or repeated mistakes. Write in a way that enables immediate resumption of the task.
Wrap your summary in <summary></summary> tags.
```
</section>
### Limitations
#### Server-side tools
<Warning>
Compaction requires special consideration when using server-side tools such as [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).
</Warning>
When using server-side tools, the SDK may incorrectly calculate token usage, causing compaction to trigger at the wrong time.
For example, after a web search operation, the API response might show:
```json Output
{
"usage": {
"input_tokens": 63000,
"cache_read_input_tokens": 270000,
"output_tokens": 1400
}
}
```
The SDK calculates total usage as 63,000 + 270,000 = 333,000 tokens. However, the `cache_read_input_tokens` value includes accumulated reads from multiple internal API calls made by the server-side tool, not your actual conversation context. Your real context length might only be the 63,000 `input_tokens`, but the SDK sees 333k and triggers compaction prematurely.
**Workarounds:**
- Use the [token counting](/docs/en/build-with-claude/token-counting) endpoint to get accurate context length
- Avoid compaction when using server-side tools extensively
#### Tool use edge cases
When the SDK triggers compaction while a tool use response is pending, it removes the tool use block from the message history before generating the summary. Claude will re-issue the tool call after resuming from the summary if still needed.
### Monitoring compaction
Understanding when compaction triggers helps you tune thresholds and verify expected behavior.
<Tabs>
<Tab title="Python">
The Python SDK logs compaction events at the INFO level. Enable the `anthropic.lib.tools` logger:
```python Python
import logging
logging.basicConfig(level=logging.INFO)
logging.getLogger("anthropic.lib.tools").setLevel(logging.INFO)
# Logs will show:
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500
```
</Tab>
<Tab title="TypeScript">
The TypeScript SDK's `toolRunner` supports compaction but does not log events. Detect compaction by watching `runner.params.messages.length` shrink between turns:
```typescript TypeScript hidelines={1..25,-3..}
import Anthropic from "@anthropic-ai/sdk";
import { betaTool } from "@anthropic-ai/sdk/helpers/beta/json-schema";
const readFile = betaTool({
name: "read_file",
description: "Read the contents of a file",
inputSchema: {
type: "object",
properties: { path: { type: "string" } },
required: ["path"]
},
run: async () => "file contents..."
});
async function main() {
const client = new Anthropic();
const runner = client.beta.messages.toolRunner({
model: "claude-opus-4-7",
max_tokens: 1024,
tools: [readFile],
messages: [{ role: "user", content: "What's in config.json?" }],
compactionControl: { enabled: true, contextTokenThreshold: 100000 }
});
let prevMsgCount = 0;
for await (const message of runner) {
const currMsgCount = runner.params.messages.length;
if (currMsgCount < prevMsgCount) {
console.log(`Compaction occurred: ${prevMsgCount} -> ${currMsgCount} messages`);
console.log(`Input tokens after compaction: ${message.usage.input_tokens}`);
}
prevMsgCount = currMsgCount;
}
}
main();
```
</Tab>
<Tab title="C#">
<Note>
The C# SDK does not include a `tool_runner` helper. Use [server-side compaction](/docs/en/build-with-claude/compaction) instead.
</Note>
</Tab>
<Tab title="Go">
<Note>
The Go SDK's `tool_runner` does not support `compaction_control`. Use [server-side compaction](/docs/en/build-with-claude/compaction) instead.
</Note>
</Tab>
<Tab title="Java">
<Note>
The Java SDK's `tool_runner` does not support `compaction_control`. Use [server-side compaction](/docs/en/build-with-claude/compaction) instead.
</Note>
</Tab>
<Tab title="PHP">
<Note>
The PHP SDK's `tool_runner` does not support `compaction_control`. Use [server-side compaction](/docs/en/build-with-claude/compaction) instead.
</Note>
</Tab>
<Tab title="Ruby">
The Ruby SDK supports an `on_compact:` callback that fires when compaction occurs. Add it to your `compaction_control` configuration:
```ruby Ruby hidelines={1..15}
require "anthropic"
class ReadFileInput < Anthropic::BaseModel
required :path, String, doc: "Path to the file"
end
class ReadFile < Anthropic::BaseTool
doc "Read the contents of a file"
input_schema ReadFileInput
def call(input)
"file contents..."
end
end
client = Anthropic::Client.new
runner = client.beta.messages.tool_runner(
model: "claude-opus-4-7",
max_tokens: 1024,
tools: [ReadFile.new],
messages: [{ role: "user", content: "What's in config.json?" }],
compaction_control: {
enabled: true,
context_token_threshold: 100000,
on_compact: ->(tokens_before, tokens_after) do
puts "Compaction occurred: #{tokens_before} -> #{tokens_after} tokens"
end
}
)
runner.each_message do |message|
puts "Tokens: #{message.usage.input_tokens}"
end
```
</Tab>
</Tabs>
### When to use compaction
**Good use cases:**
- Long-running agent tasks that process many files or data sources
- Research workflows that accumulate large amounts of information
- Multi-step tasks with clear, measurable progress
- Tasks that produce artifacts (files, reports) that persist outside the conversation
**Less ideal use cases:**
- Tasks requiring precise recall of early conversation details
- Workflows using server-side tools extensively
- Tasks that need to maintain exact state across many variables
---
## Guides/build-with-claude-context-windows-13ca780d1d.md
# Context windows
---
<Note>
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.
</Note>
As conversations grow, you'll eventually approach context window limits. This guide explains how context windows work and introduces strategies for managing them effectively.
For long-running conversations and agentic workflows, [server-side compaction](/docs/en/build-with-claude/compaction) is the primary strategy for context management. For more specialized needs, [context editing](/docs/en/build-with-claude/context-editing) offers additional strategies like tool result clearing and thinking block clearing.
## Understanding the context window
The "context window" refers to all the text a language model can reference when generating a response, including the response itself. This is different from the large corpus of data the language model was trained on, and instead represents a "working memory" for the model. A larger context window allows the model to handle more complex and lengthy prompts, but more context isn't automatically better. As token count grows, accuracy and recall degrade, a phenomenon known as *context rot*. This makes curating what's in context just as important as how much space is available.
Claude achieves state-of-the-art results on long-context retrieval benchmarks like [MRCR](https://arxiv.org/abs/2501.03276) and [GraphWalks](https://arxiv.org/abs/2412.04360), but these gains depend on what's in context, not just how much fits.
<Tip>
For a deep dive into why long contexts degrade and how to engineer around it, see [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents).
</Tip>
The diagram below illustrates the standard context window behavior for API requests<sup>1</sup>:
_<sup>1</sup>For chat interfaces, such as for [claude.ai](https://claude.ai/), context windows can also be set up on a rolling "first in, first out" system._
* **Progressive token accumulation:** As the conversation advances through turns, each user message and assistant response accumulates within the context window. Previous turns are preserved completely.
* **Linear growth pattern:** The context usage grows linearly with each turn, with previous turns preserved completely.
* **Context window capacity:** The total available context window (up to 1M tokens) represents the maximum capacity for storing conversation history and generating new output from Claude.
* **Input-output flow:** Each turn consists of:
- **Input phase:** Contains all previous conversation history plus the current user message
- **Output phase:** Generates a text response that becomes part of a future input
## The context window with extended thinking
When using [extended thinking](/docs/en/build-with-claude/extended-thinking), all input and output tokens, including the tokens used for thinking, count toward the context window limit, with a few nuances in multi-turn situations.
The thinking budget tokens are a subset of your `max_tokens` parameter, are billed as output tokens, and count towards rate limits. With [adaptive thinking](/docs/en/build-with-claude/adaptive-thinking), Claude dynamically decides its thinking allocation, so actual thinking token usage may vary per request.
However, previous thinking blocks are automatically stripped from the context window calculation by the Claude API and are not part of the conversation history that the model "sees" for subsequent turns, preserving token capacity for actual conversation content.
The diagram below demonstrates the specialized token management when extended thinking is enabled:
* **Stripping extended thinking:** Extended thinking blocks (shown in dark gray) are generated during each turn's output phase, **but are not carried forward as input tokens for subsequent turns**. You do not need to strip the thinking blocks yourself. The Claude API automatically does this for you if you pass them back.
* **Technical implementation details:**
- The API automatically excludes thinking blocks from previous turns when you pass them back as part of the conversation history.
- Extended thinking tokens are billed as output tokens only once, during their generation.
- The effective context window calculation becomes: `context_window = (input_tokens - previous_thinking_tokens) + current_turn_tokens`.
- Thinking tokens include `thinking` blocks.
This architecture is token efficient and allows for extensive reasoning without token waste, as thinking blocks can be substantial in length.
<Note>
You can read more about the context window and extended thinking in the [extended thinking guide](/docs/en/build-with-claude/extended-thinking).
</Note>
## The context window with extended thinking and tool use
The diagram below illustrates the context window token management when combining extended thinking with tool use:
<Steps>
<Step title="First turn architecture">
- **Input components:** Tools configuration and user message
- **Output components:** Extended thinking + text response + tool use request
- **Token calculation:** All input and output components count toward the context window, and all output components are billed as output tokens.
</Step>
<Step title="Tool result handling (turn 2)">
- **Input components:** Every block in the first turn as well as the `tool_result`. The extended thinking block **must** be returned with the corresponding tool results. This is the only case wherein you **have to** return thinking blocks.
- **Output components:** After tool results have been passed back to Claude, Claude will respond with only text (no additional extended thinking until the next `user` message).
- **Token calculation:** All input and output components count toward the context window, and all output components are billed as output tokens.
</Step>
<Step title="Third Step">
- **Input components:** All inputs and the output from the previous turn is carried forward with the exception of the thinking block, which can be dropped now that Claude has completed the entire tool use cycle. The API will automatically strip the thinking block for you if you pass it back, or you can feel free to strip it yourself at this stage. This is also where you would add the next `User` turn.
- **Output components:** Since there is a new `User` turn outside of the tool use cycle, Claude generates a new extended thinking block and continues from there.
- **Token calculation:** Previous thinking tokens are automatically stripped from context window calculations. All other previous blocks still count as part of the token window, and the thinking block in the current `Assistant` turn counts as part of the context window.
</Step>
</Steps>
* **Considerations for tool use with extended thinking:**
- When posting tool results, the entire unmodified thinking block that accompanies that specific tool request (including signature portions) must be included.
- The effective context window calculation for extended thinking with tool use becomes: `context_window = input_tokens + current_turn_tokens`.
- The system uses cryptographic signatures to verify thinking block authenticity. Failing to preserve thinking blocks during tool use can break Claude's reasoning continuity. Thus, if you modify thinking blocks, the API returns an error.
<Note>
Claude 4 models support [interleaved thinking](/docs/en/build-with-claude/extended-thinking#interleaved-thinking), which enables Claude to think between tool calls and make more sophisticated reasoning after receiving tool results.
Claude Sonnet 3.7 does not support interleaved thinking, so there is no interleaving of extended thinking and tool calls without a non-`tool_result` user turn in between.
For more information about using tools with extended thinking, see the [extended thinking guide](/docs/en/build-with-claude/extended-thinking#extended-thinking-with-tool-use).
</Note>
[Claude Mythos Preview](https://anthropic.com/glasswing), Claude Opus 4.7, Claude Opus 4.6, and Claude Sonnet 4.6 have a 1M-token context window. Other Claude models, including Claude Sonnet 4.5 and Sonnet 4 (deprecated), have a 200k-token context window.
A single request can include up to 600 images or PDF pages (100 for models with a 200k-token context window). When sending many images or large documents, you may approach [request size limits](/docs/en/api/overview#request-size-limits) before the token limit.
## Context awareness in Claude Sonnet 4.6, Sonnet 4.5, and Haiku 4.5
Claude Sonnet 4.6, Claude Sonnet 4.5, and Claude Haiku 4.5 feature **context awareness**. This capability lets these models track their remaining context window (i.e. "token budget") throughout a conversation. This enables Claude to execute tasks and manage context more effectively by understanding how much space it has to work. Claude is trained to use this context precisely, persisting in the task until the very end rather than guessing how many tokens remain. For a model, lacking context awareness is like competing in a cooking show without a clock. Claude 4.5+ models change this by explicitly informing the model about its remaining context, so it can take maximum advantage of the available tokens.
**How it works:**
At the start of a conversation, Claude receives information about its total context window:
```xml
<budget:token_budget>1000000</budget:token_budget>
```
The budget is set to 1M tokens (200k for models with a smaller context window).
After each tool call, Claude receives an update on remaining capacity:
```xml
<system_warning>Token usage: 35000/1000000; 965000 remaining</system_warning>
```
This awareness helps Claude determine how much capacity remains for work and enables more effective execution on long-running tasks. Image tokens are included in these budgets.
**Benefits:**
Context awareness is particularly valuable for:
- Long-running agent sessions that require sustained focus
- Multi-context-window workflows where state transitions matter
- Complex tasks requiring careful token management
<Tip>
For agents that span multiple sessions, design your state artifacts so that context recovery is fast when a new session starts. The [memory tool's multi-session pattern](/docs/en/agents-and-tools/tool-use/memory-tool#multi-session-software-development-pattern) walks through a concrete approach. See also [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents).
</Tip>
For prompting guidance on leveraging context awareness, see the [prompting best practices guide](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#context-awareness-and-multi-window-workflows).
## Managing context with compaction
If your conversations regularly approach context window limits, [server-side compaction](/docs/en/build-with-claude/compaction) is the recommended approach. Compaction provides server-side summarization that automatically condenses earlier parts of a conversation, enabling long-running conversations beyond context limits with minimal integration work. It is currently available in beta for Claude Opus 4.7, Claude Opus 4.6, and Claude Sonnet 4.6.
For more specialized needs, [context editing](/docs/en/build-with-claude/context-editing) offers additional strategies:
- **Tool result clearing** - Clear old tool results in agentic workflows
- **Thinking block clearing** - Manage thinking blocks with extended thinking
## Context window management with newer Claude models
Newer Claude models (starting with Claude Sonnet 3.7) return a validation error when prompt and output tokens exceed the context window, rather than silently truncating. This change provides more predictable behavior but requires more careful token management.
Use the [token counting API](/docs/en/build-with-claude/token-counting) to estimate token usage before sending messages to Claude. This helps you plan and stay within context window limits.
See the [model comparison](/docs/en/about-claude/models/overview#latest-models-comparison) table for a list of context window sizes by model.
## Next steps
<CardGroup cols={2}>
<Card title="Compaction" icon="compress" href="/docs/en/build-with-claude/compaction">
The recommended strategy for managing context in long-running conversations.
</Card>
<Card title="Context editing" icon="pen" href="/docs/en/build-with-claude/context-editing">
Fine-grained strategies like tool result clearing and thinking block clearing.
</Card>
<Card title="Model comparison table" icon="scales" href="/docs/en/about-claude/models/overview#latest-models-comparison">
See the model comparison table for a list of context window sizes and input / output token pricing by model.
</Card>
<Card title="Extended thinking overview" icon="settings" href="/docs/en/build-with-claude/extended-thinking">
Learn more about how extended thinking works and how to implement it alongside other features such as tool use and prompt caching.
</Card>
</CardGroup>
---
## Guides/build-with-claude-context-windows.md
# Context windows
As conversations grow, you'll eventually approach context window limits. This guide explains how context windows work and introduces strategies for managing them effectively.
For long-running conversations and agentic workflows, [server-side compaction](/docs/en/build-with-claude/compaction) is the primary strategy for context management. For more specialized needs, [context editing](/docs/en/build-with-claude/context-editing) offers additional strategies like tool result clearing and thinking block clearing.
Understanding the context window
The "context window" refers to all the text a language model can reference when generating a response, including the response itself. This is different from the large corpus of data the language model was trained on, and instead represents a "working memory" for the model. A larger context window allows the model to handle more complex and lengthy prompts, but more context isn't automatically better. As token count grows, accuracy and recall degrade, a phenomenon known as *context rot*. This makes curating what's in context just as important as how much space is available.
Claude achieves state-of-the-art results on long-context retrieval benchmarks like [MRCR](https://arxiv.org/abs/2501.03276) and [GraphWalks](https://arxiv.org/abs/2412.04360), but these gains depend on what's in context, not just how much fits.
For a deep dive into why long contexts degrade and how to engineer around it, see [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents).
The diagram below illustrates the standard context window behavior for API requests¹:
*¹For chat interfaces, such as for [claude.ai](https://claude.ai/), context windows can also be set up on a rolling "first in, first out" system.*
- **Progressive token accumulation:** As the conversation advances through turns, each user message and assistant response accumulates within the context window. Previous turns are preserved completely.
- **Linear growth pattern:** The context usage grows linearly with each turn, with previous turns preserved completely.
- **Context window capacity:** The total available context window (up to 1M tokens) represents the maximum capacity for storing conversation history and generating new output from Claude.
- **Input-output flow:** Each turn consists of:
- **Input phase:** Contains all previous conversation history plus the current user message
- **Output phase:** Generates a text response that becomes part of a future input
The context window with extended thinking
When using [extended thinking](/docs/en/build-with-claude/extended-thinking), all input and output tokens, including the tokens used for thinking, count toward the context window limit, with a few nuances in multi-turn situations.
The thinking budget tokens are a subset of your `max_tokens` parameter, are billed as output tokens, and count towards rate limits. With [adaptive thinking](/docs/en/build-with-claude/adaptive-thinking), Claude dynamically decides its thinking allocation, so actual thinking token usage may vary per request.
However, previous thinking blocks are automatically stripped from the context window calculation by the Claude API and are not part of the conversation history that the model "sees" for subsequent turns, preserving token capacity for actual conversation content.
The diagram below demonstrates the specialized token management when extended thinking is enabled:
- **Stripping extended thinking:** Extended thinking blocks (shown in dark gray) are generated during each turn's output phase, **but are not carried forward as input tokens for subsequent turns**. You do not need to strip the thinking blocks yourself. The Claude API automatically does this for you if you pass them back.
- **Technical implementation details:**
- The API automatically excludes thinking blocks from previous turns when you pass them back as part of the conversation history.
- Extended thinking tokens are billed as output tokens only once, during their generation.
- The effective context window calculation becomes: `context_window = (input_tokens - previous_thinking_tokens) + current_turn_tokens`.
- Thinking tokens include `thinking` blocks.
This architecture is token efficient and allows for extensive reasoning without token waste, as thinking blocks can be substantial in length.
You can read more about the context window and extended thinking in the [extended thinking guide](/docs/en/build-with-claude/extended-thinking).
The context window with extended thinking and tool use
The diagram below illustrates the context window token management when combining extended thinking with tool use:
1. 1
First turn architecture
- **Input components:** Tools configuration and user message
- **Output components:** Extended thinking + text response + tool use request
- **Token calculation:** All input and output components count toward the context window, and all output components are billed as output tokens.
2. 2
Tool result handling (turn 2)
- **Input components:** Every block in the first turn as well as the `tool_result`. The extended thinking block **must** be returned with the corresponding tool results. This is the only case wherein you **have to** return thinking blocks.
- **Output components:** After tool results have been passed back to Claude, Claude will respond with only text (no additional extended thinking until the next `user` message).
- **Token calculation:** All input and output components count toward the context window, and all output components are billed as output tokens.
3. 3
Third Step
- **Input components:** All inputs and the output from the previous turn is carried forward with the exception of the thinking block, which can be dropped now that Claude has completed the entire tool use cycle. The API will automatically strip the thinking block for you if you pass it back, or you can feel free to strip it yourself at this stage. This is also where you would add the next `User` turn.
- **Output components:** Since there is a new `User` turn outside of the tool use cycle, Claude generates a new extended thinking block and continues from there.
- **Token calculation:** Previous thinking tokens are automatically stripped from context window calculations. All other previous blocks still count as part of the token window, and the thinking block in the current `Assistant` turn counts as part of the context window.
- **Considerations for tool use with extended thinking:**
- When posting tool results, the entire unmodified thinking block that accompanies that specific tool request (including signature portions) must be included.
- The effective context window calculation for extended thinking with tool use becomes: `context_window = input_tokens + current_turn_tokens`.
- The system uses cryptographic signatures to verify thinking block authenticity. Failing to preserve thinking blocks during tool use can break Claude's reasoning continuity. Thus, if you modify thinking blocks, the API returns an error.
Claude 4 models support [interleaved thinking](/docs/en/build-with-claude/extended-thinking#interleaved-thinking), which enables Claude to think between tool calls and make more sophisticated reasoning after receiving tool results.
Claude Sonnet 3.7 does not support interleaved thinking, so there is no interleaving of extended thinking and tool calls without a non-`tool_result` user turn in between.
For more information about using tools with extended thinking, see the [extended thinking guide](/docs/en/build-with-claude/extended-thinking#extended-thinking-with-tool-use).
Claude Opus 4.6 and Sonnet 4.6 have a 1M-token context window.
Claude Sonnet 4.5 and Sonnet 4 require the `context-1m-2025-08-07` [beta header](/docs/en/api/beta-headers) for requests beyond 200k tokens (available to organizations in [usage tier](/docs/en/api/rate-limits) 4 and those with custom rate limits). Other Claude models have a 200k-token context window.
A single request can include up to 600 images or PDF pages (100 for models with a 200k-token context window). When sending many images or large documents, you may approach [request size limits](/docs/en/api/overview#request-size-limits) before the token limit.
Context awareness in Claude Sonnet 4.6, Sonnet 4.5, and Haiku 4.5
Claude Sonnet 4.6, Claude Sonnet 4.5, and Claude Haiku 4.5 feature **context awareness**. This capability lets these models track their remaining context window (i.e. "token budget") throughout a conversation. This enables Claude to execute tasks and manage context more effectively by understanding how much space it has to work. Claude is trained to use this context precisely, persisting in the task until the very end rather than guessing how many tokens remain. For a model, lacking context awareness is like competing in a cooking show without a clock. Claude 4.5+ models change this by explicitly informing the model about its remaining context, so it can take maximum advantage of the available tokens.
**How it works:**
At the start of a conversation, Claude receives information about its total context window:
```python
<budget:token_budget>1000000</budget:token_budget>
```
The budget is set to 1M tokens (200k for models with a smaller context window).
After each tool call, Claude receives an update on remaining capacity:
```python
<system_warning>Token usage: 35000/1000000; 965000 remaining</system_warning>
```
This awareness helps Claude determine how much capacity remains for work and enables more effective execution on long-running tasks. Image tokens are included in these budgets.
**Benefits:**
Context awareness is particularly valuable for:
- Long-running agent sessions that require sustained focus
- Multi-context-window workflows where state transitions matter
- Complex tasks requiring careful token management
For agents that span multiple sessions, design your state artifacts so that context recovery is fast when a new session starts. The [memory tool's multi-session pattern](/docs/en/agents-and-tools/tool-use/memory-tool#multi-session-software-development-pattern) walks through a concrete approach. See also [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents).
For prompting guidance on leveraging context awareness, see the [prompting best practices guide](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#context-awareness-and-multi-window-workflows).
Managing context with compaction
If your conversations regularly approach context window limits, [server-side compaction](/docs/en/build-with-claude/compaction) is the recommended approach. Compaction provides server-side summarization that automatically condenses earlier parts of a conversation, enabling long-running conversations beyond context limits with minimal integration work. It is currently available in beta for Claude Opus 4.6 and Sonnet 4.6.
For more specialized needs, [context editing](/docs/en/build-with-claude/context-editing) offers additional strategies:
- **Tool result clearing** - Clear old tool results in agentic workflows
- **Thinking block clearing** - Manage thinking blocks with extended thinking
Context window management with newer Claude models
Newer Claude models (starting with Claude Sonnet 3.7) return a validation error when prompt and output tokens exceed the context window, rather than silently truncating. This change provides more predictable behavior but requires more careful token management.
Use the [token counting API](/docs/en/build-with-claude/token-counting) to estimate token usage before sending messages to Claude. This helps you plan and stay within context window limits.
See the [model comparison](/docs/en/about-claude/models/overview#latest-models-comparison) table for a list of context window sizes by model.
Next steps
Compaction
The recommended strategy for managing context in long-running conversations.
Context editing
Fine-grained strategies like tool result clearing and thinking block clearing.
Model comparison table
See the model comparison table for a list of context window sizes and input / output token pricing by model.
Extended thinking overview
Learn more about how extended thinking works and how to implement it alongside other features such as tool use and prompt caching.
---
## Guides/build-with-claude-data-residency-6c8e324ea6.md
# Data residency
Manage where model inference runs and where data is stored with geographic controls.
---
<Note>
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.
</Note>
Data residency controls let you manage where your data is processed and stored. Two independent settings govern this:
- **Inference geo:** Controls where model inference runs, on a per-request basis. Set via the `inference_geo` API parameter or as a workspace default.
- **Workspace geo:** Controls where data is stored at rest and where endpoint processing (image transcoding, code execution, etc.) happens. Configured at the workspace level in the [Console](../Other/platform-claude-com.md).
## Inference geo
The `inference_geo` parameter controls where model inference runs for a specific API request. Add it to any `POST /v1/messages` call.
| Value | Description |
|:------|:------------|
| `"global"` | Default. Inference may run in any available geography for optimal performance and availability. |
| `"us"` | Inference runs only in US-based infrastructure. |
### API usage
<CodeGroup>
```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,
"inference_geo": "us",
"messages": [{
"role": "user",
"content": "Summarize the key points of this document."
}]
}'
```
```bash CLI
ant messages create \
--model claude-opus-4-7 \
--max-tokens 1024 \
--inference-geo us \
--message '{role: user, content: "Summarize the key points of this document."}' \
--transform '{content.0.text,usage.inference_geo}' --format yaml
```
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
inference_geo="us",
messages=[
{"role": "user", "content": "Summarize the key points of this document."}
],
)
print(response.content[0].text)
# Check where inference actually ran
print(f"Inference geo: {response.usage.inference_geo}")
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-4-7",
max_tokens: 1024,
inference_geo: "us",
messages: [
{
role: "user",
content: "Summarize the key points of this document."
}
]
});
const textBlock = response.content.find(
(block): block is Anthropic.TextBlock => block.type === "text"
);
console.log(textBlock?.text);
// Check where inference actually ran
console.log(`Inference geo: ${response.usage.inference_geo}`);
```
</CodeGroup>
### Response
The response `usage` object includes an `inference_geo` field indicating where inference ran:
```json Output
{
"usage": {
"input_tokens": 25,
"output_tokens": 150,
"inference_geo": "us"
}
}
```
### Model availability
The `inference_geo` parameter is supported on Claude Opus 4.6 and all subsequent models. Older models released before Opus 4.6 do not support the parameter. Requests with `inference_geo` on legacy models return a 400 error.
<Note>
The `inference_geo` parameter is only available on the Claude API (1P). On third-party platforms (AWS Bedrock, Google Vertex AI), the inference region is determined by the endpoint URL or inference profile, so `inference_geo` is not applicable. The `inference_geo` parameter is also not available via the [OpenAI SDK compatibility endpoint](/docs/en/api/openai-sdk).
</Note>
### Workspace-level restrictions
Workspace settings also support restricting which inference geos are available:
- **`allowed_inference_geos`:** Restricts which geos a workspace can use. If a request specifies an `inference_geo` not in this list, the API returns an error.
- **`default_inference_geo`:** Sets the fallback geo when `inference_geo` is omitted from a request. Individual requests can override this by setting `inference_geo` explicitly.
These settings can be configured through the Console or the [Admin API](/docs/en/build-with-claude/administration-api) under the `data_residency` field.
## Workspace geo
Workspace geo is set when you create a workspace and can't be changed afterwards. Currently, `"us"` is the only available workspace geo.
To set workspace geo, create a new workspace in the [Console](../Other/platform-claude-com.md):
1. Go to **Settings** > **Workspaces**.
2. Create a new workspace.
3. Select the workspace geo.
## Pricing
Data residency pricing varies by model generation:
- **Claude Opus 4.6 and newer:** US-only inference (`inference_geo: "us"`) is priced at 1.1x the standard rate across all token pricing categories (input tokens, output tokens, cache writes, and cache reads).
- **Global routing** (`inference_geo: "global"` or omitted): Standard pricing applies.
- **Older models:** Existing pricing is unchanged regardless of `inference_geo` settings.
This pricing applies to the Claude API (1P) only. Third-party platforms (AWS Bedrock, Google Vertex AI) have their own regional pricing. See the [pricing page](/docs/en/about-claude/pricing#data-residency-pricing) for details.
<Note>
If you use [Priority Tier](/docs/en/api/service-tiers), the 1.1x multiplier for US-only inference also affects how tokens are counted against your Priority Tier capacity. Each token consumed with `inference_geo: "us"` draws down 1.1 tokens from your committed TPM, consistent with how other pricing multipliers (such as prompt caching) affect burndown rates.
</Note>
## Batch API support
The `inference_geo` parameter is supported on the [Batch API](/docs/en/build-with-claude/batch-processing). Each request in a batch can specify its own `inference_geo` value.
## Migration from legacy opt-outs
If your organization previously opted out of global routing to keep inference in the US, your workspace has been automatically configured with `allowed_inference_geos: ["us"]` and `default_inference_geo: "us"`. No code changes are required. Your existing data residency requirements continue to be enforced through the new geo controls.
### What changed
The legacy opt-out was an organization-level setting that restricted all requests to US-based infrastructure. The new data residency controls replace this with two mechanisms:
- **Per-request control:** The `inference_geo` parameter lets you specify `"us"` or `"global"` on each API call, giving you request-level flexibility.
- **Workspace controls:** The `default_inference_geo` and `allowed_inference_geos` settings in the Console let you enforce geo policies across all keys in a workspace.
### What happened to your workspace
Your workspace was migrated automatically:
| Legacy setting | New equivalent |
|:---------------|:---------------|
| Global routing opt-out (US only) | `allowed_inference_geos: ["us"]`, `default_inference_geo: "us"` |
All API requests using keys from your workspace continue to run on US-based infrastructure. No action is needed to maintain your current behavior.
### If you want to use global routing
If your data residency requirements have changed and you want to take advantage of global routing for better performance and availability, update your workspace's inference geo settings to include `"global"` in the allowed geos and set `default_inference_geo` to `"global"`. See [Workspace-level restrictions](#workspace-level-restrictions) for details.
### Pricing impact
Legacy models are unaffected by this migration. For current pricing on newer models, see [Pricing](#pricing).
## Current limitations
- **Shared rate limits:** Rate limits are shared across all geos.
- **Inference geo:** Only `"us"` and `"global"` are available at launch. Additional regions will be added over time.
- **Workspace geo:** Only `"us"` is currently available. Workspace geo can't be changed after workspace creation.
## Next steps
<CardGroup>
<Card title="Pricing" icon="dollar-sign" href="/docs/en/about-claude/pricing#data-residency-pricing">
View data residency pricing details.
</Card>
<Card title="Workspaces" icon="building" href="/docs/en/build-with-claude/workspaces">
Learn about workspace configuration.
</Card>
<Card title="Usage and Cost API" icon="chart" href="/docs/en/build-with-claude/usage-cost-api">
Track usage and costs by data residency.
</Card>
</CardGroup>
---
## Guides/build-with-claude-effort-20d7f07a6f.md
# Effort
Control how many tokens Claude uses when responding with the effort parameter, trading off between response thoroughness and token efficiency.
---
<Note>
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.
</Note>
The effort parameter allows you to control how eager Claude is about spending tokens when responding to requests. This gives you the ability to trade off between response thoroughness and token efficiency, all with a single model. The effort parameter is generally available on all supported models with no beta header required.
<Note>
The effort parameter is supported by [Claude Mythos Preview](https://anthropic.com/glasswing), Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, and Claude Opus 4.5.
</Note>
<Tip>
For Claude Opus 4.6 and Sonnet 4.6, effort replaces `budget_tokens` as the recommended way to control thinking depth. Combine effort with [adaptive thinking](/docs/en/build-with-claude/adaptive-thinking) (`thinking: {type: "adaptive"}`) for the best experience. While `budget_tokens` is still accepted on Opus 4.6 and Sonnet 4.6, it is deprecated and will be removed in a future model release. At `high` (default) and `max` effort, Claude will almost always think. At lower effort levels, it may skip thinking for simpler problems.
</Tip>
## How effort works
By default, Claude uses high effort, spending as many tokens as needed for excellent results. You can raise the effort level to `max` for the absolute highest capability, or lower it to be more conservative with token usage, optimizing for speed and cost while accepting some reduction in capability.
<Tip>
Setting `effort` to `"high"` produces exactly the same behavior as omitting the `effort` parameter entirely.
</Tip>
The effort parameter affects **all tokens** in the response, including:
- Text responses and explanations
- Tool calls and function arguments
- Extended thinking (when enabled)
This approach has two major advantages:
1. It doesn't require thinking to be enabled in order to use it.
2. It can affect all token spend including tool calls. For example, lower effort would mean Claude makes fewer tool calls. This gives a much greater degree of control over efficiency.
### Effort levels
| Level | Description | Typical use case |
| -------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `max` | Absolute maximum capability with no constraints on token spending. Available on Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, and Claude Sonnet 4.6. | Tasks requiring the deepest possible reasoning and most thorough analysis |
| `xhigh` | Extended capability for long-horizon work. Available on Claude Opus 4.7. | Long-running agentic and coding tasks (over 30 minutes) with token budgets in the millions |
| `high` | High capability. Equivalent to not setting the parameter. | Complex reasoning, difficult coding problems, agentic tasks |
| `medium` | Balanced approach with moderate token savings. | Agentic tasks that require a balance of speed, cost, and performance |
| `low` | Most efficient. Significant token savings with some capability reduction. | Simpler tasks that need the best speed and lowest costs, such as subagents |
<Note>
Effort is a behavioral signal, not a strict token budget. At lower effort levels, Claude will still think on sufficiently difficult problems, but it will think less than it would at higher effort levels for the same problem.
</Note>
### Recommended effort levels for Sonnet 4.6
Sonnet 4.6 defaults to `high` effort. Explicitly set effort when using Sonnet 4.6 to avoid unexpected latency:
- **Medium effort** (recommended default): Best balance of speed, cost, and performance for most applications. Suitable for agentic coding, tool-heavy workflows, and code generation.
- **Low effort:** For high-volume or latency-sensitive workloads. Suitable for chat and non-coding use cases where faster turnaround is prioritized.
- **High effort:** For tasks requiring maximum intelligence from Sonnet 4.6.
- **Max effort:** For tasks requiring the absolute highest capability with no constraints on token spending.
### Recommended effort levels for Claude Opus 4.7
**Start with `xhigh` for coding and agentic use cases**, and use `high` as the minimum for most intelligence-sensitive workloads. Step down to `medium` for cost-sensitive workloads, or up to `max` only when your evals show measurable headroom at `xhigh`.
The API default is `high`. To use `xhigh`, set `effort` explicitly; the value you pass overrides the default.
| Effort | Guidance for Claude Opus 4.7 |
|--------|------------------------------|
| `low` | Efficient, but best for short, scoped tasks. Pair `low` with explicit checklists if your task has multiple sections. |
| `medium` | The drop-in for the average workflow where you want good results while reducing costs. |
| `high` | Advanced use cases that still need a balance of intelligence and token consumption. This is often the sweet spot balancing quality and token efficiency. |
| `xhigh` | The recommended starting point for coding and agentic work, and for exploratory tasks such as repeated tool calling, detailed web search, and knowledge-base search. Expect meaningfully higher token usage than `high`. |
| `max` | Reserve for genuinely frontier problems. On most workloads `max` adds significant cost for relatively small quality gains, and on some structured-output or less intelligence-sensitive tasks it can lead to overthinking. |
Claude Opus 4.7 also respects effort levels more strictly than Claude Opus 4.6, especially at `low` and `medium`. At lower effort levels, the model scopes its work to what was asked rather than going above and beyond. If you observe shallow reasoning on complex problems with Claude Opus 4.7, raise effort rather than prompting around it. If you must keep effort low for latency, add targeted guidance like "This task involves multi-step reasoning. Think carefully before responding."
When running Claude Opus 4.7 at `xhigh` or `max` effort, set a large `max_tokens` so the model has room to think and act across subagents and tool calls. Starting at 64k tokens and tuning from there is a reasonable default.
## Basic usage
<CodeGroup>
```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": "Analyze the trade-offs between microservices and monolithic architectures"
}],
"output_config": {
"effort": "medium"
}
}'
```
```bash CLI
ant messages create --transform 'content.0.text' --format yaml <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
messages:
- role: user
content: Analyze the trade-offs between microservices and monolithic architectures
output_config:
effort: medium
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": "Analyze the trade-offs between microservices and monolithic architectures",
}
],
output_config={"effort": "medium"},
)
print(response.content[0].text)
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
messages: [
{
role: "user",
content: "Analyze the trade-offs between microservices and monolithic architectures"
}
],
output_config: {
effort: "medium"
}
});
const textBlock = response.content.find(
(block): block is Anthropic.TextBlock => block.type === "text"
);
console.log(textBlock?.text);
```
```csharp C#
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 = "Analyze the trade-offs between microservices and monolithic architectures" }],
OutputConfig = new OutputConfig
{
Effort = Effort.Medium
}
};
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("Analyze the trade-offs between microservices and monolithic architectures")),
},
OutputConfig: anthropic.OutputConfigParam{
Effort: anthropic.OutputConfigEffortMedium,
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Content[0].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.OutputConfig;
public class Main {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(4096L)
.addUserMessage("Analyze the trade-offs between microservices and monolithic architectures")
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.MEDIUM)
.build())
.build();
Message response = client.messages().create(params);
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> System.out.println(textBlock.text()));
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Analyze the trade-offs between microservices and monolithic architectures']
],
model: 'claude-opus-4-7',
outputConfig: ['effort' => 'medium'],
);
echo $message->content[0]->text;
```
```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: "Analyze the trade-offs between microservices and monolithic architectures" }
],
output_config: {
effort: "medium"
}
)
puts message.content.first.text
```
</CodeGroup>
## When to adjust the effort parameter
- Use **max effort** when you need the absolute highest capability with no constraints: the most thorough reasoning and deepest analysis. Available on Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, and Claude Sonnet 4.6.
- Use **xhigh effort** for advanced coding and complex agentic work requiring extended exploration, such as repeated tool calling and detailed search. Available on Claude Opus 4.7.
- Use **high effort** (the default) when you need Claude's best work: complex reasoning, nuanced analysis, difficult coding problems, or any task where quality is the top priority.
- Use **medium effort** as a balanced option when you want solid performance without the full token expenditure of high effort.
- Use **low effort** when you're optimizing for speed (because Claude answers with fewer tokens) or cost. For example, simple classification tasks, quick lookups, or high-volume use cases where marginal quality improvements don't justify additional latency or spend.
## Effort with tool use
When using tools, the effort parameter affects both the explanations around tool calls and the tool calls themselves. Lower effort levels tend to:
- Combine multiple operations into fewer tool calls
- Make fewer tool calls
- Proceed directly to action without preamble
- Use terse confirmation messages after completion
Higher effort levels may:
- Make more tool calls
- Explain the plan before taking action
- Provide detailed summaries of changes
- Include more comprehensive code comments
## Effort with extended thinking
The effort parameter works alongside extended thinking. Its behavior depends on the model:
- **Claude Mythos Preview** uses [adaptive thinking](/docs/en/build-with-claude/adaptive-thinking) by default (no `thinking` configuration required). `thinking: {type: "disabled"}` is rejected. Effort controls thinking depth the same way as on Opus 4.7 and Opus 4.6.
- **Claude Opus 4.7** uses [adaptive thinking](/docs/en/build-with-claude/adaptive-thinking) (`thinking: {type: "adaptive"}`), where effort is the recommended control for thinking depth. Manual extended thinking (`thinking: {type: "enabled", budget_tokens: N}`) is no longer supported on Opus 4.7; use adaptive thinking with effort instead. At `high`, `xhigh`, and `max` effort, Claude almost always thinks deeply. At lower levels, it may skip thinking for simpler problems.
- **Claude Opus 4.6** uses [adaptive thinking](/docs/en/build-with-claude/adaptive-thinking) (`thinking: {type: "adaptive"}`), where effort is the recommended control for thinking depth. While `budget_tokens` is still accepted on Opus 4.6, it is deprecated and will be removed in a future release. At `high` and `max` effort, Claude almost always thinks deeply. At lower levels, it may skip thinking for simpler problems.
- **Claude Sonnet 4.6** uses [adaptive thinking](/docs/en/build-with-claude/adaptive-thinking) (where effort controls thinking depth). Manual thinking with [interleaved mode](/docs/en/build-with-claude/extended-thinking#interleaved-thinking) (`thinking: {type: "enabled", budget_tokens: N}`) is still functional but deprecated.
- **Claude Opus 4.5 and other Claude 4 models** use manual thinking (`thinking: {type: "enabled", budget_tokens: N}`), where effort works alongside the thinking token budget. Set the effort level for your task, then set the thinking token budget based on task complexity.
The effort parameter can be used with or without extended thinking enabled. When used without thinking, it still controls overall token spend for text responses and tool calls.
## Best practices
1. **Set effort explicitly:** The API defaults to `high`, but the right starting point depends on your model and workload.
2. **Use low for speed-sensitive or simple tasks:** When latency matters or tasks are straightforward, low effort can significantly reduce response times and costs.
3. **Test your use case:** The impact of effort levels varies by task type. Evaluate performance on your specific use cases before deploying.
4. **Consider dynamic effort:** Adjust effort based on task complexity. Simple queries may warrant low effort while agentic coding and complex reasoning benefit from high effort.
---
## Guides/build-with-claude-embeddings-bf8288b900.md
# Embeddings
Text embeddings are numerical representations of text that enable measuring semantic similarity. This guide introduces embeddings, their applications, and how to use embedding models for tasks like search, recommendations, and anomaly detection.
---
## Before implementing embeddings
When selecting an embeddings provider, there are several factors you can consider depending on your needs and preferences:
- Dataset size & domain specificity: size of the model training dataset and its relevance to the domain you want to embed. Larger or more domain-specific data generally produces better in-domain embeddings
- Inference performance: embedding lookup speed and end-to-end latency. This is a particularly important consideration for large scale production deployments
- Customization: options for continued training on private data, or specialization of models for very specific domains. This can improve performance on unique vocabularies
## How to get embeddings with Anthropic
Anthropic does not offer its own embedding model. One embeddings provider that has a wide variety of options and capabilities encompassing all of the above considerations is Voyage AI.
Voyage AI makes state-of-the-art embedding models and offers customized models for specific industry domains such as finance and healthcare, or bespoke fine-tuned models for individual customers.
The rest of this guide is for Voyage AI, but you should assess a variety of embeddings vendors to find the best fit for your specific use case.
## Available models
Voyage recommends using the following text embedding models:
**Voyage 4 (latest generation)**
| Model | Context Length | Embedding Dimension | Description |
| --- | --- | --- | --- |
| `voyage-4-large` | 32,000 | 1024 (default), 256, 512, 2048 | The best general-purpose and multilingual retrieval quality. See [blog post](https://blog.voyageai.com/2026/01/15/voyage-4/) for details. |
| `voyage-4` | 32,000 | 1024 (default), 256, 512, 2048 | Optimized for general-purpose and multilingual retrieval quality. Balances quality and efficiency. See [blog post](https://blog.voyageai.com/2026/01/15/voyage-4/) for details. |
| `voyage-4-lite` | 32,000 | 1024 (default), 256, 512, 2048 | Optimized for latency and cost. See [blog post](https://blog.voyageai.com/2026/01/15/voyage-4/) for details. |
| `voyage-4-nano` | 32,000 | 1024 (default), 256, 512, 2048 | Open-weight model (Apache 2.0 license) available on Hugging Face. See [blog post](https://blog.voyageai.com/2026/01/15/voyage-4/) for details. |
**Previous generation**
| Model | Context Length | Embedding Dimension | Description |
| --- | --- | --- | --- |
| `voyage-3-large` | 32,000 | 1024 (default), 256, 512, 2048 | The best general-purpose and multilingual retrieval quality. See [blog post](https://blog.voyageai.com/2025/01/07/voyage-3-large/) for details. |
| `voyage-3.5` | 32,000 | 1024 (default), 256, 512, 2048 | Optimized for general-purpose and multilingual retrieval quality. See [blog post](https://blog.voyageai.com/2025/05/20/voyage-3-5/) for details. |
| `voyage-3.5-lite` | 32,000 | 1024 (default), 256, 512, 2048 | Optimized for latency and cost. See [blog post](https://blog.voyageai.com/2025/05/20/voyage-3-5/) for details. |
| `voyage-code-3` | 32,000 | 1024 (default), 256, 512, 2048 | Optimized for **code** retrieval. See [blog post](https://blog.voyageai.com/2024/12/04/voyage-code-3/) for details. |
| `voyage-finance-2` | 32,000 | 1024 | Optimized for **finance** retrieval and RAG. See [blog post](https://blog.voyageai.com/2024/06/03/domain-specific-embeddings-finance-edition-voyage-finance-2/) for details. |
| `voyage-law-2` | 16,000 | 1024 | Optimized for **legal** and **long-context** retrieval and RAG. Also improved performance across all domains. See [blog post](https://blog.voyageai.com/2024/04/15/domain-specific-embeddings-and-retrieval-legal-edition-voyage-law-2/) for details. |
Additionally, the following multimodal embedding models are recommended:
| Model | Context Length | Embedding Dimension | Description |
| --- | --- | --- | --- |
| `voyage-multimodal-3.5` | 32,000 | 1024 (default), 256, 512, 2048 | Rich multimodal embedding model that can vectorize interleaved text, images, and videos. Includes video support as the first production-grade video embedding model. See [blog post](https://blog.voyageai.com/2026/01/15/voyage-multimodal-3-5/) for details. |
| `voyage-multimodal-3` | 32,000 | 1024 | Rich multimodal embedding model that can vectorize interleaved text and content-rich images, such as screenshots of PDFs, slides, tables, figures, and more. See [blog post](https://blog.voyageai.com/2024/11/12/voyage-multimodal-3/) for details. |
Need help deciding which text embedding model to use? Check out the [FAQ](https://docs.voyageai.com/docs/faq#what-embedding-models-are-available-and-which-one-should-i-use&ref=anthropic).
## Getting started with Voyage AI
To access Voyage embeddings:
1. Sign up on Voyage AI's website
2. Obtain an API key
3. Set the API key as an environment variable for convenience:
```bash
export VOYAGE_API_KEY="<your secret key>"
```
You can obtain the embeddings by either using the official [`voyageai` Python package](https://github.com/voyage-ai/voyageai-python) or HTTP requests, as described below.
### Voyage Python library
The `voyageai` package can be installed using the following command:
```bash
pip install -U voyageai
```
Then, you can create a client object and start using it to embed your texts:
```python nocheck
import voyageai
vo = voyageai.Client()
# This will automatically use the environment variable VOYAGE_API_KEY.
# Alternatively, you can use vo = voyageai.Client(api_key="<your secret key>")
texts = ["Sample text 1", "Sample text 2"]
result = vo.embed(texts, model="voyage-4", input_type="document")
print(result.embeddings[0])
print(result.embeddings[1])
```
`result.embeddings` will be a list of two embedding vectors, each containing 1024 floating-point numbers. After running the above code, the two embeddings will be printed on the screen:
```text
[-0.013131560757756233, 0.019828535616397858, ...] # embedding for "Sample text 1"
[-0.0069352793507277966, 0.020878976210951805, ...] # embedding for "Sample text 2"
```
When creating the embeddings, you can specify a few other arguments to the `embed()` function.
For more information on the Voyage python package, see [the Voyage documentation](https://docs.voyageai.com/docs/embeddings#python-api).
### Voyage HTTP API
You can also get embeddings by requesting Voyage HTTP API. For example, you can send an HTTP request through the `curl` command in a terminal:
```bash cURL
curl https://api.voyageai.com/v1/embeddings \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $VOYAGE_API_KEY" \
-d '{
"input": ["Sample text 1", "Sample text 2"],
"model": "voyage-4"
}'
```
The response you would get is a JSON object containing the embeddings and the token usage:
```json
{
"object": "list",
"data": [
{
"embedding": [-0.013131560757756233, 0.019828535616397858 /* ... */],
"index": 0
},
{
"embedding": [-0.0069352793507277966, 0.020878976210951805 /* ... */],
"index": 1
}
],
"model": "voyage-4",
"usage": {
"total_tokens": 10
}
}
```
For more information on the Voyage HTTP API, see [the Voyage documentation](https://docs.voyageai.com/reference/embeddings-api).
### AWS Marketplace
Voyage embeddings are available on [AWS Marketplace](https://aws.amazon.com/marketplace/seller-profile?id=seller-snt4gb6fd7ljg). Instructions for accessing Voyage on AWS are available in the [Voyage AWS Marketplace documentation](https://docs.voyageai.com/docs/aws-marketplace-model-package?ref=anthropic).
## Quickstart example
The following brief example shows how to use embeddings.
Suppose you have a small corpus of six documents to retrieve from
```python nocheck
documents = [
"The Mediterranean diet emphasizes fish, olive oil, and vegetables, believed to reduce chronic diseases.",
"Photosynthesis in plants converts light energy into glucose and produces essential oxygen.",
"20th-century innovations, from radios to smartphones, centered on electronic advancements.",
"Rivers provide water, irrigation, and habitat for aquatic species, vital for ecosystems.",
"Apple's conference call to discuss fourth fiscal quarter results and business updates is scheduled for Thursday, November 2, 2023 at 2:00 p.m. PT / 5:00 p.m. ET.",
"Shakespeare's works, like 'Hamlet' and 'A Midsummer Night's Dream,' endure in literature.",
]
```
First, use Voyage to convert each document into an embedding vector
```python nocheck
import voyageai
vo = voyageai.Client()
# Embed the documents
doc_embds = vo.embed(documents, model="voyage-4", input_type="document").embeddings
```
The embeddings allow you to do semantic search / retrieval in the vector space. Given an example query,
```python
query = "When is Apple's conference call scheduled?"
```
Next, convert it into an embedding and conduct a nearest neighbor search to find the most relevant document based on the distance in the embedding space.
```python nocheck
import numpy as np
# Embed the query
query_embd = vo.embed([query], model="voyage-4", input_type="query").embeddings[0]
# Compute the similarity
# Voyage embeddings are normalized to length 1, therefore dot-product
# and cosine similarity are the same.
similarities = np.dot(doc_embds, query_embd)
retrieved_id = np.argmax(similarities)
print(documents[retrieved_id])
```
Note that `input_type="document"` and `input_type="query"` are used for embedding the document and query, respectively. More specification can be found in the [Voyage Python package section](/docs/en/build-with-claude/embeddings#voyage-python-package).
The output would be the 5th document, which is indeed the most relevant to the query:
```text
Apple's conference call to discuss fourth fiscal quarter results and business updates is scheduled for Thursday, November 2, 2023 at 2:00 p.m. PT / 5:00 p.m. ET.
```
If you are looking for a detailed set of cookbooks on how to do RAG with embeddings, including vector databases, check out the [RAG cookbook](https://platform.claude.com/cookbook/third-party-pinecone-rag-using-pinecone).
## FAQ
<section title="Why do Voyage embeddings have superior quality?">
Embedding models rely on powerful neural networks to capture and compress semantic context, similar to generative models. Voyage's team of experienced AI researchers optimizes every component of the embedding process, including:
- Model architecture
- Data collection
- Loss functions
- Optimizer selection
Learn more about Voyage's technical approach on their [blog](https://blog.voyageai.com/).
</section>
<section title="What embedding models are available and which should I use?">
For general-purpose embedding, the recommended models are:
- `voyage-4-large`: Best quality
- `voyage-4-lite`: Lowest latency and cost
- `voyage-4`: Balanced performance
For retrieval, use the `input_type` parameter to specify whether the text is a query or document type.
Domain-specific models:
- Legal tasks: `voyage-law-2`
- Code and programming documentation: `voyage-code-3`
- Finance-related tasks: `voyage-finance-2`
</section>
<section title="Which similarity function should I use?">
You can use Voyage embeddings with either dot-product similarity, cosine similarity, or Euclidean distance. An explanation about embedding similarity can be found in this [vector similarity guide](https://www.pinecone.io/learn/vector-similarity/).
Voyage AI embeddings are normalized to length 1, which means that:
- Cosine similarity is equivalent to dot-product similarity, while the latter can be computed more quickly.
- Cosine similarity and Euclidean distance will result in the identical rankings.
</section>
<section title="What is the relationship between characters, words, and tokens?">
See this [page](https://docs.voyageai.com/docs/tokenization?ref=anthropic).
</section>
<section title="When and how should I use the input_type parameter?">
For all retrieval tasks and use cases (for example, RAG), use the `input_type` parameter to specify whether the input text is a query or document. Do not omit `input_type` or set `input_type=None`. Specifying whether input text is a query or document can create better dense vector representations for retrieval, which can lead to better retrieval quality.
When using the `input_type` parameter, special prompts are prepended to the input text prior to embedding. Specifically:
> 📘 **Prompts associated with `input_type`**
>
> - For a query, the prompt is “Represent the query for retrieving supporting documents: “.
> - For a document, the prompt is “Represent the document for retrieval: “.
> - Example
> - When `input_type="query"`, a query like "When is Apple's conference call scheduled?" will become "**Represent the query for retrieving supporting documents:** When is Apple's conference call scheduled?"
> - When `input_type="document"`, a query like "Apple's conference call to discuss fourth fiscal quarter results and business updates is scheduled for Thursday, November 2, 2023 at 2:00 p.m. PT / 5:00 p.m. ET." will become "**Represent the document for retrieval:** Apple's conference call to discuss fourth fiscal quarter results and business updates is scheduled for Thursday, November 2, 2023 at 2:00 p.m. PT / 5:00 p.m. ET."
`voyage-large-2-instruct`, as the name suggests, is trained to be responsive to additional instructions that are prepended to the input text. For classification, clustering, or other [MTEB](https://huggingface.co/mteb) subtasks, please use the [voyage-large-2-instruct instructions](https://github.com/voyage-ai/voyage-large-2-instruct).
</section>
<section title="What quantization options are available?">
Quantization in embeddings converts high-precision values, like 32-bit single-precision floating-point numbers, to lower-precision formats such as 8-bit integers or 1-bit binary values, reducing storage, memory, and costs by 4x and 32x, respectively. Supported Voyage models enable quantization by specifying the output data type with the `output_dtype` parameter:
- `float`: Each returned embedding is a list of 32-bit (4-byte) single-precision floating-point numbers. This is the default and provides the highest precision / retrieval accuracy.
- `int8` and `uint8`: Each returned embedding is a list of 8-bit (1-byte) integers ranging from -128 to 127 and 0 to 255, respectively.
- `binary` and `ubinary`: Each returned embedding is a list of 8-bit integers that represent bit-packed, quantized single-bit embedding values: `int8` for `binary` and `uint8` for `ubinary`. The length of the returned list of integers is 1/8 of the actual dimension of the embedding. The binary type uses the offset binary method, which you can learn more about in the FAQ below.
> **Binary quantization example**
>
> Consider the following eight embedding values: -0.03955078, 0.006214142, -0.07446289, -0.039001465, 0.0046463013, 0.00030612946, -0.08496094, and 0.03994751. With binary quantization, values less than or equal to zero will be quantized to a binary zero, and positive values to a binary one, resulting in the following binary sequence: 0, 1, 0, 0, 1, 1, 0, 1. These eight bits are then packed into a single 8-bit integer, 01001101 (with the leftmost bit as the most significant bit).
> - `ubinary`: The binary sequence is directly converted and represented as the unsigned integer (`uint8`) 77.
> - `binary`: The binary sequence is represented as the signed integer (`int8`) -51, calculated using the offset binary method (77 - 128 = -51).
</section>
<section title="How can I truncate Matryoshka embeddings?">
Matryoshka learning creates embeddings with coarse-to-fine representations within a single vector. Voyage models, such as `voyage-code-3`, that support multiple output dimensions generate such Matryoshka embeddings. You can truncate these vectors by keeping the leading subset of dimensions. For example, the following Python code demonstrates how to truncate 1024-dimensional vectors to 256 dimensions:
```python nocheck
import voyageai
import numpy as np
def embd_normalize(v: np.ndarray) -> np.ndarray:
"""
Normalize the rows of a 2D numpy array to unit vectors by dividing each row by its Euclidean
norm. Raises a ValueError if any row has a norm of zero to prevent division by zero.
"""
row_norms = np.linalg.norm(v, axis=1, keepdims=True)
if np.any(row_norms == 0):
raise ValueError("Cannot normalize rows with a norm of zero.")
return v / row_norms
vo = voyageai.Client()
# Generate voyage-code-3 vectors, which by default are 1024-dimensional floating-point numbers
embd = vo.embed(["Sample text 1", "Sample text 2"], model="voyage-code-3").embeddings
# Set shorter dimension
short_dim = 256
# Resize and normalize vectors to shorter dimension
resized_embd = embd_normalize(np.array(embd)[:, :short_dim]).tolist()
```
</section>
## Pricing
Visit Voyage's [pricing page](https://docs.voyageai.com/docs/pricing?ref=anthropic) for the most up to date pricing details.
---
## Guides/build-with-claude-extended-thinking-dd12780e6a.md
# Building with extended thinking
---
<Note>
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.
</Note>
Extended thinking gives Claude enhanced reasoning capabilities for complex tasks, while providing varying levels of transparency into its step-by-step thought process before it delivers its final answer.
<Note>
For Claude Opus 4.7 and later models, use [adaptive thinking](/docs/en/build-with-claude/adaptive-thinking) (`thinking: {type: "adaptive"}`) with the [effort parameter](/docs/en/build-with-claude/effort). Manual extended thinking (`thinking: {type: "enabled", budget_tokens: N}`) is no longer supported on Claude Opus 4.7 or later models and returns a 400 error. For Claude Opus 4.6 and Claude Sonnet 4.6, adaptive thinking is also recommended; the manual configuration is still functional on these models but is deprecated and will be removed in a future model release.
</Note>
## Supported models
Manual extended thinking (`thinking: {type: "enabled", budget_tokens: N}`) is supported on all current Claude models **except Claude Opus 4.7 and later models**, where it is no longer accepted and returns a 400 error. A few models have mode-specific behavior:
- **Claude Opus 4.7 (`claude-opus-4-7`) and later models:** manual extended thinking is no longer supported. Use [adaptive thinking](/docs/en/build-with-claude/adaptive-thinking) (`thinking: {type: "adaptive"}`) with the [effort parameter](/docs/en/build-with-claude/effort) instead.
- **[Claude Mythos Preview](https://anthropic.com/glasswing):** [adaptive thinking](/docs/en/build-with-claude/adaptive-thinking) is the default; `thinking: {type: "enabled", budget_tokens: N}` is also accepted. `thinking: {type: "disabled"}` is not supported, and `display` defaults to `"omitted"` rather than returning thinking content. Pass `display: "summarized"` to receive summaries.
- **Claude Opus 4.6 (`claude-opus-4-6`):** [adaptive thinking](/docs/en/build-with-claude/adaptive-thinking) recommended; manual mode (`type: "enabled"`) is deprecated but still functional.
- **Claude Sonnet 4.6 (`claude-sonnet-4-6`):** [adaptive thinking](/docs/en/build-with-claude/adaptive-thinking) recommended; manual mode (`type: "enabled"`) with [interleaved mode](#interleaved-thinking) is deprecated but still functional.
<Note>
API behavior differs across Claude Sonnet 3.7 and Claude 4 models, but the API shapes remain exactly the same.
For more information, see [Differences in thinking across model versions](#differences-in-thinking-across-model-versions).
</Note>
## How extended thinking works
When extended thinking is turned on, Claude creates `thinking` content blocks where it outputs its internal reasoning. Claude incorporates insights from this reasoning before crafting a final response.
The API response includes `thinking` content blocks, followed by `text` content blocks.
Here's an example of the default response format:
```json
{
"content": [
{
"type": "thinking",
"thinking": "Let me analyze this step by step...",
"signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
},
{
"type": "text",
"text": "Based on my analysis..."
}
]
}
```
For more information about the response format of extended thinking, see the [Messages API Reference](/docs/en/api/messages/create).
## How to use extended thinking
Here is an example of using extended thinking in the Messages API:
<CodeGroup>
```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-sonnet-4-6",
"max_tokens": 16000,
"thinking": {
"type": "enabled",
"budget_tokens": 10000
},
"messages": [
{
"role": "user",
"content": "Are there an infinite number of prime numbers such that n mod 4 == 3?"
}
]
}'
```
```bash CLI
ant messages create \
--transform content --format yaml \
--model claude-sonnet-4-6 \
--max-tokens 16000 \
--thinking '{type: enabled, budget_tokens: 10000}' \
--message '{role: user, content: Are there an infinite number of prime numbers such that n mod 4 == 3?}'
```
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[
{
"role": "user",
"content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
}
],
)
# The response contains summarized thinking blocks and text blocks
for block in response.content:
if block.type == "thinking":
print(f"\nThinking summary: {block.thinking}")
elif block.type == "text":
print(f"\nResponse: {block.text}")
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 16000,
thinking: {
type: "enabled",
budget_tokens: 10000
},
messages: [
{
role: "user",
content: "Are there an infinite number of prime numbers such that n mod 4 == 3?"
}
]
});
// The response contains summarized thinking blocks and text blocks
for (const block of response.content) {
if (block.type === "thinking") {
console.log(`\nThinking summary: ${block.thinking}`);
} else if (block.type === "text") {
console.log(`\nResponse: ${block.text}`);
}
}
```
```csharp C#
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.ClaudeSonnet4_6,
MaxTokens = 16000,
Thinking = new ThinkingConfigEnabled(budgetTokens: 10000),
Messages = [
new() {
Role = Role.User,
Content = "Are there an infinite number of prime numbers such that n mod 4 == 3?"
}
]
};
var message = await client.Messages.Create(parameters);
foreach (var block in message.Content)
{
if (block.TryPickThinking(out ThinkingBlock? thinking))
{
Console.WriteLine($"\nThinking summary: {thinking.Thinking}");
}
else if (block.TryPickText(out TextBlock? text))
{
Console.WriteLine($"\nResponse: {text.Text}");
}
}
}
}
```
```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.Model("claude-sonnet-4-6"),
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(10000),
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Are there an infinite number of prime numbers such that n mod 4 == 3?")),
},
})
if err != nil {
log.Fatal(err)
}
for _, block := range response.Content {
switch v := block.AsAny().(type) {
case anthropic.ThinkingBlock:
fmt.Printf("\nThinking summary: %s", v.Thinking)
case anthropic.TextBlock:
fmt.Printf("\nResponse: %s", v.Text)
}
}
}
```
```java Java hidelines={1..8,-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;
public class ExtendedThinkingExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_4_6)
.maxTokens(16000L)
.enabledThinking(10000L)
.addUserMessage("Are there an infinite number of prime numbers such that n mod 4 == 3?")
.build();
Message response = client.messages().create(params);
response.content().forEach(block -> {
block.thinking().ifPresent(thinkingBlock ->
System.out.println("\nThinking summary: " + thinkingBlock.thinking())
);
block.text().ifPresent(textBlock ->
System.out.println("\nResponse: " + textBlock.text())
);
});
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->messages->create(
maxTokens: 16000,
messages: [
[
'role' => 'user',
'content' => 'Are there an infinite number of prime numbers such that n mod 4 == 3?'
]
],
model: 'claude-sonnet-4-6',
thinking: ['type' => 'enabled', 'budget_tokens' => 10000],
);
foreach ($message->content as $block) {
if ($block->type === 'thinking') {
echo "\nThinking summary: " . $block->thinking;
} elseif ($block->type === 'text') {
echo "\nResponse: " . $block->text;
}
}
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-sonnet-4-6",
max_tokens: 16000,
thinking: {
type: "enabled",
budget_tokens: 10000
},
messages: [
{
role: "user",
content: "Are there an infinite number of prime numbers such that n mod 4 == 3?"
}
]
)
message.content.each do |block|
case block.type
when :thinking
puts "\nThinking summary: #{block.thinking}"
when :text
puts "\nResponse: #{block.text}"
end
end
```
</CodeGroup>
To turn on extended thinking, add a `thinking` object, with the `type` parameter set to `enabled` and the `budget_tokens` to a specified token budget for extended thinking. For Claude Opus 4.6 and Claude Sonnet 4.6, use `type: "adaptive"` instead. See [Adaptive thinking](/docs/en/build-with-claude/adaptive-thinking) for details. While `type: "enabled"` with `budget_tokens` is still functional on these models, it is deprecated and will be removed in a future release.
The `budget_tokens` parameter determines the maximum number of tokens Claude is allowed to use for its internal reasoning process. In Claude 4 and later models, this limit applies to full thinking tokens, and not to [the summarized output](#summarized-thinking). Larger budgets can improve response quality by enabling more thorough analysis for complex problems, although Claude may not use the entire budget allocated, especially at ranges above 32k.
<Warning>
`budget_tokens` is [deprecated](/docs/en/build-with-claude/overview#feature-availability) on Claude Opus 4.6 and Claude Sonnet 4.6 and will be removed in a future model release. Use [adaptive thinking](/docs/en/build-with-claude/adaptive-thinking) with the [effort parameter](/docs/en/build-with-claude/effort) to control thinking depth instead.
</Warning>
<Note>
[Claude Mythos Preview](https://anthropic.com/glasswing), Claude Opus 4.7, and Claude Opus 4.6 support up to 128k output tokens. Claude Sonnet 4.6 and Claude Haiku 4.5 support up to 64k. See the [models overview](/docs/en/about-claude/models/overview) for limits on legacy models. On the [Message Batches API](/docs/en/build-with-claude/batch-processing#extended-output-beta), the `output-300k-2026-03-24` [beta header](/docs/en/api/beta-headers) raises the output limit to 300k for Opus 4.7, Opus 4.6, and Sonnet 4.6.
</Note>
`budget_tokens` must be set to a value less than `max_tokens`. However, when using [interleaved thinking with tools](#interleaved-thinking), you can exceed this limit as the token limit becomes your entire context window.
### Summarized thinking
With extended thinking enabled, the Messages API for Claude 4 models returns a summary of Claude's full thinking process. Summarized thinking provides the full intelligence benefits of extended thinking, while preventing misuse. This is the default behavior on Claude 4 models when the `display` field on the thinking configuration is unset or set to `"summarized"`. On Claude Opus 4.7 and [Claude Mythos Preview](https://anthropic.com/glasswing), `display` defaults to `"omitted"` instead, so you must set `display: "summarized"` explicitly to receive summarized thinking.
Here are some important considerations for summarized thinking:
- You're charged for the full thinking tokens generated by the original request, not the summary tokens.
- The billed output token count will **not match** the count of tokens you see in the response.
- On Claude 4 models, the first few lines of thinking output are more verbose, providing detailed reasoning that's particularly helpful for prompt engineering purposes. [Claude Mythos Preview](https://anthropic.com/glasswing) summarizes from the first token, so its thinking blocks do not show this verbose preamble.
- As Anthropic seeks to improve the extended thinking feature, summarization behavior is subject to change.
- Summarization preserves the key ideas of Claude's thinking process with minimal added latency, enabling a streamable user experience and easy migration from Claude Sonnet 3.7 to Claude 4 and later models.
- Summarization is processed by a different model than the one you target in your requests. The thinking model does not see the summarized output.
<Note>
Claude Sonnet 3.7 continues to return full thinking output.
In rare cases where you need access to full thinking output for Claude 4 models, [contact our sales team](mailto:sales@anthropic.com).
</Note>
### Controlling thinking display
The `display` field on the thinking configuration controls how thinking content is returned in API responses. It accepts two values:
- `"summarized"`: Thinking blocks contain summarized thinking text. See [Summarized thinking](#summarized-thinking) for details. This is the default on Claude Opus 4.6, Claude Sonnet 4.6, and earlier Claude 4 models.
- `"omitted"`: Thinking blocks are returned with an empty `thinking` field. The `signature` field still carries the encrypted full thinking for multi-turn continuity (see [Thinking encryption](#thinking-encryption)). This is the default on Claude Opus 4.7 and [Claude Mythos Preview](https://anthropic.com/glasswing).
Setting `display: "omitted"` is useful when your application doesn't surface thinking content to users. The primary benefit is **faster time-to-first-text-token when streaming:** The server skips streaming thinking tokens entirely and delivers only the signature, so the final text response begins streaming sooner.
<Note>
No SDK currently includes `display` in its type definitions. The Python SDK forwards unrecognized dict keys to the API at runtime; passing `display` in the thinking dict works transparently. The TypeScript SDK requires a type assertion. The C#, Go, Java, PHP, and Ruby SDKs require a direct HTTP request until native support lands.
</Note>
Here are some important considerations for omitted thinking:
- You're still charged for the full thinking tokens. Omitting reduces latency, not cost.
- If you pass thinking blocks back in multi-turn conversations, pass them unchanged. The server decrypts the `signature` to reconstruct the original thinking for prompt construction (see [Preserving thinking blocks](/docs/en/build-with-claude/extended-thinking#preserving-thinking-blocks)). Any text you place in the `thinking` field of a round-tripped omitted block is ignored.
- `display` is invalid with `thinking.type: "disabled"` (there is nothing to display).
- When using `thinking.type: "adaptive"` and the model skips thinking for a simple request, no thinking block is produced regardless of `display`.
<Note>
The `signature` field is identical whether `display` is `"summarized"` or `"omitted"`. Switching `display` values between turns in a conversation is supported.
</Note>
<Note>
On [Claude Mythos Preview](https://anthropic.com/glasswing), `display` defaults to `"omitted"`. The examples in this section pass `display` explicitly so they apply to all models, but on Mythos Preview you can leave it unset and receive the same behavior. To receive summarized thinking on Mythos Preview, set `display: "summarized"` explicitly.
</Note>
Automated pipelines that never surface thinking content to end users can skip the overhead of receiving thinking tokens over the wire. Latency-sensitive applications get the same reasoning quality without waiting for thinking text to stream before the final response begins.
<Tabs>
<Tab title="cURL">
```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-sonnet-4-6",
"max_tokens": 16000,
"thinking": {
"type": "enabled",
"budget_tokens": 10000,
"display": "omitted"
},
"messages": [
{
"role": "user",
"content": "What is 27 * 453?"
}
]
}'
```
</Tab>
<Tab title="CLI">
```bash CLI
ant messages create \
--model claude-sonnet-4-6 \
--max-tokens 16000 \
--transform content --format yaml \
--thinking '{type: enabled, budget_tokens: 10000, display: omitted}' \
--message '{role: user, content: "What is 27 * 453?"}'
```
</Tab>
<Tab title="Python">
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=16000,
thinking={
"type": "enabled",
"budget_tokens": 10000,
"display": "omitted",
},
messages=[
{"role": "user", "content": "What is 27 * 453?"},
],
)
for block in response.content:
if block.type == "thinking":
if block.thinking:
print(f"Thinking: {block.thinking}")
else:
print("Thinking: [omitted]")
elif block.type == "text":
print(f"Response: {block.text}")
```
</Tab>
<Tab title="TypeScript">
<Note>
TypeScript SDK types don't yet include `display`. The type assertion passes it through at runtime; the SDK forwards unknown parameters to the API.
</Note>
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 16000,
thinking: {
type: "enabled",
budget_tokens: 10000,
display: "omitted"
},
messages: [
{
role: "user",
content: "What is 27 * 453?"
}
]
} as unknown as Anthropic.MessageCreateParamsNonStreaming);
for (const block of response.content) {
if (block.type === "thinking") {
if (block.thinking) {
console.log(`Thinking: ${block.thinking}`);
} else {
console.log("Thinking: [omitted]");
}
} else if (block.type === "text") {
console.log(`Response: ${block.text}`);
}
}
```
</Tab>
<Tab title="C#">
<Note>
Native SDK support for the `display` field is coming soon. Until then, you can use a direct HTTP request:
</Note>
```csharp C# hidelines={1..10,-2..-1}
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY"));
client.DefaultRequestHeaders.Add("anthropic-version", "2023-06-01");
var body = """
{
"model": "claude-sonnet-4-6",
"max_tokens": 16000,
"thinking": {
"type": "enabled",
"budget_tokens": 10000,
"display": "omitted"
},
"messages": [
{"role": "user", "content": "What is 27 * 453?"}
]
}
""";
var response = await client.PostAsync(
"https://api.anthropic.com/v1/messages",
new StringContent(body, Encoding.UTF8, "application/json"));
var json = await response.Content.ReadAsStringAsync();
var doc = JsonDocument.Parse(json);
foreach (var block in doc.RootElement.GetProperty("content").EnumerateArray())
{
var type = block.GetProperty("type").GetString();
if (type == "thinking")
{
var thinking = block.GetProperty("thinking").GetString();
Console.WriteLine($"Thinking: {(string.IsNullOrEmpty(thinking) ? "[omitted]" : thinking)}");
}
else if (type == "text")
{
Console.WriteLine($"Response: {block.GetProperty("text").GetString()}");
}
}
}
}
```
</Tab>
<Tab title="Go">
<Note>
Native SDK support for the `display` field is coming soon. Until then, you can use a direct HTTP request:
</Note>
```go Go hidelines={1..12,-1}
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
)
func main() {
body := []byte(`{
"model": "claude-sonnet-4-6",
"max_tokens": 16000,
"thinking": {
"type": "enabled",
"budget_tokens": 10000,
"display": "omitted"
},
"messages": [
{"role": "user", "content": "What is 27 * 453?"}
]
}`)
req, _ := http.NewRequest("POST", "https://api.anthropic.com/v1/messages", bytes.NewBuffer(body))
req.Header.Set("x-api-key", os.Getenv("ANTHROPIC_API_KEY"))
req.Header.Set("anthropic-version", "2023-06-01")
req.Header.Set("content-type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
respBody, _ := io.ReadAll(resp.Body)
var result map[string]any
json.Unmarshal(respBody, &result)
for _, block := range result["content"].([]any) {
b := block.(map[string]any)
if b["type"] == "thinking" {
thinking := b["thinking"].(string)
if thinking == "" {
fmt.Println("Thinking: [omitted]")
} else {
fmt.Println("Thinking:", thinking)
}
} else if b["type"] == "text" {
fmt.Println("Response:", b["text"])
}
}
}
```
</Tab>
<Tab title="Java">
<Note>
Native SDK support for the `display` field is coming soon. Until then, you can use a direct HTTP request:
</Note>
```java Java hidelines={1..9,-2..-1}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import org.json.JSONArray;
import org.json.JSONObject;
public class ThinkingDisplay {
public static void main(String[] args) throws Exception {
String body = """
{
"model": "claude-sonnet-4-6",
"max_tokens": 16000,
"thinking": {
"type": "enabled",
"budget_tokens": 10000,
"display": "omitted"
},
"messages": [
{"role": "user", "content": "What is 27 * 453?"}
]
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.anthropic.com/v1/messages"))
.header("x-api-key", System.getenv("ANTHROPIC_API_KEY"))
.header("anthropic-version", "2023-06-01")
.header("content-type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
JSONObject json = new JSONObject(response.body());
JSONArray content = json.getJSONArray("content");
for (int i = 0; i < content.length(); i++) {
JSONObject block = content.getJSONObject(i);
String type = block.getString("type");
if (type.equals("thinking")) {
String thinking = block.getString("thinking");
System.out.println("Thinking: " + (thinking.isEmpty() ? "[omitted]" : thinking));
} else if (type.equals("text")) {
System.out.println("Response: " + block.getString("text"));
}
}
}
}
```
</Tab>
<Tab title="PHP">
<Note>
Native SDK support for the `display` field is coming soon. Until then, you can use a direct HTTP request:
</Note>
```php PHP hidelines={1..2}
<?php
$body = json_encode([
"model" => "claude-sonnet-4-6",
"max_tokens" => 16000,
"thinking" => [
"type" => "enabled",
"budget_tokens" => 10000,
"display" => "omitted",
],
"messages" => [
["role" => "user", "content" => "What is 27 * 453?"],
],
]);
$ch = curl_init("https://api.anthropic.com/v1/messages");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"x-api-key: " . getenv("ANTHROPIC_API_KEY"),
"anthropic-version: 2023-06-01",
"content-type: application/json",
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
foreach ($response["content"] as $block) {
if ($block["type"] === "thinking") {
$thinking = $block["thinking"];
echo "Thinking: " . ($thinking === "" ? "[omitted]" : $thinking) . "\n";
} elseif ($block["type"] === "text") {
echo "Response: " . $block["text"] . "\n";
}
}
```
</Tab>
<Tab title="Ruby">
<Note>
Native SDK support for the `display` field is coming soon. Until then, you can use a direct HTTP request:
</Note>
```ruby Ruby
require "net/http"
require "json"
require "uri"
uri = URI("https://api.anthropic.com/v1/messages")
body = {
model: "claude-sonnet-4-6",
max_tokens: 16000,
thinking: {
type: "enabled",
budget_tokens: 10000,
display: "omitted"
},
messages: [
{ role: "user", content: "What is 27 * 453?" }
]
}
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request["x-api-key"] = ENV["ANTHROPIC_API_KEY"]
request["anthropic-version"] = "2023-06-01"
request["content-type"] = "application/json"
request.body = body.to_json
response = JSON.parse(http.request(request).body)
response["content"].each do |block|
if block["type"] == "thinking"
thinking = block["thinking"]
puts "Thinking: #{thinking.empty? ? '[omitted]' : thinking}"
elsif block["type"] == "text"
puts "Response: #{block['text']}"
end
end
```
</Tab>
</Tabs>
When `display: "omitted"` is set, the response contains `thinking` blocks with an empty `thinking` field:
```json Output
{
"content": [
{
"type": "thinking",
"thinking": "",
"signature": "EosnCkYICxIMMb3LzNrMu..."
},
{
"type": "text",
"text": "The answer is 12,231."
}
]
}
```
When streaming with `display: "omitted"`, no `thinking_delta` events are emitted; see [Streaming thinking](#streaming-thinking) below for the event sequence.
### Streaming thinking
You can stream extended thinking responses using [server-sent events (SSE)](https://developer.mozilla.org/en-US/Web/API/Server-sent%5Fevents/Using%5Fserver-sent%5Fevents).
When streaming is enabled for extended thinking, you receive thinking content via `thinking_delta` events.
When `display: "omitted"` is set, no `thinking_delta` events are emitted. See [Controlling thinking display](#controlling-thinking-display).
For more documentation on streaming via the Messages API, see [Streaming Messages](/docs/en/build-with-claude/streaming).
Here's how to handle streaming with thinking:
<CodeGroup tryInConsole={{ userPrompt: "What is the greatest common divisor of 1071 and 462?", thinkingBudgetTokens: 16000 }}>
```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-sonnet-4-6",
"max_tokens": 16000,
"stream": true,
"thinking": {
"type": "enabled",
"budget_tokens": 10000
},
"messages": [
{
"role": "user",
"content": "What is the greatest common divisor of 1071 and 462?"
}
]
}'
```
```bash CLI
ant messages create --stream --format jsonl \
--model claude-sonnet-4-6 \
--max-tokens 16000 \
--thinking '{type: enabled, budget_tokens: 10000}' \
--message '{role: user, content: What is the greatest common divisor of 1071 and 462?}'
```
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
with client.messages.stream(
model="claude-sonnet-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[
{
"role": "user",
"content": "What is the greatest common divisor of 1071 and 462?",
}
],
) as stream:
thinking_started = False
response_started = False
for event in stream:
if event.type == "content_block_start":
print(f"\nStarting {event.content_block.type} block...")
# Reset flags for each new block
thinking_started = False
response_started = False
elif event.type == "content_block_delta":
if event.delta.type == "thinking_delta":
if not thinking_started:
print("Thinking: ", end="", flush=True)
thinking_started = True
print(event.delta.thinking, end="", flush=True)
elif event.delta.type == "text_delta":
if not response_started:
print("Response: ", end="", flush=True)
response_started = True
print(event.delta.text, end="", flush=True)
elif event.type == "content_block_stop":
print("\nBlock complete.")
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const stream = await client.messages.stream({
model: "claude-sonnet-4-6",
max_tokens: 16000,
thinking: {
type: "enabled",
budget_tokens: 10000
},
messages: [
{
role: "user",
content: "What is the greatest common divisor of 1071 and 462?"
}
]
});
let thinkingStarted = false;
let responseStarted = false;
for await (const event of stream) {
if (event.type === "content_block_start") {
console.log(`\nStarting ${event.content_block.type} block...`);
// Reset flags for each new block
thinkingStarted = false;
responseStarted = false;
} else if (event.type === "content_block_delta") {
if (event.delta.type === "thinking_delta") {
if (!thinkingStarted) {
process.stdout.write("Thinking: ");
thinkingStarted = true;
}
process.stdout.write(event.delta.thinking);
} else if (event.delta.type === "text_delta") {
if (!responseStarted) {
process.stdout.write("Response: ");
responseStarted = true;
}
process.stdout.write(event.delta.text);
}
} else if (event.type === "content_block_stop") {
console.log("\nBlock complete.");
}
}
```
```csharp C#
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages;
public class Program
{
public static async Task Main()
{
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeSonnet4_6,
MaxTokens = 16000,
Thinking = new ThinkingConfigEnabled(budgetTokens: 10000),
Messages = [new() { Role = Role.User, Content = "What is the greatest common divisor of 1071 and 462?" }]
};
bool thinkingStarted = false;
bool responseStarted = false;
await foreach (var streamEvent in client.Messages.CreateStreaming(parameters))
{
if (streamEvent.TryPickContentBlockStart(out var blockStart))
{
Console.WriteLine($"\nStarting {blockStart.ContentBlock.Type} block...");
thinkingStarted = false;
responseStarted = false;
}
else if (streamEvent.TryPickContentBlockDelta(out var blockDelta))
{
if (blockDelta.Delta.TryPickThinking(out var thinkingDelta))
{
if (!thinkingStarted)
{
Console.Write("Thinking: ");
thinkingStarted = true;
}
Console.Write(thinkingDelta.Thinking);
}
else if (blockDelta.Delta.TryPickText(out var textDelta))
{
if (!responseStarted)
{
Console.Write("Response: ");
responseStarted = true;
}
Console.Write(textDelta.Text);
}
}
else if (streamEvent.TryPickContentBlockStop(out _))
{
Console.WriteLine("\nBlock complete.");
}
}
}
}
```
```go Go hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.Model("claude-sonnet-4-6"),
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(10000),
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What is the greatest common divisor of 1071 and 462?")),
},
})
thinkingStarted := false
responseStarted := false
for stream.Next() {
event := stream.Current()
switch eventVariant := event.AsAny().(type) {
case anthropic.ContentBlockStartEvent:
fmt.Printf("\nStarting %s block...\n", eventVariant.ContentBlock.Type)
thinkingStarted = false
responseStarted = false
case anthropic.ContentBlockDeltaEvent:
switch deltaVariant := eventVariant.Delta.AsAny().(type) {
case anthropic.ThinkingDelta:
if !thinkingStarted {
fmt.Print("Thinking: ")
thinkingStarted = true
}
fmt.Print(deltaVariant.Thinking)
case anthropic.TextDelta:
if !responseStarted {
fmt.Print("Response: ")
responseStarted = true
}
fmt.Print(deltaVariant.Text)
}
case anthropic.ContentBlockStopEvent:
fmt.Println("\nBlock complete.")
}
}
if err := stream.Err(); err != nil {
log.Fatal(err)
}
}
```
```java Java hidelines={1..7,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
public class ExtendedThinkingStreaming {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_4_6)
.maxTokens(16000L)
.enabledThinking(10000L)
.addUserMessage("What is the greatest common divisor of 1071 and 462?")
.build();
try (var streamResponse = client.messages().createStreaming(params)) {
streamResponse.stream().forEach(event -> {
event.contentBlockStart().ifPresent(startEvent ->
System.out.println("\nStarting block...")
);
event.contentBlockDelta().ifPresent(deltaEvent -> {
deltaEvent.delta().thinking().ifPresent(td ->
System.out.print(td.thinking())
);
deltaEvent.delta().text().ifPresent(td ->
System.out.print(td.text())
);
});
event.contentBlockStop().ifPresent(stopEvent ->
System.out.println("\nBlock complete.")
);
});
}
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$thinkingStarted = false;
$responseStarted = false;
$stream = $client->messages->createStream(
maxTokens: 16000,
messages: [
['role' => 'user', 'content' => 'What is the greatest common divisor of 1071 and 462?']
],
model: 'claude-sonnet-4-6',
thinking: ['type' => 'enabled', 'budget_tokens' => 10000],
);
foreach ($stream as $event) {
if ($event->type === 'content_block_start') {
echo "\nStarting {$event->contentBlock->type} block...\n";
$thinkingStarted = false;
$responseStarted = false;
} elseif ($event->type === 'content_block_delta') {
if ($event->delta->type === 'thinking_delta') {
if (!$thinkingStarted) {
echo "Thinking: ";
$thinkingStarted = true;
}
echo $event->delta->thinking;
} elseif ($event->delta->type === 'text_delta') {
if (!$responseStarted) {
echo "Response: ";
$responseStarted = true;
}
echo $event->delta->text;
}
} elseif ($event->type === 'content_block_stop') {
echo "\nBlock complete.\n";
}
}
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
thinking_started = false
response_started = false
stream = client.messages.stream(
model: "claude-sonnet-4-6",
max_tokens: 16000,
thinking: {
type: "enabled",
budget_tokens: 10000
},
messages: [
{ role: "user", content: "What is the greatest common divisor of 1071 and 462?" }
]
)
stream.each do |event|
case event.type
when :content_block_start
puts "\nStarting #{event.content_block.type} block..."
thinking_started = false
response_started = false
when :content_block_delta
if event.delta.type == :thinking_delta
unless thinking_started
print "Thinking: "
thinking_started = true
end
print event.delta.thinking
elsif event.delta.type == :text_delta
unless response_started
print "Response: "
response_started = true
end
print event.delta.text
end
when :content_block_stop
puts "\nBlock complete."
end
end
```
</CodeGroup>
Example streaming output:
```sse Output
event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-sonnet-4-6", "stop_reason": null, "stop_sequence": null}}
event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": "", "signature": ""}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21\n147 = 7 × 21 + 0\n\nSo GCD(1071, 462) = 21"}}
// Additional thinking deltas...
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}
event: content_block_stop
data: {"type": "content_block_stop", "index": 0}
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "The greatest common divisor of 1071 and 462 is **21**."}}
// Additional text deltas...
event: content_block_stop
data: {"type": "content_block_stop", "index": 1}
event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}
event: message_stop
data: {"type": "message_stop"}
```
When `display: "omitted"` is set, the thinking block opens, a single `signature_delta` arrives, and the block closes without any `thinking_delta` events. Text streaming begins immediately after:
```sse Output
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":"","signature":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"signature_delta","signature":"EosnCkYICxIMMb3LzNrMu..."}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}
```
<Note>
When using streaming with thinking enabled, you might notice that text sometimes arrives in larger chunks alternating with smaller, token-by-token delivery. This is expected behavior, especially for thinking content.
The streaming system needs to process content in batches for optimal performance, which can result in this "chunky" delivery pattern, with possible delays between streaming events. Anthropic is continuously working to improve this experience, with future updates focused on making thinking content stream more smoothly.
</Note>
## Extended thinking with tool use
Extended thinking can be used alongside [tool use](/docs/en/agents-and-tools/tool-use/overview), allowing Claude to reason through tool selection and results processing.
When using extended thinking with tool use, be aware of the following limitations:
1. **Tool choice limitation**: Tool use with thinking only supports `tool_choice: {"type": "auto"}` (the default) or `tool_choice: {"type": "none"}`. Using `tool_choice: {"type": "any"}` or `tool_choice: {"type": "tool", "name": "..."}` will result in an error because these options force tool use, which is incompatible with extended thinking.
2. **Preserving thinking blocks**: During tool use, you must pass `thinking` blocks back to the API for the last assistant message. Include the complete unmodified block back to the API to maintain reasoning continuity.
### Toggling thinking modes in conversations
You can't toggle thinking in the middle of an assistant turn, including during tool use loops. The entire assistant turn should operate in a single thinking mode:
- **If thinking is enabled**, the final assistant turn should start with a thinking block.
- **If thinking is disabled**, the final assistant turn shouldn't contain any thinking blocks
From the model's perspective, **tool use loops are part of the assistant turn**. An assistant turn doesn't complete until Claude finishes its full response, which may include multiple tool calls and results.
For example, this sequence is all part of a **single assistant turn**:
```text
User: "What's the weather in Paris?"
Assistant: [thinking] + [tool_use: get_weather]
User: [tool_result: "20°C, sunny"]
Assistant: [text: "The weather in Paris is 20°C and sunny"]
```
Even though there are multiple API messages, the tool use loop is conceptually part of one continuous assistant response.
#### Graceful thinking degradation
When a mid-turn thinking conflict occurs (such as toggling thinking on or off during a tool use loop), the API automatically disables thinking for that request. To preserve model quality and remain on-distribution, the API may:
- Strip thinking blocks from the conversation when they would create an invalid turn structure
- Disable thinking for the current request when the conversation history is incompatible with thinking being enabled
This means that attempting to toggle thinking mid-turn won't cause an error, but thinking will be silently disabled for that request. To confirm whether thinking was active, check for the presence of `thinking` blocks in the response.
#### Practical guidance
**Best practice**: Plan your thinking strategy at the start of each turn rather than trying to toggle mid-turn.
**Example: Toggling thinking after completing a turn**
```text
User: "What's the weather?"
Assistant: [tool_use] (thinking disabled)
User: [tool_result]
Assistant: [text: "It's sunny"]
User: "What about tomorrow?"
Assistant: [thinking] + [text: "..."] (thinking enabled - new turn)
```
By completing the assistant turn before toggling thinking, you ensure that thinking is actually enabled for the new request.
<Note>
Toggling thinking modes also invalidates prompt caching for message history. For more details, see the [Extended thinking with prompt caching](#extended-thinking-with-prompt-caching) section.
</Note>
<section title="Example: Passing thinking blocks with tool results">
Here's a practical example showing how to preserve thinking blocks when providing tool results:
<CodeGroup>
```bash CLI
ant messages create --transform content <<'YAML'
model: claude-sonnet-4-6
max_tokens: 16000
thinking:
type: enabled
budget_tokens: 10000
tools:
- name: get_weather
description: Get current weather for a location
input_schema:
type: object
properties:
location:
type: string
required:
- location
messages:
- role: user
content: "What's the weather in Paris?"
YAML
```
```python Python
weather_tool = {
"name": "get_weather",
"description": "Get current weather for a location",
"input_schema": {
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"],
},
}
# First request - Claude responds with thinking and tool request
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
tools=[weather_tool],
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)
```
```typescript TypeScript
const weatherTool: Anthropic.Tool = {
name: "get_weather",
description: "Get current weather for a location",
input_schema: {
type: "object",
properties: {
location: { type: "string" }
},
required: ["location"]
}
};
// First request - Claude responds with thinking and tool request
const response = await client.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 16000,
thinking: {
type: "enabled",
budget_tokens: 10000
},
tools: [weatherTool],
messages: [{ role: "user", content: "What's the weather in Paris?" }]
});
```
```csharp C#
using System;
using System.Text.Json;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages;
class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new();
var weatherTool = new ToolUnion(new Tool()
{
Name = "get_weather",
Description = "Get current weather for a location",
InputSchema = new InputSchema()
{
Properties = new Dictionary<string, JsonElement>
{
["location"] = JsonSerializer.SerializeToElement(new { type = "string" }),
},
Required = ["location"],
},
});
var parameters = new MessageCreateParams
{
Model = Model.ClaudeSonnet4_6,
MaxTokens = 16000,
Thinking = new ThinkingConfigEnabled(budgetTokens: 10000),
Tools = [weatherTool],
Messages = [new() { Role = Role.User, Content = "What's the weather in Paris?" }]
};
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()
weatherTool := anthropic.ToolUnionParam{
OfTool: &anthropic.ToolParam{
Name: "get_weather",
Description: anthropic.String("Get current weather for a location"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"location": map[string]any{
"type": "string",
},
},
Required: []string{"location"},
},
},
}
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.Model("claude-sonnet-4-6"),
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(10000),
Tools: []anthropic.ToolUnionParam{weatherTool},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in Paris?")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
}
```
```java Java hidelines={1..12,-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.Tool;
import com.anthropic.core.JsonValue;
import java.util.List;
import java.util.Map;
public class ExtendedThinkingWithTools {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_4_6)
.maxTokens(16000L)
.enabledThinking(10000L)
.addTool(Tool.builder()
.name("get_weather")
.description("Get current weather for a location")
.inputSchema(Tool.InputSchema.builder()
.properties(JsonValue.from(Map.of(
"location", Map.of("type", "string")
)))
.putAdditionalProperty("required", JsonValue.from(List.of("location")))
.build())
.build())
.addUserMessage("What's the weather in Paris?")
.build();
Message response = client.messages().create(params);
System.out.println(response);
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$weatherTool = [
'name' => 'get_weather',
'description' => 'Get current weather for a location',
'input_schema' => [
'type' => 'object',
'properties' => [
'location' => ['type' => 'string']
],
'required' => ['location']
]
];
$message = $client->messages->create(
maxTokens: 16000,
messages: [
['role' => 'user', 'content' => "What's the weather in Paris?"]
],
model: 'claude-sonnet-4-6',
thinking: ['type' => 'enabled', 'budget_tokens' => 10000],
tools: [$weatherTool],
);
echo $message;
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
weather_tool = {
name: "get_weather",
description: "Get current weather for a location",
input_schema: {
type: "object",
properties: {
location: { type: "string" }
},
required: ["location"]
}
}
message = client.messages.create(
model: "claude-sonnet-4-6",
max_tokens: 16000,
thinking: {
type: "enabled",
budget_tokens: 10000
},
tools: [weather_tool],
messages: [
{ role: "user", content: "What's the weather in Paris?" }
]
)
puts message
```
</CodeGroup>
The API response includes thinking, text, and tool_use blocks:
```json Output
{
"content": [
{
"type": "thinking",
"thinking": "The user wants to know the current weather in Paris. I have access to a function `get_weather`...",
"signature": "BDaL4VrbR2Oj0hO4XpJxT28J5TILnCrrUXoKiiNBZW9P+nr8XSj1zuZzAl4egiCCpQNvfyUuFFJP5CncdYZEQPPmLxYsNrcs...."
},
{
"type": "text",
"text": "I can help you get the current weather information for Paris. Let me check that for you"
},
{
"type": "tool_use",
"id": "toolu_01CswdEQBMshySk6Y9DFKrfq",
"name": "get_weather",
"input": {
"location": "Paris"
}
}
]
}
```
Now let's continue the conversation and use the tool
<CodeGroup>
```bash CLI
# First turn: capture the assistant content array (thinking + tool_use,
# with signatures intact) as compact JSON.
ASSISTANT_CONTENT=$(ant messages create \
--transform content <<'YAML'
model: claude-sonnet-4-6
max_tokens: 16000
thinking:
type: enabled
budget_tokens: 10000
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
required: [location]
messages:
- role: user
content: What's the weather in Paris?
YAML
)
TOOL_USE_ID=$(printf '%s' "$ASSISTANT_CONTENT" \
| grep -o 'toolu_[A-Za-z0-9]*')
# Second turn: pass the captured blocks back as the assistant message.
# The thinking block MUST accompany the tool_use block.
ant messages create <<YAML
model: claude-sonnet-4-6
max_tokens: 16000
thinking:
type: enabled
budget_tokens: 10000
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
required: [location]
messages:
- role: user
content: What's the weather in Paris?
- role: assistant
content: $ASSISTANT_CONTENT
- role: user
content:
- type: tool_result
tool_use_id: $TOOL_USE_ID
content: "Current temperature: 88°F"
YAML
```
```python Python hidelines={1}
import anthropic
from typing import Any
client = anthropic.Anthropic()
weather_tool = {
"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"}
},
"required": ["location"],
},
}
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
tools=[weather_tool],
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)
# Extract thinking block and tool use block
thinking_block = next(
(block for block in response.content if block.type == "thinking"), None
)
tool_use_block = next(
(block for block in response.content if block.type == "tool_use"), None
)
# Call your actual weather API, here is where your actual API call would go
# Let's pretend this is what we get back
weather_data = {"temperature": 88}
# Second request - Include thinking block and tool result
# No new thinking blocks are generated in the response
continuation = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
tools=[weather_tool],
messages=[
{"role": "user", "content": "What's the weather in Paris?"},
# notice that the thinking_block is passed in as well as the tool_use_block
# if this is not passed in, an error is raised
{"role": "assistant", "content": [thinking_block, tool_use_block]},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": tool_use_block.id,
"content": f"Current temperature: {weather_data['temperature']}°F",
}
],
},
],
)
```
```typescript TypeScript nocheck
// Extract thinking block and tool use block
const thinkingBlock = response.content.find(
(block): block is Anthropic.ThinkingBlock => block.type === "thinking"
);
const toolUseBlock = response.content.find(
(block): block is Anthropic.ToolUseBlock => block.type === "tool_use"
);
// Call your actual weather API, here is where your actual API call would go
// Let's pretend this is what we get back
const weatherData = { temperature: 88 };
if (thinkingBlock && toolUseBlock) {
// Second request - Include thinking block and tool result
// No new thinking blocks are generated in the response
const continuation = await client.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 16000,
thinking: {
type: "enabled",
budget_tokens: 10000
},
tools: [weatherTool],
messages: [
{ role: "user", content: "What's the weather in Paris?" },
// notice that the thinkingBlock is passed in as well as the toolUseBlock
// if this is not passed in, an error is raised
{ role: "assistant", content: [thinkingBlock, toolUseBlock] },
{
role: "user",
content: [
{
type: "tool_result" as const,
tool_use_id: toolUseBlock.id,
content: `Current temperature: ${weatherData.temperature}°F`
}
]
}
]
});
}
```
```csharp C# nocheck
using System;
using System.Text.Json;
using System.Linq;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages;
public class Program
{
public static async Task Main(string[] args)
{
AnthropicClient client = new();
var weatherTool = new ToolUnion(new Tool()
{
Name = "get_weather",
Description = "Get current weather for a location",
InputSchema = new InputSchema()
{
Properties = new Dictionary<string, JsonElement>
{
["location"] = JsonSerializer.SerializeToElement(new { type = "string", description = "City name" }),
},
Required = ["location"],
},
});
var parameters = new MessageCreateParams
{
Model = Model.ClaudeSonnet4_6,
MaxTokens = 16000,
Thinking = new ThinkingConfigEnabled(budgetTokens: 10000),
Tools = [weatherTool],
Messages = [
new() { Role = Role.User, Content = "What is the weather in Paris?" }
]
};
var response = await client.Messages.Create(parameters);
// Extract thinking and tool_use blocks from response
var thinkingBlock = response.Content.FirstOrDefault(b => b.TryPickThinking(out _));
var toolUseBlock = response.Content.FirstOrDefault(b => b.TryPickToolUse(out _));
var weatherData = new { temperature = 88 };
// Build continuation with tool result
var continuationParams = new MessageCreateParams
{
Model = Model.ClaudeSonnet4_6,
MaxTokens = 16000,
Thinking = new ThinkingConfigEnabled(budgetTokens: 10000),
Tools = [weatherTool],
Messages = [
new() { Role = Role.User, Content = "What is the weather in Paris?" },
new() { Role = Role.Assistant, Content = response.Content },
new() { Role = Role.User, Content = new MessageParamContent(new List<ContentBlockParam>
{
new ContentBlockParam(new ToolResultBlockParam()
{
ToolUseID = toolUseBlock?.Id ?? "",
Content = $"Current temperature: {weatherData.temperature}\u00b0F"
})
})}
]
};
var continuation = await client.Messages.Create(continuationParams);
Console.WriteLine(continuation);
}
}
```
```go Go hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
weatherTool := anthropic.ToolUnionParam{
OfTool: &anthropic.ToolParam{
Name: "get_weather",
Description: anthropic.String("Get current weather for a location"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"location": map[string]any{
"type": "string",
"description": "City name",
},
},
Required: []string{"location"},
},
},
}
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.Model("claude-sonnet-4-6"),
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(10000),
Tools: []anthropic.ToolUnionParam{weatherTool},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What is the weather in Paris?")),
},
})
if err != nil {
log.Fatal(err)
}
var toolUseBlock anthropic.ToolUseBlock
for _, block := range response.Content {
switch v := block.AsAny().(type) {
case anthropic.ToolUseBlock:
toolUseBlock = v
}
}
weatherData := map[string]int{"temperature": 88}
continuation, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.Model("claude-sonnet-4-6"),
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(10000),
Tools: []anthropic.ToolUnionParam{weatherTool},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What is the weather in Paris?")),
response.ToParam(),
anthropic.NewUserMessage(
anthropic.NewToolResultBlock(toolUseBlock.ID, fmt.Sprintf("Current temperature: %d°F", weatherData["temperature"]), false),
),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(continuation)
}
```
```java Java hidelines={1..10,13..18,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
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.ToolResultBlockParam;
import com.anthropic.models.messages.ToolUseBlock;
import com.anthropic.models.messages.ToolUseBlockParam;
import com.anthropic.models.messages.ThinkingBlock;
import com.anthropic.models.messages.ThinkingBlockParam;
import com.anthropic.core.JsonValue;
import java.util.List;
import java.util.Map;
public class ExtendedThinkingToolUse {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Tool weatherTool = Tool.builder()
.name("get_weather")
.description("Get current weather for a location")
.inputSchema(Tool.InputSchema.builder()
.properties(JsonValue.from(Map.of(
"location", Map.of("type", "string", "description", "City name")
)))
.putAdditionalProperty("required", JsonValue.from(List.of("location")))
.build())
.build();
MessageCreateParams initialParams = MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_4_6)
.maxTokens(16000L)
.enabledThinking(10000L)
.addTool(weatherTool)
.addUserMessage("What is the weather in Paris?")
.build();
Message response = client.messages().create(initialParams);
ThinkingBlock thinkingBlock = null;
ToolUseBlock toolUseBlock = null;
for (var block : response.content()) {
if (block.thinking().isPresent()) {
thinkingBlock = block.thinking().get();
}
if (block.toolUse().isPresent()) {
toolUseBlock = block.toolUse().get();
}
}
int temperature = 88;
// Second request: pass back thinking block and tool result
MessageCreateParams continuationParams = MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_4_6)
.maxTokens(16000L)
.enabledThinking(10000L)
.addTool(weatherTool)
.addUserMessage("What is the weather in Paris?")
.addAssistantMessageOfBlockParams(List.of(
ContentBlockParam.ofThinking(ThinkingBlockParam.builder()
.thinking(thinkingBlock.thinking())
.signature(thinkingBlock.signature())
.build()),
ContentBlockParam.ofToolUse(ToolUseBlockParam.builder()
.id(toolUseBlock.id())
.name(toolUseBlock.name())
.input(toolUseBlock._input())
.build())
))
.addUserMessageOfBlockParams(List.of(
ContentBlockParam.ofToolResult(
ToolResultBlockParam.builder()
.toolUseId(toolUseBlock.id())
.content("Current temperature: " + temperature + "°F")
.build()
)
))
.build();
Message continuation = client.messages().create(continuationParams);
System.out.println(continuation);
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$weatherTool = [
'name' => 'get_weather',
'description' => 'Get current weather for a location',
'input_schema' => [
'type' => 'object',
'properties' => [
'location' => [
'type' => 'string',
'description' => 'City name'
]
],
'required' => ['location']
]
];
$response = $client->messages->create(
maxTokens: 16000,
messages: [
['role' => 'user', 'content' => 'What is the weather in Paris?']
],
model: 'claude-sonnet-4-6',
thinking: ['type' => 'enabled', 'budget_tokens' => 10000],
tools: [$weatherTool],
);
$thinkingBlock = null;
$toolUseBlock = null;
foreach ($response->content as $block) {
if ($block->type === 'thinking') {
$thinkingBlock = $block;
}
if ($block->type === 'tool_use') {
$toolUseBlock = $block;
}
}
$weatherData = ['temperature' => 88];
$continuation = $client->messages->create(
maxTokens: 16000,
messages: [
['role' => 'user', 'content' => 'What is the weather in Paris?'],
['role' => 'assistant', 'content' => [$thinkingBlock, $toolUseBlock]],
['role' => 'user', 'content' => [
[
'type' => 'tool_result',
'tool_use_id' => $toolUseBlock->id,
'content' => "Current temperature: {$weatherData['temperature']}°F"
]
]]
],
model: 'claude-sonnet-4-6',
thinking: ['type' => 'enabled', 'budget_tokens' => 10000],
tools: [$weatherTool],
);
echo $continuation;
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
weather_tool = {
name: "get_weather",
description: "Get current weather for a location",
input_schema: {
type: "object",
properties: {
location: { type: "string", description: "City name" }
},
required: ["location"]
}
}
response = client.messages.create(
model: "claude-sonnet-4-6",
max_tokens: 16000,
thinking: {
type: "enabled",
budget_tokens: 10000
},
tools: [weather_tool],
messages: [
{ role: "user", content: "What is the weather in Paris?" }
]
)
thinking_block = response.content.find { |block| block.type == :thinking }
tool_use_block = response.content.find { |block| block.type == :tool_use }
raise "No tool_use block found" unless tool_use_block
weather_data = { temperature: 88 }
continuation = client.messages.create(
model: "claude-sonnet-4-6",
max_tokens: 16000,
thinking: {
type: "enabled",
budget_tokens: 10000
},
tools: [weather_tool],
messages: [
{ role: "user", content: "What is the weather in Paris?" },
{ role: "assistant", content: [thinking_block, tool_use_block] },
{ role: "user", content: [
{
type: "tool_result",
tool_use_id: tool_use_block.id,
content: "Current temperature: #{weather_data[:temperature]}°F"
}
] }
]
)
puts continuation
```
</CodeGroup>
The API response now includes **only** text
```json Output
{
"content": [
{
"type": "text",
"text": "Currently in Paris, the temperature is 88°F (31°C)"
}
]
}
```
</section>
### Preserving thinking blocks
During tool use, you must pass `thinking` blocks back to the API, and you must include the complete unmodified block back to the API. This is critical for maintaining the model's reasoning flow and conversation integrity.
<Tip>
While you can omit `thinking` blocks from prior `assistant` role turns, always pass back all thinking blocks to the API for any multi-turn conversation. The API:
- Automatically filters the provided thinking blocks
- Uses the relevant thinking blocks necessary to preserve the model's reasoning
- Only bills for the input tokens for the blocks shown to Claude
</Tip>
<Note>
When toggling thinking modes during a conversation, remember that the entire assistant turn (including tool use loops) must operate in a single thinking mode. For more details, see [Toggling thinking modes in conversations](#toggling-thinking-modes-in-conversations).
</Note>
When Claude invokes tools, it is pausing its construction of a response to await external information. When tool results are returned, Claude continues building that existing response. This necessitates preserving thinking blocks during tool use, for a couple of reasons:
1. **Reasoning continuity**: The thinking blocks capture Claude's step-by-step reasoning that led to tool requests. When you post tool results, including the original thinking ensures Claude can continue its reasoning from where it left off.
2. **Context maintenance**: While tool results appear as user messages in the API structure, they're part of a continuous reasoning flow. Preserving thinking blocks maintains this conceptual flow across multiple API calls. For more information on context management, see the [guide on context windows](/docs/en/build-with-claude/context-windows).
**Important**: When providing `thinking` blocks, the entire sequence of consecutive `thinking` blocks must match the outputs generated by the model during the original request; you can't rearrange or modify the sequence of these blocks.
### Interleaved thinking
Extended thinking with tool use in Claude 4 models supports interleaved thinking, which enables Claude to think between tool calls and make more sophisticated reasoning after receiving tool results.
With interleaved thinking, Claude can:
- Reason about the results of a tool call before deciding what to do next
- Chain multiple tool calls with reasoning steps in between
- Make more nuanced decisions based on intermediate results
**Model support:**
- **[Claude Mythos Preview](https://anthropic.com/glasswing)**: Interleaved thinking happens automatically. Every inter-tool reasoning step moves into a thinking block instead of plain text, and thinking blocks are preserved across turns by default. No beta header is needed or supported.
- **Claude Opus 4.7**: Interleaved thinking is automatically enabled when using [adaptive thinking](/docs/en/build-with-claude/adaptive-thinking) (the only supported thinking mode on Opus 4.7). No beta header is needed.
- **Claude Opus 4.6**: Interleaved thinking is automatically enabled when using [adaptive thinking](/docs/en/build-with-claude/adaptive-thinking). No beta header is needed. The `interleaved-thinking-2025-05-14` beta header is **deprecated** on Opus 4.6 and is safely ignored if included.
- **Claude Sonnet 4.6**: Interleaved thinking is automatically enabled when using [adaptive thinking](/docs/en/build-with-claude/adaptive-thinking) (recommended). The `interleaved-thinking-2025-05-14` beta header with manual extended thinking (`thinking: {type: "enabled"}`) is still functional but deprecated.
- **Other Claude 4 models** (Opus 4.5, Opus 4.1, Opus 4 (deprecated), Sonnet 4.5, Sonnet 4 (deprecated)): Add [the beta header](/docs/en/api/beta-headers) `interleaved-thinking-2025-05-14` to your API request to enable interleaved thinking.
Here are some important considerations for interleaved thinking:
- With interleaved thinking, the `budget_tokens` can exceed the `max_tokens` parameter, as it represents the total budget across all thinking blocks within one assistant turn.
- Interleaved thinking is only supported for [tools used via the Messages API](/docs/en/agents-and-tools/tool-use/overview).
- Direct calls to the Claude API allow you to pass `interleaved-thinking-2025-05-14` in requests to any model, with no effect (except Opus 4.7 and Opus 4.6, where it's deprecated and safely ignored).
- On 3rd-party platforms (for example, [Amazon Bedrock](/docs/en/build-with-claude/claude-in-amazon-bedrock) and [Vertex AI](/docs/en/build-with-claude/claude-on-vertex-ai)), if you pass `interleaved-thinking-2025-05-14` to any model aside from Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4.5, Claude Opus 4.1, Opus 4 (deprecated), Sonnet 4.5, or Sonnet 4 (deprecated), your request will fail.
<section title="Tool use without interleaved thinking">
Without interleaved thinking, Claude thinks once at the start of the assistant turn. Subsequent responses after tool results continue without new thinking blocks.
```text
User: "What's the total revenue if we sold 150 units at $50 each,
and how does this compare to our average monthly revenue?"
Turn 1: [thinking] "I need to calculate 150 * $50, then check the database..."
[tool_use: calculator] { "expression": "150 * 50" }
↓ tool result: "7500"
Turn 2: [tool_use: database_query] { "query": "SELECT AVG(revenue)..." }
↑ no thinking block
↓ tool result: "5200"
Turn 3: [text] "The total revenue is $7,500, which is 44% above your
average monthly revenue of $5,200."
↑ no thinking block
```
</section>
<section title="Tool use with interleaved thinking">
With interleaved thinking enabled, Claude can think after receiving each tool result, allowing it to reason about intermediate results before continuing.
```text
User: "What's the total revenue if we sold 150 units at $50 each,
and how does this compare to our average monthly revenue?"
Turn 1: [thinking] "I need to calculate 150 * $50 first..."
[tool_use: calculator] { "expression": "150 * 50" }
↓ tool result: "7500"
Turn 2: [thinking] "Got $7,500. Now I should query the database to compare..."
[tool_use: database_query] { "query": "SELECT AVG(revenue)..." }
↑ thinking after receiving calculator result
↓ tool result: "5200"
Turn 3: [thinking] "$7,500 vs $5,200 average - that's a 44% increase..."
[text] "The total revenue is $7,500, which is 44% above your
average monthly revenue of $5,200."
↑ thinking before final answer
```
</section>
## Extended thinking with prompt caching
[Prompt caching](/docs/en/build-with-claude/prompt-caching) with thinking has several important considerations:
<Tip>
Extended thinking tasks often take longer than 5 minutes to complete. Consider using the [1-hour cache duration](/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration) to maintain cache hits across longer thinking sessions and multi-step workflows.
</Tip>
**Thinking block context removal**
- Thinking blocks from previous turns are removed from context, which can affect cache breakpoints
- When continuing conversations with tool use, thinking blocks are cached and count as input tokens when read from cache
- This creates a tradeoff: while thinking blocks don't consume context window space visually, they still count toward your input token usage when cached
- If thinking becomes disabled and you pass thinking content in the current tool use turn, the thinking content will be stripped and thinking will remain disabled for that request
**Cache invalidation patterns**
- Changes to thinking parameters (enabled/disabled or budget allocation) invalidate message cache breakpoints
- [Interleaved thinking](#interleaved-thinking) amplifies cache invalidation, as thinking blocks can occur between multiple [tool calls](#extended-thinking-with-tool-use)
- System prompts and tools remain cached despite thinking parameter changes or block removal
<Note>
While thinking blocks are removed for caching and context calculations, they must be preserved when continuing conversations with [tool use](#extended-thinking-with-tool-use), especially with [interleaved thinking](#interleaved-thinking).
</Note>
### Understanding thinking block caching behavior
When using extended thinking with tool use, thinking blocks exhibit specific caching behavior that affects token counting:
**How it works:**
1. Caching only occurs when you make a subsequent request that includes tool results
2. When the subsequent request is made, the previous conversation history (including thinking blocks) can be cached
3. These cached thinking blocks count as input tokens in your usage metrics when read from the cache
4. When a non-tool-result user block is included, all previous thinking blocks are ignored and stripped from context
**Detailed example flow:**
**Request 1:**
```text
User: "What's the weather in Paris?"
```
**Response 1:**
```text
[thinking_block_1] + [tool_use block 1]
```
**Request 2:**
```text
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
```
**Response 2:**
```text
[thinking_block_2] + [text block 2]
```
Request 2 writes a cache of the request content (not the response). The cache includes the original user message, the first thinking block, tool use block, and the tool result.
**Request 3:**
```text
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
```
For Claude Opus 4.5 and later (including Claude Opus 4.6), all previous thinking blocks are kept by default. For older models, because a non-tool-result user block was included, all previous thinking blocks are ignored. This request will be processed the same as:
```text
User: ["What's the weather in Paris?"],
Assistant: [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [text block 2],
User: [Text response, cache=True]
```
**Key points:**
- This caching behavior happens automatically, even without explicit `cache_control` markers
- This behavior is consistent whether using regular thinking or interleaved thinking
<section title="System prompt caching (preserved when thinking changes)">
<CodeGroup>
```bash CLI
# Fetch ~10 kB of Pride and Prejudice for the cached system block
curl -s https://www.gutenberg.org/cache/epub/1342/pg1342.txt \
| head -c 10000 > pride.txt
# Emit a request body for the given thinking budget. Once CONTENT1
# is populated (after the first turn), the assistant reply and a
# follow-up user message are appended so the conversation grows.
build_body() {
cat <<YAML
model: claude-sonnet-4-6
max_tokens: 20000
thinking:
type: enabled
budget_tokens: $1
system:
- type: text
text: >-
You are an AI assistant that is tasked with literary analysis.
Analyze the following text carefully.
- type: text
text: "@./pride.txt"
cache_control:
type: ephemeral
messages:
- role: user
content: Analyze the tone of this passage.
YAML
if [[ -n "${CONTENT1:-}" ]]; then
printf ' - role: assistant\n content: %s\n' "$CONTENT1"
printf ' - role: user\n'
printf ' content: Analyze the characters in this passage.\n'
fi
}
# First request (budget 4000): establishes the cache. Capture usage
# and content as two jsonl lines so the reply can be fed forward.
printf 'First request - establishing cache\n'
{
read -r USAGE1
read -r CONTENT1
} < <(build_body 4000 \
| ant messages create --transform '[usage,content]' --format jsonl)
printf 'First response usage: %s\n' "$USAGE1"
# Second request: same budget, system-prompt cache hit expected.
printf '\nSecond request - same thinking parameters (cache hit expected)\n'
USAGE2=$(build_body 4000 \
| ant messages create --transform usage --format jsonl)
printf 'Second response usage: %s\n' "$USAGE2"
# Third request: budget changed to 8000. The cached system prompt
# still hits; only message-block caching is invalidated.
printf '\nThird request - different thinking parameters (cache miss for messages)\n'
USAGE3=$(build_body 8000 \
| ant messages create --transform usage --format jsonl)
printf 'Third response usage: %s\n' "$USAGE3"
```
```python Python hidelines={1}
from anthropic import Anthropic
import requests
from bs4 import BeautifulSoup
client = Anthropic()
def fetch_article_content(url):
response = requests.get(url)
soup = BeautifulSoup(response.content, "html.parser")
# Remove script and style elements
for script in soup(["script", "style"]):
script.decompose()
# Get text
text = soup.get_text()
# Break into lines and remove leading and trailing space on each
lines = (line.strip() for line in text.splitlines())
# Break multi-headlines into a line each
chunks = (phrase.strip() for line in lines for phrase in line.split(" "))
# Drop blank lines
text = "\n".join(chunk for chunk in chunks if chunk)
return text
# Fetch the content of the article
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# Use just enough text for caching (first few chapters)
LARGE_TEXT = book_content[:10000]
SYSTEM_PROMPT = [
{
"type": "text",
"text": "You are an AI assistant that is tasked with literary analysis. Analyze the following text carefully.",
},
{"type": "text", "text": LARGE_TEXT, "cache_control": {"type": "ephemeral"}},
]
MESSAGES = [{"role": "user", "content": "Analyze the tone of this passage."}]
# First request - establish cache
print("First request - establishing cache")
response1 = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=20000,
thinking={"type": "enabled", "budget_tokens": 4000},
system=SYSTEM_PROMPT,
messages=MESSAGES,
)
print(f"First response usage: {response1.usage}")
MESSAGES.append({"role": "assistant", "content": response1.content})
MESSAGES.append({"role": "user", "content": "Analyze the characters in this passage."})
# Second request - same thinking parameters (cache hit expected)
print("\nSecond request - same thinking parameters (cache hit expected)")
response2 = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=20000,
thinking={"type": "enabled", "budget_tokens": 4000},
system=SYSTEM_PROMPT,
messages=MESSAGES,
)
print(f"Second response usage: {response2.usage}")
# Third request - different thinking parameters (cache miss for messages)
print("\nThird request - different thinking parameters (cache miss for messages)")
response3 = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=20000,
thinking={
"type": "enabled",
"budget_tokens": 8000, # Changed thinking budget
},
system=SYSTEM_PROMPT, # System prompt remains cached
messages=MESSAGES, # Messages cache is invalidated
)
print(f"Third response usage: {response3.usage}")
```
```typescript TypeScript nocheck hidelines={1}
import Anthropic from "@anthropic-ai/sdk";
import axios from "axios";
import * as cheerio from "cheerio";
const client = new Anthropic();
async function fetchArticleContent(url: string): Promise<string> {
const response = await axios.get(url);
const $ = cheerio.load(response.data);
$("script, style").remove();
let text = $.text();
const lines = text.split("\n").map((line) => line.trim());
text = lines.filter((line) => line.length > 0).join("\n");
return text;
}
async function main(): Promise<void> {
const bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt";
const bookContent = await fetchArticleContent(bookUrl);
const LARGE_TEXT = bookContent.slice(0, 10000);
const SYSTEM_PROMPT: Anthropic.TextBlockParam[] = [
{
type: "text",
text: "You are an AI assistant that is tasked with literary analysis. Analyze the following text carefully."
},
{
type: "text",
text: LARGE_TEXT,
cache_control: { type: "ephemeral" }
}
];
const messages: Anthropic.MessageParam[] = [
{ role: "user", content: "Analyze the tone of this passage." }
];
// First request - establish cache
console.log("First request - establishing cache");
const response1 = await client.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 20000,
thinking: { type: "enabled", budget_tokens: 4000 },
system: SYSTEM_PROMPT,
messages
});
console.log(`First response usage: ${JSON.stringify(response1.usage)}`);
messages.push({
role: "assistant",
content: response1.content as Anthropic.ContentBlockParam[]
});
messages.push({
role: "user",
content: "Analyze the characters in this passage."
});
// Second request - same thinking parameters (cache hit expected)
console.log("\nSecond request - same thinking parameters (cache hit expected)");
const response2 = await client.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 20000,
thinking: { type: "enabled", budget_tokens: 4000 },
system: SYSTEM_PROMPT,
messages
});
console.log(`Second response usage: ${JSON.stringify(response2.usage)}`);
// Third request - different thinking parameters (cache miss for messages)
console.log("\nThird request - different thinking parameters (cache miss for messages)");
const response3 = await client.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 20000,
thinking: { type: "enabled", budget_tokens: 8000 },
system: SYSTEM_PROMPT,
messages
});
console.log(`Third response usage: ${JSON.stringify(response3.usage)}`);
}
main();
```
```csharp C# nocheck
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Collections.Generic;
using Anthropic;
using Anthropic.Models.Messages;
public class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new();
// Fetch book content
using var httpClient = new HttpClient();
var bookContent = await httpClient.GetStringAsync("https://www.gutenberg.org/cache/epub/1342/pg1342.txt");
var largeText = bookContent.Substring(0, Math.Min(10000, bookContent.Length));
var systemPrompt = new MessageCreateParamsSystem(new List<TextBlockParam>
{
new TextBlockParam()
{
Text = "You are an AI assistant that is tasked with literary analysis. Analyze the following text carefully."
},
new TextBlockParam()
{
Text = largeText,
CacheControl = new CacheControlEphemeral(),
},
});
var messages = new List<MessageParam>
{
new() { Role = Role.User, Content = "Analyze the tone of this passage." }
};
// First request - establish cache
Console.WriteLine("First request - establishing cache");
var parameters1 = new MessageCreateParams
{
Model = Model.ClaudeSonnet4_6,
MaxTokens = 20000,
Thinking = new ThinkingConfigEnabled(budgetTokens: 4000),
System = systemPrompt,
Messages = messages
};
var response1 = await client.Messages.Create(parameters1);
Console.WriteLine($"First response usage: {response1.Usage}");
messages.Add(new() { Role = Role.Assistant, Content = response1.Content });
messages.Add(new() { Role = Role.User, Content = "Analyze the characters in this passage." });
// Second request - same thinking parameters (cache hit expected)
Console.WriteLine("\nSecond request - same thinking parameters (cache hit expected)");
var parameters2 = new MessageCreateParams
{
Model = Model.ClaudeSonnet4_6,
MaxTokens = 20000,
Thinking = new ThinkingConfigEnabled(budgetTokens: 4000),
System = systemPrompt,
Messages = messages
};
var response2 = await client.Messages.Create(parameters2);
Console.WriteLine($"Second response usage: {response2.Usage}");
// Third request - different thinking parameters (cache miss for messages)
Console.WriteLine("\nThird request - different thinking parameters (cache miss for messages)");
var parameters3 = new MessageCreateParams
{
Model = Model.ClaudeSonnet4_6,
MaxTokens = 20000,
Thinking = new ThinkingConfigEnabled(budgetTokens: 8000),
System = systemPrompt,
Messages = messages
};
var response3 = await client.Messages.Create(parameters3);
Console.WriteLine($"Third response usage: {response3.Usage}");
}
}
```
```go Go hidelines={1..15,-6..-1}
package main
import (
"context"
"fmt"
"io"
"log"
"net/http"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
// Fetch book content
resp, err := http.Get("https://www.gutenberg.org/cache/epub/1342/pg1342.txt")
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
log.Fatal(err)
}
largeText := string(body)
if len(largeText) > 10000 {
largeText = largeText[:10000]
}
systemPrompt := []anthropic.TextBlockParam{
{Text: "You are an AI assistant that is tasked with literary analysis. Analyze the following text carefully."},
{
Text: largeText,
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
}
messages := []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the tone of this passage.")),
}
// First request - establish cache
fmt.Println("First request - establishing cache")
response1, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.Model("claude-sonnet-4-6"),
MaxTokens: 20000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(4000),
System: systemPrompt,
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("First response usage: %+v\n", response1.Usage)
messages = append(messages, response1.ToParam())
messages = append(messages, anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the characters in this passage.")))
// Second request - same thinking parameters (cache hit expected)
fmt.Println("\nSecond request - same thinking parameters (cache hit expected)")
response2, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.Model("claude-sonnet-4-6"),
MaxTokens: 20000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(4000),
System: systemPrompt,
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Second response usage: %+v\n", response2.Usage)
// Third request - different thinking parameters (cache miss for messages)
fmt.Println("\nThird request - different thinking parameters (cache miss for messages)")
response3, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.Model("claude-sonnet-4-6"),
MaxTokens: 20000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(8000),
System: systemPrompt,
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Third response usage: %+v\n", response3.Usage)
}
```
```java Java hidelines={1..2,4..15,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.CacheControlEphemeral;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.TextBlockParam;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.List;
public class ThinkingCacheExample {
public static void main(String[] args) throws Exception {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Fetch book content
HttpClient httpClient = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://www.gutenberg.org/cache/epub/1342/pg1342.txt"))
.build();
HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
String bookContent = response.body();
String largeText = bookContent.substring(0, Math.min(10000, bookContent.length()));
List<TextBlockParam> systemPrompt = List.of(
TextBlockParam.builder()
.text("You are an AI assistant that is tasked with literary analysis. Analyze the following text carefully.")
.build(),
TextBlockParam.builder()
.text(largeText)
.cacheControl(CacheControlEphemeral.builder().build())
.build()
);
// First request - establish cache
System.out.println("First request - establishing cache");
MessageCreateParams params1 = MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_4_6)
.maxTokens(20000L)
.enabledThinking(4000L)
.systemOfTextBlockParams(systemPrompt)
.addUserMessage("Analyze the tone of this passage.")
.build();
Message response1 = client.messages().create(params1);
System.out.println("First response usage: " + response1.usage());
// Second request - same thinking parameters (cache hit expected)
System.out.println("\nSecond request - same thinking parameters (cache hit expected)");
MessageCreateParams params2 = MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_4_6)
.maxTokens(20000L)
.enabledThinking(4000L)
.systemOfTextBlockParams(systemPrompt)
.addUserMessage("Analyze the tone of this passage.")
.addAssistantMessageOfBlockParams(response1.content().stream()
.map(block -> block.toParam())
.collect(java.util.stream.Collectors.toList()))
.addUserMessage("Analyze the characters in this passage.")
.build();
Message response2 = client.messages().create(params2);
System.out.println("Second response usage: " + response2.usage());
// Third request - different thinking parameters (cache miss for messages)
System.out.println("\nThird request - different thinking parameters (cache miss for messages)");
MessageCreateParams params3 = MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_4_6)
.maxTokens(20000L)
.enabledThinking(8000L)
.systemOfTextBlockParams(systemPrompt)
.addUserMessage("Analyze the tone of this passage.")
.addAssistantMessageOfBlockParams(response1.content().stream()
.map(block -> block.toParam())
.collect(java.util.stream.Collectors.toList()))
.addUserMessage("Analyze the characters in this passage.")
.build();
Message response3 = client.messages().create(params3);
System.out.println("Third response usage: " + response3.usage());
}
}
```
```php PHP hidelines={1..5}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
// Fetch book content
$bookContent = file_get_contents("https://www.gutenberg.org/cache/epub/1342/pg1342.txt");
$largeText = substr($bookContent, 0, 10000);
$systemPrompt = [
[
'type' => 'text',
'text' => 'You are an AI assistant that is tasked with literary analysis. Analyze the following text carefully.'
],
[
'type' => 'text',
'text' => $largeText,
'cache_control' => ['type' => 'ephemeral']
]
];
$messages = [
['role' => 'user', 'content' => 'Analyze the tone of this passage.']
];
// First request - establish cache
echo "First request - establishing cache\n";
$response1 = $client->messages->create(
maxTokens: 20000,
messages: $messages,
model: 'claude-sonnet-4-6',
system: $systemPrompt,
thinking: ['type' => 'enabled', 'budget_tokens' => 4000],
);
echo "First response usage: " . json_encode($response1->usage) . "\n";
$messages[] = ['role' => 'assistant', 'content' => $response1->content];
$messages[] = ['role' => 'user', 'content' => 'Analyze the characters in this passage.'];
// Second request - same thinking parameters (cache hit expected)
echo "\nSecond request - same thinking parameters (cache hit expected)\n";
$response2 = $client->messages->create(
maxTokens: 20000,
messages: $messages,
model: 'claude-sonnet-4-6',
system: $systemPrompt,
thinking: ['type' => 'enabled', 'budget_tokens' => 4000],
);
echo "Second response usage: " . json_encode($response2->usage) . "\n";
// Third request - different thinking parameters (cache miss for messages)
echo "\nThird request - different thinking parameters (cache miss for messages)\n";
$response3 = $client->messages->create(
maxTokens: 20000,
messages: $messages,
model: 'claude-sonnet-4-6',
system: $systemPrompt,
thinking: ['type' => 'enabled', 'budget_tokens' => 8000],
);
echo "Third response usage: " . json_encode($response3->usage) . "\n";
```
```ruby Ruby hidelines={1}
require "anthropic"
require "net/http"
require "uri"
client = Anthropic::Client.new
# Fetch book content
uri = URI("https://www.gutenberg.org/cache/epub/1342/pg1342.txt")
response = Net::HTTP.get_response(uri)
book_content = response.body
large_text = book_content[0...10000]
system_prompt = [
{
type: "text",
text: "You are an AI assistant that is tasked with literary analysis. Analyze the following text carefully."
},
{
type: "text",
text: large_text,
cache_control: { type: "ephemeral" }
}
]
messages = [
{ role: "user", content: "Analyze the tone of this passage." }
]
# First request - establish cache
puts "First request - establishing cache"
response1 = client.messages.create(
model: "claude-sonnet-4-6",
max_tokens: 20000,
thinking: {
type: "enabled",
budget_tokens: 4000
},
system: system_prompt,
messages: messages
)
puts "First response usage: #{response1.usage}"
messages << { role: "assistant", content: response1.content }
messages << { role: "user", content: "Analyze the characters in this passage." }
# Second request - same thinking parameters (cache hit expected)
puts "\nSecond request - same thinking parameters (cache hit expected)"
response2 = client.messages.create(
model: "claude-sonnet-4-6",
max_tokens: 20000,
thinking: {
type: "enabled",
budget_tokens: 4000
},
system: system_prompt,
messages: messages
)
puts "Second response usage: #{response2.usage}"
# Third request - different thinking parameters (cache miss for messages)
puts "\nThird request - different thinking parameters (cache miss for messages)"
response3 = client.messages.create(
model: "claude-sonnet-4-6",
max_tokens: 20000,
thinking: {
type: "enabled",
budget_tokens: 8000
},
system: system_prompt,
messages: messages
)
puts "Third response usage: #{response3.usage}"
```
</CodeGroup>
</section>
<section title="Messages caching (invalidated when thinking changes)">
<CodeGroup>
```bash CLI
# Fetch the first ~10 kB of Pride and Prejudice for the cached prefix
curl -sL 'https://www.gutenberg.org/cache/epub/1342/pg1342.txt' \
| head -c 10000 > book.txt
# Call 1: thinking budget 4000, writes the cache
USAGE=$(ant messages create \
--model claude-sonnet-4-6 --max-tokens 20000 \
--transform usage <<'YAML'
thinking:
type: enabled
budget_tokens: 4000
messages:
- role: user
content:
- type: text
text: "@./book.txt"
cache_control:
type: ephemeral
- type: text
text: "Give a one-sentence summary of this passage."
YAML
)
printf 'Call 1 (budget 4000):\n%s\n\n' "$USAGE"
# Call 2: same budget, conversation extended; expect cache HIT
USAGE=$(ant messages create \
--model claude-sonnet-4-6 --max-tokens 20000 \
--transform usage <<'YAML'
thinking:
type: enabled
budget_tokens: 4000
messages:
- role: user
content:
- type: text
text: "@./book.txt"
cache_control:
type: ephemeral
- type: text
text: "Give a one-sentence summary of this passage."
- role: assistant
content: "It opens Pride and Prejudice with the Bennet family."
- role: user
content: "Who is the protagonist?"
YAML
)
printf 'Call 2 (budget 4000):\n%s\n\n' "$USAGE"
# Call 3: budget changed to 8000; cache MISS even though prefix is identical
USAGE=$(ant messages create \
--model claude-sonnet-4-6 --max-tokens 20000 \
--transform usage <<'YAML'
thinking:
type: enabled
budget_tokens: 8000
messages:
- role: user
content:
- type: text
text: "@./book.txt"
cache_control:
type: ephemeral
- type: text
text: "Give a one-sentence summary of this passage."
- role: assistant
content: "It opens Pride and Prejudice with the Bennet family."
- role: user
content: "Who is the protagonist?"
- role: assistant
content: "Elizabeth Bennet is the protagonist."
- role: user
content: "What era is the story set in?"
YAML
)
printf 'Call 3 (budget 8000):\n%s\n' "$USAGE"
```
```python Python hidelines={1}
from anthropic import Anthropic
import requests
from bs4 import BeautifulSoup
client = Anthropic()
def fetch_article_content(url):
response = requests.get(url)
soup = BeautifulSoup(response.content, "html.parser")
# Remove script and style elements
for script in soup(["script", "style"]):
script.decompose()
# Get text
text = soup.get_text()
# Break into lines and remove leading and trailing space on each
lines = (line.strip() for line in text.splitlines())
# Break multi-headlines into a line each
chunks = (phrase.strip() for line in lines for phrase in line.split(" "))
# Drop blank lines
text = "\n".join(chunk for chunk in chunks if chunk)
return text
# Fetch the content of the article
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# Use just enough text for caching (first few chapters)
LARGE_TEXT = book_content[:10000]
# No system prompt - caching in messages instead
MESSAGES = [
{
"role": "user",
"content": [
{
"type": "text",
"text": LARGE_TEXT,
"cache_control": {"type": "ephemeral"},
},
{"type": "text", "text": "Analyze the tone of this passage."},
],
}
]
# First request - establish cache
print("First request - establishing cache")
response1 = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=20000,
thinking={"type": "enabled", "budget_tokens": 4000},
messages=MESSAGES,
)
print(f"First response usage: {response1.usage}")
MESSAGES.append({"role": "assistant", "content": response1.content})
MESSAGES.append({"role": "user", "content": "Analyze the characters in this passage."})
# Second request - same thinking parameters (cache hit expected)
print("\nSecond request - same thinking parameters (cache hit expected)")
response2 = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=20000,
thinking={
"type": "enabled",
"budget_tokens": 4000, # Same thinking budget
},
messages=MESSAGES,
)
print(f"Second response usage: {response2.usage}")
MESSAGES.append({"role": "assistant", "content": response2.content})
MESSAGES.append({"role": "user", "content": "Analyze the setting in this passage."})
# Third request - different thinking budget (cache miss expected)
print("\nThird request - different thinking budget (cache miss expected)")
response3 = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=20000,
thinking={
"type": "enabled",
"budget_tokens": 8000, # Different thinking budget breaks cache
},
messages=MESSAGES,
)
print(f"Third response usage: {response3.usage}")
```
```typescript TypeScript nocheck hidelines={1}
import Anthropic from "@anthropic-ai/sdk";
import axios from "axios";
import * as cheerio from "cheerio";
const client = new Anthropic();
async function fetchArticleContent(url: string): Promise<string> {
const response = await axios.get(url);
const $ = cheerio.load(response.data);
// Remove script and style elements
$("script, style").remove();
// Get text
let text = $.text();
// Clean up text (break into lines, remove whitespace)
const lines = text.split("\n").map((line) => line.trim());
const chunks = lines.flatMap((line) => line.split(" ").map((phrase) => phrase.trim()));
text = chunks.filter((chunk) => chunk).join("\n");
return text;
}
async function main(): Promise<void> {
const bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt";
const bookContent = await fetchArticleContent(bookUrl);
const LARGE_TEXT = bookContent.substring(0, 10000);
// No system prompt - caching in messages instead
const messages: Anthropic.MessageParam[] = [
{
role: "user",
content: [
{
type: "text",
text: LARGE_TEXT,
cache_control: { type: "ephemeral" }
},
{
type: "text",
text: "Analyze the tone of this passage."
}
]
}
];
// First request - establish cache
console.log("First request - establishing cache");
const response1 = await client.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 20000,
thinking: { type: "enabled", budget_tokens: 4000 },
messages
});
console.log("First response usage: ", response1.usage);
messages.push(
{ role: "assistant", content: response1.content as Anthropic.ContentBlockParam[] },
{ role: "user", content: "Analyze the characters in this passage." }
);
// Second request - same thinking parameters (cache hit expected)
console.log("\nSecond request - same thinking parameters (cache hit expected)");
const response2 = await client.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 20000,
thinking: { type: "enabled", budget_tokens: 4000 },
messages
});
console.log("Second response usage: ", response2.usage);
messages.push(
{ role: "assistant", content: response2.content as Anthropic.ContentBlockParam[] },
{ role: "user", content: "Analyze the setting in this passage." }
);
// Third request - different thinking budget (cache miss expected)
console.log("\nThird request - different thinking budget (cache miss expected)");
const response3 = await client.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 20000,
thinking: { type: "enabled", budget_tokens: 8000 },
messages
});
console.log("Third response usage: ", response3.usage);
}
main().catch(console.error);
```
```csharp C# nocheck
using System;
using System.Net.Http;
using System.Collections.Generic;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages;
public class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new();
string bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt";
string bookContent = await FetchArticleContent(bookUrl);
string largeText = bookContent.Substring(0, Math.Min(10000, bookContent.Length));
Console.WriteLine("First request - establishing cache");
var parameters1 = new MessageCreateParams
{
Model = Model.ClaudeSonnet4_6,
MaxTokens = 20000,
Thinking = new ThinkingConfigEnabled(budgetTokens: 4000),
Messages =
[
new()
{
Role = Role.User,
Content = new MessageParamContent(new List<ContentBlockParam>
{
new ContentBlockParam(new TextBlockParam()
{
Text = largeText,
CacheControl = new CacheControlEphemeral(),
}),
new ContentBlockParam(new TextBlockParam()
{
Text = "Analyze the tone of this passage."
}),
})
}
]
};
var response1 = await client.Messages.Create(parameters1);
Console.WriteLine($"First response usage: {response1.Usage}");
Console.WriteLine("\nSecond request - same thinking parameters (cache hit expected)");
var parameters2 = new MessageCreateParams
{
Model = Model.ClaudeSonnet4_6,
MaxTokens = 20000,
Thinking = new ThinkingConfigEnabled(budgetTokens: 4000),
Messages =
[
new()
{
Role = Role.User,
Content = new MessageParamContent(new List<ContentBlockParam>
{
new ContentBlockParam(new TextBlockParam()
{
Text = largeText,
CacheControl = new CacheControlEphemeral(),
}),
new ContentBlockParam(new TextBlockParam()
{
Text = "Analyze the tone of this passage."
}),
})
},
new()
{
Role = Role.Assistant,
Content = response1.Content
},
new()
{
Role = Role.User,
Content = "Analyze the characters in this passage."
}
]
};
var response2 = await client.Messages.Create(parameters2);
Console.WriteLine($"Second response usage: {response2.Usage}");
Console.WriteLine("\nThird request - different thinking budget (cache miss expected)");
var parameters3 = new MessageCreateParams
{
Model = Model.ClaudeSonnet4_6,
MaxTokens = 20000,
Thinking = new ThinkingConfigEnabled(budgetTokens: 8000),
Messages =
[
new()
{
Role = Role.User,
Content = new MessageParamContent(new List<ContentBlockParam>
{
new ContentBlockParam(new TextBlockParam()
{
Text = largeText,
CacheControl = new CacheControlEphemeral(),
}),
new ContentBlockParam(new TextBlockParam()
{
Text = "Analyze the tone of this passage."
}),
})
},
new()
{
Role = Role.Assistant,
Content = response1.Content
},
new()
{
Role = Role.User,
Content = "Analyze the characters in this passage."
},
new()
{
Role = Role.Assistant,
Content = response2.Content
},
new()
{
Role = Role.User,
Content = "Analyze the setting in this passage."
}
]
};
var response3 = await client.Messages.Create(parameters3);
Console.WriteLine($"Third response usage: {response3.Usage}");
}
static async Task<string> FetchArticleContent(string url)
{
using HttpClient httpClient = new();
string content = await httpClient.GetStringAsync(url);
return content;
}
}
```
```go Go hidelines={1..41,-1}
package main
import (
"context"
"fmt"
"io"
"log"
"net/http"
"strings"
"github.com/anthropics/anthropic-sdk-go"
)
func fetchArticleContent(url string) (string, error) {
resp, err := http.Get(url)
if err != nil {
return "", err
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
return "", err
}
text := string(body)
lines := strings.Split(text, "\n")
var cleanedLines []string
for _, line := range lines {
trimmed := strings.TrimSpace(line)
if trimmed != "" {
cleanedLines = append(cleanedLines, trimmed)
}
}
return strings.Join(cleanedLines, "\n"), nil
}
func main() {
client := anthropic.NewClient()
bookURL := "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
bookContent, err := fetchArticleContent(bookURL)
if err != nil {
log.Fatal(err)
}
largeText := bookContent
if len(largeText) > 10000 {
largeText = largeText[:10000]
}
// No system prompt - caching in messages instead
messages := []anthropic.MessageParam{
anthropic.NewUserMessage(
anthropic.ContentBlockParamUnion{OfText: &anthropic.TextBlockParam{
Text: largeText,
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}},
anthropic.NewTextBlock("Analyze the tone of this passage."),
),
}
// First request - establish cache
fmt.Println("First request - establishing cache")
response1, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.Model("claude-sonnet-4-6"),
MaxTokens: 20000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(4000),
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("First response usage: %+v\n", response1.Usage)
messages = append(messages, response1.ToParam())
messages = append(messages, anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the characters in this passage.")))
// Second request - same thinking parameters (cache hit expected)
fmt.Println("\nSecond request - same thinking parameters (cache hit expected)")
response2, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.Model("claude-sonnet-4-6"),
MaxTokens: 20000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(4000),
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Second response usage: %+v\n", response2.Usage)
messages = append(messages, response2.ToParam())
messages = append(messages, anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the setting in this passage.")))
// Third request - different thinking budget (cache miss expected)
fmt.Println("\nThird request - different thinking budget (cache miss expected)")
response3, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.Model("claude-sonnet-4-6"),
MaxTokens: 20000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(8000),
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Third response usage: %+v\n", response3.Usage)
}
```
```java Java hidelines={1..2,4..16,94..95,-1}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.CacheControlEphemeral;
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.TextBlockParam;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.List;
public class CachingThinkingExample {
public static void main(String[] args) throws Exception {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
String bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt";
String bookContent = fetchArticleContent(bookUrl);
String largeText = bookContent.substring(0, Math.min(10000, bookContent.length()));
// First request - establishing cache
System.out.println("First request - establishing cache");
MessageCreateParams params1 = MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_4_6)
.maxTokens(20000L)
.enabledThinking(4000L)
.addUserMessageOfBlockParams(List.of(
ContentBlockParam.ofText(TextBlockParam.builder()
.text(largeText)
.cacheControl(CacheControlEphemeral.builder().build())
.build()),
ContentBlockParam.ofText(TextBlockParam.builder()
.text("Analyze the tone of this passage.")
.build())
))
.build();
Message response1 = client.messages().create(params1);
System.out.println("First response usage: " + response1.usage());
// Second request - same thinking parameters (cache hit expected)
System.out.println("\nSecond request - same thinking parameters (cache hit expected)");
MessageCreateParams params2 = MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_4_6)
.maxTokens(20000L)
.enabledThinking(4000L)
.addUserMessageOfBlockParams(List.of(
ContentBlockParam.ofText(TextBlockParam.builder()
.text(largeText)
.cacheControl(CacheControlEphemeral.builder().build())
.build()),
ContentBlockParam.ofText(TextBlockParam.builder()
.text("Analyze the tone of this passage.")
.build())
))
.addAssistantMessageOfBlockParams(response1.content().stream()
.map(block -> block.toParam())
.collect(java.util.stream.Collectors.toList()))
.addUserMessage("Analyze the characters in this passage.")
.build();
Message response2 = client.messages().create(params2);
System.out.println("Second response usage: " + response2.usage());
// Third request - different thinking budget (cache miss expected)
System.out.println("\nThird request - different thinking budget (cache miss expected)");
MessageCreateParams params3 = MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_4_6)
.maxTokens(20000L)
.enabledThinking(8000L)
.addUserMessageOfBlockParams(List.of(
ContentBlockParam.ofText(TextBlockParam.builder()
.text(largeText)
.cacheControl(CacheControlEphemeral.builder().build())
.build()),
ContentBlockParam.ofText(TextBlockParam.builder()
.text("Analyze the tone of this passage.")
.build())
))
.addAssistantMessageOfBlockParams(response1.content().stream()
.map(block -> block.toParam())
.collect(java.util.stream.Collectors.toList()))
.addUserMessage("Analyze the characters in this passage.")
.addAssistantMessageOfBlockParams(response2.content().stream()
.map(block -> block.toParam())
.collect(java.util.stream.Collectors.toList()))
.addUserMessage("Analyze the setting in this passage.")
.build();
Message response3 = client.messages().create(params3);
System.out.println("Third response usage: " + response3.usage());
}
private static String fetchArticleContent(String url) throws Exception {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
return response.body();
}
}
```
```php PHP hidelines={1..6}
<?php
use Anthropic\Client;
function fetchArticleContent($url) {
$content = file_get_contents($url);
$lines = explode("\n", $content);
$cleanedLines = array_filter(array_map('trim', $lines));
return implode("\n", $cleanedLines);
}
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt";
$bookContent = fetchArticleContent($bookUrl);
$largeText = substr($bookContent, 0, 10000);
echo "First request - establishing cache\n";
$response1 = $client->messages->create(
maxTokens: 20000,
messages: [[
'role' => 'user',
'content' => [
[
'type' => 'text',
'text' => $largeText,
'cache_control' => ['type' => 'ephemeral']
],
[
'type' => 'text',
'text' => 'Analyze the tone of this passage.'
]
]
]],
model: 'claude-sonnet-4-6',
thinking: ['type' => 'enabled', 'budget_tokens' => 4000],
);
echo "First response usage: " . json_encode($response1->usage) . "\n";
echo "\nSecond request - same thinking parameters (cache hit expected)\n";
$response2 = $client->messages->create(
maxTokens: 20000,
messages: [
[
'role' => 'user',
'content' => [
[
'type' => 'text',
'text' => $largeText,
'cache_control' => ['type' => 'ephemeral']
],
[
'type' => 'text',
'text' => 'Analyze the tone of this passage.'
]
]
],
[
'role' => 'assistant',
'content' => $response1->content
],
[
'role' => 'user',
'content' => 'Analyze the characters in this passage.'
]
],
model: 'claude-sonnet-4-6',
thinking: ['type' => 'enabled', 'budget_tokens' => 4000],
);
echo "Second response usage: " . json_encode($response2->usage) . "\n";
echo "\nThird request - different thinking budget (cache miss expected)\n";
$response3 = $client->messages->create(
maxTokens: 20000,
messages: [
[
'role' => 'user',
'content' => [
[
'type' => 'text',
'text' => $largeText,
'cache_control' => ['type' => 'ephemeral']
],
[
'type' => 'text',
'text' => 'Analyze the tone of this passage.'
]
]
],
[
'role' => 'assistant',
'content' => $response1->content
],
[
'role' => 'user',
'content' => 'Analyze the characters in this passage.'
],
[
'role' => 'assistant',
'content' => $response2->content
],
[
'role' => 'user',
'content' => 'Analyze the setting in this passage.'
]
],
model: 'claude-sonnet-4-6',
thinking: ['type' => 'enabled', 'budget_tokens' => 8000],
);
echo "Third response usage: " . json_encode($response3->usage) . "\n";
```
```ruby Ruby hidelines={1}
require "anthropic"
require "net/http"
require "uri"
def fetch_article_content(url)
uri = URI.parse(url)
response = Net::HTTP.get_response(uri)
text = response.body
lines = text.split("\n").map(&:strip)
lines.reject(&:empty?).join("\n")
end
client = Anthropic::Client.new
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
large_text = book_content[0...10000]
puts "First request - establishing cache"
response1 = client.messages.create(
model: "claude-sonnet-4-6",
max_tokens: 20000,
thinking: {
type: "enabled",
budget_tokens: 4000
},
messages: [{
role: "user",
content: [
{
type: "text",
text: large_text,
cache_control: { type: "ephemeral" }
},
{
type: "text",
text: "Analyze the tone of this passage."
}
]
}]
)
puts "First response usage: #{response1.usage}"
puts "\nSecond request - same thinking parameters (cache hit expected)"
response2 = client.messages.create(
model: "claude-sonnet-4-6",
max_tokens: 20000,
thinking: {
type: "enabled",
budget_tokens: 4000
},
messages: [
{
role: "user",
content: [
{
type: "text",
text: large_text,
cache_control: { type: "ephemeral" }
},
{
type: "text",
text: "Analyze the tone of this passage."
}
]
},
{
role: "assistant",
content: response1.content
},
{
role: "user",
content: "Analyze the characters in this passage."
}
]
)
puts "Second response usage: #{response2.usage}"
puts "\nThird request - different thinking budget (cache miss expected)"
response3 = client.messages.create(
model: "claude-sonnet-4-6",
max_tokens: 20000,
thinking: {
type: "enabled",
budget_tokens: 8000
},
messages: [
{
role: "user",
content: [
{
type: "text",
text: large_text,
cache_control: { type: "ephemeral" }
},
{
type: "text",
text: "Analyze the tone of this passage."
}
]
},
{
role: "assistant",
content: response1.content
},
{
role: "user",
content: "Analyze the characters in this passage."
},
{
role: "assistant",
content: response2.content
},
{
role: "user",
content: "Analyze the setting in this passage."
}
]
)
puts "Third response usage: #{response3.usage}"
```
</CodeGroup>
Here is the output of the script (you may see slightly different numbers)
```text Output
First request - establishing cache
First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }
Second request - same thinking parameters (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }
Third request - different thinking budget (cache miss expected)
Third response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }
```
This example demonstrates that when caching is set up in the messages array, changing the thinking parameters (budget_tokens increased from 4000 to 8000) **invalidates the cache**. The third request shows no cache hit with `cache_creation_input_tokens=1370` and `cache_read_input_tokens=0`, proving that message-based caching is invalidated when thinking parameters change.
</section>
## Max tokens and context window size with extended thinking
In older Claude models (prior to Claude Sonnet 3.7), if the sum of prompt tokens and `max_tokens` exceeded the model's context window, the system would automatically adjust `max_tokens` to fit within the context limit. This meant you could set a large `max_tokens` value and the system would silently reduce it as needed.
With Claude 3.7 and 4 models, `max_tokens` (which includes your thinking budget when thinking is enabled) is enforced as a strict limit. The system will now return a validation error if prompt tokens + `max_tokens` exceeds the context window size.
<Note>
You can read through the [guide on context windows](/docs/en/build-with-claude/context-windows) for a more thorough deep dive.
</Note>
### The context window with extended thinking
When calculating context window usage with thinking enabled, there are some considerations to be aware of:
- Thinking blocks from previous turns are stripped and not counted towards your context window
- Current turn thinking counts towards your `max_tokens` limit for that turn
The diagram below demonstrates the specialized token management when extended thinking is enabled:
The effective context window is calculated as:
```text
context window =
(current input tokens - previous thinking tokens) +
(thinking tokens + encrypted thinking tokens + text output tokens)
```
Use the [token counting API](/docs/en/build-with-claude/token-counting) to get accurate token counts for your specific use case, especially when working with multi-turn conversations that include thinking.
### The context window with extended thinking and tool use
When using extended thinking with tool use, thinking blocks must be explicitly preserved and returned with the tool results.
The effective context window calculation for extended thinking with tool use becomes:
```text
context window =
(current input tokens + previous thinking tokens + tool use tokens) +
(thinking tokens + encrypted thinking tokens + text output tokens)
```
The diagram below illustrates token management for extended thinking with tool use:
### Managing tokens with extended thinking
Given the context window and `max_tokens` behavior with extended thinking Claude 3.7 and 4 models, you may need to:
- More actively monitor and manage your token usage
- Adjust `max_tokens` values as your prompt length changes
- Potentially use the [token counting endpoints](/docs/en/build-with-claude/token-counting) more frequently
- Be aware that previous thinking blocks don't accumulate in your context window
This change has been made to provide more predictable and transparent behavior, especially as maximum token limits have increased significantly.
## Thinking encryption
Full thinking content is encrypted and returned in the `signature` field. This field is used to verify that thinking blocks were generated by Claude when passed back to the API.
<Note>
It is only strictly necessary to send back thinking blocks when using [tools with extended thinking](/docs/en/build-with-claude/extended-thinking#extended-thinking-with-tool-use). Otherwise you can omit thinking blocks from previous turns, or let the API strip them for you if you pass them back.
If sending back thinking blocks, we recommend passing everything back as you received it for consistency and to avoid potential issues.
</Note>
Here are some important considerations on thinking encryption:
- When [streaming responses](/docs/en/build-with-claude/extended-thinking#streaming-thinking), the signature is added via a `signature_delta` inside a `content_block_delta` event just before the `content_block_stop` event.
- `signature` values are significantly longer in Claude 4 models than in previous models.
- The `signature` field is an opaque field and should not be interpreted or parsed.
- `signature` values are compatible across platforms (Claude APIs, [Amazon Bedrock](/docs/en/build-with-claude/claude-in-amazon-bedrock), and [Vertex AI](/docs/en/build-with-claude/claude-on-vertex-ai)). Values generated on one platform will be compatible with another.
## Redacted thinking blocks
In addition to regular `thinking` blocks, the API may return `redacted_thinking` blocks. A `redacted_thinking` block contains encrypted thinking content in a `data` field, with no readable summary:
```json
{
"type": "redacted_thinking",
"data": "..."
}
```
The `data` field is opaque and encrypted. Like the `signature` field on regular thinking blocks, you should pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation with [tools](/docs/en/build-with-claude/extended-thinking#extended-thinking-with-tool-use).
<Tip>
If your code filters content blocks by type (for example, `block.type == "thinking"`) when round-tripping responses with tool use, also include `redacted_thinking` blocks. Filtering on `block.type == "thinking"` alone silently drops `redacted_thinking` blocks and breaks the multi-turn protocol described above.
</Tip>
<Note>
`redacted_thinking` blocks are a distinct content block type returned by the API when portions of thinking are safety-redacted. This is separate from the [`display: "omitted"`](#controlling-thinking-display) option, which returns regular `thinking` blocks with an empty `thinking` field.
</Note>
## Differences in thinking across model versions
The Messages API handles thinking differently across Claude Sonnet 3.7 and Claude 4 models, primarily in summarization behavior.
See the table below for a condensed comparison:
| Feature | Claude Sonnet 3.7 | Claude 4 Models (pre-Opus 4.5) | Claude Opus 4.5 | Claude Sonnet 4.6 | Claude Opus 4.6 ([adaptive thinking](/docs/en/build-with-claude/adaptive-thinking)) | [Claude Mythos Preview](https://anthropic.com/glasswing) ([adaptive thinking](/docs/en/build-with-claude/adaptive-thinking)) |
|---------|------------------|-------------------------------|--------------------------|------------------|--------------------------|--------------------------|
| **Thinking Output** | Returns full thinking output | Returns summarized thinking | Returns summarized thinking | Returns summarized thinking | Returns summarized thinking | Omitted by default; set `display: "summarized"` to receive summarized thinking. Raw thinking tokens are never returned. |
| **Interleaved Thinking** | Not supported | Supported with `interleaved-thinking-2025-05-14` beta header | Supported with `interleaved-thinking-2025-05-14` beta header | Supported with `interleaved-thinking-2025-05-14` beta header or automatic with [adaptive thinking](/docs/en/build-with-claude/adaptive-thinking) | Automatic with adaptive thinking (beta header not supported) | Automatic with adaptive thinking (beta header not supported). Inter-tool reasoning moves into thinking blocks on this model. |
| **Thinking Block Preservation** | Not preserved across turns | Not preserved across turns | **Preserved by default** | **Preserved by default** | **Preserved by default** | **Preserved by default.** Blocks are stripped when continuing the conversation on a model that does not support the Mythos thinking format. |
### Thinking block preservation in Claude Opus 4.5 and later
Starting with Claude Opus 4.5 (and continuing in Claude Opus 4.6), **thinking blocks from previous assistant turns are preserved in model context by default**. This differs from earlier models, which remove thinking blocks from prior turns.
**Benefits of thinking block preservation:**
- **Cache optimization**: When using tool use, preserved thinking blocks enable cache hits as they are passed back with tool results and cached incrementally across the assistant turn, resulting in token savings in multi-step workflows
- **No intelligence impact**: Preserving thinking blocks has no negative effect on model performance
**Important considerations:**
- **Context usage**: Long conversations will consume more context space since thinking blocks are retained in context
- **Automatic behavior**: This is the default behavior for Claude Opus 4.5 and later models (including [Claude Mythos Preview](https://anthropic.com/glasswing) and Claude Opus 4.6). No code changes or beta headers required
- **Backward compatibility**: To leverage this feature, continue passing complete, unmodified thinking blocks back to the API as you would for tool use
<Note>
For earlier models (Claude Sonnet 4.5, Opus 4.1, etc.), thinking blocks from previous turns continue to be removed from context. The existing behavior described in the [Extended thinking with prompt caching](#extended-thinking-with-prompt-caching) section applies to those models.
</Note>
## Pricing
For complete pricing information including base rates, cache writes, cache hits, and output tokens, see the [pricing page](/docs/en/about-claude/pricing).
The thinking process incurs charges for:
- Tokens used during thinking (output tokens)
- Thinking blocks from the last assistant turn included in subsequent requests (input tokens)
- Standard text output tokens
<Note>
When extended thinking is enabled, a specialized system prompt is automatically included to support this feature.
</Note>
When using summarized thinking:
- **Input tokens:** Tokens in your original request (excludes thinking tokens from previous turns)
- **Output tokens (billed):** The original thinking tokens that Claude generated internally
- **Output tokens (visible):** The summarized thinking tokens you see in the response
- **No charge:** Tokens used to generate the summary
When using `display: "omitted"`:
- **Input tokens:** Tokens in your original request (same as summarized)
- **Output tokens (billed):** The original thinking tokens that Claude generated internally (same as summarized)
- **Output tokens (visible):** Zero thinking tokens (the `thinking` field is empty)
<Warning>
The billed output token count will **not** match the visible token count in the response. You are billed for the full thinking process, not the thinking content visible in the response.
</Warning>
## Best practices and considerations for extended thinking
### Working with thinking budgets
- **Budget optimization:** The minimum budget is 1,024 tokens. Start at the minimum and increase the thinking budget incrementally to find the optimal range for your use case. Higher token counts enable more comprehensive reasoning but with diminishing returns depending on the task. Increasing the budget can improve response quality at the tradeoff of increased latency. For critical tasks, test different settings to find the optimal balance. Note that the thinking budget is a target rather than a strict limit. Actual token usage may vary based on the task.
- **Starting points:** Start with larger thinking budgets (16k+ tokens) for complex tasks and adjust based on your needs.
- **Large budgets:** For thinking budgets above 32k, use [batch processing](/docs/en/build-with-claude/batch-processing) to avoid networking issues. Requests pushing the model to think above 32k tokens causes long running requests that might run up against system timeouts and open connection limits.
- **Token usage tracking:** Monitor thinking token usage to optimize costs and performance.
### Performance considerations
- **Response times:** Be prepared for longer response times due to additional processing. Generating thinking blocks increases overall response time.
- **Streaming requirements:** The SDKs require streaming when `max_tokens` is greater than 21,333 to avoid HTTP timeouts on long-running requests. This is a client-side validation, not an API restriction. If you don't need to process events incrementally, use `.stream()` with `.get_final_message()` (Python) or `.finalMessage()` (TypeScript) to get the complete `Message` object without handling individual events. See [Streaming Messages](/docs/en/build-with-claude/streaming#get-the-final-message-without-handling-events) for details. When streaming, be prepared to handle both thinking and text content blocks as they arrive.
- **Omitting thinking for latency:** If your application doesn't display thinking content, set `display: "omitted"` on the thinking configuration to reduce time-to-first-text-token. See [Controlling thinking display](#controlling-thinking-display).
### Feature compatibility
- Thinking isn't compatible with `temperature` or `top_k` modifications as well as [forced tool use](/docs/en/agents-and-tools/tool-use/define-tools#forcing-tool-use).
- When thinking is enabled, you can set `top_p` to values between 1 and 0.95.
- You can't pre-fill responses when thinking is enabled.
- Changes to the thinking budget invalidate cached prompt prefixes that include messages. However, cached system prompts and tool definitions will continue to work when thinking parameters change.
### Usage guidelines
- **Task selection:** Use extended thinking for particularly complex tasks that benefit from step-by-step reasoning, like math, coding, and analysis.
- **Context handling:** You don't need to remove previous thinking blocks yourself. The Claude API automatically ignores thinking blocks from previous turns and they aren't included when calculating context usage.
- **Prompt engineering:** Review the [extended thinking prompting tips](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#leverage-thinking-and-interleaved-thinking-capabilities) if you want to maximize Claude's thinking capabilities.
## Next steps
<CardGroup>
<Card title="Try the extended thinking cookbook" icon="book" href="https://platform.claude.com/cookbook/extended-thinking-extended-thinking">
Explore practical examples of thinking in the cookbook.
</Card>
<Card title="Extended thinking prompting tips" icon="code" href="/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#leverage-thinking-and-interleaved-thinking-capabilities">
Learn prompt engineering best practices for extended thinking.
</Card>
</CardGroup>
---
## Guides/build-with-claude-fast-mode-7af2fa7ffd.md
# Fast mode (beta: research preview)
Higher output speed for Claude Opus 4.6, delivering significantly faster token generation for latency-sensitive and agentic workflows.
---
Fast mode provides significantly faster output token generation for Claude Opus 4.6. By setting `speed: "fast"` in your API request, you get up to 2.5x higher output tokens per second from the same model at premium pricing.
<Note>
Fast mode is in beta (research preview). [Join the waitlist](https://claude.com/fast-mode) to request access. Availability is limited while Anthropic gathers feedback.
</Note>
<Note>
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.
</Note>
## Supported models
Fast mode is supported on the following models:
- Claude Opus 4.6 (`claude-opus-4-6`)
## How fast mode works
Fast mode runs the same model with a faster inference configuration. There is no change to intelligence or capabilities.
- Up to 2.5x higher output tokens per second compared to standard speed
- Speed benefits are focused on output tokens per second (OTPS), not time to first token (TTFT)
- Same model weights and behavior (not a different model)
## Basic usage
<CodeGroup>
```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: fast-mode-2026-02-01" \
--header "content-type: application/json" \
--data '{
"model": "claude-opus-4-6",
"max_tokens": 4096,
"speed": "fast",
"messages": [{
"role": "user",
"content": "Refactor this module to use dependency injection"
}]
}'
```
```bash CLI
ant beta:messages create \
--beta fast-mode-2026-02-01 \
--transform 'content.0.text' --format yaml <<'YAML'
model: claude-opus-4-6
max_tokens: 4096
speed: fast
messages:
- role: user
content: Refactor this module to use dependency injection
YAML
```
```python Python nocheck hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-4-6",
max_tokens=4096,
speed="fast",
betas=["fast-mode-2026-02-01"],
messages=[
{"role": "user", "content": "Refactor this module to use dependency injection"}
],
)
print(response.content[0].text)
```
```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-6",
max_tokens: 4096,
speed: "fast",
betas: ["fast-mode-2026-02-01"],
messages: [
{
role: "user",
content: "Refactor this module to use dependency injection"
}
]
});
const textBlock = response.content.find(
(block): block is Anthropic.Beta.Messages.BetaTextBlock => block.type === "text"
);
console.log(textBlock?.text);
```
```csharp C# hidelines={1..5}
using Anthropic;
using Anthropic.Models.Beta.Messages;
AnthropicClient client = new();
var response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = "claude-opus-4-6",
MaxTokens = 4096,
Speed = Speed.Fast,
Betas = ["fast-mode-2026-02-01"],
Messages = [
new() { Role = Role.User, Content = "Refactor this module to use dependency injection" }
],
});
Console.WriteLine(response);
```
```go Go hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
anthropic "github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus4_6,
MaxTokens: 4096,
Speed: anthropic.BetaMessageNewParamsSpeedFast,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFastMode2026_02_01},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Refactor this module to use dependency injection")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Content[0].AsText().Text)
}
```
```java Java hidelines={1..9,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
public class FastModeExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
BetaMessage response = client.beta().messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_6)
.maxTokens(4096L)
.speed(MessageCreateParams.Speed.FAST)
.addBeta(AnthropicBeta.FAST_MODE_2026_02_01)
.addUserMessage("Refactor this module to use dependency injection")
.build());
System.out.println(response.content().get(0).text().get().text());
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client();
$response = $client->beta->messages->create(
model: 'claude-opus-4-6',
maxTokens: 4096,
speed: 'fast',
betas: ['fast-mode-2026-02-01'],
messages: [
['role' => 'user', 'content' => 'Refactor this module to use dependency injection'],
],
);
echo $response->content[0]->text;
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
response = client.beta.messages.create(
model: "claude-opus-4-6",
max_tokens: 4096,
speed: "fast",
betas: ["fast-mode-2026-02-01"],
messages: [{role: "user", content: "Refactor this module to use dependency injection"}]
)
puts response.content[0].text
```
</CodeGroup>
## Pricing
Fast mode is priced at 6x standard Opus rates across the full context window, including requests over 200k input tokens. The following table shows pricing for Claude Opus 4.6 with fast mode:
| Input | Output |
|:------|:-------|
| $30 / MTok | $150 / MTok |
Fast mode pricing stacks with other pricing modifiers:
- [Prompt caching multipliers](/docs/en/about-claude/pricing#model-pricing) apply on top of fast mode pricing
- [Data residency](/docs/en/build-with-claude/data-residency) multipliers apply on top of fast mode pricing
For complete pricing details, see the [pricing page](/docs/en/about-claude/pricing#fast-mode-pricing).
## Rate limits
Fast mode has a dedicated rate limit that is separate from standard Opus rate limits. When your fast mode rate limit is exceeded, the API returns a `429` error with a `retry-after` header indicating when capacity will be available.
The response includes headers that indicate your fast mode rate limit status:
| Header | Description |
|:-------|:------------|
| `anthropic-fast-input-tokens-limit` | Maximum fast mode input tokens per minute |
| `anthropic-fast-input-tokens-remaining` | Remaining fast mode input tokens |
| `anthropic-fast-input-tokens-reset` | Time when the fast mode input token limit resets |
| `anthropic-fast-output-tokens-limit` | Maximum fast mode output tokens per minute |
| `anthropic-fast-output-tokens-remaining` | Remaining fast mode output tokens |
| `anthropic-fast-output-tokens-reset` | Time when the fast mode output token limit resets |
For tier-specific rate limits, see the [rate limits page](/docs/en/api/rate-limits).
## Checking which speed was used
The response `usage` object includes a `speed` field that indicates which speed was used, either `"fast"` or `"standard"`:
<CodeGroup>
```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: fast-mode-2026-02-01" \
--header "content-type: application/json" \
--data '{
"model": "claude-opus-4-6",
"max_tokens": 1024,
"speed": "fast",
"messages": [{"role": "user", "content": "Hello"}]
}'
```
```bash CLI
ant beta:messages create --beta fast-mode-2026-02-01 \
--transform usage.speed --format yaml <<'YAML'
model: claude-opus-4-6
max_tokens: 1024
speed: fast
messages:
- role: user
content: Hello
YAML
```
```python Python nocheck
response = client.beta.messages.create(
model="claude-opus-4-6",
max_tokens=1024,
speed="fast",
betas=["fast-mode-2026-02-01"],
messages=[{"role": "user", "content": "Hello"}],
)
print(response.usage.speed) # "fast" or "standard"
```
```typescript TypeScript
const response = await client.beta.messages.create({
model: "claude-opus-4-6",
max_tokens: 1024,
speed: "fast",
betas: ["fast-mode-2026-02-01"],
messages: [{ role: "user", content: "Hello" }]
});
console.log(response.usage.speed); // "fast" or "standard"
```
```csharp C# hidelines={1..5}
using Anthropic;
using Anthropic.Models.Beta.Messages;
AnthropicClient client = new();
var response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = "claude-opus-4-6",
MaxTokens = 1024,
Speed = Speed.Fast,
Betas = ["fast-mode-2026-02-01"],
Messages = [new() { Role = Role.User, Content = "Hello" }],
});
Console.WriteLine(response.Usage.Speed); // "fast" or "standard"
```
```go Go hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
anthropic "github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus4_6,
MaxTokens: 1024,
Speed: anthropic.BetaMessageNewParamsSpeedFast,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFastMode2026_02_01},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.Speed) // "fast" or "standard"
}
```
```java Java hidelines={1..9,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
public class FastModeUsage {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_6)
.maxTokens(1024L)
.speed(MessageCreateParams.Speed.FAST)
.addBeta(AnthropicBeta.FAST_MODE_2026_02_01)
.addUserMessage("Hello")
.build();
BetaMessage response = client.beta().messages().create(params);
System.out.println(response.usage().speed()); // "fast" or "standard"
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client();
$response = $client->beta->messages->create(
model: 'claude-opus-4-6',
maxTokens: 1024,
speed: 'fast',
betas: ['fast-mode-2026-02-01'],
messages: [['role' => 'user', 'content' => 'Hello']],
);
echo $response->usage->speed; // "fast" or "standard"
```
```ruby Ruby nocheck
response = anthropic.beta.messages.create(
model: "claude-opus-4-6",
max_tokens: 1024,
speed: "fast",
betas: ["fast-mode-2026-02-01"],
messages: [{ role: "user", content: "Hello" }]
)
puts(response.usage.speed) # "fast" or "standard"
```
</CodeGroup>
```json Output hidelines={5..8}
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [{ "type": "text", "text": "Hello!" }],
"model": "claude-opus-4-6",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 523,
"output_tokens": 1842,
"speed": "fast"
}
}
```
To track fast mode usage and costs across your organization, see the [Usage and Cost API](/docs/en/build-with-claude/usage-cost-api).
## Retries and fallback
### Automatic retries
When fast mode rate limits are exceeded, the API returns a `429` error with a `retry-after` header. The Anthropic SDKs automatically retry these requests up to 2 times by default (configurable via `max_retries`), waiting for the server-specified delay before each retry. Since fast mode uses continuous token replenishment, the `retry-after` delay is typically short and requests succeed once capacity is available.
### Falling back to standard speed
If you'd prefer to fall back to standard speed rather than wait for fast mode capacity, catch the rate limit error and retry without `speed: "fast"`. Set `max_retries` to `0` on the initial fast request to skip automatic retries and fail immediately on rate limit errors.
<Note>
Falling back from fast to standard speed will result in a [prompt cache](/docs/en/build-with-claude/prompt-caching) miss. Requests at different speeds do not share cached prefixes.
</Note>
Since setting `max_retries` to `0` also disables retries for other transient errors (overloaded, internal server errors), the examples below re-issue the original request with default retries for those cases.
<CodeGroup>
```bash CLI
# `ant` retries 429/5xx automatically and has no per-request max_retries
# override, so on a fast-mode 429 the fallback runs after the built-in
# retries exhaust. --transform-error surfaces error.type for branching.
create_message_with_fast_fallback() {
local speed="$1" max_attempts="${2:-3}" body out
body=${3:-$(cat)}
out=$(
ant beta:messages create --beta fast-mode-2026-02-01 \
${speed:+--speed "$speed"} \
--transform-error error.type --format-error yaml <<<"$body" 2>/dev/null
) && { printf '%s\n' "$out"; return; }
case "$out" in
rate_limit_error)
if [[ -n "$speed" ]]; then
create_message_with_fast_fallback "" "$max_attempts" "$body"
return
fi ;;
overloaded_error | api_error | "")
if (( max_attempts > 1 )); then
create_message_with_fast_fallback "$speed" $((max_attempts - 1)) "$body"
return
fi ;;
esac
printf '%s\n' "${out:-connection_error}" >&2
return 1
}
MESSAGE=$(
create_message_with_fast_fallback fast <<'YAML'
model: claude-opus-4-6
max_tokens: 1024
messages:
- role: user
content: Hello
YAML
)
```
```python Python nocheck hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
def create_message_with_fast_fallback(max_retries=None, max_attempts=3, **params):
try:
return client.beta.messages.create(**params, max_retries=max_retries)
except anthropic.RateLimitError:
if params.get("speed") == "fast":
del params["speed"]
return create_message_with_fast_fallback(**params)
raise
except (
anthropic.InternalServerError,
anthropic.OverloadedError,
anthropic.APIConnectionError,
):
if max_attempts > 1:
return create_message_with_fast_fallback(
max_attempts=max_attempts - 1, **params
)
raise
message = create_message_with_fast_fallback(
model="claude-opus-4-6",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
betas=["fast-mode-2026-02-01"],
speed="fast",
max_retries=0,
)
```
```typescript TypeScript hidelines={1..3,-1}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
(async () => {
async function createMessageWithFastFallback(
params: Anthropic.Beta.MessageCreateParams,
requestOptions?: Anthropic.RequestOptions,
maxAttempts: number = 3
): Promise<Anthropic.Beta.Messages.BetaMessage> {
try {
return (await client.beta.messages.create(
params,
requestOptions
)) as Anthropic.Beta.Messages.BetaMessage;
} catch (e) {
if (e instanceof Anthropic.RateLimitError && params.speed === "fast") {
const { speed, ...rest } = params;
return createMessageWithFastFallback(rest);
}
if (
e instanceof Anthropic.InternalServerError ||
e instanceof Anthropic.APIConnectionError
) {
if (maxAttempts > 1) {
return createMessageWithFastFallback(params, undefined, maxAttempts - 1);
}
}
throw e;
}
}
const message = await createMessageWithFastFallback(
{
model: "claude-opus-4-6",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello" }],
betas: ["fast-mode-2026-02-01"],
speed: "fast"
},
{ maxRetries: 0 }
);
})();
```
```csharp C# hidelines={1..6}
using Anthropic;
using Anthropic.Exceptions;
using Anthropic.Models.Beta.Messages;
AnthropicClient client = new();
async Task<BetaMessage> CreateMessageWithFastFallback(
MessageCreateParams parameters,
int? maxRetries = null,
int maxAttempts = 3)
{
try
{
var requestClient = maxRetries is int retries
? client.WithOptions(o => o with { MaxRetries = retries })
: client;
return await requestClient.Beta.Messages.Create(parameters);
}
catch (AnthropicRateLimitException)
{
if (parameters.Speed is not null)
{
return await CreateMessageWithFastFallback(
parameters with { Speed = null });
}
throw;
}
catch (Anthropic5xxException)
{
if (maxAttempts > 1)
{
return await CreateMessageWithFastFallback(
parameters, maxAttempts: maxAttempts - 1);
}
throw;
}
}
var message = await CreateMessageWithFastFallback(
new MessageCreateParams
{
Model = "claude-opus-4-6",
MaxTokens = 1024,
Messages = [new() { Role = Role.User, Content = "Hello" }],
Betas = ["fast-mode-2026-02-01"],
Speed = Speed.Fast,
},
maxRetries: 0);
```
```go Go hidelines={1..11}
package main
import (
"context"
"errors"
"fmt"
anthropic "github.com/anthropics/anthropic-sdk-go"
"github.com/anthropics/anthropic-sdk-go/option"
)
func createMessageWithFastFallback(
ctx context.Context,
client *anthropic.Client,
params anthropic.BetaMessageNewParams,
maxAttempts int,
opts ...option.RequestOption,
) (*anthropic.BetaMessage, error) {
message, err := client.Beta.Messages.New(ctx, params, opts...)
if err != nil {
var apierr *anthropic.Error
if errors.As(err, &apierr) && apierr.StatusCode == 429 && params.Speed != "" {
params.Speed = ""
return createMessageWithFastFallback(ctx, client, params, maxAttempts)
}
if (errors.As(err, &apierr) && apierr.StatusCode >= 500) || !errors.As(err, &apierr) {
if maxAttempts > 1 {
return createMessageWithFastFallback(ctx, client, params, maxAttempts-1)
}
}
return nil, err
}
return message, nil
}
func main() {
client := anthropic.NewClient()
message, err := createMessageWithFastFallback(
context.TODO(),
&client,
anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus4_6,
MaxTokens: 1024,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello")),
},
Speed: "fast",
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFastMode2026_02_01},
},
3,
option.WithMaxRetries(0),
)
if err != nil {
panic(err)
}
fmt.Println(message)
}
```
```java Java hidelines={1..2,5..11,-1}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.errors.InternalServerException;
import com.anthropic.errors.RateLimitException;
import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import java.util.Optional;
public class FastModeFallback {
// Disable SDK auto-retry so the fallback logic below handles it
static AnthropicClient client =
AnthropicOkHttpClient.builder().fromEnv().maxRetries(0).build();
static BetaMessage createMessageWithFastFallback(
MessageCreateParams params, int maxAttempts) {
try {
return client.beta().messages().create(params);
} catch (RateLimitException e) {
if (params.speed().isPresent()) {
MessageCreateParams retryParams = params.toBuilder()
.speed(Optional.empty())
.build();
return createMessageWithFastFallback(retryParams, maxAttempts);
}
throw e;
} catch (InternalServerException e) {
if (maxAttempts > 1) {
return createMessageWithFastFallback(params, maxAttempts - 1);
}
throw e;
}
}
public static void main(String[] args) {
BetaMessage message = createMessageWithFastFallback(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_6)
.maxTokens(1024L)
.addUserMessage("Hello")
.addBeta(AnthropicBeta.FAST_MODE_2026_02_01)
.speed(MessageCreateParams.Speed.FAST)
.build(),
3);
}
}
```
```php PHP hidelines={1..3,8}
<?php
use Anthropic\Client;
use Anthropic\Core\Exceptions\APIConnectionException;
use Anthropic\Core\Exceptions\InternalServerException;
use Anthropic\Core\Exceptions\RateLimitException;
use Anthropic\RequestOptions;
$client = new Client();
function createMessageWithFastFallback(
Client $client,
array $params,
?RequestOptions $requestOptions = null,
int $maxAttempts = 3,
) {
try {
return $client->beta->messages->create(
...$params,
requestOptions: $requestOptions,
);
} catch (RateLimitException $e) {
if (isset($params['speed'])) {
unset($params['speed']);
return createMessageWithFastFallback($client, $params);
}
throw $e;
} catch (InternalServerException | APIConnectionException $e) {
if ($maxAttempts > 1) {
return createMessageWithFastFallback(
$client, $params, maxAttempts: $maxAttempts - 1
);
}
throw $e;
}
}
$message = createMessageWithFastFallback(
$client,
[
'model' => 'claude-opus-4-6',
'maxTokens' => 1024,
'messages' => [['role' => 'user', 'content' => 'Hello']],
'betas' => ['fast-mode-2026-02-01'],
'speed' => 'fast',
],
RequestOptions::with(maxRetries: 0),
);
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
anthropic = Anthropic::Client.new
def create_message_with_fast_fallback(client, request_options: {}, max_attempts: 3, **params)
client.beta.messages.create(**params, request_options: request_options)
rescue Anthropic::Errors::RateLimitError
raise unless params[:speed] == "fast"
params.delete(:speed)
create_message_with_fast_fallback(client, **params)
rescue Anthropic::Errors::InternalServerError, Anthropic::Errors::APIConnectionError
raise unless max_attempts > 1
create_message_with_fast_fallback(client, max_attempts: max_attempts - 1, **params)
end
message = create_message_with_fast_fallback(
anthropic,
model: "claude-opus-4-6",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello" }],
betas: ["fast-mode-2026-02-01"],
speed: "fast",
request_options: { max_retries: 0 }
)
```
</CodeGroup>
## Considerations
- **Prompt caching:** Switching between fast and standard speed invalidates the prompt cache. Requests at different speeds do not share cached prefixes.
- **Supported models:** Fast mode is currently supported on Opus 4.6 only. Sending `speed: "fast"` with an unsupported model returns an error.
- **TTFT:** Fast mode's benefits are focused on output tokens per second (OTPS), not time to first token (TTFT).
- **Batch API:** Fast mode is not available with the [Batch API](/docs/en/build-with-claude/batch-processing).
- **Priority Tier:** Fast mode is not available with [Priority Tier](/docs/en/api/service-tiers).
## Next steps
<CardGroup>
<Card title="Pricing" icon="dollar-sign" href="/docs/en/about-claude/pricing#fast-mode-pricing">
View detailed fast mode pricing information.
</Card>
<Card title="Rate limits" icon="gauge" href="/docs/en/api/rate-limits">
Check rate limit tiers for fast mode.
</Card>
<Card title="Effort parameter" icon="sliders" href="/docs/en/build-with-claude/effort">
Control token usage with the effort parameter.
</Card>
</CardGroup>
---
## Guides/build-with-claude-files-dacd285bb2.md
# Files API
---
The Files API lets you upload and manage files to use with the Claude API without re-uploading content with each request. This is particularly useful when using the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool) to provide inputs (e.g. datasets and documents) and then download outputs (e.g. charts). You can also use the Files API to prevent having to continually re-upload frequently used documents and images across multiple API calls. You can [explore the API reference directly](/docs/en/api/files-create), in addition to this guide.
<Note>
The Files API is in beta. Reach out through the [feedback form](https://forms.gle/tisHyierGwgN4DUE9) to share your experience with the Files API.
</Note>
<Note>
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.
</Note>
## Supported models
Referencing a `file_id` in a Messages request is supported in all models that support the given file type. For example, [images](/docs/en/build-with-claude/vision) are supported in all Claude 3+ models, [PDFs](/docs/en/build-with-claude/pdf-support) in all Claude 3.5+ models, and [various other file types](/docs/en/agents-and-tools/tool-use/code-execution-tool#supported-file-types) for the code execution tool in Claude Haiku 4.5 plus all Claude 3.7+ models.
The Files API is currently not supported on Amazon Bedrock or Google Vertex AI.
## How the Files API works
The Files API provides a simple create-once, use-many-times approach for working with files:
- **Upload files** to Anthropic's secure storage and receive a unique `file_id`
- **Download files** that are created from skills or the code execution tool
- **Reference files** in [Messages](/docs/en/api/messages/create) requests using the `file_id` instead of re-uploading content
- **Manage your files** with list, retrieve, and delete operations
## How to use the Files API
<Note>
To use the Files API, you'll need to include the beta feature header: `anthropic-beta: files-api-2025-04-14`.
</Note>
### Uploading a file
Upload a file to be referenced in future API calls:
<CodeGroup>
````bash
curl -X POST https://api.anthropic.com/v1/files \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: files-api-2025-04-14" \
-F "file=@/path/to/document.pdf"
````
````bash
FILE_ID=$(ant beta:files upload \
--file /path/to/document.pdf \
--transform id --format yaml)
````
````python
uploaded = client.beta.files.upload(
file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
````
````typescript
const uploaded = await anthropic.beta.files.upload({
file: await toFile(
fs.createReadStream("/path/to/document.pdf"),
undefined,
{ type: "application/pdf" },
),
});
````
````csharp
var uploaded = await client.Beta.Files.Upload(
new FileUploadParams
{
File = File.OpenRead("/path/to/document.pdf")
});
Console.WriteLine(uploaded.Id);
````
````go
f, err := os.Open("/path/to/document.pdf")
if err != nil {
log.Fatal(err)
}
defer f.Close()
response, err := client.Beta.Files.Upload(context.Background(),
anthropic.BetaFileUploadParams{
File: anthropic.File(f, "document.pdf", "application/pdf"),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.ID)
````
````java
FileMetadata file = client.beta().files().upload(
FileUploadParams.builder()
.file(MultipartField.<InputStream>builder()
.value(Files.newInputStream(Path.of("/path/to/document.pdf")))
.filename("document.pdf")
.contentType("application/pdf")
.build())
.build()
);
System.out.println(file.id());
````
```php PHP nocheck hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(
apiKey: getenv("ANTHROPIC_API_KEY")
);
$file = $client->beta->files->upload(
file: fopen('/path/to/document.pdf', 'r'),
);
echo $file->id;
```
````ruby
file = client.beta.files.upload(
file: Anthropic::FilePart.new(
Pathname("/path/to/document.pdf"),
content_type: "application/pdf"
)
)
puts file.id
````
</CodeGroup>
The response from uploading a file will include:
```json Output
{
"id": "file_011CNha8iCJcU1wXNR6q4V8w",
"type": "file",
"filename": "document.pdf",
"mime_type": "application/pdf",
"size_bytes": 1024000,
"created_at": "2025-01-01T00:00:00Z",
"downloadable": false
}
```
### Using a file in messages
Once uploaded, reference the file using its `file_id`:
<CodeGroup>
````bash
curl -X POST https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: files-api-2025-04-14" \
-H "content-type: application/json" \
-d @- <<EOF
{
"model": "claude-opus-4-6",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Please summarize this document for me."
},
{
"type": "document",
"source": {
"type": "file",
"file_id": "$FILE_ID"
}
}
]
}
]
}
EOF
````
````bash
ant beta:messages create --beta files-api-2025-04-14 <<YAML
model: claude-opus-4-6
max_tokens: 1024
messages:
- role: user
content:
- type: text
text: Please summarize this document for me.
- type: document
source:
type: file
file_id: $FILE_ID
YAML
````
````python
response = client.beta.messages.create(
model="claude-opus-4-6",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Please summarize this document for me."},
{
"type": "document",
"source": {
"type": "file",
"file_id": file_id,
},
},
],
}
],
betas=["files-api-2025-04-14"],
)
print(response)
````
````typescript
const response = await anthropic.beta.messages.create({
model: "claude-opus-4-6",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
{
type: "text",
text: "Please summarize this document for me.",
},
{
type: "document",
source: {
type: "file",
file_id: uploaded.id,
},
},
],
},
],
betas: ["files-api-2025-04-14"],
});
console.log(response);
````
````csharp
var response = await client.Beta.Messages.Create(
new MessageCreateParams
{
Model = "claude-opus-4-6",
MaxTokens = 1024,
Betas = new[] { "files-api-2025-04-14" },
Messages = new[]
{
new BetaMessageParam
{
Role = "user",
Content = new object[]
{
new { type = "text", text = "Please summarize this document for me." },
new
{
type = "document",
source = new
{
type = "file",
file_id = fileId
}
}
}
}
}
});
Console.WriteLine(response);
````
````go
msg, err := client.Beta.Messages.New(context.Background(),
anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus4_6,
MaxTokens: 1024,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFilesAPI2025_04_14},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(
anthropic.NewBetaTextBlock("Please summarize this document for me."),
anthropic.NewBetaDocumentBlock(anthropic.BetaFileDocumentSourceParam{
FileID: fileID,
}),
),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg)
````
````java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_6)
.addBeta("files-api-2025-04-14")
.maxTokens(1024)
.addUserMessageOfBetaContentBlockParams(List.of(
BetaContentBlockParam.ofText(BetaTextBlockParam.builder()
.text("Please summarize this document for me.")
.build()),
BetaContentBlockParam.ofDocument(BetaRequestDocumentBlock.builder()
.source(BetaFileDocumentSource.builder()
.fileId(fileId)
.build())
.build())
))
.build();
BetaMessage message = client.beta().messages().create(params);
System.out.println(message);
````
````php
$response = $client->beta->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => [
['type' => 'text', 'text' => 'Please summarize this document for me.'],
[
'type' => 'document',
'source' => [
'type' => 'file',
'file_id' => $fileId
]
]
]
]
],
model: 'claude-opus-4-6',
betas: ['files-api-2025-04-14'],
);
print_r($response);
````
````ruby
response = client.beta.messages.create(
model: "claude-opus-4-6",
max_tokens: 1024,
betas: ["files-api-2025-04-14"],
messages: [
{
role: "user",
content: [
{ type: "text", text: "Please summarize this document for me." },
{
type: "document",
source: {
type: "file",
file_id: file_id
}
}
]
}
]
)
puts response
````
</CodeGroup>
### File types and content blocks
The Files API supports different file types that correspond to different content block types:
| File Type | MIME Type | Content Block Type | Use Case |
| :--- | :--- | :--- | :--- |
| PDF | `application/pdf` | `document` | Text analysis, document processing |
| Plain text | `text/plain` | `document` | Text analysis, processing |
| Images | `image/jpeg`, `image/png`, `image/gif`, `image/webp` | `image` | Image analysis, visual tasks |
| [Datasets, others](/docs/en/agents-and-tools/tool-use/code-execution-tool#supported-file-types) | Varies | `container_upload` | Analyze data, create visualizations |
### Working with other file formats
For file types that are not supported as `document` blocks (.csv, .txt, .md, .docx, .xlsx), convert the files to plain text, and include the content directly in your message:
<CodeGroup>
```bash cURL hidelines={3..4}
# Example: Reading a text file and sending it as plain text
# Note: For files with special characters, consider base64 encoding
TEXT_CONTENT="This is a sample document. It has multiple lines."
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 @- <<EOF
{
"model": "claude-opus-4-7",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Here's the document content:\n\n${TEXT_CONTENT}\n\nPlease summarize this document."
}
]
}
]
}
EOF
```
```bash CLI hidelines={1}
printf 'This is a test document for upload.\n' > document.txt
# The "@./path" reference inlines the file contents directly into the field.
ant messages create \
--model claude-opus-4-7 \
--max-tokens 1024 \
--transform 'content.0.text' --format yaml <<'YAML'
messages:
- role: user
content:
- type: text
text: "Here's the document content:"
- type: text
text: "@./document.txt"
- type: text
text: "Please summarize this document."
YAML
```
```python Python nocheck hidelines={2..5}
import pandas as pd
import anthropic
client = anthropic.Anthropic()
# Example: Reading a CSV file
df = pd.read_csv("data.csv")
csv_content = df.to_string()
# Send as plain text in the message
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": f"Here's the CSV data:\n\n{csv_content}\n\nPlease analyze this data.",
}
],
}
],
)
print(response.content[0].text)
```
```typescript TypeScript nocheck hidelines={1}
import Anthropic from "@anthropic-ai/sdk";
import fs from "fs/promises";
const anthropic = new Anthropic();
async function analyzeDocument() {
// Example: Reading a text file
const textContent = await fs.readFile("document.txt", "utf-8");
// Send as plain text in the message
const response = await anthropic.messages.create({
model: "claude-opus-4-7",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
{
type: "text",
text: `Here's the document content:\n\n${textContent}\n\nPlease summarize this document.`
}
]
}
]
});
const block = response.content[0];
if (block.type === "text") {
console.log(block.text);
}
}
analyzeDocument();
```
```csharp C# nocheck
using System;
using System.IO;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages;
class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new();
// Example: Reading a text file
string textContent = await File.ReadAllTextAsync("document.txt");
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus4_7,
MaxTokens = 1024,
Messages = [new()
{
Role = Role.User,
Content = $"Here's the document content:\n\n{textContent}\n\nPlease summarize this document."
}]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
}
}
```
```go Go hidelines={11..15}
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/anthropics/anthropic-sdk-go"
)
func init() {
os.WriteFile("document.txt", []byte("This is a test document for upload."), 0644)
}
func main() {
client := anthropic.NewClient()
// Example: Reading a text file
textContent, err := os.ReadFile("document.txt")
if err != nil {
log.Fatal(err)
}
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_7,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock(
fmt.Sprintf("Here's the document content:\n\n%s\n\nPlease summarize this document.", string(textContent)),
)),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Content[0].Text)
}
```
```java Java nocheck hidelines={1..11,-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 java.nio.file.Files;
import java.nio.file.Paths;
import java.io.IOException;
public class FileUploadExample {
public static void main(String[] args) throws IOException {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Example: Reading a text file
String textContent = Files.readString(Paths.get("document.txt"));
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(1024L)
.addUserMessage("Here's the document content:\n\n" + textContent + "\n\nPlease summarize this document.")
.build();
Message response = client.messages().create(params);
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> System.out.println(textBlock.text()));
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
// Example: Reading a text file
$textContent = file_get_contents("document.txt");
$message = $client->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => [
[
'type' => 'text',
'text' => "Here's the document content:\n\n{$textContent}\n\nPlease summarize this document."
]
]
]
],
model: 'claude-opus-4-7',
);
echo $message->content[0]->text;
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
# Example: Reading a text file
text_content = File.read("document.txt")
message = client.messages.create(
model: "claude-opus-4-7",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
{
type: "text",
text: "Here's the document content:\n\n#{text_content}\n\nPlease summarize this document."
}
]
}
]
)
puts message.content.first.text
```
</CodeGroup>
<Note>
For .docx files containing images, convert them to PDF format first, then use [PDF support](/docs/en/build-with-claude/pdf-support) to take advantage of the built-in image parsing. This allows using citations from the PDF document.
</Note>
#### Document blocks
For PDFs and text files, use the `document` content block:
```json
{
"type": "document",
"source": {
"type": "file",
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
},
"title": "Document Title", // Optional
"context": "Context about the document", // Optional
"citations": { "enabled": true } // Optional, enables citations
}
```
#### Image blocks
For images, use the `image` content block:
```json
{
"type": "image",
"source": {
"type": "file",
"file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
}
}
```
### Managing files
#### List files
Retrieve a list of your uploaded files:
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/files \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: files-api-2025-04-14"
```
```bash CLI nocheck
ant beta:files list
```
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
files = client.beta.files.list()
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
const files = await anthropic.beta.files.list();
```
```csharp C# nocheck
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Beta.Files;
class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new();
var files = await client.Beta.Files.List();
Console.WriteLine(files);
}
}
```
```go Go hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
files, err := client.Beta.Files.List(context.TODO(), anthropic.BetaFileListParams{})
if err != nil {
log.Fatal(err)
}
fmt.Println(files)
}
```
```java Java hidelines={1..2,4..6,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.files.FileListPage;
public class ListFiles {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
FileListPage files = client.beta().files().list();
System.out.println(files);
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$files = $client->beta->files->list();
print_r($files);
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
files = client.beta.files.list
puts files
```
</CodeGroup>
#### Get file metadata
Retrieve information about a specific file:
<CodeGroup>
````bash
curl "https://api.anthropic.com/v1/files/$FILE_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: files-api-2025-04-14"
````
````bash
ant beta:files retrieve-metadata \
--file-id "$FILE_ID"
````
````python
file = client.beta.files.retrieve_metadata(file_id)
````
````typescript
const file = await anthropic.beta.files.retrieveMetadata(uploaded.id);
````
````csharp
var file = await client.Beta.Files.RetrieveMetadata(fileId);
Console.WriteLine(file);
````
````go
metadata, err := client.Beta.Files.GetMetadata(
context.TODO(),
fileID,
anthropic.BetaFileGetMetadataParams{},
)
if err != nil {
log.Fatal(err)
}
fmt.Println(metadata)
````
````java
FileMetadata metadata = client.beta().files().retrieveMetadata(fileId);
System.out.println(metadata);
````
````php
$file = $client->beta->files->retrieveMetadata(
fileID: $fileId,
);
echo $file;
````
````ruby
file = client.beta.files.retrieve_metadata(file_id)
puts file
````
</CodeGroup>
#### Delete a file
Remove a file from your workspace:
<CodeGroup>
````bash
curl -X DELETE "https://api.anthropic.com/v1/files/$FILE_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: files-api-2025-04-14"
````
````bash
ant beta:files delete \
--file-id "$FILE_ID"
````
````python
result = client.beta.files.delete(file_id)
````
````typescript
await anthropic.beta.files.delete(uploaded.id);
````
````csharp
await client.Beta.Files.Delete(fileId);
````
````go
_, err = client.Beta.Files.Delete(
context.TODO(),
fileID,
anthropic.BetaFileDeleteParams{},
)
if err != nil {
log.Fatal(err)
}
````
````java
client.beta().files().delete(fileId);
````
````php
$result = $client->beta->files->delete(
fileID: $fileId,
);
````
````ruby
result = client.beta.files.delete(file_id)
````
</CodeGroup>
### Downloading a file
Download files that have been created by skills or the code execution tool:
<CodeGroup>
````bash
curl -X GET "https://api.anthropic.com/v1/files/$FILE_ID/content" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: files-api-2025-04-14" \
--output downloaded_file.txt
````
````bash
ant beta:files download \
--file-id "$FILE_ID" \
--output downloaded_file.txt
````
````python
file_content = client.beta.files.download(file_id)
# Save to file
file_content.write_to_file("downloaded_file.txt")
````
````typescript
const content = await anthropic.beta.files.download(uploaded.id);
const bytes = Buffer.from(await content.arrayBuffer());
await fsp.writeFile("downloaded_file.txt", bytes);
````
````csharp
byte[] fileContent = await client.Beta.Files.Download(fileId);
await File.WriteAllBytesAsync("downloaded_file.txt", fileContent);
````
````go
func downloadFile(client anthropic.Client, fileID string) error {
resp, err := client.Beta.Files.Download(
context.TODO(),
fileID,
anthropic.BetaFileDownloadParams{},
)
if err != nil {
return err
}
defer resp.Body.Close()
fileContent, err := io.ReadAll(resp.Body)
if err != nil {
return err
}
return os.WriteFile("downloaded_file.txt", fileContent, 0644)
}
````
````java
try (HttpResponse response = client.beta().files().download(fileId)) {
try (InputStream body = response.body()) {
Files.copy(body, Path.of("downloaded_file.txt"),
StandardCopyOption.REPLACE_EXISTING);
}
}
````
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$fileContent = $client->beta->files->download(
fileID: 'file_011CNha8iCJcU1wXNR6q4V8w',
);
file_put_contents("downloaded_file.txt", $fileContent);
```
````ruby
file_content = client.beta.files.download(file_id)
File.binwrite("downloaded_file.txt", file_content.read)
````
</CodeGroup>
<Note>
You can only download files that were created by [skills](/docs/en/build-with-claude/skills-guide) or the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool). Files that you uploaded cannot be downloaded.
</Note>
---
## File storage and limits
### Storage limits
- **Maximum file size:** 500 MB per file
- **Total storage:** 500 GB per organization
### File lifecycle
- Files are scoped to the workspace of the API key. Other API keys can use files created by any other API key associated with the same workspace
- Files persist until you delete them
- Deleted files cannot be recovered
- Files are inaccessible via the API shortly after deletion, but they may persist in active `Messages` API calls and associated tool uses
- Files that users delete will be deleted in accordance with Anthropic's [data retention policy](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data).
---
## Data retention
Files uploaded via the Files API are retained until explicitly deleted using the `DELETE /v1/files/{file_id}` endpoint. Files are stored for reuse across multiple API requests.
For ZDR eligibility across all features, see [API and data retention](/docs/en/build-with-claude/api-and-data-retention).
## Error handling
Common errors when using the Files API include:
- **File not found (404):** The specified `file_id` doesn't exist or you don't have access to it
- **Invalid file type (400):** The file type doesn't match the content block type (e.g., using an image file in a document block)
- **Exceeds context window size (400):** The file is larger than the context window size (e.g. using a 500 MB plaintext file in a `/v1/messages` request)
- **Invalid filename (400):** Filename doesn't meet the length requirements (1-255 characters) or contains forbidden characters (`<`, `>`, `:`, `"`, `|`, `?`, `*`, `\`, `/`, or unicode characters 0-31)
- **File too large (413):** File exceeds the 500 MB limit
- **Storage limit exceeded (403):** Your organization has reached the 500 GB storage limit
```json Output
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "File not found: file_011CNha8iCJcU1wXNR6q4V8w"
}
}
```
## Usage and billing
File API operations are **free**:
- Uploading files
- Downloading files
- Listing files
- Getting file metadata
- Deleting files
File content used in `Messages` requests are priced as input tokens. You can only download files created by [skills](/docs/en/build-with-claude/skills-guide) or the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool).
### Rate limits
During the beta period:
- File-related API calls are limited to approximately 100 requests per minute
- [Contact us](mailto:sales@anthropic.com) if you need higher limits for your use case
---
## Guides/build-with-claude-handling-stop-reasons-767bec5b32.md
# Handling stop reasons
---
When you make a request to the Messages API, Claude's response includes a `stop_reason` field that indicates why the model stopped generating its response. Understanding these values is crucial for building robust applications that handle different response types appropriately.
For details about `stop_reason` in the API response, see the [Messages API reference](/docs/en/api/messages/create).
## The stop_reason field
The `stop_reason` field is part of every successful Messages API response. Unlike errors, which indicate failures in processing your request, `stop_reason` tells you why Claude successfully completed its response generation.
```json Example response
{
"id": "msg_01234",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Here's the answer to your question..."
}
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 100,
"output_tokens": 50
}
}
```
## Stop reason values
### end_turn
The most common stop reason. Indicates Claude finished its response naturally.
```python Python
from anthropic import Anthropic
client = Anthropic()
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}],
)
if response.stop_reason == "end_turn":
# Process the complete response
print(response.content[0].text)
```
#### Empty responses with end_turn
Sometimes Claude returns an empty response (exactly 2-3 tokens with no content) with `stop_reason: "end_turn"`. This typically happens when Claude interprets that the assistant turn is complete, particularly after tool results.
**Common causes:**
- Adding text blocks immediately after tool results (Claude learns to expect the user to always insert text after tool results, so it ends its turn to follow the pattern)
- Sending Claude's completed response back without adding anything (Claude already decided it's done, so it will remain done)
**How to prevent empty responses:**
```python nocheck
# INCORRECT: Adding text immediately after tool_result
messages = [
{"role": "user", "content": "Calculate the sum of 1234 and 5678"},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_123",
"name": "calculator",
"input": {"operation": "add", "a": 1234, "b": 5678},
}
],
},
{
"role": "user",
"content": [
{"type": "tool_result", "tool_use_id": "toolu_123", "content": "6912"},
{
"type": "text",
"text": "Here's the result", # Don't add text after tool_result
},
],
},
]
# CORRECT: Send tool results directly without additional text
messages = [
{"role": "user", "content": "Calculate the sum of 1234 and 5678"},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_123",
"name": "calculator",
"input": {"operation": "add", "a": 1234, "b": 5678},
}
],
},
{
"role": "user",
"content": [
{"type": "tool_result", "tool_use_id": "toolu_123", "content": "6912"}
],
}, # Just the tool_result, no additional text
]
# If you still get empty responses after fixing the above:
def handle_empty_response(client, messages):
response = client.messages.create(
model="claude-opus-4-7", max_tokens=1024, messages=messages
)
# Check if response is empty
if response.stop_reason == "end_turn" and not response.content:
# INCORRECT: Don't just retry with the empty response
# This won't work because Claude already decided it's done
# CORRECT: Add a continuation prompt in a NEW user message
messages.append({"role": "user", "content": "Please continue"})
response = client.messages.create(
model="claude-opus-4-7", max_tokens=1024, messages=messages
)
return response
```
**Best practices:**
1. **Never add text blocks immediately after tool results** - This teaches Claude to expect user input after every tool use
2. **Don't retry empty responses without modification** - Simply sending the empty response back won't help
3. **Use continuation prompts as a last resort** - Only if the above fixes don't resolve the issue
### max_tokens
Claude stopped because it reached the `max_tokens` limit specified in your request.
```python Python
# Request with limited tokens
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=10,
messages=[{"role": "user", "content": "Explain quantum physics"}],
)
if response.stop_reason == "max_tokens":
# Response was truncated
print("Response was cut off at token limit")
# Consider making another request to continue
```
#### Incomplete tool use blocks
If Claude's response is cut off due to hitting the `max_tokens` limit, and the truncated response contains an incomplete tool use block, you'll need to retry the request with a higher `max_tokens` value to get the full tool use.
<CodeGroup>
```bash CLI nocheck
RESPONSE=$(ant messages create --max-tokens 1024 \
--format jsonl < request.yaml)
# Check if the response was truncated mid tool use
STOP_REASON=$(jq -r '.stop_reason' <<<"$RESPONSE")
LAST_TYPE=$(jq -r '.content[-1].type' <<<"$RESPONSE")
if [ "$STOP_REASON" = "max_tokens" ] && [ "$LAST_TYPE" = "tool_use" ]; then
# Retry with a higher max_tokens
ant messages create --max-tokens 4096 < request.yaml
fi
```
```python Python nocheck hidelines={1..8}
import anthropic
client = anthropic.Anthropic()
tools: list[dict] = []
messages: list[dict] = []
response = client.messages.create(
model="claude-opus-4-7", max_tokens=1024, tools=tools, messages=messages
)
# Check if response was truncated during tool use
if response.stop_reason == "max_tokens":
# Check if the last content block is an incomplete tool_use
last_block = response.content[-1]
if last_block.type == "tool_use":
# Send the request with higher max_tokens
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=4096, # Increased limit
messages=messages,
tools=tools,
)
```
```typescript TypeScript nocheck
// Check if response was truncated during tool use
if (response.stop_reason === "max_tokens") {
// Check if the last content block is an incomplete tool_use
const lastBlock = response.content[response.content.length - 1];
if (lastBlock.type === "tool_use") {
// Send the request with higher max_tokens
response = await client.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096, // Increased limit
messages: messages,
tools: tools
});
}
}
```
```csharp C# nocheck
using System;
using System.Linq;
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 = 1024,
Messages = messages,
Tools = tools
};
var response = await client.Messages.Create(parameters);
if (response.StopReason == "max_tokens")
{
var lastBlock = response.Content.Last();
if (lastBlock.Type == "tool_use")
{
parameters.MaxTokens = 4096;
response = await client.Messages.Create(parameters);
}
}
}
}
```
```go Go hidelines={1..15,-3..-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
tools := []anthropic.ToolUnionParam{}
messages := []anthropic.MessageParam{anthropic.NewUserMessage(anthropic.NewTextBlock("test"))}
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_7,
MaxTokens: 1024,
Messages: messages,
Tools: tools,
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "max_tokens" {
lastBlock := response.Content[len(response.Content)-1]
switch lastBlock.AsAny().(type) {
case anthropic.ToolUseBlock:
response, err = client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_7,
MaxTokens: 4096,
Messages: messages,
Tools: tools,
})
if err != nil {
log.Fatal(err)
}
}
}
fmt.Println(response)
}
```
```java Java nocheck hidelines={1..13}
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.Tool;
import com.anthropic.models.messages.ContentBlock;
import java.util.List;
import com.anthropic.models.messages.StopReason;
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
List<MessageCreateParams.Message> messages = List.of();
List<Tool> tools = List.of();
Message response = client.messages().create(MessageCreateParams.builder().model(Model.CLAUDE_OPUS_4_7).maxTokens(1024L).addUserMessage("test").build());
// Check if response was truncated during tool use
if (response.stopReason().isPresent() && response.stopReason().get().equals(StopReason.MAX_TOKENS)) {
ContentBlock lastBlock = response.content().get(response.content().size() - 1);
if (lastBlock.toolUse().isPresent()) {
// Send the request with higher max_tokens
response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(4096L) // Increased limit
.messages(messages)
.tools(tools)
.build()
);
}
}
```
```php PHP hidelines={1..6} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$response = $client->messages->create(
maxTokens: 1024,
messages: $messages,
model: 'claude-opus-4-7',
tools: $tools,
);
if ($response->stopReason === 'max_tokens') {
$lastBlock = end($response->content);
if ($lastBlock->type === 'tool_use') {
$response = $client->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-4-7',
tools: $tools,
);
}
}
```
```ruby Ruby hidelines={1..15}
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" } }, required: ["location"] }
}
]
messages = [
{ role: "user", content: "What's the weather in San Francisco?" }
]
response = client.messages.create(
model: "claude-opus-4-7",
max_tokens: 1024,
messages: messages,
tools: tools
)
if response.stop_reason == :max_tokens
last_block = response.content.last
if last_block.type == :tool_use
response = client.messages.create(
model: "claude-opus-4-7",
max_tokens: 4096,
messages: messages,
tools: tools
)
end
end
```
</CodeGroup>
### stop_sequence
Claude encountered one of your custom stop sequences.
```python Python
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
stop_sequences=["END", "STOP"],
messages=[{"role": "user", "content": "Generate text until you say END"}],
)
if response.stop_reason == "stop_sequence":
print(f"Stopped at sequence: {response.stop_sequence}")
```
### tool_use
Claude is calling a tool and expects you to execute it.
<Note>
For most tool use implementations, we recommend using the [tool runner](/docs/en/agents-and-tools/tool-use/tool-runner) which automatically handles tool execution, result formatting, and conversation management.
</Note>
```python Python nocheck
from anthropic import Anthropic
client = Anthropic()
weather_tool = {
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "City and state"},
},
"required": ["location"],
},
}
def execute_tool(name, tool_input):
"""Execute a tool and return the result."""
return f"Weather in {tool_input.get('location', 'unknown')}: 72°F"
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
tools=[weather_tool],
messages=[{"role": "user", "content": "What's the weather?"}],
)
if response.stop_reason == "tool_use":
# Extract and execute the tool
for content in response.content:
if content.type == "tool_use":
result = execute_tool(content.name, content.input)
# Return result to Claude for final response
```
### pause_turn
Returned when the server-side sampling loop reaches its iteration limit while executing [server tools](/docs/en/agents-and-tools/tool-use/server-tools) like web search or web fetch. The default limit is 10 iterations per request.
When this happens, the response may contain a `server_tool_use` block without a corresponding `server_tool_result`. To let Claude finish processing, continue the conversation by sending the response back as-is.
```python Python nocheck
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
tools=[{"type": "web_search_20250305", "name": "web_search"}],
messages=[{"role": "user", "content": "Search for latest AI news"}],
)
if response.stop_reason == "pause_turn":
# Continue the conversation by sending the response back
messages = [
{"role": "user", "content": original_query},
{"role": "assistant", "content": response.content},
]
continuation = client.messages.create(
model="claude-opus-4-7",
messages=messages,
tools=[{"type": "web_search_20250305", "name": "web_search"}],
)
```
<Note>
Your application should handle `pause_turn` in any agent loop that uses server tools. Simply add the assistant's response to your messages array and make another API request to let Claude continue.
</Note>
### refusal
Claude refused to generate a response due to safety concerns.
```python Python
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
messages=[{"role": "user", "content": "[Unsafe request]"}],
)
if response.stop_reason == "refusal":
# Claude declined to respond
print("Claude was unable to process this request")
# Consider rephrasing or modifying the request
```
<Tip>
If you encounter `refusal` stop reasons frequently while using Claude Sonnet 4.5 or Opus 4.1, you can try updating your API calls to use Haiku 4.5 (`claude-haiku-4-5-20251001`), which has different usage restrictions. Learn more about [understanding Sonnet 4.5's API safety filters](https://support.claude.com/en/articles/12449294-understanding-sonnet-4-5-s-api-safety-filters).
</Tip>
<Note>
To learn more about refusals triggered by API safety filters for Claude Sonnet 4.5, see [Understanding Sonnet 4.5's API Safety Filters](https://support.claude.com/en/articles/12449294-understanding-sonnet-4-5-s-api-safety-filters).
</Note>
### model_context_window_exceeded
Claude stopped because it reached the model's context window limit. This allows you to request the maximum possible tokens without knowing the exact input size.
```python Python nocheck
# Request with maximum tokens to get as much as possible
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=64000, # Practical non-streaming ceiling (Opus 4.7 supports 128K with streaming)
messages=[
{"role": "user", "content": "Large input that uses most of context window..."}
],
)
if response.stop_reason == "model_context_window_exceeded":
# Response hit context window limit before max_tokens
print("Response reached model's context window limit")
# The response is still valid but was limited by context window
```
<Note>
This stop reason is available by default in Sonnet 4.5 and newer models. For earlier models, use the beta header `model-context-window-exceeded-2025-08-26` to enable this behavior.
</Note>
## Best practices for handling stop reasons
### 1. Always check stop_reason
Make it a habit to check the `stop_reason` in your response handling logic:
```python nocheck
def handle_response(response):
if response.stop_reason == "tool_use":
return handle_tool_use(response)
elif response.stop_reason == "max_tokens":
return handle_truncation(response)
elif response.stop_reason == "model_context_window_exceeded":
return handle_context_limit(response)
elif response.stop_reason == "pause_turn":
return handle_pause(response)
elif response.stop_reason == "refusal":
return handle_refusal(response)
else:
# Handle end_turn and other cases
return response.content[0].text
```
### 2. Handle truncated responses gracefully
When a response is truncated due to token limits or context window:
```python nocheck
def handle_truncated_response(response):
if response.stop_reason in ["max_tokens", "model_context_window_exceeded"]:
# Option 1: Warn the user about the specific limit
if response.stop_reason == "max_tokens":
message = "[Response truncated due to max_tokens limit]"
else:
message = "[Response truncated due to context window limit]"
return f"{response.content[0].text}\n\n{message}"
# Option 2: Continue generation
messages = [
{"role": "user", "content": original_prompt},
{"role": "assistant", "content": response.content[0].text},
]
continuation = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
messages=messages + [{"role": "user", "content": "Please continue"}],
)
return response.content[0].text + continuation.content[0].text
```
### 3. Implement retry logic for pause_turn
When using [server tools](/docs/en/agents-and-tools/tool-use/server-tools), the API may return `pause_turn` if the server-side sampling loop reaches its iteration limit (default 10). Handle this by continuing the conversation:
```python nocheck
def handle_server_tool_conversation(client, user_query, tools, max_continuations=5):
"""
Handle server tool conversations that may require multiple continuations.
The server runs a sampling loop when executing server tools. If the loop
reaches its iteration limit, the API returns pause_turn. Continue the
conversation by sending the response back to let Claude finish.
"""
messages = [{"role": "user", "content": user_query}]
for _ in range(max_continuations):
response = client.messages.create(
model="claude-opus-4-7", messages=messages, tools=tools
)
if response.stop_reason != "pause_turn":
# Claude finished processing - return the final response
return response
# pause_turn: replace the full message list to maintain alternating roles
messages = [
{"role": "user", "content": user_query},
{"role": "assistant", "content": response.content},
]
# Reached max continuations - return the last response
return response
```
## Stop reasons vs. errors
It's important to distinguish between `stop_reason` values and actual errors:
### Stop reasons (successful responses)
- Part of the response body
- Indicate why generation stopped normally
- Response contains valid content
### Errors (failed requests)
- HTTP status codes 4xx or 5xx
- Indicate request processing failures
- Response contains error details
```python Python
import anthropic
from anthropic import Anthropic
client = Anthropic()
try:
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}],
)
# Handle successful response with stop_reason
if response.stop_reason == "max_tokens":
print("Response was truncated")
except anthropic.APIError as e:
# Handle actual errors
if e.status_code == 429:
print("Rate limit exceeded")
elif e.status_code == 500:
print("Server error")
```
## Streaming considerations
When using streaming, `stop_reason` is:
- `null` in the initial `message_start` event
- Provided in the `message_delta` event
- Not provided in any other events
```python Python
from anthropic import Anthropic
client = Anthropic()
with client.messages.stream(
model="claude-sonnet-4-20250514",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}],
) as stream:
for event in stream:
if event.type == "message_delta":
stop_reason = event.delta.stop_reason
if stop_reason:
print(f"Stream ended with: {stop_reason}")
```
## Common patterns
### Handling tool use workflows
<Tip>
**Simpler with tool runner**: The example below shows manual tool handling. For most use cases, the [tool runner](/docs/en/agents-and-tools/tool-use/tool-runner) automatically handles tool execution with much less code.
</Tip>
```python nocheck
def complete_tool_workflow(client, user_query, tools):
messages = [{"role": "user", "content": user_query}]
while True:
response = client.messages.create(
model="claude-opus-4-7", messages=messages, tools=tools
)
if response.stop_reason == "tool_use":
# Execute tools and continue
tool_results = execute_tools(response.content)
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_results})
else:
# Final response
return response
```
### Ensuring complete responses
```python nocheck
def get_complete_response(client, prompt, max_attempts=3):
messages = [{"role": "user", "content": prompt}]
full_response = ""
for _ in range(max_attempts):
response = client.messages.create(
model="claude-opus-4-7", messages=messages, max_tokens=4096
)
full_response += response.content[0].text
if response.stop_reason != "max_tokens":
break
# Continue from where it left off
messages = [
{"role": "user", "content": prompt},
{"role": "assistant", "content": full_response},
{"role": "user", "content": "Please continue from where you left off."},
]
return full_response
```
### Getting maximum tokens without knowing input size
With the `model_context_window_exceeded` stop reason, you can request the maximum possible tokens without calculating input size:
```python nocheck
def get_max_possible_tokens(client, prompt):
"""
Get as many tokens as possible within the model's context window
without needing to calculate input token count
"""
response = client.messages.create(
model="claude-opus-4-7",
messages=[{"role": "user", "content": prompt}],
max_tokens=64000, # Practical non-streaming ceiling (Opus 4.7 supports 128K with streaming)
)
if response.stop_reason == "model_context_window_exceeded":
# Got the maximum possible tokens given input size
print(
f"Generated {response.usage.output_tokens} tokens (context limit reached)"
)
elif response.stop_reason == "max_tokens":
# Got exactly the requested tokens
print(f"Generated {response.usage.output_tokens} tokens (max_tokens reached)")
else:
# Natural completion
print(f"Generated {response.usage.output_tokens} tokens (natural completion)")
return response.content[0].text
```
By properly handling `stop_reason` values, you can build more robust applications that gracefully handle different response scenarios and provide better user experiences.
---
## Guides/build-with-claude-multilingual-support-2d75e26f84.md
# Multilingual support
Claude excels at tasks across multiple languages, maintaining strong cross-lingual performance relative to English.
---
## Overview
Claude demonstrates robust multilingual capabilities, with particularly strong performance in zero-shot tasks across languages. The model maintains consistent relative performance across both widely-spoken and lower-resource languages, making it a reliable choice for multilingual applications.
Note that Claude is capable in many languages beyond those benchmarked below. Consider testing with any languages relevant to your specific use cases.
## Performance data
Below are the zero-shot chain-of-thought evaluation scores for Claude models across different languages, shown as a percent relative to English performance (100%):
| Language | Claude Opus 4.1<sup>1</sup> | Claude Opus 4 (deprecated)<sup>1</sup> | Claude Sonnet 4.5<sup>1</sup> | Claude Sonnet 4 (deprecated)<sup>1</sup> | Claude Haiku 4.5<sup>1</sup> |
|----------|---------------|---------------|---------------|-----------------|------------------|
| English (baseline, fixed to 100%) | 100% | 100% | 100% | 100% | 100% |
| Spanish | 98.1% | 98.0% | 98.2% | 97.5% | 96.4% |
| Portuguese (Brazil) | 97.8% | 97.3% | 97.8% | 97.2% | 96.1% |
| Italian | 97.7% | 97.5% | 97.9% | 97.3% | 96.0% |
| French | 97.9% | 97.7% | 97.5% | 97.1% | 95.7% |
| Indonesian | 97.3% | 97.2% | 97.3% | 96.2% | 94.2% |
| German | 97.7% | 97.1% | 97.0% | 94.7% | 94.3% |
| Arabic | 97.1% | 96.9% | 97.2% | 96.1% | 92.5% |
| Chinese (Simplified) | 97.1% | 96.7% | 96.9% | 95.9% | 94.2% |
| Korean | 96.6% | 96.4% | 96.7% | 95.9% | 93.3% |
| Japanese | 96.9% | 96.2% | 96.8% | 95.6% | 93.5% |
| Hindi | 96.8% | 96.7% | 96.7% | 95.8% | 92.4% |
| Bengali | 95.7% | 95.2% | 95.4% | 94.4% | 90.4% |
| Swahili | 89.8% | 89.5% | 91.1% | 87.1% | 78.3% |
| Yoruba | 80.3% | 78.9% | 79.7% | 76.4% | 52.7% |
<sup>1</sup> With [extended thinking](/docs/en/build-with-claude/extended-thinking).
<Note>
These metrics are based on [MMLU (Massive Multitask Language Understanding)](https://en.wikipedia.org/wiki/MMLU) English test sets that were translated into 14 additional languages by professional human translators, as documented in [OpenAI's simple-evals repository](https://github.com/openai/simple-evals/blob/main/multilingual_mmlu_benchmark_results.md). The use of human translators for this evaluation ensures high-quality translations, particularly important for languages with fewer digital resources.
</Note>
***
## Best practices
When working with multilingual content:
1. **Provide clear language context**: While Claude can detect the target language automatically, explicitly stating the desired input/output language improves reliability. For enhanced fluency, you can prompt Claude to use "idiomatic speech as if it were a native speaker."
2. **Use native scripts**: Submit text in its native script rather than transliteration for optimal results
3. **Consider cultural context**: Effective communication often requires cultural and regional awareness beyond pure translation
Also follow the general [prompt engineering guidelines](/docs/en/build-with-claude/prompt-engineering/overview) to better improve Claude's performance.
***
## Language support considerations
- Claude processes input and generates output in most world languages that use standard Unicode characters
- Performance varies by language, with particularly strong capabilities in widely-spoken languages
- Even in languages with fewer digital resources, Claude maintains meaningful capabilities
<CardGroup cols={1}>
<Card title="Prompt Engineering Guide" icon="edit" href="/docs/en/build-with-claude/prompt-engineering/overview">
Master the art of prompt crafting to get the most out of Claude.
</Card>
</CardGroup>
---
## Guides/build-with-claude-overview-236d3362b2.md
# Features overview
Explore Claude's advanced features and capabilities.
---
Claude's API surface is organized into five areas:
- **Model capabilities:** Control how Claude reasons and formats responses.
- **Tools:** Let Claude take actions on the web or in your environment.
- **Tool infrastructure:** Handles discovery and orchestration at scale.
- **Context management:** Keeps long-running sessions efficient.
- **Files and assets:** Manage the documents and data you provide to Claude.
If you're new, start with [model capabilities](#model-capabilities) and [tools](#tools). Return to the other sections when you're ready to optimize cost, latency, or scale.
## Feature availability
Features on the Claude Platform are assigned one of the following availability classifications per platform (shown in the Availability column of each table below). Not all features pass through every stage. A feature may enter at any classification and may skip stages.
| Classification | Description |
|----------------|-------------|
| **Beta**<sup>*</sup> | Preview features used for gathering feedback and iterating on a less mature use case. Availability may be limited, including through sign-up requirements or waitlists, and may not be publicly announced. <br/><br/> Features may change significantly or be discontinued based on feedback. Not guaranteed for ongoing production use. Breaking changes are possible with notice, and some platform-specific limitations may apply. Beta features have a [beta header](/docs/en/api/beta-headers). |
| **Generally available (GA)** | Feature is stable, fully supported, and recommended for production use. Should not have a beta header or other indicator that the feature is in a preview state. Covered by standard API [versioning](/docs/en/api/versioning) guarantees. |
| **Deprecated** | Feature is still functional but no longer recommended. A migration path and removal timeline are provided. |
| **Retired** | Feature is no longer available. |
_<sup>*</sup> May carry a qualifier indicating narrower availability or added constraints (for example, "beta: research preview"). See the feature's page for details._
## Model capabilities
Ways to steer Claude and Claude's direct outputs, including response format, reasoning depth, and input modalities.
<Tip>
You can discover which capabilities a model supports programmatically. The [Models API](/docs/en/api/models/list) returns `max_input_tokens`, `max_tokens`, and a `capabilities` object for every available model.
</Tip>
| Feature | Description | Zero Data Retention (ZDR) | Availability |
|---------|-----------|----|--------------|
| [Context windows](/docs/en/build-with-claude/context-windows) | Up to 1M tokens for processing large documents, extensive codebases, and long conversations. | ZDR eligible | <PlatformAvailability claudeApi bedrock vertexAi azureAiBeta /> |
| [Adaptive thinking](/docs/en/build-with-claude/adaptive-thinking) | Let Claude dynamically decide when and how much to think. The recommended thinking mode for Opus 4.7. Use the effort parameter to control thinking depth. | ZDR eligible | <PlatformAvailability claudeApi bedrock vertexAi azureAiBeta /> |
| [Batch processing](/docs/en/build-with-claude/batch-processing) | Process large volumes of requests asynchronously for cost savings. Send batches with a large number of queries per batch. Batch API calls cost 50% less than standard API calls. | Not ZDR eligible | <PlatformAvailability claudeApi bedrock vertexAi /> |
| [Citations](/docs/en/build-with-claude/citations) | Ground Claude's responses in source documents. With Citations, Claude can provide detailed references to the exact sentences and passages it uses to generate responses, leading to more verifiable, trustworthy outputs. | ZDR eligible | <PlatformAvailability claudeApi bedrock vertexAi azureAiBeta /> |
| [Data residency](/docs/en/build-with-claude/data-residency) | Control where model inference runs using geographic controls. Specify `"global"` or `"us"` routing per request via the `inference_geo` parameter. | ZDR eligible | <PlatformAvailability claudeApi /> |
| [Effort](/docs/en/build-with-claude/effort) | Control how many tokens Claude uses when responding with the effort parameter, trading off between response thoroughness and token efficiency. Supported on Opus 4.7, Opus 4.6, and Opus 4.5. | ZDR eligible | <PlatformAvailability claudeApi bedrock vertexAi azureAiBeta /> |
| [Extended thinking](/docs/en/build-with-claude/extended-thinking) | Enhanced reasoning capabilities for complex tasks, providing transparency into Claude's step-by-step thought process before delivering its final answer. | ZDR eligible | <PlatformAvailability claudeApi bedrock vertexAi azureAiBeta /> |
| [PDF support](/docs/en/build-with-claude/pdf-support) | Process and analyze text and visual content from PDF documents. | ZDR eligible | <PlatformAvailability claudeApi bedrock vertexAi azureAiBeta /> |
| [Search results](/docs/en/build-with-claude/search-results) | Enable natural citations for RAG applications by providing search results with proper source attribution. Achieve web search-quality citations for custom knowledge bases and tools. | ZDR eligible | <PlatformAvailability claudeApi bedrock vertexAi azureAiBeta /> |
| [Structured outputs](/docs/en/build-with-claude/structured-outputs) | Guarantee schema conformance with two approaches: JSON outputs for structured data responses, and strict tool use for validated tool inputs. | [ZDR eligible (qualified)](/docs/en/build-with-claude/structured-outputs#data-retention)* | <PlatformAvailability claudeApi bedrock azureAiBeta /> |
## Tools
Built-in tools that Claude invokes via `tool_use`. Server-side tools are run by the platform; client-side tools are implemented and executed by you.
### Server-side tools
| Feature | Description | ZDR | Availability |
|---------|-----------|----|--------------|
| [Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool) | Pair a faster executor model with a higher-intelligence advisor model that provides strategic guidance mid-generation for long-horizon agentic workloads. | ZDR eligible | <PlatformAvailability claudeApiBeta /> |
| [Code execution](/docs/en/agents-and-tools/tool-use/code-execution-tool) | Run code in a sandboxed environment for advanced data analysis, calculations, and file processing. Free when used with web search or web fetch. | Not ZDR eligible | <PlatformAvailability claudeApi azureAiBeta /> |
| [Web fetch](/docs/en/agents-and-tools/tool-use/web-fetch-tool) | Retrieve full content from specified web pages and PDF documents for in-depth analysis. | ZDR eligible* | <PlatformAvailability claudeApi azureAiBeta /> |
| [Web search](/docs/en/agents-and-tools/tool-use/web-search-tool) | Augment Claude's comprehensive knowledge with current, real-world data from across the web. | ZDR eligible* | <PlatformAvailability claudeApi vertexAi azureAiBeta /> |
### Client-side tools
| Feature | Description | ZDR | Availability |
|---------|-----------|----|--------------|
| [Bash](/docs/en/agents-and-tools/tool-use/bash-tool) | Execute bash commands and scripts to interact with the system shell and perform command-line operations. | ZDR eligible | <PlatformAvailability claudeApi bedrock vertexAi azureAiBeta /> |
| [Computer use](/docs/en/agents-and-tools/tool-use/computer-use-tool) | Control computer interfaces by taking screenshots and issuing mouse and keyboard commands. | ZDR eligible | <PlatformAvailability claudeApiBeta bedrockBeta vertexAiBeta azureAiBeta /> |
| [Memory](/docs/en/agents-and-tools/tool-use/memory-tool) | Enable Claude to store and retrieve information across conversations. Build knowledge bases over time, maintain project context, and learn from past interactions. | ZDR eligible | <PlatformAvailability claudeApi bedrock vertexAi azureAiBeta /> |
| [Text editor](/docs/en/agents-and-tools/tool-use/text-editor-tool) | Create and edit text files with a built-in text editor interface for file manipulation tasks. | ZDR eligible | <PlatformAvailability claudeApi bedrock vertexAi azureAiBeta /> |
## Tool infrastructure
Infrastructure that supports discovering, orchestrating, and scaling tool use.
| Feature | Description | ZDR | Availability |
|---------|-----------|----|--------------|
| [Agent Skills](/docs/en/agents-and-tools/agent-skills/overview) | Extend Claude's capabilities with Skills. Use pre-built Skills (PowerPoint, Excel, Word, PDF) or create custom Skills with instructions and scripts. Skills use progressive disclosure to efficiently manage context. | Not ZDR eligible | <PlatformAvailability claudeApiBeta azureAiBeta /> |
| [Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming) | Stream tool use parameters without buffering/JSON validation, reducing latency for receiving large parameters. | ZDR eligible | <PlatformAvailability claudeApi bedrock vertexAi azureAiBeta /> |
| [MCP connector](/docs/en/agents-and-tools/mcp-connector) | Connect to remote [MCP](/docs/en/mcp) servers directly from the Messages API without a separate MCP client. | Not ZDR eligible | <PlatformAvailability claudeApiBeta azureAiBeta /> |
| [Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) | Enable Claude to call your tools programmatically from within code execution containers, reducing latency and token consumption for multi-tool workflows. | Not ZDR eligible | <PlatformAvailability claudeApi azureAiBeta /> |
| [Tool search](/docs/en/agents-and-tools/tool-use/tool-search-tool) | Scale to thousands of tools by dynamically discovering and loading tools on-demand using regex-based search, optimizing context usage and improving tool selection accuracy. | ZDR eligible | <PlatformAvailability claudeApi bedrock vertexAi azureAiBeta /> |
## Context management
Infrastructure for controlling and optimizing Claude's context window.
| Feature | Description | ZDR | Availability |
|---------|-----------|----|--------------|
| [Compaction](/docs/en/build-with-claude/compaction) | Server-side context summarization for long-running conversations. When context approaches the window limit, the API automatically summarizes earlier parts of the conversation. Supported on Opus 4.7, Opus 4.6, and Sonnet 4.6. | ZDR eligible | <PlatformAvailability claudeApiBeta bedrockBeta vertexAiBeta azureAiBeta /> |
| [Context editing](/docs/en/build-with-claude/context-editing) | Automatically manage conversation context with configurable strategies. Supports clearing tool results when approaching token limits and managing thinking blocks in extended thinking conversations. | ZDR eligible | <PlatformAvailability claudeApiBeta bedrockBeta vertexAiBeta azureAiBeta /> |
| [Automatic prompt caching](/docs/en/build-with-claude/prompt-caching#automatic-caching) | Simplify prompt caching to a single API parameter. The system automatically caches the last cacheable block in your request, moving the cache point forward as conversations grow. | ZDR eligible | <PlatformAvailability claudeApi azureAiBeta /> |
| [Prompt caching (5m)](/docs/en/build-with-claude/prompt-caching) | Provide Claude with more background knowledge and example outputs to reduce costs and latency. | ZDR eligible | <PlatformAvailability claudeApi bedrock vertexAi azureAiBeta /> |
| [Prompt caching (1hr)](/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration) | Extended 1-hour cache duration for less frequently accessed but important context, complementing the standard 5-minute cache. | ZDR eligible | <PlatformAvailability claudeApi vertexAi azureAiBeta /> |
| [Token counting](/docs/en/api/messages-count-tokens) | Token counting enables you to determine the number of tokens in a message before sending it to Claude, helping you make informed decisions about your prompts and usage. | ZDR eligible | <PlatformAvailability claudeApi bedrock vertexAi azureAiBeta /> |
## Files and assets
Manage files and assets for use with Claude.
| Feature | Description | ZDR | Availability |
|---------|-----------|----|--------------|
| [Files API](/docs/en/build-with-claude/files) | Upload and manage files to use with Claude without re-uploading content with each request. Supports PDFs, images, and text files. | Not ZDR eligible | <PlatformAvailability claudeApiBeta azureAiBeta /> |
\* **Structured outputs:** Your prompts and Claude's outputs are not stored. Only JSON schemas are cached, for up to 24 hours since last use. **Web search and web fetch:** ZDR-eligible except when [dynamic filtering](/docs/en/agents-and-tools/tool-use/web-search-tool#dynamic-filtering) is enabled. See [ZDR details](/docs/en/build-with-claude/api-and-data-retention#feature-eligibility).
---
## Guides/build-with-claude-pdf-support-01e729abfc.md
# PDF support
Process PDFs with Claude. Extract text, analyze charts, and understand visual content from your documents.
---
<Note>
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.
</Note>
You can ask Claude about any text, pictures, charts, and tables in PDFs you provide. Some sample use cases:
- Analyzing financial reports and understanding charts/tables
- Extracting key information from legal documents
- Translation assistance for documents
- Converting document information into structured formats
## Before you begin
### Check PDF requirements
Claude works with any standard PDF. Ensure your request size meets these requirements:
| Requirement | Limit |
|------------|--------|
| Maximum request size | 32 MB ([varies by platform](/docs/en/api/overview#request-size-limits)) |
| Maximum pages per request | 600 (100 for models with a 200k-token context window) |
| Format | Standard PDF (no passwords/encryption) |
Both limits are on the entire request payload, including any other content sent alongside PDFs. For large PDFs, consider uploading with the [Files API](#option-3-files-api) and referencing by `file_id` to keep request payloads small.
<Tip>
Dense PDFs (many small-font pages, complex tables, or heavy graphics) can fill the context window before reaching the page limit. Requests with large PDFs can also fail before reaching the page limit, even when using the Files API. Try splitting the document into sections; for large files, since each page is processed as an image, downsampling embedded images can also help.
</Tip>
Since PDF support relies on Claude's vision capabilities, it is subject to the same [limitations and considerations](/docs/en/build-with-claude/vision#limitations) as other vision tasks.
### Supported platforms and models
PDF support is currently supported via direct API access and Google Vertex AI. All [active models](/docs/en/about-claude/models/overview) support PDF processing.
PDF support is now available on Amazon Bedrock with the following considerations:
### Amazon Bedrock PDF Support
When using PDF support through Amazon Bedrock's Converse API, there are two distinct document processing modes:
<Note>
**Important:** To access Claude's full visual PDF understanding capabilities in the Converse API, you must enable citations. Without citations enabled, the API falls back to basic text extraction only. Learn more about [working with citations](/docs/en/build-with-claude/citations).
</Note>
#### Document Processing Modes
1. **Converse Document Chat** (Original mode - Text extraction only)
- Provides basic text extraction from PDFs
- Cannot analyze images, charts, or visual layouts within PDFs
- Uses approximately 1,000 tokens for a 3-page PDF
- Automatically used when citations are not enabled
2. **Claude PDF Chat** (New mode - Full visual understanding)
- Provides complete visual analysis of PDFs
- Can understand and analyze charts, graphs, images, and visual layouts
- Processes each page as both text and image for comprehensive understanding
- Uses approximately 7,000 tokens for a 3-page PDF
- **Requires citations to be enabled** in the Converse API
#### Key Limitations
- **Converse API**: Visual PDF analysis requires citations to be enabled. There is currently no option to use visual analysis without citations (unlike the InvokeModel API).
- **InvokeModel API**: Provides full control over PDF processing without forced citations.
#### Common Issues
If customers report that Claude isn't seeing images or charts in their PDFs when using the Converse API, they likely need to enable the citations flag. Without it, Converse falls back to basic text extraction only.
<Note>
This is a known constraint with the Converse API. For applications that require visual PDF analysis without citations, consider using the InvokeModel API instead.
</Note>
<Note>
For non-PDF files like .csv, .xlsx, .docx, .md, or .txt files, see [Working with other file formats](/docs/en/build-with-claude/files#working-with-other-file-formats).
</Note>
***
## Process PDFs with Claude
### Send your first PDF request
Let's start with a simple example using the Messages API. You can provide PDFs to Claude in three ways:
1. As a URL reference to a PDF hosted online
2. As a base64-encoded PDF in `document` content blocks
3. By a `file_id` from the [Files API](/docs/en/build-with-claude/files)
#### Option 1: URL-based PDF document
The simplest approach is to reference a PDF directly from a URL:
<CodeGroup>
```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": [{
"type": "document",
"source": {
"type": "url",
"url": "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf"
}
},
{
"type": "text",
"text": "What are the key findings in this document?"
}]
}]
}'
```
```bash CLI
ant messages create --transform content --format yaml <<'YAML'
model: claude-opus-4-7
max_tokens: 1024
messages:
- role: user
content:
- type: document
source:
type: url
url: https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf
- type: text
text: What are the key findings in this document?
YAML
```
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "url",
"url": "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf",
},
},
{"type": "text", "text": "What are the key findings in this document?"},
],
}
],
)
print(message.content)
```
```typescript TypeScript hidelines={1..4}
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: 1024,
messages: [
{
role: "user",
content: [
{
type: "document",
source: {
type: "url",
url: "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf"
}
},
{
type: "text",
text: "What are the key findings in this document?"
}
]
}
]
});
console.log(response);
}
main();
```
```java Java hidelines={1..8,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.*;
import java.util.List;
public class PdfUrlExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Create document block with URL
DocumentBlockParam documentParam = DocumentBlockParam.builder()
.source(
UrlPdfSource.builder()
.url(
"https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf"
)
.build()
)
.build();
// Create a message with document and text content blocks
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(1024)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofDocument(documentParam),
ContentBlockParam.ofText(
TextBlockParam.builder()
.text("What are the key findings in this document?")
.build()
)
)
)
.build();
Message message = client.messages().create(params);
System.out.println(message.content());
}
}
```
</CodeGroup>
#### Option 2: Base64-encoded PDF document
If you need to send PDFs from your local system or when a URL isn't available:
<CodeGroup>
```bash cURL hidelines={1}
cd "$(mktemp -d)"
# Method 1: Fetch and encode a remote PDF
curl -s "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf" | base64 | tr -d '\n' > pdf_base64.txt
# Method 2: Encode a local PDF file
# base64 document.pdf | tr -d '\n' > pdf_base64.txt
# Create a JSON request file using the pdf_base64.txt content
jq -n --rawfile PDF_BASE64 pdf_base64.txt '{
"model": "claude-opus-4-7",
"max_tokens": 1024,
"messages": [{
"role": "user",
"content": [{
"type": "document",
"source": {
"type": "base64",
"media_type": "application/pdf",
"data": $PDF_BASE64
}
},
{
"type": "text",
"text": "What are the key findings in this document?"
}]
}]
}' > request.json
# Send the API request using the JSON file
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 @request.json
```
```bash CLI hidelines={1..2}
cd "$(mktemp -d)"
curl -sSo document.pdf https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf
ant messages create \
--model claude-opus-4-7 \
--max-tokens 1024 \
--transform content --format yaml <<'YAML'
messages:
- role: user
content:
- type: document
source:
type: base64
media_type: application/pdf
data: "@./document.pdf"
- type: text
text: What are the key findings in this document?
YAML
```
```python Python hidelines={1}
import anthropic
import base64
import httpx
# First, load and encode the PDF
pdf_url = "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf"
pdf_data = base64.standard_b64encode(httpx.get(pdf_url).content).decode("utf-8")
# Alternative: Load from a local file
# with open("document.pdf", "rb") as f:
# pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")
# Send to Claude using base64 encoding
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "base64",
"media_type": "application/pdf",
"data": pdf_data,
},
},
{"type": "text", "text": "What are the key findings in this document?"},
],
}
],
)
print(message.content)
```
```typescript TypeScript hidelines={1..3,-3..-1}
import Anthropic from "@anthropic-ai/sdk";
async function main() {
// Method 1: Fetch and encode a remote PDF
const pdfURL =
"https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf";
const pdfResponse = await fetch(pdfURL);
const arrayBuffer = await pdfResponse.arrayBuffer();
const pdfBase64 = Buffer.from(arrayBuffer).toString("base64");
// Method 2: Load from a local file
// import fs from "fs";
// const pdfBase64 = (await fs.readFile('document.pdf')).toString('base64');
// Send the API request with base64-encoded PDF
const anthropic = new Anthropic();
const response = await anthropic.messages.create({
model: "claude-opus-4-7",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
{
type: "document",
source: {
type: "base64",
media_type: "application/pdf",
data: pdfBase64
}
},
{
type: "text",
text: "What are the key findings in this document?"
}
]
}
]
});
console.log(response);
}
main();
```
```java Java hidelines={1..2,4,6..22,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.Base64PdfSource;
import com.anthropic.models.messages.ContentBlockParam;
import com.anthropic.models.messages.DocumentBlockParam;
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 java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;
import java.util.List;
public class PdfBase64Example {
public static void main(String[] args) throws IOException, InterruptedException {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Method 1: Download and encode a remote PDF
String pdfUrl =
"https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf";
HttpClient httpClient = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder().uri(URI.create(pdfUrl)).GET().build();
HttpResponse<byte[]> response = httpClient.send(
request,
HttpResponse.BodyHandlers.ofByteArray()
);
String pdfBase64 = Base64.getEncoder().encodeToString(response.body());
// Method 2: Load from a local file
// byte[] fileBytes = Files.readAllBytes(Path.of("document.pdf"));
// String pdfBase64 = Base64.getEncoder().encodeToString(fileBytes);
// Create document block with base64 data
DocumentBlockParam documentParam = DocumentBlockParam.builder()
.source(Base64PdfSource.builder().data(pdfBase64).build())
.build();
// Create a message with document and text content blocks
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(1024)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofDocument(documentParam),
ContentBlockParam.ofText(
TextBlockParam.builder()
.text("What are the key findings in this document?")
.build()
)
)
)
.build();
Message message = client.messages().create(params);
System.out.println(message.content());
}
}
```
</CodeGroup>
#### Option 3: Files API
For PDFs you'll use repeatedly, or when you want to avoid encoding overhead, use the [Files API](/docs/en/build-with-claude/files):
<CodeGroup>
```bash cURL hidelines={1..2}
cd "$(mktemp -d)"
curl -sSo document.pdf https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf
# First, upload your PDF to the Files API
curl -X POST https://api.anthropic.com/v1/files \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: files-api-2025-04-14" \
-F "file=@document.pdf"
# Then use the returned file_id in your message
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: files-api-2025-04-14" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 1024,
"messages": [{
"role": "user",
"content": [{
"type": "document",
"source": {
"type": "file",
"file_id": "file_abc123"
}
},
{
"type": "text",
"text": "What are the key findings in this document?"
}]
}]
}'
```
```bash CLI nocheck hidelines={1..2}
cd "$(mktemp -d)"
curl -sSo document.pdf https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf
# First, upload your PDF to the Files API
FILE_ID=$(ant beta:files upload \
--file ./document.pdf \
--transform id --format yaml)
# Then use the returned file_id in your message
ant beta:messages create \
--beta files-api-2025-04-14 \
--transform content --format yaml <<YAML
model: claude-opus-4-7
max_tokens: 1024
messages:
- role: user
content:
- type: document
source:
type: file
file_id: $FILE_ID
- type: text
text: What are the key findings in this document?
YAML
```
```python Python nocheck hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
# Upload the PDF file
with open("document.pdf", "rb") as f:
file_upload = client.beta.files.upload(file=("document.pdf", f, "application/pdf"))
# Use the uploaded file in a message
message = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
betas=["files-api-2025-04-14"],
messages=[
{
"role": "user",
"content": [
{
"type": "document",
"source": {"type": "file", "file_id": file_upload.id},
},
{"type": "text", "text": "What are the key findings in this document?"},
],
}
],
)
print(message.content)
```
```typescript TypeScript nocheck
import Anthropic, { toFile } from "@anthropic-ai/sdk";
import fs from "fs";
const anthropic = new Anthropic();
async function main() {
// Upload the PDF file
const fileUpload = await anthropic.beta.files.upload({
file: await toFile(fs.createReadStream("document.pdf"), undefined, {
type: "application/pdf"
})
});
// Use the uploaded file in a message
const response = await anthropic.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 1024,
betas: ["files-api-2025-04-14"],
messages: [
{
role: "user",
content: [
{
type: "document",
source: {
type: "file",
file_id: fileUpload.id
}
},
{
type: "text",
text: "What are the key findings in this document?"
}
]
}
]
});
console.log(response);
}
main();
```
```java Java nocheck hidelines={1..3,6,8,10..19,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.Model;
import com.anthropic.models.beta.files.FileMetadata;
import com.anthropic.models.beta.files.FileUploadParams;
import com.anthropic.models.beta.messages.BetaContentBlockParam;
import com.anthropic.models.beta.messages.BetaFileDocumentSource;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaRequestDocumentBlock;
import com.anthropic.models.beta.messages.BetaTextBlockParam;
import com.anthropic.models.beta.messages.MessageCreateParams;
import java.nio.file.Path;
import java.util.List;
public class PdfFilesExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Upload the PDF file
FileMetadata file = client
.beta()
.files()
.upload(FileUploadParams.builder().file(Path.of("document.pdf")).build());
// Use the uploaded file in a message
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.addBeta("files-api-2025-04-14")
.maxTokens(1024)
.addUserMessageOfBetaContentBlockParams(
List.of(
BetaContentBlockParam.ofDocument(
BetaRequestDocumentBlock.builder()
.source(
BetaFileDocumentSource.builder()
.fileId(file.id())
.build()
)
.build()
),
BetaContentBlockParam.ofText(
BetaTextBlockParam.builder()
.text("What are the key findings in this document?")
.build()
)
)
)
.build();
BetaMessage message = client.beta().messages().create(params);
System.out.println(message.content());
}
}
```
</CodeGroup>
### How PDF support works
When you send a PDF to Claude, the following steps occur:
<Steps>
<Step title="The system extracts the contents of the document.">
- The system converts each page of the document into an image.
- The text from each page is extracted and provided alongside each page's image.
</Step>
<Step title="Claude analyzes both the text and images to better understand the document.">
- Documents are provided as a combination of text and images for analysis.
- This allows users to ask for insights on visual elements of a PDF, such as charts, diagrams, and other non-textual content.
</Step>
<Step title="Claude responds, referencing the PDF's contents if relevant.">
Claude can reference both textual and visual content when it responds. You can further improve performance by integrating PDF support with:
- **Prompt caching**: To improve performance for repeated analysis.
- **Batch processing**: For high-volume document processing.
- **Tool use**: To extract specific information from documents for use as tool inputs.
</Step>
</Steps>
### Estimate your costs
The token count of a PDF file depends on the total text extracted from the document as well as the number of pages:
- Text token costs: Each page typically uses 1,500-3,000 tokens per page depending on content density. Standard API pricing applies with no additional PDF fees.
- Image token costs: Since each page is converted into an image, the same [image-based cost calculations](/docs/en/build-with-claude/vision#evaluate-image-size) are applied.
You can use [token counting](/docs/en/build-with-claude/token-counting) to estimate costs for your specific PDFs.
***
## Optimize PDF processing
### Improve performance
Follow these best practices for optimal results:
- Place PDFs before text in your requests
- Use standard fonts
- Ensure text is clear and legible
- Rotate pages to proper upright orientation
- Use logical page numbers (from PDF viewer) in prompts
- Split large PDFs into chunks when needed
- Enable prompt caching for repeated analysis
### Scale your implementation
For high-volume processing, consider these approaches:
#### Use prompt caching
Cache PDFs to improve performance on repeated queries:
<CodeGroup>
```bash cURL hidelines={1..2}
cd "$(mktemp -d)"
curl -s "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf" | base64 | tr -d '\n' > pdf_base64.txt
# Create a JSON request file using the pdf_base64.txt content
jq -n --rawfile PDF_BASE64 pdf_base64.txt '{
"model": "claude-opus-4-7",
"max_tokens": 1024,
"messages": [{
"role": "user",
"content": [{
"type": "document",
"source": {
"type": "base64",
"media_type": "application/pdf",
"data": $PDF_BASE64
},
"cache_control": {
"type": "ephemeral"
}
},
{
"type": "text",
"text": "Which model has the highest human preference win rates across each use-case?"
}]
}]
}' > request.json
# Then make the API call using the JSON file
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 @request.json
```
```bash CLI hidelines={1..2}
cd "$(mktemp -d)"
curl -sSo document.pdf https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf
ant messages create <<'YAML'
model: claude-opus-4-7
max_tokens: 1024
messages:
- role: user
content:
- type: document
source:
type: base64
media_type: application/pdf
data: "@./document.pdf"
cache_control:
type: ephemeral
- type: text
text: Which model has the highest human preference win rates across each use-case?
YAML
```
```python Python nocheck hidelines={1..5,7..13}
import anthropic
import base64
from pypdf import PdfWriter
import io
client = anthropic.Anthropic()
buf = io.BytesIO()
writer = PdfWriter()
writer.add_blank_page(width=72, height=72)
writer.write(buf)
pdf_data = base64.standard_b64encode(buf.getvalue()).decode("utf-8")
message = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "base64",
"media_type": "application/pdf",
"data": pdf_data,
},
"cache_control": {"type": "ephemeral"},
},
{"type": "text", "text": "Analyze this document."},
],
}
],
)
```
```typescript TypeScript nocheck
const response = await anthropic.messages.create({
model: "claude-opus-4-7",
max_tokens: 1024,
messages: [
{
content: [
{
type: "document",
source: {
media_type: "application/pdf",
type: "base64",
data: pdfBase64
},
cache_control: { type: "ephemeral" }
},
{
type: "text",
text: "Which model has the highest human preference win rates across each use-case?"
}
],
role: "user"
}
]
});
console.log(response);
```
```java Java nocheck hidelines={1..2,5,7..20,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.Base64PdfSource;
import com.anthropic.models.messages.CacheControlEphemeral;
import com.anthropic.models.messages.ContentBlockParam;
import com.anthropic.models.messages.DocumentBlockParam;
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 java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.List;
public class MessagesDocumentExample {
public static void main(String[] args) throws IOException {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Read PDF file as base64
byte[] pdfBytes = Files.readAllBytes(Paths.get("pdf_base64.txt"));
String pdfBase64 = new String(pdfBytes);
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(1024)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofDocument(
DocumentBlockParam.builder()
.source(Base64PdfSource.builder().data(pdfBase64).build())
.cacheControl(CacheControlEphemeral.builder().build())
.build()
),
ContentBlockParam.ofText(
TextBlockParam.builder()
.text(
"Which model has the highest human preference win rates across each use-case?"
)
.build()
)
)
)
.build();
Message message = client.messages().create(params);
System.out.println(message);
}
}
```
</CodeGroup>
#### Process document batches
Use the Message Batches API for high-volume workflows:
<CodeGroup>
```bash cURL hidelines={1..2}
cd "$(mktemp -d)"
curl -s "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf" | base64 | tr -d '\n' > pdf_base64.txt
# Create a JSON request file using the pdf_base64.txt content
jq -n --rawfile PDF_BASE64 pdf_base64.txt '
{
"requests": [
{
"custom_id": "my-first-request",
"params": {
"model": "claude-opus-4-7",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "base64",
"media_type": "application/pdf",
"data": $PDF_BASE64
}
},
{
"type": "text",
"text": "Which model has the highest human preference win rates across each use-case?"
}
]
}
]
}
},
{
"custom_id": "my-second-request",
"params": {
"model": "claude-opus-4-7",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "base64",
"media_type": "application/pdf",
"data": $PDF_BASE64
}
},
{
"type": "text",
"text": "Extract 5 key insights from this document."
}
]
}
]
}
}
]
}
' > request.json
# Then make the API call using the JSON file
curl https://api.anthropic.com/v1/messages/batches \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d @request.json
```
```bash CLI hidelines={1..2}
cd "$(mktemp -d)"
curl -sSo document.pdf https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf
ant messages:batches create <<'YAML'
requests:
- custom_id: my-first-request
params:
model: claude-opus-4-7
max_tokens: 1024
messages:
- role: user
content:
- type: document
source:
type: base64
media_type: application/pdf
data: "@./document.pdf"
- type: text
text: >-
Which model has the highest human preference win rates
across each use-case?
- custom_id: my-second-request
params:
model: claude-opus-4-7
max_tokens: 1024
messages:
- role: user
content:
- type: document
source:
type: base64
media_type: application/pdf
data: "@./document.pdf"
- type: text
text: Extract 5 key insights from this document.
YAML
```
```python Python nocheck hidelines={1..5,7..13}
import anthropic
import base64
from pypdf import PdfWriter
import io
client = anthropic.Anthropic()
buf = io.BytesIO()
writer = PdfWriter()
writer.add_blank_page(width=72, height=72)
writer.write(buf)
pdf_data = base64.standard_b64encode(buf.getvalue()).decode("utf-8")
message_batch = client.messages.batches.create(
requests=[
{
"custom_id": "doc1",
"params": {
"model": "claude-opus-4-7",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "base64",
"media_type": "application/pdf",
"data": pdf_data,
},
},
{"type": "text", "text": "Summarize this document."},
],
}
],
},
}
]
)
```
```typescript TypeScript nocheck
const response = await anthropic.messages.batches.create({
requests: [
{
custom_id: "my-first-request",
params: {
max_tokens: 1024,
messages: [
{
content: [
{
type: "document",
source: {
media_type: "application/pdf",
type: "base64",
data: pdfBase64
}
},
{
type: "text",
text: "Which model has the highest human preference win rates across each use-case?"
}
],
role: "user"
}
],
model: "claude-opus-4-7"
}
},
{
custom_id: "my-second-request",
params: {
max_tokens: 1024,
messages: [
{
content: [
{
type: "document",
source: {
media_type: "application/pdf",
type: "base64",
data: pdfBase64
}
},
{
type: "text",
text: "Extract 5 key insights from this document."
}
],
role: "user"
}
],
model: "claude-opus-4-7"
}
}
]
});
console.log(response);
```
```java Java nocheck hidelines={1..3,5..14,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.*;
import com.anthropic.models.messages.batches.*;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.List;
public class MessagesBatchDocumentExample {
public static void main(String[] args) throws IOException {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Read PDF file as base64
byte[] pdfBytes = Files.readAllBytes(Paths.get("pdf_base64.txt"));
String pdfBase64 = new String(pdfBytes);
BatchCreateParams params = BatchCreateParams.builder()
.addRequest(
BatchCreateParams.Request.builder()
.customId("my-first-request")
.params(
BatchCreateParams.Request.Params.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(1024)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofDocument(
DocumentBlockParam.builder()
.source(Base64PdfSource.builder().data(pdfBase64).build())
.build()
),
ContentBlockParam.ofText(
TextBlockParam.builder()
.text(
"Which model has the highest human preference win rates across each use-case?"
)
.build()
)
)
)
.build()
)
.build()
)
.addRequest(
BatchCreateParams.Request.builder()
.customId("my-second-request")
.params(
BatchCreateParams.Request.Params.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(1024)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofDocument(
DocumentBlockParam.builder()
.source(Base64PdfSource.builder().data(pdfBase64).build())
.build()
),
ContentBlockParam.ofText(
TextBlockParam.builder()
.text("Extract 5 key insights from this document.")
.build()
)
)
)
.build()
)
.build()
)
.build();
MessageBatch batch = client.messages().batches().create(params);
System.out.println(batch);
}
}
```
</CodeGroup>
## Next steps
<CardGroup cols={2}>
<Card
title="Try PDF examples"
icon="file"
href="https://platform.claude.com/cookbook/multimodal-getting-started-with-vision"
>
Explore practical examples of PDF processing in the cookbook recipe.
</Card>
<Card
title="View API reference"
icon="code"
href="/docs/en/api/messages/create"
>
See complete API documentation for PDF support.
</Card>
</CardGroup>
---
## Guides/build-with-claude-rate-limits-api-f95b04961e.md
# Rate Limits API
Programmatically query your organization's API rate limits with the Rate Limits API.
---
<Tip>
**The Admin API is unavailable for individual accounts.** To collaborate with teammates and add members, set up your organization in **Console → Settings → Organization**.
</Tip>
The Rate Limits API provides programmatic access to the rate limits configured for your organization and its workspaces. This is the same information shown on the [Limits](/settings/limits) page in the Claude Console.
Use this API to:
- **Keep gateways and proxies in sync:** Read your current limits at startup and on a schedule instead of hardcoding values that drift when Anthropic adjusts them.
- **Power internal alerting:** Compare usage data from the [Usage and Cost API](/docs/en/build-with-claude/usage-cost-api) against your configured limits.
- **Audit workspace configuration:** Verify that workspace overrides match what your provisioning automation expects.
<Check>
**Admin API key required**
This API is part of the [Admin API](/docs/en/build-with-claude/administration-api). These endpoints require an Admin API key (starting with `sk-ant-admin...`) that differs from standard API keys. Only organization members with the admin role can provision Admin API keys through the [Claude Console](/settings/admin-keys).
</Check>
## Quick start
List the rate limits configured for your organization:
```bash cURL
curl "https://api.anthropic.com/v1/organizations/rate_limits" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```
## Organization rate limits
The `/v1/organizations/rate_limits` endpoint returns the rate limits applied at the organization level for the Messages API and its supporting resources. Limits for other products, such as [Claude Managed Agents](/docs/en/managed-agents/overview), are not included.
### Key concepts
- **Rate limit groups:** Each entry in the response represents one rate limit group. Model rate limits are grouped so that several model versions share a single set of limits, and other groups cover resources such as the Message Batches API, the Files API, the Token Counting API, agent skills, and the web search tool.
- **`group_type`:** Identifies which category of limits the entry covers. See [Filtering by group type](#filtering-by-group-type) for the list of values.
- **`models` list:** For `model_group` entries, the `models` field lists every model ID and alias that counts against that group's limits. Use this list to look up which group any model string falls under. For other group types, `models` is `null`.
- **`limits` list:** Each group carries a list of `{type, value}` pairs. The `type` field identifies the limiter (such as `requests_per_minute`, `input_tokens_per_minute`, or `output_tokens_per_minute`) and `value` is the configured limit. See [Rate limits](/docs/en/api/rate-limits) for how each limiter is measured and enforced.
For complete parameter details and response schemas, see the [Organization Rate Limits API reference](/docs/en/api/admin/rate_limits/list).
### List all organization rate limits
```bash cURL
curl "https://api.anthropic.com/v1/organizations/rate_limits" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```
```json
{
"data": [
{
"type": "rate_limit",
"group_type": "model_group",
"models": [
"claude-opus-4-5",
"claude-opus-4-5-20251101",
"claude-opus-4-6",
"claude-opus-4-7"
],
"limits": [
{ "type": "requests_per_minute", "value": 4000 },
{ "type": "input_tokens_per_minute", "value": 2000000 },
{ "type": "output_tokens_per_minute", "value": 400000 }
]
},
{
"type": "rate_limit",
"group_type": "batch",
"models": null,
"limits": [{ "type": "enqueued_batch_requests", "value": 500000 }]
}
],
"next_page": null
}
```
### Look up the limits for a specific model
Pass any model ID or alias as the `model` query parameter to return only the entry that contains it:
```bash cURL
curl "https://api.anthropic.com/v1/organizations/rate_limits?model=claude-opus-4-7" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```
If the model string doesn't match any group, the endpoint returns a 404 error. The `model` parameter is supported on the organization endpoint only; the workspace endpoint doesn't accept it.
## Workspace rate limits
The `/v1/organizations/workspaces/{workspace_id}/rate_limits` endpoint returns the rate limit overrides configured for a single workspace.
The response only includes overrides, so anything missing from it is inherited from the organization:
- A group that is absent from `data` has no workspace override at all. The workspace inherits the organization-level limits for that group (it is not unlimited).
- Within a group that is present, a limiter type that is absent from `limits[]` has no workspace override for that limiter. The workspace inherits the organization value for it.
- For each limiter that is present, `org_limit` is the organization-level value for the same limiter, or `null` if the organization has no configured limit for that limiter type.
For complete parameter details and response schemas, see the [Workspace Rate Limits API reference](/docs/en/api/admin/workspaces/rate_limits/list).
<Tip>
To retrieve your organization's workspace IDs, use the [List Workspaces](/docs/en/api/admin/workspaces/list) endpoint, or find them in the [Claude Console](/settings/workspaces). The default workspace cannot have rate limit overrides, so it has no entry on this endpoint; use the organization endpoint to read its limits.
</Tip>
```bash cURL
curl "https://api.anthropic.com/v1/organizations/workspaces/wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ/rate_limits" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```
```json
{
"data": [
{
"type": "workspace_rate_limit",
"group_type": "model_group",
"models": [
"claude-opus-4-5",
"claude-opus-4-5-20251101",
"claude-opus-4-6",
"claude-opus-4-7"
],
"limits": [
{ "type": "requests_per_minute", "value": 1000, "org_limit": 4000 },
{ "type": "input_tokens_per_minute", "value": 500000, "org_limit": 2000000 }
]
}
],
"next_page": null
}
```
## Filtering by group type
Both endpoints accept an optional `group_type` query parameter that restricts the response to a single category:
```bash cURL
curl "https://api.anthropic.com/v1/organizations/rate_limits?group_type=batch" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_ADMIN_KEY"
```
Valid values are `model_group`, `batch`, `token_count`, `files`, `skills`, and `web_search`.
## Pagination
Both endpoints accept a `page` query parameter and return a `next_page` field. Responses are currently always a single page, so `next_page` is `null`. Loop on `next_page` so your client paginates correctly without changes when the response grows.
## Frequently asked questions
### Which model strings appear in the `models` list?
Every model ID and alias that counts against the group, including dated IDs (such as `claude-sonnet-4-5-20250929`) and undated aliases (such as `claude-sonnet-4-5`). Look up any model string you pass to the Messages API and you'll find it in exactly one `model_group` entry.
### What does it mean if a group is missing from the workspace response?
The workspace has no override for that group and inherits the organization-level limit. Query the organization endpoint to see the inherited values.
### Can I update rate limits with this API?
No. To set workspace rate limits, open the workspace in the [Claude Console](/settings/workspaces) and use the **Limits** tab.
## See also
- [Rate limits](/docs/en/api/rate-limits)
- [Admin API overview](/docs/en/build-with-claude/administration-api)
- [Admin API reference](/docs/en/api/admin)
- [Workspaces](/docs/en/build-with-claude/workspaces)
- [Usage and Cost API](/docs/en/build-with-claude/usage-cost-api)
---
## Guides/build-with-claude-search-results-e16f90758e.md
# Search results
Enable natural citations for RAG applications by providing search results with source attribution
---
<Note>
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.
</Note>
Search result content blocks enable natural citations with proper source attribution, bringing web search-quality citations to your custom applications. This feature is particularly powerful for RAG (Retrieval-Augmented Generation) applications where you need Claude to cite sources accurately.
The search results feature is available on the following models:
- 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 Sonnet 4.5 (`claude-sonnet-4-5-20250929`)
- Claude Opus 4.5 (`claude-opus-4-5-20251101`)
- Claude Opus 4.1 (`claude-opus-4-1-20250805`)
- Claude Opus 4 ([deprecated](/docs/en/about-claude/model-deprecations)) (`claude-opus-4-20250514`)
- Claude Sonnet 4 ([deprecated](/docs/en/about-claude/model-deprecations)) (`claude-sonnet-4-20250514`)
- Claude Sonnet 3.7 ([deprecated](/docs/en/about-claude/model-deprecations)) (`claude-3-7-sonnet-20250219`)
- Claude Haiku 4.5 (`claude-haiku-4-5-20251001`)
- Claude Haiku 3.5 ([deprecated](/docs/en/about-claude/model-deprecations)) (`claude-3-5-haiku-20241022`)
## Key benefits
- **Natural citations** - Achieve the same citation quality as web search for any content
- **Flexible integration** - Use in tool returns for dynamic RAG or as top-level content for pre-fetched data
- **Proper source attribution** - Each result includes source and title information for clear attribution
- **No document workarounds needed** - Eliminates the need for document-based workarounds
- **Consistent citation format** - Matches the citation quality and format of Claude's web search functionality
## How it works
Search results can be provided in two ways:
1. **From tool calls** - Your custom tools return search results, enabling dynamic RAG applications
2. **As top-level content** - You provide search results directly in user messages for pre-fetched or cached content
In both cases, Claude can automatically cite information from the search results with proper source attribution.
### Search result schema
Search results use the following structure:
```json
{
"type": "search_result",
"source": "https://example.com/article", // Required: Source URL or identifier
"title": "Article Title", // Required: Title of the result
"content": [
// Required: Array of text blocks
{
"type": "text",
"text": "The actual content of the search result..."
}
],
"citations": {
// Optional: Citation configuration
"enabled": true // Enable/disable citations for this result
}
}
```
### Required fields
| Field | Type | Description |
|-------|------|-------------|
| `type` | string | Must be `"search_result"` |
| `source` | string | The source URL or identifier for the content |
| `title` | string | A descriptive title for the search result |
| `content` | array | An array of text blocks containing the actual content |
### Optional fields
| Field | Type | Description |
|-------|------|-------------|
| `citations` | object | Citation configuration with `enabled` boolean field |
| `cache_control` | object | Cache control settings (e.g., `{"type": "ephemeral"}`) |
Each item in the `content` array must be a text block with:
- `type`: Must be `"text"`
- `text`: The actual text content (non-empty string)
## Method 1: Search results from tool calls
The most powerful use case is returning search results from your custom tools. This enables dynamic RAG applications where tools fetch and return relevant content with automatic citations.
### Example: Knowledge base tool
<CodeGroup>
```python Python nocheck hidelines={1}
from anthropic import Anthropic
from anthropic.types import (
MessageParam,
TextBlockParam,
SearchResultBlockParam,
ToolResultBlockParam,
)
client = Anthropic()
# Define a knowledge base search tool
knowledge_base_tool = {
"name": "search_knowledge_base",
"description": "Search the company knowledge base for information",
"input_schema": {
"type": "object",
"properties": {"query": {"type": "string", "description": "The search query"}},
"required": ["query"],
},
}
# Function to handle the tool call
def search_knowledge_base(query):
# Your search logic here
# Returns search results in the correct format
return [
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/product-guide",
title="Product Configuration Guide",
content=[
TextBlockParam(
type="text",
text="To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs.",
)
],
citations={"enabled": True},
),
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/troubleshooting",
title="Troubleshooting Guide",
content=[
TextBlockParam(
type="text",
text="If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values.",
)
],
citations={"enabled": True},
),
]
# Create a message with the tool
response = client.messages.create(
model="claude-opus-4-7", # Works with all supported models
max_tokens=1024,
tools=[knowledge_base_tool],
messages=[
MessageParam(role="user", content="How do I configure the timeout settings?")
],
)
# When Claude calls the tool, provide the search results
if response.content[0].type == "tool_use":
tool_result = search_knowledge_base(response.content[0].input["query"])
# Send the tool result back
final_response = client.messages.create(
model="claude-opus-4-7", # Works with all supported models
max_tokens=1024,
messages=[
MessageParam(
role="user", content="How do I configure the timeout settings?"
),
MessageParam(role="assistant", content=response.content),
MessageParam(
role="user",
content=[
ToolResultBlockParam(
type="tool_result",
tool_use_id=response.content[0].id,
content=tool_result, # Search results go here
)
],
),
],
)
```
```typescript TypeScript nocheck hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
// Define a knowledge base search tool
const knowledgeBaseTool: Anthropic.Messages.Tool = {
name: "search_knowledge_base",
description: "Search the company knowledge base for information",
input_schema: {
type: "object" as const,
properties: {
query: {
type: "string",
description: "The search query"
}
},
required: ["query"]
}
};
// Function to handle the tool call
function searchKnowledgeBase(query: string) {
// Your search logic here
// Returns search results in the correct format
return [
{
type: "search_result" as const,
source: "https://docs.company.com/product-guide",
title: "Product Configuration Guide",
content: [
{
type: "text" as const,
text: "To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs."
}
],
citations: { enabled: true }
},
{
type: "search_result" as const,
source: "https://docs.company.com/troubleshooting",
title: "Troubleshooting Guide",
content: [
{
type: "text" as const,
text: "If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values."
}
],
citations: { enabled: true }
}
];
}
// Create a message with the tool
const response = await anthropic.messages.create({
model: "claude-opus-4-7", // Works with all supported models
max_tokens: 1024,
tools: [knowledgeBaseTool],
messages: [
{
role: "user",
content: "How do I configure the timeout settings?"
}
]
});
// Handle tool use and provide results
if (response.content[0].type === "tool_use") {
const input = response.content[0].input as { query: string };
const toolResult = searchKnowledgeBase(input.query);
const finalResponse = await anthropic.messages.create({
model: "claude-opus-4-7", // Works with all supported models
max_tokens: 1024,
messages: [
{ role: "user", content: "How do I configure the timeout settings?" },
{ role: "assistant", content: response.content },
{
role: "user",
content: [
{
type: "tool_result" as const,
tool_use_id: response.content[0].id,
content: toolResult // Search results go here
}
]
}
]
});
}
```
```csharp C# nocheck
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages;
public class Program
{
public static async Task Main(string[] args)
{
AnthropicClient client = new();
var knowledgeBaseTool = new Tool
{
Name = "search_knowledge_base",
Description = "Search the company knowledge base for information",
InputSchema = new
{
type = "object",
properties = new
{
query = new
{
type = "string",
description = "The search query"
}
},
required = new[] { "query" }
}
};
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus4_7,
MaxTokens = 1024,
Tools = new[] { knowledgeBaseTool },
Messages = new[]
{
new MessageParam
{
Role = Role.User,
Content = "How do I configure the timeout settings?"
}
}
};
var response = await client.Messages.Create(parameters);
if (response.Content[0] is ToolUseBlock toolUse)
{
var toolResult = SearchKnowledgeBase(toolUse.Input["query"].ToString());
var finalParameters = new MessageCreateParams
{
Model = Model.ClaudeOpus4_7,
MaxTokens = 1024,
Messages = new[]
{
new MessageParam { Role = Role.User, Content = "How do I configure the timeout settings?" },
new MessageParam { Role = Role.Assistant, Content = response.Content },
new MessageParam
{
Role = Role.User,
Content = new[]
{
new ToolResultBlockParam
{
ToolUseID = toolUse.Id,
Content = toolResult
}
}
}
}
};
var finalResponse = await client.Messages.Create(finalParameters);
Console.WriteLine(finalResponse);
}
}
private static List<SearchResultBlockParam> SearchKnowledgeBase(string query)
{
return new List<SearchResultBlockParam>
{
new SearchResultBlockParam
{
Source = "https://docs.company.com/product-guide",
Title = "Product Configuration Guide",
Content = new[]
{
new TextBlockParam
{
Text = "To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs."
}
},
Citations = new CitationsConfigParam { Enabled = true }
},
new SearchResultBlockParam
{
Source = "https://docs.company.com/troubleshooting",
Title = "Troubleshooting Guide",
Content = new[]
{
new TextBlockParam
{
Text = "If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values."
}
},
Citations = new CitationsConfigParam { Enabled = true }
}
};
}
}
```
```go Go nocheck hidelines={1..12,77..78}
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
knowledgeBaseTool := anthropic.ToolUnionParam{
OfTool: &anthropic.ToolParam{
Name: "search_knowledge_base",
Description: anthropic.String("Search the company knowledge base for information"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"query": map[string]any{
"type": "string",
"description": "The search query",
},
},
Required: []string{"query"},
},
},
}
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_7,
MaxTokens: 1024,
Tools: []anthropic.ToolUnionParam{knowledgeBaseTool},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("How do I configure the timeout settings?")),
},
})
if err != nil {
log.Fatal(err)
}
for _, block := range response.Content {
switch variant := block.AsAny().(type) {
case anthropic.ToolUseBlock:
var input struct {
Query string `json:"query"`
}
if err := json.Unmarshal(variant.Input, &input); err != nil {
log.Fatal(err)
}
toolResults := searchKnowledgeBase(input.Query)
// Build assistant message from the response
assistantParam := response.ToParam()
finalResponse, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_7,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("How do I configure the timeout settings?")),
assistantParam,
anthropic.NewUserMessage(anthropic.ContentBlockParamUnion{
OfToolResult: &anthropic.ToolResultBlockParam{
ToolUseID: variant.ID,
Content: toolResults,
},
}),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(finalResponse)
}
}
}
func searchKnowledgeBase(query string) []anthropic.ToolResultBlockParamContentUnion {
return []anthropic.ToolResultBlockParamContentUnion{
{OfSearchResult: &anthropic.SearchResultBlockParam{
Content: []anthropic.TextBlockParam{
{Text: "To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs."},
},
Source: "https://docs.company.com/product-guide",
Title: "Product Configuration Guide",
Citations: anthropic.CitationsConfigParam{Enabled: anthropic.Bool(true)},
}},
{OfSearchResult: &anthropic.SearchResultBlockParam{
Content: []anthropic.TextBlockParam{
{Text: "If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values."},
},
Source: "https://docs.company.com/troubleshooting",
Title: "Troubleshooting Guide",
Citations: anthropic.CitationsConfigParam{Enabled: anthropic.Bool(true)},
}},
}
}
```
```java Java nocheck hidelines={1..3,5..7,9..19,75..76,-1}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.ContentBlockParam;
import com.anthropic.models.messages.CitationsConfigParam;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.SearchResultBlockParam;
import com.anthropic.models.messages.TextBlockParam;
import com.anthropic.models.messages.Tool;
import com.anthropic.models.messages.ToolResultBlockParam;
import com.anthropic.models.messages.ToolUseBlock;
import com.anthropic.models.messages.ToolUseBlockParam;
import com.anthropic.core.JsonValue;
import java.util.List;
import java.util.Map;
public class SearchKnowledgeBaseExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Tool knowledgeBaseTool = Tool.builder()
.name("search_knowledge_base")
.description("Search the company knowledge base for information")
.inputSchema(Tool.InputSchema.builder()
.properties(JsonValue.from(Map.of(
"query", Map.of(
"type", "string",
"description", "The search query"
)
)))
.putAdditionalProperty("required", JsonValue.from(List.of("query")))
.build())
.build();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(1024L)
.addTool(knowledgeBaseTool)
.addUserMessage("How do I configure the timeout settings?")
.build();
Message response = client.messages().create(params);
response.content().get(0).toolUse().ifPresent(toolUse -> {
List<ContentBlockParam> toolResult = searchKnowledgeBase(
(String) ((Map<?, ?>) toolUse._input()).get("query")
);
MessageCreateParams finalParams = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(1024L)
.addTool(knowledgeBaseTool)
.addUserMessage("How do I configure the timeout settings?")
.addAssistantMessageOfBlockParams(List.of(
ContentBlockParam.ofToolUse(ToolUseBlockParam.builder()
.id(toolUse.id())
.name(toolUse.name())
.input(toolUse._input())
.build())
))
.addUserMessageOfBlockParams(List.of(
ContentBlockParam.ofToolResult(
ToolResultBlockParam.builder()
.toolUseId(toolUse.id())
.contentOfBlockParams(toolResult)
.build()
)
))
.build();
Message finalResponse = client.messages().create(finalParams);
System.out.println(finalResponse);
});
}
private static List<ContentBlockParam> searchKnowledgeBase(String query) {
return List.of(
ContentBlockParam.ofSearchResult(
SearchResultBlockParam.builder()
.source("https://docs.company.com/product-guide")
.title("Product Configuration Guide")
.content(List.of(
TextBlockParam.builder()
.text("To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs.")
.build()
))
.citations(CitationsConfigParam.builder().enabled(true).build())
.build()
),
ContentBlockParam.ofSearchResult(
SearchResultBlockParam.builder()
.source("https://docs.company.com/troubleshooting")
.title("Troubleshooting Guide")
.content(List.of(
TextBlockParam.builder()
.text("If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values.")
.build()
))
.citations(CitationsConfigParam.builder().enabled(true).build())
.build()
)
);
}
}
```
```php PHP nocheck hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$knowledgeBaseTool = [
'name' => 'search_knowledge_base',
'description' => 'Search the company knowledge base for information',
'input_schema' => [
'type' => 'object',
'properties' => [
'query' => [
'type' => 'string',
'description' => 'The search query'
]
],
'required' => ['query']
]
];
function searchKnowledgeBase($query) {
return [
[
'type' => 'search_result',
'source' => 'https://docs.company.com/product-guide',
'title' => 'Product Configuration Guide',
'content' => [
[
'type' => 'text',
'text' => 'To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs.'
]
],
'citations' => ['enabled' => true]
],
[
'type' => 'search_result',
'source' => 'https://docs.company.com/troubleshooting',
'title' => 'Troubleshooting Guide',
'content' => [
[
'type' => 'text',
'text' => 'If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values.'
]
],
'citations' => ['enabled' => true]
]
];
}
$response = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => 'How do I configure the timeout settings?']
],
model: 'claude-opus-4-7',
tools: [$knowledgeBaseTool],
);
$toolUseBlock = null;
foreach ($response->content as $block) {
if ($block->type === 'tool_use') {
$toolUseBlock = $block;
break;
}
}
if ($toolUseBlock !== null) {
$toolResult = searchKnowledgeBase($toolUseBlock->input['query']);
$finalResponse = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => 'How do I configure the timeout settings?'],
['role' => 'assistant', 'content' => $response->content],
[
'role' => 'user',
'content' => [
[
'type' => 'tool_result',
'tool_use_id' => $toolUseBlock->id,
'content' => $toolResult
]
]
]
],
model: 'claude-opus-4-7',
);
echo $finalResponse;
} else {
echo $response;
}
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
knowledge_base_tool = {
name: "search_knowledge_base",
description: "Search the company knowledge base for information",
input_schema: {
type: "object",
properties: {
query: { type: "string", description: "The search query" }
},
required: ["query"]
}
}
def search_knowledge_base(query)
[
{
type: "search_result",
source: "https://docs.company.com/product-guide",
title: "Product Configuration Guide",
content: [
{
type: "text",
text: "To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs."
}
],
citations: { enabled: true }
},
{
type: "search_result",
source: "https://docs.company.com/troubleshooting",
title: "Troubleshooting Guide",
content: [
{
type: "text",
text: "If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values."
}
],
citations: { enabled: true }
}
]
end
response = client.messages.create(
model: "claude-opus-4-7",
max_tokens: 1024,
tools: [knowledge_base_tool],
messages: [
{ role: "user", content: "How do I configure the timeout settings?" }
]
)
if response.content.first.type == :tool_use
tool_result = search_knowledge_base(response.content.first.input["query"])
final_response = client.messages.create(
model: "claude-opus-4-7",
max_tokens: 1024,
messages: [
{ role: "user", content: "How do I configure the timeout settings?" },
{ role: "assistant", content: response.content },
{
role: "user",
content: [
{
type: "tool_result",
tool_use_id: response.content.first.id,
content: tool_result
}
]
}
]
)
puts final_response
end
```
</CodeGroup>
## Method 2: Search results as top-level content
You can also provide search results directly in user messages. This is useful for:
- Pre-fetched content from your search infrastructure
- Cached search results from previous queries
- Content from external search services
- Testing and development
### Example: Direct search results
<CodeGroup>
```bash cURL
#!/bin/sh
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": [
{
"type": "search_result",
"source": "https://docs.company.com/api-reference",
"title": "API Reference - Authentication",
"content": [
{
"type": "text",
"text": "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium."
}
],
"citations": {
"enabled": true
}
},
{
"type": "search_result",
"source": "https://docs.company.com/quickstart",
"title": "Getting Started Guide",
"content": [
{
"type": "text",
"text": "To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key."
}
],
"citations": {
"enabled": true
}
},
{
"type": "text",
"text": "Based on these search results, how do I authenticate API requests and what are the rate limits?"
}
]
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-4-7
max_tokens: 1024
messages:
- role: user
content:
- type: search_result
source: https://docs.company.com/api-reference
title: API Reference - Authentication
content:
- type: text
text: >-
All API requests must include an API key in the Authorization
header. Keys can be generated from the dashboard. Rate limits:
1000 requests per hour for standard tier, 10000 for premium.
citations:
enabled: true
- type: search_result
source: https://docs.company.com/quickstart
title: Getting Started Guide
content:
- type: text
text: >-
To get started: 1) Sign up for an account, 2) Generate an API
key from the dashboard, 3) Install our SDK using pip install
company-sdk, 4) Initialize the client with your API key.
citations:
enabled: true
- type: text
text: >-
Based on these search results, how do I authenticate API requests
and what are the rate limits?
YAML
```
```python Python hidelines={1}
from anthropic import Anthropic
from anthropic.types import MessageParam, TextBlockParam, SearchResultBlockParam
client = Anthropic()
# Provide search results directly in the user message
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
messages=[
MessageParam(
role="user",
content=[
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/api-reference",
title="API Reference - Authentication",
content=[
TextBlockParam(
type="text",
text="All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium.",
)
],
citations={"enabled": True},
),
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/quickstart",
title="Getting Started Guide",
content=[
TextBlockParam(
type="text",
text="To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key.",
)
],
citations={"enabled": True},
),
TextBlockParam(
type="text",
text="Based on these search results, how do I authenticate API requests and what are the rate limits?",
),
],
)
],
)
print(response.model_dump_json(indent=2))
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
// Provide search results directly in the user message
const response = await anthropic.messages.create({
model: "claude-opus-4-7",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
{
type: "search_result" as const,
source: "https://docs.company.com/api-reference",
title: "API Reference - Authentication",
content: [
{
type: "text" as const,
text: "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium."
}
],
citations: { enabled: true }
},
{
type: "search_result" as const,
source: "https://docs.company.com/quickstart",
title: "Getting Started Guide",
content: [
{
type: "text" as const,
text: "To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key."
}
],
citations: { enabled: true }
},
{
type: "text" as const,
text: "Based on these search results, how do I authenticate API requests and what are the rate limits?"
}
]
}
]
});
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 = 1024,
Messages =
[
new()
{
Role = Role.User,
Content =
[
new SearchResultBlockParam
{
Source = "https://docs.company.com/api-reference",
Title = "API Reference - Authentication",
Content =
[
new TextBlockParam
{
Text = "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium."
}
],
Citations = new CitationsConfigParam { Enabled = true }
},
new SearchResultBlockParam
{
Source = "https://docs.company.com/quickstart",
Title = "Getting Started Guide",
Content =
[
new TextBlockParam
{
Text = "To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key."
}
],
Citations = new CitationsConfigParam { Enabled = true }
},
new TextBlockParam
{
Text = "Based on these search results, how do I authenticate API requests and what are the rate limits?"
}
]
}
]
};
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.ContentBlockParamUnion{OfSearchResult: &anthropic.SearchResultBlockParam{
Content: []anthropic.TextBlockParam{
{Text: "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium."},
},
Source: "https://docs.company.com/api-reference",
Title: "API Reference - Authentication",
Citations: anthropic.CitationsConfigParam{Enabled: anthropic.Bool(true)},
}},
anthropic.ContentBlockParamUnion{OfSearchResult: &anthropic.SearchResultBlockParam{
Content: []anthropic.TextBlockParam{
{Text: "To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key."},
},
Source: "https://docs.company.com/quickstart",
Title: "Getting Started Guide",
Citations: anthropic.CitationsConfigParam{Enabled: anthropic.Bool(true)},
}},
anthropic.NewTextBlock("Based on these search results, how do I authenticate API requests and what are the rate limits?"),
),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
}
```
```java Java hidelines={1..3,5..7,9..13,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.ContentBlockParam;
import com.anthropic.models.messages.CitationsConfigParam;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.SearchResultBlockParam;
import com.anthropic.models.messages.TextBlockParam;
import java.util.List;
public class SearchResultExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(1024L)
.addUserMessageOfBlockParams(List.of(
ContentBlockParam.ofSearchResult(
SearchResultBlockParam.builder()
.source("https://docs.company.com/api-reference")
.title("API Reference - Authentication")
.content(List.of(
TextBlockParam.builder()
.text("All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium.")
.build()
))
.citations(CitationsConfigParam.builder().enabled(true).build())
.build()
),
ContentBlockParam.ofSearchResult(
SearchResultBlockParam.builder()
.source("https://docs.company.com/quickstart")
.title("Getting Started Guide")
.content(List.of(
TextBlockParam.builder()
.text("To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key.")
.build()
))
.citations(CitationsConfigParam.builder().enabled(true).build())
.build()
),
ContentBlockParam.ofText(
TextBlockParam.builder()
.text("Based on these search results, how do I authenticate API requests and what are the rate limits?")
.build()
)
))
.build();
Message response = client.messages().create(params);
System.out.println(response);
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => [
[
'type' => 'search_result',
'source' => 'https://docs.company.com/api-reference',
'title' => 'API Reference - Authentication',
'content' => [
[
'type' => 'text',
'text' => 'All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium.'
]
],
'citations' => ['enabled' => true]
],
[
'type' => 'search_result',
'source' => 'https://docs.company.com/quickstart',
'title' => 'Getting Started Guide',
'content' => [
[
'type' => 'text',
'text' => 'To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key.'
]
],
'citations' => ['enabled' => true]
],
[
'type' => 'text',
'text' => 'Based on these search results, how do I authenticate API requests and what are the rate limits?'
]
]
]
],
model: 'claude-opus-4-7',
);
echo json_encode($message, JSON_PRETTY_PRINT);
```
```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: [
{
type: "search_result",
source: "https://docs.company.com/api-reference",
title: "API Reference - Authentication",
content: [
{
type: "text",
text: "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium."
}
],
citations: { enabled: true }
},
{
type: "search_result",
source: "https://docs.company.com/quickstart",
title: "Getting Started Guide",
content: [
{
type: "text",
text: "To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key."
}
],
citations: { enabled: true }
},
{
type: "text",
text: "Based on these search results, how do I authenticate API requests and what are the rate limits?"
}
]
}
]
)
puts message
```
</CodeGroup>
## Claude's response with citations
Regardless of how search results are provided, Claude automatically includes citations when using information from them:
```json
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "To authenticate API requests, you need to include an API key in the Authorization header",
"citations": [
{
"type": "search_result_location",
"source": "https://docs.company.com/api-reference",
"title": "API Reference - Authentication",
"cited_text": "All API requests must include an API key in the Authorization header",
"search_result_index": 0,
"start_block_index": 0,
"end_block_index": 0
}
]
},
{
"type": "text",
"text": ". You can generate API keys from your dashboard",
"citations": [
{
"type": "search_result_location",
"source": "https://docs.company.com/api-reference",
"title": "API Reference - Authentication",
"cited_text": "Keys can be generated from the dashboard",
"search_result_index": 0,
"start_block_index": 0,
"end_block_index": 0
}
]
},
{
"type": "text",
"text": ". The rate limits are 1,000 requests per hour for the standard tier and 10,000 requests per hour for the premium tier.",
"citations": [
{
"type": "search_result_location",
"source": "https://docs.company.com/api-reference",
"title": "API Reference - Authentication",
"cited_text": "Rate limits: 1000 requests per hour for standard tier, 10000 for premium",
"search_result_index": 0,
"start_block_index": 0,
"end_block_index": 0
}
]
}
]
}
```
### Citation fields
Each citation includes:
| Field | Type | Description |
|-------|------|-------------|
| `type` | string | Always `"search_result_location"` for search result citations |
| `source` | string | The source from the original search result |
| `title` | string or null | The title from the original search result |
| `cited_text` | string | The exact text being cited |
| `search_result_index` | integer | Index of the search result (0-based) |
| `start_block_index` | integer | Starting position in the content array |
| `end_block_index` | integer | Ending position in the content array |
Note: The `search_result_index` refers to the index of the search result content block (0-based), regardless of how the search results were provided (tool call or top-level content).
## Multiple content blocks
Search results can contain multiple text blocks in the `content` array:
```json
{
"type": "search_result",
"source": "https://docs.company.com/api-guide",
"title": "API Documentation",
"content": [
{
"type": "text",
"text": "Authentication: All API requests require an API key."
},
{
"type": "text",
"text": "Rate Limits: The API allows 1000 requests per hour per key."
},
{
"type": "text",
"text": "Error Handling: The API returns standard HTTP status codes."
}
]
}
```
Claude can cite specific blocks using the `start_block_index` and `end_block_index` fields.
## Advanced usage
### Combining both methods
You can use both tool-based and top-level search results in the same conversation:
```python nocheck
from anthropic.types import MessageParam, SearchResultBlockParam, TextBlockParam
# First message with top-level search results
messages = [
MessageParam(
role="user",
content=[
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/overview",
title="Product Overview",
content=[
TextBlockParam(
type="text", text="Our product helps teams collaborate..."
)
],
citations={"enabled": True},
),
TextBlockParam(
type="text",
text="Tell me about this product and search for pricing information",
),
],
)
]
# Claude might respond and call a tool to search for pricing
# Then you provide tool results with more search results
```
### Combining with other content types
Both methods support mixing search results with other content:
```python nocheck
from anthropic.types import SearchResultBlockParam, TextBlockParam
# In tool results
tool_result = [
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/guide",
title="User Guide",
content=[TextBlockParam(type="text", text="Configuration details...")],
citations={"enabled": True},
),
TextBlockParam(
type="text", text="Additional context: This applies to version 2.0 and later."
),
]
# In top-level content
user_content = [
SearchResultBlockParam(
type="search_result",
source="https://research.com/paper",
title="Research Paper",
content=[TextBlockParam(type="text", text="Key findings...")],
citations={"enabled": True},
),
{
"type": "image",
"source": {"type": "url", "url": "https://example.com/chart.png"},
},
TextBlockParam(
type="text", text="How does the chart relate to the research findings?"
),
]
```
### Cache control
Add cache control for better performance:
```json
{
"type": "search_result",
"source": "https://docs.company.com/guide",
"title": "User Guide",
"content": [{ "type": "text", "text": "..." }],
"cache_control": {
"type": "ephemeral"
}
}
```
### Citation control
By default, citations are disabled for search results. You can enable citations by explicitly setting the `citations` configuration:
```json
{
"type": "search_result",
"source": "https://docs.company.com/guide",
"title": "User Guide",
"content": [{ "type": "text", "text": "Important documentation..." }],
"citations": {
"enabled": true // Enable citations for this result
}
}
```
When `citations.enabled` is set to `true`, Claude includes citation references when using information from the search result. This enables:
- Natural citations for your custom RAG applications
- Source attribution when interfacing with proprietary knowledge bases
- Web search-quality citations for any custom tool that returns search results
If the `citations` field is omitted, citations are disabled by default.
<Warning>
Citations are all-or-nothing: either all search results in a request must have citations enabled, or all must have them disabled. Mixing search results with different citation settings results in an error. If you need to disable citations for some sources, you must disable them for all search results in that request.
</Warning>
## Best practices
### For tool-based search (Method 1)
- **Dynamic content:** Use for real-time searches and dynamic RAG applications
- **Error handling:** Return appropriate messages when searches fail
- **Result limits:** Return only the most relevant results to avoid context overflow
### For top-level search (Method 2)
- **Pre-fetched content:** Use when you already have search results
- **Batch processing:** Ideal for processing multiple search results at once
- **Testing:** Great for testing citation behavior with known content
### General best practices
1. **Structure results effectively**
- Use clear, permanent source URLs
- Provide descriptive titles
- Break long content into logical text blocks
2. **Maintain consistency**
- Use consistent source formats across your application
- Ensure titles accurately reflect content
- Keep formatting consistent
3. **Handle errors gracefully**
```python nocheck
def search_with_fallback(query):
try:
results = perform_search(query)
if not results:
return {"type": "text", "text": "No results found."}
return format_as_search_results(results)
except Exception as e:
return {"type": "text", "text": f"Search error: {str(e)}"}
```
## Limitations
- Search result content blocks are available on Claude API, Amazon Bedrock, and Google Cloud's Vertex AI
- Only text content is supported within search results (no images or other media)
- The `content` array must contain at least one text block
---
## Guides/build-with-claude-skills-guide-8feadbbf7d.md
# Using Agent Skills with the API
Learn how to use Agent Skills to extend Claude's capabilities through the API.
---
Agent Skills extend Claude's capabilities through organized folders of instructions, scripts, and resources. This guide shows you how to use both pre-built and custom Skills with the Claude API.
<Note>
For complete API reference including request/response schemas and all parameters, see:
- [Skill Management API Reference](/docs/en/api/skills/list-skills) - CRUD operations for Skills
- [Skill Versions API Reference](/docs/en/api/skills/list-skill-versions) - Version management
</Note>
<Note>
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.
</Note>
## Quick Links
<CardGroup cols={2}>
<Card
title="Get started with Agent Skills"
icon="rocket"
href="/docs/en/agents-and-tools/agent-skills/quickstart"
>
Create your first Skill
</Card>
<Card
title="Create Custom Skills"
icon="hammer"
href="/docs/en/agents-and-tools/agent-skills/best-practices"
>
Best practices for authoring Skills
</Card>
</CardGroup>
## Overview
<Note>
For a deep dive into the architecture and real-world applications of Agent Skills, read the engineering blog post: [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).
</Note>
Skills integrate with the Messages API through the code execution tool. Whether using pre-built Skills managed by Anthropic or custom Skills you've uploaded, the integration shape is identical: both require code execution and use the same `container` structure.
### Using Skills
Skills integrate identically in the Messages API regardless of source. You specify Skills in the `container` parameter with a `skill_id`, `type`, and optional `version`, and they execute in the code execution environment.
**You can use Skills from two sources:**
| Aspect | Anthropic Skills | Custom Skills |
|--------|------------------|---------------|
| **Type value** | `anthropic` | `custom` |
| **Skill IDs** | Short names: `pptx`, `xlsx`, `docx`, `pdf` | Generated: `skill_01AbCdEfGhIjKlMnOpQrStUv` |
| **Version format** | Date-based: `20251013` or `latest` | Epoch timestamp: `1759178010641129` or `latest` |
| **Management** | Pre-built and maintained by Anthropic | Upload and manage via [Skills API](/docs/en/api/skills/create-skill) |
| **Availability** | Available to all users | Private to your workspace |
Both skill sources are returned by the [List Skills endpoint](/docs/en/api/skills/list-skills) (use the `source` parameter to filter). The integration shape and execution environment are identical. The only difference is where the Skills come from and how they're managed.
### Prerequisites
To use Skills, you need:
1. **Claude API key** from the [Console](/settings/keys)
2. **Beta headers:**
- `code-execution-2025-08-25` - Enables code execution (required for Skills)
- `skills-2025-10-02` - Enables Skills API
- `files-api-2025-04-14` - For uploading/downloading files to/from container
3. **Code execution tool** enabled in your requests
---
## Using Skills in Messages
### Container Parameter
Skills are specified using the `container` parameter in the Messages API. You can include up to 8 Skills per request.
The structure is identical for both Anthropic and custom Skills. Specify the required `type` and `skill_id`, and optionally include `version` to pin to a specific version:
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "anthropic",
"skill_id": "pptx",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Create a presentation about renewable energy"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
```bash CLI
ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: pptx
version: latest
messages:
- role: user
content: Create a presentation about renewable energy
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python nocheck hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
},
messages=[
{"role": "user", "content": "Create a presentation about renewable energy"}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```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: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{
type: "anthropic",
skill_id: "pptx",
version: "latest"
}
]
},
messages: [
{
role: "user",
content: "Create a presentation about renewable energy"
}
],
tools: [
{
type: "code_execution_20250825",
name: "code_execution"
}
]
});
```
```csharp C# nocheck
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Beta.Messages;
public class Program
{
public static async Task Main(string[] args)
{
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = "claude-opus-4-7",
MaxTokens = 4096,
Betas = new[] { "code-execution-2025-08-25", "skills-2025-10-02" },
Container = new BetaContainerParams
{
Skills = new[]
{
new BetaAnthropicSkillParams
{
Type = "anthropic",
SkillId = "pptx",
Version = "latest"
}
}
},
Messages = new[]
{
new BetaMessageParam
{
Role = Role.User,
Content = "Create a presentation about renewable energy"
}
},
Tools = new[]
{
new BetaCodeExecutionToolParams
{
Type = "code_execution_20250825",
Name = "code_execution"
}
}
};
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: "claude-opus-4-7",
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{
"code-execution-2025-08-25",
anthropic.AnthropicBetaSkills2025_10_02,
},
Container: anthropic.BetaMessageNewParamsContainerUnion{
OfContainers: &anthropic.BetaContainerParams{
Skills: []anthropic.BetaSkillParams{
{
Type: anthropic.BetaSkillParamsTypeAnthropic,
SkillID: "pptx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Create a presentation about renewable energy")),
},
Tools: []anthropic.BetaToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
},
})
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.BetaContainerParams;
import com.anthropic.models.beta.messages.BetaSkillParams;
import com.anthropic.models.beta.messages.BetaCodeExecutionTool20250825;
public class Main {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model("claude-opus-4-7")
.maxTokens(4096L)
.addBeta("code-execution-2025-08-25")
.addBeta("skills-2025-10-02")
.container(BetaContainerParams.builder()
.addSkill(BetaSkillParams.builder()
.type(BetaSkillParams.Type.ANTHROPIC)
.skillId("pptx")
.version("latest")
.build())
.build())
.addUserMessage("Create a presentation about renewable energy")
.addTool(BetaCodeExecutionTool20250825.builder().build())
.build();
BetaMessage response = client.beta().messages().create(params);
System.out.println(response);
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->beta->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Create a presentation about renewable energy']
],
model: 'claude-opus-4-7',
betas: ['code-execution-2025-08-25', 'skills-2025-10-02'],
container: [
'skills' => [
[
'type' => 'anthropic',
'skill_id' => 'pptx',
'version' => 'latest'
]
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $message;
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
message = client.beta.messages.create(
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{
type: "anthropic",
skill_id: "pptx",
version: "latest"
}
]
},
messages: [
{ role: "user", content: "Create a presentation about renewable energy" }
],
tools: [
{ type: "code_execution_20250825", name: "code_execution" }
]
)
puts message
```
</CodeGroup>
### Downloading Generated Files
When Skills create documents (Excel, PowerPoint, PDF, Word), they return `file_id` attributes in the response. You must use the Files API to download these files.
**How it works:**
1. Skills create files during code execution
2. Response includes `file_id` for each created file
3. Use Files API to download the actual file content
4. Save locally or process as needed
**Example: Creating and downloading an Excel file**
<Tabs>
<Tab title="cURL">
```bash cURL hidelines={1}
cd "$(mktemp -d)"
# Step 1: Use a Skill to create a file
RESPONSE=$(curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 4096,
"container": {
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
]
},
"messages": [{
"role": "user",
"content": "Create an Excel file with a simple budget spreadsheet"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}')
# Step 2: Extract file_id from response (using jq)
FILE_ID=$(echo "$RESPONSE" | jq -r '.content[] | select(.type=="bash_code_execution_tool_result") | .content | select(.type=="bash_code_execution_result") | .content[] | select(.file_id) | .file_id')
# Step 3: Get filename from metadata
FILENAME=$(curl "https://api.anthropic.com/v1/files/$FILE_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: files-api-2025-04-14" | jq -r '.filename')
# Step 4: Download the file using Files API
curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: files-api-2025-04-14" \
--output "$FILENAME"
echo "Downloaded: $FILENAME"
```
</Tab>
<Tab title="CLI">
```bash CLI nocheck hidelines={1}
cd "$(mktemp -d)"
# Step 1: Use the xlsx Skill to create a file
# Step 2: Extract file_id from the response via --transform (GJSON path)
FILE_ID=$(ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 \
--transform 'content.#.content.content.#.file_id|@flatten|0' \
--format yaml <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: xlsx
version: latest
messages:
- role: user
content: Create an Excel file with a simple budget spreadsheet
tools:
- type: code_execution_20250825
name: code_execution
YAML
)
# Step 3: Get the filename from file metadata
FILENAME=$(ant beta:files retrieve-metadata \
--file-id "$FILE_ID" \
--transform filename --format yaml)
# Step 4: Download the file using Files API
ant beta:files download \
--file-id "$FILE_ID" \
--output "$FILENAME" > /dev/null
printf 'Downloaded: %s\n' "$FILENAME"
```
</Tab>
<Tab title="Python">
```python Python nocheck hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
# Step 1: Use a Skill to create a file
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Create an Excel file with a simple budget spreadsheet",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# Step 2: 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":
for file in content_item.content:
if hasattr(file, "file_id"):
file_ids.append(file.file_id)
return file_ids
# Step 3: Download the file using Files API
for file_id in extract_file_ids(response):
file_metadata = client.beta.files.retrieve_metadata(file_id=file_id)
file_content = client.beta.files.download(file_id=file_id)
# Step 4: Save to disk
file_content.write_to_file(file_metadata.filename)
print(f"Downloaded: {file_metadata.filename}")
```
</Tab>
<Tab title="TypeScript">
```typescript TypeScript hidelines={1..3}
import Anthropic from "@anthropic-ai/sdk";
import fs from "node:fs/promises";
const client = new Anthropic();
// Step 1: Use a Skill to create a file
const response = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages: [
{
role: "user",
content: "Create an Excel file with a simple budget spreadsheet"
}
],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
// Step 2: Extract file IDs from the response
function extractFileIds(response: any): string[] {
const fileIds: string[] = [];
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") {
for (const file of contentItem.content) {
if ("file_id" in file) {
fileIds.push(file.file_id);
}
}
}
}
}
return fileIds;
}
// Step 3: Download the file using Files API
for (const fileId of extractFileIds(response)) {
const fileMetadata = await client.beta.files.retrieveMetadata(fileId);
const fileContent = await client.beta.files.download(fileId);
// Step 4: Save to disk
await fs.writeFile(fileMetadata.filename, Buffer.from(await fileContent.arrayBuffer()));
console.log(`Downloaded: ${fileMetadata.filename}`);
}
```
</Tab>
<Tab title="C#">
```csharp C# nocheck
using System;
using System.IO;
using System.Linq;
using System.Threading.Tasks;
using System.Collections.Generic;
using Anthropic;
using Anthropic.Models.Beta.Messages;
using Anthropic.Models.Beta.Files;
class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new();
// Step 1: Use a Skill to create a file
var parameters = new MessageCreateParams
{
Model = "claude-opus-4-7",
MaxTokens = 4096,
Betas = new[] { "code-execution-2025-08-25", "skills-2025-10-02" },
Container = new BetaContainer
{
Skills = new[]
{
new BetaSkill
{
Type = "anthropic",
SkillId = "xlsx",
Version = "latest"
}
}
},
Messages = new[]
{
new BetaMessage
{
Role = Role.User,
Content = "Create an Excel file with a simple budget spreadsheet"
}
},
Tools = new[]
{
new BetaTool
{
Type = "code_execution_20250825",
Name = "code_execution"
}
}
};
var response = await client.Beta.Messages.Create(parameters);
// Step 2: Extract file IDs from the response
var fileIds = ExtractFileIds(response);
// Step 3: Download the file using Files API
foreach (var fileId in fileIds)
{
var fileMetadata = await client.Beta.Files.RetrieveMetadata(fileId);
var fileContent = await client.Beta.Files.Download(fileId);
// Step 4: Save to disk
await File.WriteAllBytesAsync(fileMetadata.Filename, fileContent);
Console.WriteLine($"Downloaded: {fileMetadata.Filename}");
}
}
static List<string> ExtractFileIds(BetaMessage response)
{
var fileIds = new List<string>();
foreach (var item in response.Content)
{
if (item is BetaBashCodeExecutionToolResult toolResult)
{
if (toolResult.Content is BetaBashCodeExecutionResult result)
{
foreach (var content in result.Content)
{
if (content is BetaBashCodeExecutionResultFile file)
{
fileIds.Add(file.FileId);
}
}
}
}
}
return fileIds;
}
}
```
</Tab>
<Tab title="Go">
```go Go hidelines={1..15,68..69}
package main
import (
"context"
"fmt"
"io"
"log"
"os"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
// Step 1: Use a Skill to create a file
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: "claude-opus-4-7",
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{"code-execution-2025-08-25", anthropic.AnthropicBetaSkills2025_10_02},
Container: anthropic.BetaMessageNewParamsContainerUnion{
OfContainers: &anthropic.BetaContainerParams{
Skills: []anthropic.BetaSkillParams{
{
Type: anthropic.BetaSkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Create an Excel file with a simple budget spreadsheet")),
},
Tools: []anthropic.BetaToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
// Step 2: Extract file IDs from the response
fileIDs := extractFileIDs(response)
// Step 3: Download the file using Files API
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)
}
// Step 4: Save to disk
out, err := os.Create(fileMetadata.Filename)
if err != nil {
log.Fatal(err)
}
io.Copy(out, fileContent.Body)
out.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 v := item.AsAny().(type) {
case anthropic.BetaBashCodeExecutionToolResultBlock:
for _, output := range v.Content.Content {
if output.FileID != "" {
fileIDs = append(fileIDs, output.FileID)
}
}
}
}
return fileIDs
}
```
</Tab>
<Tab title="Java">
```java Java nocheck hidelines={1..4,8,10..17,-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.BetaContainerParams;
import com.anthropic.models.beta.messages.BetaSkillParams;
import com.anthropic.models.beta.messages.BetaCodeExecutionTool20250825;
import com.anthropic.models.beta.messages.BetaContentBlock;
import com.anthropic.models.beta.files.FileMetadata;
import com.anthropic.core.http.HttpResponse;
import java.io.FileOutputStream;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;
public class SkillsFileDownload {
public static void main(String[] args) throws Exception {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Step 1: Use a Skill to create a file
MessageCreateParams params = MessageCreateParams.builder()
.model("claude-opus-4-7")
.maxTokens(4096L)
.addBeta("code-execution-2025-08-25")
.addBeta("skills-2025-10-02")
.container(BetaContainerParams.builder()
.addSkill(BetaSkillParams.builder()
.type(BetaSkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build())
.build())
.addUserMessage("Create an Excel file with a simple budget spreadsheet")
.addTool(BetaCodeExecutionTool20250825.builder().build())
.build();
BetaMessage response = client.beta().messages().create(params);
// Step 2: Extract file IDs from the response
List<String> fileIds = new ArrayList<>();
for (BetaContentBlock block : response.content()) {
if (block.isCodeExecutionToolResult()) {
var toolResult = block.asCodeExecutionToolResult();
for (var content : toolResult.content()) {
content.file().ifPresent(file -> fileIds.add(file.fileId()));
}
}
}
// Step 3: Download the file using Files API
for (String fileId : fileIds) {
FileMetadata fileMetadata = client.beta().files().retrieveMetadata(fileId);
HttpResponse fileContent = client.beta().files().download(fileId);
// Step 4: Save to disk
try (InputStream is = fileContent.body();
FileOutputStream fos = new FileOutputStream(fileMetadata.filename())) {
is.transferTo(fos);
}
System.out.println("Downloaded: " + fileMetadata.filename());
}
}
}
```
</Tab>
<Tab title="PHP">
<Note>
The PHP SDK doesn't include a file download method. Use `retrieveMetadata()` for file info, then download the file content via the REST API.
</Note>
```php PHP nocheck hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
// Step 1: Use a Skill to create a file
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Create an Excel file with a simple budget spreadsheet']
],
model: 'claude-opus-4-7',
betas: ['code-execution-2025-08-25', 'skills-2025-10-02'],
container: [
'skills' => [
['type' => 'anthropic', 'skill_id' => 'xlsx', 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
// Step 2: Extract file IDs from the response
function extractFileIds($response) {
$fileIds = [];
foreach ($response->content as $item) {
if ($item->type === 'bash_code_execution_tool_result') {
$contentItem = $item->content;
if ($contentItem->type === 'bash_code_execution_result') {
foreach ($contentItem->content as $file) {
if (isset($file->fileID)) {
$fileIds[] = $file->fileID;
}
}
}
}
}
return $fileIds;
}
// Step 3: Get metadata and download via REST API
$apiKey = getenv("ANTHROPIC_API_KEY");
foreach (extractFileIds($response) as $fileId) {
$fileMetadata = $client->beta->files->retrieveMetadata(
fileID: $fileId,
);
// Download file content via REST API
$context = stream_context_create([
'http' => [
'header' => implode("\r\n", [
"x-api-key: $apiKey",
"anthropic-version: 2023-06-01",
"anthropic-beta: files-api-2025-04-14",
]),
],
]);
$fileContent = file_get_contents(
"https://api.anthropic.com/v1/files/$fileId/content",
false,
$context
);
// Step 4: Save to disk
file_put_contents($fileMetadata->filename, $fileContent);
echo "Downloaded: {$fileMetadata->filename}\n";
}
```
</Tab>
<Tab title="Ruby">
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
# Step 1: Use a Skill to create a file
response = client.beta.messages.create(
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages: [
{
role: "user",
content: "Create an Excel file with a simple budget spreadsheet"
}
],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
# Step 2: Extract file IDs from the response
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
content_item.content.each do |file|
file_ids << file.file_id if file.respond_to?(:file_id)
end
end
end
end
file_ids
end
# Step 3: Download the file using Files API
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)
# Step 4: Save to disk
File.binwrite(file_metadata.filename, file_content.read)
puts "Downloaded: #{file_metadata.filename}"
end
```
</Tab>
</Tabs>
**Additional Files API operations:**
<CodeGroup>
```bash cURL
# Get file metadata
curl "https://api.anthropic.com/v1/files/$FILE_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: files-api-2025-04-14"
# List all files
curl "https://api.anthropic.com/v1/files" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: files-api-2025-04-14"
# Delete a file
curl -X DELETE "https://api.anthropic.com/v1/files/$FILE_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: files-api-2025-04-14"
```
```bash CLI nocheck
# Get file metadata
ant beta:files retrieve-metadata --file-id "$FILE_ID" \
--transform '{filename,size_bytes}' --format yaml \
| { read -r _ name; read -r _ size
printf 'Filename: %s, Size: %s bytes\n' "$name" "$size"; }
# List all files
ant beta:files list \
--transform '{filename,created_at}' --format yaml \
| while read -r _ name && read -r _ date; do
printf '%s - %s\n' "$name" "${date//\"/}"
done
# Delete a file
ant beta:files delete --file-id "$FILE_ID" >/dev/null
```
```python Python nocheck hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
file_id = "file_abc123"
# Get file metadata
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")
# List all files
files = client.beta.files.list()
for file in files.data:
print(f"{file.filename} - {file.created_at}")
# Delete a file
client.beta.files.delete(file_id=file_id)
```
```typescript TypeScript nocheck hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const fileId = "file_011CNha8iCJcU1wXNR6q4V8w";
// Get file metadata
const fileInfo = await client.beta.files.retrieveMetadata(fileId);
console.log(`Filename: ${fileInfo.filename}, Size: ${fileInfo.size_bytes} bytes`);
// List all files
const files = await client.beta.files.list();
for (const file of files.data) {
console.log(`${file.filename} - ${file.created_at}`);
}
// Delete a file
await client.beta.files.delete(fileId);
```
```csharp C# nocheck
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Beta.Files;
class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new();
string fileId = "file_abc123";
// Get file metadata
var fileInfo = await client.Beta.Files.RetrieveMetadata(fileId);
Console.WriteLine($"Filename: {fileInfo.Filename}, Size: {fileInfo.SizeBytes} bytes");
// List all files
var files = await client.Beta.Files.List();
foreach (var file in files.Data)
{
Console.WriteLine($"{file.Filename} - {file.CreatedAt}");
}
// Delete a file
await client.Beta.Files.Delete(fileId);
}
}
```
```go Go nocheck hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
fileID := "file_abc123"
// Get file metadata
fileInfo, err := client.Beta.Files.GetMetadata(context.TODO(), fileID, anthropic.BetaFileGetMetadataParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Filename: %s, Size: %d bytes\n", fileInfo.Filename, fileInfo.SizeBytes)
// List all files
files := client.Beta.Files.ListAutoPaging(context.TODO(), anthropic.BetaFileListParams{})
for files.Next() {
file := files.Current()
fmt.Printf("%s - %s\n", file.Filename, file.CreatedAt)
}
// Delete a file
_, err = client.Beta.Files.Delete(context.TODO(), fileID, anthropic.BetaFileDeleteParams{})
if err != nil {
log.Fatal(err)
}
}
```
```java Java nocheck hidelines={1..2,5..7,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.files.FileMetadata;
import com.anthropic.models.beta.files.FileListPage;
public class FileManagement {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
String fileId = "file_abc123";
// Get file metadata
FileMetadata fileInfo = client.beta().files().retrieveMetadata(fileId);
System.out.println("Filename: " + fileInfo.filename() + ", Size: " + fileInfo.sizeBytes() + " bytes");
// List all files
FileListPage files = client.beta().files().list();
for (var file : files.data()) {
System.out.println(file.filename() + " - " + file.createdAt());
}
// Delete a file
client.beta().files().delete(fileId);
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$fileId = "file_abc123";
// Get file metadata
$fileInfo = $client->beta->files->retrieveMetadata(
fileID: $fileId,
);
echo "Filename: {$fileInfo->filename}, Size: {$fileInfo->sizeBytes} bytes\n";
// List all files
$files = $client->beta->files->list();
foreach ($files->data as $file) {
echo "{$file->filename} - {$file->createdAt}\n";
}
// Delete a file
$client->beta->files->delete(
fileID: $fileId,
);
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
file_id = "file_abc123"
# Get file metadata
file_info = client.beta.files.retrieve_metadata(file_id)
puts "Filename: #{file_info.filename}, Size: #{file_info.size_bytes} bytes"
# List all files
files = client.beta.files.list
files.data.each do |file|
puts "#{file.filename} - #{file.created_at}"
end
# Delete a file
client.beta.files.delete(file_id)
```
</CodeGroup>
<Note>
For complete details on the Files API, see the [Files API documentation](/docs/en/api/files-content).
</Note>
### Multi-Turn Conversations
Reuse the same container across multiple messages by specifying the container ID:
<CodeGroup>
```bash CLI
# First request creates container
CONTAINER_ID=$(ant beta:messages create \
--beta code-execution-2025-08-25 --beta skills-2025-10-02 \
--transform container.id --format yaml <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- {type: anthropic, skill_id: xlsx, version: latest}
messages:
- role: user
content: Analyze this sales data
tools:
- {type: code_execution_20250825, name: code_execution}
YAML
)
# Continue conversation with same container
ant beta:messages create \
--beta code-execution-2025-08-25 --beta skills-2025-10-02 <<YAML
model: claude-opus-4-7
max_tokens: 4096
container:
id: $CONTAINER_ID # Reuse container
skills:
- {type: anthropic, skill_id: xlsx, version: latest}
messages:
- role: user
content: Analyze this sales data
- role: assistant
content: [] # content blocks from the first response
- role: user
content: What was the total revenue?
tools:
- {type: code_execution_20250825, name: code_execution}
YAML
```
```python Python
# First request creates container
response1 = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
},
messages=[{"role": "user", "content": "Analyze this sales data"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# Continue conversation with same container
messages = [
{"role": "user", "content": "Analyze this sales data"},
{"role": "assistant", "content": response1.content},
{"role": "user", "content": "What was the total revenue?"},
]
response2 = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"id": response1.container.id, # Reuse container
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}],
},
messages=messages,
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript
// First request creates container
const response1 = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages: [{ role: "user", content: "Analyze this sales data" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
// Continue conversation with same container
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
{ role: "user", content: "Analyze this sales data" },
{
role: "assistant",
content: response1.content as Anthropic.Beta.Messages.BetaContentBlockParam[]
},
{ role: "user", content: "What was the total revenue?" }
];
const response2 = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
id: response1.container!.id, // Reuse container
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages,
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
```
```csharp C# nocheck
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Beta.Messages;
public class Program
{
public static async Task Main()
{
var client = new AnthropicClient();
var parameters1 = new MessageCreateParams
{
Model = "claude-opus-4-7",
MaxTokens = 4096,
Betas = new[] { "code-execution-2025-08-25", "skills-2025-10-02" },
Container = new BetaContainerParams
{
Skills = new[]
{
new BetaSkillParam
{
Type = "anthropic",
SkillId = "xlsx",
Version = "latest"
}
}
},
Messages = new[]
{
new BetaMessageParam
{
Role = Role.User,
Content = "Analyze this sales data"
}
},
Tools = new[]
{
new BetaToolParam
{
Type = "code_execution_20250825",
Name = "code_execution"
}
}
};
var response1 = await client.Beta.Messages.Create(parameters1);
var parameters2 = new MessageCreateParams
{
Model = "claude-opus-4-7",
MaxTokens = 4096,
Betas = new[] { "code-execution-2025-08-25", "skills-2025-10-02" },
Container = new BetaContainerParams
{
Id = response1.Container.Id,
Skills = new[]
{
new BetaSkillParam
{
Type = "anthropic",
SkillId = "xlsx",
Version = "latest"
}
}
},
Messages = new[]
{
new BetaMessageParam { Role = Role.User, Content = "Analyze this sales data" },
new BetaMessageParam { Role = Role.Assistant, Content = response1.Content },
new BetaMessageParam { Role = Role.User, Content = "What was the total revenue?" }
},
Tools = new[]
{
new BetaToolParam
{
Type = "code_execution_20250825",
Name = "code_execution"
}
}
};
var response2 = await client.Beta.Messages.Create(parameters2);
Console.WriteLine(response2);
}
}
```
```go Go nocheck 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: "claude-opus-4-7",
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{"code-execution-2025-08-25", anthropic.AnthropicBetaSkills2025_10_02},
Container: anthropic.BetaMessageNewParamsContainerUnion{
OfContainers: &anthropic.BetaContainerParams{
Skills: []anthropic.BetaSkillParams{
{
Type: anthropic.BetaSkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Analyze this sales data")),
},
Tools: []anthropic.BetaToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
response2, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: "claude-opus-4-7",
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{"code-execution-2025-08-25", anthropic.AnthropicBetaSkills2025_10_02},
Container: anthropic.BetaMessageNewParamsContainerUnion{
OfString: anthropic.String(response1.Container.ID),
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Analyze this sales data")),
response1.ToParam(),
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What was the total revenue?")),
},
Tools: []anthropic.BetaToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response2)
}
```
```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.BetaContainerParams;
import com.anthropic.models.beta.messages.BetaSkillParams;
import com.anthropic.models.beta.messages.BetaCodeExecutionTool20250825;
public class ContainerReuse {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params1 = MessageCreateParams.builder()
.model("claude-opus-4-7")
.maxTokens(4096L)
.addBeta("code-execution-2025-08-25")
.addBeta("skills-2025-10-02")
.container(BetaContainerParams.builder()
.addSkill(BetaSkillParams.builder()
.type(BetaSkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build())
.build())
.addUserMessage("Analyze this sales data")
.addTool(BetaCodeExecutionTool20250825.builder().build())
.build();
BetaMessage response1 = client.beta().messages().create(params1);
MessageCreateParams params2 = MessageCreateParams.builder()
.model("claude-opus-4-7")
.maxTokens(4096L)
.addBeta("code-execution-2025-08-25")
.addBeta("skills-2025-10-02")
.container(BetaContainerParams.builder()
.id(response1.container().get().id())
.addSkill(BetaSkillParams.builder()
.type(BetaSkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build())
.build())
.addUserMessage("Analyze this sales data")
.addMessage(response1)
.addUserMessage("What was the total revenue?")
.addTool(BetaCodeExecutionTool20250825.builder().build())
.build();
BetaMessage response2 = client.beta().messages().create(params2);
System.out.println(response2);
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$response1 = $client->beta->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Analyze this sales data']
],
model: 'claude-opus-4-7',
betas: ['code-execution-2025-08-25', 'skills-2025-10-02'],
container: [
'skills' => [
['type' => 'anthropic', 'skill_id' => 'xlsx', 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
$messages = [
['role' => 'user', 'content' => 'Analyze this sales data'],
['role' => 'assistant', 'content' => $response1->content],
['role' => 'user', 'content' => 'What was the total revenue?']
];
$response2 = $client->beta->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-4-7',
betas: ['code-execution-2025-08-25', 'skills-2025-10-02'],
container: [
'id' => $response1->container->id,
'skills' => [
['type' => 'anthropic', 'skill_id' => 'xlsx', 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $response2;
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
response1 = client.beta.messages.create(
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages: [
{ role: "user", content: "Analyze this sales data" }
],
tools: [
{ type: "code_execution_20250825", name: "code_execution" }
]
)
messages = [
{ role: "user", content: "Analyze this sales data" },
{ role: "assistant", content: response1.content },
{ role: "user", content: "What was the total revenue?" }
]
response2 = client.beta.messages.create(
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
id: response1.container.id,
skills: [
{ type: "anthropic", skill_id: "xlsx", version: "latest" }
]
},
messages: messages,
tools: [
{ type: "code_execution_20250825", name: "code_execution" }
]
)
puts response2
```
</CodeGroup>
### Long-Running Operations
Skills may perform operations that require multiple turns. Handle `pause_turn` stop reasons:
<CodeGroup>
```bash cURL nocheck
# Initial request
RESPONSE=$(curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Process this large dataset"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}')
# Check stop_reason and handle pause_turn in a loop
STOP_REASON=$(echo "$RESPONSE" | jq -r '.stop_reason')
CONTAINER_ID=$(echo "$RESPONSE" | jq -r '.container.id')
while [ "$STOP_REASON" = "pause_turn" ]; do
# Continue with same container
RESPONSE=$(curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d "{
\"model\": \"claude-opus-4-7\",
\"max_tokens\": 4096,
\"container\": {
\"id\": \"$CONTAINER_ID\",
\"skills\": [{
\"type\": \"custom\",
\"skill_id\": \"skill_01AbCdEfGhIjKlMnOpQrStUv\",
\"version\": \"latest\"
}]
},
\"messages\": [/* include conversation history */],
\"tools\": [{
\"type\": \"code_execution_20250825\",
\"name\": \"code_execution\"
}]
}")
STOP_REASON=$(echo "$RESPONSE" | jq -r '.stop_reason')
done
```
```bash CLI nocheck
RESP=$(mktemp)
# Initial request: capture the full JSON response to a temp file
ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 \
> "$RESP" <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: latest
messages:
- role: user
content: Process this large dataset
tools:
- type: code_execution_20250825
name: code_execution
YAML
# Handle pause_turn for long operations (up to 10 iterations)
for _ in {1..10}; do
[[ $(jq -r '.stop_reason' "$RESP") == pause_turn ]] || break
CONTAINER_ID=$(jq -r '.container.id' "$RESP")
# Continue in the same container, appending the prior response's
# content array to messages as the assistant turn.
ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 \
> "$RESP" <<YAML
model: claude-opus-4-7
max_tokens: 4096
container:
id: $CONTAINER_ID
skills:
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: latest
messages:
# ... conversation history with prior assistant content appended
tools:
- type: code_execution_20250825
name: code_execution
YAML
done
```
```python Python nocheck
messages = [{"role": "user", "content": "Process this large dataset"}]
max_retries = 10
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
}
]
},
messages=messages,
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# Handle pause_turn for long operations
for i in range(max_retries):
if response.stop_reason != "pause_turn":
break
messages.append({"role": "assistant", "content": response.content})
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"id": response.container.id,
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
}
],
},
messages=messages,
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript nocheck hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
{ role: "user", content: "Process this large dataset" }
];
const maxRetries = 10;
let response = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [{ type: "custom", skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv", version: "latest" }]
},
messages,
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
// Handle pause_turn for long operations
for (let i = 0; i < maxRetries; i++) {
if (response.stop_reason !== "pause_turn") {
break;
}
messages.push({
role: "assistant" as const,
content: response.content as Anthropic.Beta.Messages.BetaContentBlockParam[]
});
response = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
id: response.container!.id,
skills: [
{ type: "custom", skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv", version: "latest" }
]
},
messages,
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
}
```
```csharp C# nocheck
using Anthropic;
using Anthropic.Models.Beta.Messages;
AnthropicClient client = new();
var messages = new List<BetaMessageParam>
{
new() { Role = Role.User, Content = "Process this large dataset" }
};
int maxRetries = 10;
var response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = "claude-opus-4-7",
MaxTokens = 4096,
Betas = ["code-execution-2025-08-25", "skills-2025-10-02"],
Container = new BetaContainerParams
{
Skills = [
new BetaSkillParam
{
Type = "custom",
SkillId = "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version = "latest"
}
]
},
Messages = messages,
Tools = [new BetaToolParam { Type = "code_execution_20250825", Name = "code_execution" }]
});
for (int i = 0; i < maxRetries; i++)
{
if (response.StopReason != "pause_turn")
{
break;
}
messages.Add(new BetaMessageParam { Role = Role.Assistant, Content = response.Content });
response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = "claude-opus-4-7",
MaxTokens = 4096,
Betas = ["code-execution-2025-08-25", "skills-2025-10-02"],
Container = new BetaContainerParams
{
Id = response.Container.Id,
Skills = [
new BetaSkillParam
{
Type = "custom",
SkillId = "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version = "latest"
}
]
},
Messages = messages,
Tools = [new BetaToolParam { Type = "code_execution_20250825", Name = "code_execution" }]
});
}
```
```go Go nocheck 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("Process this large dataset")),
}
maxRetries := 10
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: "claude-opus-4-7",
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{"code-execution-2025-08-25", anthropic.AnthropicBetaSkills2025_10_02},
Container: anthropic.BetaMessageNewParamsContainerUnion{
OfContainers: &anthropic.BetaContainerParams{
Skills: []anthropic.BetaSkillParams{
{
Type: anthropic.BetaSkillParamsTypeCustom,
SkillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version: anthropic.String("latest"),
},
},
},
},
Messages: messages,
Tools: []anthropic.BetaToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
for i := 0; i < maxRetries; i++ {
if response.StopReason != "pause_turn" {
break
}
messages = append(messages, response.ToParam())
response, err = client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: "claude-opus-4-7",
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{"code-execution-2025-08-25", anthropic.AnthropicBetaSkills2025_10_02},
Container: anthropic.BetaMessageNewParamsContainerUnion{
OfString: anthropic.String(response.Container.ID),
},
Messages: messages,
Tools: []anthropic.BetaToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
}
fmt.Println(response)
}
```
```java Java nocheck hidelines={1..5,9..10,12..14,-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.BetaMessageParam;
import com.anthropic.models.beta.messages.BetaContainerParams;
import com.anthropic.models.beta.messages.BetaSkillParams;
import com.anthropic.models.beta.messages.BetaCodeExecutionTool20250825;
import java.util.ArrayList;
import java.util.List;
import com.anthropic.models.beta.messages.BetaStopReason;
public class Main {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
List<BetaMessageParam> messages = new ArrayList<>();
messages.add(
BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.content("Process this large dataset")
.build()
);
int maxRetries = 10;
BetaMessage response = client.beta().messages().create(
MessageCreateParams.builder()
.model("claude-opus-4-7")
.maxTokens(4096L)
.addBeta("code-execution-2025-08-25")
.addBeta("skills-2025-10-02")
.container(BetaContainerParams.builder()
.addSkill(BetaSkillParams.builder()
.type(BetaSkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version("latest")
.build())
.build())
.messages(messages)
.addTool(BetaCodeExecutionTool20250825.builder().build())
.build());
for (int i = 0; i < maxRetries; i++) {
if (!response.stopReason().isPresent()
|| !response.stopReason().get().equals(BetaStopReason.PAUSE_TURN)) {
break;
}
messages.add(response.toParam());
response = client.beta().messages().create(
MessageCreateParams.builder()
.model("claude-opus-4-7")
.maxTokens(4096L)
.addBeta("code-execution-2025-08-25")
.addBeta("skills-2025-10-02")
.container(BetaContainerParams.builder()
.id(response.container().get().id())
.addSkill(BetaSkillParams.builder()
.type(BetaSkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version("latest")
.build())
.build())
.messages(messages)
.addTool(BetaCodeExecutionTool20250825.builder().build())
.build());
}
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$messages = [
['role' => 'user', 'content' => 'Process this large dataset']
];
$maxRetries = 10;
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-4-7',
betas: ['code-execution-2025-08-25', 'skills-2025-10-02'],
container: [
'skills' => [
[
'type' => 'custom',
'skill_id' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]
]
],
tools: [['type' => 'code_execution_20250825', 'name' => 'code_execution']]
);
for ($i = 0; $i < $maxRetries; $i++) {
if ($response->stopReason !== 'pause_turn') {
break;
}
$messages[] = ['role' => 'assistant', 'content' => $response->content];
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-4-7',
betas: ['code-execution-2025-08-25', 'skills-2025-10-02'],
container: [
'id' => $response->container->id,
'skills' => [
[
'type' => 'custom',
'skill_id' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]
]
],
tools: [['type' => 'code_execution_20250825', 'name' => 'code_execution']]
);
}
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
messages = [
{ role: "user", content: "Process this large dataset" }
]
max_retries = 10
response = client.beta.messages.create(
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}
]
},
messages: messages,
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
max_retries.times do
break if response.stop_reason != :pause_turn
messages << { role: "assistant", content: response.content }
response = client.beta.messages.create(
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
id: response.container.id,
skills: [
{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}
]
},
messages: messages,
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
end
```
</CodeGroup>
<Note>
The response may include a `pause_turn` stop reason, which indicates that the API paused a long-running Skill operation. You can 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 and provide additional guidance.
</Note>
### Using Multiple Skills
Combine multiple Skills in a single request to handle complex workflows:
<CodeGroup>
```bash cURL nocheck
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "anthropic",
"skill_id": "xlsx",
"version": "latest"
},
{
"type": "anthropic",
"skill_id": "pptx",
"version": "latest"
},
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Analyze sales data and create a presentation"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
```bash CLI nocheck
ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: xlsx
version: latest
- type: anthropic
skill_id: pptx
version: latest
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: latest
messages:
- role: user
content: Analyze sales data and create a presentation
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python nocheck
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{"type": "anthropic", "skill_id": "pptx", "version": "latest"},
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
},
]
},
messages=[
{"role": "user", "content": "Analyze sales data and create a presentation"}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript nocheck
const response = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{
type: "anthropic",
skill_id: "xlsx",
version: "latest"
},
{
type: "anthropic",
skill_id: "pptx",
version: "latest"
},
{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}
]
},
messages: [
{
role: "user",
content: "Analyze sales data and create a presentation"
}
],
tools: [
{
type: "code_execution_20250825",
name: "code_execution"
}
]
});
```
```csharp C# nocheck
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Beta.Messages;
public class Program
{
public static async Task Main(string[] args)
{
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = "claude-opus-4-7",
MaxTokens = 4096,
Betas = new[] { "code-execution-2025-08-25", "skills-2025-10-02" },
Container = new BetaContainerParams
{
Skills = new object[]
{
new
{
type = "anthropic",
skill_id = "xlsx",
version = "latest"
},
new
{
type = "anthropic",
skill_id = "pptx",
version = "latest"
},
new
{
type = "custom",
skill_id = "skill_01AbCdEfGhIjKlMnOpQrStUv",
version = "latest"
}
}
},
Messages = new[]
{
new BetaMessageParam
{
Role = Role.User,
Content = "Analyze sales data and create a presentation"
}
},
Tools = new object[]
{
new
{
type = "code_execution_20250825",
name = "code_execution"
}
}
};
var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);
}
}
```
```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: "claude-opus-4-7",
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{
"code-execution-2025-08-25",
anthropic.AnthropicBetaSkills2025_10_02,
},
Container: anthropic.BetaMessageNewParamsContainerUnion{
OfContainers: &anthropic.BetaContainerParams{
Skills: []anthropic.BetaSkillParams{
{
Type: anthropic.BetaSkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
{
Type: anthropic.BetaSkillParamsTypeAnthropic,
SkillID: "pptx",
Version: anthropic.String("latest"),
},
{
Type: anthropic.BetaSkillParamsTypeCustom,
SkillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Analyze sales data and create a presentation")),
},
Tools: []anthropic.BetaToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
}
```
```java Java nocheck hidelines={1..4,8..11,-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.BetaContainerParams;
import com.anthropic.models.beta.messages.BetaSkillParams;
import com.anthropic.models.beta.messages.BetaCodeExecutionTool20250825;
import java.util.List;
public class SkillsExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model("claude-opus-4-7")
.maxTokens(4096L)
.addBeta("code-execution-2025-08-25")
.addBeta("skills-2025-10-02")
.container(BetaContainerParams.builder()
.skills(List.of(
BetaSkillParams.builder()
.type(BetaSkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build(),
BetaSkillParams.builder()
.type(BetaSkillParams.Type.ANTHROPIC)
.skillId("pptx")
.version("latest")
.build(),
BetaSkillParams.builder()
.type(BetaSkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version("latest")
.build()
))
.build())
.addUserMessage("Analyze sales data and create a presentation")
.addTool(BetaCodeExecutionTool20250825.builder().build())
.build();
BetaMessage response = client.beta().messages().create(params);
System.out.println(response);
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->beta->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Analyze sales data and create a presentation']
],
model: 'claude-opus-4-7',
betas: ['code-execution-2025-08-25', 'skills-2025-10-02'],
container: [
'skills' => [
[
'type' => 'anthropic',
'skill_id' => 'xlsx',
'version' => 'latest'
],
[
'type' => 'anthropic',
'skill_id' => 'pptx',
'version' => 'latest'
],
[
'type' => 'custom',
'skill_id' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $message;
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
message = client.beta.messages.create(
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{
type: "anthropic",
skill_id: "xlsx",
version: "latest"
},
{
type: "anthropic",
skill_id: "pptx",
version: "latest"
},
{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}
]
},
messages: [
{ role: "user", content: "Analyze sales data and create a presentation" }
],
tools: [
{ type: "code_execution_20250825", name: "code_execution" }
]
)
puts message
```
</CodeGroup>
---
## Managing Custom Skills
### Creating a Skill
Upload your custom Skill to make it available in your workspace. You can upload using either a directory path or individual file objects.
<CodeGroup defaultLanguage="CLI">
```bash cURL nocheck
curl -X POST "https://api.anthropic.com/v1/skills" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: skills-2025-10-02" \
-F "display_title=Financial Analysis" \
-F "files[]=@financial_skill/SKILL.md;filename=financial_skill/SKILL.md" \
-F "files[]=@financial_skill/analyze.py;filename=financial_skill/analyze.py"
```
```bash CLI nocheck
# Option 1: Upload individual files (one --file flag per file)
ant beta:skills create \
--display-title "Financial Analysis" \
--file financial_skill/SKILL.md \
--file financial_skill/analyze.py \
--beta skills-2025-10-02
# Option 2: Upload a zip archive
ant beta:skills create \
--display-title "Financial Analysis" \
--file financial_analysis_skill.zip \
--beta skills-2025-10-02
```
```python Python nocheck hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
# Option 1: Using files_from_dir helper (Python only, recommended)
from anthropic.lib import files_from_dir
skill = client.beta.skills.create(
display_title="Financial Analysis",
files=files_from_dir("/path/to/financial_analysis_skill"),
)
# Option 2: Using a zip file
skill = client.beta.skills.create(
display_title="Financial Analysis",
files=[("skill.zip", open("financial_analysis_skill.zip", "rb"))],
)
# Option 3: Using file tuples (filename, file_content, mime_type)
skill = client.beta.skills.create(
display_title="Financial Analysis",
files=[
(
"financial_skill/SKILL.md",
open("financial_skill/SKILL.md", "rb"),
"text/markdown",
),
(
"financial_skill/analyze.py",
open("financial_skill/analyze.py", "rb"),
"text/x-python",
),
],
)
print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")
```
```typescript TypeScript nocheck
import Anthropic, { toFile } from "@anthropic-ai/sdk";
import fs from "fs";
const client = new Anthropic();
// Option 1: Using a zip file
const skillFromZip = await client.beta.skills.create({
display_title: "Financial Analysis",
files: [await toFile(fs.createReadStream("financial_analysis_skill.zip"), "skill.zip")]
});
// Option 2: Using individual file objects
const skill = await client.beta.skills.create({
display_title: "Financial Analysis",
files: [
await toFile(fs.createReadStream("financial_skill/SKILL.md"), "financial_skill/SKILL.md", {
type: "text/markdown"
}),
await toFile(
fs.createReadStream("financial_skill/analyze.py"),
"financial_skill/analyze.py",
{ type: "text/x-python" }
)
]
});
console.log(`Created skill: ${skill.id}`);
console.log(`Latest version: ${skill.latest_version}`);
```
```csharp C# nocheck
using System;
using System.IO;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Beta.Skills;
class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new();
// Option 1: Using a zip file
var parameters = new SkillCreateParams
{
DisplayTitle = "Financial Analysis",
Files = [
new FileStream("financial_analysis_skill.zip", FileMode.Open, FileAccess.Read)
],
};
var skill = await client.Beta.Skills.Create(parameters);
// Option 2: Using individual files
var parameters2 = new SkillCreateParams
{
DisplayTitle = "Financial Analysis",
Files = [
new FileStream("financial_skill/SKILL.md", FileMode.Open, FileAccess.Read),
new FileStream("financial_skill/analyze.py", FileMode.Open, FileAccess.Read)
],
};
var skill2 = await client.Beta.Skills.Create(parameters2);
Console.WriteLine($"Created skill: {skill.Id}");
Console.WriteLine($"Latest version: {skill.LatestVersion}");
}
}
```
```go Go nocheck hidelines={1..15,-1}
package main
import (
"context"
"fmt"
"io"
"log"
"os"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
// Option 1: Using a zip file
zipFile, err := os.Open("financial_analysis_skill.zip")
if err != nil {
log.Fatal(err)
}
defer zipFile.Close()
skill, err := client.Beta.Skills.New(context.TODO(), anthropic.BetaSkillNewParams{
DisplayTitle: anthropic.String("Financial Analysis"),
Files: []io.Reader{zipFile},
})
if err != nil {
log.Fatal(err)
}
// Option 2: Using individual files
skillMd, err := os.Open("financial_skill/SKILL.md")
if err != nil {
log.Fatal(err)
}
defer skillMd.Close()
analyzePy, err := os.Open("financial_skill/analyze.py")
if err != nil {
log.Fatal(err)
}
defer analyzePy.Close()
skill2, err := client.Beta.Skills.New(context.TODO(), anthropic.BetaSkillNewParams{
DisplayTitle: anthropic.String("Financial Analysis"),
Files: []io.Reader{skillMd, analyzePy},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Created skill: %s\n", skill.ID)
fmt.Printf("Latest version: %s\n", skill.LatestVersion)
fmt.Printf("Created skill 2: %s\n", skill2.ID)
}
```
```java Java nocheck hidelines={1..2,5..10,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.skills.SkillCreateParams;
import com.anthropic.models.beta.skills.SkillCreateResponse;
import java.io.FileInputStream;
import java.io.IOException;
import java.nio.file.Path;
public class SkillCreate {
public static void main(String[] args) throws IOException {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Option 1: Using a zip file
SkillCreateParams params = SkillCreateParams.builder()
.displayTitle("Financial Analysis")
.addFile(new FileInputStream("financial_analysis_skill.zip"))
.build();
SkillCreateResponse skill = client.beta().skills().create(params);
// Option 2: Using individual files
SkillCreateParams params2 = SkillCreateParams.builder()
.displayTitle("Financial Analysis")
.addFile(Path.of("financial_skill/SKILL.md"))
.addFile(Path.of("financial_skill/analyze.py"))
.build();
SkillCreateResponse skill2 = client.beta().skills().create(params2);
System.out.println("Created skill: " + skill.id());
System.out.println("Latest version: " + skill.latestVersion());
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
// Option 1: Using a zip file
$skill = $client->beta->skills->create(
displayTitle: 'Financial Analysis',
files: [
fopen('financial_analysis_skill.zip', 'r')
],
);
// Option 2: Using individual files
$skill = $client->beta->skills->create(
displayTitle: 'Financial Analysis',
files: [
fopen('financial_skill/SKILL.md', 'r'),
fopen('financial_skill/analyze.py', 'r')
],
);
echo "Created skill: {$skill->id}\n";
echo "Latest version: {$skill->latestVersion}\n";
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
# Option 1: Using a zip file
skill = client.beta.skills.create(
display_title: "Financial Analysis",
files: [
File.open("financial_analysis_skill.zip", "rb")
]
)
# Option 2: Using individual files
skill = client.beta.skills.create(
display_title: "Financial Analysis",
files: [
File.open("financial_skill/SKILL.md", "rb"),
File.open("financial_skill/analyze.py", "rb")
]
)
puts "Created skill: #{skill.id}"
puts "Latest version: #{skill.latest_version}"
```
</CodeGroup>
**Requirements:**
- Must include a SKILL.md file at the top level
- All files must specify a common root directory in their paths
- Total upload size must be under 30 MB
- YAML frontmatter requirements:
- `name`: Maximum 64 characters, lowercase letters/numbers/hyphens only, no XML tags, no reserved words ("anthropic", "claude")
- `description`: Maximum 1024 characters, non-empty, no XML tags
For complete request/response schemas, see the [Create Skill API reference](/docs/en/api/skills/create-skill).
### Listing Skills
Retrieve all Skills available to your workspace, including both Anthropic pre-built Skills and your custom Skills. Use the `source` parameter to filter by skill type:
<CodeGroup defaultLanguage="CLI">
```bash cURL
# List all Skills
curl "https://api.anthropic.com/v1/skills" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: skills-2025-10-02"
# List only custom Skills
curl "https://api.anthropic.com/v1/skills?source=custom" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: skills-2025-10-02"
```
```bash CLI
# List all Skills
ant beta:skills list
# List only custom Skills
ant beta:skills list --source custom
```
```python Python
# List all Skills
skills = client.beta.skills.list()
for skill in skills.data:
print(f"{skill.id}: {skill.display_title} (source: {skill.source})")
# List only custom Skills
custom_skills = client.beta.skills.list(source="custom")
```
```typescript TypeScript
// List all Skills
const skills = await client.beta.skills.list();
for (const skill of skills.data) {
console.log(`${skill.id}: ${skill.display_title} (source: ${skill.source})`);
}
// List only custom Skills
const customSkills = await client.beta.skills.list({
source: "custom"
});
```
```csharp C# nocheck
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Beta.Skills;
class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new();
// List all Skills
var skills = await client.Beta.Skills.List();
foreach (var skill in skills.Data)
{
Console.WriteLine($"{skill.Id}: {skill.DisplayTitle} (source: {skill.Source})");
}
// List only custom Skills
var customSkills = await client.Beta.Skills.List(new SkillListParams
{
Source = "custom",
});
}
}
```
```go Go hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
// List all Skills
skills := client.Beta.Skills.ListAutoPaging(context.TODO(), anthropic.BetaSkillListParams{})
for skills.Next() {
skill := skills.Current()
fmt.Printf("%s: %s (source: %s)\n", skill.ID, skill.DisplayTitle, skill.Source)
}
if skills.Err() != nil {
log.Fatal(skills.Err())
}
// List only custom Skills
customSkills := client.Beta.Skills.ListAutoPaging(context.TODO(), anthropic.BetaSkillListParams{
Source: anthropic.String("custom"),
})
for customSkills.Next() {
skill := customSkills.Current()
fmt.Printf("%s: %s (source: %s)\n", skill.ID, skill.DisplayTitle, skill.Source)
}
}
```
```java Java hidelines={1..2,6..8,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.skills.SkillListParams;
import com.anthropic.models.beta.skills.SkillListPage;
import com.anthropic.models.beta.skills.SkillListResponse;
public class ListSkills {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// List all Skills
SkillListPage skills = client.beta().skills().list();
for (SkillListResponse skill : skills.data()) {
System.out.println(skill.id() + ": " + skill.displayTitle() + " (source: " + skill.source() + ")");
}
// List only custom Skills
SkillListParams customParams = SkillListParams.builder()
.source("custom")
.build();
SkillListPage customSkills = client.beta().skills().list(customParams);
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
// List all Skills
$skills = $client->beta->skills->list();
foreach ($skills->data as $skill) {
echo "{$skill->id}: {$skill->displayTitle} (source: {$skill->source})\n";
}
// List only custom Skills
$customSkills = $client->beta->skills->list(
source: 'custom',
);
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
# List all Skills
skills = client.beta.skills.list
skills.data.each do |skill|
puts "#{skill.id}: #{skill.display_title} (source: #{skill.source})"
end
# List only custom Skills
custom_skills = client.beta.skills.list(
source: "custom"
)
```
</CodeGroup>
See the [List Skills API reference](/docs/en/api/skills/list-skills) for pagination and filtering options.
### Retrieving a Skill
Get details about a specific Skill:
<CodeGroup defaultLanguage="CLI">
```bash cURL nocheck
curl "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: skills-2025-10-02"
```
```bash CLI nocheck
ant beta:skills retrieve \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv
```
```python Python nocheck
skill = client.beta.skills.retrieve(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")
print(f"Skill: {skill.display_title}")
print(f"Latest version: {skill.latest_version}")
print(f"Created: {skill.created_at}")
```
```typescript TypeScript nocheck
const skill = await client.beta.skills.retrieve("skill_01AbCdEfGhIjKlMnOpQrStUv");
console.log(`Skill: ${skill.display_title}`);
console.log(`Latest version: ${skill.latest_version}`);
console.log(`Created: ${skill.created_at}`);
```
```csharp C# nocheck
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Beta.Skills;
class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new();
var skill = await client.Beta.Skills.Retrieve("skill_01AbCdEfGhIjKlMnOpQrStUv");
Console.WriteLine($"Skill: {skill.DisplayTitle}");
Console.WriteLine($"Latest version: {skill.LatestVersion}");
Console.WriteLine($"Created: {skill.CreatedAt}");
}
}
```
```go Go nocheck hidelines={1..13,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
skill, err := client.Beta.Skills.Get(
context.TODO(),
"skill_01AbCdEfGhIjKlMnOpQrStUv",
anthropic.BetaSkillGetParams{},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Skill: %s\n", skill.DisplayTitle)
fmt.Printf("Latest version: %s\n", skill.LatestVersion)
fmt.Printf("Created: %s\n", skill.CreatedAt)
}
```
```java Java nocheck hidelines={1..2,4..6,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.skills.SkillRetrieveResponse;
public class RetrieveSkill {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
SkillRetrieveResponse skill = client.beta().skills().retrieve("skill_01AbCdEfGhIjKlMnOpQrStUv");
System.out.println("Skill: " + skill.displayTitle());
System.out.println("Latest version: " + skill.latestVersion());
System.out.println("Created: " + skill.createdAt());
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$skill = $client->beta->skills->retrieve(
skillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
);
echo "Skill: " . $skill->displayTitle . "\n";
echo "Latest version: " . $skill->latestVersion . "\n";
echo "Created: " . $skill->createdAt . "\n";
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
skill = client.beta.skills.retrieve("skill_01AbCdEfGhIjKlMnOpQrStUv")
puts "Skill: #{skill.display_title}"
puts "Latest version: #{skill.latest_version}"
puts "Created: #{skill.created_at}"
```
</CodeGroup>
### Deleting a Skill
To delete a Skill, you must first delete all its versions:
<CodeGroup defaultLanguage="CLI">
```bash cURL nocheck
# Delete all versions first, then delete the Skill
curl -X DELETE "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: skills-2025-10-02"
```
```bash CLI nocheck
# Step 1: Delete all versions
ant beta:skills:versions list \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
--transform version --format yaml \
| tr -d '"' \
| while read -r VERSION; do
ant beta:skills:versions delete \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
--version "$VERSION" >/dev/null
done
# Step 2: Delete the Skill
ant beta:skills delete \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null
```
```python Python nocheck
# Step 1: Delete all versions
versions = client.beta.skills.versions.list(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")
for version in versions.data:
client.beta.skills.versions.delete(
skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
version=version.version,
)
# Step 2: Delete the Skill
client.beta.skills.delete(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")
```
```typescript TypeScript nocheck hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
// Step 1: Delete all versions
const versions = await client.beta.skills.versions.list("skill_01AbCdEfGhIjKlMnOpQrStUv");
for (const version of versions.data) {
await client.beta.skills.versions.delete("skill_01AbCdEfGhIjKlMnOpQrStUv", version.version);
}
// Step 2: Delete the Skill
await client.beta.skills.delete("skill_01AbCdEfGhIjKlMnOpQrStUv");
```
```csharp C# nocheck
using System;
using System.Threading.Tasks;
using Anthropic;
class Program
{
static async Task Main(string[] args)
{
AnthropicClient client = new();
// Step 1: Delete all versions
var versions = await client.Beta.Skills.Versions.List("skill_01AbCdEfGhIjKlMnOpQrStUv");
foreach (var version in versions.Data)
{
await client.Beta.Skills.Versions.Delete(
"skill_01AbCdEfGhIjKlMnOpQrStUv",
version.Version
);
}
// Step 2: Delete the Skill
await client.Beta.Skills.Delete("skill_01AbCdEfGhIjKlMnOpQrStUv");
}
}
```
```go Go nocheck hidelines={1..12,-1}
package main
import (
"context"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
// Step 1: Delete all versions
versions := client.Beta.Skills.Versions.ListAutoPaging(
context.TODO(),
"skill_01AbCdEfGhIjKlMnOpQrStUv",
anthropic.BetaSkillVersionListParams{},
)
for versions.Next() {
version := versions.Current()
_, err := client.Beta.Skills.Versions.Delete(
context.TODO(),
version.Version,
anthropic.BetaSkillVersionDeleteParams{
SkillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
},
)
if err != nil {
log.Fatal(err)
}
}
// Step 2: Delete the Skill
_, err := client.Beta.Skills.Delete(
context.TODO(),
"skill_01AbCdEfGhIjKlMnOpQrStUv",
anthropic.BetaSkillDeleteParams{},
)
if err != nil {
log.Fatal(err)
}
}
```
```java Java nocheck hidelines={1..2,5..7,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.skills.versions.VersionListPage;
import com.anthropic.models.beta.skills.versions.VersionDeleteParams;
public class DeleteSkill {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Step 1: Delete all versions
VersionListPage versions = client.beta().skills().versions().list("skill_01AbCdEfGhIjKlMnOpQrStUv");
for (var version : versions.data()) {
client.beta().skills().versions().delete(
version.version(),
VersionDeleteParams.builder()
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.build()
);
}
// Step 2: Delete the Skill
client.beta().skills().delete("skill_01AbCdEfGhIjKlMnOpQrStUv");
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
// Step 1: Delete all versions
$versions = $client->beta->skills->versions->list(
skillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
);
foreach ($versions->data as $version) {
$client->beta->skills->versions->delete(
skillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: $version->version,
);
}
// Step 2: Delete the Skill
$client->beta->skills->delete(
skillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
);
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
# Step 1: Delete all versions
versions = client.beta.skills.versions.list("skill_01AbCdEfGhIjKlMnOpQrStUv")
versions.data.each do |version|
client.beta.skills.versions.delete(
version.version,
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv"
)
end
# Step 2: Delete the Skill
client.beta.skills.delete("skill_01AbCdEfGhIjKlMnOpQrStUv")
```
</CodeGroup>
Attempting to delete a Skill with existing versions returns a 400 error.
### Versioning
Skills support versioning to manage updates safely:
**Anthropic-Managed Skills:**
- Versions use date format: `20251013`
- New versions released as updates are made
- Specify exact versions for stability
**Custom Skills:**
- Auto-generated epoch timestamps: `1759178010641129`
- Use `"latest"` to always get the most recent version
- Create new versions when updating Skill files
<CodeGroup defaultLanguage="CLI">
```bash cURL nocheck
# Create a new version
NEW_VERSION=$(curl -X POST "https://api.anthropic.com/v1/skills/skill_01AbCdEfGhIjKlMnOpQrStUv/versions" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: skills-2025-10-02" \
-F "files[]=@updated_skill/SKILL.md;filename=updated_skill/SKILL.md")
VERSION_NUMBER=$(echo "$NEW_VERSION" | jq -r '.version')
# Use specific version
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d "{
\"model\": \"claude-opus-4-7\",
\"max_tokens\": 4096,
\"container\": {
\"skills\": [{
\"type\": \"custom\",
\"skill_id\": \"skill_01AbCdEfGhIjKlMnOpQrStUv\",
\"version\": \"$VERSION_NUMBER\"
}]
},
\"messages\": [{\"role\": \"user\", \"content\": \"Use updated Skill\"}],
\"tools\": [{\"type\": \"code_execution_20250825\", \"name\": \"code_execution\"}]
}"
# Use latest version
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 4096,
"container": {
"skills": [{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest"
}]
},
"messages": [{"role": "user", "content": "Use latest Skill version"}],
"tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
}'
```
```bash CLI nocheck
# Create a new version
VERSION_NUMBER=$(ant beta:skills:versions create \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
--file updated_skill/SKILL.md \
--transform version --format yaml)
# Use specific version
ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 <<YAML
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: $VERSION_NUMBER
messages:
- role: user
content: Use updated Skill
tools:
- type: code_execution_20250825
name: code_execution
YAML
# Use latest version
ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: latest
messages:
- role: user
content: Use latest Skill version
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python nocheck
# Create a new version
from anthropic.lib import files_from_dir
new_version = client.beta.skills.versions.create(
skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
files=files_from_dir("/path/to/updated_skill"),
)
# Use specific version
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": new_version.version,
}
]
},
messages=[{"role": "user", "content": "Use updated Skill"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# Use latest version
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
}
]
},
messages=[{"role": "user", "content": "Use latest Skill version"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript nocheck hidelines={1}
import Anthropic from "@anthropic-ai/sdk";
import fs from "fs";
const client = new Anthropic();
// Create a new version using a zip file
const newVersion = await client.beta.skills.versions.create("skill_01AbCdEfGhIjKlMnOpQrStUv", {
files: [fs.createReadStream("updated_skill.zip")]
});
// Use specific version
const specificVersionResponse = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: newVersion.version
}
]
},
messages: [{ role: "user", content: "Use updated Skill" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
// Use latest version
const latestVersionResponse = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}
]
},
messages: [{ role: "user", content: "Use latest Skill version" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
```
```csharp C# nocheck
using System;
using System.IO;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Beta.Messages;
using Anthropic.Models.Beta.Skills;
class Program
{
static async Task Main()
{
var client = new AnthropicClient
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
// Create a new version
var versionParams = new SkillVersionCreateParams
{
Files = [File.OpenRead("/path/to/updated_skill/SKILL.md")],
};
var newVersion = await client.Beta.Skills.Versions.Create(
"skill_01AbCdEfGhIjKlMnOpQrStUv",
versionParams
);
// Use specific version
var specificVersionParams = new MessageCreateParams
{
Model = "claude-opus-4-7",
MaxTokens = 4096,
Betas = ["code-execution-2025-08-25", "skills-2025-10-02"],
Container = new()
{
Skills =
[
new()
{
Type = "custom",
SkillId = "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version = newVersion.Version
}
]
},
Messages = [new() { Role = Role.User, Content = "Use updated Skill" }],
Tools =
[
new() { Type = "code_execution_20250825", Name = "code_execution" }
]
};
var response = await client.Beta.Messages.Create(specificVersionParams);
Console.WriteLine(response);
// Use latest version
var latestVersionParams = new MessageCreateParams
{
Model = "claude-opus-4-7",
MaxTokens = 4096,
Betas = ["code-execution-2025-08-25", "skills-2025-10-02"],
Container = new()
{
Skills =
[
new()
{
Type = "custom",
SkillId = "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version = "latest"
}
]
},
Messages = [new() { Role = Role.User, Content = "Use latest Skill version" }],
Tools =
[
new() { Type = "code_execution_20250825", Name = "code_execution" }
]
};
var latestResponse = await client.Beta.Messages.Create(latestVersionParams);
Console.WriteLine(latestResponse);
}
}
```
```go Go nocheck hidelines={1..13,87..88}
package main
import (
"context"
"fmt"
"io"
"log"
"os"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
// Create a new version
skillFile := mustOpen("/path/to/updated_skill/SKILL.md")
defer skillFile.Close()
newVersion, err := client.Beta.Skills.Versions.New(
context.TODO(),
"skill_01AbCdEfGhIjKlMnOpQrStUv",
anthropic.BetaSkillVersionNewParams{
Files: []io.Reader{skillFile},
},
)
if err != nil {
log.Fatal(err)
}
// Use specific version
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: "claude-opus-4-7",
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{"code-execution-2025-08-25", anthropic.AnthropicBetaSkills2025_10_02},
Container: anthropic.BetaMessageNewParamsContainerUnion{
OfContainers: &anthropic.BetaContainerParams{
Skills: []anthropic.BetaSkillParams{
{
Type: anthropic.BetaSkillParamsTypeCustom,
SkillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version: anthropic.String(newVersion.Version),
},
},
},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Use updated Skill")),
},
Tools: []anthropic.BetaToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
// Use latest version
latestResponse, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: "claude-opus-4-7",
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{"code-execution-2025-08-25", anthropic.AnthropicBetaSkills2025_10_02},
Container: anthropic.BetaMessageNewParamsContainerUnion{
OfContainers: &anthropic.BetaContainerParams{
Skills: []anthropic.BetaSkillParams{
{
Type: anthropic.BetaSkillParamsTypeCustom,
SkillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Use latest Skill version")),
},
Tools: []anthropic.BetaToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(latestResponse)
}
func mustOpen(path string) *os.File {
f, err := os.Open(path)
if err != nil {
log.Fatal(err)
}
return f
}
```
```java Java nocheck hidelines={1..4,10..13,-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.BetaContainerParams;
import com.anthropic.models.beta.messages.BetaSkillParams;
import com.anthropic.models.beta.messages.BetaCodeExecutionTool20250825;
import com.anthropic.models.beta.skills.versions.VersionCreateParams;
import com.anthropic.models.beta.skills.versions.VersionCreateResponse;
import java.nio.file.Path;
public class SkillVersioning {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Create a new version
VersionCreateParams versionParams = VersionCreateParams.builder()
.addFile(Path.of("/path/to/updated_skill/SKILL.md"))
.build();
VersionCreateResponse newVersion = client.beta().skills().versions()
.create("skill_01AbCdEfGhIjKlMnOpQrStUv", versionParams);
// Use specific version
MessageCreateParams specificVersionParams = MessageCreateParams.builder()
.model("claude-opus-4-7")
.maxTokens(4096L)
.addBeta("code-execution-2025-08-25")
.addBeta("skills-2025-10-02")
.container(BetaContainerParams.builder()
.addSkill(BetaSkillParams.builder()
.type(BetaSkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version(newVersion.version())
.build())
.build())
.addUserMessage("Use updated Skill")
.addTool(BetaCodeExecutionTool20250825.builder().build())
.build();
BetaMessage response = client.beta().messages().create(specificVersionParams);
System.out.println(response);
// Use latest version
MessageCreateParams latestVersionParams = MessageCreateParams.builder()
.model("claude-opus-4-7")
.maxTokens(4096L)
.addBeta("code-execution-2025-08-25")
.addBeta("skills-2025-10-02")
.container(BetaContainerParams.builder()
.addSkill(BetaSkillParams.builder()
.type(BetaSkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version("latest")
.build())
.build())
.addUserMessage("Use latest Skill version")
.addTool(BetaCodeExecutionTool20250825.builder().build())
.build();
BetaMessage latestResponse = client.beta().messages().create(latestVersionParams);
System.out.println(latestResponse);
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
// Create a new version
$newVersion = $client->beta->skills->versions->create(
skillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
files: [fopen("/path/to/updated_skill/SKILL.md", "r")],
);
// Use specific version
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: [['role' => 'user', 'content' => 'Use updated Skill']],
model: 'claude-opus-4-7',
betas: ['code-execution-2025-08-25', 'skills-2025-10-02'],
container: [
'skills' => [[
'type' => 'custom',
'skill_id' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => $newVersion->version
]]
],
tools: [['type' => 'code_execution_20250825', 'name' => 'code_execution']]
);
echo $response;
// Use latest version
$latestResponse = $client->beta->messages->create(
maxTokens: 4096,
messages: [['role' => 'user', 'content' => 'Use latest Skill version']],
model: 'claude-opus-4-7',
betas: ['code-execution-2025-08-25', 'skills-2025-10-02'],
container: [
'skills' => [[
'type' => 'custom',
'skill_id' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]]
],
tools: [['type' => 'code_execution_20250825', 'name' => 'code_execution']]
);
echo $latestResponse;
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
# Create a new version
new_version = client.beta.skills.versions.create(
"skill_01AbCdEfGhIjKlMnOpQrStUv",
files: [File.open("/path/to/updated_skill/SKILL.md")]
)
# Use specific version
response = client.beta.messages.create(
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: new_version.version
}]
},
messages: [{ role: "user", content: "Use updated Skill" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
puts response
# Use latest version
latest_response = client.beta.messages.create(
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}]
},
messages: [{ role: "user", content: "Use latest Skill version" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
puts latest_response
```
</CodeGroup>
See the [Create Skill Version API reference](/docs/en/api/skills/create-skill-version) for complete details.
---
## How Skills Are Loaded
When you specify Skills in a container:
1. **Metadata Discovery:** Claude sees metadata for each Skill (name, description) in the system prompt
2. **File Loading:** Skill files are copied into the container at `/skills/{directory}/`
3. **Automatic Use:** Claude automatically loads and uses Skills when relevant to your request
4. **Composition:** Multiple Skills compose together for complex workflows
The progressive disclosure architecture ensures efficient context usage: Claude only loads full Skill instructions when needed.
---
## Use Cases
### Organizational Skills
**Brand & Communications**
- Apply company-specific formatting (colors, fonts, layouts) to documents
- Generate communications following organizational templates
- Ensure consistent brand guidelines across all outputs
**Project Management**
- Structure notes with company-specific formats (OKRs, decision logs)
- Generate tasks following team conventions
- Create standardized meeting recaps and status updates
**Business Operations**
- Create company-standard reports, proposals, and analyses
- Execute company-specific analytical procedures
- Generate financial models following organizational templates
### Personal Skills
**Content Creation**
- Custom document templates
- Specialized formatting and styling
- Domain-specific content generation
**Data Analysis**
- Custom data processing pipelines
- Specialized visualization templates
- Industry-specific analytical methods
**Development & Automation**
- Code generation templates
- Testing frameworks
- Deployment workflows
### Example: Financial Modeling
Combine Excel and custom DCF analysis Skills:
<CodeGroup>
```bash cURL nocheck
# Create custom DCF analysis Skill
DCF_SKILL=$(curl -X POST "https://api.anthropic.com/v1/skills" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: skills-2025-10-02" \
-F "display_title=DCF Analysis" \
-F "files[]=@dcf_skill/SKILL.md;filename=dcf_skill/SKILL.md")
DCF_SKILL_ID=$(echo "$DCF_SKILL" | jq -r '.id')
# Use with Excel to create financial model
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d "{
\"model\": \"claude-opus-4-7\",
\"max_tokens\": 4096,
\"container\": {
\"skills\": [
{
\"type\": \"anthropic\",
\"skill_id\": \"xlsx\",
\"version\": \"latest\"
},
{
\"type\": \"custom\",
\"skill_id\": \"$DCF_SKILL_ID\",
\"version\": \"latest\"
}
]
},
\"messages\": [{
\"role\": \"user\",
\"content\": \"Build a DCF valuation model for a SaaS company with the attached financials\"
}],
\"tools\": [{
\"type\": \"code_execution_20250825\",
\"name\": \"code_execution\"
}]
}"
```
```bash CLI nocheck
# Create custom DCF analysis Skill
DCF_SKILL_ID=$(ant beta:skills create \
--display-title "DCF Analysis" \
--file dcf_skill/SKILL.md \
--transform id --format yaml)
# Use with Excel to create financial model
ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 <<YAML
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: xlsx
version: latest
- type: custom
skill_id: $DCF_SKILL_ID
version: latest
messages:
- role: user
content: Build a DCF valuation model for a SaaS company with the attached financials
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python nocheck
# Create custom DCF analysis Skill
from anthropic.lib import files_from_dir
dcf_skill = client.beta.skills.create(
display_title="DCF Analysis",
files=files_from_dir("/path/to/dcf_skill"),
)
# Use with Excel to create financial model
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{"type": "custom", "skill_id": dcf_skill.id, "version": "latest"},
]
},
messages=[
{
"role": "user",
"content": "Build a DCF valuation model for a SaaS company with the attached financials",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript nocheck
// Create custom DCF analysis Skill
import Anthropic, { toFile } from "@anthropic-ai/sdk";
import fs from "fs";
const client = new Anthropic();
const dcfSkill = await client.beta.skills.create({
display_title: "DCF Analysis",
files: [await toFile(fs.createReadStream("dcf_skill.zip"), "skill.zip")]
});
// Use with Excel to create financial model
const response = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{ type: "anthropic", skill_id: "xlsx", version: "latest" },
{ type: "custom", skill_id: dcfSkill.id, version: "latest" }
]
},
messages: [
{
role: "user",
content: "Build a DCF valuation model for a SaaS company with the attached financials"
}
],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
```
```csharp C# nocheck hidelines={1..7}
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Beta.Messages;
var client = new AnthropicClient();
// Create custom DCF analysis Skill
var dcfSkill = await client.Beta.Skills.Create(new SkillCreateParams
{
DisplayTitle = "DCF Analysis",
Files = new[] { new SkillFileParam { Path = "dcf_skill/SKILL.md", Content = skillContent } },
});
// Use with Excel to create financial model
var parameters = new MessageCreateParams
{
Model = "claude-opus-4-7",
MaxTokens = 4096,
Betas = new[] { "code-execution-2025-08-25", "skills-2025-10-02" },
Container = new BetaContainerParams
{
Skills = new[]
{
new BetaSkillParam
{
Type = "anthropic",
SkillId = "xlsx",
Version = "latest"
},
new BetaSkillParam
{
Type = "custom",
SkillId = dcfSkill.Id,
Version = "latest"
}
}
},
Messages = new[]
{
new BetaMessageParam
{
Role = Role.User,
Content = "Build a DCF valuation model for a SaaS company with the attached financials"
}
},
Tools = new[]
{
new BetaToolParam
{
Type = "code_execution_20250825",
Name = "code_execution"
}
}
};
var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go nocheck hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
// Create custom DCF analysis Skill (ID obtained from Skills API)
dcfSkillID := "skill_01AbCdEfGhIjKlMnOpQrStUv"
// Use with Excel to create financial model
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: "claude-opus-4-7",
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{
"code-execution-2025-08-25",
anthropic.AnthropicBetaSkills2025_10_02,
},
Container: anthropic.BetaMessageNewParamsContainerUnion{
OfContainers: &anthropic.BetaContainerParams{
Skills: []anthropic.BetaSkillParams{
{
Type: anthropic.BetaSkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
{
Type: anthropic.BetaSkillParamsTypeCustom,
SkillID: dcfSkillID,
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Build a DCF valuation model for a SaaS company with the attached financials")),
},
Tools: []anthropic.BetaToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
}
```
```java Java nocheck hidelines={1..4,8..11,-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.BetaContainerParams;
import com.anthropic.models.beta.messages.BetaSkillParams;
import com.anthropic.models.beta.messages.BetaCodeExecutionTool20250825;
import java.util.List;
public class CustomSkillExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Create custom DCF analysis Skill (via Skills API)
String dcfSkillId = "skill_01AbCdEfGhIjKlMnOpQrStUv"; // From Skills API create response
// Use with Excel Skill to create financial model
MessageCreateParams params = MessageCreateParams.builder()
.model("claude-opus-4-7")
.maxTokens(4096L)
.addBeta("code-execution-2025-08-25")
.addBeta("skills-2025-10-02")
.container(BetaContainerParams.builder()
.skills(List.of(
BetaSkillParams.builder()
.type(BetaSkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build(),
BetaSkillParams.builder()
.type(BetaSkillParams.Type.CUSTOM)
.skillId(dcfSkillId)
.version("latest")
.build()
))
.build())
.addUserMessage("Build a DCF valuation model for a SaaS company with the attached financials")
.addTool(BetaCodeExecutionTool20250825.builder().build())
.build();
BetaMessage response = client.beta().messages().create(params);
System.out.println(response);
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
// Create custom DCF analysis Skill
$dcfSkillId = "skill_01AbCdEfGhIjKlMnOpQrStUv"; // From API response
// Use with Excel to create financial model
$message = $client->beta->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Build a DCF valuation model for a SaaS company with the attached financials']
],
model: 'claude-opus-4-7',
betas: ['code-execution-2025-08-25', 'skills-2025-10-02'],
container: [
'skills' => [
['type' => 'anthropic', 'skill_id' => 'xlsx', 'version' => 'latest'],
['type' => 'custom', 'skill_id' => $dcfSkillId, 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $message->content[0]->text;
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
# Create custom DCF analysis Skill
dcf_skill = client.beta.skills.create(
display_title: "DCF Analysis",
files: [
File.open("dcf_skill/SKILL.md", "rb")
]
)
# Use with Excel to create financial model
response = client.beta.messages.create(
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{ type: "anthropic", skill_id: "xlsx", version: "latest" },
{ type: "custom", skill_id: dcf_skill.id, version: "latest" }
]
},
messages: [
{ role: "user", content: "Build a DCF valuation model for a SaaS company with the attached financials" }
],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
```
</CodeGroup>
---
## Limits and Constraints
### Request Limits
- **Maximum Skills per request:** 8
- **Maximum Skill upload size:** 30 MB (all files combined)
- **YAML frontmatter requirements:**
- `name`: Maximum 64 characters, lowercase letters/numbers/hyphens only, no XML tags, no reserved words
- `description`: Maximum 1024 characters, non-empty, no XML tags
### Environment Constraints
Skills run in the code execution container with these limitations:
- **No network access** - Cannot make external API calls
- **No runtime package installation** - Only pre-installed packages available
- **Isolated environment** - Each request gets a fresh container
See the [code execution tool documentation](/docs/en/agents-and-tools/tool-use/code-execution-tool) for available packages.
---
## Best Practices
### When to Use Multiple Skills
Combine Skills when tasks involve multiple document types or domains:
**Good use cases:**
- Data analysis (Excel) + presentation creation (PowerPoint)
- Report generation (Word) + export to PDF
- Custom domain logic + document generation
**Avoid:**
- Including unused Skills (impacts performance)
### Version Management Strategy
**For production:**
```python nocheck
# Pin to specific versions for stability
container = {
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "1759178010641129", # Specific version
}
]
}
```
**For development:**
```python nocheck
# Use latest for active development
container = {
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest", # Always get newest
}
]
}
```
### Prompt Caching Considerations
When using prompt caching, note that changing the Skills list in your container breaks the cache:
<CodeGroup>
```bash cURL
# First request creates cache
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02,prompt-caching-2024-07-31" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 4096,
"container": {
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
]
},
"messages": [{"role": "user", "content": "Analyze sales data"}],
"tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
}'
# Adding/removing Skills breaks cache
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02,prompt-caching-2024-07-31" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 4096,
"container": {
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{"type": "anthropic", "skill_id": "pptx", "version": "latest"}
]
},
"messages": [{"role": "user", "content": "Create a presentation"}],
"tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
}'
```
```bash CLI
# First request creates cache
ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 \
--beta prompt-caching-2024-07-31 <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: xlsx
version: latest
messages:
- role: user
content: Analyze sales data
tools:
- type: code_execution_20250825
name: code_execution
YAML
# Adding/removing Skills breaks cache
ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 \
--beta prompt-caching-2024-07-31 <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: xlsx
version: latest
- type: anthropic
skill_id: pptx
version: latest
messages:
- role: user
content: Create a presentation
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python
# First request creates cache
response1 = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=[
"code-execution-2025-08-25",
"skills-2025-10-02",
"prompt-caching-2024-07-31",
],
container={
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
},
messages=[{"role": "user", "content": "Analyze sales data"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# Adding/removing Skills breaks cache
response2 = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=[
"code-execution-2025-08-25",
"skills-2025-10-02",
"prompt-caching-2024-07-31",
],
container={
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{
"type": "anthropic",
"skill_id": "pptx",
"version": "latest",
}, # Cache miss
]
},
messages=[{"role": "user", "content": "Create a presentation"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript
// First request creates cache
const response1 = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31"],
container: {
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages: [{ role: "user", content: "Analyze sales data" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
// Adding/removing Skills breaks cache
const response2 = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31"],
container: {
skills: [
{ type: "anthropic", skill_id: "xlsx", version: "latest" },
{ type: "anthropic", skill_id: "pptx", version: "latest" } // Cache miss
]
},
messages: [{ role: "user", content: "Create a presentation" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
```
```csharp C# nocheck
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();
// First request creates cache
var parameters1 = new MessageCreateParams
{
Model = "claude-opus-4-7",
MaxTokens = 4096,
Betas = new[] { "code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31" },
Container = new BetaContainer
{
Skills = new[]
{
new BetaSkill { Type = "anthropic", SkillId = "xlsx", Version = "latest" }
}
},
Messages = new[] { new BetaMessageParam { Role = Role.User, Content = "Analyze sales data" } },
Tools = new[] { new BetaTool { Type = "code_execution_20250825", Name = "code_execution" } }
};
var response1 = await client.Beta.Messages.Create(parameters1);
Console.WriteLine(response1);
// Adding/removing Skills breaks cache
var parameters2 = new MessageCreateParams
{
Model = "claude-opus-4-7",
MaxTokens = 4096,
Betas = new[] { "code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31" },
Container = new BetaContainer
{
Skills = new[]
{
new BetaSkill { Type = "anthropic", SkillId = "xlsx", Version = "latest" },
new BetaSkill { Type = "anthropic", SkillId = "pptx", Version = "latest" }
}
},
Messages = new[] { new BetaMessageParam { Role = Role.User, Content = "Create a presentation" } },
Tools = new[] { new BetaTool { Type = "code_execution_20250825", Name = "code_execution" } }
};
var response2 = await client.Beta.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()
// First request creates cache
response1, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: "claude-opus-4-7",
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{
"code-execution-2025-08-25",
anthropic.AnthropicBetaSkills2025_10_02,
anthropic.AnthropicBetaPromptCaching2024_07_31,
},
Container: anthropic.BetaMessageNewParamsContainerUnion{
OfContainers: &anthropic.BetaContainerParams{
Skills: []anthropic.BetaSkillParams{
{
Type: anthropic.BetaSkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Analyze sales data")),
},
Tools: []anthropic.BetaToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response1)
// Adding/removing Skills breaks cache
response2, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: "claude-opus-4-7",
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{
"code-execution-2025-08-25",
anthropic.AnthropicBetaSkills2025_10_02,
anthropic.AnthropicBetaPromptCaching2024_07_31,
},
Container: anthropic.BetaMessageNewParamsContainerUnion{
OfContainers: &anthropic.BetaContainerParams{
Skills: []anthropic.BetaSkillParams{
{
Type: anthropic.BetaSkillParamsTypeAnthropic,
SkillID: "xlsx",
Version: anthropic.String("latest"),
},
{
Type: anthropic.BetaSkillParamsTypeAnthropic,
SkillID: "pptx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Create a presentation")),
},
Tools: []anthropic.BetaToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response2)
}
```
```java Java hidelines={1..4,8..11,-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.BetaContainerParams;
import com.anthropic.models.beta.messages.BetaSkillParams;
import com.anthropic.models.beta.messages.BetaCodeExecutionTool20250825;
import java.util.List;
public class SkillsCaching {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// First request creates cache
MessageCreateParams params1 = MessageCreateParams.builder()
.model("claude-opus-4-7")
.maxTokens(4096L)
.addBeta("code-execution-2025-08-25")
.addBeta("skills-2025-10-02")
.addBeta("prompt-caching-2024-07-31")
.container(BetaContainerParams.builder()
.skills(List.of(
BetaSkillParams.builder()
.type(BetaSkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build()
))
.build())
.addUserMessage("Analyze sales data")
.addTool(BetaCodeExecutionTool20250825.builder().build())
.build();
BetaMessage response1 = client.beta().messages().create(params1);
System.out.println(response1);
// Adding/removing Skills breaks cache
MessageCreateParams params2 = MessageCreateParams.builder()
.model("claude-opus-4-7")
.maxTokens(4096L)
.addBeta("code-execution-2025-08-25")
.addBeta("skills-2025-10-02")
.addBeta("prompt-caching-2024-07-31")
.container(BetaContainerParams.builder()
.skills(List.of(
BetaSkillParams.builder()
.type(BetaSkillParams.Type.ANTHROPIC)
.skillId("xlsx")
.version("latest")
.build(),
BetaSkillParams.builder()
.type(BetaSkillParams.Type.ANTHROPIC)
.skillId("pptx")
.version("latest")
.build()
))
.build())
.addUserMessage("Create a presentation")
.addTool(BetaCodeExecutionTool20250825.builder().build())
.build();
BetaMessage response2 = client.beta().messages().create(params2);
System.out.println(response2);
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
// First request creates cache
$response1 = $client->beta->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Analyze sales data']
],
model: 'claude-opus-4-7',
betas: [
'code-execution-2025-08-25',
'skills-2025-10-02',
'prompt-caching-2024-07-31'
],
container: [
'skills' => [
['type' => 'anthropic', 'skill_id' => 'xlsx', 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $response1;
// Adding/removing Skills breaks cache
$response2 = $client->beta->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Create a presentation']
],
model: 'claude-opus-4-7',
betas: [
'code-execution-2025-08-25',
'skills-2025-10-02',
'prompt-caching-2024-07-31'
],
container: [
'skills' => [
['type' => 'anthropic', 'skill_id' => 'xlsx', 'version' => 'latest'],
['type' => 'anthropic', 'skill_id' => 'pptx', 'version' => 'latest']
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $response2;
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
# First request creates cache
response1 = client.beta.messages.create(
model: "claude-opus-4-7",
max_tokens: 4096,
betas: [
"code-execution-2025-08-25",
"skills-2025-10-02",
"prompt-caching-2024-07-31"
],
container: {
skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }]
},
messages: [{ role: "user", content: "Analyze sales data" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
puts response1
# Adding/removing Skills breaks cache
response2 = client.beta.messages.create(
model: "claude-opus-4-7",
max_tokens: 4096,
betas: [
"code-execution-2025-08-25",
"skills-2025-10-02",
"prompt-caching-2024-07-31"
],
container: {
skills: [
{ type: "anthropic", skill_id: "xlsx", version: "latest" },
{ type: "anthropic", skill_id: "pptx", version: "latest" }
]
},
messages: [{ role: "user", content: "Create a presentation" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
puts response2
```
</CodeGroup>
For best caching performance, keep your Skills list consistent across requests.
### Error Handling
Handle Skill-related errors gracefully:
<CodeGroup>
```bash CLI nocheck
if ! RESULT=$(ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 \
--transform-error error.message --format-error yaml 2>&1 <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: latest
messages:
- role: user
content: Process data
tools:
- type: code_execution_20250825
name: code_execution
YAML
); then
case "$RESULT" in
*skill*)
printf 'Skill error: %s\n' "$RESULT"
# Handle skill-specific errors
;;
*)
printf '%s\n' "$RESULT" >&2
exit 1
;;
esac
fi
```
```python Python nocheck hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
try:
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
}
]
},
messages=[{"role": "user", "content": "Process data"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
except anthropic.BadRequestError as e:
if "skill" in str(e):
print(f"Skill error: {e}")
# Handle skill-specific errors
else:
raise
```
```typescript TypeScript nocheck
try {
const response = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{ type: "custom", skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv", version: "latest" }
]
},
messages: [{ role: "user", content: "Process data" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
});
} catch (error) {
if (error instanceof Anthropic.BadRequestError && error.message.includes("skill")) {
console.error(`Skill error: ${error.message}`);
// Handle skill-specific errors
} else {
throw error;
}
}
```
```csharp C# nocheck
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Beta.Messages;
class Program
{
static async Task Main(string[] args)
{
var client = new AnthropicClient();
try
{
var parameters = new MessageCreateParams
{
Model = "claude-opus-4-7",
MaxTokens = 4096,
Betas = ["code-execution-2025-08-25", "skills-2025-10-02"],
Container = new BetaContainerParams
{
Skills = [
new BetaSkillParam
{
Type = "custom",
SkillId = "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version = "latest"
}
]
},
Messages = [new() { Role = Role.User, Content = "Process data" }],
Tools = [new BetaToolParam { Type = "code_execution_20250825", Name = "code_execution" }]
};
var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);
}
catch (Exception e) when (e.Message.Contains("skill"))
{
Console.WriteLine($"Skill error: {e.Message}");
}
}
}
```
```go Go nocheck hidelines={1..14,-1}
package main
import (
"context"
"fmt"
"log"
"strings"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
_, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: "claude-opus-4-7",
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{"code-execution-2025-08-25", anthropic.AnthropicBetaSkills2025_10_02},
Container: anthropic.BetaMessageNewParamsContainerUnion{
OfContainers: &anthropic.BetaContainerParams{
Skills: []anthropic.BetaSkillParams{
{
Type: anthropic.BetaSkillParamsTypeCustom,
SkillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Process data")),
},
Tools: []anthropic.BetaToolUnionParam{
{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
},
})
if err != nil {
if strings.Contains(err.Error(), "skill") {
fmt.Printf("Skill error: %v\n", err)
} else {
log.Fatal(err)
}
}
}
```
```java Java nocheck 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.BetaContainerParams;
import com.anthropic.models.beta.messages.BetaSkillParams;
import com.anthropic.models.beta.messages.BetaCodeExecutionTool20250825;
public class SkillErrorHandling {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
try {
MessageCreateParams params = MessageCreateParams.builder()
.model("claude-opus-4-7")
.maxTokens(4096L)
.addBeta("code-execution-2025-08-25")
.addBeta("skills-2025-10-02")
.container(BetaContainerParams.builder()
.addSkill(BetaSkillParams.builder()
.type(BetaSkillParams.Type.CUSTOM)
.skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
.version("latest")
.build())
.build())
.addUserMessage("Process data")
.addTool(BetaCodeExecutionTool20250825.builder().build())
.build();
BetaMessage response = client.beta().messages().create(params);
System.out.println(response);
} catch (Exception e) {
if (e.getMessage().contains("skill")) {
System.err.println("Skill error: " + e.getMessage());
} else {
throw e;
}
}
}
}
```
```php PHP hidelines={1..4} nocheck
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
try {
$message = $client->beta->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Process data']
],
model: 'claude-opus-4-7',
betas: ['code-execution-2025-08-25', 'skills-2025-10-02'],
container: [
'skills' => [
[
'type' => 'custom',
'skill_id' => 'skill_01AbCdEfGhIjKlMnOpQrStUv',
'version' => 'latest'
]
]
],
tools: [
['type' => 'code_execution_20250825', 'name' => 'code_execution']
]
);
echo $message->content[0]->text;
} catch (Exception $e) {
if (str_contains($e->getMessage(), 'skill')) {
echo "Skill error: " . $e->getMessage();
} else {
throw $e;
}
}
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
begin
response = client.beta.messages.create(
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{
type: "custom",
skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
version: "latest"
}
]
},
messages: [{ role: "user", content: "Process data" }],
tools: [{ type: "code_execution_20250825", name: "code_execution" }]
)
rescue Anthropic::Errors::BadRequestError => e
if e.message.include?("skill")
puts "Skill error: #{e.message}"
else
raise
end
end
```
</CodeGroup>
---
## Data retention
Agent Skills are not covered by ZDR arrangements. Skill definitions and execution data are retained according to Anthropic's standard data retention policy.
For ZDR eligibility across all features, see [API and data retention](/docs/en/build-with-claude/api-and-data-retention).
## Next Steps
<CardGroup cols={2}>
<Card
title="API Reference"
icon="book"
href="/docs/en/api/skills/create-skill"
>
Complete API reference with all endpoints
</Card>
<Card
title="Authoring Guide"
icon="edit"
href="/docs/en/agents-and-tools/agent-skills/best-practices"
>
Best practices for writing effective Skills
</Card>
<Card
title="Code Execution Tool"
icon="terminal"
href="/docs/en/agents-and-tools/tool-use/code-execution-tool"
>
Learn about the code execution environment
</Card>
</CardGroup>
---
## Guides/build-with-claude-streaming-74f4dddaf7.md
# Streaming Messages
---
When creating a Message, you can set `"stream": true` to incrementally stream the response using [server-sent events](https://developer.mozilla.org/en-US/Web/API/Server-sent%5Fevents/Using%5Fserver-sent%5Fevents) (SSE).
## Streaming with SDKs
The [Python](https://github.com/anthropics/anthropic-sdk-python) and [TypeScript](https://github.com/anthropics/anthropic-sdk-typescript) SDKs offer multiple ways of streaming. The [PHP](https://github.com/anthropics/anthropic-sdk-php) SDK provides streaming via `createStream()`. The Python SDK allows both sync and async streams. See the documentation in each SDK for details.
<CodeGroup>
```bash CLI
ant messages create --stream --format jsonl \
--model claude-opus-4-7 \
--max-tokens 1024 \
--message '{role: user, content: "Hello"}' \
| while IFS= read -r event; do
[[ $event == *'"text_delta"'* ]] || continue
text=${event#*'"text":"'}
printf '%b' "${text%\"*}"
done
```
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
with client.messages.stream(
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
model="claude-opus-4-7",
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
await client.messages
.stream({
messages: [{ role: "user", content: "Hello" }],
model: "claude-opus-4-7",
max_tokens: 1024
})
.on("text", (text) => {
console.log(text);
});
```
```csharp C#
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 = 1024,
Messages = [new() { Role = Role.User, Content = "Hello" }]
};
await foreach (var msg in client.Messages.CreateStreaming(parameters))
{
Console.Write(msg);
}
}
}
```
```go Go hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_7,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello")),
},
})
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)
}
}
```
```java Java hidelines={1..6,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
public class StreamingExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model("claude-opus-4-7")
.maxTokens(1024L)
.addUserMessage("Hello")
.build();
try (var streamResponse = client.messages().createStreaming(params)) {
streamResponse.stream().forEach(event -> {
event.contentBlockDelta().ifPresent(deltaEvent ->
deltaEvent.delta().text().ifPresent(td ->
System.out.print(td.text())
)
);
});
}
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$stream = $client->messages->createStream(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => 'Hello']
],
model: 'claude-opus-4-7',
);
foreach ($stream as $message) {
echo $message;
}
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
stream = client.messages.stream(
model: "claude-opus-4-7",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello" }]
)
stream.text.each { |text| print(text) }
```
</CodeGroup>
## Get the final message without handling events
If you don't need to process text as it arrives, the SDKs provide a way to use streaming under the hood while returning the complete `Message` object, identical to what `.create()` returns. This is especially useful for requests with large `max_tokens` values, where the SDKs require streaming to avoid HTTP timeouts.
<CodeGroup>
```bash CLI
# The ant CLI's --stream flag emits one event per line and does not
# accumulate into a final Message. For long generations, stream the
# raw events:
ant messages create --stream --format jsonl <<'YAML'
model: claude-opus-4-7
max_tokens: 128000
messages:
- role: user
content: Write a detailed analysis...
YAML
```
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
with client.messages.stream(
max_tokens=128000,
messages=[{"role": "user", "content": "Write a detailed analysis..."}],
model="claude-opus-4-7",
) as stream:
message = stream.get_final_message()
print(message.content[0].text)
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const stream = client.messages.stream({
max_tokens: 128000,
messages: [{ role: "user", content: "Write a detailed analysis..." }],
model: "claude-opus-4-7"
});
const message = await stream.finalMessage();
const textBlock = message.content.find((block) => block.type === "text");
if (textBlock && textBlock.type === "text") {
console.log(textBlock.text);
}
```
```csharp C# nocheck
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages;
class Program
{
static async Task Main()
{
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus4_7,
MaxTokens = 128000,
Messages = [new() { Role = Role.User, Content = "Write a detailed analysis..." }]
};
var fullText = "";
await foreach (var msg in client.Messages.CreateStreaming(parameters))
{
fullText += msg;
}
Console.WriteLine(fullText);
}
}
```
```go Go hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_7,
MaxTokens: 128000,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Write a detailed analysis...")),
},
})
message := anthropic.Message{}
for stream.Next() {
event := stream.Current()
if err := message.Accumulate(event); err != nil {
log.Fatal(err)
}
}
if err := stream.Err(); err != nil {
log.Fatal(err)
}
fmt.Println(message.Content[0].Text)
}
```
```java Java hidelines={1..2,4..9,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
public class StreamingExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(128000L)
.addUserMessage("Write a detailed analysis...")
.build();
MessageAccumulator accumulator = MessageAccumulator.create();
try (var streamResponse = client.messages().createStreaming(params)) {
streamResponse.stream().forEach(accumulator::accumulate);
}
Message message = accumulator.message();
message.content().get(0).text().ifPresent(tb -> System.out.println(tb.text()));
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$stream = $client->messages->createStream(
maxTokens: 128000,
messages: [
['role' => 'user', 'content' => 'Write a detailed analysis...']
],
model: 'claude-opus-4-7',
);
$fullText = '';
foreach ($stream as $event) {
if ($event->type === 'content_block_delta') {
$fullText .= $event->delta->text;
}
}
echo $fullText;
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
message = client.messages.stream(
model: "claude-opus-4-7",
max_tokens: 128000,
messages: [{ role: "user", content: "Write a detailed analysis..." }]
).accumulated_message
puts message.content.first.text
```
</CodeGroup>
The `.stream()` call keeps the HTTP connection alive with server-sent events, then `.get_final_message()` (Python) or `.finalMessage()` (TypeScript) accumulates all events and returns the complete `Message` object. In Go, you call `message.Accumulate(event)` inside the stream loop to build the same complete `Message`. In Java, use `MessageAccumulator.create()` and call `accumulator.accumulate(event)` on each event. In Ruby, call `.accumulated_message` on the stream. In the PHP SDK, you iterate over stream events manually to accumulate the response.
## Event types
Each server-sent event includes a named event type and associated JSON data. Each event uses an SSE event name (e.g. `event: message_stop`), and includes the matching event `type` in its data.
Each stream uses the following event flow:
1. `message_start`: contains a `Message` object with empty `content`.
2. A series of content blocks, each of which have a `content_block_start`, one or more `content_block_delta` events, and a `content_block_stop` event. Each content block has an `index` that corresponds to its index in the final Message `content` array.
3. One or more `message_delta` events, indicating top-level changes to the final `Message` object.
4. A final `message_stop` event.
<Warning>
The token counts shown in the `usage` field of the `message_delta` event are *cumulative*.
</Warning>
### Ping events
Event streams may also include any number of `ping` events.
### Error events
The API may occasionally send [errors](/docs/en/api/errors) in the event stream. For example, during periods of high usage, you may receive an `overloaded_error`, which would normally correspond to an HTTP 529 in a non-streaming context:
```sse Example error
event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}
```
### Other events
In accordance with the [versioning policy](/docs/en/api/versioning), new event types may be added, and your code should handle unknown event types gracefully.
## Content block delta types
Each `content_block_delta` event contains a `delta` of a type that updates the `content` block at a given `index`.
### Text delta
A `text` content block delta looks like:
```sse Text delta
event: content_block_delta
data: {"type": "content_block_delta","index": 0,"delta": {"type": "text_delta", "text": "ello frien"}}
```
### Input JSON delta
The deltas for `tool_use` content blocks correspond to updates for the `input` field of the block. To support maximum granularity, the deltas are _partial JSON strings_, whereas the final `tool_use.input` is always an _object_.
You can accumulate the string deltas and parse the JSON once you receive a `content_block_stop` event, by using a library like [Pydantic](https://docs.pydantic.dev/latest/concepts/json/#partial-json-parsing) to do partial JSON parsing, or by using the [SDKs](/docs/en/api/client-sdks), which provide helpers to access parsed incremental values.
A `tool_use` content block delta looks like:
```sse Input JSON delta
event: content_block_delta
data: {"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}
```
Note: Current models only support emitting one complete key and value property from `input` at a time. As such, when using tools, there may be delays between streaming events while the model is working. Once an `input` key and value are accumulated, they are emitted as multiple `content_block_delta` events with chunked partial json so that the format can automatically support finer granularity in future models.
### Thinking delta
When using [extended thinking](/docs/en/build-with-claude/extended-thinking#streaming-thinking) with streaming enabled, you'll receive thinking content via `thinking_delta` events. These deltas correspond to the `thinking` field of the `thinking` content blocks.
For thinking content, a special `signature_delta` event is sent just before the `content_block_stop` event. This signature is used to verify the integrity of the thinking block.
When `display: "omitted"` is set on the thinking configuration, no `thinking_delta` events are sent. The thinking block opens, receives a single `signature_delta`, and closes. See [Controlling thinking display](/docs/en/build-with-claude/extended-thinking#controlling-thinking-display).
A typical thinking delta looks like:
```sse Thinking delta
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}
```
The signature delta looks like:
```sse Signature delta
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}
```
## Full HTTP Stream response
Use the [client SDKs](/docs/en/api/client-sdks) when using streaming mode. However, if you are building a direct API integration, you need to handle these events yourself.
A stream response is comprised of:
1. A `message_start` event
2. Potentially multiple content blocks, each of which contains:
- A `content_block_start` event
- Potentially multiple `content_block_delta` events
- A `content_block_stop` event
3. A `message_delta` event
4. A `message_stop` event
There may be `ping` events dispersed throughout the response as well. See [Event types](#event-types) for more details on the format.
### Basic streaming request
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--data \
'{
"model": "claude-opus-4-7",
"messages": [{"role": "user", "content": "Hello"}],
"max_tokens": 256,
"stream": true
}'
```
```bash CLI
ant messages create --stream --format jsonl \
--model claude-opus-4-7 \
--max-tokens 256 \
--message '{role: user, content: Hello}'
```
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
with client.messages.stream(
model="claude-opus-4-7",
messages=[{"role": "user", "content": "Hello"}],
max_tokens=256,
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const stream = client.messages.stream({
model: "claude-opus-4-7",
messages: [{ role: "user", content: "Hello" }],
max_tokens: 256
});
for await (const event of stream) {
if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
process.stdout.write(event.delta.text);
}
}
```
```csharp C#
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 = 256,
Messages = [new() { Role = Role.User, Content = "Hello" }]
};
await foreach (var msg in client.Messages.CreateStreaming(parameters))
{
Console.Write(msg);
}
}
}
```
```go Go hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_7,
MaxTokens: 256,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello")),
},
})
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)
}
}
```
```java Java hidelines={1..7,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
public class StreamingExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(256L)
.addUserMessage("Hello")
.build();
try (var streamResponse = client.messages().createStreaming(params)) {
streamResponse.stream().forEach(event -> {
event.contentBlockDelta().ifPresent(deltaEvent ->
deltaEvent.delta().text().ifPresent(td ->
System.out.print(td.text())
)
);
});
}
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$stream = $client->messages->createStream(
maxTokens: 256,
messages: [
['role' => 'user', 'content' => 'Hello']
],
model: 'claude-opus-4-7',
);
foreach ($stream as $message) {
echo $message;
}
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
stream = client.messages.stream(
model: "claude-opus-4-7",
messages: [{ role: "user", content: "Hello" }],
max_tokens: 256
)
stream.text.each { |text| print(text) }
```
</CodeGroup>
```sse Response
event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-7", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}
event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}
event: ping
data: {"type": "ping"}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}
event: content_block_stop
data: {"type": "content_block_stop", "index": 0}
event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}
event: message_stop
data: {"type": "message_stop"}
```
### Streaming request with tool use
<Tip>
Tool use supports [fine-grained streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming) for parameter values. Enable it per tool with `eager_input_streaming`.
</Tip>
This request asks Claude to use a tool to report the weather.
<CodeGroup>
```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": [
{
"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"]
}
}
],
"tool_choice": {"type": "any"},
"messages": [
{
"role": "user",
"content": "What is the weather like in San Francisco?"
}
],
"stream": true
}'
```
```bash CLI
ant messages create --stream --format jsonl <<'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
required:
- location
tool_choice:
type: any
messages:
- role: user
content: What is the weather like in San Francisco?
YAML
```
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
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"],
},
}
]
with client.messages.stream(
model="claude-opus-4-7",
max_tokens=1024,
tools=tools,
tool_choice={"type": "any"},
messages=[
{"role": "user", "content": "What is the weather like in San Francisco?"}
],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const tools: Anthropic.Tool[] = [
{
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"]
}
}
];
const stream = client.messages.stream({
model: "claude-opus-4-7",
max_tokens: 1024,
tools: tools,
tool_choice: { type: "any" },
messages: [
{
role: "user",
content: "What is the weather like in San Francisco?"
}
]
});
for await (const event of stream) {
if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
process.stdout.write(event.delta.text);
}
}
```
```csharp C#
using System;
using System.Text.Json;
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 = 1024,
Tools = [
new ToolUnion(new Tool()
{
Name = "get_weather",
Description = "Get the current weather in a given location",
InputSchema = new InputSchema()
{
Properties = new Dictionary<string, JsonElement>
{
["location"] = JsonSerializer.SerializeToElement(new { type = "string", description = "The city and state, e.g. San Francisco, CA" }),
},
Required = ["location"],
},
}),
],
ToolChoice = new ToolChoiceAny(),
Messages = [
new() { Role = Role.User, Content = "What is the weather like in San Francisco?" }
]
};
await foreach (var msg in client.Messages.CreateStreaming(parameters))
{
Console.Write(msg);
}
}
}
```
```go Go hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
stream := client.Messages.NewStreaming(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",
},
},
Required: []string{"location"},
},
}},
},
ToolChoice: anthropic.ToolChoiceUnionParam{OfAny: &anthropic.ToolChoiceAnyParam{}},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What is the weather like in San Francisco?")),
},
})
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)
}
}
```
```java Java hidelines={1..13,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.ToolChoice;
import com.anthropic.models.messages.ToolChoiceAny;
import com.anthropic.models.messages.Tool;
import com.anthropic.core.JsonValue;
import java.util.Map;
import java.util.List;
public class StreamingToolUse {
public static void main(String[] args) {
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(Tool.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())
.toolChoice(ToolChoice.ofAny(ToolChoiceAny.builder().build()))
.addUserMessage("What is the weather like in San Francisco?")
.build();
try (var streamResponse = client.messages().createStreaming(params)) {
streamResponse.stream().forEach(event -> {
event.contentBlockDelta().ifPresent(deltaEvent ->
deltaEvent.delta().text().ifPresent(td ->
System.out.print(td.text())
)
);
});
}
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$stream = $client->messages->createStream(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => 'What is the weather like in San Francisco?']
],
model: 'claude-opus-4-7',
toolChoice: ['type' => 'any'],
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']
]
]
],
);
foreach ($stream as $message) {
echo $message;
}
```
```ruby Ruby hidelines={1..2}
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"]
}
}
]
stream = client.messages.stream(
model: "claude-opus-4-7",
max_tokens: 1024,
tools: tools,
tool_choice: { type: "any" },
messages: [
{ role: "user", content: "What is the weather like in San Francisco?" }
]
)
stream.text.each { |text| print(text) }
```
</CodeGroup>
```sse Response
event: message_start
data: {"type":"message_start","message":{"id":"msg_014p7gG3wDgGV9EUtLvnow3U","type":"message","role":"assistant","model":"claude-opus-4-7","stop_sequence":null,"usage":{"input_tokens":472,"output_tokens":2},"content":[],"stop_reason":null}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
event: ping
data: {"type": "ping"}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Okay"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" let"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"'s"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" check"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" the"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" weather"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" for"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" San"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Francisco"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" CA"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":":"}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"toolu_01T1x1fJ34qAmk2tNTrN7Up6","name":"get_weather","input":{}}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"location\":"}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"San"}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" Francisc"}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"o,"}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" CA\""}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":", "}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\"unit\": \"fah"}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"renheit\"}"}}
event: content_block_stop
data: {"type":"content_block_stop","index":1}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"tool_use","stop_sequence":null},"usage":{"output_tokens":89}}
event: message_stop
data: {"type":"message_stop"}
```
### Streaming request with extended thinking
This request enables extended thinking with streaming to see Claude's step-by-step reasoning.
<CodeGroup>
```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": 20000,
"stream": true,
"thinking": {
"type": "adaptive",
"display": "summarized"
},
"messages": [
{
"role": "user",
"content": "What is the greatest common divisor of 1071 and 462?"
}
]
}'
```
```bash CLI
ant messages create --stream --format jsonl \
--model claude-opus-4-7 \
--max-tokens 20000 \
--thinking '{type: adaptive, display: summarized}' \
--message '{role: user, content: What is the greatest common divisor of 1071 and 462?}'
```
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
with client.messages.stream(
model="claude-opus-4-7",
max_tokens=20000,
thinking={"type": "adaptive", "display": "summarized"},
messages=[
{
"role": "user",
"content": "What is the greatest common divisor of 1071 and 462?",
}
],
) as stream:
for event in stream:
if event.type == "content_block_delta":
if event.delta.type == "thinking_delta":
print(event.delta.thinking, end="", flush=True)
elif event.delta.type == "text_delta":
print(event.delta.text, end="", flush=True)
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const stream = client.messages.stream({
model: "claude-opus-4-7",
max_tokens: 20000,
thinking: { type: "adaptive", display: "summarized" },
messages: [
{
role: "user",
content: "What is the greatest common divisor of 1071 and 462?"
}
]
});
for await (const event of stream) {
if (event.type === "content_block_delta") {
if (event.delta.type === "thinking_delta") {
process.stdout.write(event.delta.thinking);
} else if (event.delta.type === "text_delta") {
process.stdout.write(event.delta.text);
}
}
}
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus4_6,
MaxTokens = 20000,
Thinking = new ThinkingConfigEnabled(budgetTokens: 16000),
Messages = [new() { Role = Role.User, Content = "What is the greatest common divisor of 1071 and 462?" }]
};
await foreach (var msg in client.Messages.CreateStreaming(parameters))
{
Console.Write(msg);
}
```
```go Go hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_6,
MaxTokens: 20000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(16000),
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What is the greatest common divisor of 1071 and 462?")),
},
})
for stream.Next() {
event := stream.Current()
switch eventVariant := event.AsAny().(type) {
case anthropic.ContentBlockDeltaEvent:
switch deltaVariant := eventVariant.Delta.AsAny().(type) {
case anthropic.ThinkingDelta:
fmt.Print(deltaVariant.Thinking)
case anthropic.TextDelta:
fmt.Print(deltaVariant.Text)
}
}
}
if err := stream.Err(); err != nil {
log.Fatal(err)
}
}
```
```java Java hidelines={1..7,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
public class ExtendedThinkingStreaming {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_6)
.maxTokens(20000L)
.enabledThinking(16000L)
.addUserMessage("What is the greatest common divisor of 1071 and 462?")
.build();
try (var streamResponse = client.messages().createStreaming(params)) {
streamResponse.stream().forEach(event -> {
event.contentBlockDelta().ifPresent(deltaEvent -> {
deltaEvent.delta().thinking().ifPresent(td ->
System.out.print(td.thinking())
);
deltaEvent.delta().text().ifPresent(td ->
System.out.print(td.text())
);
});
});
}
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$stream = $client->messages->createStream(
maxTokens: 20000,
messages: [
['role' => 'user', 'content' => 'What is the greatest common divisor of 1071 and 462?']
],
model: 'claude-opus-4-7',
thinking: ['type' => 'adaptive', 'display' => 'summarized'],
);
foreach ($stream as $message) {
echo $message;
}
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
stream = client.messages.stream(
model: "claude-opus-4-7",
max_tokens: 20000,
thinking: { type: "adaptive", display: "summarized" },
messages: [
{ role: "user", content: "What is the greatest common divisor of 1071 and 462?" }
]
)
stream.each do |event|
if event.type == :content_block_delta
if event.delta.type == :thinking_delta
print(event.delta.thinking)
elsif event.delta.type == :text_delta
print(event.delta.text)
end
end
end
```
</CodeGroup>
```sse Response
event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-7", "stop_reason": null, "stop_sequence": null}}
event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": "", "signature": ""}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21"}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n147 = 7 × 21 + 0"}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\nThe remainder is 0, so GCD(1071, 462) = 21."}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}
event: content_block_stop
data: {"type": "content_block_stop", "index": 0}
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "The greatest common divisor of 1071 and 462 is **21**."}}
event: content_block_stop
data: {"type": "content_block_stop", "index": 1}
event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}
event: message_stop
data: {"type": "message_stop"}
```
### Streaming request with web search tool use
This request asks Claude to search the web for current weather information.
<CodeGroup>
```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,
"stream": true,
"tools": [
{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5
}
],
"messages": [
{
"role": "user",
"content": "What is the weather like in New York City today?"
}
]
}'
```
```bash CLI
ant messages create --stream --format jsonl \
--model claude-opus-4-7 \
--max-tokens 1024 \
--tool '{type: web_search_20250305, name: web_search, max_uses: 5}' \
--message '{role: user, content: What is the weather like in New York City today?}'
```
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
with client.messages.stream(
model="claude-opus-4-7",
max_tokens=1024,
tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
messages=[
{"role": "user", "content": "What is the weather like in New York City today?"}
],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
```
```typescript TypeScript hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const stream = client.messages.stream({
model: "claude-opus-4-7",
max_tokens: 1024,
tools: [{ type: "web_search_20250305", name: "web_search", max_uses: 5 }],
messages: [{ role: "user", content: "What is the weather like in New York City today?" }]
});
for await (const event of stream) {
if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
process.stdout.write(event.delta.text);
}
}
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus4_7,
MaxTokens = 1024,
Tools = [new ToolUnion(new WebSearchTool20250305() { MaxUses = 5 })],
Messages = [new() { Role = Role.User, Content = "What is the weather like in New York City today?" }]
};
await foreach (var msg in client.Messages.CreateStreaming(parameters))
{
Console.Write(msg);
}
```
```go Go hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_7,
MaxTokens: 1024,
Tools: []anthropic.ToolUnionParam{
{
OfWebSearchTool20250305: &anthropic.WebSearchTool20250305Param{
MaxUses: anthropic.Int(5),
},
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What is the weather like in New York City today?")),
},
})
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)
}
}
```
```java Java hidelines={1..4,6..8,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.WebSearchTool20250305;
public class WebSearchStreaming {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_7)
.maxTokens(1024L)
.addTool(WebSearchTool20250305.builder()
.maxUses(5L)
.build())
.addUserMessage("What is the weather like in New York City today?")
.build();
try (var streamResponse = client.messages().createStreaming(params)) {
streamResponse.stream().forEach(event -> {
event.contentBlockDelta().ifPresent(deltaEvent ->
deltaEvent.delta().text().ifPresent(td ->
System.out.print(td.text())
)
);
});
}
}
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$stream = $client->messages->createStream(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => 'What is the weather like in New York City today?']
],
model: 'claude-opus-4-7',
tools: [
['type' => 'web_search_20250305', 'name' => 'web_search', 'max_uses' => 5]
],
);
foreach ($stream as $message) {
echo $message;
}
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
stream = client.messages.stream(
model: :"claude-opus-4-7",
max_tokens: 1024,
tools: [
{
type: "web_search_20250305",
name: "web_search",
max_uses: 5
}
],
messages: [
{
role: "user",
content: "What is the weather like in New York City today?"
}
]
)
stream.text.each { |text| print(text) }
```
</CodeGroup>
```sse Response
event: message_start
data: {"type":"message_start","message":{"id":"msg_01G...","type":"message","role":"assistant","model":"claude-opus-4-7","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":2679,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":3}}}
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":"I'll check"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" the current weather in New York City for you"}}
event: ping
data: {"type": "ping"}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"."}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"server_tool_use","id":"srvtoolu_014hJH82Qum7Td6UV8gDXThB","name":"web_search","input":{}}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"query"}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\":"}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"weather"}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" NY"}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"C to"}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"day\"}"}}
event: content_block_stop
data: {"type":"content_block_stop","index":1 }
event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"web_search_tool_result","tool_use_id":"srvtoolu_014hJH82Qum7Td6UV8gDXThB","content":[{"type":"web_search_result","title":"Weather in New York City in May 2025 (New York) - detailed Weather Forecast for a month","url":"https://world-weather.info/forecast/usa/new_york/may-2025/","encrypted_content":"Ev0DCioIAxgCIiQ3NmU4ZmI4OC1k...","page_age":null},...]}}
event: content_block_stop
data: {"type":"content_block_stop","index":2}
event: content_block_start
data: {"type":"content_block_start","index":3,"content_block":{"type":"text","text":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":"Here's the current weather information for New York"}}
event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":" City:\n\n# Weather"}}
event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":" in New York City"}}
event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":"\n\n"}}
...
event: content_block_stop
data: {"type":"content_block_stop","index":17}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":10682,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":510,"server_tool_use":{"web_search_requests":1}}}
event: message_stop
data: {"type":"message_stop"}
```
## Error recovery
### Claude 4.5 and earlier
For Claude 4.5 models and earlier, you can recover a streaming request that was interrupted due to network issues, timeouts, or other errors by resuming from where the stream was interrupted. This approach saves you from re-processing the entire response.
The basic recovery strategy involves:
1. **Capture the partial response**: Save all content that was successfully received before the error occurred
2. **Construct a continuation request**: Create a new API request that includes the partial assistant response as the beginning of a new assistant message
3. **Resume streaming**: Continue receiving the rest of the response from where it was interrupted
### Claude 4.6
For Claude 4.6 models, you should add a user message that instructs the model to continue from where it left off. For example:
```text Sample prompt
Your previous response was interrupted and ended with [previous_response]. Continue from where you left off.
```
### Error recovery best practices
1. **Use SDK features**: Leverage the SDK's built-in message accumulation and error handling capabilities
2. **Handle content types**: Be aware that messages can contain multiple content blocks (`text`, `tool_use`, `thinking`). Tool use and extended thinking blocks cannot be partially recovered. You can resume streaming from the most recent text block.
---
*Truncated: 1105 more documents not shown (size limit)*