One read of Claude Developer Platformapi-20261023T100709Z
143 pages moved out of 820 read.
Pages moved
143
significant first
Pages read
820
in this capture
Captured
10:07 UTC
Corpus hash
1df9c76a5544
corpus-hash
What this read moved
1-25 of 143, page 1 of 6This capture is too large to show at once. Changes 1-25 of 143 are below, significant first; the rest are on the following screens.
about-claude/pricing Changed · +3 / -3 lines
from line 300
300300
301301Code execution usage is tracked in the response:
302302
303```text wrap
303```json
304304{
305305 "usage": {
306306 "input_tokens": 105,
from line 329
329329
330330Web search usage is charged in addition to token usage:
331331
332```text wrap
332```json
333333{
334334 "usage": {
335335 "input_tokens": 105,
from line 351
351351
352352Web fetch usage has **no additional charges** beyond standard token costs:
353353
354```text wrap
354```json
355355{
356356 "usage": {
357357 "input_tokens": 25039,
about-claude/use-case-guides/commerce-agents Changed · +5 / -1 lines
from line 4
44description: Build a shopping agent and a merchant agent on Claude using Claude for commerce, an open-source blueprint with working implementations on the Messages API, the Claude Agent SDK, and Claude Managed Agents.
55---
66
7This guide shows how to build commerce agents on Claude: a shopping agent that customers use inside your app, and a merchant agent for the people running the store, whether that is the business's own operations staff or the sellers on its platform. It does that through Claude for commerce, an open-source blueprint with a working implementation of each agent on the [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages), the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview), and [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview), runnable examples for retail, travel, telecom, and entertainment, and a Claude Code plugin that scaffolds the same design against your own systems.
7This guide shows how to build commerce agents on Claude: a shopping agent that customers use inside your app, and a merchant agent for the people running the store, whether that is the business's own operations staff or the sellers on its platform. It does that through Claude for commerce, an open-source blueprint that includes the following:
8
9* A working implementation of each agent on the [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages), the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview), and [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)
10* Runnable examples for retail, travel, telecom, and entertainment
11* A Claude Code plugin that scaffolds the same design against your own systems
812
913The code, setup instructions, and safety documentation are in the [Claude for commerce repository on GitHub](https://github.com/anthropics/commerce-agents). For how the agents are built and why, including the single-agent-with-skills design, UI components as tools, harness-enforced safety, prompt caching, memory, and evals, read the engineering post [A guide to the anatomy of effective commerce agents](https://claude.com/blog/the-anatomy-of-effective-commerce-agents).
1014
about-claude/use-case-guides/ticket-routing Changed · +8 / -8 lines
from line 1058
10581058 DEFAULT_MODEL = "claude-haiku-5-5"
10591059
10601060
1061 def classify_support_request(request, actual_intent):
1061 def classify_support_request(ticket_contents, actual_intent):
10621062 # Define the prompt for the classification task
10631063 classification_prompt = f"""You will be acting as a customer support ticket classification system.
10641064 […]
from line 1101
11011101 const DEFAULT_MODEL = "claude-haiku-5-5";
11021102
11031103 async function classifySupportRequest(
1104 request: string,
1104 ticketContents: string,
11051105 actualIntent: string
11061106 ): Promise<{ reasoning: string; intent: string; correct: boolean; usage: Anthropic.Usage }> {
11071107 // Define the prompt for the classification task
from line 1147
11471147 // Set the default model
11481148 const Model DefaultModel = Model.ClaudeHaiku5_5;
11491149
1150 async Task<(string Reasoning, string Intent, bool Correct, Usage Usage)> ClassifySupportRequest(string request, string actualIntent)
1150 async Task<(string Reasoning, string Intent, bool Correct, Usage Usage)> ClassifySupportRequest(string ticketContents, string actualIntent)
11511151 {
11521152 // Define the prompt for the classification task
11531153 var classificationPrompt = """
from line 1205
12051205 // Set the default model
12061206 const defaultModel = anthropic.ModelClaudeHaiku5_5
12071207
1208 func classifySupportRequest(ctx context.Context, request, actualIntent string) (reasoning, intent string, correct bool, usage anthropic.Usage, err error) {
1208 func classifySupportRequest(ctx context.Context, ticketContents, actualIntent string) (reasoning, intent string, correct bool, usage anthropic.Usage, err error) {
12091209 // Define the prompt for the classification task
12101210 classificationPrompt := `You will be acting as a customer support ticket classification system.
12111211 […]
from line 1264
12641264
12651265 record Classification(String reasoning, String intent, boolean correct, Usage usage) {}
12661266
1267 Classification classifySupportRequest(String request, String actualIntent) {
1267 Classification classifySupportRequest(String ticketContents, String actualIntent) {
12681268 // Define the prompt for the classification task
12691269 String classificationPrompt = """
12701270 You will be acting as a customer support ticket classification system.
from line 1316
13161316 /**
13171317 * @return array{string, string, bool, Usage} the reasoning, the intent, whether the intent is correct, and the usage
13181318 */
1319 function classifySupportRequest(Client $client, string $request, string $actualIntent): array
1319 function classifySupportRequest(Client $client, string $ticketContents, string $actualIntent): array
13201320 {
13211321 // Define the prompt for the classification task
13221322 $classificationPrompt = <<<PROMPT
from line 1366
13661366 # Set the default model
13671367 DEFAULT_MODEL = Anthropic::Model::CLAUDE_HAIKU_5_5
13681368
1369 def classify_support_request(client, request, actual_intent)
1369 def classify_support_request(client, ticket_contents, actual_intent)
13701370 # Define the prompt for the classification task
13711371 classification_prompt = <<~PROMPT
13721372 You will be acting as a customer support ticket classification system.
from line 1411
14111411* **Accuracy:** 95% (out of 100 tests)
14121412* **Cost per classification:** 50% reduction on average (across 100 tests) from current routing method
14131413
1414Having these thresholds allows you to 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.
1414Having these thresholds allows you to tell at scale, and with impartial empiricism, what method is best for you and what changes you might need to make to better fit your requirements.
14151415
14161416***
14171417
agents-and-tools/agent-skills/enterprise Changed · +13 / -1 lines
from line 46
4646
4747### Skill content scanning
4848
49Claude Enterprise organizations can turn on automated security scanning for custom Skills in claude.ai and Claude Cowork. After you turn on **Skill and plugin security scanning** at [claude.ai > Organization settings > Skills](https://claude.ai/admin-settings/skills), Skills that members then upload or edit in claude.ai or Cowork are scanned for signs of malicious behavior, such as hidden code execution, sending your data to an outside service, or instructions that tamper with Claude's safeguards. A Skill that fails the scan, or whose scan hasn't completed, is blocked from use. An administrator can allow some Skills that failed the scan. A Skill that passes with a warning stays usable behind a caution notice. If scanning is available to your organization, turn it on. It complements, but doesn't replace, the [review checklist](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise#review-checklist).
49Claude Enterprise organizations can turn on automated security scanning for custom Skills in claude.ai and Claude Cowork. The setting is **Skill and plugin security scanning** at [claude.ai > Organization settings > Skills](https://claude.ai/admin-settings/skills).
50
51After you turn on the setting, scanning applies to Skills that members then upload or edit in claude.ai or Cowork. Each scan checks for signs of malicious behavior. These signs include hidden code execution, transfer of your data to an outside service, and instructions that tamper with Claude's safeguards.
52
53Whether a Skill is usable depends on its scan:
54
55* A Skill that fails the scan is blocked from use.
56* A Skill whose scan hasn't completed is blocked from use.
57* A Skill that passes with a warning stays usable behind a caution notice.
58
59Organization owners can allow some Skills that failed the scan. So can members whose [custom role](https://platform.claude.com/docs/en/manage-claude/user-management#custom-roles) can manage **Libraries**.
60
61If scanning is available to your organization, turn it on. Scanning complements, but doesn't replace, the [review checklist](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise#review-checklist).
5062
5163Scanning doesn't cover the Claude API. Skills you upload through the Skills API (`/v1/skills`), including from the Claude Console, aren't scanned, so for API deployments, rely on the review checklist and [version pinning](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise#versioning-strategy). Scanning also doesn't apply to Skills that were already in your organization when you turned it on, or to organizations with certain data handling configurations, such as customer-managed encryption keys (CMEK), zero data retention (ZDR), or HIPAA readiness. For setup steps, exclusions, and result types, see [Get started with skill and plugin scanning](https://support.claude.com/en/articles/15927065-get-started-with-skill-and-plugin-scanning) in the Claude Help Center.
5264
agents-and-tools/mcp-connector Changed · +3 / -3 lines
from line 498
498498
499499### MCP tool use block
500500
501```text wrap
501```json
502502{
503503 "type": "mcp_tool_use",
504504 "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
from line 510
510510
511511### MCP tool result block
512512
513```text wrap
513```json
514514{
515515 "type": "mcp_tool_result",
516516 "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
from line 530
530530
531531When the API asks an MCP server for its tools while producing a response, the response starts with an `mcp_tool_listing` block for that server, one block for each server it asked:
532532
533```text wrap
533```json
534534{
535535 "type": "mcp_tool_listing",
536536 "mcp_server_name": "example-mcp",
agents-and-tools/tool-use/advisor-tool Changed · +6 / -6 lines
from line 300
300300
301301When the advisor is called, a `server_tool_use` block is followed by an `advisor_tool_result` block in the assistant's content. The following example shows the plaintext `advisor_result` variant returned by a Claude Opus 4.8 advisor. The [Quick start](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#quick-start) uses Claude Opus 5.5, which returns the encrypted `advisor_redacted_result` variant instead; see [Result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants) for both shapes side by side.
302302
303```text
303```json
304304{
305305 "role": "assistant",
306306 "content": [
from line 349
349349
350350With `"model": "claude-opus-4-8"`, the advice is plaintext:
351351
352```text
352```json
353353{
354354 "type": "advisor_tool_result",
355355 "tool_use_id": "srvtoolu_abc123",
from line 362
362362
363363With `"model": "claude-opus-5-5"`, the advice is encrypted:
364364
365```text
365```json
366366{
367367 "type": "advisor_tool_result",
368368 "tool_use_id": "srvtoolu_abc123",
from line 383
383383
384384If the advisor call fails, the result carries an error:
385385
386```text wrap
386```json
387387{
388388 "type": "advisor_tool_result",
389389 "tool_use_id": "srvtoolu_abc123",
from line 1250
12501250
12511251Advisor calls run as a separate sub-inference billed at the advisor model's rates. Usage is reported in the `usage.iterations[]` array:
12521252
1253```text wrap
1253```json
12541254{
12551255 "usage": {
12561256 "input_tokens": 1760,
from line 1777
17771777
17781778When the advisor does hit the cap, the result block carries `stop_reason: "max_tokens"` on both [result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants), whichever advisor model you use. Use `stop_reason` to detect truncated advice and decide whether to raise the cap or let the executor proceed with partial guidance. The API also appends `[Advisor output truncated at max_tokens=2048.]` (naming your cap) to the advice text, so the executor receives the truncation notice in its own context; with a plaintext `advisor_result` advisor that marker is visible to your client as well. Both signals appear only when you set `max_tokens` on the tool definition.
17791779
1780```text
1780```json
17811781{
17821782 "type": "advisor_tool_result",
17831783 "tool_use_id": "srvtoolu_abc123",
agents-and-tools/tool-use/browser-use-tool Changed · +4 / -4 lines
from line 205
205205
206206Claude's first response ends with `stop_reason: "tool_use"` and carries one or more member `tool_use` blocks, each naming a member tool in `name` and carrying `"toolset_name": "browser"`:
207207
208```text Output
208```json Output
209209{
210210 "id": "msg_01HCDu4XSTLzTAcodEQ58vDo",
211211 "type": "message",
from line 1062
10621062
10631063A turn with several member calls is a batch action: run the calls in the order they appear, stop at the first failure, and answer every later call with `is_error: true` and the exact text `Not executed: an earlier action in this turn failed.` A batch uses the same response shape as [parallel tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use); the difference is that you run the blocks in order rather than concurrently. Here Claude clicks the search box it found earlier, types a query, and presses Enter in one turn:
10641064
1065```text wrap
1065```json
10661066{
10671067 "role": "assistant",
10681068 "content": [
from line 1139
11391139
11401140 1. Run the browser and your executor in a dedicated container or virtual machine with minimal privileges, a fresh profile that holds no credentials, and no access to sensitive filesystems or internal networks; isolate any tool you run alongside it the same way.
11411141 2. Restrict the hosts the browser can reach to a domain allowlist enforced at the network layer and re-checked in your `navigate` handler after redirects, and block loopback, link-local, and private ranges unless the task needs them.
1142 3. Treat everything a page supplies as untrusted input, including the tab titles and URLs, and each download's `url`, `path`, and `error`, that you report in a [`browser_state`](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state) block, and build page reads from what the page renders (the accessibility tree or visible text), not raw DOM source, so hidden text doesn't reach Claude.
1142 3. Treat everything a page supplies as untrusted input. That includes the tab titles and URLs, and each download's `url`, `path`, and `error`, that you report in a [`browser_state`](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state) block. Build page reads from what the page renders (the accessibility tree or visible text), not raw DOM source, so hidden text doesn't reach Claude.
11431143 4. In your `navigate` handler, accept the history keywords `"back"`, `"forward"`, and `"reload"`, treat a URL without a scheme as `https://`, then parse the URL and refuse any scheme other than `http` or `https` (`javascript:`, `file:`, `data:`, `chrome:`, and so on) with an [error result](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor). Check the scheme with a URL parser rather than a string prefix; the API doesn't filter the URLs Claude opens, so it can't reject one for you.
11441144 5. Leave `javascript_exec` and `file_upload` disabled unless you need them, and read [Enable optional members](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools) before turning either on.
11451145 6. Have a human confirm consequential actions and anything that requires affirmative consent (purchasing, modifying accounts, messaging, and accepting terms), and make that check in your executor before each call, because one turn can carry several.
from line 1271
12711271* `paths` are file paths on the executor's filesystem, for deployments where the executor can read your application's files directly (the same condition under which you populate a download's `path`).
12721272* `document_ids` are identifiers for files your application has staged for the browser, for deployments where it can't. Your application defines what the identifiers mean; scope their resolution the way you scope `paths`, to files staged for this task.
12731273
1274```text wrap
1274```json
12751275{
12761276 "type": "tool_use",
12771277 "id": "toolu_01N7gVzFEfZjLjgsYwnrPgrF",
agents-and-tools/tool-use/code-execution-tool Changed · +13 / -13 lines
from line 938
938938
939939### Bash command response
940940
941```text Output
941```json Output
942942{
943943 "type": "server_tool_use",
944944 "id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
from line 964
964964
965965**View file:**
966966
967```text Output wrap
967```json Output
968968{
969969 "type": "server_tool_use",
970970 "id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
from line 990
990990
991991**Create file:**
992992
993```text Output wrap
993```json Output
994994{
995995 "type": "server_tool_use",
996996 "id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
from line 1013
10131013
10141014**Edit file (str\_replace):**
10151015
1016```text Output wrap
1016```json Output
10171017{
10181018 "type": "server_tool_use",
10191019 "id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
from line 1060
10601060
10611061**Common errors (all tools):**
10621062
1063```text Output wrap
1063```json Output
10641064{
10651065 "type": "bash_code_execution_tool_result",
10661066 "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
from line 1100
11001100
11011101### Resource limits
11021102
1103* **Memory:** 5 GiB RAM
1104* **Disk space:** 5 GiB workspace storage
1105* **CPU:** 1 CPU
1106* **Execution time:** A tool call that runs past the maximum execution time returns an `execution_time_exceeded` [error](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#errors). With [programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling), each REPL cell also has a 90-second wall-clock limit
1103* **Memory:** The container has 5 GiB of RAM.
1104* **Disk space:** The container has 5 GiB of workspace storage.
1105* **CPU:** The container has 1 CPU.
1106* **Execution time:** A tool call that runs past the maximum execution time returns an `execution_time_exceeded` [error](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#errors). With [programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling), each REPL cell also has a 90-second wall-clock limit.
11071107
11081108### Networking and security
11091109
from line 1111
11111111* **External connections:** No outbound network requests allowed
11121112* **Sandbox isolation:** Full isolation from host system and other containers
11131113* **File access:** Limited to workspace directory only
1114* **Workspace scoping:** Like the [Files API](https://platform.claude.com/docs/en/build-with-claude/files), containers are scoped to the request's workspace
1115* **Expiration:** Containers expire 30 days after creation
1114* **Workspace scoping:** Scoped to the request's workspace, like the [Files API](https://platform.claude.com/docs/en/build-with-claude/files)
1115* **Expiration:** 30 days after creation
11161116
11171117### Pre-installed libraries
11181118
from line 1443
14431443
14441444With [streaming](https://platform.claude.com/docs/en/build-with-claude/streaming) enabled (`"stream": true`), you'll receive code execution events as they occur. The sub-tool input streams as `input_json_delta` events, and each result block arrives whole in a single `content_block_start` event:
14451445
1446```text
1446```sse
14471447event: content_block_start
14481448data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "bash_code_execution"}}
14491449
from line 1475
14751475
14761476Code execution usage is tracked in the response:
14771477
1478```text wrap
1478```json
14791479{
14801480 "usage": {
14811481 "input_tokens": 105,
agents-and-tools/tool-use/computer-use-tool Changed · +10 / -10 lines
from line 277
277277
278278When Claude acts on the desktop, the response has a `stop_reason` of `tool_use` and contains one or more member `tool_use` blocks, each naming a member tool and carrying `"toolset_name": "computer"`. Partway through this task, after Claude has received a screenshot of the desktop, a response might look like this:
279279
280```text Output wrap
280```json Output
281281{
282282 "id": "msg_01UZ3bXcQH8mTqNhVfL9eK2p",
283283 "type": "message",
from line 347
347347
348348A response with a three-action batch looks like this:
349349
350```text wrap
350```json
351351{
352352 "role": "assistant",
353353 "content": [
from line 761
761761
762762 Shift+click at a position, for example, to extend a selection. Unlike `hold_key`, `text` holds the modifiers only for the duration of that click or scroll:
763763
764 ```text wrap
764 ```json
765765 {
766766 "type": "tool_use",
767767 "id": "toolu_01Qg8m3XqC5aRy7tD2eS4jUg",
from line 773
773773
774774 Drag from one point to another:
775775
776 ```text wrap
776 ```json
777777 {
778778 "type": "tool_use",
779779 "id": "toolu_01Ed6j9VnA3yPw5rB8cQ2gSe",
from line 788
788788
789789 Scroll down three clicks of the wheel:
790790
791 ```text wrap
791 ```json
792792 {
793793 "type": "tool_use",
794794 "id": "toolu_01Yc5h8UmZ2xNv4qA7bP9fRd",
from line 804
804804
805805 Press Tab four times:
806806
807 ```text wrap
807 ```json
808808 {
809809 "type": "tool_use",
810810 "id": "toolu_01Sb4g7TkY9wLu3pX6zM8eQc",
from line 816
816816
817817 Zoom in to inspect a region at full resolution:
818818
819 ```text wrap
819 ```json
820820 {
821821 "type": "tool_use",
822822 "id": "toolu_01Kf7k2WpB4zQx6sC9dR3hTf",
from line 828
828828
829829 Report the cursor position. Answer this call with a short text result that gives the position in screenshot pixels, for example, `X=512, Y=384`:
830830
831 ```text wrap
831 ```json
832832 {
833833 "type": "tool_use",
834834 "id": "toolu_01Ekh3vqB6yTs2mNc4Rw8pLd",
from line 887
887887
888888To add other tools alongside computer use, include them in the same `tools` array. The [Quick start](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#quick-start) section shows this pattern with the [bash tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool) and [text editor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool). You can add your own [custom tool definitions](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools) the same way.
889889
890For tasks that stay inside webpages, you can also [declare the browser use tool in the same request](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool#combine-with-other-tools): the two toolsets work independently, each in its own coordinate frame, and calls to members that share a name, such as `screenshot` or `key`, are told apart by `toolset_name`.
890For tasks that stay inside webpages, you can also [declare the browser use tool in the same request](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool#combine-with-other-tools). The two toolsets work independently, each in its own coordinate frame. The `toolset_name` value distinguishes calls to members that share a name, such as `screenshot` or `key`.
891891
892892### Build a custom computer use environment
893893
from line 1859
18591859 ```typescript TypeScript
18601860 async function clickAndWait(x: number, y: number, waitMs = 500): Promise<void> {
18611861 clickAt(x, y);
1862 await setTimeout(waitMs); // Allow UI to update
1862 await new Promise((resolve) => setTimeout(resolve, waitMs)); // Allow UI to update
18631863 }
18641864 ```
18651865
agents-and-tools/tool-use/programmatic-tool-calling Changed · +9 / -9 lines
from line 368
368368
369369When you configure a tool to be callable from code execution and Claude determines that tool is needed:
370370
3711. Claude writes Python code that calls the tool as a function. The code can include multiple tool calls and pre/post-processing logic.
3711. Claude writes Python code that calls the tool as a function. The code can include multiple tool calls, plus preprocessing and post-processing logic.
3723722. Claude runs this code in a sandboxed container through code execution.
3733733. When a tool function is called, code execution pauses and the API returns a `tool_use` block.
3743744. You provide the tool result, and code execution continues (intermediate results are not loaded into Claude's context window).
from line 423
423423
424424**Direct call (traditional tool use):**
425425
426```text wrap
426```json
427427{
428428 "type": "tool_use",
429429 "id": "toolu_abc123",
from line 435
435435
436436**Programmatic call:**
437437
438```text wrap
438```json
439439{
440440 "type": "tool_use",
441441 "id": "toolu_xyz789",
from line 481
481481
482482Claude writes code that calls your tool. The API pauses and returns:
483483
484```text Output
484```json Output
485485{
486486 "role": "assistant",
487487 "content": [
from line 1143
11431143
11441144### Step 4: Next tool call or completion
11451145
1146The code picks up where it paused and processes your result. Each continuation response either pauses again with more programmatic `tool_use` blocks, or completes the code execution and lets Claude continue the turn (Step 5). Check `stop_reason` and each `tool_use` block's `caller` to tell the two apart: a response that pauses for you has `stop_reason: "tool_use"` and a `tool_use` block whose `caller` names a code execution version, and you repeat Step 3 with a `tool_result` for every pending programmatic call in one user message.
1146The code picks up where it paused and processes your result. Each continuation response either pauses again with more programmatic `tool_use` blocks, or completes the code execution and lets Claude continue the turn (Step 5). Check `stop_reason` and each `tool_use` block's `caller` to tell the two apart. A response that pauses for you has `stop_reason: "tool_use"` and a `tool_use` block whose `caller` names a code execution version. In that case, repeat Step 3 with a `tool_result` for every pending programmatic call in one user message.
11471147
11481148### Step 5: Final response
11491149
11501150Once the code execution completes, Claude provides the final response:
11511151
1152```text Output
1152```json Output
11531153{
11541154 "content": [
11551155 {
from line 1238
12381238
12391239When code execution calls a tool:
12401240
1241```text wrap
1241```json
12421242{
12431243 "type": "tool_use",
12441244 "id": "toolu_abc123",
from line 1272
12721272
12731273When all tool calls are satisfied and code completes:
12741274
1275```text
1275```json
12761276{
12771277 "type": "code_execution_tool_result",
12781278 "tool_use_id": "srvtoolu_xyz789",
from line 1299
12991299
13001300If your tool result doesn't arrive within about 4 minutes, the pending call raises a `TimeoutError` inside Claude's running code. Claude receives the error in `stderr` and typically retries the call:
13011301
1302```text
1302```json
13031303{
13041304 "type": "code_execution_tool_result",
13051305 "tool_use_id": "srvtoolu_abc123",
agents-and-tools/tool-use/server-tools Changed · +4 / -4 lines
from line 10
1010
1111The `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:
1212
13```text wrap
13```json
1414{
1515 "type": "server_tool_use",
1616 "id": "srvtoolu_01A2B3C4D5E6F7G8H9",
from line 408
408408 With [programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling), the same response shape means something different. The client `tool_use` block comes from code that is running in the `code_execution` tool rather than from Claude directly, and its `caller` field names the `code_execution` block that called it. That code has already started: it is paused waiting for your `tool_result` blocks, and sending them resumes the execution instead of starting a deferred tool. The `code_execution` block's own result block arrives once the code completes, which can take more than one round of tool results. The follow-up user message itself is the same in both cases; with programmatic tool calling, also pass back the `id` from the response's `container` field, as that page shows.
409409</Note>
410410
411```text wrap
411```json
412412{
413413 "stop_reason": "tool_use",
414414 "content": [
from line 449
449449
450450The API attaches your results to the still-open assistant turn, runs the deferred server tool (for paused code execution, resumes it), and then lets Claude continue. For a server tool Claude called directly, the next response starts with the result block that answers the previous response's `server_tool_use` `id`, followed by the newly generated content and a fresh `stop_reason`:
451451
452```text wrap
452```json
453453{
454454 "stop_reason": "end_turn",
455455 "content": [
from line 1010
10101010 ```
10111011</CodeGroup>
10121012
1013This code is also correct when Claude does not mix the two kinds of call. A turn with only client `tool_use` blocks takes the same continuation path, and a turn with only server tool calls needs no client `tool_result` blocks from you: its result blocks are normally already present, and one that comes back suspended, such as a [`pause_turn` response](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn), is re-sent as-is instead.
1013This code is also correct when Claude does not mix the two kinds of call. A turn with only client `tool_use` blocks takes the same continuation path. A turn with only server tool calls needs no client `tool_result` blocks from you, because its result blocks are normally already present. If that turn comes back suspended, for example as a [`pause_turn` response](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn), re-send it as-is instead.
10141014
10151015## ZDR and allowed\_callers
10161016
agents-and-tools/tool-use/text-editor-tool Changed · +8 / -8 lines
from line 274
274274<Accordion title="Example view commands">
275275 Example for viewing a file:
276276
277 ```text wrap
277 ```json
278278 {
279279 "type": "tool_use",
280280 "id": "toolu_01A09q90qw90lq917835lq9",
from line 288
288288
289289 Example for viewing a directory:
290290
291 ```text wrap
291 ```json
292292 {
293293 "type": "tool_use",
294294 "id": "toolu_02B19r91rw91mr917835mr9",
from line 313
313313* `new_str`: The new text to insert in place of the old text
314314
315315<Accordion title="Example str_replace command">
316 ```text wrap
316 ```json
317317 {
318318 "type": "tool_use",
319319 "id": "toolu_01A09q90qw90lq917835lq9",
from line 339
339339* `file_text`: The content to write to the new file
340340
341341<Accordion title="Example create command">
342 ```text
342 ```json
343343 {
344344 "type": "tool_use",
345345 "id": "toolu_01A09q90qw90lq917835lq9",
from line 365
365365* `insert_text`: The text to insert
366366
367367<Accordion title="Example insert command">
368 ```text
368 ```json
369369 {
370370 "type": "tool_use",
371371 "id": "toolu_01A09q90qw90lq917835lq9",
from line 560
560560
561561Claude uses the text editor tool first to view the file:
562562
563```text Output
563```json Output
564564{
565565 "id": "msg_01XAbCDeFgHiJkLmNoPQrStU",
566566 "model": "claude-opus-5-5",
from line 1021
10211021
10221022Claude identifies the syntax error and uses the `str_replace` command to fix it:
10231023
1024```text Output
1024```json Output
10251025{
10261026 "id": "msg_01VwXyZAbCdEfGhIjKlMnO",
10271027 "model": "claude-opus-5-5",
from line 1461
14611461
14621462Finally, Claude provides a complete explanation of the fix:
14631463
1464````text Output
1464````json Output
14651465{
14661466 "id": "msg_01IjKlMnOpQrStUvWxYzAb",
14671467 "model": "claude-opus-5-5",
agents-and-tools/tool-use/tool-search-tool Changed · +5 / -5 lines
from line 604
604604
605605When Claude uses the tool search tool, the response includes the following block types:
606606
607```text JSON
607```json JSON
608608{
609609 "role": "assistant",
610610 "content": [
from line 693
693693
694694**All tools deferred:**
695695
696```text
696```json
697697{
698698 "type": "error",
699699 "error": {
from line 705
705705
706706**Missing tool definition:**
707707
708```text wrap
708```json
709709{
710710 "type": "error",
711711 "error": {
from line 719
719719
720720When a tool search operation fails during execution, the API returns a 200 response with the error in the body:
721721
722```text JSON
722```json JSON
723723{
724724 "type": "tool_search_tool_result",
725725 "tool_use_id": "srvtoolu_01ABC123",
from line 793
793793
794794With streaming enabled, you'll receive tool search events as part of the stream:
795795
796```text
796```sse
797797event: content_block_start
798798data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "tool_search_tool_regex"}}
799799
agents-and-tools/tool-use/web-fetch-tool Changed · +6 / -6 lines
from line 426
426426 "type": "web_fetch_20250910",
427427 "name": "web_fetch",
428428
429 // Optional: Limit the number of fetches per request
429 // Optional: Limit the number of fetches for each request
430430 "max_uses": 10,
431431
432432 // Optional: Only fetch from these domains
from line 524
524524
525525Here's an example response structure:
526526
527```text Output
527```json Output
528528{
529529 "role": "assistant",
530530 "content": [
from line 608
608608
609609For PDF documents, content is returned as base64-encoded data:
610610
611```text Output wrap
611```json Output
612612{
613613 "type": "web_fetch_tool_result",
614614 "tool_use_id": "srvtoolu_02",
from line 633
633633
634634When the web fetch tool encounters an error, the Claude API returns a 200 (success) response with the error represented in the response body. Claude receives the error result and continues the turn. For example:
635635
636```text Output wrap
636```json Output
637637{
638638 "type": "web_fetch_tool_result",
639639 "tool_use_id": "srvtoolu_a93jad",
from line 962
962962
963963With streaming enabled, fetch events are part of the stream with a pause during content retrieval:
964964
965```text Output
965```sse Output
966966event: message_start
967967data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}}
968968
from line 995
995995
996996Web fetch usage has **no additional charges** beyond standard token costs:
997997
998```text wrap
998```json
999999{
10001000 "usage": {
10011001 "input_tokens": 25039,
agents-and-tools/tool-use/web-search-tool Changed · +5 / -5 lines
from line 415
415415 "type": "web_search_20250305",
416416 "name": "web_search",
417417
418 // Optional: Limit the number of searches per request
418 // Optional: Limit the number of searches for each request
419419 "max_uses": 5,
420420
421421 // Optional: Only include results from these domains.
from line 488
488488
489489Here's an example response structure:
490490
491```text Output
491```json Output
492492{
493493 "role": "assistant",
494494 "content": [
from line 583
583583
584584When 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:
585585
586```text Output wrap
586```json Output
587587{
588588 "type": "web_search_tool_result",
589589 "tool_use_id": "srvtoolu_a93jad",
from line 621
621621
622622With streaming enabled, you'll receive search events as part of the stream. There is a pause while the search runs:
623623
624```text Output
624```sse Output
625625event: message_start
626626data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}}
627627
from line 656
656656
657657Web search usage is charged in addition to token usage:
658658
659```text wrap
659```json
660660{
661661 "usage": {
662662 "input_tokens": 105,
api/errors Changed · +3 / -3 lines
from line 57
5757
5858The API always returns errors as JSON, with a top-level `error` object that always includes a `type` and `message` value. The response also includes a `request_id` field for easier tracking and debugging. For example:
5959
60```text JSON wrap
60```json JSON
6161{
6262 "type": "error",
6363 "error": {
from line 430
430430
431431Claude 4.6 and later models and [Claude Mythos Preview](https://anthropic.com/glasswing) do not support prefilling assistant messages. Sending a request with a prefilled last assistant message to any of these models returns a 400 `invalid_request_error`:
432432
433```text
433```json
434434{
435435 "type": "error",
436436 "error": {
from line 450
450450`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified. These blocks must remain as they were in the original response.
451451```
452452
453With tool use, every `thinking` and `redacted_thinking` block from the assistant turn must be passed back exactly as received, including blocks whose `thinking` field is empty. Pass thinking blocks back unchanged, and if your application filters content blocks by type before resending, include both `thinking` and `redacted_thinking`. See the [fix for modified thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-blocks-modified) in Troubleshooting thinking, and also [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks) and [Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-thinking).
453With tool use, pass back every `thinking` and `redacted_thinking` block from the assistant turn exactly as received, including blocks whose `thinking` field is empty. If your application filters content blocks by type before resending, include both `thinking` and `redacted_thinking`. See the [fix for modified thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-blocks-modified) in Troubleshooting thinking, and also [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks) and [Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-thinking).
454454
455455### Extended thinking not supported
456456
api/opentelemetry/spans Changed · +12 / -12 lines
from line 439
439439
440440Every SDK span for a request, including [`anthropic.messages.create`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-create), [`anthropic.messages.count_tokens`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-count-tokens), and [`anthropic.messages.batches.<method>`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-batches-method), has the following attributes:
441441
442| Attribute | Type | Description |
443| --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
444| `gen_ai.conversation.id` | `string` | The conversation ID passed with the [`conversation_id` (typescript, java, php: `conversationId`; csharp: `ConversationId`; go: `option.WithOpenTelemetryConversationID()`) option](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk#configure-the-sdk). Without one, the session thread ID on requests to one session thread, and on the request in which the session tool runner sends a tool's result. Absent on other requests. |
445| `anthropic.<resource>.id` | `string` | One attribute for each ID in the request's path and one for the ID of an object that the method creates. The name comes from the path, in the singular, for example `anthropic.session.id` or `anthropic.session.thread.id`. |
446| `gen_ai.agent.id` | `string` | The agent ID, on the agent methods. |
447| `gen_ai.memory.store.id` | `string` | The memory store ID, on the memory store methods. |
448| `gen_ai.memory.record.id` | `string` | The memory ID, on the memory methods. |
449| `http.request.resend_count` | `int` | The number of times that the SDK resent the request, for any reason, such as a retry. Absent when the SDK didn't resend it. |
450| `error.type` | `string` | A failed call's [error type](https://platform.claude.com/docs/en/api/errors#http-errors), for example `rate_limit_error`. The HTTP status code, for example `502`, when the error response doesn't have an error type. `connection_error`, `client_timeout_error`, or `client_error` when the call failed in the SDK. `api_error` when the server ended a stream early. |
451| `server.address` | `string` | The host of the client's base URL, `api.anthropic.com` by default. On a cloud platform's client, that platform's host. |
452| `url.query` | `string` | The URL's query string, with only the query parameters that the endpoint defines. Absent when there are none. In metadata-only mode, absent when the query has a sensitive parameter, such as `email`. |
453| `url.full` | `string` | The URL, made of `url.scheme`, `server.address`, the port when the base URL has one, `url.path`, and `url.query`. In metadata-only mode, absent whenever that mode leaves out `url.query`. |
442| Attribute | Type | Description |
443| --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
444| `gen_ai.conversation.id` | `string` | The conversation ID passed with the [`conversation_id` (typescript, java, php: `conversationId`; csharp: `ConversationId`; go: `option.WithOpenTelemetryConversationID()`) option](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk#configure-the-sdk). Without one, the ID of the session thread that the span belongs to, as in [Session attributes](https://platform.claude.com/docs/en/api/opentelemetry/spans#session-attributes), and absent on spans with no thread. |
445| `anthropic.<resource>.id` | `string` | One attribute for each ID in the request's path and one for the ID of an object that the method creates. The name comes from the path, in the singular, for example `anthropic.session.id` or `anthropic.session.thread.id`. |
446| `gen_ai.agent.id` | `string` | The agent ID, on the agent methods. |
447| `gen_ai.memory.store.id` | `string` | The memory store ID, on the memory store methods. |
448| `gen_ai.memory.record.id` | `string` | The memory ID, on the memory methods. |
449| `http.request.resend_count` | `int` | The number of times that the SDK resent the request, for any reason, such as a retry. Absent when the SDK didn't resend it. |
450| `error.type` | `string` | A failed call's [error type](https://platform.claude.com/docs/en/api/errors#http-errors), for example `rate_limit_error`. The HTTP status code, for example `502`, when the error response doesn't have an error type. `connection_error`, `client_timeout_error`, or `client_error` when the call failed in the SDK. `api_error` when the server ended a stream early. |
451| `server.address` | `string` | The host of the client's base URL, `api.anthropic.com` by default. On a cloud platform's client, that platform's host. |
452| `url.query` | `string` | The URL's query string, with only the query parameters that the endpoint defines. Absent when there are none. In metadata-only mode, absent when the query has a sensitive parameter, such as `email`. |
453| `url.full` | `string` | The URL, made of `url.scheme`, `server.address`, the port when the base URL has one, `url.path`, and `url.query`. In metadata-only mode, absent whenever that mode leaves out `url.query`. |
454454
build-with-claude/batch-processing Changed · +3 / -3 lines
from line 421
421421
422422When a batch is first created, the response has a processing status of `in_progress`.
423423
424```text Output wrap
424```json Output
425425{
426426 "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
427427 "type": "message_batch",
from line 918
918918
919919The 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:
920920
921```text .jsonl file
921```jsonl .jsonl file
922922{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-5-5","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}}}}
923923{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-opus-5-5","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}}}}
924924```
from line 1017
10171017
10181018The response shows the batch in a `canceling` state:
10191019
1020```text Output wrap
1020```json Output
10211021{
10221022 "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
10231023 "type": "message_batch",
build-with-claude/citations Changed · +5 / -5 lines
from line 982
982982</Tabs>
983983
984984<Accordion title="Example plain text citation">
985 ```text
985 ```json
986986 {
987987 "type": "char_location",
988988 "cited_text": "The exact text being cited", // not counted toward output tokens
from line 1810
18101810</Tabs>
18111811
18121812<Accordion title="Example PDF citation">
1813 ```text
1813 ```json
18141814 {
18151815 "type": "page_location",
18161816 "cited_text": "The exact text being cited", // not counted toward output tokens
from line 2137
21372137</CodeGroup>
21382138
21392139<Accordion title="Example citation">
2140 ```text
2140 ```json
21412141 {
21422142 "type": "content_block_location",
21432143 "cited_text": "The exact text being cited", // not counted toward output tokens
from line 2155
21552155
21562156When citations are enabled, responses include multiple text blocks with citations:
21572157
2158```text wrap
2158```json
21592159{
21602160 "content": [
21612161 { "type": "text", "text": "According to the document, " },
from line 2234
22342234
22352235<AccordionGroup>
22362236 <Accordion title="Example streaming events">
2237 ```text
2237 ```sse
22382238 event: message_start
22392239 data: {"type": "message_start", ...}
22402240
build-with-claude/claude-models-on-google-cloud/anthropic-managed Changed · +8 / -8 lines
from line 504
504504
505505* **Fast mode:** [Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) for Claude Opus 5.5.
506506
507- **Beta features:** If a beta is limited to selected organizations on the Claude API, the Anthropic organization that setup creates needs the same access.
507* **Beta features:** If a beta is limited to selected organizations on the Claude API, the Anthropic organization that setup creates needs the same access.
508508
509- **Tools:** [Tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview), including:
509* **Tools:** [Tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview), including:
510510
511511 * Web search
512512 * Web fetch
from line 515
515515 * The advisor tool
516516 * The MCP connector
517517
518- **Skills and files:** [Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) and the [Files API](https://platform.claude.com/docs/en/build-with-claude/files).
518* **Skills and files:** [Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) and the [Files API](https://platform.claude.com/docs/en/build-with-claude/files).
519519
520- **Model capabilities:**
520* **Model capabilities:**
521521
522522 * [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
523523 * [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/thinking)
from line 526
526526 * [Structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
527527 * [Token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting)
528528
529- **Batches and models:** The [Message Batches API](https://platform.claude.com/docs/en/build-with-claude/batch-processing) and the Models API.
529* **Batches and models:** The [Message Batches API](https://platform.claude.com/docs/en/build-with-claude/batch-processing) and the Models API.
530530
531531To turn the [Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api) on or off for the Anthropic organization that setup creates, [open the Claude Console](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#using-the-claude-console), go to **Settings > Compliance**, and use the **Compliance API** toggle.
532532
533Customer-managed encryption keys (CMEK) are available with Google Cloud KMS keys. To activate CMEK for the Anthropic organization that setup creates, see [Customer-managed encryption keys](https://platform.claude.com/docs/en/manage-claude/cmek). To set up a key, follow [Configure Google Cloud KMS for CMEK](https://platform.claude.com/docs/en/manage-claude/cmek-google-cloud-kms). Then register, verify, and attach the key in the [Claude Console](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#using-the-claude-console), as the setup page's **Claude Console** tab describes.
533Customer-managed encryption keys (CMEK) are available with Google Cloud KMS keys. To activate CMEK for the Anthropic organization that setup creates, see [Who can use CMEK](https://platform.claude.com/docs/en/manage-claude/cmek#availability). To set up a key, follow [Set up CMEK with Google Cloud KMS](https://platform.claude.com/docs/en/manage-claude/cmek-google-cloud-kms). Then register, verify, and attach the key in the [Claude Console](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed#using-the-claude-console), as the setup page's **Claude Platform** tab describes.
534534
535535### Claude Managed Agents
536536
build-with-claude/context-editing Changed · +5 / -5 lines
from line 1334
13341334You can use both thinking block clearing and tool result clearing together:
13351335
13361336<Note>
1337 When using multiple strategies, the `clear_thinking_20251015` strategy must be listed first in the `edits` array.
1337 When using multiple strategies, you must list the `clear_thinking_20251015` strategy first in the `edits` array.
13381338</Note>
13391339
13401340<CodeGroup>
from line 1735
17351735
17361736You 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.
17371737
1738```text Output wrap
1738```json Output
17391739{
17401740 "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
17411741 "type": "message",
from line 1767
17671767
17681768For streaming responses, the context edits are included in the final `message_delta` event:
17691769
1770```text Streaming Response wrap
1770```json Streaming Response
17711771{
17721772 "type": "message_delta",
17731773 "delta": {
from line 2069
20692069 ```
20702070</CodeGroup>
20712071
2072```text Output wrap
2072```json Output
20732073{
20742074 "input_tokens": 25000,
20752075 "context_management": {
from line 2798
27982798
27992799For example, after a web search operation, the API response might show:
28002800
2801```text Output wrap
2801```json Output
28022802{
28032803 "usage": {
28042804 "input_tokens": 63000,
build-with-claude/preserved-thinking Changed · +4 / -4 lines
from line 53
5353
5454With the `thinking-binding-controls-2026-08-01` [beta header](https://platform.claude.com/docs/en/api/beta-headers), the response lists each dropped block in a top-level `input_transformations` array with `reason: "model_binding_mismatch"`:
5555
56```text wrap
56```json
5757{
5858 "input_transformations": [
5959 {
from line 716
716716
717717Log `input_transformations` on every turn of your own integration. When the API drops a block, the entry looks like the following:
718718
719```text wrap
719```json
720720{
721721 "input_transformations": [
722722 {
from line 746
746746
747747On an older account, you can also watch production traffic without opting into enforcement: send the beta header, leave `block_binding` out, and log `input_transformations`. Sending the header alone doesn't change what the model receives. Every thinking block that comes after the content you edited fails the check and gets its own `thinking_mismatch_allowed` entry, with the same `path` and `reason` fields as a `thinking_dropped` entry. Blocks before the edit still pass. An edit to `system` or `tools` comes before every block, so it fails every thinking block in the request. One entry looks like this:
748748
749```text wrap
749```json
750750{
751751 "input_transformations": [
752752 {
from line 1475
14751475
14761476The response carries the new assistant turn as usual, plus one `input_transformations` entry for each dropped block. For the history in the diagram, that's the thinking on assistant turns 3 and 4:
14771477
1478```text wrap
1478```json
14791479{
14801480 "input_transformations": [
14811481 {
build-with-claude/prompt-engineering/prompting-claude-opus-5-5 Changed · +3 / -3 lines
from line 50
5050Claude Opus 5 accepts `thinking: {"type": "disabled"}` at `high` effort or below; Claude Opus 5.5 doesn't, and the [migration guide](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-5) covers the request change. If your Claude Opus 5 integration ran with thinking disabled, four changes go with it:
5151
5252* **Start at `low` effort and measure.** At `low` the model keeps its thinking short. How often it skips thinking altogether depends on your prompts, so measure latency and quality on your own traffic and move to `medium` if quality drops. If time to first token still matters after that, a system prompt line such as "Answer directly without deliberating." can reduce thinking further; measure quality when you add it, because less thinking can lower it.
53* **Remove instructions that stood in for thinking.** If your prompt asked the model to write its reasoning in the response as a substitute for thinking, remove that instruction and read the reasoning from [summarized thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#summarized-thinking) blocks instead (`display: "summarized"`); a prompt that pushes the model to reproduce its reasoning in the response text might be declined with the `reasoning_extraction` [refusal category](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response).
53* **Remove instructions that stood in for thinking.** If your prompt asked the model to write its reasoning in the response as a substitute for thinking, remove that instruction. Read the reasoning from [summarized thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#summarized-thinking) blocks instead (`display: "summarized"`). A prompt that pushes the model to reproduce its reasoning in the response text might be declined with the `reasoning_extraction` [refusal category](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response).
5454* **Re-test the thinking-disabled mitigations.** [Running with thinking disabled](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#running-with-thinking-disabled) recommends a combined instruction (permission to speak before a tool call, what to do when no tool fits, no internal tags) and removing any rule that tells the model not to think. Both address artifacts that appear on Claude Opus 5 only when thinking is disabled. With thinking always on, check whether you still need the instruction, and remove the no-thinking rule either way.
5555* **Read the response by block type.** Check each block's type instead of assuming the first content block is text: a response might or might not start with a `thinking` block, whose `thinking` field is empty under the default `display: "omitted"`.
5656
from line 68
6868
6969A system prompt addition can also make these early stops less frequent. Claude Opus 5.5 is responsive to instructions that name the specific kinds of early stop you want it to avoid, such as ending the turn with a summary that announces the next step instead of taking it. It also helps to name the stops you do want, for example when no work can advance without the user's input.
7070
71The following paragraph is one example of such an addition, written for agents that run fully unattended, where you want the model to keep working rather than stop to report. Treat it as a starting point: you might need to adapt it for your own application. Add it at the end of your system prompt from the first request of the session: adding it partway through changes the `system` prompt and invalidates the conversation's earlier thinking blocks (see [Add instructions with a mid-conversation system message](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#new-instructions)). Because it tells the model to put status notes in the same message as its next tool call, those notes arrive between tool calls as progress updates, whose text comes back empty at the default `thinking.display`; set `display: "updates"` to receive a summary of each (see [User-facing progress updates](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#user-facing-progress-updates)). With this addition the model carries on where it would otherwise have stopped to check in, so keep your own confirmation step for risky or irreversible actions, and leave the addition out of human-in-the-loop applications, where someone is there to answer. Expect somewhat more tool calls and output tokens per task.
71The following paragraph is one example of such an addition, written for agents that run fully unattended, where you want the model to keep working rather than stop to report. Treat it as a starting point: you might need to adapt it for your own application. Add it at the end of your system prompt from the first request of the session: adding it partway through changes the `system` prompt and invalidates the conversation's earlier thinking blocks (see [Add instructions with a mid-conversation system message](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#new-instructions)). Because it tells the model to put status notes in the same message as its next tool call, those notes arrive between tool calls as progress updates. The text of these updates comes back empty at the default `thinking.display`. Set `display: "updates"` to receive a summary of each (see [User-facing progress updates](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#user-facing-progress-updates)). With this addition the model carries on where it would otherwise have stopped to check in, so keep your own confirmation step for risky or irreversible actions, and leave the addition out of human-in-the-loop applications, where someone is there to answer. Expect somewhat more tool calls and output tokens per task.
7272
7373```text wrap
7474A standing instruction from the user, the person you are working for. It is about how your turns end. A message with no tool call in it ends your turn, and the work stops there until you are asked to continue. The user has seen you end turns in four ways while work they asked for was still owed, and does not want any of them. One: a long summary of what was done that closes by announcing the next step and has no tool call, so the next thing never starts. Two: an offer to carry on with something unless the user would prefer otherwise, which stops to wait for an answer the user was not going to give. Three: a list of decisions for the user when, by your own account, none of them blocks the rest of the work. Four: deciding that this is a good place to report, because the turn has been long or a milestone is done. Status notes are welcome, and so are your recommendations on open decisions, but put them in the same message as your next tool call and carry on with whatever does not depend on the user's answer. If you notice yourself inviting the user to redirect you or offering to wait, delete it and do the next thing. The stops the user does want are the ones where nothing can move without them, or where the thing blocking you is deliberately protected from you. This does not override the need for confirmation on risky or destructive actions.
from line 88
8888
8989Between tool calls, Claude Opus 5.5 writes short user-facing progress updates: what it just found and what it's doing next. Four levers control what your users see.
9090
91First, check that your client receives them: on Claude Opus 5.5 these notes come back as [progress-update `thinking` blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates) rather than `text` blocks, and their text is empty at the default `thinking.display`, so a client that renders only `text` blocks can look silent during a long agentic turn. Set `display: "updates"` (beta, `thinking-display-updates-2026-08-18` header) to receive a short summary of each note; see [Text between tool calls is returned in thinking blocks](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#text-between-tool-calls) for how to render them.
91First, check that your client receives them. On Claude Opus 5.5 these notes come back as [progress-update `thinking` blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates) rather than `text` blocks, and their text is empty at the default `thinking.display`. As a result, a client that renders only `text` blocks can look silent during a long agentic turn. Set `display: "updates"` (beta, `thinking-display-updates-2026-08-18` header) to receive a short summary of each note; see [Text between tool calls is returned in thinking blocks](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#text-between-tool-calls) for how to render them.
9292
9393Second, if the model might need to hand the user something verbatim partway through a long turn, such as a code snippet, give it a simple tool for sending the user a message and tell it to reserve the tool for that content. Declare the tool in `tools` from the first request of the session: adding it to `tools` later edits the conversation's prefix and invalidates earlier thinking blocks (see [tool changes in Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#tool-changes)).
9494
build-with-claude/refusals-and-fallback Changed · +4 / -4 lines
from line 152
152152
153153A refusal is a successful HTTP 200 response with `stop_reason: "refusal"`:
154154
155```text
155```json
156156{
157157 "id": "msg_01XFUDYJgAACzvnptvVoYEL",
158158 "type": "message",
from line 484
484484
485485Instead of default routing, you can set `fallbacks` to a list of up to three models. When the requested model declines, the API runs the next model in the chain on the same request. Use this form when you want to control exactly which models serve refused requests, such as pinning a model your application has qualified.
486486
487Named fallback models count toward the [oversized-image check](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#oversized-image-error): a request whose image block sets `"oversized_image": "error"` is checked up front against the requested model and every named fallback, is rejected if any of them would resize that image, and the rejection's reported rescale target fits them all.
487Named fallback models count toward the [oversized-image check](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#oversized-image-error). A request whose image block sets `"oversized_image": "error"` is checked up front against the requested model and every named fallback. The request is rejected if any of them would resize that image, and the rejection's reported rescale target fits them all.
488488
489489The highlighted lines are the only difference from the default-routing request.
490490
from line 645
645645
646646On a refusal before any output, the `fallback` block is the first content block. For example, when default routing selects Claude Opus 4.8 for the refusal's category:
647647
648```text wrap
648```json
649649{
650650 "id": "msg_01XFUDYJgAACzvnptvVoYEL",
651651 "type": "message",
from line 726
726726
727727### Non-streaming responses
728728
729On a non-streaming request, a mid-output decline behaves differently: the response omits the declined model's partial output, and the fallback model starts a new answer. The result looks like a decline before any output, with the `fallback` block first. The declined attempt and its output tokens still appear in `usage.iterations`.
729On a non-streaming request, a mid-output decline behaves differently: the response omits the declined model's partial output, and the fallback model answers without that output as context. The result looks like a decline before any output, with the `fallback` block first. The declined attempt and its output tokens still appear in `usage.iterations`.
730730
731731<Note>
732732 **Declines during tool use:** completed tool work does not block fallback. When a decline fires after server tools (for example, web search or code execution) have finished executing within a request, the fallback attempt proceeds: the completed tool results carry over, and the fallback model can keep invoking server tools. The one case that does not retry is a streaming decline that fires while a tool-use block of any type (a client tool, a server tool, or an MCP tool call) is still open on the stream: that refusal is returned directly, and if the `fallback-credit-2026-07-01` header is set it still carries a credit token redeemable by continuing the partial response. Non-streaming requests are unaffected; the API clears the partial work and retries before responding.
build-with-claude/search-results Changed · +3 / -3 lines
from line 1179
11791179
11801180Regardless of how search results are provided, Claude automatically includes citations when using information from them:
11811181
1182```text
1182```json
11831183{
11841184 "role": "assistant",
11851185 "content": [
from line 1266
12661266
12671267A citation referencing the rate limits block looks like:
12681268
1269```text wrap
1269```json
12701270{
12711271 "type": "search_result_location",
12721272 "cited_text": "Rate Limits: The API allows 1000 requests per hour per key.",
from line 2005
20052005
20062006The response cites both sources. The pre-fetched result is `search_result_index: 0` and the tool-returned result is `search_result_index: 1`, matching the order the `search_result` blocks appear in the conversation:
20072007
2008```text
2008```json
20092009{
20102010 "role": "assistant",
20112011 "content": [