Ásgeir Thor Johnson
525 KiB
name, description, when_to_use
| name | description | when_to_use |
|---|---|---|
| claude-api | Build, debug, and optimize Claude API / Anthropic SDK apps. Apps built with this skill should include prompt caching. Also handles migrating existing Claude API code between Claude model versions. | TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`; user asks for the Claude API, Anthropic SDK, or Managed Agents; user adds/modifies/tunes a Claude feature (caching, thinking, compaction, tool use, batch, files, citations, memory) or model (Opus/Sonnet/Haiku) in a file; questions about prompt caching / cache hit rate in an Anthropic SDK project. SKIP: file imports `openai`/other-provider SDK, filename like `*-openai.py`/`*-generic.py`, provider-neutral code, general programming/ML. |
Building LLM-Powered Applications with Claude
This skill helps you build LLM-powered applications with Claude. Choose the right surface based on your needs, detect the project language, then read the relevant language-specific documentation.
Before You Start
Scan the target file (or, if no target file, the prompt and project) for non-Anthropic provider markers — import openai, from openai, langchain_openai, OpenAI(, gpt-4, gpt-5, file names like agent-openai.py or *-generic.py, or any explicit instruction to keep the code provider-neutral. If you find any, stop and tell the user that this skill produces Claude/Anthropic SDK code; ask whether they want to switch the file to Claude or want a non-Claude implementation. Do not edit a non-Anthropic file with Anthropic SDK calls.
Output Requirement
When the user asks you to add, modify, or implement a Claude feature, your code must call Claude through one of:
- The official Anthropic SDK for the project's language (
anthropic,@anthropic-ai/sdk,com.anthropic.*, etc.). This is the default whenever a supported SDK exists for the project. - Raw HTTP (
curl,requests,fetch,httpx, etc.) — only when the user explicitly asks for cURL/REST/raw HTTP, the project is a shell/cURL project, or the language has no official SDK.
Never mix the two — don't reach for requests/fetch in a Python or TypeScript project just because it feels lighter. Never fall back to OpenAI-compatible shims.
Never guess SDK usage. Function names, class names, namespaces, method signatures, and import paths must come from explicit documentation — either the {lang}/ files in this skill or the official SDK repositories or documentation links listed in shared/live-sources.md. If the binding you need is not explicitly documented in the skill files, WebFetch the relevant SDK repo from shared/live-sources.md before writing code. Do not infer Ruby/Java/Go/PHP/C# APIs from cURL shapes or from another language's SDK.
Defaults
Unless the user requests otherwise:
For the Claude model version, please use Claude Opus 4.8, which you can access via the exact model string claude-opus-4-8. Please default to using adaptive thinking (thinking: {type: "adaptive"}) for anything remotely complicated. And finally, please default to streaming for any request that may involve long input, long output, or high max_tokens — it prevents hitting request timeouts. Use the SDK's .get_final_message() / .finalMessage() helper to get the complete response if you don't need to handle individual stream events
Subcommands
If the User Request at the bottom of this prompt is a bare subcommand string (no prose), search every Subcommands table in this document — including any in sections appended below — and follow the matching Action column directly. This lets users invoke specific flows via /claude-api <subcommand>. If no table in the document matches, treat the request as normal prose.
| Subcommand | Action |
|---|---|
migrate |
Migrate existing Claude API code to a newer model. Read shared/model-migration.md immediately and follow it in order: Step 0 (confirm scope — ask which files/directories before any edit), Step 1 (classify each file), then the per-target breaking-changes section. Do not summarize the guide — execute it. If the user did not name a target model, ask which model to migrate to in the same turn as the scope question. |
Language Detection
Before reading code examples, determine which language the user is working in:
-
Look at project files to infer the language:
*.py,requirements.txt,pyproject.toml,setup.py,Pipfile→ Python — read frompython/*.ts,*.tsx,package.json,tsconfig.json→ TypeScript — read fromtypescript/*.js,*.jsx(no.tsfiles present) → TypeScript — JS uses the same SDK, read fromtypescript/*.java,pom.xml,build.gradle→ Java — read fromjava/*.kt,*.kts,build.gradle.kts→ Java — Kotlin uses the Java SDK, read fromjava/*.scala,build.sbt→ Java — Scala uses the Java SDK, read fromjava/*.go,go.mod→ Go — read fromgo/*.rb,Gemfile→ Ruby — read fromruby/*.cs,*.csproj→ C# — read fromcsharp/*.php,composer.json→ PHP — read fromphp/
-
If multiple languages detected (e.g., both Python and TypeScript files):
- Check which language the user's current file or question relates to
- If still ambiguous, ask: "I detected both Python and TypeScript files. Which language are you using for the Claude API integration?"
-
If language can't be inferred (empty project, no source files, or unsupported language):
- Use AskUserQuestion with options: Python, TypeScript, Java, Go, Ruby, cURL/raw HTTP, C#, PHP
- If AskUserQuestion is unavailable, default to Python examples and note: "Showing Python examples. Let me know if you need a different language."
-
If unsupported language detected (Rust, Swift, C++, Elixir, etc.):
- Suggest cURL/raw HTTP examples from
curl/and note that community SDKs may exist - Offer to show Python or TypeScript examples as reference implementations
- Suggest cURL/raw HTTP examples from
-
If user needs cURL/raw HTTP examples, read from
curl/.
Language-Specific Feature Support
| Language | Tool Runner | Managed Agents | Notes |
|---|---|---|---|
| Python | Yes (beta) | Yes (beta) | Full support — @beta_tool decorator |
| TypeScript | Yes (beta) | Yes (beta) | Full support — betaZodTool + Zod |
| Java | Yes (beta) | Yes (beta) | Beta tool use with annotated classes |
| Go | Yes (beta) | Yes (beta) | BetaToolRunner in toolrunner pkg |
| Ruby | Yes (beta) | Yes (beta) | BaseTool + tool_runner in beta |
| C# | Yes (beta) | Yes (beta) | BetaToolRunner + raw JSON schema |
| PHP | Yes (beta) | Yes (beta) | BetaRunnableTool + toolRunner() |
| cURL | N/A | Yes (beta) | Raw HTTP, no SDK features |
Managed Agents code examples: dedicated language-specific READMEs are provided for Python, TypeScript, Go, Ruby, PHP, Java, and cURL (
{lang}/managed-agents/README.md,curl/managed-agents.md). Read your language's README plus the language-agnosticshared/managed-agents-*.mdconcept files. Agents are persistent — create once, reference by ID. Store the agent ID returned byagents.createand pass it to every subsequentsessions.create; do not callagents.createin the request path. The Anthropic CLI (ant) is one convenient way to create agents and environments from version-controlled YAML — seeshared/anthropic-cli.md. If a binding you need isn't shown in the README, WebFetch the relevant entry fromshared/live-sources.mdrather than guess. C# has beta Managed Agents support viaclient.Beta.Agentsand related namespaces.
Which Surface Should I Use?
Start simple. Default to the simplest tier that meets your needs. Single API calls and workflows handle most use cases — only reach for agents when the task genuinely requires open-ended, model-driven exploration.
| Use Case | Tier | Recommended Surface | Why |
|---|---|---|---|
| Classification, summarization, extraction, Q&A | Single LLM call | Claude API | One request, one response |
| Batch processing or embeddings | Single LLM call | Claude API | Specialized endpoints |
| Multi-step pipelines with code-controlled logic | Workflow | Claude API + tool use | You orchestrate the loop |
| Custom agent with your own tools | Agent | Claude API + tool use | Maximum flexibility |
| Server-managed stateful agent with workspace | Agent | Managed Agents | Anthropic runs the loop and hosts the tool-execution sandbox |
| Persisted, versioned agent configs | Agent | Managed Agents | Agents are stored objects; sessions pin to a version |
| Long-running multi-turn agent with file mounts | Agent | Managed Agents | Per-session containers, SSE event stream, Skills + MCP |
Note: Managed Agents is the right choice when you want Anthropic to run the agent loop and host the container where tools execute — file ops, bash, code execution all run in the per-session workspace. If you want to host the compute yourself or run your own custom tool runtime, Claude API + tool use is the right choice — use the tool runner for automatic loop handling, or the manual loop for fine-grained control (approval gates, custom logging, conditional execution).
Cloud-provider access. Claude Platform on AWS is Anthropic-operated with same-day API parity — Managed Agents and every feature in this skill work there, except self-hosted sandboxes (see
shared/claude-platform-on-aws.md). Amazon Bedrock, Google Vertex AI, and Microsoft Foundry do not support Managed Agents or Anthropic server-side tools; use Claude API + tool use on those.
Decision Tree
What does your application need?
0. Which provider?
├── First-party API or Claude Platform on AWS → continue (full surface available).
└── Amazon Bedrock, Google Vertex AI, or Microsoft Foundry → Claude API (+ tool use for agents); Managed Agents not available there.
1. Single LLM call (classification, summarization, extraction, Q&A)
└── Claude API — one request, one response
2. Do you want Anthropic to run the agent loop and host a per-session
container where Claude executes tools (bash, file ops, code)?
└── Yes → Managed Agents — server-managed sessions, persisted agent configs,
SSE event stream, Skills + MCP, file mounts.
Examples: "stateful coding agent with a workspace per task",
"long-running research agent that streams events to a UI",
"agent with persisted, versioned config used across many sessions"
3. Workflow (multi-step, code-orchestrated, with your own tools)
└── Claude API with tool use — you control the loop
4. Open-ended agent (model decides its own trajectory, your own tools, you host the compute)
└── Claude API agentic loop (maximum flexibility)
Should I Build an Agent?
Before choosing the agent tier, check all four criteria:
- Complexity — Is the task multi-step and hard to fully specify in advance? (e.g., "turn this design doc into a PR" vs. "extract the title from this PDF")
- Value — Does the outcome justify higher cost and latency?
- Viability — Is Claude capable at this task type?
- Cost of error — Can errors be caught and recovered from? (tests, review, rollback)
If the answer is "no" to any of these, stay at a simpler tier (single call or workflow).
Architecture
Everything goes through POST /v1/messages. Tools and output constraints are features of this single endpoint — not separate APIs.
User-defined tools — You define tools (via decorators, Zod schemas, or raw JSON), and the SDK's tool runner handles calling the API, executing your functions, and looping until Claude is done. For full control, you can write the loop manually.
Server-side tools — Anthropic-hosted tools that run on Anthropic's infrastructure. Code execution is fully server-side (declare it in tools, Claude runs code automatically). Computer use can be server-hosted or self-hosted.
Structured outputs — Constrains the Messages API response format (output_config.format) and/or tool parameter validation (strict: true). The recommended approach is client.messages.parse() which validates responses against your schema automatically. Note: the old output_format parameter is deprecated; use output_config: {format: {...}} on messages.create().
Supporting endpoints — Batches (POST /v1/messages/batches), Files (POST /v1/files), Token Counting, and Models (GET /v1/models, GET /v1/models/{id} — live capability/context-window discovery) feed into or support Messages API requests.
Current Models (cached: 2026-05-26)
| Model | Model ID | Context | Input $/1M | Output $/1M |
|---|---|---|---|---|
| Claude Opus 4.8 | claude-opus-4-8 |
1M | $5.00 | $25.00 |
| Claude Opus 4.7 | claude-opus-4-7 |
1M | $5.00 | $25.00 |
| Claude Opus 4.6 | claude-opus-4-6 |
1M | $5.00 | $25.00 |
| Claude Sonnet 4.6 | claude-sonnet-4-6 |
1M | $3.00 | $15.00 |
| Claude Haiku 4.5 | claude-haiku-4-5 |
200K | $1.00 | $5.00 |
ALWAYS use claude-opus-4-8 unless the user explicitly names a different model. This is non-negotiable. Do not use claude-sonnet-4-6, claude-sonnet-4-5, or any other model unless the user literally says "use sonnet" or "use haiku". Never downgrade for cost — that's the user's decision, not yours.
CRITICAL: Use only the exact model ID strings from the table above — they are complete as-is. Do not append date suffixes. For example, use claude-sonnet-4-6, never claude-sonnet-4-6-20251114 or any other date-suffixed variant you might recall from training data. If the user requests an older model not in the table (e.g., "opus 4.5", "sonnet 3.7"), read shared/models.md for the exact ID — do not construct one yourself.
A note: if any of the model strings above look unfamiliar to you, that's to be expected — that just means they were released after your training data cutoff. Rest assured they are real models; we wouldn't mess with you like that.
Live capability lookup: The table above is cached. When the user asks "what's the context window for X", "does X support vision/thinking/effort", or "which models support Y", query the Models API (client.models.retrieve(id) / client.models.list()) — see shared/models.md for the field reference and capability-filter examples.
Thinking & Effort (Quick Reference)
Opus 4.8 / 4.7 — Adaptive thinking only: Use thinking: {type: "adaptive"}. thinking: {type: "enabled", budget_tokens: N} returns a 400 — adaptive is the only on-mode. {type: "disabled"} and omitting thinking both work. Sampling parameters (temperature, top_p, top_k) are also removed and will 400. Opus 4.8 keeps the same request surface as 4.7 (no new breaking changes) — see shared/model-migration.md → Migrating to Opus 4.8 for the behavioral re-tuning, and → Migrating to Opus 4.7 for the full breaking-change list when coming from 4.6 or earlier. Note: with thinking disabled, Opus 4.8 may write longer reasoning into the visible response — leave adaptive thinking on, or add a final-answer-only instruction (see the migration guide).
Opus 4.6 — Adaptive thinking (recommended): Use thinking: {type: "adaptive"}. Claude dynamically decides when and how much to think. No budget_tokens needed — budget_tokens is deprecated on Opus 4.6 and Sonnet 4.6 and should not be used for new code. Adaptive thinking also automatically enables interleaved thinking (no beta header needed). When the user asks for "extended thinking", a "thinking budget", or budget_tokens: always use Opus 4.8, 4.7, or 4.6 with thinking: {type: "adaptive"}. The concept of a fixed token budget for thinking is deprecated — adaptive thinking replaces it. Do NOT use budget_tokens for new 4.6/4.7/4.8 code and do NOT switch to an older model. Gradual-migration carve-out: budget_tokens is still functional on Opus 4.6 and Sonnet 4.6 as a transitional escape hatch — if you're migrating existing code and need a hard token ceiling before you've tuned effort, see shared/model-migration.md → Transitional escape hatch. Note: this carve-out does not apply to Opus 4.7 or 4.8 — budget_tokens is fully removed there.
Effort parameter (GA, no beta header): Controls thinking depth and overall token spend via output_config: {effort: "low"|"medium"|"high"|"max"} (inside output_config, not top-level). Default is high (equivalent to omitting it). max is Opus-tier only (Opus 4.6 and later — not Sonnet or Haiku). Opus 4.7 added "xhigh" (between high and max) — the best setting for most coding and agentic use cases on Opus 4.7/4.8, and the default in Claude Code; use a minimum of high for most intelligence-sensitive work. Works on Opus 4.5, Opus 4.6, Opus 4.7, Opus 4.8, and Sonnet 4.6. Will error on Sonnet 4.5 / Haiku 4.5. On Opus 4.7 and 4.8, effort matters more than on any prior Opus — re-tune it when migrating, and run long-horizon/agentic tasks at high/xhigh with the full task spec given up front. Combine with adaptive thinking for the best cost-quality tradeoffs. Lower effort means fewer and more-consolidated tool calls, less preamble, and terser confirmations — high is often the sweet spot balancing quality and token efficiency; use max when correctness matters more than cost; use low for subagents or simple tasks.
Opus 4.8 / 4.7 — thinking content omitted by default: thinking blocks still stream but their text is empty unless you opt in with thinking: {type: "adaptive", display: "summarized"} (default is "omitted"). Silent change — no error. If you stream reasoning to users, the default looks like a long pause before output; set "summarized" to restore visible progress.
Task Budgets (beta, Opus 4.7 / 4.8): output_config: {task_budget: {type: "tokens", total: N}} tells the model how many tokens it has for a full agentic loop — it sees a running countdown and self-moderates (minimum 20,000; beta header task-budgets-2026-03-13). Distinct from max_tokens, which is an enforced per-response ceiling the model is not aware of. See shared/model-migration.md → Task Budgets.
Sonnet 4.6: Supports adaptive thinking (thinking: {type: "adaptive"}). budget_tokens is deprecated on Sonnet 4.6 — use adaptive thinking instead.
Older models (only if explicitly requested): If the user specifically asks for Sonnet 4.5 or another older model, use thinking: {type: "enabled", budget_tokens: N}. budget_tokens must be less than max_tokens (minimum 1024). Never choose an older model just because the user mentions budget_tokens — use Opus 4.8 with adaptive thinking instead.
Compaction (Quick Reference)
Beta, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6. For long-running conversations that may exceed the 1M context window, enable server-side compaction. The API automatically summarizes earlier context when it approaches the trigger threshold (default: 150K tokens). Requires beta header compact-2026-01-12.
Critical: Append response.content (not just the text) back to your messages on every turn. Compaction blocks in the response must be preserved — the API uses them to replace the compacted history on the next request. Extracting only the text string and appending that will silently lose the compaction state.
See {lang}/claude-api/README.md (Compaction section) for code examples. Full docs via WebFetch in shared/live-sources.md.
Prompt Caching (Quick Reference)
Prefix match. Any byte change anywhere in the prefix invalidates everything after it. Render order is tools → system → messages. Keep stable content first (frozen system prompt, deterministic tool list), put volatile content (timestamps, per-request IDs, varying questions) after the last cache_control breakpoint.
Mid-conversation operator instructions (beta header mid-conversation-system-2026-04-07, on supporting models): append {"role": "system", ...} to messages[] instead of editing top-level system. Preserves the cached history prefix and is the prompt-injection-safe operator channel. See shared/prompt-caching.md § Mid-conversation system messages.
Top-level auto-caching (cache_control: {type: "ephemeral"} on messages.create()) is the simplest option when you don't need fine-grained placement. Max 4 breakpoints per request. Minimum cacheable prefix is ~1024 tokens — shorter prefixes silently won't cache.
Verify with usage.cache_read_input_tokens — if it's zero across repeated requests, a silent invalidator is at work (datetime.now() in system prompt, unsorted JSON, varying tool set).
For placement patterns, architectural guidance, and the silent-invalidator audit checklist: read shared/prompt-caching.md. Language-specific syntax: {lang}/claude-api/README.md (Prompt Caching section).
Managed Agents (Beta)
Managed Agents is a third surface: server-managed stateful agents with Anthropic-hosted tool execution. You create a persisted, versioned Agent config (POST /v1/agents), then start Sessions that reference it. Each session provisions a container as the agent's workspace — bash, file ops, and code execution run there; the agent loop itself runs on Anthropic's orchestration layer and acts on the container via tools. The session streams events; you send messages and tool results back.
Managed Agents is available on the first-party API and Claude Platform on AWS. It is not available on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry — for agents there, use Claude API + tool use.
Mandatory flow: Agent (once) → Session (every run). model/system/tools live on the agent, never the session. See shared/managed-agents-overview.md for the full reading guide, beta headers, and pitfalls.
Beta headers: managed-agents-2026-04-01 — the SDK sets this automatically for all client.beta.{agents,environments,sessions,vaults,memory_stores}.* calls. Skills API uses skills-2025-10-02 and Files API uses files-api-2025-04-14, but you don't need to explicitly pass those in for endpoints other than /v1/skills and /v1/files.
Subcommands — invoke directly with /claude-api <subcommand>:
| Subcommand | Action |
|---|---|
managed-agents-onboard |
Walk the user through setting up a Managed Agent from scratch. Read shared/managed-agents-onboarding.md immediately and follow its interview script: mental model → know-or-explore branch → template config → session setup → pre-flight viability check → emit code. The viability check (reconcile the stated job against configured tools/credentials/data) catches under-resourced setups — missing a tool, credential, or data access — before the agent burns budget. Do not summarize — run the interview. |
Reading guide: Start with shared/managed-agents-overview.md, then the topical shared/managed-agents-*.md files (core, environments, tools, events, outcomes, multiagent, webhooks, memory, client-patterns, onboarding, api-reference). For Python, TypeScript, Go, Ruby, PHP, and Java, read {lang}/managed-agents/README.md for code examples. For cURL, read curl/managed-agents.md. Agents are persistent — create once, reference by ID. Store the agent ID returned by agents.create and pass it to every subsequent sessions.create; do not call agents.create in the request path. The Anthropic CLI (ant) is one convenient way to create agents and environments from version-controlled YAML — see shared/anthropic-cli.md. If a binding you need isn't shown in the language README, WebFetch the relevant entry from shared/live-sources.md rather than guess. C# has beta Managed Agents support via client.Beta.Agents and related namespaces.
When the user wants to set up a Managed Agent from scratch (e.g. "how do I get started", "walk me through creating one", "set up a new agent"): read shared/managed-agents-onboarding.md and run its interview — same flow as the managed-agents-onboard subcommand.
When the user asks "how do I write the client code for X": reach for shared/managed-agents-client-patterns.md — covers lossless stream reconnect, processed_at queued/processed gate, interrupt, tool_confirmation round-trip, the correct idle/terminated break gate, post-idle status race, stream-first ordering, file-mount gotchas, keeping credentials host-side via custom tools, etc.
Reference Documentation
The relevant documentation for your detected language is included below in <doc> tags. Each tag has a path attribute showing its original file path. Use this to find the right section:
Quick Task Reference
Single text classification/summarization/extraction/Q&A:
→ Refer to unknown/claude-api/README.md
Chat UI or real-time response display:
→ Refer to unknown/claude-api/README.md + unknown/claude-api/streaming.md
Long-running conversations (may exceed context window):
→ Refer to unknown/claude-api/README.md — see Compaction section
Migrating to a newer model or replacing a retired model:
→ Refer to shared/model-migration.md
Prompt caching / optimize caching / "why is my cache hit rate low":
→ Refer to shared/prompt-caching.md + unknown/claude-api/README.md (Prompt Caching section)
Function calling / tool use / agents:
→ Refer to unknown/claude-api/README.md + shared/tool-use-concepts.md + unknown/claude-api/tool-use.md
Batch processing (non-latency-sensitive):
→ Refer to unknown/claude-api/README.md + unknown/claude-api/batches.md
File uploads across multiple requests:
→ Refer to unknown/claude-api/README.md + unknown/claude-api/files-api.md
Agent design (tool surface, context management, caching strategy):
→ Refer to shared/agent-design.md
Anthropic CLI (ant) — terminal access, version-controlled agent/environment YAML, scripting:
→ Refer to shared/anthropic-cli.md
Managed Agents (server-managed stateful agents):
→ Refer to shared/managed-agents-overview.md and the rest of the shared/managed-agents-*.md files. For Python, TypeScript, and cURL, language-specific code examples live in unknown/managed-agents/README.md. Java, Go, Ruby, and PHP also support the API — translate the calls using your SDK's patterns from unknown/claude-api.md. C# does not currently have Managed Agents support; use raw HTTP from curl/managed-agents.md as a reference.
Error handling:
→ Refer to shared/error-codes.md
Latest docs via WebFetch:
→ Refer to shared/live-sources.md for URLs
No project language was auto-detected. Ask the user which language they are using, then refer to the matching docs below.
Included Documentation
# Claude API — C#Note: The C# SDK is the official Anthropic SDK for C#. Tool use is supported via the Messages API with a beta
BetaToolRunnerfor automatic tool execution loops. The SDK also supports Microsoft.Extensions.AI IChatClient integration with function invocation and Managed Agents (beta).
Installation
dotnet add package Anthropic
Client Initialization
using Anthropic;
// Default (uses ANTHROPIC_API_KEY env var)
AnthropicClient client = new();
// Explicit API key (use environment variables — never hardcode keys)
AnthropicClient client = new() {
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
Basic Message Request
using Anthropic.Models.Messages;
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus4_6,
MaxTokens = 16000,
Messages = [new() { Role = Role.User, Content = "What is the capital of France?" }]
};
var response = await client.Messages.Create(parameters);
// ContentBlock is a union wrapper. .Value unwraps to the variant object,
// then OfType<T> filters to the type you want. Or use the TryPick* idiom
// shown in the Thinking section below.
foreach (var text in response.Content.Select(b => b.Value).OfType<TextBlock>())
{
Console.WriteLine(text.Text);
}
Streaming
using Anthropic.Models.Messages;
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus4_6,
MaxTokens = 64000,
Messages = [new() { Role = Role.User, Content = "Write a haiku" }]
};
await foreach (RawMessageStreamEvent streamEvent in client.Messages.CreateStreaming(parameters))
{
if (streamEvent.TryPickContentBlockDelta(out var delta) &&
delta.Delta.TryPickText(out var text))
{
Console.Write(text.Text);
}
}
RawMessageStreamEvent TryPick methods (naming drops the Message/Raw prefix): TryPickStart, TryPickDelta, TryPickStop, TryPickContentBlockStart, TryPickContentBlockDelta, TryPickContentBlockStop. There is no TryPickMessageStop — use TryPickStop.
Thinking
Adaptive thinking is the recommended mode for Claude 4.6+ models. Claude decides dynamically when and how much to think.
using Anthropic.Models.Messages;
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus4_6,
MaxTokens = 16000,
// ThinkingConfigParam? implicitly converts from the concrete variant classes —
// no wrapper needed.
Thinking = new ThinkingConfigAdaptive(),
Messages =
[
new() { Role = Role.User, Content = "Solve: 27 * 453" },
],
});
// ThinkingBlock(s) precede TextBlock in Content. TryPick* narrows the union.
foreach (var block in response.Content)
{
if (block.TryPickThinking(out ThinkingBlock? t))
{
Console.WriteLine($"[thinking] {t.Thinking}");
}
else if (block.TryPickText(out TextBlock? text))
{
Console.WriteLine(text.Text);
}
}
Deprecated:
new ThinkingConfigEnabled { BudgetTokens = N }(fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above.
Alternative to TryPick*: .Select(b => b.Value).OfType<ThinkingBlock>() (same LINQ pattern as the Basic Message example).
Tool Use
Defining a tool
Tool (NOT ToolParam) with an InputSchema record. InputSchema.Type is auto-set to "object" by the constructor — don't set it. ToolUnion has an implicit conversion from Tool, triggered by the collection expression [...].
using System.Text.Json;
using Anthropic.Models.Messages;
var parameters = new MessageCreateParams
{
Model = Model.ClaudeSonnet4_6,
MaxTokens = 16000,
Tools = [
new Tool {
Name = "get_weather",
Description = "Get the current weather in a given location",
InputSchema = new() {
Properties = new Dictionary<string, JsonElement> {
["location"] = JsonSerializer.SerializeToElement(
new { type = "string", description = "City name" }),
},
Required = ["location"],
},
},
],
Messages = [new() { Role = Role.User, Content = "Weather in Paris?" }],
};
Derived from anthropic-sdk-csharp/src/Anthropic/Models/Messages/Tool.cs and ToolUnion.cs:799 (implicit conversion).
See shared tool use concepts for the loop pattern.
Converting response content to the follow-up assistant message
When echoing Claude's response back in the assistant turn, there is no .ToParam() helper — manually reconstruct each ContentBlock variant as its *Param counterpart. Do NOT use new ContentBlockParam(block.Json): it compiles and serializes, but .Value stays null so TryPick*/Validate() fail (degraded JSON pass-through, not the typed path).
using Anthropic.Models.Messages;
Message response = await client.Messages.Create(parameters);
// No .ToParam() — reconstruct per variant. Implicit conversions from each
// *Param type to ContentBlockParam mean no explicit wrapper.
List<ContentBlockParam> assistantContent = [];
List<ContentBlockParam> toolResults = [];
foreach (ContentBlock block in response.Content)
{
if (block.TryPickText(out TextBlock? text))
{
assistantContent.Add(new TextBlockParam { Text = text.Text });
}
else if (block.TryPickThinking(out ThinkingBlock? thinking))
{
// Signature MUST be preserved — the API rejects tampering
assistantContent.Add(new ThinkingBlockParam
{
Thinking = thinking.Thinking,
Signature = thinking.Signature,
});
}
else if (block.TryPickRedactedThinking(out RedactedThinkingBlock? redacted))
{
assistantContent.Add(new RedactedThinkingBlockParam { Data = redacted.Data });
}
else if (block.TryPickToolUse(out ToolUseBlock? toolUse))
{
// ToolUseBlock has required Caller; ToolUseBlockParam.Caller is optional — don't copy it
assistantContent.Add(new ToolUseBlockParam
{
ID = toolUse.ID,
Name = toolUse.Name,
Input = toolUse.Input,
});
// Execute the tool; collect ONE result per tool_use block — the API
// rejects the follow-up if any tool_use ID lacks a matching tool_result.
string result = ExecuteYourTool(toolUse.Name, toolUse.Input);
toolResults.Add(new ToolResultBlockParam
{
ToolUseID = toolUse.ID,
Content = result,
});
}
}
// Follow-up: prior messages + assistant echo + user tool_result(s)
List<MessageParam> followUpMessages =
[
.. parameters.Messages,
new() { Role = Role.Assistant, Content = assistantContent },
new() { Role = Role.User, Content = toolResults },
];
ToolResultBlockParam has no tuple constructor — use the object initializer. Content is a string-or-list union; a plain string implicitly converts.
Context Editing / Compaction (Beta)
Beta-namespace prefix is inconsistent (source-verified against src/Anthropic/Models/Beta/Messages/*.cs @ 12.9.0). No prefix: MessageCreateParams, MessageCountTokensParams, Role. Everything else has the Beta prefix: BetaMessageParam, BetaMessage, BetaContentBlock, BetaToolUseBlock, all block param types. The unprefixed Role WILL collide with Anthropic.Models.Messages.Role if you import both namespaces (CS0104). Safest: import only Beta; if mixing, alias the beta Role:
using Anthropic.Models.Beta.Messages;
using NonBeta = Anthropic.Models.Messages; // only if you also need non-beta types
// Now: MessageCreateParams, BetaMessageParam, Role (beta's), NonBeta.Role (if needed)
BetaMessage.Content is IReadOnlyList<BetaContentBlock> — a 15-variant discriminated union. Narrow with TryPick*. Response BetaContentBlock is NOT assignable to param BetaContentBlockParam — there's no .ToParam() in C#. Round-trip by converting each block:
using Anthropic.Models.Beta.Messages;
var betaParams = new MessageCreateParams // no Beta prefix — one of only 2 unprefixed
{
Model = Model.ClaudeOpus4_6,
MaxTokens = 16000,
Betas = ["compact-2026-01-12"],
ContextManagement = new BetaContextManagementConfig
{
Edits = [new BetaCompact20260112Edit()],
},
Messages = messages,
};
BetaMessage resp = await client.Beta.Messages.Create(betaParams);
foreach (BetaContentBlock block in resp.Content)
{
if (block.TryPickCompaction(out BetaCompactionBlock? compaction))
{
// Content is nullable — compaction can fail server-side
Console.WriteLine($"compaction summary: {compaction.Content}");
}
}
// Context-edit metadata lives on a separate nullable field
if (resp.ContextManagement is { } ctx)
{
foreach (var edit in ctx.AppliedEdits)
Console.WriteLine($"cleared {edit.ClearedInputTokens} tokens");
}
// ROUND-TRIP: BetaMessageParam.Content is BetaMessageParamContent (a string|list
// union). It implicit-converts from List<BetaContentBlockParam>, NOT from the
// response's IReadOnlyList<BetaContentBlock>. Convert each block:
List<BetaContentBlockParam> paramBlocks = [];
foreach (var b in resp.Content)
{
if (b.TryPickText(out var t)) paramBlocks.Add(new BetaTextBlockParam { Text = t.Text });
else if (b.TryPickCompaction(out var c)) paramBlocks.Add(new BetaCompactionBlockParam { Content = c.Content });
// ... other variants as needed
}
messages.Add(new BetaMessageParam { Role = Role.Assistant, Content = paramBlocks });
All 15 BetaContentBlock.TryPick* variants: Text, Thinking, RedactedThinking, ToolUse, ServerToolUse, WebSearchToolResult, WebFetchToolResult, CodeExecutionToolResult, BashCodeExecutionToolResult, TextEditorCodeExecutionToolResult, ToolSearchToolResult, McpToolUse, McpToolResult, ContainerUpload, Compaction.
BetaToolUseBlock.Input is IReadOnlyDictionary<string, JsonElement> — index by key then call the JsonElement extractor:
if (block.TryPickToolUse(out BetaToolUseBlock? tu))
{
int a = tu.Input["a"].GetInt32();
string s = tu.Input["name"].GetString()!;
}
Effort Parameter
Effort is nested under OutputConfig, NOT a top-level property. ApiEnum<string, Effort> has an implicit conversion from the enum, so assign Effort.High directly.
OutputConfig = new OutputConfig { Effort = Effort.High },
Values: Effort.Low, Effort.Medium, Effort.High, Effort.Max. Combine with Thinking = new ThinkingConfigAdaptive() for cost-quality control.
Prompt Caching
System takes MessageCreateParamsSystem? — a union of string or List<TextBlockParam>. There is no SystemTextBlockParam; use plain TextBlockParam. The implicit conversion needs the concrete List<TextBlockParam> type (array literals won't convert). For placement patterns and the silent-invalidator audit checklist, see shared/prompt-caching.md.
System = new List<TextBlockParam> {
new() {
Text = longSystemPrompt,
CacheControl = new CacheControlEphemeral(), // auto-sets Type = "ephemeral"
},
},
Optional Ttl on CacheControlEphemeral: new() { Ttl = Ttl.Ttl1h } or Ttl.Ttl5m. CacheControl also exists on Tool.CacheControl and top-level MessageCreateParams.CacheControl.
Verify hits via response.Usage.CacheCreationInputTokens / response.Usage.CacheReadInputTokens.
Token Counting
MessageTokensCount result = await client.Messages.CountTokens(new MessageCountTokensParams {
Model = Model.ClaudeOpus4_6,
Messages = [new() { Role = Role.User, Content = "Hello" }],
});
long tokens = result.InputTokens;
MessageCountTokensParams.Tools uses a different union type (MessageCountTokensTool) than MessageCreateParams.Tools (ToolUnion) — if you're passing tools, the compiler will tell you when it matters.
Structured Output
OutputConfig = new OutputConfig {
Format = new JsonOutputFormat {
Schema = new Dictionary<string, JsonElement> {
["type"] = JsonSerializer.SerializeToElement("object"),
["properties"] = JsonSerializer.SerializeToElement(
new { name = new { type = "string" } }),
["required"] = JsonSerializer.SerializeToElement(new[] { "name" }),
},
},
},
JsonOutputFormat.Type is auto-set to "json_schema" by the constructor. Schema is required.
PDF / Document Input
DocumentBlockParam takes a DocumentBlockParamSource union: Base64PdfSource / UrlPdfSource / PlainTextSource / ContentBlockSource. Base64PdfSource auto-sets MediaType = "application/pdf" and Type = "base64".
new MessageParam {
Role = Role.User,
Content = new List<ContentBlockParam> {
new DocumentBlockParam { Source = new Base64PdfSource { Data = base64String } },
new TextBlockParam { Text = "Summarize this PDF" },
},
}
Server-Side Tools
Web search, bash, text editor, and code execution are built-in server tools. Type names are version-suffixed; constructors auto-set name/type. All implicit-convert to ToolUnion.
Tools = [
new WebSearchTool20260209(),
new ToolBash20250124(),
new ToolTextEditor20250728(),
new CodeExecutionTool20260120(),
],
Also available: WebFetchTool20260209, MemoryTool20250818. WebSearchTool20260209 optionals: AllowedDomains, BlockedDomains, MaxUses, UserLocation.
Files API (Beta)
Files live under client.Beta.Files (namespace Anthropic.Models.Beta.Files). BinaryContent implicit-converts from Stream and byte[].
using Anthropic.Models.Beta.Files;
using Anthropic.Models.Beta.Messages;
FileMetadata meta = await client.Beta.Files.Upload(
new FileUploadParams { File = File.OpenRead("doc.pdf") });
// Referencing the uploaded file requires Beta message types:
new BetaRequestDocumentBlock {
Source = new BetaFileDocumentSource { FileID = meta.ID },
}
The non-beta DocumentBlockParamSource union has no file-ID variant — file references need client.Beta.Messages.Create().
Tool Runner (Beta)
The C# SDK provides a BetaToolRunner for automatic tool execution loops. Define tools with raw JSON schemas, and the runner handles the API call → tool execution → result feedback loop.
using Anthropic.Models.Beta.Messages;
// Define tools and create params as shown in the Tool Use section above,
// but using the beta namespace types (BetaToolUnion, etc.)
var runner = client.Beta.Messages.ToolRunner(betaParams);
await foreach (BetaMessage message in runner)
{
foreach (var block in message.Content)
{
if (block.TryPickText(out var text))
{
Console.WriteLine(text.Text);
}
}
}
Stop Details
When StopReason is "refusal", the response includes structured StopDetails:
if (response.StopReason == "refusal" && response.StopDetails is { } details)
{
Console.WriteLine($"Category: {details.Category}");
Console.WriteLine($"Explanation: {details.Explanation}");
}
Managed Agents (Beta)
The C# SDK supports Managed Agents via client.Beta.Agents, client.Beta.Sessions, client.Beta.Environments, and related namespaces. See shared/managed-agents-overview.md for the architecture and curl/managed-agents.md for the wire-level reference.
Use these examples when the user needs raw HTTP requests or is working in a language without an official SDK.
Setup
export ANTHROPIC_API_KEY="your-api-key"
Basic Message Request
curl https://api.anthropic.com/v1/messages \
-H "Content-Type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-4-8",
"max_tokens": 16000,
"messages": [
{"role": "user", "content": "What is the capital of France?"}
]
}'
Parsing the response
Use jq to extract fields from the JSON response. Do not use grep/sed —
JSON strings can contain any character and regex parsing will break on quotes,
escapes, or multi-line content.
# Capture the response, then extract fields
response=$(curl -s 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-8","max_tokens":16000,"messages":[{"role":"user","content":"Hello"}]}')
# Print the first text block (-r strips the JSON quotes)
echo "$response" | jq -r '.content[0].text'
# Read usage fields
input_tokens=$(echo "$response" | jq -r '.usage.input_tokens')
output_tokens=$(echo "$response" | jq -r '.usage.output_tokens')
# Read stop reason (for tool-use loops)
stop_reason=$(echo "$response" | jq -r '.stop_reason')
# Extract all text blocks (content is an array; filter to type=="text")
echo "$response" | jq -r '.content[] | select(.type == "text") | .text'
Streaming (SSE)
curl https://api.anthropic.com/v1/messages \
-H "Content-Type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-4-8",
"max_tokens": 64000,
"stream": true,
"messages": [{"role": "user", "content": "Write a haiku"}]
}'
The response is a stream of Server-Sent Events:
event: message_start
data: {"type":"message_start","message":{"id":"msg_...","type":"message",...}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}}
event: message_stop
data: {"type":"message_stop"}
Tool Use
curl https://api.anthropic.com/v1/messages \
-H "Content-Type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-4-8",
"max_tokens": 16000,
"tools": [{
"name": "get_weather",
"description": "Get current weather for a location",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "City name"}
},
"required": ["location"]
}
}],
"messages": [{"role": "user", "content": "What is the weather in Paris?"}]
}'
When Claude responds with a tool_use block, send the result back:
curl https://api.anthropic.com/v1/messages \
-H "Content-Type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-4-8",
"max_tokens": 16000,
"tools": [{
"name": "get_weather",
"description": "Get current weather for a location",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "City name"}
},
"required": ["location"]
}
}],
"messages": [
{"role": "user", "content": "What is the weather in Paris?"},
{"role": "assistant", "content": [
{"type": "text", "text": "Let me check the weather."},
{"type": "tool_use", "id": "toolu_abc123", "name": "get_weather", "input": {"location": "Paris"}}
]},
{"role": "user", "content": [
{"type": "tool_result", "tool_use_id": "toolu_abc123", "content": "72°F and sunny"}
]}
]
}'
Prompt Caching
Put cache_control on the last block of the stable prefix. See shared/prompt-caching.md for placement patterns and the silent-invalidator audit checklist.
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-8",
"max_tokens": 16000,
"system": [
{"type": "text", "text": "<large shared prompt...>", "cache_control": {"type": "ephemeral"}}
],
"messages": [{"role": "user", "content": "Summarize the key points"}]
}'
For 1-hour TTL: "cache_control": {"type": "ephemeral", "ttl": "1h"}. Top-level "cache_control" on the request body auto-places on the last cacheable block. Verify hits via the response usage.cache_creation_input_tokens / usage.cache_read_input_tokens fields.
Extended Thinking
Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6: Use adaptive thinking.
budget_tokensis removed on Opus 4.8 and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. Older models: Use"type": "enabled"with"budget_tokens": N(must be <max_tokens, min 1024).
# Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended)
curl https://api.anthropic.com/v1/messages \
-H "Content-Type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-4-8",
"max_tokens": 16000,
"thinking": {
"type": "adaptive"
},
"output_config": {
"effort": "high"
},
"messages": [{"role": "user", "content": "Solve this step by step..."}]
}'
Required Headers
| Header | Value | Description |
|---|---|---|
Content-Type |
application/json |
Required |
x-api-key |
Your API key | Authentication |
anthropic-version |
2023-06-01 |
API version |
anthropic-beta |
Beta feature IDs | Required for beta features |
Use these examples when the user needs raw HTTP requests or is working without an SDK.
Setup
export ANTHROPIC_API_KEY="your-api-key"
# Common headers
HEADERS=(
-H "Content-Type: application/json"
-H "x-api-key: $ANTHROPIC_API_KEY"
-H "anthropic-version: 2023-06-01"
-H "anthropic-beta: managed-agents-2026-04-01"
)
Create an Environment
curl -X POST https://api.anthropic.com/v1/environments \
"${HEADERS[@]}" \
-d '{
"name": "my-dev-env",
"config": {
"type": "cloud",
"networking": { "type": "unrestricted" }
}
}'
With restricted networking
curl -X POST https://api.anthropic.com/v1/environments \
"${HEADERS[@]}" \
-d '{
"name": "restricted-env",
"config": {
"type": "cloud",
"networking": {
"type": "limited",
"allow_package_managers": true,
"allow_mcp_servers": true,
"allowed_hosts": ["api.example.com"]
}
}
}'
Create an Agent (required first step)
⚠️ There is no inline agent config. Under
managed-agents-2026-04-01,model/system/toolsare top-level fields onPOST /v1/agents, not on the session. Always create the agent first — the session only takes"agent": {"type": "agent", "id": "..."}.
Minimal
# 1. Create the agent
curl -X POST https://api.anthropic.com/v1/agents \
"${HEADERS[@]}" \
-d '{
"name": "Coding Assistant",
"model": "claude-opus-4-8",
"tools": [{ "type": "agent_toolset_20260401" }]
}'
# → { "id": "agent_abc123", ... }
# 2. Start a session
curl -X POST https://api.anthropic.com/v1/sessions \
"${HEADERS[@]}" \
-d '{
"agent": { "type": "agent", "id": "agent_abc123", "version": "1772585501101368014" },
"environment_id": "env_abc123"
}'
With system prompt, custom tools, and GitHub repo
# 1. Create the agent
curl -X POST https://api.anthropic.com/v1/agents \
"${HEADERS[@]}" \
-d '{
"name": "Code Reviewer",
"model": "claude-opus-4-8",
"system": "You are a senior code reviewer. Be thorough and constructive.",
"tools": [
{ "type": "agent_toolset_20260401" },
{
"type": "custom",
"name": "run_linter",
"description": "Run the project linter on a file",
"input_schema": {
"type": "object",
"properties": {
"file_path": { "type": "string", "description": "Path to lint" }
},
"required": ["file_path"]
}
}
]
}'
# 2. Start a session with the repo mounted
curl -X POST https://api.anthropic.com/v1/sessions \
"${HEADERS[@]}" \
-d '{
"agent": { "type": "agent", "id": "agent_abc123", "version": "1772585501101368014" },
"environment_id": "env_abc123",
"title": "Code review session",
"resources": [
{
"type": "github_repository",
"url": "https://github.com/owner/repo",
"mount_path": "/workspace/repo",
"authorization_token": "ghp_...",
"branch": "feature-branch"
}
]
}'
Send a User Message
curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
"${HEADERS[@]}" \
-d '{
"events": [
{
"type": "user.message",
"content": [{ "type": "text", "text": "Review the auth module for security issues" }]
}
]
}'
Stream Events (SSE)
curl -N https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream \
"${HEADERS[@]}"
Response format:
event: session.status_running
data: {"type":"session.status_running","id":"sevt_...","processed_at":"..."}
event: agent.message
data: {"type":"agent.message","id":"sevt_...","content":[{"type":"text","text":"I'll review..."}],"processed_at":"..."}
event: session.status_idle
data: {"type":"session.status_idle","id":"sevt_...","processed_at":"..."}
Poll Events
# Get all events
curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
"${HEADERS[@]}"
# Paginated — get next page of events
curl "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?page=page_abc123" \
"${HEADERS[@]}"
Provide Custom Tool Result
When the agent calls a custom tool, send the result back:
curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
"${HEADERS[@]}" \
-d '{
"events": [
{
"type": "user.custom_tool_result",
"custom_tool_use_id": "sevt_abc123",
"content": [{ "type": "text", "text": "No linting errors found." }]
}
]
}'
Interrupt a Running Session
curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
"${HEADERS[@]}" \
-d '{
"events": [
{
"type": "interrupt"
}
]
}'
Get Session Details
curl https://api.anthropic.com/v1/sessions/$SESSION_ID \
"${HEADERS[@]}"
List Sessions
curl https://api.anthropic.com/v1/sessions \
"${HEADERS[@]}"
Delete a Session
curl -X DELETE https://api.anthropic.com/v1/sessions/$SESSION_ID \
"${HEADERS[@]}"
Upload a File
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/file.txt" \
-F "purpose=agent"
List and Download Session Files
List files the agent wrote to /mnt/session/outputs/ during a session, then download them.
# List files associated with a session
curl "https://api.anthropic.com/v1/files?scope_id=$SESSION_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: files-api-2025-04-14,managed-agents-2026-04-01"
# Download a specific 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,managed-agents-2026-04-01" \
-o downloaded_file.txt
List Agents
curl https://api.anthropic.com/v1/agents \
"${HEADERS[@]}"
MCP Server Integration
# 1. Agent declares MCP server (no auth here — auth goes in a vault)
curl -X POST https://api.anthropic.com/v1/agents \
"${HEADERS[@]}" \
-d '{
"name": "MCP Agent",
"model": "claude-opus-4-8",
"mcp_servers": [
{ "type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse" }
],
"tools": [
{ "type": "agent_toolset_20260401" },
{ "type": "mcp_toolset", "mcp_server_name": "my-tools" }
]
}'
# 2. Session attaches vault containing credentials for that MCP server URL
curl -X POST https://api.anthropic.com/v1/sessions \
"${HEADERS[@]}" \
-d '{
"agent": "agent_abc123",
"environment_id": "env_abc123",
"vault_ids": ["vlt_abc123"]
}'
See shared/managed-agents-tools.md §Vaults for creating vaults and adding credentials.
Tool Configuration
curl -X POST https://api.anthropic.com/v1/agents \
"${HEADERS[@]}" \
-d '{
"name": "Restricted Agent",
"model": "claude-opus-4-8",
"tools": [
{
"type": "agent_toolset_20260401",
"default_config": { "enabled": true },
"configs": [
{ "name": "bash", "enabled": false }
]
}
]
}'
Note: The Go SDK supports the Claude API and beta tool use with
BetaToolRunner. Agent SDK is not yet available for Go.
Installation
go get github.com/anthropics/anthropic-sdk-go
Client Initialization
import (
"github.com/anthropics/anthropic-sdk-go"
"github.com/anthropics/anthropic-sdk-go/option"
)
// Default (uses ANTHROPIC_API_KEY env var)
client := anthropic.NewClient()
// Explicit API key
client := anthropic.NewClient(
option.WithAPIKey("your-api-key"),
)
Model Constants
The Go SDK provides typed model constants: anthropic.ModelClaudeOpus4_8, anthropic.ModelClaudeOpus4_7, anthropic.ModelClaudeSonnet4_6, anthropic.ModelClaudeHaiku4_5_20251001. Use ModelClaudeOpus4_8 unless the user specifies otherwise.
Basic Message Request
response, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_8,
MaxTokens: 16000,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What is the capital of France?")),
},
})
if err != nil {
log.Fatal(err)
}
for _, block := range response.Content {
switch variant := block.AsAny().(type) {
case anthropic.TextBlock:
fmt.Println(variant.Text)
}
}
Streaming
stream := client.Messages.NewStreaming(context.Background(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_6,
MaxTokens: 64000,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Write a haiku")),
},
})
for stream.Next() {
event := stream.Current()
switch eventVariant := event.AsAny().(type) {
case anthropic.ContentBlockDeltaEvent:
switch deltaVariant := eventVariant.Delta.AsAny().(type) {
case anthropic.TextDelta:
fmt.Print(deltaVariant.Text)
}
}
}
if err := stream.Err(); err != nil {
log.Fatal(err)
}
Accumulating the final message (there is no GetFinalMessage() on the stream):
stream := client.Messages.NewStreaming(ctx, params)
message := anthropic.Message{}
for stream.Next() {
message.Accumulate(stream.Current())
}
if err := stream.Err(); err != nil { log.Fatal(err) }
// message.Content now has the complete response
Tool Use
Tool Runner (Beta — Recommended)
Beta: The Go SDK provides BetaToolRunner for automatic tool use loops via the toolrunner package.
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
"github.com/anthropics/anthropic-sdk-go/toolrunner"
)
// Define tool input with jsonschema tags for automatic schema generation
type GetWeatherInput struct {
City string `json:"city" jsonschema:"required,description=The city name"`
}
// Create a tool with automatic schema generation from struct tags
weatherTool, err := toolrunner.NewBetaToolFromJSONSchema(
"get_weather",
"Get current weather for a city",
func(ctx context.Context, input GetWeatherInput) (anthropic.BetaToolResultBlockParamContentUnion, error) {
return anthropic.BetaToolResultBlockParamContentUnion{
OfText: &anthropic.BetaTextBlockParam{
Text: fmt.Sprintf("The weather in %s is sunny, 72°F", input.City),
},
}, nil
},
)
if err != nil {
log.Fatal(err)
}
// Create a tool runner that handles the conversation loop automatically
runner := client.Beta.Messages.NewToolRunner(
[]anthropic.BetaTool{weatherTool},
anthropic.BetaToolRunnerParams{
BetaMessageNewParams: anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus4_6,
MaxTokens: 16000,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What's the weather in Paris?")),
},
},
MaxIterations: 5,
},
)
// Run until Claude produces a final response
message, err := runner.RunToCompletion(context.Background())
if err != nil {
log.Fatal(err)
}
// RunToCompletion returns *BetaMessage; content is []BetaContentBlockUnion.
// Narrow via AsAny() switch — note the Beta-namespace types (BetaTextBlock,
// not TextBlock):
for _, block := range message.Content {
switch block := block.AsAny().(type) {
case anthropic.BetaTextBlock:
fmt.Println(block.Text)
}
}
Key features of the Go tool runner:
- Automatic schema generation from Go structs via
jsonschematags RunToCompletion()for simple one-shot usageAll()iterator for processing each message in the conversationNextMessage()for step-by-step iteration- Streaming variant via
NewToolRunnerStreaming()withAllStreaming()
Manual Loop
For fine-grained control over the agentic loop, define tools with ToolParam, check StopReason, execute tools yourself, and feed tool_result blocks back. This is the pattern when you need to intercept, validate, or log tool calls.
Derived from anthropic-sdk-go/examples/tools/main.go.
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
// 1. Define tools. ToolParam.InputSchema uses a map, no struct tags needed.
addTool := anthropic.ToolParam{
Name: "add",
Description: anthropic.String("Add two integers"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"a": map[string]any{"type": "integer"},
"b": map[string]any{"type": "integer"},
},
},
}
// ToolParam must be wrapped in ToolUnionParam for the Tools slice
tools := []anthropic.ToolUnionParam{{OfTool: &addTool}}
messages := []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What is 2 + 3?")),
}
for {
resp, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeSonnet4_6,
MaxTokens: 16000,
Messages: messages,
Tools: tools,
})
if err != nil {
log.Fatal(err)
}
// 2. Append the assistant response to history BEFORE processing tool calls.
// resp.ToParam() converts Message → MessageParam in one call.
messages = append(messages, resp.ToParam())
// 3. Walk content blocks. ContentBlockUnion is a flattened struct;
// use block.AsAny().(type) to switch on the actual variant.
toolResults := []anthropic.ContentBlockParamUnion{}
for _, block := range resp.Content {
switch variant := block.AsAny().(type) {
case anthropic.TextBlock:
fmt.Println(variant.Text)
case anthropic.ToolUseBlock:
// 4. Parse the tool input. Use variant.JSON.Input.Raw() to get the
// raw JSON — block.Input is json.RawMessage, not the parsed value.
var in struct {
A int `json:"a"`
B int `json:"b"`
}
if err := json.Unmarshal([]byte(variant.JSON.Input.Raw()), &in); err != nil {
log.Fatal(err)
}
result := fmt.Sprintf("%d", in.A+in.B)
// 5. NewToolResultBlock(toolUseID, content, isError) builds the
// ContentBlockParamUnion for you. block.ID is the tool_use_id.
toolResults = append(toolResults,
anthropic.NewToolResultBlock(block.ID, result, false))
}
}
// 6. Exit when Claude stops asking for tools
if resp.StopReason != anthropic.StopReasonToolUse {
break
}
// 7. Tool results go in a user message (variadic: all results in one turn)
messages = append(messages, anthropic.NewUserMessage(toolResults...))
}
}
Key API surface:
| Symbol | Purpose |
|---|---|
resp.ToParam() |
Convert Message response → MessageParam for history |
block.AsAny().(type) |
Type-switch on ContentBlockUnion variants |
variant.JSON.Input.Raw() |
Raw JSON string of tool input (for json.Unmarshal) |
anthropic.NewToolResultBlock(id, content, isError) |
Build tool_result block |
anthropic.NewUserMessage(blocks...) |
Wrap tool results as a user turn |
anthropic.StopReasonToolUse |
StopReason constant to check loop termination |
anthropic.ToolUnionParam{OfTool: &t} |
Wrap ToolParam in the union for Tools: |
Thinking
Enable Claude's internal reasoning by setting Thinking in MessageNewParams. The response will contain ThinkingBlock content before the final TextBlock.
Adaptive thinking is the recommended mode for Claude 4.6+ models. Claude decides dynamically when and how much to think. Combine with the effort parameter for cost-quality control.
Derived from anthropic-sdk-go/message.go (ThinkingConfigParamUnion, ThinkingConfigAdaptiveParam).
// There is no ThinkingConfigParamOfAdaptive helper — construct the union
// struct-literal directly and take the address of the variant.
adaptive := anthropic.ThinkingConfigAdaptiveParam{}
params := anthropic.MessageNewParams{
Model: anthropic.ModelClaudeSonnet4_6,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{OfAdaptive: &adaptive},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("How many r's in strawberry?")),
},
}
resp, err := client.Messages.New(context.Background(), params)
if err != nil {
log.Fatal(err)
}
// ThinkingBlock(s) precede TextBlock in content
for _, block := range resp.Content {
switch b := block.AsAny().(type) {
case anthropic.ThinkingBlock:
fmt.Println("[thinking]", b.Thinking)
case anthropic.TextBlock:
fmt.Println(b.Text)
}
}
Deprecated:
ThinkingConfigParamOfEnabled(budgetTokens)(fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above.
To disable: anthropic.ThinkingConfigParamUnion{OfDisabled: &anthropic.ThinkingConfigDisabledParam{}}.
Prompt Caching
System is []TextBlockParam; set CacheControl on the last block to cache tools + system together. For placement patterns and the silent-invalidator audit checklist, see shared/prompt-caching.md.
System: []anthropic.TextBlockParam{{
Text: longSystemPrompt,
CacheControl: anthropic.NewCacheControlEphemeralParam(), // default 5m TTL
}},
For 1-hour TTL: anthropic.CacheControlEphemeralParam{TTL: anthropic.CacheControlEphemeralTTLTTL1h}. There's also a top-level CacheControl on MessageNewParams that auto-places on the last cacheable block.
Verify hits via resp.Usage.CacheCreationInputTokens / resp.Usage.CacheReadInputTokens.
Server-Side Tools
Version-suffixed struct names with Param suffix. Name/Type are constant.* types — zero value marshals correctly, so {} works. Wrap in ToolUnionParam with the matching Of* field.
Tools: []anthropic.ToolUnionParam{
{OfWebSearchTool20260209: &anthropic.WebSearchTool20260209Param{}},
{OfBashTool20250124: &anthropic.ToolBash20250124Param{}},
{OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}},
{OfCodeExecutionTool20260120: &anthropic.CodeExecutionTool20260120Param{}},
},
Also available: WebFetchTool20260209Param, MemoryTool20250818Param, ToolSearchToolBm25_20251119Param, ToolSearchToolRegex20251119Param. For the advisor tool, use BetaAdvisorTool20260301Param in the beta namespace.
Stop Details
When StopReason is anthropic.StopReasonRefusal, the response includes structured StopDetails:
if resp.StopReason == anthropic.StopReasonRefusal {
fmt.Println("Category:", resp.StopDetails.Category) // "cyber" | "bio" | ""
fmt.Println("Explanation:", resp.StopDetails.Explanation)
}
PDF / Document Input
NewDocumentBlock generic helper accepts any source type. MediaType/Type are auto-set.
b64 := base64.StdEncoding.EncodeToString(pdfBytes)
msg := anthropic.NewUserMessage(
anthropic.NewDocumentBlock(anthropic.Base64PDFSourceParam{Data: b64}),
anthropic.NewTextBlock("Summarize this document"),
)
Other sources: URLPDFSourceParam{URL: "https://..."}, PlainTextSourceParam{Data: "..."}.
Files API (Beta)
Under client.Beta.Files. Method is Upload (NOT New/Create), params struct is BetaFileUploadParams. The File field takes an io.Reader; use anthropic.File() to attach a filename + content-type for the multipart encoding.
f, _ := os.Open("./upload_me.txt")
defer f.Close()
meta, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{
File: anthropic.File(f, "upload_me.txt", "text/plain"),
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFilesAPI2025_04_14},
})
// meta.ID is the file_id to reference in subsequent message requests
Other Beta.Files methods: List, Delete, Download, GetMetadata.
Context Editing / Compaction (Beta)
Use Beta.Messages.New with ContextManagement on BetaMessageNewParams. There is no NewBetaAssistantMessage — use .ToParam() for the round-trip.
params := anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus4_6, // also supported: ModelClaudeSonnet4_6
MaxTokens: 16000,
Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"},
ContextManagement: anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}},
},
},
Messages: []anthropic.BetaMessageParam{ /* ... */ },
}
resp, err := client.Beta.Messages.New(ctx, params)
if err != nil {
log.Fatal(err)
}
// Round-trip: append response to history via .ToParam()
params.Messages = append(params.Messages, resp.ToParam())
// Read compaction blocks from the response
for _, block := range resp.Content {
if c, ok := block.AsAny().(anthropic.BetaCompactionBlock); ok {
fmt.Println("compaction summary:", c.Content)
}
}
Other edit types: BetaClearToolUses20250919EditParam, BetaClearThinking20251015EditParam.
Note: The Java SDK supports the Claude API and beta tool use with annotated classes. Agent SDK is not yet available for Java.
Installation
Maven:
<dependency>
<groupId>com.anthropic</groupId>
<artifactId>anthropic-java</artifactId>
<version>2.34.0</version>
</dependency>
Gradle:
implementation("com.anthropic:anthropic-java:2.34.0")
Client Initialization
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
// Default (reads ANTHROPIC_API_KEY from environment)
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Explicit API key
AnthropicClient client = AnthropicOkHttpClient.builder()
.apiKey("your-api-key")
.build();
Basic Message Request
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.Model;
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_6)
.maxTokens(16000L)
.addUserMessage("What is the capital of France?")
.build();
Message response = client.messages().create(params);
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> System.out.println(textBlock.text()));
Streaming
import com.anthropic.core.http.StreamResponse;
import com.anthropic.models.messages.RawMessageStreamEvent;
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_6)
.maxTokens(64000L)
.addUserMessage("Write a haiku")
.build();
try (StreamResponse<RawMessageStreamEvent> streamResponse = client.messages().createStreaming(params)) {
streamResponse.stream()
.flatMap(event -> event.contentBlockDelta().stream())
.flatMap(deltaEvent -> deltaEvent.delta().text().stream())
.forEach(textDelta -> System.out.print(textDelta.text()));
}
Thinking
Adaptive thinking is the recommended mode for Claude 4.6+ models. Claude decides dynamically when and how much to think. The builder has a direct .thinking(ThinkingConfigAdaptive) overload — no manual union wrapping.
import com.anthropic.models.messages.ContentBlock;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.ThinkingConfigAdaptive;
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_4_6)
.maxTokens(16000L)
.thinking(ThinkingConfigAdaptive.builder().build())
.addUserMessage("Solve this step by step: 27 * 453")
.build();
for (ContentBlock block : client.messages().create(params).content()) {
block.thinking().ifPresent(t -> System.out.println("[thinking] " + t.thinking()));
block.text().ifPresent(t -> System.out.println(t.text()));
}
Deprecated:
ThinkingConfigEnabled.builder().budgetTokens(N)(and the.enabledThinking(N)shortcut) still works on Claude 4.6 but is deprecated. Use adaptive thinking above.
ContentBlock narrowing: .thinking() / .text() return Optional<T> — use .ifPresent(...) or .stream().flatMap(...). Alternative: isThinking() / asThinking() boolean+unwrap pairs (throws on wrong variant).
Tool Use (Beta)
The Java SDK supports beta tool use with annotated classes. Tool classes implement Supplier<String> for automatic execution via BetaToolRunner.
Tool Runner (automatic loop)
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.helpers.BetaToolRunner;
import com.fasterxml.jackson.annotation.JsonClassDescription;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;
import java.util.function.Supplier;
@JsonClassDescription("Get the weather in a given location")
static class GetWeather implements Supplier<String> {
@JsonPropertyDescription("The city and state, e.g. San Francisco, CA")
public String location;
@Override
public String get() {
return "The weather in " + location + " is sunny and 72°F";
}
}
BetaToolRunner toolRunner = client.beta().messages().toolRunner(
MessageCreateParams.builder()
.model("claude-opus-4-8")
.maxTokens(16000L)
.putAdditionalHeader("anthropic-beta", "structured-outputs-2025-11-13")
.addTool(GetWeather.class)
.addUserMessage("What's the weather in San Francisco?")
.build());
for (BetaMessage message : toolRunner) {
System.out.println(message);
}
Memory Tool
The Java SDK provides BetaMemoryToolHandler for implementing the memory tool backend. You supply a handler that manages file storage, and the BetaToolRunner handles memory tool calls automatically.
import com.anthropic.helpers.BetaMemoryToolHandler;
import com.anthropic.helpers.BetaToolRunner;
import com.anthropic.models.beta.messages.BetaMemoryTool20250818;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.beta.messages.ToolRunnerCreateParams;
// Implement BetaMemoryToolHandler with your storage backend (e.g., filesystem)
BetaMemoryToolHandler memoryHandler = new FileSystemMemoryToolHandler(sandboxRoot);
MessageCreateParams createParams = MessageCreateParams.builder()
.model("claude-opus-4-8")
.maxTokens(4096L)
.addTool(BetaMemoryTool20250818.builder().build())
.addUserMessage("Remember that my favorite color is blue")
.build();
BetaToolRunner toolRunner = client.beta().messages().toolRunner(
ToolRunnerCreateParams.builder()
.betaMemoryToolHandler(memoryHandler)
.initialMessageParams(createParams)
.build());
for (BetaMessage message : toolRunner) {
System.out.println(message);
}
See the shared memory tool concepts for more details on the memory tool.
Non-Beta Tool Declaration (manual JSON schema)
Tool.InputSchema.Properties is a freeform Map<String, JsonValue> wrapper — build property schemas via putAdditionalProperty. type: "object" is the default. The builder has a direct .addTool(Tool) overload that wraps in ToolUnion automatically.
import com.anthropic.core.JsonValue;
import com.anthropic.models.messages.Tool;
Tool tool = Tool.builder()
.name("get_weather")
.description("Get the current weather in a given location")
.inputSchema(Tool.InputSchema.builder()
.properties(Tool.InputSchema.Properties.builder()
.putAdditionalProperty("location", JsonValue.from(Map.of("type", "string")))
.build())
.required(List.of("location"))
.build())
.build();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_4_6)
.maxTokens(16000L)
.addTool(tool)
.addUserMessage("Weather in Paris?")
.build();
For manual tool loops, handle tool_use blocks in the response, send tool_result back, loop until stop_reason is "end_turn". See shared tool use concepts.
Building MessageParam with Content Blocks (Tool Result Round-Trip)
MessageParam.Content is an inner union class (string | list). Use the builder's .contentOfBlockParams(List<ContentBlockParam>) alias — there is NO separate MessageParamContent class with a static ofBlockParams:
import com.anthropic.models.messages.MessageParam;
import com.anthropic.models.messages.ContentBlockParam;
import com.anthropic.models.messages.ToolResultBlockParam;
List<ContentBlockParam> results = List.of(
ContentBlockParam.ofToolResult(ToolResultBlockParam.builder()
.toolUseId(toolUseBlock.id())
.content(yourResultString)
.build())
);
MessageParam toolResultMsg = MessageParam.builder()
.role(MessageParam.Role.USER)
.contentOfBlockParams(results) // builder alias for Content.ofBlockParams(...)
.build();
Effort Parameter
Effort is nested inside OutputConfig — there is NO .effort() directly on MessageCreateParams.Builder.
import com.anthropic.models.messages.OutputConfig;
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.HIGH) // or LOW, MEDIUM, MAX
.build())
Combine with Thinking = ThinkingConfigAdaptive for cost-quality control.
Prompt Caching
System message as a list of TextBlockParam with CacheControlEphemeral. Use .systemOfTextBlockParams(...) — the plain .system(String) overload can't carry cache control. For placement patterns and the silent-invalidator audit checklist, see shared/prompt-caching.md.
import com.anthropic.models.messages.TextBlockParam;
import com.anthropic.models.messages.CacheControlEphemeral;
.systemOfTextBlockParams(List.of(
TextBlockParam.builder()
.text(longSystemPrompt)
.cacheControl(CacheControlEphemeral.builder()
.ttl(CacheControlEphemeral.Ttl.TTL_1H) // optional; also TTL_5M
.build())
.build()))
There's also a top-level .cacheControl(CacheControlEphemeral) on MessageCreateParams.Builder and on Tool.builder().
Verify hits via response.usage().cacheCreationInputTokens() / response.usage().cacheReadInputTokens().
Token Counting
import com.anthropic.models.messages.MessageCountTokensParams;
long tokens = client.messages().countTokens(
MessageCountTokensParams.builder()
.model(Model.CLAUDE_SONNET_4_6)
.addUserMessage("Hello")
.build()
).inputTokens();
Structured Output
The class-based overload auto-derives the JSON schema from your POJO and gives you a typed .text() return — no manual schema, no manual parsing.
import com.anthropic.models.messages.StructuredMessageCreateParams;
record Book(String title, String author) {}
record BookList(List<Book> books) {}
StructuredMessageCreateParams<BookList> params = MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_4_6)
.maxTokens(16000L)
.outputConfig(BookList.class) // returns a typed builder
.addUserMessage("List 3 classic novels")
.build();
client.messages().create(params).content().stream()
.flatMap(cb -> cb.text().stream())
.forEach(typed -> {
// typed.text() returns BookList, not String
for (Book b : typed.text().books()) System.out.println(b.title());
});
Supports Jackson annotations: @JsonPropertyDescription, @JsonIgnore, @ArraySchema(minItems=...). Manual schema path: OutputConfig.builder().format(JsonOutputFormat.builder().schema(...).build()).
PDF / Document Input
DocumentBlockParam builder has source shortcuts. Wrap in ContentBlockParam.ofDocument() and pass via .addUserMessageOfBlockParams().
import com.anthropic.models.messages.DocumentBlockParam;
import com.anthropic.models.messages.ContentBlockParam;
import com.anthropic.models.messages.TextBlockParam;
DocumentBlockParam doc = DocumentBlockParam.builder()
.base64Source(base64String) // or .urlSource("https://...") or .textSource("...")
.title("My Document") // optional
.build();
.addUserMessageOfBlockParams(List.of(
ContentBlockParam.ofDocument(doc),
ContentBlockParam.ofText(TextBlockParam.builder().text("Summarize this").build())))
Server-Side Tools
Version-suffixed types; name/type auto-set by builder. Direct .addTool() overloads exist for every type — no manual ToolUnion wrapping.
import com.anthropic.models.messages.WebSearchTool20260209;
import com.anthropic.models.messages.ToolBash20250124;
import com.anthropic.models.messages.ToolTextEditor20250728;
import com.anthropic.models.messages.CodeExecutionTool20260120;
.addTool(WebSearchTool20260209.builder()
.maxUses(5L) // optional
.allowedDomains(List.of("example.com")) // optional
.build())
.addTool(ToolBash20250124.builder().build())
.addTool(ToolTextEditor20250728.builder().build())
.addTool(CodeExecutionTool20260120.builder().build())
Also available: WebFetchTool20260209, MemoryTool20250818, ToolSearchToolBm25_20251119. For the advisor tool, use BetaAdvisorTool20260301 in the beta namespace.
Beta namespace (MCP, compaction)
For beta-only features use com.anthropic.models.beta.messages.* — class names have a Beta prefix AND live in the beta package. The beta MessageCreateParams.Builder has direct .addTool(BetaToolBash20250124) overloads AND .addMcpServer():
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.beta.messages.BetaToolBash20250124;
import com.anthropic.models.beta.messages.BetaCodeExecutionTool20260120;
import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_6)
.maxTokens(16000L)
.addBeta("mcp-client-2025-11-20")
.addTool(BetaToolBash20250124.builder().build())
.addTool(BetaCodeExecutionTool20260120.builder().build())
.addMcpServer(BetaRequestMcpServerUrlDefinition.builder()
.name("my-server")
.url("https://example.com/mcp")
.build())
.addUserMessage("...")
.build();
client.beta().messages().create(params);
BetaTool* types are NOT interchangeable with non-beta Tool* — pick one namespace per request.
Reading server-tool blocks in the response: ServerToolUseBlock has .id(), .name() (enum), and ._input() returning raw JsonValue — there is NO typed .input(). For code execution results, unwrap two levels:
for (ContentBlock block : response.content()) {
block.serverToolUse().ifPresent(stu -> {
System.out.println("tool: " + stu.name() + " input: " + stu._input());
});
block.codeExecutionToolResult().ifPresent(r -> {
r.content().resultBlock().ifPresent(result -> {
System.out.println("stdout: " + result.stdout());
System.out.println("stderr: " + result.stderr());
System.out.println("exit: " + result.returnCode());
});
});
}
Stop Details
When stopReason() is "refusal", the response includes structured stopDetails():
response.stopDetails().ifPresent(details -> {
System.out.println("Category: " + details.category());
System.out.println("Explanation: " + details.explanation());
});
Error Type
AnthropicServiceException exposes .errorType() returning Optional<ErrorType> for programmatic error classification:
try {
client.messages().create(params);
} catch (AnthropicServiceException e) {
e.errorType().ifPresent(type ->
System.out.println("Error type: " + type) // RATE_LIMIT_ERROR, OVERLOADED_ERROR, etc.
);
}
Files API (Beta)
Under client.beta().files(). File references in messages need the beta message types (non-beta DocumentBlockParam.Source has no file-ID variant).
import com.anthropic.models.beta.files.FileUploadParams;
import com.anthropic.models.beta.files.FileMetadata;
import com.anthropic.models.beta.messages.BetaRequestDocumentBlock;
import java.nio.file.Paths;
FileMetadata meta = client.beta().files().upload(
FileUploadParams.builder()
.file(Paths.get("/path/to/doc.pdf")) // or .file(InputStream) or .file(byte[])
.build());
// Reference in a beta message:
BetaRequestDocumentBlock doc = BetaRequestDocumentBlock.builder()
.fileSource(meta.id())
.build();
Other methods: .list(), .delete(String fileId), .download(String fileId), .retrieveMetadata(String fileId).
Note: The PHP SDK is the official Anthropic SDK for PHP. A beta tool runner is available via
$client->beta->messages->toolRunner(). Structured output helpers are supported viaStructuredOutputModelclasses. Agent SDK is not available. Bedrock, Vertex AI, and Foundry clients are supported.
Installation
composer require "anthropic-ai/sdk"
Client Initialization
use Anthropic\Client;
// Using API key from environment variable
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
Amazon Bedrock
use Anthropic\Bedrock;
// Constructor is private — use the static factory. Reads AWS credentials from env.
$client = Bedrock\Client::fromEnvironment(region: 'us-east-1');
Google Vertex AI
use Anthropic\Vertex;
// Constructor is private. Parameter is `location`, not `region`.
$client = Vertex\Client::fromEnvironment(
location: 'us-east5',
projectId: 'my-project-id',
);
Anthropic Foundry
use Anthropic\Foundry;
// Constructor is private. baseUrl or resource is required.
$client = Foundry\Client::withCredentials(
authToken: getenv('ANTHROPIC_FOUNDRY_AUTH_TOKEN'),
baseUrl: 'https://<resource>.services.ai.azure.com/anthropic',
);
Basic Message Request
$message = $client->messages->create(
model: 'claude-opus-4-8',
maxTokens: 16000,
messages: [
['role' => 'user', 'content' => 'What is the capital of France?'],
],
);
// content is an array of polymorphic blocks (TextBlock, ToolUseBlock,
// ThinkingBlock). Accessing ->text on content[0] without checking the block
// type will throw if the first block is not a TextBlock (e.g., when extended
// thinking is enabled and a ThinkingBlock comes first). Always guard:
foreach ($message->content as $block) {
if ($block->type === 'text') {
echo $block->text;
}
}
If you only want the first text block:
foreach ($message->content as $block) {
if ($block->type === 'text') {
echo $block->text;
break;
}
}
Streaming
Requires SDK v0.5.0+. v0.4.0 and earlier used a single
$paramsarray; calling with named parameters throwsUnknown named parameter $model. Upgrade:composer require "anthropic-ai/sdk:^0.7"
use Anthropic\Messages\RawContentBlockDeltaEvent;
use Anthropic\Messages\TextDelta;
$stream = $client->messages->createStream(
model: 'claude-opus-4-8',
maxTokens: 64000,
messages: [
['role' => 'user', 'content' => 'Write a haiku'],
],
);
foreach ($stream as $event) {
if ($event instanceof RawContentBlockDeltaEvent && $event->delta instanceof TextDelta) {
echo $event->delta->text;
}
}
Tool Use
Tool Runner (Beta)
Beta: The PHP SDK provides a tool runner via $client->beta->messages->toolRunner(). Define tools with BetaRunnableTool — a definition array plus a run closure:
use Anthropic\Lib\Tools\BetaRunnableTool;
$weatherTool = new BetaRunnableTool(
definition: [
'name' => 'get_weather',
'description' => 'Get the current weather for a location.',
'input_schema' => [
'type' => 'object',
'properties' => [
'location' => ['type' => 'string', 'description' => 'City and state'],
],
'required' => ['location'],
],
],
run: function (array $input): string {
return "The weather in {$input['location']} is sunny and 72°F.";
},
);
$runner = $client->beta->messages->toolRunner(
maxTokens: 16000,
messages: [['role' => 'user', 'content' => 'What is the weather in Paris?']],
model: 'claude-opus-4-8',
tools: [$weatherTool],
);
foreach ($runner as $message) {
foreach ($message->content as $block) {
if ($block->type === 'text') {
echo $block->text;
}
}
}
Manual Loop
Tools are passed as arrays. The SDK uses camelCase keys (inputSchema, toolUseID, stopReason) and auto-maps to the API's snake_case on the wire — since v0.5.0. See shared tool use concepts for the loop pattern.
use Anthropic\Messages\ToolUseBlock;
$tools = [
[
'name' => 'get_weather',
'description' => 'Get the current weather in a given location',
'inputSchema' => [ // camelCase, not input_schema
'type' => 'object',
'properties' => [
'location' => ['type' => 'string', 'description' => 'City and state'],
],
'required' => ['location'],
],
],
];
$messages = [['role' => 'user', 'content' => 'What is the weather in SF?']];
$response = $client->messages->create(
model: 'claude-opus-4-8',
maxTokens: 16000,
tools: $tools,
messages: $messages,
);
while ($response->stopReason === 'tool_use') { // camelCase property
$toolResults = [];
foreach ($response->content as $block) {
if ($block instanceof ToolUseBlock) {
// $block->name : string — tool name to dispatch on
// $block->input : array<string,mixed> — parsed JSON input
// $block->id : string — pass back as toolUseID
$result = executeYourTool($block->name, $block->input);
$toolResults[] = [
'type' => 'tool_result',
'toolUseID' => $block->id, // camelCase, not tool_use_id
'content' => $result,
];
}
}
// Append assistant turn + user turn with tool results
$messages[] = ['role' => 'assistant', 'content' => $response->content];
$messages[] = ['role' => 'user', 'content' => $toolResults];
$response = $client->messages->create(
model: 'claude-opus-4-8',
maxTokens: 16000,
tools: $tools,
messages: $messages,
);
}
// Final text response
foreach ($response->content as $block) {
if ($block->type === 'text') {
echo $block->text;
}
}
$block->type === 'tool_use' also works; instanceof ToolUseBlock narrows for PHPStan.
Extended Thinking
Adaptive thinking is the recommended mode for Claude 4.6+ models. Claude decides dynamically when and how much to think.
use Anthropic\Messages\ThinkingBlock;
$message = $client->messages->create(
model: 'claude-opus-4-8',
maxTokens: 16000,
thinking: ['type' => 'adaptive'],
messages: [
['role' => 'user', 'content' => 'Solve: 27 * 453'],
],
);
// ThinkingBlock(s) precede TextBlock in content
foreach ($message->content as $block) {
if ($block instanceof ThinkingBlock) {
echo "Thinking:\n{$block->thinking}\n\n";
// $block->signature is an opaque string — preserve verbatim if
// passing thinking blocks back in multi-turn conversations
} elseif ($block->type === 'text') {
echo "Answer: {$block->text}\n";
}
}
Deprecated:
['type' => 'enabled', 'budgetTokens' => N](fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above.
$block->type === 'thinking' also works for the check; instanceof narrows for PHPStan.
Prompt Caching
system: takes an array of text blocks; set cacheControl on the last block. Array-shape syntax (camelCase keys) is idiomatic. For placement patterns and the silent-invalidator audit checklist, see shared/prompt-caching.md.
$message = $client->messages->create(
model: 'claude-opus-4-8',
maxTokens: 16000,
system: [
['type' => 'text', 'text' => $longSystemPrompt, 'cacheControl' => ['type' => 'ephemeral']],
],
messages: [['role' => 'user', 'content' => 'Summarize the key points']],
);
For 1-hour TTL: 'cacheControl' => ['type' => 'ephemeral', 'ttl' => '1h']. There's also a top-level cacheControl: on messages->create(...) that auto-places on the last cacheable block.
Verify hits via $message->usage->cacheCreationInputTokens / $message->usage->cacheReadInputTokens.
Structured Outputs
Using StructuredOutputModel (Recommended)
Define a PHP class implementing StructuredOutputModel and pass it as outputConfig:
use Anthropic\Lib\Contracts\StructuredOutputModel;
use Anthropic\Lib\Concerns\StructuredOutputModelTrait;
use Anthropic\Lib\Attributes\Constrained;
class Person implements StructuredOutputModel
{
use StructuredOutputModelTrait;
#[Constrained(description: 'Full name')]
public string $name;
public int $age;
public ?string $email = null; // nullable = optional field
}
$message = $client->messages->create(
model: 'claude-opus-4-8',
maxTokens: 16000,
messages: [['role' => 'user', 'content' => 'Generate a profile for Alice, age 30']],
outputConfig: ['format' => Person::class],
);
$person = $message->parsedOutput(); // Person instance
echo $person->name;
Types are inferred from PHP type hints. Use #[Constrained(description: '...')] to add descriptions. Nullable properties (?string) become optional fields.
Raw Schema
$message = $client->messages->create(
model: 'claude-opus-4-8',
maxTokens: 16000,
messages: [['role' => 'user', 'content' => 'Extract: John (john@co.com), Enterprise plan']],
outputConfig: [
'format' => [
'type' => 'json_schema',
'schema' => [
'type' => 'object',
'properties' => [
'name' => ['type' => 'string'],
'email' => ['type' => 'string'],
'plan' => ['type' => 'string'],
],
'required' => ['name', 'email', 'plan'],
'additionalProperties' => false,
],
],
],
);
// First text block contains valid JSON
foreach ($message->content as $block) {
if ($block->type === 'text') {
$data = json_decode($block->text, true);
break;
}
}
Beta Features & Server-Side Tools
betas: is NOT a param on $client->messages->create() — it only exists on the beta namespace. Use it for features that need an explicit opt-in header:
use Anthropic\Beta\Messages\BetaRequestMCPServerURLDefinition;
$response = $client->beta->messages->create(
model: 'claude-opus-4-8',
maxTokens: 16000,
mcpServers: [
BetaRequestMCPServerURLDefinition::with(
name: 'my-server',
url: 'https://example.com/mcp',
),
],
betas: ['mcp-client-2025-11-20'], // only valid on ->beta->messages
messages: [['role' => 'user', 'content' => 'Use the MCP tools']],
);
Server-side tools (bash, web_search, text_editor, code_execution) are GA and work on both paths — Anthropic\Messages\ToolBash20250124 / WebSearchTool20260209 / ToolTextEditor20250728 / CodeExecutionTool20260120 for non-beta, Anthropic\Beta\Messages\BetaToolBash20250124 / BetaWebSearchTool20260209 / BetaToolTextEditor20250728 / BetaCodeExecutionTool20260120 for beta. No betas: header needed for these.
Stop Details
When stopReason is 'refusal', the response includes structured stopDetails:
if ($message->stopReason === 'refusal' && $message->stopDetails !== null) {
echo "Category: " . $message->stopDetails->category . "\n"; // "cyber" | "bio" | null
echo "Explanation: " . $message->stopDetails->explanation . "\n";
}
Error Type
APIStatusException exposes a ->type property for programmatic error classification:
try {
$client->messages->create(...);
} catch (\Anthropic\Core\Exceptions\APIStatusException $e) {
echo $e->type?->value; // "rate_limit_error", "overloaded_error", etc.
}
Installation
pip install anthropic
Client Initialization
import anthropic
# Default — resolves credentials from the environment:
# ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN, or an `ant auth login` profile.
# Prefer this for local dev; don't hardcode a key.
client = anthropic.Anthropic()
# Explicit API key (only when you must inject a specific key)
client = anthropic.Anthropic(api_key="your-api-key")
# Async client
async_client = anthropic.AsyncAnthropic()
Client Configuration
Per-request overrides
Use with_options() to override client settings for a single call without mutating the client:
client.with_options(timeout=5.0, max_retries=5).messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
)
Timeouts
Default request timeout is 10 minutes. Pass a float (seconds) or an httpx.Timeout for granular control. On timeout the SDK raises anthropic.APITimeoutError (and retries per max_retries).
import httpx
client = anthropic.Anthropic(timeout=20.0)
client = anthropic.Anthropic(
timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)
Retries
The SDK auto-retries connection errors, 408, 409, 429, and ≥500 with exponential backoff (default 2 retries). Set max_retries on the client or via with_options(); max_retries=0 disables.
Async performance (aiohttp backend)
For high-concurrency async workloads, install anthropic[aiohttp] and pass DefaultAioHttpClient instead of the default httpx backend:
from anthropic import AsyncAnthropic, DefaultAioHttpClient
async with AsyncAnthropic(http_client=DefaultAioHttpClient()) as client:
...
Custom HTTP client (proxy, base URL)
Use DefaultHttpxClient / DefaultAsyncHttpxClient — not raw httpx.Client — so the SDK's default timeouts and connection limits are preserved:
from anthropic import Anthropic, DefaultHttpxClient
client = Anthropic(
base_url="http://my.test.server.example.com:8083", # or ANTHROPIC_BASE_URL env var
http_client=DefaultHttpxClient(proxy="http://my.test.proxy.example.com"),
)
Logging
Set ANTHROPIC_LOG=debug (or info) to enable SDK logging via the standard logging module.
Basic Message Request
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
messages=[
{"role": "user", "content": "What is the capital of France?"}
]
)
# response.content is a list of content block objects (TextBlock, ThinkingBlock,
# ToolUseBlock, ...). Check .type before accessing .text.
for block in response.content:
if block.type == "text":
print(block.text)
System Prompts
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
system="You are a helpful coding assistant. Always provide examples in Python.",
messages=[{"role": "user", "content": "How do I read a JSON file?"}]
)
Mid-conversation system messages (beta, model-gated)
For operator instructions that arrive mid-conversation (mode switches, injected state), append {"role": "system", ...} to messages instead of editing top-level system — this preserves the cached prefix and carries operator authority. Must follow a user message; cannot be messages[0]. Unsupported models return a 400 (role 'system' is not supported on this model). See shared/prompt-caching.md for when to use this vs. top-level system.
response = client.messages.create(
model=MODEL_ID, # must support mid-conversation system messages
max_tokens=16000,
system=[{"type": "text", "text": STABLE_SYSTEM, "cache_control": {"type": "ephemeral"}}],
messages=history + [
{"role": "user", "content": user_message},
{"role": "system", "content": "Terse mode enabled — keep responses under 40 words."},
],
extra_headers={"anthropic-beta": "mid-conversation-system-2026-04-07"},
)
Vision (Images)
Base64
import base64
with open("image.png", "rb") as f:
image_data = base64.standard_b64encode(f.read()).decode("utf-8")
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
messages=[{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": image_data
}
},
{"type": "text", "text": "What's in this image?"}
]
}]
)
URL
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
messages=[{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "url",
"url": "https://example.com/image.png"
}
},
{"type": "text", "text": "Describe this image"}
]
}]
)
Prompt Caching
Cache large context to reduce costs (up to 90% savings). Caching is a prefix match — any byte change anywhere in the prefix invalidates everything after it. For placement patterns, architectural guidance (frozen system prompt, deterministic tool order, where to put volatile content), and the silent-invalidator audit checklist, read shared/prompt-caching.md.
Automatic Caching (Recommended)
Use top-level cache_control to automatically cache the last cacheable block in the request — no need to annotate individual content blocks:
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
cache_control={"type": "ephemeral"}, # auto-caches the last cacheable block
system="You are an expert on this large document...",
messages=[{"role": "user", "content": "Summarize the key points"}]
)
Manual Cache Control
For fine-grained control, add cache_control to specific content blocks:
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
system=[{
"type": "text",
"text": "You are an expert on this large document...",
"cache_control": {"type": "ephemeral"} # default TTL is 5 minutes
}],
messages=[{"role": "user", "content": "Summarize the key points"}]
)
# With explicit TTL (time-to-live)
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
system=[{
"type": "text",
"text": "You are an expert on this large document...",
"cache_control": {"type": "ephemeral", "ttl": "1h"} # 1 hour TTL
}],
messages=[{"role": "user", "content": "Summarize the key points"}]
)
Verifying Cache Hits
print(response.usage.cache_creation_input_tokens) # tokens written to cache (~1.25x cost)
print(response.usage.cache_read_input_tokens) # tokens served from cache (~0.1x cost)
print(response.usage.input_tokens) # uncached tokens (full cost)
If cache_read_input_tokens is zero across repeated identical-prefix requests, a silent invalidator is at work — datetime.now() or a UUID in the system prompt, unsorted json.dumps(), or a varying tool set. See shared/prompt-caching.md for the full audit table.
Extended Thinking
Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6: Use adaptive thinking.
budget_tokensis removed on Opus 4.8 and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. Older models: Usethinking: {type: "enabled", budget_tokens: N}(must be <max_tokens, min 1024).
# Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended)
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
thinking={"type": "adaptive"},
output_config={"effort": "high"}, # low | medium | high | max
messages=[{"role": "user", "content": "Solve this step by step..."}]
)
# Access thinking and response
for block in response.content:
if block.type == "thinking":
print(f"Thinking: {block.thinking}")
elif block.type == "text":
print(f"Response: {block.text}")
Error Handling
import anthropic
try:
response = client.messages.create(...)
except anthropic.BadRequestError as e:
print(f"Bad request: {e.message}")
except anthropic.AuthenticationError:
print("Invalid API key")
except anthropic.PermissionDeniedError:
print("API key lacks required permissions")
except anthropic.NotFoundError:
print("Invalid model or endpoint")
except anthropic.RateLimitError as e:
retry_after = int(e.response.headers.get("retry-after", "60"))
print(f"Rate limited. Retry after {retry_after}s.")
except anthropic.APIStatusError as e:
if e.status_code >= 500:
print(f"Server error ({e.status_code}). Retry later.")
else:
print(f"API error: {e.message}")
except anthropic.APIConnectionError:
print("Network error. Check internet connection.")
Response Helpers
Every response object exposes _request_id (populated from the request-id header) — log it when reporting failures to Anthropic. Despite the underscore prefix, this property is public.
message = client.messages.create(...)
print(message._request_id) # req_018EeWyXxfu5pfWkrYcMdjWG
print(message.to_json()) # serialize the Pydantic model
print(message.to_dict()) # plain dict
To access raw headers or other response metadata, use .with_raw_response:
raw = client.messages.with_raw_response.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
)
print(raw.headers.get("request-id"))
message = raw.parse() # the Message object messages.create() would have returned
Multi-Turn Conversations
The API is stateless — send the full conversation history each time.
class ConversationManager:
"""Manage multi-turn conversations with the Claude API."""
def __init__(self, client: anthropic.Anthropic, model: str, system: str = None):
self.client = client
self.model = model
self.system = system
self.messages = []
def send(self, user_message: str, **kwargs) -> str:
"""Send a message and get a response."""
self.messages.append({"role": "user", "content": user_message})
response = self.client.messages.create(
model=self.model,
max_tokens=kwargs.get("max_tokens", 16000),
system=self.system,
messages=self.messages,
**kwargs
)
assistant_message = next(
(b.text for b in response.content if b.type == "text"), ""
)
self.messages.append({"role": "assistant", "content": assistant_message})
return assistant_message
# Usage
conversation = ConversationManager(
client=anthropic.Anthropic(),
model="claude-opus-4-8",
system="You are a helpful assistant."
)
response1 = conversation.send("My name is Alice.")
response2 = conversation.send("What's my name?") # Claude remembers "Alice"
Rules:
- Consecutive same-role messages are allowed — the API combines them into a single turn
- First message must be
user role: "system"messages are allowed mid-conversation under themid-conversation-system-2026-04-07beta on supporting models — see § Mid-conversation system messages above
Compaction (long conversations)
Beta, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6. When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a
compactionblock; you must pass it back on subsequent requests — appendresponse.content, not just the text.
import anthropic
client = anthropic.Anthropic()
messages = []
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-8",
max_tokens=16000,
messages=messages,
context_management={
"edits": [{"type": "compact_20260112"}]
}
)
# Append full content — compaction blocks must be preserved
messages.append({"role": "assistant", "content": response.content})
return next(block.text for block in response.content if block.type == "text")
# Compaction triggers automatically when context grows large
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"))
Stop Reasons
The stop_reason field in the response indicates why the model stopped generating:
| Value | Meaning |
|---|---|
end_turn |
Claude finished its response naturally |
max_tokens |
Hit the max_tokens limit — increase it or use streaming |
stop_sequence |
Hit a custom stop sequence |
tool_use |
Claude wants to call a tool — execute it and continue |
pause_turn |
Model paused and can be resumed (agentic flows) |
refusal |
Claude refused for safety reasons — check stop_details |
Structured Stop Details
When stop_reason is "refusal", the response includes a stop_details object with structured information about the refusal:
if response.stop_reason == "refusal" and response.stop_details:
print(f"Category: {response.stop_details.category}") # "cyber" | "bio" | None
print(f"Explanation: {response.stop_details.explanation}")
Cost Optimization Strategies
1. Use Prompt Caching for Repeated Context
# Automatic caching (simplest — caches the last cacheable block)
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
cache_control={"type": "ephemeral"},
system=large_document_text, # e.g., 50KB of context
messages=[{"role": "user", "content": "Summarize the key points"}]
)
# First request: full cost
# Subsequent requests: ~90% cheaper for cached portion
2. Choose the Right Model
# Default to Opus for most tasks
response = client.messages.create(
model="claude-opus-4-8", # $5.00/$25.00 per 1M tokens
max_tokens=16000,
messages=[{"role": "user", "content": "Explain quantum computing"}]
)
# Use Sonnet for high-volume production workloads
standard_response = client.messages.create(
model="claude-sonnet-4-6", # $3.00/$15.00 per 1M tokens
max_tokens=16000,
messages=[{"role": "user", "content": "Summarize this document"}]
)
# Use Haiku only for simple, speed-critical tasks
simple_response = client.messages.create(
model="claude-haiku-4-5", # $1.00/$5.00 per 1M tokens
max_tokens=256,
messages=[{"role": "user", "content": "Classify this as positive or negative"}]
)
3. Use Token Counting Before Requests
count_response = client.messages.count_tokens(
model="claude-opus-4-8",
messages=messages,
system=system
)
estimated_input_cost = count_response.input_tokens * 0.000005 # $5/1M tokens
print(f"Estimated input cost: ${estimated_input_cost:.4f}")
Retry with Exponential Backoff
Note: The Anthropic SDK automatically retries rate limit (429) and server errors (5xx) with exponential backoff. You can configure this with
max_retries(default: 2). Only implement custom retry logic if you need behavior beyond what the SDK provides.
import time
import random
import anthropic
def call_with_retry(
client: anthropic.Anthropic,
max_retries: int = 5,
base_delay: float = 1.0,
max_delay: float = 60.0,
**kwargs
):
"""Call the API with exponential backoff retry."""
last_exception = None
for attempt in range(max_retries):
try:
return client.messages.create(**kwargs)
except anthropic.RateLimitError as e:
last_exception = e
except anthropic.APIStatusError as e:
if e.status_code >= 500:
last_exception = e
else:
raise # Client errors (4xx except 429) should not be retried
delay = min(base_delay * (2 ** attempt) + random.uniform(0, 1), max_delay)
print(f"Retry {attempt + 1}/{max_retries} after {delay:.1f}s")
time.sleep(delay)
raise last_exception
The Batches API (POST /v1/messages/batches) processes Messages API requests asynchronously at 50% of standard prices.
Key Facts
- Up to 100,000 requests or 256 MB per batch
- Most batches complete within 1 hour; maximum 24 hours
- Results available for 29 days after creation
- 50% cost reduction on all token usage
- All Messages API features supported (vision, tools, caching, etc.)
Create a Batch
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="request-1",
params=MessageCreateParamsNonStreaming(
model="claude-opus-4-8",
max_tokens=16000,
messages=[{"role": "user", "content": "Summarize climate change impacts"}]
)
),
Request(
custom_id="request-2",
params=MessageCreateParamsNonStreaming(
model="claude-opus-4-8",
max_tokens=16000,
messages=[{"role": "user", "content": "Explain quantum computing basics"}]
)
),
]
)
print(f"Batch ID: {message_batch.id}")
print(f"Status: {message_batch.processing_status}")
Poll for Completion
import time
while True:
batch = client.messages.batches.retrieve(message_batch.id)
if batch.processing_status == "ended":
break
print(f"Status: {batch.processing_status}, processing: {batch.request_counts.processing}")
time.sleep(60)
print("Batch complete!")
print(f"Succeeded: {batch.request_counts.succeeded}")
print(f"Errored: {batch.request_counts.errored}")
Retrieve Results
Note: Examples below use
match/casesyntax, requiring Python 3.10+. For earlier versions, useif/elifchains instead.
for result in client.messages.batches.results(message_batch.id):
match result.result.type:
case "succeeded":
msg = result.result.message
text = next((b.text for b in msg.content if b.type == "text"), "")
print(f"[{result.custom_id}] {text[:100]}")
case "errored":
if result.result.error.type == "invalid_request":
print(f"[{result.custom_id}] Validation error - fix request and retry")
else:
print(f"[{result.custom_id}] Server error - safe to retry")
case "canceled":
print(f"[{result.custom_id}] Canceled")
case "expired":
print(f"[{result.custom_id}] Expired - resubmit")
Cancel a Batch
cancelled = client.messages.batches.cancel(message_batch.id)
print(f"Status: {cancelled.processing_status}") # "canceling"
List Batches (auto-pagination)
Iterating the return value of any list() call auto-paginates across all pages — do not index into .data if you want the full set:
for batch in client.messages.batches.list(limit=20):
print(batch.id, batch.processing_status)
For manual control, use first_page.has_next_page() / first_page.get_next_page() / first_page.next_page_info(); first_page.data holds the current page's items and first_page.last_id is the cursor.
Batch with Prompt Caching
shared_system = [
{"type": "text", "text": "You are a literary analyst."},
{
"type": "text",
"text": large_document_text, # Shared across all requests
"cache_control": {"type": "ephemeral"}
}
]
message_batch = client.messages.batches.create(
requests=[
Request(
custom_id=f"analysis-{i}",
params=MessageCreateParamsNonStreaming(
model="claude-opus-4-8",
max_tokens=16000,
system=shared_system,
messages=[{"role": "user", "content": question}]
)
)
for i, question in enumerate(questions)
]
)
Full End-to-End Example
import anthropic
import time
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request
client = anthropic.Anthropic()
# 1. Prepare requests
items_to_classify = [
"The product quality is excellent!",
"Terrible customer service, never again.",
"It's okay, nothing special.",
]
requests = [
Request(
custom_id=f"classify-{i}",
params=MessageCreateParamsNonStreaming(
model="claude-haiku-4-5",
max_tokens=50,
messages=[{
"role": "user",
"content": f"Classify as positive/negative/neutral (one word): {text}"
}]
)
)
for i, text in enumerate(items_to_classify)
]
# 2. Create batch
batch = client.messages.batches.create(requests=requests)
print(f"Created batch: {batch.id}")
# 3. Wait for completion
while True:
batch = client.messages.batches.retrieve(batch.id)
if batch.processing_status == "ended":
break
time.sleep(10)
# 4. Collect results
results = {}
for result in client.messages.batches.results(batch.id):
if result.result.type == "succeeded":
msg = result.result.message
results[result.custom_id] = next((b.text for b in msg.content if b.type == "text"), "")
for custom_id, classification in sorted(results.items()):
print(f"{custom_id}: {classification}")
The Files API uploads files for use in Messages API requests. Reference files via file_id in content blocks, avoiding re-uploads across multiple API calls.
Beta: Pass betas=["files-api-2025-04-14"] in your API calls (the SDK sets the required header automatically).
Key Facts
- Maximum file size: 500 MB
- Total storage: 100 GB per organization
- Files persist until deleted
- File operations (upload, list, delete) are free; content used in messages is billed as input tokens
- Not available on Amazon Bedrock or Google Vertex AI
Upload a File
The file argument accepts a (filename, content, content_type) tuple, a pathlib.Path (or any PathLike — read for you, async-safe with AsyncAnthropic), or an open binary file object.
import anthropic
from pathlib import Path
client = anthropic.Anthropic()
uploaded = client.beta.files.upload(
file=("report.pdf", open("report.pdf", "rb"), "application/pdf"),
)
# or: client.beta.files.upload(file=Path("report.pdf"))
print(f"File ID: {uploaded.id}")
print(f"Size: {uploaded.size_bytes} bytes")
Use a File in Messages
PDF / Text Document
response = client.beta.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "Summarize the key findings in this report."},
{
"type": "document",
"source": {"type": "file", "file_id": uploaded.id},
"title": "Q4 Report", # optional
"citations": {"enabled": True} # optional, enables citations
}
]
}],
betas=["files-api-2025-04-14"],
)
for block in response.content:
if block.type == "text":
print(block.text)
Image
image_file = client.beta.files.upload(
file=("photo.png", open("photo.png", "rb"), "image/png"),
)
response = client.beta.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "What's in this image?"},
{
"type": "image",
"source": {"type": "file", "file_id": image_file.id}
}
]
}],
betas=["files-api-2025-04-14"],
)
Manage Files
List Files
Iterate the list result directly — the SDK auto-paginates across all pages. Only use .data if you want the first page only.
for f in client.beta.files.list():
print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)")
Get File Metadata
file_info = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w")
print(f"Filename: {file_info.filename}")
print(f"MIME type: {file_info.mime_type}")
Delete a File
client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w")
Download a File
Only files created by the code execution tool or skills can be downloaded (not user-uploaded files).
file_content = client.beta.files.download("file_011CNha8iCJcU1wXNR6q4V8w")
file_content.write_to_file("output.txt")
Full End-to-End Example
Upload a document once, ask multiple questions about it:
import anthropic
client = anthropic.Anthropic()
# 1. Upload once
uploaded = client.beta.files.upload(
file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf"),
)
print(f"Uploaded: {uploaded.id}")
# 2. Ask multiple questions using the same file_id
questions = [
"What are the key terms and conditions?",
"What is the termination clause?",
"Summarize the payment schedule.",
]
for question in questions:
response = client.beta.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
messages=[{
"role": "user",
"content": [
{"type": "text", "text": question},
{
"type": "document",
"source": {"type": "file", "file_id": uploaded.id}
}
]
}],
betas=["files-api-2025-04-14"],
)
print(f"\nQ: {question}")
text = next((b.text for b in response.content if b.type == "text"), "")
print(f"A: {text[:200]}")
# 3. Clean up when done
client.beta.files.delete(uploaded.id)
Quick Start
with client.messages.stream(
model="claude-opus-4-8",
max_tokens=64000,
messages=[{"role": "user", "content": "Write a story"}]
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
Async
async with async_client.messages.stream(
model="claude-opus-4-8",
max_tokens=64000,
messages=[{"role": "user", "content": "Write a story"}]
) as stream:
async for text in stream.text_stream:
print(text, end="", flush=True)
Low-level: stream=True
messages.stream() (above) is the recommended helper — it accumulates state and exposes text_stream / get_final_message(). If you only need the raw event iterator and want lower memory use, pass stream=True to messages.create() instead:
for event in client.messages.create(
model="claude-opus-4-8",
max_tokens=64000,
messages=[{"role": "user", "content": "Write a story"}],
stream=True,
):
print(event.type)
No final-message accumulation is done for you in this form.
Handling Different Content Types
Claude may return text, thinking blocks, or tool use. Handle each appropriately:
Opus 4.8 / Opus 4.7 / Opus 4.6: Use
thinking: {type: "adaptive"}. On older models, usethinking: {type: "enabled", budget_tokens: N}instead.
with client.messages.stream(
model="claude-opus-4-8",
max_tokens=64000,
thinking={"type": "adaptive"},
messages=[{"role": "user", "content": "Analyze this problem"}]
) as stream:
for event in stream:
if event.type == "content_block_start":
if event.content_block.type == "thinking":
print("\n[Thinking...]")
elif event.content_block.type == "text":
print("\n[Response:]")
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)
Streaming with Tool Use
The Python tool runner currently returns complete messages. Use streaming for individual API calls within a manual loop if you need per-token streaming with tools:
with client.messages.stream(
model="claude-opus-4-8",
max_tokens=64000,
tools=tools,
messages=messages
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
response = stream.get_final_message()
# Continue with tool execution if response.stop_reason == "tool_use"
Getting the Final Message
with client.messages.stream(
model="claude-opus-4-8",
max_tokens=64000,
messages=[{"role": "user", "content": "Hello"}]
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
# Get full message after streaming
final_message = stream.get_final_message()
print(f"\n\nTokens used: {final_message.usage.output_tokens}")
Streaming with Progress Updates
def stream_with_progress(client, **kwargs):
"""Stream a response with progress updates."""
total_tokens = 0
content_parts = []
with client.messages.stream(**kwargs) as stream:
for event in stream:
if event.type == "content_block_delta":
if event.delta.type == "text_delta":
text = event.delta.text
content_parts.append(text)
print(text, end="", flush=True)
elif event.type == "message_delta":
if event.usage and event.usage.output_tokens is not None:
total_tokens = event.usage.output_tokens
final_message = stream.get_final_message()
print(f"\n\n[Tokens used: {total_tokens}]")
return "".join(content_parts)
Error Handling in Streams
try:
with client.messages.stream(
model="claude-opus-4-8",
max_tokens=64000,
messages=[{"role": "user", "content": "Write a story"}]
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
except anthropic.APIConnectionError:
print("\nConnection lost. Please retry.")
except anthropic.RateLimitError:
print("\nRate limited. Please wait and retry.")
except anthropic.APIStatusError as e:
print(f"\nAPI error: {e.status_code}")
Stream Event Types
| Event Type | Description | When it fires |
|---|---|---|
message_start |
Contains message metadata | Once at the beginning |
content_block_start |
New content block beginning | When a text/tool_use block starts |
content_block_delta |
Incremental content update | For each token/chunk |
content_block_stop |
Content block complete | When a block finishes |
message_delta |
Message-level updates | Contains stop_reason, usage |
message_stop |
Message complete | Once at the end |
Best Practices
- Always flush output — Use
flush=Trueto show tokens immediately - Handle partial responses — If the stream is interrupted, you may have incomplete content
- Track token usage — The
message_deltaevent contains usage information - Use timeouts — Set appropriate timeouts for your application
- Default to streaming — Use
.get_final_message()to get the complete response even when streaming, giving you timeout protection without needing to handle individual events - Large
max_tokenswithout streaming raisesValueError— The SDK refuses non-streaming requests it estimates will exceed ~10 minutes (idle connections drop). Passstream=True/ usemessages.stream(), or explicitly overridetimeout, to suppress the guard.
For conceptual overview (tool definitions, tool choice, tips), see shared/tool-use-concepts.md.
Tool Runner (Recommended)
Beta: The tool runner is in beta in the Python SDK.
Use the @beta_tool decorator to define tools as typed functions, then pass them to client.beta.messages.tool_runner():
import anthropic
from anthropic import beta_tool
client = anthropic.Anthropic()
@beta_tool
def get_weather(location: str, unit: str = "celsius") -> str:
"""Get current weather for a location.
Args:
location: City and state, e.g., San Francisco, CA.
unit: Temperature unit, either "celsius" or "fahrenheit".
"""
# Your implementation here
return f"72°F and sunny in {location}"
# The tool runner handles the agentic loop automatically
runner = client.beta.messages.tool_runner(
model="claude-opus-4-8",
max_tokens=16000,
tools=[get_weather],
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)
# Each iteration yields a BetaMessage; iteration stops when Claude is done
for message in runner:
print(message)
For async usage, use @beta_async_tool with async def functions.
Key benefits of the tool runner:
- No manual loop — the SDK handles calling tools and feeding results back
- Type-safe tool inputs via decorators
- Tool schemas are generated automatically from function signatures
- Iteration stops automatically when Claude has no more tool calls
MCP Tool Conversion Helpers
Beta. Convert MCP (Model Context Protocol) tools, prompts, and resources to Anthropic API types for use with the tool runner. Requires pip install anthropic[mcp] (Python 3.10+).
Note: The Claude API also supports an
mcp_serversparameter that lets Claude connect directly to remote MCP servers. Use these helpers instead when you need local MCP servers, prompts, resources, or more control over the MCP connection.
MCP Tools with Tool Runner
from anthropic import AsyncAnthropic
from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import stdio_client, StdioServerParameters
client = AsyncAnthropic()
async with stdio_client(StdioServerParameters(command="mcp-server")) as (read, write):
async with ClientSession(read, write) as mcp_client:
await mcp_client.initialize()
tools_result = await mcp_client.list_tools()
# tool_runner is sync — returns the runner, not a coroutine
runner = client.beta.messages.tool_runner(
model="claude-opus-4-8",
max_tokens=16000,
messages=[{"role": "user", "content": "Use the available tools"}],
tools=[async_mcp_tool(t, mcp_client) for t in tools_result.tools],
)
async for message in runner:
print(message)
For sync usage, use mcp_tool instead of async_mcp_tool.
MCP Prompts
from anthropic.lib.tools.mcp import mcp_message
prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
messages=[mcp_message(m) for m in prompt.messages],
)
MCP Resources as Content
from anthropic.lib.tools.mcp import mcp_resource_to_content
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
messages=[{
"role": "user",
"content": [
mcp_resource_to_content(resource),
{"type": "text", "text": "Summarize this document"},
],
}],
)
Upload MCP Resources as Files
from anthropic.lib.tools.mcp import mcp_resource_to_file
resource = await mcp_client.read_resource(uri="file:///path/to/data.json")
uploaded = await client.beta.files.upload(file=mcp_resource_to_file(resource))
Conversion functions raise UnsupportedMCPValueError if an MCP value cannot be converted (e.g., unsupported content types like audio, unsupported MIME types).
Manual Agentic Loop
Use this when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval):
import anthropic
client = anthropic.Anthropic()
tools = [...] # Your tool definitions
messages = [{"role": "user", "content": user_input}]
# Agentic loop: keep going until Claude stops calling tools
while True:
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
tools=tools,
messages=messages
)
# If Claude is done (no more tool calls), break
if response.stop_reason == "end_turn":
break
# Server-side tool hit iteration limit; re-send to continue
if response.stop_reason == "pause_turn":
messages = [
{"role": "user", "content": user_input},
{"role": "assistant", "content": response.content},
]
continue
# Extract tool use blocks from the response
tool_use_blocks = [b for b in response.content if b.type == "tool_use"]
# Append assistant's response (including tool_use blocks)
messages.append({"role": "assistant", "content": response.content})
# Execute each tool and collect results
tool_results = []
for tool in tool_use_blocks:
result = execute_tool(tool.name, tool.input) # Your implementation
tool_results.append({
"type": "tool_result",
"tool_use_id": tool.id, # Must match the tool_use block's id
"content": result
})
# Append tool results as a user message
messages.append({"role": "user", "content": tool_results})
# Final response text
final_text = next(b.text for b in response.content if b.type == "text")
Handling Tool Results
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
tools=tools,
messages=[{"role": "user", "content": "What's the weather in Paris?"}]
)
for block in response.content:
if block.type == "tool_use":
tool_name = block.name
tool_input = block.input
tool_use_id = block.id
result = execute_tool(tool_name, tool_input)
followup = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
tools=tools,
messages=[
{"role": "user", "content": "What's the weather in Paris?"},
{"role": "assistant", "content": response.content},
{
"role": "user",
"content": [{
"type": "tool_result",
"tool_use_id": tool_use_id,
"content": result
}]
}
]
)
Multiple Tool Calls
tool_results = []
for block in response.content:
if block.type == "tool_use":
result = execute_tool(block.name, block.input)
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": result
})
# Send all results back at once
if tool_results:
followup = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
tools=tools,
messages=[
*previous_messages,
{"role": "assistant", "content": response.content},
{"role": "user", "content": tool_results}
]
)
Error Handling in Tool Results
tool_result = {
"type": "tool_result",
"tool_use_id": tool_use_id,
"content": "Error: Location 'xyz' not found. Please provide a valid city name.",
"is_error": True
}
Tool Choice
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
tools=tools,
tool_choice={"type": "tool", "name": "get_weather"}, # Force specific tool
messages=[{"role": "user", "content": "What's the weather in Paris?"}]
)
Code Execution
Basic Usage
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
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_20260120",
"name": "code_execution"
}]
)
for block in response.content:
if block.type == "text":
print(block.text)
elif block.type == "bash_code_execution_tool_result":
print(f"stdout: {block.content.stdout}")
Upload Files for Analysis
# 1. Upload a file
uploaded = client.beta.files.upload(file=open("sales_data.csv", "rb"))
# 2. Pass to code execution via container_upload block
# Code execution is GA; Files API is still beta (pass via extra_headers)
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
extra_headers={"anthropic-beta": "files-api-2025-04-14"},
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "Analyze this sales data. Show trends and create a visualization."},
{"type": "container_upload", "file_id": uploaded.id}
]
}],
tools=[{"type": "code_execution_20260120", "name": "code_execution"}]
)
Retrieve Generated Files
import os
OUTPUT_DIR = "./claude_outputs"
os.makedirs(OUTPUT_DIR, exist_ok=True)
for block in response.content:
if block.type == "bash_code_execution_tool_result":
result = block.content
if result.type == "bash_code_execution_result" and result.content:
for file_ref in result.content:
if file_ref.type == "bash_code_execution_output":
metadata = client.beta.files.retrieve_metadata(file_ref.file_id)
file_content = client.beta.files.download(file_ref.file_id)
# Use basename to prevent path traversal; validate result
safe_name = os.path.basename(metadata.filename)
if not safe_name or safe_name in (".", ".."):
print(f"Skipping invalid filename: {metadata.filename}")
continue
output_path = os.path.join(OUTPUT_DIR, safe_name)
file_content.write_to_file(output_path)
print(f"Saved: {output_path}")
Container Reuse
# First request: set up environment
response1 = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
messages=[{"role": "user", "content": "Install tabulate and create data.json with sample data"}],
tools=[{"type": "code_execution_20260120", "name": "code_execution"}]
)
# Get container ID from response
container_id = response1.container.id
# Second request: reuse the same container
response2 = client.messages.create(
container=container_id,
model="claude-opus-4-8",
max_tokens=16000,
messages=[{"role": "user", "content": "Read data.json and display as a formatted table"}],
tools=[{"type": "code_execution_20260120", "name": "code_execution"}]
)
Response Structure
for block in response.content:
if block.type == "text":
print(block.text) # Claude's explanation
elif block.type == "server_tool_use":
print(f"Running: {block.name} - {block.input}") # What Claude is doing
elif block.type == "bash_code_execution_tool_result":
result = block.content
if result.type == "bash_code_execution_result":
if result.return_code == 0:
print(f"Output: {result.stdout}")
else:
print(f"Error: {result.stderr}")
else:
print(f"Tool error: {result.error_code}")
elif block.type == "text_editor_code_execution_tool_result":
print(f"File operation: {block.content}")
Memory Tool
Basic Usage
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
messages=[{"role": "user", "content": "Remember that my preferred language is Python."}],
tools=[{"type": "memory_20250818", "name": "memory"}],
)
SDK Memory Helper
Subclass BetaAbstractMemoryTool:
from anthropic.lib.tools import BetaAbstractMemoryTool
class MyMemoryTool(BetaAbstractMemoryTool):
def view(self, command): ...
def create(self, command): ...
def str_replace(self, command): ...
def insert(self, command): ...
def delete(self, command): ...
def rename(self, command): ...
memory = MyMemoryTool()
# Use with tool runner
runner = client.beta.messages.tool_runner(
model="claude-opus-4-8",
max_tokens=16000,
tools=[memory],
messages=[{"role": "user", "content": "Remember my preferences"}],
)
for message in runner:
print(message)
For full implementation examples, use WebFetch:
https://github.com/anthropics/anthropic-sdk-python/blob/main/examples/memory/basic.py
Structured Outputs
JSON Outputs (Pydantic — Recommended)
from pydantic import BaseModel
from typing import List
import anthropic
class ContactInfo(BaseModel):
name: str
email: str
plan: str
interests: List[str]
demo_requested: bool
client = anthropic.Anthropic()
response = client.messages.parse(
model="claude-opus-4-8",
max_tokens=16000,
messages=[{
"role": "user",
"content": "Extract: Jane Doe (jane@co.com) wants Enterprise, interested in API and SDKs, wants a demo."
}],
output_format=ContactInfo,
)
# response.parsed_output is a validated ContactInfo instance
contact = response.parsed_output
print(contact.name) # "Jane Doe"
print(contact.interests) # ["API", "SDKs"]
Raw Schema
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
messages=[{
"role": "user",
"content": "Extract info: John Smith (john@example.com) wants the Enterprise plan."
}],
output_config={
"format": {
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"email": {"type": "string"},
"plan": {"type": "string"},
"demo_requested": {"type": "boolean"}
},
"required": ["name", "email", "plan", "demo_requested"],
"additionalProperties": False
}
}
}
)
import json
# output_config.format guarantees the first block is text with valid JSON
text = next(b.text for b in response.content if b.type == "text")
data = json.loads(text)
Strict Tool Use
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
messages=[{"role": "user", "content": "Book a flight to Tokyo for 2 passengers on March 15"}],
tools=[{
"name": "book_flight",
"description": "Book a flight to a destination",
"strict": True,
"input_schema": {
"type": "object",
"properties": {
"destination": {"type": "string"},
"date": {"type": "string", "format": "date"},
"passengers": {"type": "integer", "enum": [1, 2, 3, 4, 5, 6, 7, 8]}
},
"required": ["destination", "date", "passengers"],
"additionalProperties": False
}
}]
)
Using Both Together
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
messages=[{"role": "user", "content": "Plan a trip to Paris next month"}],
output_config={
"format": {
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"summary": {"type": "string"},
"next_steps": {"type": "array", "items": {"type": "string"}}
},
"required": ["summary", "next_steps"],
"additionalProperties": False
}
}
},
tools=[{
"name": "search_flights",
"description": "Search for available flights",
"strict": True,
"input_schema": {
"type": "object",
"properties": {
"destination": {"type": "string"},
"date": {"type": "string", "format": "date"}
},
"required": ["destination", "date"],
"additionalProperties": False
}
}]
)
Bindings not shown here: This README covers the most common managed-agents flows for Python. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Python SDK repo or the relevant docs page from
shared/live-sources.mdrather than guess. Do not extrapolate from cURL shapes or another language's SDK.
Agents are persistent — create once, reference by ID. Store the agent ID returned by
agents.createand pass it to every subsequentsessions.create; do not callagents.createin the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is inshared/live-sources.md. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path.
Installation
pip install anthropic
Client Initialization
import anthropic
# Default — resolves credentials from the environment:
# ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN, or an `ant auth login` profile.
# Prefer this for local dev; don't hardcode a key.
client = anthropic.Anthropic()
# Explicit API key (only when you must inject a specific key)
client = anthropic.Anthropic(api_key="your-api-key")
Create an Environment
environment = client.beta.environments.create(
name="my-dev-env",
config={
"type": "cloud",
"networking": {"type": "unrestricted"},
},
)
print(environment.id) # env_...
Create an Agent (required first step)
⚠️ There is no inline agent config.
model/system/toolslive on the agent object, not the session. Always start withagents.create()— the session only takesagent={"type": "agent", "id": agent.id}.
Minimal
# 1. Create the agent (reusable, versioned)
agent = client.beta.agents.create(
name="Coding Assistant",
model="claude-opus-4-8",
tools=[{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}],
)
# 2. Start a session
session = client.beta.sessions.create(
agent={"type": "agent", "id": agent.id, "version": agent.version},
environment_id=environment.id,
)
print(session.id, session.status)
With system prompt and custom tools
import os
agent = client.beta.agents.create(
name="Code Reviewer",
model="claude-opus-4-8",
system="You are a senior code reviewer.",
tools=[
{"type": "agent_toolset_20260401"},
{
"type": "custom",
"name": "run_tests",
"description": "Run the test suite",
"input_schema": {
"type": "object",
"properties": {
"test_path": {"type": "string", "description": "Path to test file"}
},
"required": ["test_path"],
},
},
],
)
session = client.beta.sessions.create(
agent={"type": "agent", "id": agent.id, "version": agent.version},
environment_id=environment.id,
title="Code review session",
resources=[
{
"type": "github_repository",
"url": "https://github.com/owner/repo",
"mount_path": "/workspace/repo",
"authorization_token": os.environ["GITHUB_TOKEN"],
"branch": "main",
}
],
)
Send a User Message
client.beta.sessions.events.send(
session_id=session.id,
events=[
{
"type": "user.message",
"content": [{"type": "text", "text": "Review the auth module"}],
}
],
)
💡 Stream-first: Open the stream before (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See Steering Patterns.
Stream Events (SSE)
import json
# Stream-first: open stream, then send while stream is live
with client.beta.sessions.events.stream(
session_id=session.id,
) as stream:
client.beta.sessions.events.send(
session_id=session.id,
events=[{"type": "user.message", "content": [{"type": "text", "text": "..."}]}],
)
for event in stream:
... # process events
# Standalone stream iteration:
with client.beta.sessions.events.stream(
session_id=session.id,
) as stream:
for event in stream:
if event.type == "agent.message":
for block in event.content:
if block.type == "text":
print(block.text, end="", flush=True)
elif event.type == "agent.custom_tool_use":
# Custom tool invocation — session is now idle
print(f"\nCustom tool call: {event.name}")
print(f"Input: {json.dumps(event.input)}")
# Send result back (see below)
elif event.type == "session.status_idle":
print("\n--- Agent idle ---")
elif event.type == "session.status_terminated":
print("\n--- Session terminated ---")
break
Provide Custom Tool Result
client.beta.sessions.events.send(
session_id=session.id,
events=[
{
"type": "user.custom_tool_result",
"custom_tool_use_id": "sevt_abc123",
"content": [{"type": "text", "text": "All 42 tests passed."}],
}
],
)
Poll Events
events = client.beta.sessions.events.list(
session_id=session.id,
)
for event in events.data:
print(f"{event.type}: {event.id}")
⚠️ Prefer the SDK over raw
requests/httpx. If you hand-roll a poll loop, don't assumetimeout=(5, 60)orhttpx.Timeout(120)caps total call duration — both are per-chunk read timeouts (reset on every byte), so a trickling response can block forever. For a hard wall-clock deadline, tracktime.monotonic()at the loop level and bail explicitly, or wrap withasyncio.wait_for(). See Receiving Events.
Full Streaming Loop with Custom Tools
import json
def run_custom_tool(tool_name: str, tool_input: dict) -> str:
"""Execute a custom tool and return the result."""
if tool_name == "run_tests":
# Your tool implementation here
return "All tests passed."
return f"Unknown tool: {tool_name}"
def run_session(client, session_id: str):
"""Stream events and handle custom tool calls."""
while True:
with client.beta.sessions.events.stream(
session_id=session_id,
) as stream:
tool_calls = []
for event in stream:
if event.type == "agent.message":
for block in event.content:
if block.type == "text":
print(block.text, end="", flush=True)
elif event.type == "agent.custom_tool_use":
tool_calls.append(event)
elif event.type == "session.status_idle":
break
elif event.type == "session.status_terminated":
return
if not tool_calls:
break
# Process custom tool calls
results = []
for call in tool_calls:
result = run_custom_tool(call.name, call.input)
results.append({
"type": "user.custom_tool_result",
"custom_tool_use_id": call.id,
"content": [{"type": "text", "text": result}],
})
client.beta.sessions.events.send(
session_id=session_id,
events=results,
)
Upload a File
with open("data.csv", "rb") as f:
file = client.beta.files.upload(
file=f,
)
# Use in a session
session = client.beta.sessions.create(
agent={"type": "agent", "id": agent.id, "version": agent.version},
environment_id=environment.id,
resources=[{"type": "file", "file_id": file.id, "mount_path": "/workspace/data.csv"}],
)
List and Download Session Files
List files the agent wrote to /mnt/session/outputs/ during a session, then download them.
# List files associated with a session
files = client.beta.files.list(
scope_id=session.id,
betas=["managed-agents-2026-04-01"],
)
for f in files.data:
print(f.filename, f.size_bytes)
# Download each file and save to disk
file_content = client.beta.files.download(f.id)
file_content.write_to_file(f.filename)
💡 There's a brief indexing lag (~1–3s) between
session.status_idleand output files appearing infiles.list. Retry once or twice if the list is empty.
Session Management
# Get session details
session = client.beta.sessions.retrieve(session_id="sesn_011CZxAbc123Def456")
print(session.status, session.usage)
# List sessions
sessions = client.beta.sessions.list()
# Delete a session
client.beta.sessions.delete(session_id="sesn_011CZxAbc123Def456")
# Archive a session
client.beta.sessions.archive(session_id="sesn_011CZxAbc123Def456")
MCP Server Integration
# Agent declares MCP server (no auth here — auth goes in a vault)
agent = client.beta.agents.create(
name="MCP Agent",
model="claude-opus-4-8",
mcp_servers=[
{"type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse"},
],
tools=[
{"type": "agent_toolset_20260401", "default_config": {"enabled": True}},
{"type": "mcp_toolset", "mcp_server_name": "my-tools"},
],
)
# Session attaches vault(s) containing credentials for those MCP server URLs
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
vault_ids=[vault.id],
)
See shared/managed-agents-tools.md §Vaults for creating vaults and adding credentials.
Note: The Ruby SDK supports the Claude API. A tool runner is available in beta via
client.beta.messages.tool_runner(). Agent SDK is not yet available for Ruby.
Installation
gem install anthropic
Client Initialization
require "anthropic"
# Default (uses ANTHROPIC_API_KEY env var)
client = Anthropic::Client.new
# Explicit API key
client = Anthropic::Client.new(api_key: "your-api-key")
Basic Message Request
message = client.messages.create(
model: :"claude-opus-4-8",
max_tokens: 16000,
messages: [
{ role: "user", content: "What is the capital of France?" }
]
)
# content is an array of polymorphic block objects (TextBlock, ThinkingBlock,
# ToolUseBlock, ...). .type is a Symbol — compare with :text, not "text".
# .text raises NoMethodError on non-TextBlock entries.
message.content.each do |block|
puts block.text if block.type == :text
end
Streaming
stream = client.messages.stream(
model: :"claude-opus-4-8",
max_tokens: 64000,
messages: [{ role: "user", content: "Write a haiku" }]
)
stream.text.each { |text| print(text) }
Tool Use
The Ruby SDK supports tool use via raw JSON schema definitions and also provides a beta tool runner for automatic tool execution.
Tool Runner (Beta)
class GetWeatherInput < Anthropic::BaseModel
required :location, String, doc: "City and state, e.g. San Francisco, CA"
end
class GetWeather < Anthropic::BaseTool
doc "Get the current weather for a location"
input_schema GetWeatherInput
def call(input)
"The weather in #{input.location} is sunny and 72°F."
end
end
client.beta.messages.tool_runner(
model: :"claude-opus-4-8",
max_tokens: 16000,
tools: [GetWeather.new],
messages: [{ role: "user", content: "What's the weather in San Francisco?" }]
).each_message do |message|
puts message.content
end
Manual Loop
See the shared tool use concepts for the tool definition format and agentic loop pattern.
Prompt Caching
system_: (trailing underscore — avoids shadowing Kernel#system) takes an array of text blocks; set cache_control on the last block. Plain hashes work via the OrHash type alias. For placement patterns and the silent-invalidator audit checklist, see shared/prompt-caching.md.
message = client.messages.create(
model: :"claude-opus-4-8",
max_tokens: 16000,
system_: [
{ type: "text", text: long_system_prompt, cache_control: { type: "ephemeral" } }
],
messages: [{ role: "user", content: "Summarize the key points" }]
)
For 1-hour TTL: cache_control: { type: "ephemeral", ttl: "1h" }. There's also a top-level cache_control: on messages.create that auto-places on the last cacheable block.
Verify hits via message.usage.cache_creation_input_tokens / message.usage.cache_read_input_tokens.
Stop Details
When stop_reason is :refusal, the response includes structured stop_details:
if message.stop_reason == :refusal && message.stop_details
puts "Category: #{message.stop_details.category}" # :cyber, :bio, or nil
puts "Explanation: #{message.stop_details.explanation}"
end
Error Type
APIStatusError exposes a .type field for programmatic error classification:
begin
client.messages.create(...)
rescue Anthropic::APIStatusError => e
puts e.type # :rate_limit_error, :overloaded_error, etc.
end
This file covers decision heuristics for building agents on the Claude API: which primitives to reach for, how to design your tool surface, and how to manage context and cost over long runs. For per-tool mechanics and code examples, see tool-use-concepts.md and the language-specific folders.
Model Parameters
| Parameter | When to use it | What to expect |
|---|---|---|
Adaptive thinking (thinking: {type: "adaptive"}) |
When you want Claude to control when and how much to think. | Claude determines thinking depth per request and automatically interleaves thinking between tool calls. No token budget to tune. |
Effort (output_config: {effort: ...}) |
When adjusting the tradeoff between thoroughness and token efficiency. | Lower effort → fewer and more-consolidated tool calls, less preamble, terser confirmations. medium is often a favorable balance. Use max when correctness matters more than cost. |
See SKILL.md §Thinking & Effort for model support and parameter details.
Designing Your Tool Surface
Bash vs. dedicated tools
Claude doesn't know your application's security boundary, approval policy, or UX surface. Claude emits tool calls; your harness handles them. The shape of those tool calls determines what the harness can do.
A bash tool gives Claude broad programmatic leverage — it can perform almost any action. But it gives the harness only an opaque command string, the same shape for every action. Promoting an action to a dedicated tool gives the harness an action-specific hook with typed arguments it can intercept, gate, render, or audit.
When to promote an action to a dedicated tool:
- Security boundary. Actions that require gating are natural candidates. Reversibility is a useful criterion: hard-to-reverse actions (external API calls, sending messages, deleting data) can be gated behind user confirmation. A
send_emailtool is easy to gate;bash -c "curl -X POST ..."is not. - Staleness checks. A dedicated
edittool can reject writes if the file changed since Claude last read it. Bash can't enforce that invariant. - Rendering. Some actions benefit from custom UI. Claude Code promotes question-asking to a tool so it can render as a modal, present options, and block the agent loop until answered.
- Scheduling. Read-only tools like
globandgrepcan be marked parallel-safe. When the same actions run through bash, the harness can't tell a parallel-safegrepfrom a parallel-unsafegit push, so it must serialize.
Rule of thumb: Start with bash for breadth. Promote to dedicated tools when you need to gate, render, audit, or parallelize the action.
Anthropic-Provided Tools
| Tool | Side | When to use it | What to expect |
|---|---|---|---|
| Bash | Client | Claude needs to execute shell commands. | Claude emits commands; your harness executes them. Reference implementation provided. |
| Text editor | Client | Claude needs to read or edit files. | Claude views, creates, and edits files via your implementation. Reference implementation provided. |
| Computer use | Client or Server | Claude needs to interact with GUIs, web apps, or visual interfaces. | Claude takes screenshots and issues mouse/keyboard commands. Can be self-hosted (you run the environment) or Anthropic-hosted. |
| Code execution | Server | Claude needs to run code in a sandbox you don't want to manage. | Anthropic-hosted container with built-in file and bash sub-tools. No client-side execution. |
| Web search / fetch | Server | Claude needs information past its training cutoff (news, current events, recent docs) or the content of a specific URL. | Claude issues a query or URL; Anthropic executes it and returns results with citations. |
| Memory | Client | Claude needs to save context across sessions. | Claude reads/writes a /memories directory. You implement the storage backend. |
Client-side tools are defined by Anthropic (name, schema, Claude's usage pattern) but executed by your harness. Anthropic provides reference implementations. Server-side tools run entirely on Anthropic infrastructure — declare them in tools and Claude handles the rest.
Composing Tool Calls: Programmatic Tool Calling
With standard tool use, each tool call is a round trip: Claude calls the tool, the result lands in Claude's context, Claude reasons about it, then calls the next tool. Three sequential actions (read profile → look up orders → check inventory) means three round trips. Each adds latency and tokens, and most of the intermediate data is never needed again.
Programmatic tool calling (PTC) lets Claude compose those calls into a script instead. The script runs in the code execution container. When the script calls a tool, the container pauses, the call is executed (client-side or server-side), and the result returns to the running code — not to Claude's context. The script processes it with normal control flow (loops, filters, branches). Only the script's final output returns to Claude.
| When to use it | What to expect |
|---|---|
| Many sequential tool calls, or large intermediate results you want filtered before they hit the context window. | Claude writes code that invokes tools as functions. Runs in the code execution container. Token cost scales with final output, not intermediate results. |
Scaling the Tool and Instruction Set
| Feature | When to use it | What to expect |
|---|---|---|
| Tool search | Many tools available, but only a few relevant per request. Don't want all schemas in context upfront. | Claude searches the tool set and loads only relevant schemas. Tool definitions are appended, not swapped — preserves cache (see Caching below). |
| Skills | Task-specific instructions Claude should load only when relevant. | Each skill is a folder with a SKILL.md. The skill's description sits in context by default; Claude reads the full file when the task calls for it. |
Both patterns keep the fixed context small and load detail on demand.
Long-Running Agents: Managing Context
| Pattern | When to use it | What to expect |
|---|---|---|
| Context editing | Context grows stale over many turns (old tool results, completed thinking). | Tool results and thinking blocks are cleared based on configurable thresholds. Keeps the transcript lean without summarizing. |
| Compaction | Conversation likely to reach or exceed the context window limit. | Earlier context is summarized into a compaction block server-side. See SKILL.md §Compaction for the critical response.content handling. |
| Memory | State must persist across sessions (not just within one conversation). | Claude reads/writes files in a memory directory. Survives process restarts. |
Choosing between them: Context editing and compaction operate within a session — editing prunes stale turns, compaction summarizes when you're near the limit. Memory is for cross-session persistence. Many long-running agents use all three.
Caching for Agents
Read prompt-caching.md first. It covers the prefix-match invariant, breakpoint placement, the silent-invalidator audit, and why changing tools or models mid-session breaks the cache. This section covers only the agent-specific workarounds for those constraints.
Constraint (from prompt-caching.md) |
Agent-specific workaround |
|---|---|
| Editing the system prompt mid-session invalidates the cache. | Append a {"role": "system", ...} message to messages[] instead (beta, on supporting models — see prompt-caching.md § Mid-conversation system messages). The cached prefix stays intact, and the model treats it as an operator-authority instruction rather than user text. On models that don't support it, fall back to a <system-reminder> text block in the user turn. |
| Switching models mid-session invalidates the cache. | Spawn a subagent with the cheaper model for the sub-task; keep the main loop on one model. Claude Code's Explore subagents use Haiku this way. |
| Adding/removing tools mid-session invalidates the cache. | Use tool search for dynamic discovery — it appends tool schemas rather than swapping them, so the existing prefix is preserved. |
For multi-turn breakpoint placement, use top-level auto-caching — see prompt-caching.md §Placement patterns.
For live documentation on any of these features, see live-sources.md.
The ant CLI exposes every Claude API resource as a shell subcommand. Compared to curl: request bodies are built from typed flags or piped YAML instead of hand-written JSON, @path inlines file contents into any string field, --transform extracts fields with a GJSON path (no jq), list endpoints auto-paginate (cap total results with --max-items N; --limit only sets the server page size), and the beta: prefix auto-sets the right anthropic-beta header.
When to use the CLI vs the SDK
CLI for the control plane, SDK for the data plane. Agents and environments are relatively static resources you define, configure, and debug with ant — check the YAML into your repo, apply from CI, inspect from a terminal. Sessions are dynamic and driven by your application through the SDK — create per task, stream events, react to tool calls, integrate into your product. Both hit the same API; the split is about where the call lives, not what's possible.
Control plane → ant |
Data plane → SDK | |
|---|---|---|
| Resources | agents, environments, skills, vaults, files | sessions, events |
| Cadence | Once per deploy / ad-hoc | Every task / every turn |
| Lives in | *.yaml in your repo + CI + terminal |
Application code |
| Typical calls | create < agent.yaml, update --version N, list, retrieve, archive, --debug |
sessions.create(), events.stream(), events.send() |
Install and auth
# macOS
brew install anthropics/tap/ant
xattr -d com.apple.quarantine "$(brew --prefix)/bin/ant"
# Linux / WSL — pick the release from github.com/anthropics/anthropic-cli/releases
curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_$(uname -s | tr A-Z a-z)_$(uname -m | sed -e s/x86_64/amd64/ -e s/aarch64/arm64/).tar.gz" \
| sudo tar -xz -C /usr/local/bin ant
# Or from source (Go 1.22+)
go install github.com/anthropics/anthropic-cli/cmd/ant@latest
Auth — the CLI resolves credentials the same way the SDKs do (first match wins): explicit flags, then ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN env vars, then ANTHROPIC_PROFILE, then the active profile from ant auth login. Override the host with ANTHROPIC_BASE_URL or --base-url.
- API key: set
ANTHROPIC_API_KEYin the environment. - OAuth profile (no static key to manage):
ant auth loginopens a browser, exchanges for a short-lived token, and stores a profile under~/.config/anthropic/. Subsequentant(and SDK) calls pick it up automatically.ant auth statusshows the active profile;ant auth logoutclears it.
To hand the active credential to a subprocess or raw-HTTP script:
# Bare access token — for curl's Authorization header
curl https://api.anthropic.com/v1/messages \
-H "Authorization: Bearer $(ant auth print-credentials --access-token)" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model": "claude-opus-4-8", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}]}'
# .env format — sets ANTHROPIC_AUTH_TOKEN (and ANTHROPIC_BASE_URL if the profile has one).
# Output is bare KEY=value (no `export`), so use `set -a` to auto-export for child processes:
set -a; eval "$(ant auth print-credentials --env)"; set +a
python my_script.py # SDK picks up ANTHROPIC_AUTH_TOKEN
OAuth tokens go on Authorization: Bearer (not x-api-key:). The token is short-lived and not auto-refreshed when passed via env var, so re-run print-credentials before it expires for long-running scripts. If both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are set, the SDKs send both and the API rejects the request — unset ANTHROPIC_API_KEY before evaling the --env output.
Command structure
ant <resource>[:<subresource>] <action> [flags]
Beta resources (agents, sessions, environments, deployments, skills, vaults, memory stores) live under beta: — the CLI auto-sends the right anthropic-beta header, so don't pass it yourself unless overriding with --beta <header>. For self-hosted environments, ant beta:worker poll/run and ant beta:environments:work stats/stop drive and monitor the work queue — see shared/managed-agents-self-hosted-sandboxes.md.
ant models list
ant messages create --model claude-opus-4-8 --max-tokens 1024 --message '{role: user, content: "Hello"}'
ant beta:agents retrieve --agent-id agent_01...
ant beta:sessions:events list --session-id session_01...
ant --help lists resources; append --help to any subcommand for its flags.
Global flags
| Flag | Purpose |
|---|---|
--format |
auto (default: pretty if TTY, compact if piped), json, jsonl, yaml, pretty, raw, explore (interactive TUI) |
--transform |
GJSON path applied to the response (per-item on list endpoints). Not applied when --format raw. |
-r, --raw-output |
If the transformed result is a string, print it without quotes (jq semantics). Pair with --transform for scalar capture. |
--max-items |
Cap total results returned from auto-paginating list endpoints (distinct from --limit, which is the server page size). |
--format-error / --transform-error |
Same as --format/--transform, applied to error responses. -r does not apply to the error path — use --format-error yaml for unquoted error scalars. |
--base-url |
Override API host |
--debug |
Print full HTTP request + response to stderr (API key redacted) |
Output — --transform + --format
--transform takes a GJSON path. On list endpoints it runs per item, not on the envelope.
ant beta:agents list --transform '{id,name,model}' --format jsonl
Extract a scalar for shell use: pair --transform with -r (--raw-output — prints strings unquoted, jq-style):
AGENT_ID=$(ant beta:agents create --name "My Agent" --model '{id: claude-sonnet-4-6}' \
--transform id -r)
Input — flags, stdin, @file
Flags — scalar fields map directly. Structured fields accept relaxed-YAML syntax (unquoted keys) or strict JSON. Repeatable flags build arrays (each --tool, --event, --message appends one element):
ant beta:agents create \
--name "Research Agent" \
--model '{id: claude-opus-4-8}' \
--tool '{type: agent_toolset_20260401}' \
--tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'
Stdin — pipe a full JSON or YAML body. Merged with flags; flags win on conflict (for array fields, any flag replaces the stdin array entirely — it does not append). Quote the heredoc delimiter (<<'YAML') to disable shell expansion inside the body:
ant beta:agents create <<'YAML'
name: Research Agent
model: claude-opus-4-8
system: |
You are a research assistant. Cite sources for every claim.
tools:
- type: agent_toolset_20260401
YAML
@file references — inline a file's contents into any string-valued field. Inside structured flag values, quote the path. Binary files are auto-base64'd; force with @file:// (text) or @data:// (base64). Escape a literal leading @ as \@.
ant beta:agents create --name "Researcher" --model '{id: claude-sonnet-4-6}' --system @./prompts/researcher.txt
ant messages create --model claude-opus-4-8 --max-tokens 1024 \
--message '{role: user, content: [
{type: document, source: {type: base64, media_type: application/pdf, data: "@./scan.pdf"}},
{type: text, text: "Extract the text from this scanned document."}
]}' \
--transform 'content.0.text' -r
Flags that natively take a file path (e.g. --file on beta:files upload) accept a bare path without @.
Version-controlled Managed Agents resources
This is the recommended flow for defining agents and environments — check the YAML into your repo and sync via create (first time) / update (thereafter). See shared/managed-agents-core.md for the field reference.
# summarizer.agent.yaml
name: Summarizer
model: claude-sonnet-4-6
system: |
You are a helpful assistant that writes concise summaries.
tools:
- type: agent_toolset_20260401
# Create (once) — capture the ID
AGENT_ID=$(ant beta:agents create < summarizer.agent.yaml --transform id -r)
# Update (CI) — needs ID + current version (optimistic lock)
ant beta:agents update --agent-id "$AGENT_ID" --version 1 < summarizer.agent.yaml
Same pattern for environments (ant beta:environments create|update < env.yaml), then start a session with both IDs:
ant beta:sessions create --agent "$AGENT_ID" --environment-id "$ENV_ID" --title "Task"
ant beta:sessions:events send --session-id "$SID" \
--event '{type: user.message, content: [{type: text, text: "Summarize X"}]}'
ant beta:sessions:events list --session-id "$SID" --transform 'content.0.text' -r
ant beta:sessions:events stream --session-id "$SID" # live event stream
Interactive session loop (stream-before-send)
ant beta:sessions:events stream only delivers events emitted after the stream opens — so open it before sending the kickoff to avoid missing early events. Use process substitution to hold the stream on a file descriptor, send, then read:
exec {stream}< <(ant beta:sessions:events stream --session-id "$SID" \
--transform '{type,text:content.#(type=="text").text,err:error.message}' --format yaml)
ant beta:sessions:events send --session-id "$SID" > /dev/null <<'YAML'
events:
- type: user.message
content:
- type: text
text: Summarize the repo README
YAML
type=
while IFS= read -r -u "$stream" line; do
case "$line" in
type:\ session.status_idle) break ;;
type:\ session.error)
IFS= read -r -u "$stream" next || next=
case "$next" in err:\ *) msg=${next#err: } ;; *) msg=unknown ;; esac
printf '\n[Error: %s]\n' "$msg"; break ;;
type:\ *) type=${line#type: } ;;
text:*)
[[ $type == agent.message ]] || continue
val=${line#text: }
case "$val" in '|-'|'|') ;; *) printf '%s' "$val" ;; esac ;;
\ \ *)
if [[ $type == agent.message ]]; then printf '%s\n' "${line# }"; fi ;;
esac
done
exec {stream}<&-
This works for interactive exploration and demos. For application code that needs to react to agent.tool_use / agent.custom_tool_use events, reconnect after drops, or dedup against events.list, use the SDK — see shared/managed-agents-client-patterns.md.
Scripting patterns
--transform id -r on a list endpoint emits one bare ID per line — compose with xargs, or use --max-items N to bound the result set without piping through head:
FIRST=$(ant beta:agents list --transform id -r --max-items 1)
ant beta:agents:versions list --agent-id "$FIRST" --transform '{version,created_at}' --format jsonl
Error shaping mirrors the success path (note: -r does not apply to error output — use --format-error yaml for an unquoted scalar here):
ant beta:agents retrieve --agent-id bogus --transform-error error.message --format-error yaml 2>&1
Shell completion: ant @completion {zsh|bash|fish|powershell}.
For the full, always-current reference (including per-endpoint flags), WebFetch the Anthropic CLI URL in shared/live-sources.md.
Anthropic-operated access to the Claude Developer Platform through AWS infrastructure — SigV4 authentication, AWS IAM access control, and AWS Marketplace billing. Because Anthropic operates it, the API surface matches first-party with same-day parity: Managed Agents, server-side tools, batches, Files, and every feature in this skill work the same way (except self-hosted sandboxes — config:{type:"self_hosted"} is not available here; use cloud). Model IDs are the bare first-party strings (claude-opus-4-8, claude-sonnet-4-6) — no provider prefix.
Not the same as Amazon Bedrock. Bedrock is partner-operated (AWS runs the service; release schedules vary, feature subset,
anthropic.-prefixed model IDs). Claude Platform on AWS and Bedrock coexist; pick by whether you need AWS-native IAM/billing with full Anthropic API parity (this page) vs. Bedrock's own ecosystem.
Client & install
| Language | Install | Client |
|---|---|---|
| Python | pip install -U "anthropic[aws]" |
from anthropic import AnthropicAWS → AnthropicAWS() |
| TypeScript | npm install @anthropic-ai/aws-sdk |
import AnthropicAws from "@anthropic-ai/aws-sdk" → new AnthropicAws() |
| Go | go get github.com/anthropics/anthropic-sdk-go |
import anthropicaws "github.com/anthropics/anthropic-sdk-go/aws" → anthropicaws.NewClient(ctx, anthropicaws.ClientConfig{}) |
| C# | dotnet add package Anthropic.Aws |
new AnthropicAwsClient() |
| Java | See SDK repo in shared/live-sources.md |
See SDK repo in shared/live-sources.md |
| Ruby | gem install anthropic aws-sdk-core |
See SDK repo in shared/live-sources.md |
| PHP | composer require anthropic-ai/sdk aws/aws-sdk-php |
See SDK repo in shared/live-sources.md |
After construction, use the client exactly as you would Anthropic() — client.messages.create(...), client.beta.sessions.*, etc., with bare model IDs.
from anthropic import AnthropicAWS
client = AnthropicAWS() # region + workspace_id from env; see below
client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
)
Required configuration
Two values must be available (constructor args or environment) — there is no default fallback for either:
| Value | Env var | Notes |
|---|---|---|
| AWS region | AWS_REGION |
Required. Unlike AnthropicBedrock, there is no us-east-1 fallback. |
| Workspace ID | ANTHROPIC_AWS_WORKSPACE_ID |
Required. Routes requests to your Claude workspace. |
Endpoint pattern: https://aws-external-anthropic.{region}.api.aws/v1/.... Requests are SigV4-signed with service name aws-external-anthropic.
Authentication
The client resolves AWS credentials via the standard precedence chain: explicit constructor args → environment (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN) → shared profile → assumed role / instance metadata.
Short-term API keys are also supported for cases where SigV4 isn't practical (e.g., browser, simple scripts). Mint one with the per-language token-generator package; pass it as api_key on the client. Lifetime is the lesser of the requested duration, the underlying credential's expiry, and 12 hours. For package names and IAM details, WebFetch the Claude Platform on AWS page in shared/live-sources.md.
What to tell users
- Treat it as first-party: every section of this skill applies unchanged. Do not apply Bedrock's feature-availability mask.
- Model IDs are bare (
claude-opus-4-8). Do not add ananthropic.prefix. - A missing region or
workspace_idthrows at client-construction time (no request is sent). A 403 means the request reached the server — check for a wrongworkspace_idor a missing IAM action on the principal. See the IAM actions reference inshared/live-sources.md.
This file documents HTTP error codes returned by the Claude API, their common causes, and how to handle them. For language-specific error handling examples, see the python/ or typescript/ folders.
Error Code Summary
| Code | Error Type | Retryable | Common Cause |
|---|---|---|---|
| 400 | invalid_request_error |
No | Invalid request format or parameters |
| 401 | authentication_error |
No | Invalid or missing API key |
| 403 | permission_error |
No | API key lacks permission |
| 404 | not_found_error |
No | Invalid endpoint or model ID |
| 413 | request_too_large |
No | Request exceeds size limits |
| 429 | rate_limit_error |
Yes | Too many requests |
| 500 | api_error |
Yes | Anthropic service issue |
| 529 | overloaded_error |
Yes | API is temporarily overloaded |
Detailed Error Information
400 Bad Request
Causes:
- Malformed JSON in request body
- Missing required parameters (
model,max_tokens,messages) - Invalid parameter types (e.g., string where integer expected)
- Empty messages array
- Messages not alternating user/assistant
Example error:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "messages: roles must alternate between \"user\" and \"assistant\""
},
"request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}
Fix: Validate request structure before sending. Check that:
modelis a valid model IDmax_tokensis a positive integermessagesarray is non-empty and alternates correctly
401 Unauthorized
Causes:
- Missing
x-api-keyheader orAuthorizationheader - Invalid API key format
- Revoked or deleted API key
- OAuth bearer token sent via
x-api-keyinstead ofAuthorization: Bearer - Both
ANTHROPIC_API_KEYandANTHROPIC_AUTH_TOKENset — the SDK sends both headers and the API rejects the request
Fix: Set ANTHROPIC_API_KEY, or run ant auth login and leave the client constructor empty. For raw HTTP with an OAuth token, use Authorization: Bearer <token> (not x-api-key:).
403 Forbidden
Causes:
- API key doesn't have access to the requested model
- Organization-level restrictions
- Attempting to access beta features without beta access
Fix: Check your API key permissions in the Console. You may need a different API key or to request access to specific features.
404 Not Found
Causes:
- Typo in model ID (e.g.,
claude-sonnet-4.6instead ofclaude-sonnet-4-6) - Using deprecated model ID
- Invalid API endpoint
Fix: Use exact model IDs from the models documentation. You can use aliases (e.g., claude-opus-4-8).
413 Request Too Large
Causes:
- Request body exceeds maximum size
- Too many tokens in input
- Image data too large
Fix: Reduce input size — truncate conversation history, compress/resize images, or split large documents into chunks.
400 Validation Errors
Some 400 errors are specifically related to parameter validation:
max_tokensexceeds model's limit- Invalid
temperaturevalue (must be 0.0-1.0) budget_tokens>=max_tokensin extended thinking- Invalid tool definition schema
Model-specific 400s on Opus 4.8 / 4.7:
temperature,top_p,top_kare removed — sending any of them returns 400. Delete the parameter; seeshared/model-migration.md→ Per-SDK Syntax Reference.thinking: {type: "enabled", budget_tokens: N}is removed — sending it returns 400. Usethinking: {type: "adaptive"}instead.
Common mistake with extended thinking on older models (Opus 4.6 and earlier):
# Wrong: budget_tokens must be < max_tokens
thinking: budget_tokens=10000, max_tokens=1000 → Error!
# Correct
thinking: budget_tokens=10000, max_tokens=16000
429 Rate Limited
Causes:
- Exceeded requests per minute (RPM)
- Exceeded tokens per minute (TPM)
- Exceeded tokens per day (TPD)
Headers to check:
retry-after: Seconds to wait before retryingx-ratelimit-limit-*: Your limitsx-ratelimit-remaining-*: Remaining quota
Fix: The Anthropic SDKs automatically retry 429 and 5xx errors with exponential backoff (default: max_retries=2). For custom retry behavior, see the language-specific error handling examples.
500 Internal Server Error
Causes:
- Temporary Anthropic service issue
- Bug in API processing
Fix: Retry with exponential backoff. If persistent, check status.anthropic.com.
529 Overloaded
Causes:
- High API demand
- Service capacity reached
Fix: Retry with exponential backoff. Consider using a different model (Haiku is often less loaded), spreading requests over time, or implementing request queuing.
Common Mistakes and Fixes
| Mistake | Error | Fix |
|---|---|---|
temperature/top_p/top_k on Opus 4.8 / 4.7 |
400 | Remove the parameter (see shared/model-migration.md) |
budget_tokens on Opus 4.8 / 4.7 |
400 | Use thinking: {type: "adaptive"} |
budget_tokens >= max_tokens (older models) |
400 | Ensure budget_tokens < max_tokens |
| Typo in model ID | 404 | Use valid model ID like claude-opus-4-8 |
First message is assistant |
400 | First message must be user |
| Consecutive same-role messages | 400 | Alternate user and assistant |
| API key in code | 401 (leaked key) | Use environment variable |
| Custom retry needs | 429/5xx | SDK retries automatically; customize with max_retries |
Typed Exceptions in SDKs
Always use the SDK's typed exception classes instead of checking error messages with string matching. Each HTTP error code maps to a specific exception class:
| HTTP Code | TypeScript Class | Python Class |
|---|---|---|
| 400 | Anthropic.BadRequestError |
anthropic.BadRequestError |
| 401 | Anthropic.AuthenticationError |
anthropic.AuthenticationError |
| 403 | Anthropic.PermissionDeniedError |
anthropic.PermissionDeniedError |
| 404 | Anthropic.NotFoundError |
anthropic.NotFoundError |
| 413 | Anthropic.RequestTooLargeError |
anthropic.RequestTooLargeError |
| 429 | Anthropic.RateLimitError |
anthropic.RateLimitError |
| 500+ | Anthropic.InternalServerError |
anthropic.InternalServerError |
| 529 | Anthropic.OverloadedError |
anthropic.OverloadedError |
| Any | Anthropic.APIError |
anthropic.APIError |
// ✅ Correct: use typed exceptions
try {
const response = await client.messages.create({...});
} catch (error) {
if (error instanceof Anthropic.RateLimitError) {
// Handle rate limiting
} else if (error instanceof Anthropic.APIError) {
console.error(`API error ${error.status}:`, error.message);
}
}
// ❌ Wrong: don't check error messages with string matching
try {
const response = await client.messages.create({...});
} catch (error) {
const msg = error instanceof Error ? error.message : String(error);
if (msg.includes("429") || msg.includes("rate_limit")) { ... }
}
All exception classes extend Anthropic.APIError, which has a status property. Use instanceof checks from most specific to least specific (e.g., check RateLimitError before APIError).
Error .type Field
All APIStatusError subclasses now expose a .type property (Python: .type, TypeScript: .type, Java: .errorType(), Go: .Type(), Ruby: .type, PHP: .type) that returns the API error type string (e.g., "invalid_request_error", "authentication_error", "rate_limit_error", "overloaded_error"). Use this for programmatic error classification when you need finer granularity than the HTTP status code — for example, distinguishing "billing_error" from "permission_error" (both map to 403).
except anthropic.APIStatusError as e:
if e.type == "rate_limit_error":
# handle rate limiting
elif e.type == "overloaded_error":
# handle overload
This file contains WebFetch URLs for fetching current information from platform.claude.com and Agent SDK repositories. Use these when users need the latest data that may have changed since the cached content was last updated.
When to Use WebFetch
- User explicitly asks for "latest" or "current" information
- Cached data seems incorrect
- User asks about features not covered in cached content
- User needs specific API details or examples
Claude API Documentation URLs
Models & Pricing
| Topic | URL | Extraction Prompt |
|---|---|---|
| Models Overview | https://platform.claude.com/docs/en/about-claude/models/overview.md |
"Extract current model IDs, context windows, and pricing for all Claude models" |
| Migration Guide | https://platform.claude.com/docs/en/about-claude/models/migration-guide.md |
"Extract breaking changes, deprecated parameters, and per-model migration steps when moving to a newer Claude model" |
| Pricing | https://platform.claude.com/docs/en/pricing.md |
"Extract current pricing per million tokens for input and output" |
Core Features
| Topic | URL | Extraction Prompt |
|---|---|---|
| Extended Thinking | https://platform.claude.com/docs/en/build-with-claude/extended-thinking.md |
"Extract extended thinking parameters, budget_tokens requirements, and usage examples" |
| Adaptive Thinking | https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking.md |
"Extract adaptive thinking setup, effort levels, and Claude Opus 4.8 usage examples" |
| Effort Parameter | https://platform.claude.com/docs/en/build-with-claude/effort.md |
"Extract effort levels, cost-quality tradeoffs, and interaction with thinking" |
| Tool Use | https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview.md |
"Extract tool definition schema, tool_choice options, and handling tool results" |
| Streaming | https://platform.claude.com/docs/en/build-with-claude/streaming.md |
"Extract streaming event types, SDK examples, and best practices" |
| Prompt Caching | https://platform.claude.com/docs/en/build-with-claude/prompt-caching.md |
"Extract cache_control usage, pricing benefits, and implementation examples" |
Media & Files
| Topic | URL | Extraction Prompt |
|---|---|---|
| Vision | https://platform.claude.com/docs/en/build-with-claude/vision.md |
"Extract supported image formats, size limits, and code examples" |
| PDF Support | https://platform.claude.com/docs/en/build-with-claude/pdf-support.md |
"Extract PDF handling capabilities, limits, and examples" |
API Operations
| Topic | URL | Extraction Prompt |
|---|---|---|
| Batch Processing | https://platform.claude.com/docs/en/build-with-claude/batch-processing.md |
"Extract batch API endpoints, request format, and polling for results" |
| Files API | https://platform.claude.com/docs/en/build-with-claude/files.md |
"Extract file upload, download, and referencing in messages, including supported types and beta header" |
| Token Counting | https://platform.claude.com/docs/en/build-with-claude/token-counting.md |
"Extract token counting API usage and examples" |
| Rate Limits | https://platform.claude.com/docs/en/api/rate-limits.md |
"Extract current rate limits by tier and model" |
| Errors | https://platform.claude.com/docs/en/api/errors.md |
"Extract HTTP error codes, meanings, and retry guidance" |
| Amazon Bedrock | https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock.md |
"Extract the AnthropicBedrockMantle client per language, anthropic.-prefixed model IDs, auth paths, feature availability, and regions" |
| Claude Platform on AWS | https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws.md |
"Extract the AnthropicAWS client per language, SigV4 auth, credential precedence, short-term API keys, workspace_id, and region requirements" |
| Claude Platform on AWS — IAM actions | https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions.md |
"Extract the IAM action names, resource ARNs, and policy examples required for each API capability" |
Tools
| Topic | URL | Extraction Prompt |
|---|---|---|
| Code Execution | https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool.md |
"Extract code execution tool setup, file upload, container reuse, and response handling" |
| Computer Use | https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use.md |
"Extract computer use tool setup, capabilities, and implementation examples" |
| Bash Tool | https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool.md |
"Extract bash tool schema, reference implementation, and security considerations" |
| Text Editor | https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool.md |
"Extract text editor tool commands, schema, and reference implementation" |
| Memory Tool | https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md |
"Extract memory tool commands, directory structure, and implementation patterns" |
| Tool Search | https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool.md |
"Extract tool search setup, when to use, and cache interaction" |
| Programmatic Tool Calling | https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling.md |
"Extract PTC setup, script execution model, and tool invocation from code" |
| Skills | https://platform.claude.com/docs/en/agents-and-tools/skills.md |
"Extract skill folder structure, SKILL.md format, and loading behavior" |
Advanced Features
| Topic | URL | Extraction Prompt |
|---|---|---|
| Structured Outputs | https://platform.claude.com/docs/en/build-with-claude/structured-outputs.md |
"Extract output_config.format usage and schema enforcement" |
| Compaction | https://platform.claude.com/docs/en/build-with-claude/compaction.md |
"Extract compaction setup, trigger config, and streaming with compaction" |
| Context Editing | https://platform.claude.com/docs/en/build-with-claude/context-editing.md |
"Extract context editing thresholds, what gets cleared, and configuration" |
| Citations | https://platform.claude.com/docs/en/build-with-claude/citations.md |
"Extract citation format and implementation" |
| Context Windows | https://platform.claude.com/docs/en/build-with-claude/context-windows.md |
"Extract context window sizes and token management" |
Managed Agents
Use these when a managed-agents binding, behavior, or wire-level detail isn't covered in the cached shared/managed-agents-*.md concept files or in {lang}/managed-agents/README.md.
| Topic | URL | Extraction Prompt |
|---|---|---|
| Overview | https://platform.claude.com/docs/en/managed-agents/overview.md |
"Extract the high-level architecture and how agents/sessions/environments/vaults fit together" |
| Quickstart | https://platform.claude.com/docs/en/managed-agents/quickstart.md |
"Extract the minimal end-to-end agent → environment → session → stream code path" |
| Agent Setup | https://platform.claude.com/docs/en/managed-agents/agent-setup.md |
"Extract agent create/update/list-versions/archive lifecycle and parameters" |
| Define Outcomes | https://platform.claude.com/docs/en/managed-agents/define-outcomes.md |
"Extract outcome definitions, evaluation hooks, and success criteria configuration" |
| Sessions | https://platform.claude.com/docs/en/managed-agents/sessions.md |
"Extract session lifecycle, status transitions, idle/terminated semantics, and resume rules" |
| Environments | https://platform.claude.com/docs/en/managed-agents/environments.md |
"Extract environment config (cloud/networking), management endpoints, and reuse model" |
| Self-Hosted Sandboxes | https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes.md |
"Extract config:{type:self_hosted}, ANTHROPIC_ENVIRONMENT_KEY, EnvironmentWorker.run/run_one, beta_agent_toolset, ant beta:worker poll/run, webhook-driven wake" |
| Self-Hosted Sandboxes — Security | https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-security.md |
"Extract what the customer owns (hardening, egress, key custody, trust boundaries) vs what Anthropic cannot do" |
| Events and Streaming | https://platform.claude.com/docs/en/managed-agents/events-and-streaming.md |
"Extract event stream types, stream-first ordering, reconnect/dedupe, and steering patterns" |
| Tools | https://platform.claude.com/docs/en/managed-agents/tools.md |
"Extract built-in toolset, custom tool definitions, and tool result wire format" |
| Files | https://platform.claude.com/docs/en/managed-agents/files.md |
"Extract file upload, mount paths, session resources, and listing/downloading session outputs" |
| Permission Policies | https://platform.claude.com/docs/en/managed-agents/permission-policies.md |
"Extract permission policy types (allow/deny/confirm) and per-tool config" |
| Multi-Agent | https://platform.claude.com/docs/en/managed-agents/multi-agent.md |
"Extract multi-agent composition patterns, sub-agent invocation, and result handoff" |
| Observability | https://platform.claude.com/docs/en/managed-agents/observability.md |
"Extract logging, tracing, and usage telemetry exposed by managed agents" |
| Webhooks | https://platform.claude.com/docs/en/managed-agents/webhooks.md |
"Extract webhook endpoint registration, HMAC signature verification, supported event types, and delivery semantics" |
| GitHub | https://platform.claude.com/docs/en/managed-agents/github.md |
"Extract github_repository resource shape, multi-repo mounting, and token rotation" |
| MCP Connector | https://platform.claude.com/docs/en/managed-agents/mcp-connector.md |
"Extract MCP server declaration on agents and vault-based credential injection at session" |
| Vaults | https://platform.claude.com/docs/en/managed-agents/vaults.md |
"Extract vault create, credential add/rotate, OAuth refresh shape, and archive" |
| Skills | https://platform.claude.com/docs/en/managed-agents/skills.md |
"Extract skill packaging and loading model for managed agents" |
| Memory | https://platform.claude.com/docs/en/managed-agents/memory.md |
"Extract memory resource shape, scoping, and lifecycle" |
| Onboarding | https://platform.claude.com/docs/en/managed-agents/onboarding.md |
"Extract first-run setup, prerequisites, and account/region requirements" |
| Cloud Containers | https://platform.claude.com/docs/en/managed-agents/cloud-containers.md |
"Extract cloud container runtime, image config, and network/storage knobs" |
| Migration | https://platform.claude.com/docs/en/managed-agents/migration.md |
"Extract migration paths from earlier APIs/preview shapes to GA managed agents" |
Anthropic CLI
The ant CLI provides terminal access to the Claude API. Every API resource is exposed as a subcommand. It is one convenient way to create agents, environments, sessions, and other resources from version-controlled YAML, and to inspect responses interactively.
| Topic | URL | Extraction Prompt |
|---|---|---|
| Anthropic CLI | https://platform.claude.com/docs/en/api/sdks/cli.md |
"Extract CLI install, authentication, command structure, and the beta:agents/environments/sessions commands" |
Claude API SDK Repositories
WebFetch these when a binding (class, method, namespace, field) isn't covered in the cached {lang}/ skill files or in the managed-agents docs above. The SDKs include beta managed-agents support for /v1/agents, /v1/sessions, /v1/environments, and related resources — search the repo for BetaManagedAgents, beta.agents, beta.sessions, or the equivalent namespace for that language.
| SDK | URL | Extraction Prompt |
|---|---|---|
| Python | https://github.com/anthropics/anthropic-sdk-python |
"Extract beta managed-agents namespaces, classes, and method signatures (client.beta.agents, client.beta.sessions)" |
| TypeScript | https://github.com/anthropics/anthropic-sdk-typescript |
"Extract beta managed-agents namespaces, classes, and method signatures (client.beta.agents, client.beta.sessions)" |
| Java | https://github.com/anthropics/anthropic-sdk-java |
"Extract beta managed-agents classes, builders, and method signatures (client.beta().agents(), BetaManagedAgents*)" |
| Go | https://github.com/anthropics/anthropic-sdk-go |
"Extract beta managed-agents types and method signatures (client.Beta.Agents, BetaManagedAgents* event types)" |
| Ruby | https://github.com/anthropics/anthropic-sdk-ruby |
"Extract beta managed-agents methods and parameter shapes (client.beta.agents, client.beta.sessions)" |
| C# | https://github.com/anthropics/anthropic-sdk-csharp |
"Extract beta managed-agents classes and method signatures (NuGet package, BetaManagedAgents* types)" |
| PHP | https://github.com/anthropics/anthropic-sdk-php |
"Extract beta managed-agents classes and method signatures ($client->beta->agents, BetaManagedAgents* params)" |
Fallback Strategy
If WebFetch fails (network issues, URL changed):
- Use cached content from the language-specific files (note the cache date)
- Inform user the data may be outdated
- Suggest they check platform.claude.com or the GitHub repos directly
All endpoints require x-api-key and anthropic-version: 2023-06-01 headers. Managed Agents endpoints additionally require the anthropic-beta header.
Beta Headers
anthropic-beta: managed-agents-2026-04-01
The SDK adds this header automatically for all client.beta.{agents,environments,sessions,vaults,memory_stores}.* calls. Skills endpoints use skills-2025-10-02; Files endpoints use files-api-2025-04-14.
SDK Method Reference
All resources are under the beta namespace. Python and TypeScript share identical method names.
| Resource | Python / TypeScript (client.beta.*) |
Go (client.Beta.*) |
|---|---|---|
| Agents | agents.create / retrieve / update / list / archive |
Agents.New / Get / Update / List / Archive |
| Agent Versions | agents.versions.list |
Agents.Versions.List |
| Environments | environments.create / retrieve / update / list / delete / archive |
Environments.New / Get / Update / List / Delete / Archive |
| Environment Work (self-hosted) | environments.work.poller / stats / stop |
See shared/managed-agents-self-hosted-sandboxes.md |
| Sessions | sessions.create / retrieve / update / list / delete / archive |
Sessions.New / Get / Update / List / Delete / Archive |
| Session Events | sessions.events.list / send / stream |
Sessions.Events.List / Send / StreamEvents |
| Session Threads | sessions.threads.list / retrieve / archive; sessions.threads.events.list / stream |
Sessions.Threads.List / Get / Archive; Sessions.Threads.Events.List / StreamEvents |
| Session Resources | sessions.resources.add / retrieve / update / list / delete |
Sessions.Resources.Add / Get / Update / List / Delete |
| Vaults | vaults.create / retrieve / update / list / delete / archive |
Vaults.New / Get / Update / List / Delete / Archive |
| Credentials | vaults.credentials.create / retrieve / update / list / delete / archive / mcp_oauth_validate |
Vaults.Credentials.New / Get / Update / List / Delete / Archive / McpOauthValidate |
| Memory Stores | memory_stores.create / retrieve / update / list / delete / archive |
MemoryStores.New / Get / Update / List / Delete / Archive |
| Memories | memory_stores.memories.create / retrieve / update / list / delete |
MemoryStores.Memories.New / Get / Update / List / Delete |
| Memory Versions | memory_stores.memory_versions.list / retrieve / redact |
MemoryStores.MemoryVersions.List / Get / Redact |
Naming quirks to watch for:
- Agents and Session Threads have no delete — only
archive. Archive is permanent: the agent becomes read-only, new sessions cannot reference it, and there is no unarchive. Confirm with the user before archiving a production agent. Environments, Sessions, Vaults, Credentials, and Memory Stores have bothdeleteandarchive; Session Resources, Files, Skills, and Memories aredelete-only; Memory Versions have neither — onlyredact. - Session resources use
add(notcreate). - Go's event stream is
StreamEvents(notStream). - The self-hosted worker is not under
client.beta.*— it'sEnvironmentWorkerfromanthropic.lib.environments/@anthropic-ai/sdk/helpers/beta/environments; onlyenvironments.work.poller/stats/stopare client methods.
Agent shorthand: agent on session create accepts either a bare string (agent="agent_abc123" — uses latest version) or the full reference object ({type: "agent", id: "agent_abc123", version: 123}).
Model shorthand: model on agent create accepts either a bare string (model="claude-opus-4-8" — uses standard speed) or the full config object ({id: "claude-opus-4-6", speed: "fast"}). Note: speed: "fast" is only supported on Opus 4.6.
Agents
Step one of every flow. Sessions require a pre-created agent — there is no inline agent config under managed-agents-2026-04-01.
| Method | Path | Operation | Description |
|---|---|---|---|
GET |
/v1/agents |
ListAgents | List agents |
POST |
/v1/agents |
CreateAgent | Create a saved agent configuration |
GET |
/v1/agents/{agent_id} |
GetAgent | Get agent details |
POST |
/v1/agents/{agent_id} |
UpdateAgent | Update agent configuration |
POST |
/v1/agents/{agent_id}/archive |
ArchiveAgent | Archive an agent. Makes it read-only; existing sessions continue, new sessions cannot reference it. No unarchive — this is the terminal state. |
GET |
/v1/agents/{agent_id}/versions |
ListAgentVersions | List agent versions |
Sessions
| Method | Path | Operation | Description |
|---|---|---|---|
GET |
/v1/sessions |
ListSessions | List sessions (paginated) |
POST |
/v1/sessions |
CreateSession | Create a new session |
GET |
/v1/sessions/{session_id} |
GetSession | Get session details |
POST |
/v1/sessions/{session_id} |
UpdateSession | Update session metadata/title, or agent.tools/agent.mcp_servers/vault_ids (session-local override; session must be idle). See shared/managed-agents-core.md → Updating the agent configuration mid-session. |
DELETE |
/v1/sessions/{session_id} |
DeleteSession | Delete a session |
POST |
/v1/sessions/{session_id}/archive |
ArchiveSession | Archive a session |
Events
| Method | Path | Operation | Description |
|---|---|---|---|
GET |
/v1/sessions/{session_id}/events |
ListEvents | List events (polling, paginated) |
POST |
/v1/sessions/{session_id}/events |
SendEvents | Send events (user message, tool result) |
GET |
/v1/sessions/{session_id}/events/stream |
StreamEvents | Stream events via SSE |
Session Threads
Per-subagent event streams in multiagent sessions. See shared/managed-agents-multiagent.md.
| Method | Path | Operation | Description |
|---|---|---|---|
GET |
/v1/sessions/{session_id}/threads |
ListThreads | List threads (paginated) |
GET |
/v1/sessions/{session_id}/threads/{thread_id} |
GetThread | Retrieve one thread (carries agent snapshot, status, parent_thread_id, stats, usage) |
POST |
/v1/sessions/{session_id}/threads/{thread_id}/archive |
ArchiveThread | Archive a thread |
GET |
/v1/sessions/{session_id}/threads/{thread_id}/events |
ListThreadEvents | List past events for one thread (paginated) |
GET |
/v1/sessions/{session_id}/threads/{thread_id}/stream |
StreamThreadEvents | Stream one thread via SSE (SDK: threads.events.stream) |
Session Resources
| Method | Path | Operation | Description |
|---|---|---|---|
GET |
/v1/sessions/{session_id}/resources |
ListResources | List resources attached to session |
POST |
/v1/sessions/{session_id}/resources |
AddResource | Attach file or github_repository resource (SDK method: add, not create). memory_store resources attach at session-create time only. |
GET |
/v1/sessions/{session_id}/resources/{resource_id} |
GetResource | Get a single resource |
POST |
/v1/sessions/{session_id}/resources/{resource_id} |
UpdateResource | Update resource |
DELETE |
/v1/sessions/{session_id}/resources/{resource_id} |
DeleteResource | Remove resource from session |
Environments
| Method | Path | Operation | Description |
|---|---|---|---|
POST |
/v1/environments |
CreateEnvironment | Create environment |
GET |
/v1/environments |
ListEnvironments | List environments |
GET |
/v1/environments/{environment_id} |
GetEnvironment | Get environment details |
POST |
/v1/environments/{environment_id} |
UpdateEnvironment | Update environment |
DELETE |
/v1/environments/{environment_id} |
DeleteEnvironment | Delete environment. Returns 204. |
POST |
/v1/environments/{environment_id}/archive |
ArchiveEnvironment | Archive environment. Makes it read-only; existing sessions continue, new sessions cannot reference it. No unarchive — this is the terminal state. |
GET |
/v1/environments/{environment_id}/work/stats |
WorkQueueStats | Self-hosted work-queue depth/pending/workers. x-api-key auth. See shared/managed-agents-self-hosted-sandboxes.md. |
POST |
/v1/environments/{environment_id}/work/{work_id}/stop |
StopWork | Self-hosted: stop a claimed work item. x-api-key auth. |
For type: "self_hosted", config is the bare {"type": "self_hosted"} — networking and packages do not apply.
Vaults
Vaults store MCP credentials that Anthropic manages on your behalf — OAuth credentials with auto-refresh, or static bearer tokens. Attach to sessions via vault_ids. See managed-agents-tools.md §Vaults for the conceptual guide and credential shapes.
| Method | Path | Operation | Description |
|---|---|---|---|
POST |
/v1/vaults |
CreateVault | Create a vault |
GET |
/v1/vaults |
ListVaults | List vaults |
GET |
/v1/vaults/{vault_id} |
GetVault | Get vault details |
POST |
/v1/vaults/{vault_id} |
UpdateVault | Update vault |
DELETE |
/v1/vaults/{vault_id} |
DeleteVault | Delete vault |
POST |
/v1/vaults/{vault_id}/archive |
ArchiveVault | Archive vault |
Credentials
Credentials are individual secrets stored inside a vault.
| Method | Path | Operation | Description |
|---|---|---|---|
POST |
/v1/vaults/{vault_id}/credentials |
CreateCredential | Create a credential |
GET |
/v1/vaults/{vault_id}/credentials |
ListCredentials | List credentials in vault |
GET |
/v1/vaults/{vault_id}/credentials/{credential_id} |
GetCredential | Get credential metadata |
POST |
/v1/vaults/{vault_id}/credentials/{credential_id} |
UpdateCredential | Update credential |
DELETE |
/v1/vaults/{vault_id}/credentials/{credential_id} |
DeleteCredential | Delete credential |
POST |
/v1/vaults/{vault_id}/credentials/{credential_id}/archive |
ArchiveCredential | Archive credential |
POST |
/v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate |
McpOauthValidate | Validate an MCP OAuth credential |
Memory Stores
Workspace-scoped persistent memory that survives across sessions. Attach to a session via a {"type": "memory_store", "memory_store_id": ...} entry in resources[] (session-create time only). See shared/managed-agents-memory.md for the conceptual guide, the FUSE-mount agent interface, preconditions, and versioning.
| Method | Path | Operation | Description |
|---|---|---|---|
POST |
/v1/memory_stores |
CreateMemoryStore | Create a store (name, description, metadata) |
GET |
/v1/memory_stores |
ListMemoryStores | List stores (include_archived, created_at_{gte,lte}) |
GET |
/v1/memory_stores/{memory_store_id} |
GetMemoryStore | Get store details |
POST |
/v1/memory_stores/{memory_store_id} |
UpdateMemoryStore | Update store |
DELETE |
/v1/memory_stores/{memory_store_id} |
DeleteMemoryStore | Delete store |
POST |
/v1/memory_stores/{memory_store_id}/archive |
ArchiveMemoryStore | Archive store. Makes it read-only; existing sessions continue, new sessions cannot reference it. No unarchive. |
Memories
Individual text documents inside a store (≤ 100KB each). create creates at a path and returns 409 (memory_path_conflict_error, with conflicting_memory_id) if the path is occupied; update mutates by mem_... ID (rename and/or content). Only update accepts a precondition ({"type": "content_sha256", "content_sha256": ...}) — on mismatch returns 409 (memory_precondition_failed_error). List endpoints accept view: "basic"|"full" (controls whether content is populated; retrieve defaults to full).
| Method | Path | Operation | Description |
|---|---|---|---|
GET |
/v1/memory_stores/{memory_store_id}/memories |
ListMemories | Returns Memory | MemoryPrefix; filter by path_prefix, depth, order_by/order |
POST |
/v1/memory_stores/{memory_store_id}/memories |
CreateMemory | Create at path (SDK: memories.create); 409 memory_path_conflict_error if occupied |
GET |
/v1/memory_stores/{memory_store_id}/memories/{memory_id} |
GetMemory | Read one memory (defaults to view="full") |
PATCH |
/v1/memory_stores/{memory_store_id}/memories/{memory_id} |
UpdateMemory | Change content, path, or both by ID; optional precondition |
DELETE |
/v1/memory_stores/{memory_store_id}/memories/{memory_id} |
DeleteMemory | Delete (optional expected_content_sha256) |
Memory Versions
Immutable per-mutation snapshots (memver_...) — the audit and rollback surface. operation ∈ created / modified / deleted.
| Method | Path | Operation | Description |
|---|---|---|---|
GET |
/v1/memory_stores/{memory_store_id}/memory_versions |
ListMemoryVersions | Newest-first; filter by memory_id, operation, session_id, api_key_id, created_at_{gte,lte} |
GET |
/v1/memory_stores/{memory_store_id}/memory_versions/{version_id} |
GetMemoryVersion | List fields + full content |
POST |
/v1/memory_stores/{memory_store_id}/memory_versions/{version_id}/redact |
RedactMemoryVersion | Clear content/content_sha256/content_size_bytes/path; preserve actor + timestamps |
Files
| Method | Path | Operation | Description |
|---|---|---|---|
POST |
/v1/files |
UploadFile | Upload a file |
GET |
/v1/files |
ListFiles | List files |
GET |
/v1/files/{file_id} |
GetFile | Get file metadata (SDK method: retrieve_metadata) |
GET |
/v1/files/{file_id}/content |
DownloadFile | Download file content |
DELETE |
/v1/files/{file_id} |
DeleteFile | Delete a file |
Skills
| Method | Path | Operation | Description |
|---|---|---|---|
POST |
/v1/skills |
CreateSkill | Create a skill |
GET |
/v1/skills |
ListSkills | List skills |
GET |
/v1/skills/{skill_id} |
GetSkill | Get skill details |
DELETE |
/v1/skills/{skill_id} |
DeleteSkill | Delete a skill |
POST |
/v1/skills/{skill_id}/versions |
CreateVersion | Create skill version |
GET |
/v1/skills/{skill_id}/versions |
ListVersions | List skill versions |
GET |
/v1/skills/{skill_id}/versions/{version} |
GetVersion | Get skill version |
DELETE |
/v1/skills/{skill_id}/versions/{version} |
DeleteVersion | Delete skill version |
Request/Response Schema Quick Reference
CreateAgent Request Body
Always start here. model, system, tools, mcp_servers, skills are top-level fields on this object — they do NOT go on the session.
{
"name": "string (required, 1-256 chars)",
"model": "claude-opus-4-8 (required — bare string, or {id, speed} object)",
"description": "string (optional, up to 2048 chars)",
"system": "string (optional, up to 100,000 chars)",
"tools": [
{ "type": "agent_toolset_20260401" }
],
"skills": [
{ "type": "anthropic", "skill_id": "xlsx" },
{ "type": "custom", "skill_id": "skill_abc123", "version": "1" }
],
"mcp_servers": [
{
"type": "url",
"name": "github",
"url": "https://api.githubcopilot.com/mcp/"
}
],
"multiagent": {
"type": "coordinator",
"agents": [
"agent_abc123",
{ "type": "agent", "id": "agent_def456", "version": 4 },
{ "type": "self" }
]
},
"metadata": {
"key": "value (max 16 pairs, keys ≤64 chars, values ≤512 chars)"
}
}
Limits:
toolsmax 128,skillsmax 20,mcp_serversmax 20 (unique names).multiagent.agents1–20 entries (string ID |{type:"agent",id,version?}|{type:"self"}) — seeshared/managed-agents-multiagent.md.
CreateSession Request Body
{
"agent": "agent_abc123 (required — string shorthand for latest version, or {type: \"agent\", id, version} object)",
"environment_id": "env_abc123 (required)",
"title": "string (optional)",
"resources": [
{
"type": "github_repository",
"url": "https://github.com/owner/repo (required)",
"authorization_token": "ghp_... (required)",
"mount_path": "/workspace/repo (optional — defaults to /workspace/<repo-name>)",
"checkout": { "type": "branch", "name": "main" }
}
],
"vault_ids": ["vlt_abc123 (optional — MCP credentials with auto-refresh)"],
"metadata": {
"key": "value"
}
}
The
agentfield accepts only a string ID or{type: "agent", id, version}—model/system/toolslive on the agent, not here.
checkoutaccepts{type: "branch", name: "..."}or{type: "commit", sha: "..."}. Omit for the repo's default branch.
CreateEnvironment Request Body
{
"name": "string (required)",
"description": "string (optional)",
"config": {
"type": "cloud | self_hosted",
"networking": {
"type": "unrestricted | limited (union — see SDK types)"
},
"packages": { }
},
"metadata": { "key": "value" }
}
SendEvents Request Body
{
"events": [
{
"type": "user.message",
"content": [
{
"type": "text",
"text": "Hello"
}
]
}
]
}
Define Outcome Event
{
"type": "user.define_outcome",
"description": "Build a DCF model for Costco in .xlsx",
"rubric": { "type": "file", "file_id": "file_01..." },
"max_iterations": 5
}
rubricis required:{type: "text", content}or{type: "file", file_id}.max_iterationsdefault 3, max 20. Echoed back withoutcome_id+processed_at. Seeshared/managed-agents-outcomes.md.
Tool Result Event
{
"type": "user.custom_tool_result",
"custom_tool_use_id": "sevt_abc123",
"content": [{ "type": "text", "text": "Result data" }],
"is_error": false
}
Error Handling
Managed Agents endpoints use the standard Anthropic API error format. Errors are returned with an HTTP status code and a JSON body containing type, error, and request_id:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Description of what went wrong"
},
"request_id": "req_011CRv1W3XQ8XpFikNYG7RnE"
}
Include the request_id when reporting issues to Anthropic — it lets us trace the request end-to-end. The inner error.type is one of the following:
| Status | Error type | Description |
|---|---|---|
| 400 | invalid_request_error |
The request was malformed or missing required parameters |
| 401 | authentication_error |
Invalid or missing API key |
| 403 | permission_error |
The API key doesn't have permission for this operation |
| 404 | not_found_error |
The requested resource doesn't exist |
| 409 | invalid_request_error |
The request conflicts with the resource's current state (e.g., sending to an archived session) |
| 413 | request_too_large |
The request body exceeds the maximum allowed size |
| 429 | rate_limit_error |
Too many requests — check rate limit headers for retry timing |
| 500 | api_error |
An internal server error occurred |
| 529 | overloaded_error |
The service is temporarily overloaded — retry with backoff |
Note that 409 Conflict carries error.type: "invalid_request_error" (there is no separate conflict_error type); inspect both the HTTP status and the message to distinguish conflicts from other invalid requests.
Rate Limits
Managed Agents endpoints have per-organization request-per-minute (RPM) limits, separate from your Messages API token limits. Model inference inside a session still draws from your organization's standard ITPM/OTPM limits.
| Endpoint group | Scope | RPM | Max concurrent |
|---|---|---|---|
| Create operations (Agents, Sessions, Vaults) | organization | 300 | — |
| All other operations (Agents, Sessions, Vaults) | organization | 600 | — |
| All operations (Environments) | organization | 60 | 5 |
Files and Skills endpoints use the standard tier-based rate limits.
When a limit is exceeded the API returns 429 with a rate_limit_error (see Error Handling for the response envelope) and a retry-after header indicating how many seconds to wait before retrying. The Anthropic SDK reads this header and retries automatically.
Patterns you'll write on the client side when driving a Managed Agent session, grounded in working SDK examples.
Code samples are TypeScript — Python and cURL follow the same shape; see python/managed-agents/README.md and curl/managed-agents.md for equivalents.
1. Lossless stream reconnect
Problem: SSE has no replay. If the connection drops mid-session, a naive reconnect re-opens the stream from "now" and you silently miss every event emitted in between.
Solution: on reconnect, fetch the full event history via events.list() before consuming the live stream, and dedupe on event ID as the live stream catches up.
const seenEventIds = new Set<string>()
const stream = await client.beta.sessions.events.stream(session.id)
// Stream is now open and buffering server-side. Read history first.
for await (const event of client.beta.sessions.events.list(session.id)) {
seenEventIds.add(event.id)
handle(event)
}
// Tail the live stream. Dedupe only gates handle() — terminal checks must run
// even for already-seen events, or a terminal event that was in the history
// response gets skipped by `continue` and the loop never exits.
for await (const event of stream) {
if (!seenEventIds.has(event.id)) {
seenEventIds.add(event.id)
handle(event)
}
if (event.type === 'session.status_terminated') break
if (event.type === 'session.status_idle' && event.stop_reason.type !== 'requires_action') break
}
2. processed_at — queued vs processed
Every event on the stream carries processed_at (ISO 8601). For client-sent events (user.message, user.interrupt, user.tool_confirmation, user.custom_tool_result) it's null when the event has been queued but not yet picked up by the agent, and populated once the agent processes it. The same event appears on the stream twice — once with processed_at: null, once with a timestamp.
for await (const event of stream) {
if (event.type === 'user.message') {
if (event.processed_at == null) onQueued(event.id)
else onProcessed(event.id, event.processed_at)
}
}
Use this to drive pending → acknowledged UI state for anything you send. How you map a locally-rendered optimistic message to the server-assigned event.id is application-specific (typically via the return value of events.send() or FIFO ordering).
3. Interrupt a running session
Send user.interrupt as a normal event. The session keeps running until it reaches a safe boundary, then goes idle.
await client.beta.sessions.events.send(session.id, {
events: [{ type: 'user.interrupt' }],
})
// Drain until the session is truly done — see Pattern 5 for the full gate.
for await (const event of stream) {
if (event.type === 'session.status_terminated') break
if (
event.type === 'session.status_idle' &&
event.stop_reason.type !== 'requires_action'
) break
}
Reference: interrupt.ts — sends the interrupt the moment it sees span.model_request_start, drains to idle, then verifies via sessions.retrieve().
4. tool_confirmation round-trip
When the agent has permission_policy: { type: 'always_ask' }, any call to that tool fires an agent.tool_use event with evaluated_permission === 'ask' and the session goes idle waiting for a decision. Respond with user.tool_confirmation.
for await (const event of stream) {
if (event.type === 'agent.tool_use' && event.evaluated_permission === 'ask') {
await client.beta.sessions.events.send(session.id, {
events: [{
type: 'user.tool_confirmation',
tool_use_id: event.id, // not a toolu_ id — use event.id
result: 'allow', // or 'deny'
// deny_message: '...', // optional, only with result: 'deny'
}],
})
}
}
Key points:
tool_use_idisevent.id(typicallysevt_...), not atoolu_...ID.resultis'allow' | 'deny'. Usedeny_messageto tell the model why you denied — it gets surfaced back to the agent.- Multiple pending tools: respond once per
agent.tool_useevent withevaluated_permission === 'ask'.
Reference: tool-permissions.ts.
5. Correct idle-break gate
Do not break on session.status_idle alone. The session goes idle transiently — e.g. between parallel tool executions, while waiting for a user.tool_confirmation, or while awaiting a user.custom_tool_result. Break when idle with a terminal stop_reason, or on session.status_terminated.
for await (const event of stream) {
handle(event)
if (event.type === 'session.status_terminated') break
if (event.type === 'session.status_idle') {
if (event.stop_reason.type === 'requires_action') continue // waiting on you — handle it
break // end_turn or retries_exhausted — both terminal
}
}
stop_reason.type values on session.status_idle:
requires_action— agent is waiting on a client-side event (tool confirmation, custom tool result). Handle it, don't break.retries_exhausted— terminal failure. Break, then checksessions.retrieve()for the error state.end_turn— normal completion.
6. Post-idle status-write race
The SSE stream emits session.status_idle slightly before the session's queryable status reflects it. Clients that break on idle and immediately call sessions.delete() or sessions.archive() will intermittently 400 with "cannot delete/archive while running."
Poll before cleanup:
let s
for (let i = 0; i < 10; i++) {
s = await client.beta.sessions.retrieve(session.id)
if (s.status !== 'running') break
await new Promise(r => setTimeout(r, 200))
}
if (s?.status !== 'running') {
await client.beta.sessions.archive(session.id)
} // else: still running after 2s — don't archive, let it settle or escalate
7. Stream-first, then send
Always open the stream before sending the kickoff event. Otherwise the agent may process the event and emit the first events before your consumer is attached, and you'll miss them.
const stream = await client.beta.sessions.events.stream(session.id)
await client.beta.sessions.events.send(session.id, {
events: [{ type: 'user.message', content: [{ type: 'text', text: 'Hello' }] }],
})
for await (const event of stream) { /* ... */ }
The Promise.all([stream, send]) shape works too, but stream-first is simpler and has the same effect — the stream starts buffering the moment it's opened.
8. File-mount gotchas
The mounted resource has a different file_id than the file you uploaded. Session creation makes a session-scoped copy.
const uploaded = await client.beta.files.upload({ file, purpose: 'agent_resource' })
// uploaded.id → the original file
const session = await client.beta.sessions.create({
/* ... */
resources: [{ type: 'file', file_id: uploaded.id, mount_path: '/workspace/data.csv' }],
})
// session.resources[0].file_id !== uploaded.id ← different IDs
Delete the original via files.delete(uploaded.id); the session-scoped copy is garbage-collected with the session. mount_path must be absolute — see shared/managed-agents-environments.md.
9. Secrets for non-MCP APIs and CLIs — keep them host-side via custom tools
Problem: you want the agent to call a third-party API or run a CLI that needs a secret (API key, token, service-account credential), but there is currently no way to set environment variables inside the session container, and vaults currently hold MCP credentials only — they are not exposed to the container's shell. So curl, installed CLIs, or SDK clients running via the bash tool have no first-class place to read a secret from.
Solution: move the authenticated call to your side. Declare a custom tool on the agent; when the agent emits agent.custom_tool_use, your orchestrator (the process reading the SSE stream) executes the call with its own credentials and responds with user.custom_tool_result. The container never sees the key.
// Agent template: declare the tool, no credentials
tools: [{ type: 'custom', name: 'linear_graphql', input_schema: { /* query, vars */ } }]
// Orchestrator: handle the call with host-side creds
for await (const event of stream) {
if (event.type === 'agent.custom_tool_use' && event.name === 'linear_graphql') {
const result = await linear.request(event.input.query, event.input.vars) // host's key
await client.beta.sessions.events.send(session.id, {
events: [{ type: 'user.custom_tool_result', tool_use_id: event.id, result }],
})
}
}
Same shape works for gh CLI, local eval scripts, or anything else that needs host-side auth or binaries.
Security note: this does not expose a public endpoint. agent.custom_tool_use arrives on the SSE stream your orchestrator already holds open with your Anthropic API key, and user.custom_tool_result goes back via events.send() under the same key. Your orchestrator is a client, not a server — nothing unauthenticated is listening.
Do not embed API keys in the system prompt or user messages as a workaround. Prompts and messages are stored in the session's event history, returned by events.list(), and included in compaction summaries — a secret placed there is durably persisted and readable via the API for the life of the session.
Architecture
Managed Agents is built around four core concepts:
| Concept | Endpoint | What it is |
|---|---|---|
| Agent | /v1/agents |
A persisted, versioned object defining the agent's capabilities and persona: model, system prompt, tools, MCP servers, skills. Must be created before starting a session. See the Agents section below. |
| Session | /v1/sessions |
A stateful interaction with an agent. References a pre-created agent by ID + an environment + initial instructions. Produces an event stream. |
| Environment | /v1/environments |
A template defining the configuration for container provisioning. |
| Container | N/A | An isolated compute instance where the agent's tools execute (bash, file ops, code). The agent loop does not run here — it runs on Anthropic's orchestration layer and acts on the container via tool calls. |
┌─────────────────────────────────────┐
│ Anthropic orchestration layer │
Agent (config) ───────▶│ (agent loop: Claude + tool calls) │
└──────────────┬──────────────────────┘
│ tool calls
▼
Environment (template) ──▶ Container (tool execution workspace)
│
Session ─┤
├── Resources (files, repos, memory stores — attached at startup)
├── Vault IDs (MCP credential references)
└── Conversation (event stream in/out)
Agent creation is a prerequisite. Sessions reference a pre-created agent by ID —
model/system/toolslive on the agent object, never on the session. Every flow starts withPOST /v1/agents.
Session Lifecycle
rescheduling → running ↔ idle → terminated
| Status | Description |
|---|---|
idle |
Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a user.message or blocked awaiting a user.custom_tool_result or user.tool_confirmation. The stop_reason attached contains more information about why the Agent has stopped working. |
running |
Session has starting running, and the Agent is actively doing work. |
rescheduling |
Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. |
terminated |
Session has terminated, entering an irreversible and unusable state. |
- Events can be sent when the session is
runningoridle. Messages are queued and processed in order. - The agent transitions
idle → runningwhen it receives a new event, then back toidlewhen done. - Errors surface as
session.errorevents in the stream, not as a status value.
Built-in session features
- Context compaction — if you approach max context, the API automatically condenses session history to keep the interaction going
- Prompt caching — historical repeated tokens are cached, reducing processing time and cost
- Extended thinking — on by default, returned as
agent.thinkingevents
Session operations
| Operation | Notes |
|---|---|
| List / fetch | Paginated list or single resource by ID |
| Update | Only title is updatable |
| Archive | Session becomes read-only. Not reversible. |
| Delete | Permanently deletes session, event history, container, and checkpoints. |
These are ops/inspection calls — typically made from a terminal, not application code. From the shell (see shared/anthropic-cli.md):
ant beta:sessions list --transform '{id,title,status,created_at}' --format jsonl
ant beta:sessions retrieve --session-id "$SID"
ant beta:sessions:events stream --session-id "$SID" # watch events live
ant beta:sessions archive --session-id "$SID"
ant beta:sessions delete --session-id "$SID"
Sessions
A session is a running agent instance inside an environment.
Session Object
Key fields returned by the API:
| Field | Type | Description |
|---|---|---|
type |
string | Always "session" |
id |
string | Unique session ID |
title |
string | Human-readable title |
status |
string | idle, running, rescheduling, terminated |
created_at |
string | ISO 8601 timestamp |
updated_at |
string | ISO 8601 timestamp |
archived_at |
string | ISO 8601 timestamp (nullable) |
environment_id |
string | Environment ID |
agent |
object | Agent configuration |
resources |
array | Attached files, repos, and memory stores |
metadata |
object | User-provided key-value pairs (max 8 keys) |
usage |
object | Token usage statistics |
Creating a session
A session is meaningless without an agent. Sessions reference a pre-created agent by ID. Create the agent first via agents.create(), then reference it:
// 1. Create the agent (reusable, versioned)
const agent = await client.beta.agents.create(
{
name: "Coding Assistant",
model: "claude-opus-4-8",
system: "You are a helpful coding agent.",
tools: [{ type: "agent_toolset_20260401"}],
},
);
// 2. Start a session that references it
const session = await client.beta.sessions.create(
{
agent: agent.id, // string shorthand → latest version. Or: { type: "agent", id: agent.id, version: agent.version }
environment_id: environmentId,
title: "Hello World Session",
},
);
💡 Watch it live in Console. While developing, print a link so you can click through to the session UI instead of parsing the event stream:
https://platform.claude.com/workspaces/{workspace}/sessions/{session.id}. Usedefaultfor the workspace slug unless you created the session in a non-default workspace; the sessions list for your workspace is athttps://platform.claude.com/workspaces/default/sessions. Include thisconsole.login code you generate for users who are iterating locally.
Session creation parameters:
| Field | Type | Required | Description |
|---|---|---|---|
agent |
string or object | Yes | String shorthand "agent_abc123" (latest version) or {type: "agent", id, version} |
environment_id |
string | Yes | Environment ID |
title |
string | No | Human-readable name (appears in logs/dashboards) |
resources |
array | No | Files, GitHub repos, or memory stores, attached to the container at startup. Memory stores are session-create-only (not addable via resources.add()). |
vault_ids |
array | No | Vault IDs (vlt_*) — MCP credentials with auto-refresh. See shared/managed-agents-tools.md → Vaults. |
metadata |
object | No | User-provided key-value pairs |
Agent configuration fields (passed to agents.create(), not sessions.create()):
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Human-readable name (1-256 chars) |
model |
string or object | Yes | Claude model ID (bare string, or {id, speed} object). All Claude 4.5+ models supported. |
system |
string | No | System prompt — defines the agent's behavior (up to 100K chars) |
tools |
array | No | Encompasses three kinds: (1) pre-built Claude Agent tools (agent_toolset_20260401), (2) MCP tools (mcp_toolset), and (3) custom client-side tools. Max 128. |
mcp_servers |
array | No | MCP server connections — standardized third-party capabilities (e.g. GitHub, Asana). Max 20, unique names. See shared/managed-agents-tools.md → MCP Servers. |
skills |
array | No | Customized "best-practices" context with progressive disclosure. Max 20. See shared/managed-agents-tools.md → Skills. |
description |
string | No | Description of the agent (up to 2048 chars) |
multiagent |
object | No | {type: "coordinator", agents: [...]} — roster this agent may delegate to. See shared/managed-agents-multiagent.md. |
metadata |
object | No | Arbitrary key-value pairs (max 16, keys ≤64 chars, values ≤512 chars) |
Agents
This is where every Managed Agents flow begins. The agent object is a persisted, versioned configuration — you create it once, then reference it by ID every time you start a session. No agent → no session.
Agent Object
The API is flat — model, system, tools etc. are top-level fields, not wrapped in an agent:{} sub-object.
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Human-readable name |
model |
string | Yes | Claude model ID |
system |
string | No | System prompt |
tools |
array | No | Agent toolset / MCP toolset / custom tools |
mcp_servers |
array | No | MCP server connections |
skills |
array | No | Skill references (max 20) |
description |
string | No | Description of the agent |
multiagent |
object | No | Coordinator roster — see shared/managed-agents-multiagent.md |
metadata |
object | No | Arbitrary key-value pairs |
Lifecycle: create once, run many, update in place
The agent is a persistent resource, not a per-run parameter. The intended pattern:
┌─ setup (once) ─────────┐ ┌─ runtime (every invocation) ─┐
│ agents.create() │ │ sessions.create( │
│ → store agent_id │ ──→ │ agent={type:..., id: ID} │
│ in config/env/db │ │ ) │
└────────────────────────┘ └──────────────────────────────┘
Anti-pattern: calling agents.create() at the top of every script run. This accumulates orphaned agent objects, pays create latency on every invocation, and defeats the versioning model. If you see agents.create() in a function that's called per-request or per-cron-tick, that's wrong — hoist it to one-time setup and persist the ID.
Recommended — define agents and environments as YAML + apply via the
antCLI. The split is CLI for the control plane, SDK for the data plane: agents and environments are relatively static resources you manage withant(version-controlled YAML, applied from CI); sessions are dynamic and driven by your application through the SDK. Seeshared/anthropic-cli.md→ Version-controlled Managed Agents resources for theant beta:agents create < agent.yaml/update --version Nflow. The SDKagents.create()call shown elsewhere in this doc is the in-code equivalent — use it when you need to provision programmatically, but prefer the YAML flow for anything a human maintains.
Versioning
Each POST /v1/agents/{id} (update) creates a new immutable version (numeric timestamp, e.g. 1772585501101368014). The agent's history is append-only — you can't edit a past version.
Why version:
- Reproducibility — pin a session to a known-good config:
{type: "agent", id, version: 3} - Safe iteration — update the agent without breaking sessions already running on the old version
- Rollback — if a new system prompt regresses, pin new sessions back to the prior version while you debug
version is optional. Omit it (or use the string shorthand agent="agent_abc123") to get the latest version at session-creation time. Pass it explicitly ({type: "agent", id, version: N}) to pin for reproducibility.
Getting the version to pin: agents.create() and agents.update() both return version in the response. Store it alongside agent_id. To fetch the current latest for an existing agent: GET /v1/agents/{id} → .version.
When to update vs create new: Update (POST /v1/agents/{id}) when it's conceptually the same agent with tweaked behavior (better prompt, extra tool). Create a new agent when it's a different persona/purpose. Rule of thumb: if you'd give it the same name, update.
Agent Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST |
/v1/agents |
| List | GET |
/v1/agents |
| Get | GET |
/v1/agents/{id} |
| Update | POST |
/v1/agents/{id} |
| Archive | POST |
/v1/agents/{id}/archive |
⚠️ Archive is permanent. Archiving makes the agent read-only: existing sessions continue to run, but new sessions cannot reference it, and there is no unarchive. Since agents have no
delete, this is the terminal lifecycle state. Never archive a production agent as routine cleanup — confirm with the user first.
Using an Agent in a Session
Reference the agent by string ID (latest version) or by object with an explicit version:
# String shorthand — uses the agent's latest version
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment_id,
)
# Or pin to a specific version (int)
session = client.beta.sessions.create(
agent={"type": "agent", "id": agent.id, "version": agent.version},
environment_id=environment_id,
)
Updating the agent configuration mid-session
sessions.update() can change agent.tools, agent.mcp_servers (including permission policies), and vault_ids on an existing session. This is a session-local override — it does not create a new agent version and does not propagate back to the agent object. The provided arrays are full replacements; to append one tool, GET the session, modify, and POST back. The session must be idle — interrupt first if running.
client.beta.sessions.update(
session.id,
agent={
"tools": [
{"type": "agent_toolset_20260401"},
{"type": "mcp_toolset", "mcp_server_name": "linear"},
],
"mcp_servers": [{"type": "url", "name": "linear", "url": "https://mcp.linear.app/sse"}],
},
vault_ids=["vlt_..."],
)
Environments
Creating a session requires an environment_id. Environments are reusable configuration templates for spinning up containers in Anthropic's infrastructure — you might create different environments for different use cases (e.g. data visualization vs web development, with different package sets). Anthropic handles scaling, container lifecycle, and work orchestration.
Environment names must be unique. Creating an environment with an existing name returns 409.
Networking
| Network Policy | Description |
|---|---|
unrestricted |
Full egress (except legal blocklist) |
limited |
Deny-by-default; opt in via allowed_hosts / allow_package_managers / allow_mcp_servers |
{
"networking": {
"type": "limited",
"allow_package_managers": true,
"allow_mcp_servers": true,
"allowed_hosts": ["api.example.com"]
}
}
All three limited fields are optional. allow_package_managers (default false) permits PyPI/npm/etc.; allow_mcp_servers (default false) permits the agent's configured MCP server endpoints without listing them in allowed_hosts.
MCP caveat: Under limited networking, either set allow_mcp_servers: true or add each MCP server domain to allowed_hosts. Otherwise the container can't reach them and tools silently fail.
Creating an environment
The SDK adds managed-agents-2026-04-01 automatically. TypeScript:
const env = await client.beta.environments.create({
name: "my_env",
config: {
type: "cloud",
networking: { type: "unrestricted" },
},
});
Self-hosted sandboxes
To run tool execution in your own infrastructure instead of Anthropic's, set config: {type: "self_hosted"} — the agent loop stays on Anthropic's side, but bash / file ops / code execute in a container you control via an outbound-polling worker. The networking block does not apply (you control egress). Resource mounting (file, github_repository) and memory stores behave differently — see shared/managed-agents-self-hosted-sandboxes.md for the worker, credentials, and cloud-vs-self-hosted comparison.
Environment CRUD
| Operation | Method | Path | Notes |
|---|---|---|---|
| Create | POST |
/v1/environments |
|
| List | GET |
/v1/environments |
Paginated (limit, after_id, before_id) |
| Get | GET |
/v1/environments/{id} |
|
| Update | POST |
/v1/environments/{id} |
Changes apply only to new containers; existing sessions keep their original config |
| Delete | DELETE |
/v1/environments/{id} |
Returns 204. |
| Archive | POST |
/v1/environments/{id}/archive |
Makes it read-only; existing sessions continue, new sessions cannot reference it. No unarchive — terminal state. |
Resources
Attach files, GitHub repositories, and memory stores to a session. Session creation blocks until all resources are mounted — the container won't go running until every file and repo is in place. Max 999 file resources per session. Multiple GitHub repositories per session are supported. For type: "memory_store" resources (persistent cross-session memory — max 8 per session), see shared/managed-agents-memory.md.
File Uploads (input — host → agent)
Upload a file first via the Files API, then reference by file_id + mount_path:
// 1. Upload
const file = await client.beta.files.upload({
file: fs.createReadStream("data.csv"),
purpose: "agent",
});
// 2. Attach as a session resource
const session = await client.beta.sessions.create({
agent: agent.id,
environment_id: envId,
resources: [
{ type: "file", file_id: file.id, mount_path: "/workspace/data.csv" }
],
});
mount_path is required and must be absolute. Parent directories are created automatically. Agent working directory defaults to /workspace. Files are mounted read-only — the agent writes modified versions to new paths.
Session outputs (output — agent → host)
The agent can write files to /mnt/session/outputs/ during a session. These are automatically captured by the Files API and can be listed and downloaded afterwards:
// After the turn completes, list output files scoped to this session:
for await (const f of client.beta.files.list({
scope_id: session.id,
betas: ["managed-agents-2026-04-01"],
})) {
console.log(f.filename, f.size_bytes);
const resp = await client.beta.files.download(f.id);
const text = await resp.text();
}
Requirements:
- The
writetool (orbash) must be enabled for the agent to create output files. - Session-scoped
files.list/files.downloadcaptures outputs written to/mnt/session/outputs/. - The filter parameter is
scope_id(REST query param?scope_id=<session_id>). The SDK's files resource auto-adds only thefiles-api-2025-04-14header, so passbetas: ["managed-agents-2026-04-01"]explicitly (or both headers on raw HTTP) — without it the API may rejectscope_idas an unknown field. Requires@anthropic-ai/sdk≥ 0.88.0 /anthropic(Python) ≥ 0.92.0 — older versions don't typescope_id. TheantCLI does not expose this flag yet; use the SDK or curl. - Pass the session ID returned by
sessions.create()verbatim (e.g.sesn_011CZx...) — the API validates the prefix. - There's a brief indexing lag (~1–3s) between
session.status_idleand output files appearing infiles.list. Retry once or twice if empty.
Fallback when
scope_idfiltering is unavailable (older SDK, or endpoint returns an error): send a follow-upuser.messageasking the agent toreadeach file under/mnt/session/outputs/and return the contents. The agent streams the file bodies back asagent.messagetext. This works for text files only and costs output tokens — use it to unblock, not as the primary path.
This gives you a bidirectional file bridge: upload reference data in, download agent artifacts out.
GitHub Repositories
Clones a GitHub repository into the session container during initialization, before the agent begins execution. The agent can read, edit, commit, and push via bash (git). Multiple repositories per session are supported — add one resources entry per repo. Repositories are cached, so future sessions that use the same repository start faster.
Repositories are attached for the lifetime of the session — to change which repositories are mounted, create a new session. You can rotate a repository's authorization_token on a running session via client.beta.sessions.resources.update(resource_id, {session_id, authorization_token}); the resource id is returned at session creation and by resources.list().
Fields:
| Field | Required | Notes |
|---|---|---|
type |
✅ | "github_repository" |
url |
✅ | The GitHub repository URL |
authorization_token |
✅ | GitHub Personal Access Token with repository access. Never echoed in API responses. |
mount_path |
❌ | Path where the repository will be cloned. Defaults to /workspace/<repo-name>. |
checkout |
❌ | {type: "branch", name: "..."} or {type: "commit", sha: "..."}. Defaults to the repo's default branch. |
Token permission levels (fine-grained PATs):
Contents: Read— clone onlyContents: Read and write— push changes and create pull requests
How auth works: authorization_token is never placed inside the container. git pull / git push and GitHub REST calls against the attached repository are routed through an Anthropic-side git proxy that injects the token after the request leaves the sandbox. Code running in the container — including anything the agent writes — cannot read or exfiltrate it.
‼️ To generate pull requests you also need GitHub MCP server access — the
github_repositoryresource gives filesystem + git access only. Seeshared/managed-agents-tools.md→ MCP Servers. The PR workflow is: edit files in the mounted repo → push branch viabash(authenticated via the git proxy usingauthorization_token) → create PR via the MCPcreate_pull_requesttool (authenticated via the vault).
TypeScript:
// 1. Create the agent — declare GitHub MCP (no auth here)
const agent = await client.beta.agents.create(
{
name: 'GitHub Agent',
model: 'claude-opus-4-8',
mcp_servers: [
{ type: 'url', name: 'github', url: 'https://api.githubcopilot.com/mcp/' },
],
tools: [
{ type: 'agent_toolset_20260401', default_config: { enabled: true } },
{ type: 'mcp_toolset', mcp_server_name: 'github' },
],
},
);
// 2. Start a session — attach vault for MCP auth + mount the repo
const session = await client.beta.sessions.create({
agent: agent.id,
environment_id: envId,
vault_ids: [vaultId], // vault contains the GitHub MCP OAuth credential
resources: [
{
type: 'github_repository',
url: 'https://github.com/owner/repo',
authorization_token: process.env.GITHUB_TOKEN, // repo clone token (≠ MCP auth)
checkout: { type: 'branch', name: 'main' },
},
],
});
Python:
import os
agent = client.beta.agents.create(
name="GitHub Agent",
model="claude-opus-4-8",
mcp_servers=[{
"type": "url",
"name": "github",
"url": "https://api.githubcopilot.com/mcp/",
}],
tools=[
{"type": "agent_toolset_20260401", "default_config": {"enabled": True}},
{"type": "mcp_toolset", "mcp_server_name": "github"},
],
)
session = client.beta.sessions.create(
agent=agent.id,
environment_id=env_id,
vault_ids=[vault_id], # vault contains the GitHub MCP OAuth credential
resources=[{
"type": "github_repository",
"url": "https://github.com/owner/repo",
"authorization_token": os.environ["GITHUB_TOKEN"], # repo clone token (≠ MCP auth)
"checkout": {"type": "branch", "name": "main"},
}],
)
Files API
Upload and manage files for use as session resources, and download files the agent wrote to /mnt/session/outputs/.
| Operation | Method | Path | SDK |
|---|---|---|---|
| Upload | POST |
/v1/files |
client.beta.files.upload({ file }) |
| List | GET |
/v1/files?scope_id=... |
client.beta.files.list({ scope_id, betas: ["managed-agents-2026-04-01"] }) |
| Get Metadata | GET |
/v1/files/{id} |
client.beta.files.retrieveMetadata(id) |
| Download | GET |
/v1/files/{id}/content |
client.beta.files.download(id) → Response |
| Delete | DELETE |
/v1/files/{id} |
client.beta.files.delete(id) |
The scope_id filter on List scopes the results to files written to /mnt/session/outputs/ by that session. Without the filter, you get all files uploaded to your account.
Events
Sending Events
Send events to a session via POST /v1/sessions/{id}/events.
| Event Type | When to Send |
|---|---|
user.message |
Send a user message |
user.interrupt |
Interrupt the agent while it's running |
user.tool_confirmation |
Approve/deny a tool call (when always_ask policy) |
user.custom_tool_result |
Provide result for a custom tool call |
user.define_outcome |
Start a rubric-graded iterate loop — see shared/managed-agents-outcomes.md |
Receiving Events
Three methods:
- Streaming (SSE):
GET /v1/sessions/{id}/events/stream— real-time Server-Sent Events. Long-lived — the server sends periodic heartbeats to keep the connection alive. - Polling:
GET /v1/sessions/{id}/events— paginated event list (query params:limitdefault 1000,page). Returns immediately — this is a plain paginated GET, not a long-poll. - Webhooks: Anthropic POSTs session state transitions to your HTTPS endpoint — thin payloads (IDs only), HMAC-signed, Console-registered. See
shared/managed-agents-webhooks.md.
All received events carry id, type, and processed_at (ISO 8601; null if not yet processed by the agent).
⚠️ Robust polling (raw HTTP). If you bypass the SDK and roll your own poll loop, don't rely on
requestsorhttpxtimeouts as wall-clock caps — they're per-chunk read timeouts, reset every time a byte arrives. A trickling response (heartbeats, a wedged chunked-encoding body, a misbehaving proxy) can keep the call blocked indefinitely even withtimeout=(5, 60)orhttpx.Timeout(120). Neither library has a "total wall-clock" timeout built in. For a hard deadline: tracktime.monotonic()at the loop level and break/cancel if a single request exceeds your budget (e.g. via a watchdog thread, orasyncio.wait_for()around async httpx). Prefer the SDK —client.beta.sessions.events.stream()andclient.beta.sessions.events.list()handle timeout + retry sanely.If
GET /v1/sessions/{id}/events(paginated) ever hangs after headers, you've likely hitGET /v1/sessions/{id}/eventsby mistake or a server-side stall — report it; don't treat it as a client-config problem.
Event Types (Received)
Event types use dot notation, grouped by namespace:
| Event Type | Description |
|---|---|
agent.message |
Agent text output |
agent.thinking |
Extended thinking blocks |
agent.tool_use |
Agent used a built-in tool (agent_toolset_20260401) |
agent.tool_result |
Result from a built-in tool |
agent.mcp_tool_use |
Agent used an MCP tool |
agent.mcp_tool_result |
Result from an MCP tool |
agent.custom_tool_use |
Agent invoked a custom tool — session goes idle, you respond with user.custom_tool_result |
agent.thread_context_compacted |
Conversation context was compacted |
session.status_idle |
Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a user.message or blocked awaiting a user.custom_tool_result or user.tool_confirmation. The stop_reason attached contains more information about why the Agent has stopped working. |
session.status_running |
Session has starting running, and the Agent is actively doing work. |
session.status_rescheduled |
Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. |
session.status_terminated |
Session has terminated, entering an irreversible and unusable state. |
session.error |
Error occurred during processing |
span.model_request_start |
Model inference started |
span.model_request_end |
Model inference completed |
span.outcome_evaluation_start / _ongoing / _end |
Grader progress for outcome-oriented sessions — see shared/managed-agents-outcomes.md |
session.thread_created |
Subagent thread spawned (multiagent) — see shared/managed-agents-multiagent.md |
session.thread_status_running / _idle / _rescheduled / _terminated |
Subagent thread status transitions (multiagent). _idle carries stop_reason. |
agent.thread_message_sent / _received |
Cross-thread message, carries to_session_thread_id / from_session_thread_id (multiagent) |
The stream also echoes back user-sent events (user.message, user.interrupt, user.tool_confirmation, user.custom_tool_result, user.define_outcome).
Steering Patterns
Practical patterns for driving a session via the events surface.
Stream-first ordering
Open the stream before sending events. The stream only delivers events that occur after it's opened — it does not replay current state or historical events. If you send a message first and open the stream second, early events (including fast status transitions) arrive buffered in a single batch and you lose the ability to react to them in real time.
// ✅ Correct — stream and send concurrently
const [response] = await Promise.all([
streamEvents(sessionId), // opens SSE connection
sendMessage(sessionId, text),
]);
// ❌ Wrong — events before stream opens arrive as a single buffered batch
await sendMessage(sessionId, text);
const response = await streamEvents(sessionId);
For full history, use GET /v1/sessions/{id}/events (paginated list) — the stream only gives you live events from connection onward.
Reconnecting after a dropped stream
The SSE stream has no replay. If your connection drops (httpx read timeout, network blip) and you reconnect, you only get events emitted after reconnection. Any events emitted during the gap are lost from the stream.
The consolidation pattern: on every (re)connect, overlap the stream with a history fetch and dedupe by event ID:
def connect_with_consolidation(client, session_id):
# 1. Open the SSE stream first
stream = client.beta.sessions.events.stream(session_id=session_id)
# 2. Fetch history to cover any gap
history = client.beta.sessions.events.list(
session_id=session_id,
)
# 3. Yield history first, then stream — dedupe by event.id
seen = set()
for ev in history.data:
seen.add(ev.id)
yield ev
for ev in stream:
if ev.id not in seen:
seen.add(ev.id)
yield ev
Message queuing
You don't have to wait for a response before sending the next message. User events are queued server-side and processed in order. This is useful for chat bridges where the user sends rapid follow-ups:
// All three go into one session; agent processes them in order
await sendMessage(sessionId, "Summarize the README");
await sendMessage(sessionId, "Actually also check the CONTRIBUTING guide");
await sendMessage(sessionId, "And compare the two");
// Stream once — agent responds to all three as a coherent turn
Events can be sent up to the Session at any time. There is no need to wait on a specific session status to enqueue new events via client.beta.sessions.events.send()
Interrupt
An interrupt event jumps the queue (ahead of any pending user messages) and forces the session into idle. Use this for "stop" / "nevermind" / "cancel" commands:
await client.beta.sessions.events.send(sessionId, {
events: [{ type: 'interrupt' }],
});
The agent stops mid-task. It does not see the interrupt as a message — it just halts. Send a follow-up user event to explain what to do instead. If an outcome is active, the interrupt also marks span.outcome_evaluation_end.result: "interrupted" (see shared/managed-agents-outcomes.md).
Note
: Interrupt events may have empty IDs in the current implementation. When troubleshooting, use the
processed_attimestamp along with surrounding event IDs.
Event payloads
some events carry useful metadata beyond the status change itself:
session.status_idle — includes a stop_reason field which elaborates on why the session stopped and what type of further action is required by the user.
{
"id": "sevt_456",
"processed_at": "2026-04-07T04:27:43.197Z",
"stop_reason": {
"event_ids": [
"sevt_123"
],
"type": "requires_action"
},
"type": "status_idle"
}
span.model_request_end contains a model_usage field for cost tracking and efficiency analysis:
{
"type": "span.model_request_end",
"id": "sevt_456",
"is_error": false,
"model_request_start_id": "sevt_123",
"model_usage": {
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 6656,
"input_tokens": 3571,
"output_tokens": 727
},
"processed_at": "2026-04-07T04:11:32.189Z"
}
agent.thread_context_compacted — emitted when the conversation history was summarized to fit context. Includes pre_compaction_tokens so you know how much was squeezed:
{
"id": "sevt_abc123",
"processed_at": "2026-03-24T14:05:15.787Z",
"type": "agent.thread_context_compacted"
}
Archive
When done with a session, archive it to free resources:
await client.beta.sessions.archive(sessionId);
# Managed Agents — Memory StoresArchiving a session is routine cleanup — sessions are per-run and disposable. Do not generalize this to agents or environments: those are persistent, reusable resources, and archiving them is permanent (no unarchive; new sessions cannot reference them). See
shared/managed-agents-overview.md→ Common Pitfalls.
Public beta. Memory stores ship under the
managed-agents-2026-04-01beta header; the SDK sets it automatically on allclient.beta.memory_stores.*calls. Ifclient.beta.memory_storesis missing, upgrade to the latest SDK release.
Sessions are ephemeral by default — when one ends, anything the agent learned is gone. A memory store is a workspace-scoped collection of small text documents that persists across sessions. When a store is attached to a session (via resources[]), it is mounted into the container as a filesystem directory; the agent reads and writes it with the ordinary file tools, and a system-prompt note tells it the mount is there.
Every mutation to a memory produces an immutable memory version (memver_...), giving you an audit trail and point-in-time rollback/redact.
Object model
| Object | ID prefix | Scope | Notes |
|---|---|---|---|
| Memory store | memstore_... |
Workspace | Attach to sessions via resources[] |
| Memory | mem_... |
Store | One text file, addressed by path (≤ 100KB each — prefer many small files) |
| Memory version | memver_... |
Memory | Immutable snapshot per mutation; operation ∈ created / modified / deleted |
Create a store
description is passed to the agent so it knows what the store contains — write it for the model, not for humans.
store = client.beta.memory_stores.create(
name="User Preferences",
description="Per-user preferences and project context.",
)
print(store.id) # memstore_01Hx...
Other SDKs: TypeScript client.beta.memoryStores.create({...}); Go client.Beta.MemoryStores.New(ctx, ...). See shared/managed-agents-api-reference.md → SDK Method Reference for the full per-language table.
Stores support retrieve / update / list (with include_archived, created_at_{gte,lte} filters) / delete / archive. Archive makes the store read-only — existing session attachments continue, new sessions cannot reference it; no unarchive.
Seed with content (optional)
Pre-load reference material before any session runs. memories.create creates a memory at the given path; if a memory already exists there the call returns 409 (memory_path_conflict_error, with the conflicting_memory_id). The store ID is the first positional argument.
client.beta.memory_stores.memories.create(
store.id,
path="/formatting_standards.md",
content="All reports use GAAP formatting. Dates are ISO-8601...",
)
Attach to a session
Memory stores go in the session's resources[] array alongside file and github_repository resources (see shared/managed-agents-environments.md → Resources). Memory stores attach at session create time only — sessions.resources.add() does not accept memory_store.
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
resources=[
{
"type": "memory_store",
"memory_store_id": store.id,
"access": "read_write", # or "read_only"; default is "read_write"
"instructions": "User preferences and project context. Check before starting any task.",
}
],
)
| Field | Required | Notes |
|---|---|---|
type |
✅ | "memory_store" |
memory_store_id |
✅ | memstore_... |
access |
— | "read_write" (default) or "read_only" — enforced at the filesystem level on the mount |
instructions |
— | Session-specific guidance for this store, in addition to the store's name/description. ≤ 4,096 chars. |
Max 8 memory stores per session. Attach multiple when different slices of memory have different owners or lifecycles — e.g. one read-only shared-reference store plus one read-write per-user store, or one store per end-user/team/project sharing a single agent config.
How the agent sees it (FUSE mount)
Each attached store is mounted in the session container at /mnt/memory/<store-name>/. The agent interacts with it using the standard file tools (bash, read, write, edit, glob, grep) — there are no dedicated memory tools. access: "read_only" makes the mount read-only at the filesystem level; "read_write" allows the agent to create, edit, and delete files under it. A short description of each mount (name, path, instructions, access) is automatically injected into the system prompt so the agent knows the store exists without you having to mention it.
Writes the agent makes under the mount are persisted back to the store and produce memory versions just like host-side memories.update calls.
Manage memories directly (host-side)
Use these for review workflows, correcting bad memories, or seeding stores out-of-band.
List
Returns Memory | MemoryPrefix entries — a MemoryPrefix (type: "memory_prefix", just a path) is a directory-like node when listing hierarchically. Use path_prefix to scope (include a trailing slash: "/notes/" matches /notes/a.md but not /notes_backup/old.md) and depth to bound the tree walk. order_by / order sort the result. Pass view="full" to include content in each item; the default "basic" returns metadata only.
for m in client.beta.memory_stores.memories.list(store.id, path_prefix="/"):
if m.type == "memory":
print(f"{m.path} ({m.content_size_bytes} bytes, sha={m.content_sha256[:8]})")
else: # "memory_prefix"
print(f"{m.path}/")
Read
mem = client.beta.memory_stores.memories.retrieve(memory_id, memory_store_id=store.id)
print(mem.content)
retrieve defaults to view="full" (content included); view matters mainly on list endpoints.
Create vs. update
| Operation | Addressed by | Semantics |
|---|---|---|
memories.create(store_id, path=..., content=...) |
Path | Create at path. 409 (memory_path_conflict_error, includes conflicting_memory_id) if the path is already occupied. |
memories.update(mem_id, memory_store_id=..., path=..., content=...) |
mem_... ID |
Mutate existing memory. Change content, path (rename), or both. Renaming onto an occupied path returns the same 409 memory_path_conflict_error. |
mem = client.beta.memory_stores.memories.create(
store.id,
path="/preferences/formatting.md",
content="Always use tabs, not spaces.",
)
client.beta.memory_stores.memories.update(
mem.id,
memory_store_id=store.id,
path="/archive/2026_q1_formatting.md", # rename
)
Optimistic concurrency (precondition on update)
memories.update accepts a precondition so you can read → modify → write back without clobbering a concurrent writer. The only supported type is content_sha256. On mismatch the API returns 409 (memory_precondition_failed_error) — re-read and retry against fresh state.
client.beta.memory_stores.memories.update(
mem.id,
memory_store_id=store.id,
content="CORRECTED: Always use 2-space indentation.",
precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
)
Delete
client.beta.memory_stores.memories.delete(mem.id, memory_store_id=store.id)
Pass expected_content_sha256 for a conditional delete.
Audit and rollback — memory versions
Every mutation creates an immutable memver_... snapshot. Versions accumulate for the lifetime of the parent memory; memories.retrieve always returns the current head, the version endpoints give you history.
| Operation that triggers it | operation field on the version |
|---|---|
memories.create at a new path |
"created" |
memories.update changing content, path, or both (or an agent-side write to the mount) |
"modified" |
memories.delete |
"deleted" |
Each version also records created_by — an actor object with type ∈ session_actor / api_actor / user_actor — and, after redaction, redacted_at + redacted_by.
List versions
Newest-first, paginated. Filter by memory_id, operation, session_id, api_key_id, or created_at_gte / created_at_lte. Pass view="full" to include content; default is metadata-only.
for v in client.beta.memory_stores.memory_versions.list(store.id, memory_id=mem.id):
print(f"{v.id}: {v.operation}")
Retrieve a version
version = client.beta.memory_stores.memory_versions.retrieve(
version_id, memory_store_id=store.id
)
print(version.content)
Redact a version
Scrubs content from a historical version while preserving the audit trail (actor + timestamps). Clears content, content_sha256, content_size_bytes, and path; everything else stays. Use for leaked secrets, PII, or user-deletion requests.
client.beta.memory_stores.memory_versions.redact(version_id, memory_store_id=store.id)
Endpoint reference
See shared/managed-agents-api-reference.md → Memory Stores / Memories / Memory Versions for the full HTTP method/path tables. Raw HTTP base path:
POST /v1/memory_stores
POST /v1/memory_stores/{memory_store_id}/archive
GET /v1/memory_stores/{memory_store_id}/memories
PATCH /v1/memory_stores/{memory_store_id}/memories/{memory_id}
GET /v1/memory_stores/{memory_store_id}/memory_versions
POST /v1/memory_stores/{memory_store_id}/memory_versions/{version_id}/redact
For cURL examples and the CLI (ant beta:memory-stores ...), WebFetch the Memory URL in shared/live-sources.md → Managed Agents.
A coordinator agent can delegate to other agents within one session. All agents share the container and filesystem; each runs in its own thread — a context-isolated event stream with its own conversation history, model, system prompt, tools, MCP servers, and skills (from that agent's own config). Threads are persistent: the coordinator can send a follow-up to a subagent it called earlier and that subagent retains its prior turns.
The SDK sets the managed-agents-2026-04-01 beta header automatically on all client.beta.{agents,sessions}.* calls; no additional header is required for multiagent.
Declare the roster on the coordinator
multiagent is a top-level field on agents.create() / agents.update() — not a tools[] entry. agents lists 1–20 roster entries. Nothing changes on sessions.create() — the roster is resolved from the coordinator's config.
orchestrator = client.beta.agents.create(
name="Engineering Lead",
model="claude-opus-4-8",
system="You coordinate engineering work. Delegate code review to the reviewer and test writing to the test agent.",
tools=[{"type": "agent_toolset_20260401"}],
multiagent={
"type": "coordinator",
"agents": [
reviewer.id, # bare string — latest version
{"type": "agent", "id": test_writer.id, "version": 4}, # pinned version
{"type": "self"}, # the coordinator itself
],
},
)
session = client.beta.sessions.create(agent=orchestrator.id, environment_id=env.id)
| Roster entry | Shape | Notes |
|---|---|---|
| String shorthand | "agent_abc123" |
References the latest version of a stored agent. |
| Agent reference | {type: "agent", id, version?} |
Omit version to pin the latest at coordinator save time. |
| Self | {type: "self"} |
The coordinator can spawn copies of itself. |
Up to 20 unique agents in the roster; the coordinator may spawn multiple copies of each. One level of delegation only — depth > 1 is ignored.
Threads
The session-level event stream is the primary thread — it shows the coordinator's trace plus a condensed view of subagent activity (thread status transitions and cross-thread messages, not every subagent tool call). Drill into a specific subagent via the per-thread endpoints:
| Operation | HTTP | SDK (client.beta.sessions.threads.*) |
|---|---|---|
| List threads | GET /v1/sessions/{sid}/threads |
.list(session_id) |
| Retrieve one | GET /v1/sessions/{sid}/threads/{tid} |
.retrieve(thread_id, session_id=...) |
| Archive | POST /v1/sessions/{sid}/threads/{tid}/archive |
.archive(thread_id, session_id=...) |
| List thread events | GET /v1/sessions/{sid}/threads/{tid}/events |
.events.list(thread_id, session_id=...) |
| Stream thread events | GET /v1/sessions/{sid}/threads/{tid}/stream |
.events.stream(thread_id, session_id=...) |
Each SessionThread carries id, status (running | idle | rescheduling | terminated), agent (a resolved snapshot of the agent config — id, name, model, system, tools, skills, mcp_servers, version), parent_thread_id (null for the primary thread, which is included in the list), archived_at, and optional stats/usage. Session status aggregates thread statuses — if any thread is running, session.status is running. Max 25 concurrent threads. When draining a per-thread stream, break on session.thread_status_idle (and check its stop_reason as you would for the session-level idle).
Multiagent events (on the session stream)
| Event | Payload highlights | Meaning |
|---|---|---|
session.thread_created |
session_thread_id, agent_name |
A new thread was created. |
session.thread_status_running |
session_thread_id, agent_name |
Thread started activity. |
session.thread_status_idle |
session_thread_id, agent_name, stop_reason |
Thread is awaiting input. Inspect stop_reason (same shape as session.status_idle.stop_reason). |
session.thread_status_rescheduled |
session_thread_id, agent_name |
Thread is rescheduling after a retryable error. |
session.thread_status_terminated |
session_thread_id, agent_name |
Thread was archived or hit a terminal error. |
agent.thread_message_sent |
to_session_thread_id, to_agent_name, content |
Coordinator sent a follow-up to another thread. |
agent.thread_message_received |
from_session_thread_id, from_agent_name, content |
An agent delivered its result to the coordinator. |
Tool permissions and custom tools from subagent threads
When a subagent needs your client (an always_ask confirmation, or a custom tool result), the request is cross-posted to the primary thread with session_thread_id identifying the originating thread — so you only need to watch the session stream. Reply with user.tool_confirmation (carrying tool_use_id) or user.custom_tool_result (carrying custom_tool_use_id), and echo the session_thread_id from the originating event (the SDK param type and docstring expect it). The server also routes by the tool-use ID, so the echo is belt-and-suspenders rather than load-bearing — but include it.
for event_id in stop.event_ids:
pending = events_by_id[event_id]
confirmation = {
"type": "user.tool_confirmation",
"tool_use_id": event_id,
"result": "allow",
}
if pending.session_thread_id is not None:
confirmation["session_thread_id"] = pending.session_thread_id
client.beta.sessions.events.send(session.id, events=[confirmation])
The same pattern applies to user.custom_tool_result.
Pitfalls
- Don't put the roster on
sessions.create()or intools[].multiagentis a top-level agent field; update the coordinator, then start a session that references it. - Don't assume shared context. Threads share the filesystem but not conversation history or tools. If the coordinator needs a subagent to act on something, it must say so in the delegated message (or write it to disk).
- Depth > 1 is ignored. A subagent's own
multiagentroster (if any) doesn't cascade — only the session's coordinator delegates.
For per-language bindings beyond Python, WebFetch https://platform.claude.com/docs/en/managed-agents/multi-agent.md (see shared/live-sources.md).
Invoked via
/claude-api managed-agents-onboard? You're in the right place. Run the interview below — don't summarize it back to the user, ask the questions.
Use this when a user wants to set up a Managed Agent from scratch: branch on know-vs-explore → configure the template → set up the session → pre-flight viability check → emit working code. The pre-flight check (§3) is not optional — a setup missing a tool, credential, or data access it needs will fail mid-run, and the gap is usually visible at setup time.
Read
shared/managed-agents-core.mdalongside this — it has full detail for each knob. This doc is the interview script, not the reference.
Claude Managed Agents is a hosted agent: Anthropic runs the agent loop on its orchestration layer and provisions a sandboxed container per session where the agent's tools execute (or, with a self_hosted environment, your own worker runs the tools — see shared/managed-agents-self-hosted-sandboxes.md). You supply the agent config and the environment config; the harness — event stream, sandbox orchestration, prompt caching, context compaction, and extended thinking — is handled for you.
What you supply:
- An agent config — tools, skills, model, system prompt. Reusable and versioned.
- An environment config — the sandbox your agent's tools execute in (
cloud: networking, packages; orself_hosted: your own infra). Reusable across agents.
Each run of the agent is a session.
1. Know or explore?
Ask the user:
Do you already know the agent you want to build, or would you like to explore some common patterns first?
Explore path — show the patterns
Four shapes, same runtime code path (sessions.create() → sessions.events.send() → stream). Only the trigger and sink differ.
| Pattern | Trigger | Example |
|---|---|---|
| Event-triggered | Webhook | GitHub PR push → CMA (GitHub tool) → Slack |
| Scheduled | Cron | Daily brief: browser + GitHub + Jira → CMA → Slack |
| Fire-and-forget PR | Human | Slack slash-command → CMA (GitHub tool) → PR passing CI |
| Research + dashboard | Human | Topic → CMA (web search + frontend-design skill) → HTML dashboard |
Ask which shape fits, then continue with the Know path using it as the reference.
Know path — configure template
Three rounds. Batch the questions in each round; don't ask them one at a time.
Round A — Tools. Start here; it's the most concrete part. Three types; ask which the user wants (any combination):
| Type | What it is | How to guide |
|---|---|---|
Prebuilt Claude Agent tools (agent_toolset_20260401) |
Ready-to-use: bash, read, write, edit, glob, grep, web_fetch, web_search. Enable all at once, or individually via enabled: true/false. |
Recommend enabling the full toolset. List the 8 tools so the user knows what they're getting. Full detail: shared/managed-agents-tools.md → Agent Toolset. |
| MCP tools | Third-party integrations (GitHub, Linear, Asana, etc.) via mcp_toolset. Credentials live in a vault, not inline. |
Ask which services. For each, walk through MCP server URL + vault credentials. Full detail: shared/managed-agents-tools.md → MCP Servers + Vaults. |
| Custom tools | The user's own app handles these tool calls — agent fires agent.custom_tool_use, the app sends a result message back. |
Ask for each tool: name, description, input schema. The app code that handles the event is their code — don't generate it. Full detail: shared/managed-agents-tools.md → Custom Tools. |
Round B — Skills, files, and repos. What the agent has on hand when it starts.
Skills — two types; both work the same way — Claude auto-uses them when relevant. Max 20 per agent.
- Pre-built Agent Skills:
xlsx,docx,pptx,pdf. Reference by name. - Custom Skills: skills uploaded to the user's org via the Skills API. Reference by
skill_id+ optionalversion. If the skill doesn't exist yet, walk the user throughPOST /v1/skills+POST /v1/skills/{id}/versions(beta headerskills-2025-10-02). Full detail:shared/managed-agents-tools.md→ Skills + Skills API.
GitHub repositories — any repos the agent needs on-disk? For each:
- Repo URL (
https://github.com/org/repo) authorization_token(PAT or GitHub App token scoped to the repo)- Optional
mount_path(defaults to/workspace/<repo-name>) andcheckout(branch or SHA)
Emit as resources: [{type: "github_repository", url, authorization_token, ...}]. Full detail: shared/managed-agents-environments.md → GitHub Repositories.
‼️ PR creation needs the GitHub MCP server too.
github_repositorygives filesystem access only — to open PRs, also attach the GitHub MCP server in Round A and credential it via a vault. The workflow is: edit files in the mounted repo → push branch viabash→ create PR via the MCPcreate_pull_requesttool.
Files — any local files to seed the session with? For each:
- Upload via the Files API → persist
file_id - Choose a
mount_path— absolute, e.g./workspace/data.csv(parents auto-created; files mount read-only)
Emit as resources: [{type: "file", file_id, mount_path}]. Max 999 file resources. Agent working directory defaults to /workspace. Full detail: shared/managed-agents-environments.md → Files API.
Round C — Identity, success criteria, environment:
- Name?
- Job (one or two sentences — becomes the system prompt)?
- What does "done" look like? Push for concrete, checkable success criteria — not "a good report" but "a CSV with a numeric
pricecolumn per SKU." Explicit criteria give the agent a clear target and let you verify the result; vague ones leave it guessing what "done" means. If they're gradeable, plan to wire an Outcome in §2 so the harness grades-and-revises against them. Seeshared/managed-agents-outcomes.md. - Networking: unrestricted internet from the container, or lock egress to specific hosts? (If locked, MCP server domains must be in
allowed_hostsor tools silently fail.) - Model? (default
claude-opus-4-8)
2. Set up the session
Per-run. Points at the agent + environment, attaches credentials, kicks off.
Vault credentials (if the agent declared MCP servers):
- Existing vault, or create one? (
client.beta.vaults.create()+vaults.credentials.create())
Credentials are write-only, matched to MCP servers by URL, auto-refreshed. See shared/managed-agents-tools.md → Vaults.
Kickoff — pick one:
- Conversational: a first
user.messageto the agent. - Outcome-graded (recommended when §Round C produced checkable criteria): send a
user.define_outcomewith a rubric instead of auser.message— the harness iterates and grades against the rubric until satisfied. Don't send both. Seeshared/managed-agents-outcomes.md.
Session creation blocks until all resources mount. Open the event stream before sending the kickoff. Stream is SSE; break on session.status_terminated, or on session.status_idle with a terminal stop_reason — i.e. anything except requires_action, which fires transiently while the session waits on a tool confirmation or custom-tool result (see shared/managed-agents-client-patterns.md Pattern 5). Usage lands on span.model_request_end. Agent-written artifacts end up in /mnt/session/outputs/ — download via files.list({scope_id: session.id, betas: ["managed-agents-2026-04-01"]}).
Console escape hatch. In the runtime block you emit, print the session's Console URL right after sessions.create() so the user can watch it in the UI while iterating: print(f"Watch in Console: https://platform.claude.com/workspaces/default/sessions/{session.id}") (swap default for the user's workspace slug if they named one).
3. Pre-flight viability check — reconcile the job against the resources
Do this before emitting any code. A common, avoidable failure is an under-resourced run: the ask is clear, but the agent is missing a tool, a credential, data access, or the context to act. The agent discovers the gap a few turns in, flails, and gives up — burning the budget to produce nothing. The gap is usually visible at setup time. Catch it here, not after the session fails.
Walk the stated job clause by clause. For each action the agent must take, confirm a resource covers it — and name the gap out loud if one doesn't:
| Gap class | Check | If missing |
|---|---|---|
| Tool / integration (most catchable upfront — config is statically inspectable) | Every verb in the job maps to an enabled tool or MCP server. "Triage tickets" → a ticketing MCP server; "open a PR" → GitHub MCP server (a github_repository mount alone can't open PRs); "search the web" → web_search enabled in the toolset. |
Add the tool/MCP server in §Round A, or cut the ask from the job. |
| Credential / access | Every MCP server has a vault credential attached (§2). Every external host the job touches is reachable — networking unrestricted, or the host is in allowed_hosts. |
Create/attach the vault; widen allowed_hosts. These don't fail until runtime — the smoke-test in §4 is how you surface them cheaply. |
| Data | Every file, dataset, or repo the job references is mounted as a resource (file, github_repository, or memory store). |
Upload + mount it in §Round B, or tell the agent where to fetch it from. |
| Prompt quality / criteria | The job is specific enough to act on, and "done" is checkable (§Round C). | Tighten the job; wire an Outcome. |
State any unmet gaps to the user and resolve them before generating code. Don't emit a config you already know is under-resourced — an agent can't complete a task it lacks the tools, credentials, or data for.
4. Emit the code
Go straight from the last interview answer to the code — no preamble about the setup-vs-runtime split, no "the critical thing to internalize…", no lecture about agents.create() being one-time. The two-block structure below already shows that; don't narrate it. Generate two clearly-separated blocks:
Block 1 — Setup (run once, store the IDs). Prefer emitting this as YAML files + ant CLI commands — agents and environments are version-controlled definitions, and the CLI flow is what users should check into their repo and run from CI. Fall back to SDK code only if the user explicitly wants setup in-language or the ant CLI is unavailable.
Emit:
<name>.agent.yamlwith everything from §Round A–C (flat:name,model,system,tools,mcp_servers,skills)<name>.environment.yamlwith §Round C networking- The apply commands:
AGENT_ID=$(ant beta:agents create < <name>.agent.yaml --transform id -r) ENV_ID=$(ant beta:environments create < <name>.environment.yaml --transform id -r) # CI sync: ant beta:agents update --agent-id "$AGENT_ID" --version N < <name>.agent.yaml
See shared/anthropic-cli.md for the full CLI reference. If emitting SDK code instead, label it # ONE-TIME SETUP — run once, save the IDs to config/.env and call environments.create() → agents.create().
Block 2 — Runtime (run on every invocation). This is SDK code in the detected language (Python/TS/cURL — see SKILL.md → Language Detection). The runtime path needs to react programmatically to events (tool confirmations, custom tool results, reconnect), which is SDK territory — don't emit shell loops here.
- Load
env_id+agent_idfrom config/env sessions.create(agent=AGENT_ID, environment_id=ENV_ID, resources=[...], vault_ids=[...])— this blocks until resources mount, so a bad file/repo mount surfaces here, before any tokens are spent.- Smoke-test first when the job depends on MCP servers, credentials, or reachable hosts. Credential and MCP-connectivity failures don't surface at
sessions.create()— only when the agent first tries to use them. Send one cheap probe turn ("Confirm you can reach and list 1–2 items; don't start the task yet"), check it succeeded, then send the real kickoff. A few hundred tokens here beats a runaway session that flails on a missing credential and gives up. Skip for agents with no external dependencies. - Open stream,
events.send()the kickoff (auser.message, or auser.define_outcomeif §2 chose the outcome-graded path), loop untilsession.status_terminatedorsession.status_idle && stop_reason.type !== 'requires_action'(seeshared/managed-agents-client-patterns.mdPattern 5 for the full gate — do not break on baresession.status_idle)
⚠️ Never emit
agents.create()andsessions.create()in the same unguarded block. That teaches the user to create a new agent on every run — the #1 anti-pattern. If they need a single script, wrap agent creation inif not os.getenv("AGENT_ID"):.
Pull exact syntax from python/managed-agents/README.md, typescript/managed-agents/README.md, or curl/managed-agents.md. Don't invent field names.
An outcome elevates a session from conversation to work: you state what "done" looks like, and the harness runs an iterate → grade → revise loop until the artifact meets the rubric, hits max_iterations, or is interrupted. A separate grader (independent context window) scores each iteration against your rubric and feeds per-criterion gaps back to the agent.
The SDK sets the managed-agents-2026-04-01 beta header automatically on all client.beta.sessions.* calls; no additional header is required for outcomes.
The user.define_outcome event
Outcomes are not a field on sessions.create(). You create a normal session, then send a user.define_outcome event. The agent starts working on receipt — do not also send a user.message to kick it off.
session = client.beta.sessions.create(
agent=AGENT_ID,
environment_id=ENVIRONMENT_ID,
title="Financial analysis on Costco",
)
client.beta.sessions.events.send(
session_id=session.id,
events=[
{
"type": "user.define_outcome",
"description": "Build a DCF model for Costco in .xlsx",
"rubric": {"type": "text", "content": RUBRIC_MD},
# or: "rubric": {"type": "file", "file_id": rubric.id}
"max_iterations": 5, # optional; default 3, max 20
}
],
)
| Field | Type | Notes |
|---|---|---|
type |
"user.define_outcome" |
|
description |
string | The task. This is what the agent works toward — no separate user.message needed. |
rubric |
{type: "text", content} | {type: "file", file_id} |
Required. Markdown with explicit, independently gradeable criteria. Upload once via client.beta.files.upload(...) (beta files-api-2025-04-14) to reuse across sessions. |
max_iterations |
int | Optional. Default 3, max 20. |
The event is echoed back on the stream with a server-assigned outcome_id and processed_at.
Writing rubrics. Use explicit, gradeable criteria ("CSV has a numeric
pricecolumn"), not vibes ("data looks good") — the grader scores each criterion independently, so vague criteria produce noisy loops. If you don't have a rubric, have Claude analyze a known-good artifact and turn that analysis into one.
Outcome-specific events
These appear on the standard event stream (sessions.events.stream / .list) alongside the usual agent.* / session.* events.
| Event | Payload highlights | Meaning |
|---|---|---|
span.outcome_evaluation_start |
outcome_id, iteration (0-indexed) |
Grader began scoring iteration N. |
span.outcome_evaluation_ongoing |
outcome_id |
Heartbeat while the grader runs. Grader reasoning is opaque — you see that it's working, not what it's thinking. |
span.outcome_evaluation_end |
outcome_evaluation_start_id, outcome_id, iteration, result, explanation, usage |
Grader finished one iteration. result drives what happens next (table below). |
span.outcome_evaluation_end.result
result |
Next |
|---|---|
satisfied |
Session → idle. Terminal for this outcome. |
needs_revision |
Agent starts another iteration. |
max_iterations_reached |
No further grader cycles. Agent may run one final revision, then session → idle. |
failed |
Session → idle. Rubric fundamentally doesn't match the task (e.g. description and rubric contradict). |
interrupted |
Only emitted if _start had already fired before a user.interrupt arrived. |
{
"type": "span.outcome_evaluation_end",
"id": "sevt_01jkl...",
"outcome_evaluation_start_id": "sevt_01def...",
"outcome_id": "outc_01a...",
"result": "satisfied",
"explanation": "All 12 criteria met: revenue projections use 5 years of historical data, ...",
"iteration": 0,
"usage": { "input_tokens": 2400, "output_tokens": 350, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 1800 },
"processed_at": "2026-03-25T14:03:00Z"
}
Checking status & retrieving deliverables
Status — either watch the stream for span.outcome_evaluation_end, or poll the session and read outcome_evaluations:
session = client.beta.sessions.retrieve(session.id)
for ev in session.outcome_evaluations:
print(f"{ev.outcome_id}: {ev.result}") # outc_01a...: satisfied
Deliverables — the agent writes to /mnt/session/outputs/. Once idle, fetch via the Files API with scope_id=session.id. This is the same session-outputs mechanism documented in shared/managed-agents-environments.md → Session outputs (including the dual-beta-header requirement on files.list).
Interaction rules & pitfalls
- One outcome at a time. Chain by sending the next
user.define_outcomeonly after the previous one's terminalspan.outcome_evaluation_end(satisfied/max_iterations_reached/failed/interrupted). The session retains history across chained outcomes. - Steering is allowed but optional. You may send
user.messageevents mid-outcome to nudge direction, but the agent already knows to keep working until terminal — don't send "keep going" prompts. user.interruptpauses the current outcome — it marksresult: "interrupted"and leaves the sessionidle, ready for a new outcome or conversational turn.- After terminal, the session is reusable — continue conversationally or define a new outcome.
- Outcome ≠ session-create field. Don't put
outcome,rubric, ordescriptiononsessions.create()— outcomes are always sent as auser.define_outcomeevent. - Idle-break gate is unchanged. In your drain loop, keep using
event.type === 'session.status_idle' && event.stop_reason?.type !== 'requires_action'— do not gate onspan.outcome_evaluation_endalone (onneeds_revisionthe session keeps running). Seeshared/managed-agents-client-patterns.mdPattern 5.
For the raw HTTP shapes and per-language SDK bindings beyond Python, WebFetch https://platform.claude.com/docs/en/managed-agents/define-outcomes.md (see shared/live-sources.md).
Managed Agents provisions a container per session as the agent's workspace. The agent loop runs on Anthropic's orchestration layer; the container is where the agent's tools execute — bash commands, file operations, code. You create a persisted Agent config (model, system prompt, tools, MCP servers, skills), then start Sessions that reference it. The session streams events back to you; you send user messages and tool results in.
⚠️ THE MANDATORY FLOW: Agent (once) → Session (every run)
Why agents are separate objects: versioning. An agent is a persisted, versioned config — every update creates a new immutable version, and sessions pin to a version at creation time. This lets you iterate on the agent (tweak the prompt, add a tool) without breaking sessions already running, roll back if a change regresses, and A/B test versions side-by-side. None of that works if you agents.create() fresh on every run.
Every session references a pre-created /v1/agents object. Create the agent once, store the ID, and reuse it across runs.
| Step | Call | Frequency |
|---|---|---|
| 1 | POST /v1/agents — model, system, tools, mcp_servers, skills live here |
ONCE. Store agent.id and agent.version. |
| 2 | POST /v1/sessions — agent: "agent_abc123" or {type: "agent", id, version} |
Every run. String shorthand uses latest version. |
If you're about to write sessions.create() with model, system, or tools on the session body — stop. Those fields live on agents.create(). The session takes a pointer only.
When generating code, separate setup from runtime. agents.create() belongs in a setup script (or a guarded if agent_id is None: block), not at the top of the hot path. If the user's code calls agents.create() on every invocation, they're accumulating orphaned agents and paying the create latency for nothing. The correct shape is: create once → persist the ID (config file, env var, secrets manager) → every run loads the ID and calls sessions.create().
To change the agent's behavior, use POST /v1/agents/{id} — don't create a new one. Each update bumps the version; running sessions keep their pinned version, new sessions get the latest (or pin explicitly via {type: "agent", id, version}). See shared/managed-agents-core.md → Agents → Versioning. To change tools/mcp_servers/vault_ids on one running session without touching the agent object, use sessions.update() — see shared/managed-agents-core.md → Updating the agent configuration mid-session.
Beta Headers
Managed Agents is in beta. The SDK sets required beta headers automatically:
| Beta Header | What it enables |
|---|---|
managed-agents-2026-04-01 |
Agents, Environments, Sessions, Events, Session Resources, Session Threads, Outcomes, Multiagent, Vaults, Credentials, Memory Stores |
skills-2025-10-02 |
Skills API (for managing custom skill definitions) |
files-api-2025-04-14 |
Files API for file uploads |
Which beta header goes where: The SDK sets managed-agents-2026-04-01 automatically on client.beta.{agents,environments,sessions,vaults,memory_stores}.* calls, and files-api-2025-04-14 / skills-2025-10-02 automatically on client.beta.files.* / client.beta.skills.* calls. You do NOT need to add the Skills or Files beta header when calling Managed Agents endpoints. Exception — session-scoped file listing: client.beta.files.list({scope_id: session.id}) is a Files endpoint that takes a Managed Agents parameter, so it needs both headers. Pass betas: ["managed-agents-2026-04-01"] explicitly on that call (the SDK adds the Files header; you add the Managed Agents one). See shared/managed-agents-environments.md → Session outputs.
Reading Guide
| User wants to... | Read these files |
|---|---|
| Get started from scratch / "help me set up an agent" | shared/managed-agents-onboarding.md — guided interview (WHERE→WHO→WHAT→WATCH), then emit code |
| Understand how the API works | shared/managed-agents-core.md |
| See the full endpoint reference | shared/managed-agents-api-reference.md |
| Create an agent (required first step) | shared/managed-agents-core.md (Agents section) + language file |
| Update/version an agent | shared/managed-agents-core.md (Agents → Versioning) — update, don't re-create |
| Create a session | shared/managed-agents-core.md + {lang}/managed-agents/README.md |
| Configure tools and permissions | shared/managed-agents-tools.md |
| Set up MCP servers | shared/managed-agents-tools.md (MCP Servers section) |
| Stream events / handle tool_use | shared/managed-agents-events.md + language file |
| Get notified of session state changes via webhook (no polling) | shared/managed-agents-webhooks.md — Console-registered endpoint, HMAC verify, thin payload + fetch |
| Define an outcome / rubric-graded iterate loop | shared/managed-agents-outcomes.md — user.define_outcome event, grader, span.outcome_evaluation_* events |
| Coordinate multiple agents / subagents / threads | shared/managed-agents-multiagent.md — multiagent: {type: "coordinator", agents: [...]} on the agent, session threads, cross-posted tool confirmations |
| Set up environments | shared/managed-agents-environments.md + language file |
| Run tool execution in your own infra / VPC (self-hosted sandbox) | shared/managed-agents-self-hosted-sandboxes.md — config:{type:"self_hosted"}, ANTHROPIC_ENVIRONMENT_KEY, EnvironmentWorker.run() / ant beta:worker poll |
| Upload files / attach repos | shared/managed-agents-environments.md (Resources) |
| Give agents persistent memory across sessions | shared/managed-agents-memory.md — memory stores, memory_store session resource, preconditions, versions/redact |
| Define agents/environments as version-controlled YAML; drive the API from the shell | shared/anthropic-cli.md — ant beta:agents create < agent.yaml, --transform, @file inlining |
| Store MCP credentials | shared/managed-agents-tools.md (Vaults section) |
| Call a non-MCP API / CLI that needs a secret | shared/managed-agents-client-patterns.md Pattern 9 — no container env vars; vaults are MCP-only; keep the secret host-side via a custom tool |
Common Pitfalls
- Agent FIRST, then session — NO EXCEPTIONS — the session's
agentfield accepts only a string ID or{type: "agent", id, version}.model,system,tools,mcp_servers,skillsare top-level fields onPOST /v1/agents, never onsessions.create(). If the user hasn't created an agent, that is step zero of every example. - Agent ONCE, not every run —
agents.create()is a setup step. Store the returnedagent_idand reuse it; don't callagents.create()at the top of your hot path. If the agent's config needs to change,POST /v1/agents/{id}— each update creates a new version, and sessions can pin to a specific version for reproducibility. - MCP auth goes through vaults — the agent's
mcp_serversarray declares{type, name, url}only (no auth). Credentials live in vaults (client.beta.vaults.credentials.create) and attach to sessions viavault_ids. Anthropic auto-refreshes OAuth tokens using the stored refresh token. - Reconcile resources before the first run — a session with a clear ask but a missing tool, credential, data mount, or context will discover the gap mid-run, then flail and give up. Before creating the session, check that every action in the task maps to a configured tool/MCP server, every MCP server has a vault credential, and every referenced file/host is mounted/reachable. When helping a user set one up, run the reconciliation in
shared/managed-agents-onboarding.md→ §3 Pre-flight viability check. - Stream to get events —
GET /v1/sessions/{id}/events/streamis the primary way to receive agent output in real-time. - SSE stream has no replay — reconnect with consolidation — if the stream drops while a
agent.tool_use,agent.mcp_tool_use, oragent.custom_tool_useis pending resolution (user.tool_confirmationfor the first two,user.custom_tool_resultfor the last one), the session deadlocks (client disconnects → session idles → reconnect happens → no client resolution happens). On every (re)connect: open stream withGET /v1/sessions/{id}/events/stream, fetchGET /v1/sessions/{id}/events, dedupe by event ID, then proceed. Seeshared/managed-agents-events.md→ Reconnecting after a dropped stream. - Don't trust HTTP-library timeouts as wall-clock caps —
requeststimeout=(c, r)andhttpx.Timeout(n)are per-chunk read timeouts; they reset every byte, so a trickling connection can block indefinitely. For a hard deadline on raw-HTTP polling, tracktime.monotonic()at the loop level and bail explicitly. Prefer the SDK'ssessions.events.stream()/session.events.list()over hand-rolled HTTP. Seeshared/managed-agents-events.md→ Receiving Events. - Messages queue — you can send events while the session is
runningoridle; they're processed in order. No need to wait for a response before sending the next message. - Environment
config.typeis"cloud"or"self_hosted"—cloudruns the container on Anthropic's infrastructure;self_hostedmoves tool execution to your own (seeshared/managed-agents-self-hosted-sandboxes.md). - Archive is permanent on every resource — archiving an agent, environment, session, vault, credential, or memory store makes it read-only with no unarchive. For agents, environments, and memory stores specifically, archived resources cannot be referenced by new sessions (existing sessions continue). Do not call
.archive()on a production agent, environment, or memory store as cleanup — always confirm with the user before archiving.
With config.type: "self_hosted", the agent loop stays on Anthropic's orchestration layer but tool execution moves to infrastructure you control — bash, file ops, and code run inside your container, so filesystem contents and network egress never leave your environment. Contrast with config.type: "cloud", where Anthropic runs the container. Connectivity is outbound-only: your worker long-polls Anthropic's work queue; Anthropic never dials into your network.
Flow
1. Create environment: config: {type: "self_hosted"} → env_...
2. Generate environment key (Console, on the environment page) → sk-ant-oat01-... as ANTHROPIC_ENVIRONMENT_KEY
3. Run a worker: EnvironmentWorker.run() or ant beta:worker poll
4. Sessions reference environment_id=env_... exactly as for cloud
Create the environment
client = anthropic.Anthropic()
environment = client.beta.environments.create(
name="self-hosted", config={"type": "self_hosted"}
)
{"type": "self_hosted"} is the entire config — there are no pool, capacity, or networking sub-fields; you control those on your side.
Run a worker — SDK (primary path)
EnvironmentWorker wraps the poll → dispatch → tool-execute loop. .run() is the always-on loop; .run_one() / .runOne() handles one work item (for webhook-driven wake).
Python — always-on:
import asyncio
import os
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker
async def main() -> None:
environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
async with AsyncAnthropic(auth_token=environment_key) as client:
await EnvironmentWorker(
client,
environment_id=environment_id,
environment_key=environment_key,
workdir="/workspace",
).run()
asyncio.run(main())
TypeScript — always-on:
import Anthropic from "@anthropic-ai/sdk";
import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";
const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
const client = new Anthropic({ authToken: environmentKey });
const ctrl = new AbortController();
process.once("SIGTERM", () => ctrl.abort());
await new EnvironmentWorker({
client,
environmentId,
environmentKey,
workdir: "/workspace",
signal: ctrl.signal
}).run();
Customizing tools. EnvironmentWorker runs the built-in toolset by default. To add or replace tools, use AgentToolContext(workdir=, client=, session_id=) with beta_agent_toolset(env) / betaAgentToolset(env) and pass the resulting tools to the lower-level tool_runner(). Skills attached to the agent are downloaded into {workdir}/skills/<name>/ before tool calls begin (AgentToolContext handles this when given client and session_id). Downloaded skill files are marked executable automatically by the CLI and SDK; if you implement skills download yourself, you set permissions.
Runtime deps: the SDK helpers require
/bin/bashat that exact path. The TypeScript SDK additionally requiresunzip,tar, and Node.js 22+. These are resolved at fixed paths and do not respectPATHoverrides.
Run a worker — ant CLI (fixed tools)
The ant CLI ships a worker with the fixed built-in toolset (bash, read, write, edit, glob, grep). Install per shared/anthropic-cli.md, then:
export ANTHROPIC_ENVIRONMENT_KEY=sk-ant-oat01-...
ant beta:worker poll --environment-id env_... --workdir /workspace
--workdiris the directory tools operate in (default.); tool calls are sandboxed to it.--environment-keyoverrides the env var.--on-work <script>runs your script per work item (e.g. to spin a fresh container per session — see Container orchestration below).--unrestricted-paths,--max-idle(default60s),--log-format— seeant beta:worker poll --help.- Flags fall back to env vars (
ANTHROPIC_ENVIRONMENT_ID,ANTHROPIC_ENVIRONMENT_KEY). - Exits cleanly on SIGTERM/SIGINT after draining in-flight work.
- Fixed toolset — for custom tools, use the SDK worker above.
Inside an --on-work container, run ant beta:worker run --workdir <dir> as the entrypoint.
Webhook-driven wake (instead of always-on)
Register a webhook for session.status_run_started (see shared/managed-agents-webhooks.md), verify the delivery, then drain one work item with .run_one():
import os
import anthropic
from anthropic.lib.environments import EnvironmentWorker
environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
client = anthropic.AsyncAnthropic(
auth_token=environment_key,
) # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env for webhooks.unwrap()
async def handle(raw: bytes, headers: dict[str, str]) -> dict:
event = client.beta.webhooks.unwrap(raw.decode(), headers=headers)
if event.data.type != "session.status_run_started":
return {"status": "ignored"}
await EnvironmentWorker(
client,
environment_id=environment_id,
environment_key=environment_key,
workdir="/workspace",
).run_one()
return {"status": "ok"}
TypeScript: same shape with client.beta.webhooks.unwrap(body, {headers}) and new EnvironmentWorker({...}).runOne().
Container orchestration (mid-level)
EnvironmentWorker.run() polls and executes tools in the same process. To run each session in its own container, use the mid-level poller in a thin orchestrator — Python client.beta.environments.work.poller(environment_id=, environment_key=, drain=, block_ms=, reclaim_older_than_ms=, auto_stop=); TypeScript new WorkPoller({client, environmentId, environmentKey, autoStop}) from @anthropic-ai/sdk/helpers/beta/environments — and, for each yielded work item, start a fresh container with these env vars injected, whose entrypoint runs ant beta:worker run or an EnvironmentWorker(...).run_one(). block_ms is 1–999 (or None for non-blocking); reclaim_older_than_ms re-claims items leased to a dead worker; drain stops once the queue is empty; auto_stop posts a stop signal after the iterator exits (set False when the launched container owns the stop call). Go's poller has no auto_stop opt-out — it calls work.Stop when the handler returns, so block in the handler until the session completes rather than detaching.
| Env var | Value |
|---|---|
ANTHROPIC_SESSION_ID |
work.data.id |
ANTHROPIC_WORK_ID |
work.id |
ANTHROPIC_ENVIRONMENT_ID |
work.environment_id |
ANTHROPIC_ENVIRONMENT_KEY |
pass through |
ANTHROPIC_BASE_URL |
pass through |
Skip items where work.data.type != "session".
Monitoring & control
These are control-plane calls — authenticate with x-api-key (not the environment key); managed-agents-2026-04-01 beta header. Call them from outside the worker host — setting ANTHROPIC_API_KEY on the worker host exposes an organization-scoped credential to agent tool calls.
SDK (client.beta.environments.work.*) |
REST | CLI | Returns |
|---|---|---|---|
stats(environment_id) |
GET /v1/environments/{id}/work/stats |
ant beta:environments:work stats |
{type:"work_queue_stats", depth, pending, oldest_queued_at, workers_polling} |
stop(work_id, environment_id=) |
POST /v1/environments/{id}/work/{work_id}/stop |
ant beta:environments:work stop |
work.state |
What changes vs cloud
| Concern | cloud |
self_hosted |
|---|---|---|
| Container lifecycle, hardening, networking | Anthropic | You — run non-root, read-only rootfs, drop caps; egress is whatever your VPC/firewall allows |
file / github_repository resource mounting |
Anthropic mounts into the container | You — pass pointers via sessions.create(metadata={...}) and have your orchestrator fetch/clone before dispatch |
memory_store resources |
Supported | Not yet supported |
| Built-in tools | Via agent_toolset_20260401 |
Supplied by your worker (EnvironmentWorker default / beta_agent_toolset(env) / ant CLI fixed set) |
| Skills download | Automatic | EnvironmentWorker / AgentToolContext fetch into {workdir}/skills/ (needs client + session_id) |
| Claude Platform on AWS | Supported | Not available |
| SDK worker helpers | All SDKs | Python, TypeScript, Go only (EnvironmentWorker / poller not in Java, Ruby, PHP, or C#) — use one of those three or the ant CLI |
Credentials
| Credential | Format | Scope |
|---|---|---|
ANTHROPIC_ENVIRONMENT_KEY |
sk-ant-oat01-... |
One environment's work queue. Generate in Console ("Generate environment key"). Pass as auth_token= / authToken on the client and as environment_key= / environmentKey on EnvironmentWorker. Store in a secrets manager; rotate on exposure. |
ANTHROPIC_WEBHOOK_SIGNING_KEY |
whsec_... |
Webhook signature verification (if using webhook-driven wake). The SDK reads this env var automatically for client.beta.webhooks.unwrap(). |
Security — what you own
Container hardening; egress restriction (there is no default); ANTHROPIC_ENVIRONMENT_KEY custody and rotation; one workspace + environment per trust boundary when running untrusted code; least-privilege for the tool process; log retention and redaction. Anthropic cannot: fast-revoke a leaked environment key, verify your image or supply chain, sandbox tool execution inside your container, or enforce retention after tool output reaches your infrastructure. See the Self-Hosted Sandboxes Security page in shared/live-sources.md for the full checklist.
Tools
Server tools vs client tools
| Type | Who runs it | How it works |
|---|---|---|
Prebuilt Claude Agent tools (agent_toolset_20260401) |
Anthropic, on the session's container (for cloud envs; for self_hosted, your worker supplies and runs them — see shared/managed-agents-self-hosted-sandboxes.md) |
File ops, bash, web search, etc. Enable all at once or configure individually with enabled: true/false. |
MCP tools (mcp_toolset) |
Anthropic's orchestration layer | Capabilities exposed by connected MCP servers. Grant access per-server via the toolset. |
| Custom tools | You — your application handles the call and returns results | Agent emits a agent.custom_tool_use event, session goes idle, you send back a user.custom_tool_result event. |
Recommendation: Enable all prebuilt tools via agent_toolset_20260401, then disable individually as needed.
Versioning: The toolset is a versioned, static resource. When underlying tools change, a new toolset version is created (hence _20260401) so you always know exactly what you're getting.
Agent Toolset
The agent_toolset_20260401 provides these built-in tools:
| Tool | Description |
|---|---|
bash |
Execute bash commands in a shell session |
read |
Read a file from the local filesystem, including text, images, PDFs, and Jupyter notebooks |
write |
Write a file to the local filesystem |
edit |
Perform string replacement in a file |
glob |
Fast file pattern matching using glob patterns |
grep |
Text search using regex patterns |
web_fetch |
Fetch content from a URL |
web_search |
Search the web for information |
Enable the full toolset:
{
"tools": [
{ "type": "agent_toolset_20260401" }
]
}
Per-Tool Configuration
Override defaults for individual tools. This example enables everything except bash:
{
"tools": [
{
"type": "agent_toolset_20260401",
"default_config": { "enabled": true },
"configs": [
{ "name": "bash", "enabled": false }
]
}
]
}
| Field | Required | Description |
|---|---|---|
type |
✅ | "agent_toolset_20260401" |
default_config |
❌ | Applied to all tools. { "enabled": bool, "permission_policy": {...} } |
configs |
❌ | Per-tool overrides: [{ "name": "...", "enabled": bool, "permission_policy": {...} }] |
Permission Policies
Control when server-executed tools (agent toolset + MCP) run automatically vs wait for approval. Does not apply to custom tools.
| Policy | Behavior |
|---|---|
always_allow |
Tool executes automatically (default) |
always_ask |
Session emits session.status_idle and pauses until you send a tool_confirmation event |
{
"type": "agent_toolset_20260401",
"default_config": {
"enabled": true,
"permission_policy": { "type": "always_allow" }
},
"configs": [
{ "name": "bash", "permission_policy": { "type": "always_ask" } }
]
}
Responding to always_ask: Send a user.tool_confirmation event with tool_use_id from the triggering agent_tool_use/mcp_tool_use event:
{ "type": "tool_confirmation", "tool_use_id": "sevt_abc123", "result": "allow" }
{ "type": "tool_confirmation", "tool_use_id": "sevt_def456", "result": "deny", "message": "Read .env.example instead" }
The optional message on a deny is delivered to the agent so it can adjust its approach.
To enable only specific tools, flip the default off and opt-in per tool:
{
"tools": [
{
"type": "agent_toolset_20260401",
"default_config": { "enabled": false },
"configs": [
{ "name": "bash", "enabled": true },
{ "name": "read", "enabled": true }
]
}
]
}
Custom Tools (Client-Side)
Custom tools are executed by your application, not Anthropic. The flow:
- Agent decides to use the tool → session emits a
agent.custom_tool_useevent with inputs - Session goes
idlewaiting for you - Your application executes the tool
- You send back a
user.custom_tool_resultevent with the output - Session resumes
running
No permission policy needed — you're the one executing.
{
"tools": [
{
"type": "custom",
"name": "get_weather",
"description": "Fetch current weather for a city.",
"input_schema": {
"type": "object",
"properties": {
"city": { "type": "string", "description": "City name" }
},
"required": ["city"]
}
}
]
}
MCP Servers
MCP (Model Context Protocol) servers expose standardized third-party capabilities (e.g. Asana, GitHub, Linear). Configuration is split across agent and vault:
- Agent creation declares which servers to connect to (
type,name,url— no auth). The agent'smcp_serversarray has no auth field. - Vault stores the OAuth credentials. Attach via
vault_idson session create.
This keeps secrets out of reusable agent definitions. Each vault credential is tied to one MCP server URL; Anthropic matches credentials to servers by URL.
Agent side — declare servers (no auth):
| Field | Required | Description |
|---|---|---|
type |
✅ | "url" |
name |
✅ | Unique name — referenced by mcp_toolset.mcp_server_name |
url |
✅ | The MCP server's endpoint URL (Streamable HTTP transport) |
{
"mcp_servers": [
{ "type": "url", "name": "linear", "url": "https://mcp.linear.app/mcp" }
],
"tools": [
{ "type": "mcp_toolset", "mcp_server_name": "linear" }
]
}
Session side — attach vault:
{
"agent": "agent_abc123",
"environment_id": "env_abc123",
"vault_ids": ["vlt_abc123"]
}
💡 Per-tool enablement (empirical):
mcp_toolsethas been observed acceptingdefault_config: {enabled: false}+configs: [{name, enabled: true}]for an allowlist pattern. The API ref shows only the minimal{type, mcp_server_name}form.
💡 Changing tools/MCP servers on a running session:
sessions.update()can replaceagent.tools,agent.mcp_servers, andvault_idswhile the session isidle— a session-local override that doesn't touch the agent object. Seeshared/managed-agents-core.md→ Updating the agent configuration mid-session.
Large MCP tool outputs. If an MCP tool returns more than 100K tokens, the output is automatically offloaded to a file in the sandbox — the agent receives a truncated preview plus the file path and can read the full content. No configuration required.
Invalid vault credentials don't block session creation. If a vault credential is invalid for a declared MCP server, the session still creates successfully; a session.error event describes the MCP auth failure, and auth retries on the next session.status_idle → session.status_running transition.
⚠️ MCP auth tokens ≠ REST API tokens. Hosted MCP servers (
mcp.notion.com,mcp.linear.app, etc.) typically require OAuth bearer tokens, not the service's native API keys. A Notionntn_integration token authenticates against Notion's REST API but will not work as a vault credential for the Notion MCP server. These are different auth systems.
Vaults — the MCP credential store
Vaults store OAuth credentials (access token + refresh token) that Anthropic auto-refreshes on your behalf via standard OAuth 2.0 refresh_token grant. This is the only way to authenticate MCP servers in the launch SDK.
Credentials and the sandbox
Vaults store credentials; those credentials never enter the sandbox. This is a deliberate security boundary — code running in the sandbox (including anything the agent writes) cannot read or exfiltrate a vaulted credential, even under prompt injection. Instead, credentials are injected by Anthropic-side proxies after a request leaves the sandbox:
- MCP tool calls are routed through an Anthropic-side proxy that fetches the credential from the vault and adds it to the outbound request.
- Git operations on attached GitHub repositories (
git pull,git push, GitHub REST calls) are routed through a git proxy that injects thegithub_repositoryresource'sauthorization_tokenthe same way.
Not yet supported: running other authenticated CLIs (e.g. aws, gcloud, stripe) directly inside the sandbox. There is currently no way to set container environment variables or expose vault credentials to arbitrary processes. If you need one of these today:
- Prefer an MCP server for that service if one exists — it gets the same vault-backed injection.
- Otherwise, register a custom tool: the agent emits
agent.custom_tool_use, your orchestrator (which already holds the credential) executes the call and returnsuser.custom_tool_resultover the same authenticated event stream. No public endpoint is exposed; the sandbox never sees the secret. Seeshared/managed-agents-client-patterns.md→ Pattern 9.
Do not put API keys in the system prompt or user messages as a workaround — they persist in the session's event history.
Formerly known internally as TATs (Tool/Tenant Access Tokens).
Flow:
- Create a vault (
client.beta.vaults.create(...)) — one per tenant/user, or one shared, depending on your model - Add MCP credentials to it (
client.beta.vaults.credentials.create(...)) — each credential is tied to one MCP server URL - Reference the vault on session create via
vault_ids: ["vlt_..."] - Anthropic auto-refreshes tokens before they expire; the agent uses the current access token when calling MCP tools
Credential shape:
{
"display_name": "Notion (workspace-foo)",
"auth": {
"type": "mcp_oauth",
"mcp_server_url": "https://mcp.notion.com/mcp",
"access_token": "<current access token>",
"expires_at": "2026-04-02T14:00:00Z",
"refresh": {
"refresh_token": "<refresh token>",
"client_id": "<your OAuth client_id>",
"token_endpoint": "https://api.notion.com/v1/oauth/token",
"token_endpoint_auth": { "type": "none" }
}
}
}
The refresh block is what enables auto-refresh — token_endpoint is where Anthropic posts the refresh_token grant. token_endpoint_auth is a discriminated union:
type |
Shape | Use when |
|---|---|---|
"none" |
{type: "none"} |
Public OAuth client (no secret) |
"client_secret_basic" |
{type: "client_secret_basic", client_secret: "..."} |
Confidential client, secret via HTTP Basic auth |
"client_secret_post" |
{type: "client_secret_post", client_secret: "..."} |
Confidential client, secret in request body |
Omit refresh entirely if you only have an access token with no refresh capability — it'll work until it expires, then the agent loses access.
💡 Getting an OAuth token. How you obtain the initial access and refresh tokens depends on the MCP server — consult its documentation. Once you have them, store them in a vault credential using the shape above; Anthropic auto-refreshes via the
refresh.token_endpointfrom there.
Scoping: Vaults are workspace-scoped. Anyone with developer+ role in the API workspace can create, read (metadata only — secrets are write-only), and attach vaults. vault_ids can be set at session create time but not via session update (the SDK docstring says "Not yet supported; requests setting this field are rejected").
Skills
Skills are reusable, filesystem-based resources that provide your agent 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.
Two types — both work the same way; the agent automatically uses them when relevant to the task at hand:
| Type | What it is |
|---|---|
| Pre-built Anthropic skills | Common document tasks (PowerPoint, Excel, Word, PDF). Reference by name (e.g. xlsx). |
| Custom skills | Skills you've created in your organization via the Skills API. Reference by skill_id + optional version. |
Max 20 skills per agent. Agent creation uses managed-agents-2026-04-01; the separate Skills API (for managing custom skill definitions) uses skills-2025-10-02.
Enabling skills on a session
Skills are attached to the agent definition via agents.create():
const agent = await client.beta.agents.create(
{
name: "Financial Agent",
model: "claude-opus-4-8",
system: "You are a financial analysis agent.",
skills: [
{ type: "anthropic", skill_id: "xlsx" },
{ type: "custom", skill_id: "skill_abc123", version: "latest" },
],
}
);
Python:
agent = client.beta.agents.create(
name="Financial Agent",
model="claude-opus-4-8",
system="You are a financial analysis agent.",
skills=[
{"type": "anthropic", "skill_id": "xlsx"},
{"type": "custom", "skill_id": "skill_abc123", "version": "latest"},
]
)
Skill reference fields:
| Field | Anthropic skill | Custom skill |
|---|---|---|
type |
"anthropic" |
"custom" |
skill_id |
Skill name (e.g. "xlsx", "docx", "pptx", "pdf") |
Skill ID from Skills API (e.g. "skill_abc123") |
version |
— | "latest" or a specific version number |
Skills API
| Operation | Method | Path |
|---|---|---|
| Create Skill | POST |
/v1/skills |
| List Skills | GET |
/v1/skills |
| Get Skill | GET |
/v1/skills/{id} |
| Delete Skill | DELETE |
/v1/skills/{id} |
| Create Version | POST |
/v1/skills/{id}/versions |
| List Versions | GET |
/v1/skills/{id}/versions |
| Get Version | GET |
/v1/skills/{id}/versions/{version} |
| Delete Version | DELETE |
/v1/skills/{id}/versions/{version} |
Anthropic can POST to your HTTPS endpoint when a Managed Agents resource changes state — an alternative to holding an SSE stream or polling. Payloads are thin (event type + resource IDs only); on receipt, fetch the resource for current state. Every delivery is HMAC-signed.
Direction matters. This page covers Anthropic → you notifications about session/vault state. It does not cover third-party → you webhooks that trigger a session (e.g. a GitHub push handler that calls
sessions.create()) — that's ordinary application code on your side with no Anthropic-specific wire format.
Register an endpoint (Console only)
Console → Manage → Webhooks. There is no programmatic endpoint-management API yet. Secret rotation is supported from the same page.
| Field | Constraint |
|---|---|
| URL | HTTPS on port 443, publicly resolvable hostname |
| Event types | Subscribe per data.type — you only receive subscribed types (plus test events) |
| Signing secret | whsec_-prefixed, 32 bytes, shown once at creation — store it |
Verify the signature
Every delivery is HMAC-signed. Use the SDK's client.beta.webhooks.unwrap() — it verifies the signature, rejects payloads more than ~5 minutes old, and returns the parsed event. It reads the whsec_ secret from ANTHROPIC_WEBHOOK_SIGNING_KEY.
import anthropic
from flask import Flask, request
client = anthropic.Anthropic() # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env
app = Flask(__name__)
@app.route("/webhook", methods=["POST"])
def webhook():
try:
event = client.beta.webhooks.unwrap(
request.get_data(as_text=True),
headers=dict(request.headers),
)
except Exception:
return "invalid signature", 400
if event.id in seen_event_ids: # dedupe retries — id is per-event, not per-delivery
return "", 204
seen_event_ids.add(event.id)
match event.data.type:
case "session.status_idled":
session = client.beta.sessions.retrieve(event.data.id)
notify_user(session)
case "vault_credential.refresh_failed":
alert_oncall(event.data.id)
return "", 204
Pass the raw request body to unwrap() — frameworks that re-serialize JSON (Express .json(), Flask .get_json()) change the bytes and break the MAC. For other languages, look up the beta.webhooks.unwrap binding in the SDK repo (shared/live-sources.md); don't hand-roll verification.
Payload envelope
{
"type": "event",
"id": "event_01ABC...",
"created_at": "2026-03-18T14:05:22Z",
"data": {
"type": "session.status_idled",
"id": "session_01XYZ...",
"organization_id": "8a3d2f1e-...",
"workspace_id": "c7b0e4d9-..."
}
}
Switch on data.type, fetch the resource by data.id, return any 2xx to acknowledge. created_at is when the state transition happened, not when the webhook fired.
Supported data.type values
data.type |
Fires when |
|---|---|
session.status_scheduled |
Session created and ready to accept events |
session.status_run_started |
Agent execution kicked off (every transition to running) |
session.status_idled |
Agent awaiting input (tool approval, custom tool result, or next message) |
session.status_terminated |
Session hit a terminal error |
session.thread_created |
Multiagent: coordinator opened a new subagent thread |
session.thread_idled |
Multiagent: a subagent thread is waiting for input |
session.outcome_evaluation_ended |
Outcome grader finished one iteration |
vault.archived |
Vault was archived |
vault.created |
Vault was created |
vault.deleted |
Vault was deleted |
vault_credential.archived |
Vault credential was archived |
vault_credential.created |
Vault credential was created |
vault_credential.deleted |
Vault credential was deleted |
vault_credential.refresh_failed |
MCP OAuth vault credential failed to refresh |
These are webhook
data.typevalues — a separate namespace from SSE event types (session.status_idle,span.outcome_evaluation_end, etc. inshared/managed-agents-events.md). Don't reuse SSE constants in webhook handlers.
Delivery behavior & pitfalls
- No ordering guarantee.
session.status_idledmay arrive beforesession.outcome_evaluation_endedeven if the evaluation finished first. Sort by envelopecreated_atif order matters. - Retries carry the same
event.id. At least one retry on non-2xx. Dedupe onevent.id. - 3xx is failure. Redirects are not followed — update the URL in Console if your endpoint moves.
- Auto-disable after ~20 consecutive failed deliveries, or immediately if the hostname resolves to a private IP or returns a redirect. Re-enable manually in Console.
- Thin payload is intentional. Don't expect
stop_reason,outcome_evaluations, credential secrets, etc. on the webhook body — fetch the resource.
If you arrived via
/claude-api migrate: this is the right file. Execute the steps below in order — do not summarize them back to the user. Start with Step 0 (confirm scope) before touching any file.
How to move existing code to newer Claude models. Covers breaking changes, deprecated parameters, and drop-in replacements for retired models.
For the latest, authoritative version (with code samples in every supported language), WebFetch the Migration Guide URL from shared/live-sources.md. Use this file for the consolidated, skill-resident reference; fall back to the live docs whenever a model launch or breaking change may have shifted the picture.
This file is large. Use the section names below to jump (or Grep this file for the heading text). Read Step 0 and Step 1 first — they apply to every migration. Then read only the per-target section for the model you are migrating to.
| Section | When you need it |
|---|---|
| Step 0: Confirm the migration scope | Always — before any edits |
| Step 1: Classify each file | Always — decides whether to swap, add-alongside, or skip |
| Per-SDK Syntax Reference | Translate the Python examples in this guide to TypeScript / Go / Ruby / Java / C# / PHP |
| Destination Models / Retired Model Replacements | Picking a target model |
| Breaking Changes by Source Model | Migrating to Opus 4.6 / Sonnet 4.6 |
| Migrating to Opus 4.7 | Migrating to Opus 4.7 (breaking changes, silent defaults, behavioral shifts) |
| Opus 4.7 Migration Checklist | The required vs optional items for 4.7, tagged [BLOCKS] / [TUNE] |
| Migrating to Opus 4.8 | Migrating to Opus 4.8 (no new breaking changes; mid-session system prompts; behavioral re-tuning) |
| Opus 4.8 Migration Checklist | The required vs optional items for 4.8, tagged [BLOCKS] / [TUNE] |
| Verify the Migration | After edits — runtime spot-check |
TL;DR: Change the model ID string. If you were using budget_tokens, switch to thinking: {type: "adaptive"}. If you were using assistant prefills, they 400 on both Opus 4.6 and Sonnet 4.6 — switch to one of the prefill replacements (most often output_config.format; see the table in Breaking Changes by Source Model). If you're moving from Sonnet 4.5 to Sonnet 4.6, set effort explicitly — 4.6 defaults to high. Remove the effort-2025-11-24 and fine-grained-tool-streaming-2025-05-14 beta headers (GA on 4.6); remove interleaved-thinking-2025-05-14 once you're on adaptive thinking (keep it only while using the transitional budget_tokens escape hatch). Then drop back from client.beta.messages.create to client.messages.create. Dial back any aggressive "CRITICAL: YOU MUST" tool instructions; 4.6 follows the system prompt much more closely.
Step 0: Confirm the migration scope
Before any Write, Edit, or MultiEdit call, confirm the scope. If the user's request does not explicitly name a single file, a specific directory, or an explicit file list, ask first — do not start editing. This is non-negotiable: even imperative-sounding requests like "migrate my codebase", "move my project to X", "upgrade to Sonnet 4.6", or bare "migrate to Opus 4.7" leave the scope ambiguous and require a clarifying question. Phrases like "my project", "my code", "my codebase", "the whole thing", "everywhere", or "across the repo" are ambiguous, not directive — they tell you what to do but not where. Ask before doing.
Offer the common scopes explicitly and wait for the answer before touching any file:
- The entire working directory
- A specific subdirectory (e.g.
src/,app/,services/billing/) - A specific file or a list of files
Surface this as a single clarifying question so the user can answer in one turn. Proceed without asking only when the scope is already unambiguous — the user named an exact file ("migrate extract.py to Sonnet 4.6"), pointed at a specific directory ("migrate everything under services/billing/ to Opus 4.6"), listed specific files ("update a.py and b.py"), or already answered the scope question in an earlier turn. If you can answer the question "which files is this change going to touch?" with a precise list from the prompt alone, proceed. If not, ask.
Worked example. If the user says "Move my project to Opus 4.6. I want adaptive thinking everywhere it makes sense." you do not know whether "my project" means the whole working directory, just src/, just the production code, or something else — the everywhere makes the intent clear (update every call site within scope) but the scope itself is still not defined. Do not start editing. Respond with:
Before I start editing, can you confirm the scope? I can migrate:
- Every
.pyfile in the working directory- Just the files under
src/(production code)- A specific subdirectory or list of files you name
Which one?
Then wait for the answer. The same applies to "Migrate to Opus 4.7" and bare "Help me upgrade to Sonnet 4.6" — ask before editing.
Sizing the scope question (large repos). Before asking, get a per-directory count so the user can pick concretely:
rg -l "<old-model-id>" --type-not md | cut -d/ -f1 | sort | uniq -c | sort -rn
Present the breakdown in your scope question (e.g. "Found 217 references across 3 directories: api/ (130), api-go/ (62), routing/ (25). Which to migrate?"). Also confirm git status is clean before surveying — unexpected modifications mean a concurrent process; stop and investigate before proceeding.
Step 1: Classify each file
Not every file that contains the old model ID is a caller of the API. Before editing, classify each file into one of these buckets — the right action differs:
| # | Bucket | What it looks like | Action |
|---|---|---|---|
| 1 | Calls the API/SDK | client.messages.create(model=…), anthropic.Anthropic(), request payloads |
Swap the model ID and apply the breaking-change checklist for the target version (below). |
| 2 | Defines or serves the model | Model registries, OpenAPI specs, routing/queue configs, model-policy enums, generated catalogs | The old entry stays (the model is still served). Ask whether to (a) add the new model alongside, (b) leave alone, or (c) retire the old model — never blind-replace. If you can't ask, default to (a): add the new model alongside and flag it — replacing would de-register a model that's still in production. |
| 3 | References the ID as an opaque string | UI fallback constants, capability-gate substring checks, generic test fixtures, label parsers, env defaults | Usually swap the string and verify any parser/regex/substring match handles the new ID — but check the sub-cases below first. |
| 4 | Suffixed variant ID | claude-<model>-<suffix> like -fast, -1024k, -200k, [1m], dated snapshots |
These are deployment/routing identifiers, not the public model ID. Do not assume a new-model equivalent exists. Verify in the registry first; if absent, leave the string alone and flag it. |
Bucket 3 sub-cases — before swapping a string reference, check:
- Capability gate (e.g.
if 'opus-4-6' in model_id:enables a feature) → add the new ID alongside, don't replace. The old model is still served and still has the capability, so replacing would silently disable the feature for any old-model traffic that still flows through. If you know no old-model traffic will hit this gate (single-caller codebase fully migrating), replacing is fine; if unsure, add alongside. - Registry-assert test (e.g.
assert "claude-X" in supported_models,test_X_has_N_clusters) → add an assertion for the new model alongside; keep the old one. The old model is still served, so its assertion stays valid — but the registry should also include the new model, so assert that too. Heuristic: if the test references multiple model versions in a list, it's a registry test; if one model in a struct compared only to itself, it's a generic fixture. - Frozen / generated snapshot → regenerate, don't hand-edit.
- Coupled to a definer (e.g. an integration test that passes model authorization via a shared
conftestseed list, or asserts on a billing-tier / rate-limit-group enum or a generated SKU/pricing catalog) → verify the definer has a new-model entry first. If not, add a seed entry (reusing the nearest existing tier as a placeholder); if you can't confidently do that, ask the user how to populate the definer. Do not skip the test. Swapping without populating the definer will make the test fail at runtime.
When migrating tests specifically: breaking parameters (temperature, top_p, budget_tokens) are usually absent — test fixtures rarely set sampling params on placeholder models. The breaking-change scan is still required, but expect mostly clean results.
Find intentionally-flagged sync points first. Many codebases tag spots that must change at every model launch with comment markers like MODEL LAUNCH, KEEP IN SYNC, @model-update, or similar. Grep for whatever convention the repo uses before the broad model-ID grep — those markers point at the load-bearing changes.
Per-SDK Syntax Reference
Code examples in this guide are Python. The same fields exist in every official Anthropic SDK — Stainless generates all 7 from the same OpenAPI spec, so JSON field names map 1:1 with only case-convention differences. Use the rows below to translate the Python examples to the SDK you are migrating.
Verify type and method names against the SDK source before writing them into customer code. WebFetch the relevant repository from the SDK source-code table in
shared/live-sources.md(one row per SDK) and confirm the exact symbol — particularly for typed SDKs (Go, Java, C#) where union/builder names can differ from the JSON shape. Do not guess type names that aren't in the table below or in<lang>/claude-api/README.md.
thinking — budget_tokens → adaptive
| SDK | Before | After |
|---|---|---|
| Python | thinking={"type": "enabled", "budget_tokens": N} |
thinking={"type": "adaptive"} |
| TypeScript | thinking: { type: 'enabled', budget_tokens: N } |
thinking: { type: 'adaptive' } |
| Go | Thinking: anthropic.ThinkingConfigParamOfEnabled(N) |
Thinking: anthropic.ThinkingConfigParamUnion{OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{}} |
| Ruby | thinking: { type: "enabled", budget_tokens: N } |
thinking: { type: "adaptive" } |
| Java | .thinking(ThinkingConfigEnabled.builder().budgetTokens(N).build()) |
.thinking(ThinkingConfigAdaptive.builder().build()) |
| C# | Thinking = new ThinkingConfigEnabled { BudgetTokens = N } |
Thinking = new ThinkingConfigAdaptive() |
| PHP | thinking: ['type' => 'enabled', 'budget_tokens' => N] |
thinking: ['type' => 'adaptive'] |
Sampling parameters — temperature / top_p / top_k
(Remove the field entirely on Opus 4.7; on Claude 4.x keep at most one of temperature or top_p.)
| SDK | Field(s) to remove |
|---|---|
| Python | temperature=…, top_p=…, top_k=… |
| TypeScript | temperature: …, top_p: …, top_k: … |
| Go | Temperature: anthropic.Float(…), TopP: anthropic.Float(…), TopK: anthropic.Int(…) |
| Ruby | temperature: …, top_p: …, top_k: … |
| Java | .temperature(…), .topP(…), .topK(…) |
| C# | Temperature = …, TopP = …, TopK = … |
| PHP | temperature: …, topP: …, topK: … |
Prefill replacement — structured outputs via output_config.format
| SDK | Remove (last assistant turn) | Add |
|---|---|---|
| Python | {"role": "assistant", "content": "…"} |
output_config={"format": {"type": "json_schema", "schema": SCHEMA}} |
| TypeScript | { role: 'assistant', content: '…' } |
output_config: { format: { type: 'json_schema', schema: SCHEMA } } |
| Go | trailing anthropic.MessageParam{Role: "assistant", …} |
OutputConfig: anthropic.OutputConfigParam{Format: anthropic.JSONOutputFormatParam{…}} |
| Ruby | { role: "assistant", content: "…" } |
output_config: { format: { type: "json_schema", schema: SCHEMA } } |
| Java | trailing Message.builder().role(ASSISTANT)… |
.outputConfig(OutputConfig.builder().format(JsonOutputFormat.builder()…build()).build()) |
| C# | trailing new Message { Role = "assistant", … } |
OutputConfig = new OutputConfig { Format = new JsonOutputFormat { … } } |
| PHP | trailing ['role' => 'assistant', 'content' => '…'] |
outputConfig: ['format' => ['type' => 'json_schema', 'schema' => $SCHEMA]] |
thinking.display — opt back into summarized reasoning (Opus 4.7)
| SDK | Add |
|---|---|
| Python | thinking={"type": "adaptive", "display": "summarized"} |
| TypeScript | thinking: { type: 'adaptive', display: 'summarized' } |
| Go | Thinking: anthropic.ThinkingConfigParamUnion{OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized}} |
| Ruby | thinking: { type: "adaptive", display: "summarized" } (or display_: when constructing the model class directly) |
| Java | .thinking(ThinkingConfigAdaptive.builder().display(ThinkingConfigAdaptive.Display.SUMMARIZED).build()) |
| C# | Thinking = new ThinkingConfigAdaptive { Display = Display.Summarized } |
| PHP | thinking: ['type' => 'adaptive', 'display' => 'summarized'] |
For any field not in these tables, the JSON key in the Python example translates directly: snake_case for Python/TypeScript/Ruby, camelCase named args for PHP, PascalCase struct fields for Go/C#, camelCase builder methods for Java.
Explain every change you make
Migration edits often look arbitrary to a user who hasn't read the release notes — a removed temperature, a deleted prefill, a rewritten system-prompt sentence. For each edit, tell the user what you changed and why, tied to the specific API or behavioral change that motivates it. Do this in your summary as you work, not just at the end.
Be especially explicit about system-prompt edits. Users are rightly protective of their prompts, and prompt-tuning changes are judgment calls (not hard API requirements). For any prompt edit:
- Quote the before and after text.
- State the behavioral shift that motivates it (e.g. "Opus 4.7 calibrates response length to task complexity, so I added an explicit length instruction", or "4.6 follows instructions more literally, so 'CRITICAL: YOU MUST use the search tool' will now overtrigger — softened to 'Use the search tool when…'").
- Make clear which prompt edits are optional tuning (tone, length, subagent guidance) versus which code edits are required to avoid a 400 (sampling params,
budget_tokens, prefills). Never present an optional prompt change as mandatory.
If you're applying several prompt-tuning edits at once, offer them as a short list the user can accept or decline item-by-item rather than silently rewriting their system prompt.
Before You Migrate
- Confirm the target model ID. Use only the exact strings from
shared/models.md— do not append date suffixes to aliases (claude-opus-4-6, notclaude-opus-4-6-20251101). Guessing an ID will 404. - Check which features your code uses with this checklist:
thinking: {type: "enabled", budget_tokens: N}→ migrate to adaptive thinking on Opus 4.6 / Sonnet 4.6 (still functional but deprecated)- Assistant-turn prefills (
messagesending withrole: "assistant") → must change on Opus 4.6 / Sonnet 4.6 (returns 400) output_formatparameter onmessages.create()→ must change on all models (deprecated API-wide)max_tokens > ~16000→ must stream on any model (above ~16K risks SDK HTTP timeouts). When streaming, Sonnet 4.6 / Haiku 4.5 cap at 64K and Opus 4.6 caps at 128K- Beta headers
effort-2025-11-24,fine-grained-tool-streaming-2025-05-14,interleaved-thinking-2025-05-14→ GA on 4.6, remove them and switch fromclient.beta.messages.createtoclient.messages.create - Moving Sonnet 4.5 → Sonnet 4.6 with no
effortset → 4.6 defaults tohigh, which may change your latency/cost profile - System prompts with
CRITICAL,MUST,If in doubt, use Xlanguage → likely to overtrigger on 4.6 (see Prompt-Behavior Changes) - Coming from 3.x / 4.0 / 4.1: also check sampling params (
temperature+top_p), tool versions (text_editor_20250728),refusal+model_context_window_exceededstop reasons, trailing-newline tool-param handling
- Test on a single request first. Run one call against the new model, inspect the response, then roll out.
Destination Models (recommended targets)
| If you're on… | Migrate to | Why |
|---|---|---|
| Opus 4.7 | claude-opus-4-8 |
Most capable model; same API surface as 4.7 (no new breaking changes) — mostly prompt re-tuning; see Migrating to Opus 4.8 |
| Opus 4.6 | claude-opus-4-8 |
Apply the Opus 4.7 breaking changes, then the 4.8 re-tuning |
| Opus 4.0 / 4.1 / 4.5 / Opus 3 | claude-opus-4-8 |
Apply 4.6 → 4.7 → 4.8 in order (adaptive thinking, drop sampling params, then re-tune) |
| Sonnet 4.0 / 4.5 / 3.7 / 3.5 | claude-sonnet-4-6 |
Best speed / intelligence balance; adaptive thinking; 64K output |
| Haiku 3 / 3.5 | claude-haiku-4-5 |
Fastest and most cost-effective |
Default to the latest Opus for the caller's tier unless they explicitly chose otherwise. The Opus migrations layer: if you're on Opus 4.6 or older, apply each version's section in order up to your target (e.g. 4.5 → 4.8 means the 4.6, 4.7, and 4.8 sections in sequence). A 4.7 → 4.8 move has no new breaking changes — see Migrating to Opus 4.8 below.
Retired Model Replacements
These models return 404 — update immediately:
| Retired model | Retired | Drop-in replacement |
|---|---|---|
claude-3-7-sonnet-20250219 |
Feb 19, 2026 | claude-sonnet-4-6 |
claude-3-5-haiku-20241022 |
Feb 19, 2026 | claude-haiku-4-5 |
claude-3-opus-20240229 |
Jan 5, 2026 | claude-opus-4-8 |
claude-3-5-sonnet-20241022 |
Oct 28, 2025 | claude-sonnet-4-6 |
claude-3-5-sonnet-20240620 |
Oct 28, 2025 | claude-sonnet-4-6 |
claude-3-sonnet-20240229 |
Jul 21, 2025 | claude-sonnet-4-6 |
claude-2.1, claude-2.0 |
Jul 21, 2025 | claude-sonnet-4-6 |
Deprecated Models (retiring soon)
| Model | Retires | Replacement |
|---|---|---|
claude-3-haiku-20240307 |
Apr 19, 2026 | claude-haiku-4-5 |
claude-opus-4-20250514 |
June 15, 2026 | claude-opus-4-8 |
claude-sonnet-4-20250514 |
June 15, 2026 | claude-sonnet-4-6 |
Breaking Changes by Source Model
Migrating from Sonnet 4.5 to Sonnet 4.6 (effort default change)
Sonnet 4.5 had no effort parameter; Sonnet 4.6 defaults to high. If you just switch the model string and do nothing else, you may see noticeably higher latency and token usage. Set effort explicitly.
Recommended starting points:
| Workload | Start at | Notes |
|---|---|---|
| Chat, classification, content generation | low |
With thinking: {"type": "disabled"} you'll see similar or better performance vs. Sonnet 4.5 no-thinking |
| Most applications (balanced) | medium |
The default sweet spot for quality vs. cost |
| Agentic coding, tool-heavy workflows | medium |
Pair with adaptive thinking and a generous max_tokens (up to 64K with streaming — Sonnet 4.6's ceiling) |
| Autonomous multi-step agents, long-horizon loops | high |
Scale down to medium if latency/tokens become a concern |
| Computer-use agents | high + adaptive |
Sonnet 4.6's best computer-use accuracy is on adaptive + high |
For non-thinking chat workloads specifically:
client.messages.create(
model="claude-sonnet-4-6",
max_tokens=8192,
thinking={"type": "disabled"},
output_config={"effort": "low"},
messages=[{"role": "user", "content": "..."}],
)
When to use Opus 4.6 instead: hardest and longest-horizon problems — large code migrations, deep research, extended autonomous work. Sonnet 4.6 wins on fast turnaround and cost efficiency.
Migrating to Opus 4.6 / Sonnet 4.6 (from any older model)
1. Manual extended thinking is deprecated — use adaptive thinking.
thinking: {type: "enabled", budget_tokens: N} (manual extended thinking with a fixed token budget) is deprecated on Opus 4.6 and Sonnet 4.6. Replace it with thinking: {type: "adaptive"}, which lets Claude decide when and how much to think. Adaptive thinking also enables interleaved thinking automatically (no beta header needed).
# Old (still works on older models, deprecated on 4.6)
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 8000},
messages=[...]
)
# New (Opus 4.6 / Sonnet 4.6)
response = client.messages.create(
model="claude-opus-4-6", # or "claude-sonnet-4-6"
max_tokens=16000,
thinking={"type": "adaptive"},
output_config={"effort": "high"}, # optional: low | medium | high | max
messages=[...]
)
Adaptive thinking is the long-term target, and on internal evaluations it outperforms manual extended thinking. Move when you can.
Transitional escape hatch: manual extended thinking is still functional on Opus 4.6 and Sonnet 4.6 (deprecated, will be removed in a future release). If you need a hard ceiling while migrating — for example, to bound token spend on a runaway workload before you've tuned effort — you can keep budget_tokens around alongside an explicit effort value, then remove it in a follow-up. budget_tokens must be strictly less than max_tokens:
# Transitional only — deprecated, plan to remove
client.messages.create(
model="claude-sonnet-4-6",
max_tokens=16384,
thinking={"type": "enabled", "budget_tokens": 8192}, # must be < max_tokens
output_config={"effort": "medium"},
messages=[...],
)
If the user asks for a "thinking budget" on 4.6, the preferred answer is effort — use low, medium, high, or max (Opus-tier only — not Sonnet or Haiku) rather than a token count.
2. Effort parameter (Opus 4.5, Opus 4.6, Sonnet 4.6 only).
Controls thinking depth and overall token spend. Goes inside output_config, not top-level. Default is high. max is Opus-tier only (Opus 4.6 and later — not Sonnet or Haiku). Errors on Sonnet 4.5 and Haiku 4.5.
output_config={"effort": "medium"} # often the best cost / quality balance
Migrating to the 4.6 family (Opus 4.6 and Sonnet 4.6)
3. Assistant-turn prefills return 400 (Opus 4.6 and Sonnet 4.6).
Prefilled responses on the final assistant turn are no longer supported on either Opus 4.6 or Sonnet 4.6 — both return a 400. Adding assistant messages elsewhere in the conversation (e.g., for few-shot examples) still works. Pick the replacement that matches what the prefill was doing:
| Prefill was used for | Replacement |
|---|---|
| Forcing JSON / YAML / schema output | output_config.format with a json_schema — see example below |
| Forcing a classification label | Tool with an enum field containing valid labels, or structured outputs |
Skipping preambles (Here is the summary:\n) |
System prompt instruction: "Respond directly without preamble. Do not start with phrases like 'Here is...' or 'Based on...'." |
| Steering around bad refusals | Usually no longer needed — 4.6 refuses far more appropriately. Plain user-turn prompting is sufficient. |
| Continuing an interrupted response | Move continuation into the user turn: "Your previous response was interrupted and ended with [last text]. Continue from there." |
| Injecting reminders / context hydration | Inject into the user turn instead. For complex agent harnesses, expose context via a tool call or during compaction. |
# Old (fails on Opus 4.6 / Sonnet 4.6) — prefill forcing JSON shape
messages=[
{"role": "user", "content": "Extract the name."},
{"role": "assistant", "content": "{\"name\": \""},
]
# New — structured outputs replace the prefill
response = client.messages.create(
model="claude-opus-4-6",
max_tokens=1024,
output_config={"format": {"type": "json_schema", "schema": {...}}},
messages=[{"role": "user", "content": "Extract the name."}],
)
4. Stream for max_tokens > ~16K (all models); Opus 4.6 alone reaches 128K.
Non-streaming requests hit SDK HTTP timeouts at high max_tokens, regardless of model — stream for anything above ~16K output. The streamable ceiling differs by model: Sonnet 4.6 and Haiku 4.5 cap at 64K, and Opus 4.6 alone goes up to 128K.
with client.messages.stream(model="claude-opus-4-6", max_tokens=64000, ...) as stream:
message = stream.get_final_message()
5. Tool-call JSON escaping may differ (Opus 4.6 and Sonnet 4.6).
Both 4.6 models can produce tool call input fields with Unicode or forward-slash escaping. Always parse with json.loads() / JSON.parse() — never raw-string-match the serialized input.
All models
6. output_format → output_config.format (API-wide).
The old top-level output_format parameter on messages.create() is deprecated. Use output_config.format instead. This is not 4.6-specific — applies to every model.
Beta Headers to Remove on 4.6
Several beta headers that were required on 4.5 are now GA on 4.6 and should be removed. Leaving them in is harmless but misleading; removing them also lets you move from client.beta.messages.create(...) back to client.messages.create(...).
| Header | Status on 4.6 | Action |
|---|---|---|
effort-2025-11-24 |
Effort parameter is GA | Remove |
fine-grained-tool-streaming-2025-05-14 |
GA | Remove |
interleaved-thinking-2025-05-14 |
Adaptive thinking enables interleaved thinking automatically | Remove when using adaptive thinking; still functional on Sonnet 4.6 with manual extended thinking, but that path is deprecated |
token-efficient-tools-2025-02-19 |
Built in to all Claude 4+ models | Remove (no effect) |
output-128k-2025-02-19 |
Built in to Claude 4+ models | Remove (no effect) |
Once you remove all of these and finish moving to adaptive thinking, you can switch the SDK call site from the beta namespace back to the regular one:
# Before
response = client.beta.messages.create(
model="claude-opus-4-5",
betas=["interleaved-thinking-2025-05-14", "effort-2025-11-24"],
...
)
# After
response = client.messages.create(
model="claude-opus-4-6",
thinking={"type": "adaptive"},
output_config={"effort": "high"},
...
)
Additional Changes When Coming from 3.x / 4.0 / 4.1 → 4.6
If you're jumping from Opus 4.1, Sonnet 4, Sonnet 3.7, or an older Claude 3.x model directly to 4.6, apply everything above plus the items in this section. Users already on Opus 4.5 / Sonnet 4.5 can skip this.
1. Sampling parameters: temperature OR top_p, not both.
Passing both will error on every Claude 4+ model:
# Old (3.x only — errors on 4+)
client.messages.create(temperature=0.7, top_p=0.9, ...)
# New
client.messages.create(temperature=0.7, ...) # or top_p, not both
2. Update tool versions.
Legacy tool versions are not supported on 4+. Both the type and the name field change — text_editor_20250728 and str_replace_based_edit_tool are a pair; updating one without the other 400s. Also remove the undo_edit command from your text-editor integration:
| Old | New |
|---|---|
text_editor_20250124 + str_replace_editor |
text_editor_20250728 + str_replace_based_edit_tool |
code_execution_* (earlier versions) |
code_execution_20250825 |
undo_edit command |
(no longer supported — delete call sites) |
# Before
tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]
# After — BOTH fields change
tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]
3. Handle the refusal stop reason.
Claude 4+ can return stop_reason: "refusal" on the response. If your code only handles end_turn / tool_use / max_tokens, add a branch:
if response.stop_reason == "refusal":
# Surface the refusal to the user; do not retry with the same prompt
...
4. Handle the model_context_window_exceeded stop reason (4.5+).
Distinct from max_tokens: it means the model hit the context window limit, not the requested output cap. Handle both:
if response.stop_reason == "model_context_window_exceeded":
# Context window exhausted — compact or split the conversation
...
elif response.stop_reason == "max_tokens":
# Requested output cap hit — retry with higher max_tokens or stream
...
5. Trailing newlines preserved in tool call string parameters (4.5+).
4.5 and 4.6 preserve trailing newlines that older models stripped. If your tool implementations do exact string matching against tool-call input values (e.g., if name == "foo"), verify they still match when the model sends "foo\n". Normalizing with .rstrip() on the receiving side is usually the simplest fix.
6. Haiku: rate limits reset between generations.
Haiku 4.5 has its own rate-limit pool separate from Haiku 3 / 3.5. If you're ramping traffic as you migrate, check your tier's Haiku 4.5 limits at API rate limits — a quota that comfortably served Haiku 3.5 traffic may need a tier bump for the same volume on 4.5.
Prompt-Behavior Changes (Opus 4.5 / 4.6, Sonnet 4.6)
These don't break your code, but prompts that worked on 4.5-and-earlier may over- or under-trigger on 4.6. Tune as needed.
1. Aggressive instructions cause overtriggering. Opus 4.5 and 4.6 follow the system prompt much more closely than earlier models. Prompts written to overcome the old reluctance are now too aggressive:
| Before (worked on 4.0 / 4.5) | After (use on 4.6) |
|---|---|
CRITICAL: You MUST use this tool when... |
Use this tool when... |
Default to using [tool] |
Use [tool] when it would improve X |
If in doubt, use [tool] |
(delete — no longer needed) |
If the model is now overtriggering a tool or skill, the fix is almost always to dial back the language, not to add more guardrails.
2. Overthinking and excessive exploration (Opus 4.6). At higher effort settings, Opus 4.6 explores more before answering. If that burns too many thinking tokens, lower effort first (medium is often the sweet spot) before adding prose instructions to constrain reasoning.
3. Overeager subagent spawning (Opus 4.6). Opus 4.6 has a strong preference for delegating to subagents. If you see it spawning a subagent for something a direct grep or read would solve, add guidance: "Use subagents only for parallel or independent workstreams. For single-file reads or sequential operations, work directly."
4. Overengineering (Opus 4.5 / 4.6). Both models may add extra files, abstractions, or defensive error handling beyond what was asked. If you want minimal changes, prompt for it explicitly: "Only make changes directly requested. Don't add helpers, abstractions, or error handling for scenarios that can't happen."
5. LaTeX math output (Opus 4.6). Opus 4.6 defaults to LaTeX (\frac{}{}, $...$) for math and technical content. If you need plain text, instruct it explicitly: "Format all math as plain text — no LaTeX, no $, no \frac{}{}. Use / for division and ^ for exponents."
6. Skipped verbal summaries (4.6 family). The 4.6 models are more concise and may skip the summary paragraph after a tool call, jumping straight to the next action. If you rely on those summaries for visibility, add: "After completing a task that involves tool use, provide a brief summary of what you did."
7. "Think" as a trigger word (Opus 4.5 with thinking disabled). When thinking is off, Opus 4.5 is particularly sensitive to the word think and may reason more than you want. Use consider, evaluate, or reason through instead.
Model-ID Rename Quick Reference
| Old string (migration source) | New string |
|---|---|
claude-opus-4-7 |
claude-opus-4-8 |
claude-opus-4-6 |
claude-opus-4-8 |
claude-opus-4-5 |
claude-opus-4-8 |
claude-opus-4-1 |
claude-opus-4-8 |
claude-opus-4-0 |
claude-opus-4-8 |
claude-sonnet-4-5 |
claude-sonnet-4-6 |
claude-sonnet-4-0 |
claude-sonnet-4-6 |
Older aliases (claude-opus-4-7, claude-opus-4-6, claude-opus-4-5, claude-sonnet-4-5, etc.) are still active and can be pinned if you need time before upgrading — see shared/models.md for the full legacy list.
Amazon Bedrock model IDs
If the code uses the AnthropicBedrockMantle client (Python anthropic[bedrock], TypeScript @anthropic-ai/bedrock-sdk, Java BedrockMantleBackend, Go bedrock.NewMantleClient, etc.) or targets https://bedrock-mantle.{region}.api.aws/anthropic, it is running on Claude in Amazon Bedrock. All breaking changes in this guide apply unchanged there — it serves the same Messages API shape — but model IDs carry an anthropic. provider prefix:
| First-party ID | Bedrock ID |
|---|---|
claude-opus-4-8 |
anthropic.claude-opus-4-8 |
claude-opus-4-7 |
anthropic.claude-opus-4-7 |
claude-haiku-4-5 |
anthropic.claude-haiku-4-5 |
When migrating a Bedrock file, apply the same rename-table row as first-party, then keep/add the anthropic. prefix. Do not generate a first-party claude-* ID for a Bedrock client — it will 400.
Skip for Bedrock: the code_execution_* tool-version checklist item and the Task Budgets section — both are first-party-only features (Bedrock does not support server-side Anthropic tools or the task-budgets-2026-03-13 beta). Everything else in this guide — effort, adaptive/extended thinking, output_config.format, thinking.display, fine-grained tool streaming, token counting — is available on Bedrock.
Out of scope: the legacy Amazon Bedrock integration (
InvokeModel/ConverseAPIs with ARN-versioned IDs likeanthropic.claude-3-5-sonnet-20241022-v2:0) uses a different request shape and model-ID format. This guide does not cover it; WebFetch the Bedrock page inshared/live-sources.mdif the user is migrating between the two Bedrock integrations.
Claude Platform on AWS
If the code uses AnthropicAWS / AnthropicAws / anthropicaws.NewClient / AnthropicAwsClient (or targets https://aws-external-anthropic.{region}.api.aws), it is running on Claude Platform on AWS — Anthropic-operated, same-day API parity. Model IDs are bare first-party strings; apply the rename table above verbatim and every breaking-change section in this guide unchanged. There is nothing to skip. Do not add an anthropic. prefix (that's Amazon Bedrock, a separate offering). See shared/claude-platform-on-aws.md for client/auth details.
Migration Checklist
Every item is tagged: [BLOCKS] items cause a 400 error, infinite loop, silent timeout, or wrong tool selection if missed — apply these as code edits, not as suggestions. [TUNE] items are quality/cost adjustments.
For each file that calls messages.create() / equivalent SDK method:
- [BLOCKS] Update the
model=string to the new alias - [BLOCKS] Replace
budget_tokenswiththinking={"type": "adaptive"}(deprecated on Opus 4.6 / Sonnet 4.6) - [BLOCKS] Move
formatfrom top-leveloutput_formatintooutput_config.format - [BLOCKS] Remove any assistant-turn prefills if targeting Opus 4.6 or Sonnet 4.6 (see the prefill replacement table)
- [BLOCKS] Switch to streaming if
max_tokens > ~16000(otherwise SDK HTTP timeout) - [TUNE] Verify tool-input handling parses JSON rather than raw-string-matching the serialized input (4.6 may escape Unicode / forward slashes differently; most SDKs already expose
block.inputas a parsed object) - [TUNE] Set
output_config={"effort": "..."}explicitly — especially when moving Sonnet 4.5 → Sonnet 4.6 (4.6 defaults tohigh) - [TUNE] Remove GA beta headers:
effort-2025-11-24,fine-grained-tool-streaming-2025-05-14,token-efficient-tools-2025-02-19,output-128k-2025-02-19; removeinterleaved-thinking-2025-05-14once on adaptive thinking - [TUNE] Switch
client.beta.messages.create(...)→client.messages.create(...)once all betas are removed - [TUNE] Review system prompt for aggressive tool language (
CRITICAL:,MUST,If in doubt) and dial it back
Extra items when coming from 3.x / 4.0 / 4.1:
- [BLOCKS] Remove either
temperatureortop_p(passing both 400s on Claude 4+) - [BLOCKS] Update text-editor tool
typetotext_editor_20250728 - [BLOCKS] Update text-editor tool
nametostr_replace_based_edit_tool— changing only thetypeand keepingname: "str_replace_editor"returns a 400 - [BLOCKS] Update code-execution tool to
code_execution_20250825 - [BLOCKS] Delete any
undo_editcommand call sites - [TUNE] Add handling for
stop_reason == "refusal" - [TUNE] Add handling for
stop_reason == "model_context_window_exceeded"(4.5+) - [TUNE] Verify tool-param string matching tolerates trailing newlines (preserved on 4.5+)
- [TUNE] If moving to Haiku 4.5: review rate-limit tier (separate pool from Haiku 3.x)
Verification:
- Run one test request and inspect
response.stop_reason,response.usage, and whether tool-use / thinking behavior matches expectations
For cached prompts: the render order and hash inputs did not change, so existing cache_control breakpoints keep working. However, changing the model string invalidates the existing cache — the first request on the new model will write the cache fresh.
Migrating to Opus 4.7
Model ID
claude-opus-4-7is authoritative as written here. When the user asks to migrate to Opus 4.7, writemodel="claude-opus-4-7"exactly. Do not WebFetch to verify — this guide is the source of truth for migration target IDs. The corresponding entry exists inshared/models.md.
Claude Opus 4.7 was Anthropic's most capable model at its launch and is now the previous-generation Opus (Opus 4.8 is current — see Migrating to Opus 4.8 below). It is highly autonomous and performs exceptionally well on long-horizon agentic work, knowledge work, vision tasks, and memory tasks. This section summarizes everything that was new at the 4.7 launch and remains the layered breaking-change path for callers coming from Opus 4.6 or older. It is layered on top of the 4.6 migration above — if the caller is jumping from Opus 4.5 or older, apply the 4.6 changes first, then this section, then the 4.8 section.
TL;DR for someone already on Opus 4.6: update the model ID to claude-opus-4-7, strip any remaining budget_tokens and sampling parameters (both 400 on Opus 4.7), give max_tokens extra headroom and re-baseline with count_tokens() against the new model, opt back into thinking.display: "summarized" if reasoning is surfaced to users, and re-tune effort — it matters more on 4.7 than on any prior Opus.
Breaking changes (will 400 on Opus 4.7)
Extended thinking removed.
thinking: {type: "enabled", budget_tokens: N} is no longer supported on Claude Opus 4.7 or later models and returns a 400 error. Switch to adaptive thinking (thinking: {type: "adaptive"}) and use the effort parameter to control thinking depth. Adaptive thinking is off by default on Claude Opus 4.7: requests with no thinking field run without thinking, matching Opus 4.6 behavior. Set thinking: {type: "adaptive"} explicitly to enable it.
# Before (Opus 4.6)
client.messages.create(
model="claude-opus-4-6",
max_tokens=64000,
thinking={"type": "enabled", "budget_tokens": 32000},
messages=[{"role": "user", "content": "..."}],
)
# After (Opus 4.7)
client.messages.create(
model="claude-opus-4-7",
max_tokens=64000,
thinking={"type": "adaptive"},
output_config={"effort": "high"}, # or "max", "xhigh", "medium", "low"
messages=[{"role": "user", "content": "..."}],
)
If the caller wasn't using extended thinking, no change is required — thinking is off by default, or can be set explicitly with thinking={"type": "disabled"}.
Delete budget_tokens plumbing entirely. For the replacement effort value, see Choosing an effort level on Opus 4.7 below — there is no exact 1:1 mapping from budget_tokens.
Sampling parameters removed.
The temperature, top_p, and top_k parameters are no longer accepted on Claude Opus 4.7. Requests that include them return a 400 error. Remove these fields from your request payloads. Prompting is the recommended way to guide model behavior on Claude Opus 4.7. If you were using temperature = 0 for determinism, note that it never guaranteed identical outputs on prior models.
# Before — errors on Opus 4.7
client.messages.create(temperature=0.7, top_p=0.9, ...)
# After
client.messages.create(...) # no sampling params
- If the intent was determinism — use
effort: "low"with a tighter prompt. - If the intent was creative variance — the prompt replacement depends on the use case; ask the user how they want variance elicited. If you can't ask, add a use-case-appropriate instruction along the lines of "choose something off-distribution and interesting" — e.g. for text generation, "Vary your phrasing and structure across responses"; for frontend/design, use the propose-4-directions approach under Design and frontend coding below.
Choosing an effort level on Opus 4.7
budget_tokens controlled how much to think; effort controls how much to think and act, so there is no exact 1:1 mapping. Use xhigh for best results in coding and agentic use cases, and a minimum of high for most intelligence-sensitive use cases. Experiment with other levels to further tune token usage and intelligence:
| Level | Use when | Notes |
|---|---|---|
max |
Intelligence-demanding tasks worth testing at the ceiling | Can deliver gains in some use cases but may show diminishing returns from increased token usage; can be prone to overthinking |
xhigh |
Most coding and agentic use cases | The best setting for these; used as the default in Claude Code |
high |
Intelligence-sensitive use cases generally | Balances token usage and intelligence; recommended minimum for most intelligence-sensitive work |
medium |
Cost-sensitive use cases that need to reduce token usage while trading off intelligence | |
low |
Short, scoped tasks and latency-sensitive workloads that are not intelligence-sensitive |
Silent default changes (no error, but behavior differs)
Thinking content omitted by default.
Thinking blocks still appear in the response stream on Claude Opus 4.7, 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 to return summarized thinking text. To restore summarized thinking content on Claude Opus 4.7, set thinking.display to "summarized". The block-field name is unchanged — it is still block.thinking on a thinking-type block; do not rename it.
Detect this: any code that reads block.thinking (or equivalent) from a thinking-type block and renders it in a UI, log, or trace. The fix is the request parameter, not the response handling — add display: "summarized" to the thinking parameter:
thinking={"type": "adaptive", "display": "summarized"} # "display" is new on Opus 4.7; values: "omitted" (default) | "summarized"
The default is "omitted" on Claude Opus 4.7. If thinking content was never surfaced anywhere, no change needed. If your product streams reasoning to users, the new default appears as a long pause before output begins; set display: "summarized" to restore visible progress during thinking.
Updated token counting.
Claude Opus 4.7 and Claude Opus 4.6 count tokens differently. The same input text produces a higher token count on Claude Opus 4.7 than on Claude Opus 4.6, and /v1/messages/count_tokens will return a different number of tokens for Claude Opus 4.7 than it did for Claude Opus 4.6. The token efficiency of Claude Opus 4.7 can vary by workload shape. Prompting interventions, task_budget, and effort can help control costs and ensure appropriate token usage. Keep in mind that these controls may trade off model intelligence. Update your max_tokens parameters to give additional headroom, including compaction triggers. Claude Opus 4.7 provides a 1M context window at standard API pricing with no long-context premium.
What else to check:
- Client-side token estimators (tiktoken-style approximations) calibrated against 4.6
- Cost calculators that multiply tokens by a fixed per-token rate
- Rate-limit retry thresholds keyed to measured token counts
Re-baseline by re-running client.messages.count_tokens() against claude-opus-4-7 on a representative sample of the caller's prompts. Do not apply a blanket multiplier. For cost-sensitive workloads, consider reducing effort by one level (e.g. high → medium). For agentic loops, consider adopting Task Budgets (below).
New feature: Task Budgets (beta)
Opus 4.7 introduces task budgets — tell Claude how many tokens it has for a full agentic loop (thinking + tool calls + final output). The model sees a running countdown and uses it to prioritize work and wrap up gracefully as the budget is consumed.
This is a suggestion the model is aware of, not a hard cap. It is distinct from max_tokens, which remains the enforced per-response limit and is not surfaced to the model. Use task_budget when you want the model to self-moderate; use max_tokens as a hard ceiling to cap usage.
Requires beta header task-budgets-2026-03-13:
client.beta.messages.create(
betas=["task-budgets-2026-03-13"],
model="claude-opus-4-7",
max_tokens=64000,
thinking={"type": "adaptive"},
output_config={
"effort": "high",
"task_budget": {"type": "tokens", "total": 128000},
},
messages=[...],
)
Set a generous budget for open-ended agentic tasks and tighten it for latency-sensitive ones. Minimum task_budget.total is 20,000 tokens. If the budget is too restrictive for the task, the model may complete it less thoroughly, referencing its budget as the constraint. Do not add task_budget during a migration unless you are sure the budget value is right — if you can run the workload and measure, do so; otherwise ask the user for the value rather than guessing. This is the primary lever for offsetting the token-counting shift on agentic workloads.
Capability improvements
High-resolution vision. Opus 4.7 is the first Claude model with high-resolution image support. Maximum image resolution is 2576 pixels on the long edge (up from 1568px on Opus 4.6 and prior). This unlocks gains on vision-heavy workloads, especially computer use and screenshot/artifact/document understanding. Coordinates returned by the model now map 1:1 to actual image pixels, so no scale-factor math is needed.
High-res support is automatic on Opus 4.7 — no beta header, no client-side opt-in required. The model accepts larger inputs and returns pixel-accurate coordinates out of the box.
Token cost. Full-resolution images on Opus 4.7 can use up to ~3× more image tokens than on prior models (up to ~4784 tokens per image, vs. the previous ~1,600-token cap). If the extra fidelity isn't needed, downsample client-side before sending to control cost — but do not add downsampling by default during a migration. If you're not sure whether the pipeline needs the fidelity, ask the user rather than guessing. Use count_tokens() on representative images on Opus 4.7 to re-baseline before reacting to any measured cost shift.
Beyond resolution, Opus 4.7 also improves on low-level perception (pointing, measuring, counting) and natural-image bounding-box localization and detection.
Knowledge work. Meaningful gains on tasks where the model visually verifies its own output — .docx redlining, .pptx editing, and programmatic chart/figure analysis (e.g. pixel-level data transcription via image-processing libraries). If prompts have scaffolding like "double-check the slide layout before returning", try removing it and re-baselining.
Memory. Opus 4.7 is better at writing and using file-system-based memory. If an agent maintains a scratchpad, notes file, or structured memory store across turns, that agent should improve at jotting down notes to itself and leveraging its notes in future tasks.
User-facing progress updates. Opus 4.7 provides more regular, higher-quality interim updates during long agentic traces. If the system prompt has scaffolding like "After every 3 tool calls, summarize progress", try removing it to avoid excessive user-facing text. If the length or contents of Opus 4.7's updates are not well-calibrated to your use case, explicitly describe what these updates should look like in the prompt and provide examples.
Real-time cybersecurity safeguards
Requests that involve prohibited or high-risk topics may lead to refusals.
Fast Mode: not available on Opus 4.7
Opus 4.7 does not have a Fast Mode variant. Opus 4.6 Fast remains supported. Only surface this if the caller's code actually uses a Fast Mode model string (e.g. claude-opus-4-6-fast); if the word "fast" does not appear in the code, say nothing about Fast Mode.
When you see model="claude-opus-4-6-fast" (or similar), the migration edit is:
# Opus 4.7 has no Fast Mode — keeping on 4.6 Fast (caller's choice to switch to standard Opus 4.7).
model="claude-opus-4-6-fast",
That is: leave the model string unchanged, add the comment above it, and tell the user their two options — (a) stay on Opus 4.6 Fast, which remains supported, or (b) move latency-tolerant traffic to standard Opus 4.7 for the intelligence gain. Do not rewrite the model string to claude-opus-4-7 yourself; that silently trades latency for intelligence, which is the caller's decision.
Behavioral shifts (prompt-tunable)
These don't break anything, but prompts tuned for Opus 4.6 may land differently. Opus 4.7 is more steerable than 4.6, so small prompt nudges usually close the gap.
More literal instruction following. Claude Opus 4.7 interprets prompts more literally and explicitly than Claude Opus 4.6, particularly at lower effort levels. It will not silently generalize an instruction from one item to another, and it will not infer requests you didn't make. The upside of this literalism is precision and less thrash. It generally performs better for API use cases with carefully tuned prompts, structured extraction, and pipelines where you want predictable behavior. A prompt and harness review may be especially helpful for migration to Claude Opus 4.7.
Verbosity calibrates to task complexity. Opus 4.7 scales response length to how complex it judges the task to be, rather than defaulting to a fixed verbosity — shorter answers on simple lookups, much longer on open-ended analysis. If the product depends on a particular length or style, tune the prompt explicitly. To reduce verbosity:
"Provide concise, focused responses. Skip non-essential context, and keep examples minimal."
If you see specific kinds of over-verbosity (e.g. over-explaining), add instructions targeting those. Positive examples showing the desired level of concision tend to be more effective than negative examples or instructions telling the model what not to do. Do not assume existing "be concise" instructions should be removed — test first.
Tone and writing style. Opus 4.7 is more direct and opinionated, with less validation-forward phrasing and fewer emoji than Opus 4.6's warmer style. As with any new model, prose style on long-form writing may shift. If the product relies on a specific voice, re-evaluate style prompts against the new baseline. If a warmer or more conversational voice is wanted, specify it:
"Use a warm, collaborative tone. Acknowledge the user's framing before answering."
effort matters more than on any prior Opus. Opus 4.7 respects effort levels more strictly, especially at the low end. At low and medium it scopes work to what was asked rather than going above and beyond — good for latency and cost, but on moderate tasks at low there is some risk of under-thinking.
- If shallow reasoning shows up on complex problems, raise
efforttohighorxhighrather than prompting around it. - If
effortmust staylowfor latency, add targeted guidance: "This task involves multi-step reasoning. Think carefully through the problem before responding." - At
xhighormax, set a largemax_tokensso the model has room to think and act across tool calls and subagents. Start at 64K and tune from there. (xhighis a new effort level on Opus 4.7, betweenhighandmax.)
Adaptive-thinking triggering is also steerable. If the model thinks more often than wanted — which can happen with large or complex system prompts — add: "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."
Uses tools less often by default. Opus 4.7 tends to use tools less often than 4.6 and to use reasoning more. This produces better results in most cases, but for products that rely on tools (search/retrieval, function-calling, computer-use steps), it can drop tool-use rate. Two levers:
- Raise
effort—highorxhighshow substantially more tool usage in agentic search and coding, and are especially useful for knowledge work. - Prompt for it — be explicit in tool descriptions or the system prompt about when and how to use the tool, and encourage the model to err on the side of using it more often:
"When the answer depends on information not present in the conversation, you MUST call the
searchtool before answering — do not answer from prior knowledge."
Fewer subagents by default. Opus 4.7 tends to spawn fewer subagents than 4.6. This is steerable — give explicit guidance on when delegation is desirable. For a coding agent, for example:
"Do NOT spawn a subagent for work you can complete directly in a single response (e.g. refactoring a function you can already see). Spawn multiple subagents in the same turn when fanning out across items or reading multiple files."
Design and frontend coding. Opus 4.7 has stronger design instincts than 4.6, with a consistent default house style: warm cream/off-white backgrounds (around #F4F1EA), serif display type (Georgia, Fraunces, Playfair), italic word-accents, and a terracotta/amber accent. This reads well for editorial, hospitality, and portfolio briefs, but will feel off for dashboards, dev tools, fintech, healthcare, or enterprise apps — and it appears in slide decks as well as web UIs.
The default is persistent. Generic instructions ("don't use cream," "make it clean and minimal") tend to shift the model to a different fixed palette rather than producing variety. Two approaches work reliably:
-
Specify a concrete alternative. The model follows explicit specs precisely — give exact hex values, typefaces, and layout constraints.
-
Have the model propose options before building. This breaks the default and gives the user control:
"Before building, propose 4 distinct visual directions tailored to this brief (each as: bg hex / accent hex / typeface — one-line rationale). Ask the user to pick one, then implement only that direction."
If the caller previously relied on temperature for design variety, use approach (2) — it produces meaningfully different directions across runs.
Opus 4.7 also requires less frontend-design prompting than previous models to avoid generic "AI slop" aesthetics. Where earlier models needed a lengthy anti-slop snippet, Opus 4.7 generates distinctive, creative frontends with a much shorter nudge. This snippet works well alongside the variety approaches above:
"NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white or dark backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character. Use unique fonts, cohesive colors and themes, and animations for effects and micro-interactions."
Interactive coding products. Opus 4.7's token usage and behavior can differ between autonomous, asynchronous coding agents with a single user turn and interactive, synchronous coding agents with multiple user turns. Specifically, it tends to use more tokens in interactive settings, primarily because it reasons more after user turns. This can improve long-horizon coherence, instruction following, and coding capabilities in long interactive coding sessions, but also comes with more token usage. To maximize both performance and token efficiency in coding products, use effort: "xhigh" or "high", add autonomous features (like an auto mode), and reduce the number of human interactions required from users.
When limiting required user interactions, specify the task, intent, and relevant constraints upfront in the first human turn. Well-specified, clear, and accurate task descriptions upfront help maximize autonomy and intelligence while minimizing extra token usage after user turns — because Opus 4.7 is more autonomous than prior models, this usage pattern helps to maximize performance. In contrast, ambiguous or underspecified prompts conveyed progressively over multiple user turns tend to reduce token efficiency and sometimes performance.
Code review. Opus 4.7 is meaningfully better at finding bugs than prior models, with both higher recall and precision. However, if a code-review harness was tuned for an earlier model, it may initially show lower recall — this is likely a harness effect, not a capability regression. When a review prompt says "only report high-severity issues," "be conservative," or "don't nitpick," Opus 4.7 follows that instruction more faithfully than earlier models did: it investigates just as thoroughly, identifies the bugs, and then declines to report findings it judges to be below the stated bar. Precision rises, but measured recall can fall even though underlying bug-finding has improved.
Recommended prompt language:
"Report every issue you find, including ones you are uncertain about or consider low-severity. Do not filter for importance or confidence at this stage — a separate verification step will do that. Your goal here is coverage: it is better to surface a finding that later gets filtered out than to silently drop a bug. For each finding, include your confidence level and an estimated severity so a downstream filter can rank them."
This can be used without an actual second step, but moving confidence filtering out of the finding step often helps. If the harness has a separate verification/dedup/ranking stage, tell the model explicitly that its job at the finding stage is coverage, not filtering. If single-pass self-filtering is wanted, be concrete about the bar rather than using qualitative terms like "important" — e.g. "report any bugs that could cause incorrect behavior, a test failure, or a misleading result; only omit nits like pure style or naming preferences." Iterate on prompts against a subset of evals to validate recall or F1 gains.
Computer use. Computer use works across resolutions up to the new 2576px / 3.75MP maximum. Sending images at 1080p provides a good balance of performance and cost. For particularly cost-sensitive workloads, 720p or 1366×768 are lower-cost options with strong performance. Test to find the ideal settings for the use case; experimenting with effort can also help tune behavior.
Opus 4.7 Migration Checklist
Every item is tagged: [BLOCKS] items cause a 400 error, infinite loop, silent truncation, or empty output if missed — apply these as code edits, not as suggestions. [TUNE] items are quality/cost adjustments — surface them to the user as recommendations.
[BLOCKS] items prefixed with "If…" or "At…" are conditional. Before working through the list, scan the file for the conditions: does it surface thinking text to a UI/log? Does it set output_config.effort to "x-high" or "max"? Is it a security workload? Is it a multi-turn agentic loop? Apply only the items whose condition matches.
- [BLOCKS] Replace
thinking: {type: "enabled", budget_tokens: N}withthinking: {type: "adaptive"}+output_config.effort; deletebudget_tokensplumbing entirely - [BLOCKS] Strip
temperature,top_p,top_kfrom request construction - [BLOCKS] If thinking content is surfaced to users or stored in logs: add
thinking.display: "summarized"(otherwise the rendered text is empty) - [BLOCKS] At
output_config.effortofxhighormax: setmax_tokens≥ 64000 (otherwise output truncates mid-thought) - [TUNE] Give
max_tokensand compaction triggers extra headroom; re-runcount_tokens()againstclaude-opus-4-7on representative prompts to re-baseline (no blanket multiplier) - [TUNE] Re-baseline cost and rate-limit dashboards before reacting to measured shifts
- [TUNE] Re-evaluate
effortper route — usexhighfor coding/agentic and a minimum ofhighfor most intelligence-sensitive work; it matters more on 4.7 than any prior Opus - [TUNE] Multi-turn agentic loops: adopt the API-native Task Budgets (
output_config.task_budget, betatask-budgets-2026-03-13, minimum 20k tokens) — this is for capping cumulative spend across a loop; per-turn depth iseffort - [TUNE] Check for ambiguous or underspecified instructions that relied on 4.6 generalizing intent, and update them to be clearer or more precise — 4.7 follows them literally
- [TUNE] Tool-use workloads: add explicit when/how-to-use guidance to tool descriptions (4.7 reaches for tools less often)
- [TUNE] Verbosity: test existing length instructions before changing them — 4.7 calibrates length to task complexity, so tune for the desired output rather than assuming a direction
- [TUNE] Remove forced-progress-update scaffolding ("after every N tool calls…")
- [TUNE] Remove knowledge-work verification scaffolding ("double-check the slide layout…") and re-baseline
- [TUNE] Add tone instruction if a warmer / more conversational voice is needed; re-evaluate style prompts on writing-heavy routes
- [TUNE] Subagent tool present: add explicit spawn / don't-spawn guidance
- [TUNE] Frontend/design output: specify a concrete palette/typeface, or have the model propose 4 visual directions before building (the default cream/serif house style is persistent)
- [TUNE] Interactive coding products: use
effort: "xhigh"or"high", add autonomous features (e.g. an auto mode) to reduce human interactions, and specify task/intent/constraints upfront in the first turn - [TUNE] Code-review harnesses: remove or loosen "only report high-severity" / "be conservative" filters and have the model report every finding with confidence + severity; move filtering to a downstream step (4.7 follows severity filters more literally, which can depress measured recall)
- [TUNE] Vision-heavy pipelines (screenshots, charts, document understanding): leave images at native resolution up to 2576px long edge for the accuracy gain; remove any scale-factor math from coordinate handling (coords are now 1:1 with pixels). No beta header / opt-in needed — high-res is automatic on Opus 4.7.
- [TUNE] Computer-use pipelines: send screenshots at 1080p for a good performance/cost balance (720p or 1366×768 for cost-sensitive workloads); experiment with
effortto tune behavior - [TUNE] Cost-sensitive image pipelines: full-res images on 4.7 use up to ~4784 tokens vs ~1,600 on prior models (~3×). Downsampling client-side before upload avoids the increase, but do not downsample by default — if you're unsure whether fidelity is needed, ask the user. Re-baseline with
count_tokens()on representative images before reacting to cost shifts.
Migrating to Opus 4.8
Model ID
claude-opus-4-8is authoritative as written here. When the user asks to migrate to Opus 4.8, writemodel="claude-opus-4-8"exactly. Do not WebFetch to verify — this guide is the source of truth for migration target IDs. The corresponding entry exists inshared/models.md.
Claude Opus 4.8 is our most capable generally available model to date — highly autonomous, with state-of-the-art long-horizon agentic execution, knowledge work, and memory. It is layered on top of the Opus 4.7 migration above. If the caller is jumping from Opus 4.6 or older, apply the 4.6 and 4.7 sections first, then this one.
No new breaking changes. Opus 4.8 keeps the same request surface as Opus 4.7. The same calls that already work on 4.7 work unchanged on 4.8 — adaptive thinking only (thinking: {type: "enabled", budget_tokens: N} still 400s; use {type: "adaptive"}), sampling parameters (temperature, top_p, top_k) still rejected, last-assistant-turn prefills still 400, thinking.display still defaults to "omitted", and the low/medium/high/xhigh/max effort levels, Task Budgets (beta), and high-resolution vision all behave as on 4.7. A 4.7 → 4.8 migration is therefore the model-ID swap plus prompt re-tuning — there is no required code edit beyond the model string.
TL;DR for someone already on Opus 4.7: swap the model ID to claude-opus-4-8. Nothing else is required to avoid an error. Then re-tune prompts for the behavioral shifts: 4.8 narrates more than 4.7 (add a silence-default if you want 4.7-like terseness), writes in a warmer, less hedged voice, is more deliberate and asks more often (add autonomy guidance to claw back ask-rate), and is more conservative about reaching for search, subagents, file-based memory, and custom tools (add explicit "when to use this" triggering). For long-horizon agentic work, give the full task specification up front in one well-specified turn and run at high effort.
No new API breaking changes (inherited from 4.7)
These all carry over from Opus 4.7 unchanged — apply them only if the caller is coming from Opus 4.6 or earlier (see the Migrating to Opus 4.7 section above for the before/after and the SDK-specific syntax):
thinking: {type: "enabled", budget_tokens: N}→ 400. Usethinking: {type: "adaptive"}+output_config.effort.temperature,top_p,top_k→ 400. Remove them; steer with prompting.- Last-assistant-turn prefills → 400. Use
output_config.format(structured outputs) or a system-prompt instruction. thinking.displaydefaults to"omitted"; set"summarized"if you surface reasoning to users.
If the caller is already on Opus 4.7 and these are clean, there is nothing to change here.
New API feature: mid-session system prompts
You can deliver trusted instructions partway through a session by placing {"role": "system", ...} entries directly in the messages array — without editing the top-level system prompt and invalidating your prompt cache. Use it for things the application learns mid-session: the user delivered async context, a mode toggled (auto-approve enabled), files changed on disk, the remaining token budget dropped.
messages=[
{"role": "user", "content": [{"type": "tool_result", "tool_use_id": "...", "content": "..."}]},
{"role": "system", "content": "This project's codebase is Go. Write code in Go."},
]
Phrase these as context, not commands. State the fact and let Claude act on it; avoid override-style language ("ignore what the user said", "regardless of the user's request", "disregard the previous instruction"). Claude is trained to protect users from instructions that appear to work against them, and that protection applies to the system role too. This is a beta (anthropic-beta: mid-conversation-system-2026-04-07) and is available from Opus 4.7 onward, not 4.8-exclusive. For cache-placement details and the older-model <system-reminder> fallback, see shared/prompt-caching.md and shared/agent-design.md.
Capability improvements
Long-horizon agentic execution. Opus 4.8 is state-of-the-art at long, autonomous agentic work — complex refactors and overnight coding runs that complete without human correction. To get the most out of it, give the full task specification up front in a single well-specified initial turn and run at high effort (effort: "high" or "xhigh"). Its long-horizon coherence comes partly from reasoning more at each step; combined with a clear up-front goal, that more-intelligent planning often produces more efficient and more accurate output than prior frontier models. The "clear goal up front" principle maps to two product surfaces: in Claude Code, /goal sets direction for the run; with Managed Agents (CMA), state what "done" looks like via an Outcome (user.define_outcome with a gradeable rubric — the harness runs an iterate → grade → revise loop), see shared/managed-agents-outcomes.md.
Effort is a dimension to test, not a fixed setting. On prior models many reached for xhigh reflexively to maximize intelligence. Opus 4.8 has a higher intelligence ceiling, so start at high as the default and iterate rather than defaulting to xhigh. Sweep medium, high, and xhigh on your own eval set and weigh the intelligence ↔ latency ↔ cost tradeoff per route — the relationship isn't monotonic: higher effort up front often reduces turn count and total cost on agentic work, while for some tasks medium delivers equally good results in less time. Reserve max for extremely hard, latency-insensitive cases. The per-level effort table in the Migrating to Opus 4.7 section above applies unchanged on 4.8.
Writing voice and clarity. Testers consistently describe 4.8's prose as clearer, warmer, and less hedged than prior models, with fewer measurable AI vocal tics — especially at higher effort, where it approaches expert-level prose and structure. This is roughly the opposite direction from the 4.7 shift (4.7 was more clipped, direct, and less validation-forward). If you added style prompts to counter 4.7's terseness or to inject warmth, re-evaluate them against the new baseline before keeping them — they may now overcorrect. 4.8 is also a stronger thought partner: more thoughtful, more willing to push back, and more likely to infer the right answer from context.
Code review and debugging. Stronger real-bug finding and clearer explanations than 4.7 — one-shot fixes where 4.7 needed more, and correctly identifying intermittent flakes rather than declaring "fixed" after one clean run. The 4.7 caveat still applies: if a review harness says "only report high-severity issues" or "be conservative", 4.8 follows it literally and measured recall can drop even though underlying bug-finding improved. Tell the model to report everything and filter downstream (or review a second time) — see the Code review guidance in the 4.7 section for the recommended prompt.
Behavioral shifts (prompt-tunable)
None of these break code, but prompts tuned for Opus 4.7 may land differently. 4.8 follows instructions well, so small, explicit nudges close the gap.
Tool triggering is surface-dependent (search & knowledge). 4.8's tool-triggering is more surface-dependent than in prior models: with a system prompt present it is high-precision / low-recall — web search triggers slightly more often but runs fewer rounds per trigger, while knowledge-retrieval tools (Drive, project knowledge, connected files) trigger less often. It searches when it's confident search is needed and otherwise answers from context, which can lower research depth on tasks that need it. Recover should-search rate with an explicit search-first instruction:
<search_first> For questions where current information would change the answer (recent events, current roles or prices, version-specific behavior, or anything the user flags as time-sensitive) search before answering rather than answering from memory. For open-ended research requests, begin searching immediately; do not ask a scoping question first unless the request is genuinely ambiguous about what to research. </search_first>
Under-utilization of subagents, memory, and custom tools. Separately from search, 4.8 is conservative about reaching for capabilities that need an explicit "decide to use this" step — file-based memory, subagent delegation, custom tools. It won't reach for complex or expensive capabilities unless reasonably sure they're needed. This is steerable since 4.8 follows instructions well — say when each capability applies, not just that it exists:
"Before any task longer than a few turns, check your memory file for relevant prior context and write new findings to it as you go. When a task fans out across independent items (many files to read, many tests to run, many candidates to check), delegate to subagents rather than iterating serially."
More user-facing narration. 4.8 narrates more than 4.7 — more text between tool calls in long tool-calling sessions, and longer, more detailed end-of-task wrap-ups by default. If you previously added scaffolding to force interim status ("after every 3 tool calls, summarize progress"), remove it — 4.8 does this on its own. If the narration is too verbose for a coding agent, an explicit silence-default makes it behave like 4.7 with no loss of quality:
"Default to silence between tool calls. Only write text when you find something, change direction, or hit a blocker — one sentence each. Do not narrate routine actions ('Now I'll...', 'Let me check...', 'Looking at...'). When done: one or two sentences on the outcome. Do not recap every file or test — the user has been following along."
For knowledge-work deliverables (reports, analysis readouts), verbosity responds very well to instructions in user preferences or the user turn — expose a verbosity preference rather than hard-coding a length.
More deliberate — asks more often. 4.8 is more deliberate than prior Opus models. On minor decisions it would previously just make (a variable name, a default value, which of two equivalent approaches), it tends to pause and ask, and it often closes a completed task with "Want me to also…?" rather than doing the obvious next step or stopping cleanly. This is preferred for high-stakes or unfamiliar codebases, but bugs users when uncalibrated. Grant autonomy on the small stuff while keeping caution where it matters (in Claude Code testing this cut ask-rate by ~12 percentage points with no increase in over-reach):
"For minor choices (naming, formatting, default values, which approach among equivalents), pick a reasonable option and note it rather than asking. For scope changes or destructive actions, still ask first."
Verbose reasoning when thinking is disabled. With thinking: {type: "disabled"}, 4.8 occasionally writes longer explanations of its reasoning into the visible response, which reads as verbose when the user wants a fast, quick answer. The simplest fix is to leave adaptive thinking on — set thinking: {type: "adaptive"} (the recommended setting; it adjusts how much to think per task). Note adaptive is not on when the field is omitted — like Opus 4.7, a request with no thinking field runs without thinking, so set it explicitly. If you need thinking off for latency or cost, scope it in the system prompt:
"Respond only with your final answer. Do not include exploratory reasoning, intermediate drafts, diffs you considered but rejected, or meta-commentary about your process."
Opus 4.8 Migration Checklist
Every item is tagged: [BLOCKS] items cause a 400 error if missed; [TUNE] items are quality/cost adjustments — surface them to the user as recommendations.
For a caller already on Opus 4.7, only the first item is required; everything else is [TUNE]. The conditional [BLOCKS] item applies only when coming from Opus 4.6 or earlier.
- [BLOCKS] Update the
model=string toclaude-opus-4-8 - [BLOCKS] (only if coming from Opus 4.6 or earlier) Apply the Migrating to Opus 4.7 breaking changes first —
budget_tokens→ adaptive thinking, striptemperature/top_p/top_k, remove last-assistant-turn prefills. These already 400 on 4.7 and continue to 400 on 4.8. - [TUNE] Long-horizon / agentic work: put the full task spec in one well-specified first turn and run at
highorxhigheffort (Claude Code:/goal; Managed Agents: an Outcome with a gradeable rubric) - [TUNE] Effort: sweep
medium/high/xhighon your eval set and pick per route by the intelligence ↔ latency ↔ cost tradeoff (defaulthigh,xhighfor coding/agentic) - [TUNE] Research depth & tool use: add a search-first instruction; add explicit triggering guidance for subagents, file-based memory, and custom tools (4.8 under-reaches for these by default)
- [TUNE] Narration: remove forced-progress scaffolding ("after every N tool calls…"); add a silence-default if a coding agent is too chatty
- [TUNE] Autonomy: add small-decisions-don't-ask guidance to cut ask-rate, while keeping caution on scope changes / destructive actions
- [TUNE] Writing voice: re-evaluate style prompts added to counter 4.7's directness — 4.8 is warmer and less hedged by default; re-baseline before keeping them
- [TUNE] Code-review harnesses: keep the report-everything-filter-downstream pattern (4.8 follows "only high-severity" / "be conservative" filters literally, which can depress measured recall)
- [TUNE] Thinking-disabled paths: add a final-answer-only instruction if reasoning leaks into the visible response
- [TUNE] Consider mid-session system messages (
role:"system"inmessages, betamid-conversation-system-2026-04-07) for context the app learns mid-session, instead of rebuilding the top-level system prompt and invalidating the cache
Verify the Migration
After updating, spot-check that the new model is actually being used. Replace YOUR_TARGET_MODEL with the model string you migrated to (e.g. claude-opus-4-8, claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5) and keep the assertion prefix in sync:
YOUR_TARGET_MODEL = "claude-opus-4-8" # or "claude-opus-4-7", "claude-sonnet-4-6", "claude-haiku-4-5"
response = client.messages.create(model=YOUR_TARGET_MODEL, max_tokens=64, messages=[...])
assert response.model.startswith(YOUR_TARGET_MODEL), response.model
For rate-limit headroom changes, pricing, or capability deltas (vision, structured outputs, effort support), query the Models API:
m = client.models.retrieve(YOUR_TARGET_MODEL)
m.max_input_tokens, m.max_tokens
m.capabilities["effort"]["max"]["supported"]
See shared/models.md for the full capability lookup pattern.
Only use exact model IDs listed in this file. Never guess or construct model IDs — incorrect IDs will cause API errors. Use aliases wherever available. For the latest information, WebFetch the Models Overview URL in shared/live-sources.md, or query the Models API directly (see Programmatic Model Discovery below).
Programmatic Model Discovery
For live capability data — context window, max output tokens, feature support (thinking, vision, effort, structured outputs, etc.) — query the Models API instead of relying on the cached tables below. Use this when the user asks "what's the context window for X", "does model X support vision/thinking/effort", "which models support feature Y", or wants to select a model by capability at runtime.
m = client.models.retrieve("claude-opus-4-8")
m.id # "claude-opus-4-8"
m.display_name # "Claude Opus 4.8"
m.max_input_tokens # context window (int)
m.max_tokens # max output tokens (int)
# capabilities is an untyped nested dict — bracket access, check ["supported"] at the leaf
caps = m.capabilities
caps["image_input"]["supported"] # vision
caps["thinking"]["types"]["adaptive"]["supported"] # adaptive thinking
caps["effort"]["max"]["supported"] # effort: max (also low/medium/high)
caps["structured_outputs"]["supported"]
caps["context_management"]["compact_20260112"]["supported"]
# filter across all models — iterate the page object directly (auto-paginates); do NOT use .data
[m for m in client.models.list()
if m.capabilities["thinking"]["types"]["adaptive"]["supported"]
and m.max_input_tokens >= 200_000]
Top-level fields (id, display_name, max_input_tokens, max_tokens) are typed attributes. capabilities is a dict — use bracket access, not attribute access. The API returns the full capability tree for every model with supported: true/false at each leaf, so bracket chains are safe without .get() guards. TypeScript SDK: same method names, also auto-paginates on iteration.
Raw HTTP
curl https://api.anthropic.com/v1/models/claude-opus-4-8 \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
{
"id": "claude-opus-4-8",
"display_name": "Claude Opus 4.8",
"max_input_tokens": 1000000,
"max_tokens": 128000,
"capabilities": {
"image_input": {"supported": true},
"structured_outputs": {"supported": true},
"thinking": {"supported": true, "types": {"enabled": {"supported": false}, "adaptive": {"supported": true}}},
"effort": {"supported": true, "low": {"supported": true}, …, "max": {"supported": true}},
…
}
}
Current Models (recommended)
| Friendly Name | Alias (use this) | Full ID | Context | Max Output | Status |
|---|---|---|---|---|---|
| Claude Opus 4.8 | claude-opus-4-8 |
— | 1M | 128K | Active |
| Claude Opus 4.7 | claude-opus-4-7 |
— | 1M | 128K | Active |
| Claude Opus 4.6 | claude-opus-4-6 |
— | 1M | 128K | Active |
| Claude Sonnet 4.6 | claude-sonnet-4-6 |
- | 1M | 64K | Active |
| Claude Haiku 4.5 | claude-haiku-4-5 |
claude-haiku-4-5-20251001 |
200K | 64K | Active |
Model Descriptions
- Claude Opus 4.8 — The most capable Claude model to date — highly autonomous, state-of-the-art on long-horizon agentic work, knowledge work, and memory; clearer, warmer writing. Same API surface as Opus 4.7 (adaptive thinking only; sampling parameters and
budget_tokensremoved). 1M context window at standard API pricing (no long-context premium). Seeshared/model-migration.md→ Migrating to Opus 4.8 — a 4.7 → 4.8 move is a model-ID swap plus prompt re-tuning, no new breaking changes. - Claude Opus 4.7 — Previous-generation Opus. Highly autonomous; strong on long-horizon agentic work, knowledge work, vision, and memory. Adaptive thinking only; sampling parameters and
budget_tokensremoved. 1M context window. Seeshared/model-migration.md→ Migrating to Opus 4.7. - Claude Opus 4.6 — Older Opus. Supports adaptive thinking (recommended), 128K max output tokens (requires streaming for large outputs). 1M context window.
- Claude Sonnet 4.6 — Our best combination of speed and intelligence. Supports adaptive thinking (recommended). 1M context window. 64K max output tokens.
- Claude Haiku 4.5 — Fastest and most cost-effective model for simple tasks.
Legacy Models (still active)
| Friendly Name | Alias (use this) | Full ID | Status |
|---|---|---|---|
| Claude Opus 4.5 | claude-opus-4-5 |
claude-opus-4-5-20251101 |
Active |
| Claude Opus 4.1 | claude-opus-4-1 |
claude-opus-4-1-20250805 |
Active |
| Claude Sonnet 4.5 | claude-sonnet-4-5 |
claude-sonnet-4-5-20250929 |
Active |
Deprecated Models (retiring soon)
| Friendly Name | Alias (use this) | Full ID | Status | Retires |
|---|---|---|---|---|
| Claude Sonnet 4 | claude-sonnet-4-0 |
claude-sonnet-4-20250514 |
Deprecated | TBD |
| Claude Opus 4 | claude-opus-4-0 |
claude-opus-4-20250514 |
Deprecated | TBD |
| Claude Haiku 3 | — | claude-3-haiku-20240307 |
Deprecated | Apr 19, 2026 |
Retired Models (no longer available)
| Friendly Name | Full ID | Retired |
|---|---|---|
| Claude Sonnet 3.7 | claude-3-7-sonnet-20250219 |
Feb 19, 2026 |
| Claude Haiku 3.5 | claude-3-5-haiku-20241022 |
Feb 19, 2026 |
| Claude Opus 3 | claude-3-opus-20240229 |
Jan 5, 2026 |
| Claude Sonnet 3.5 | claude-3-5-sonnet-20241022 |
Oct 28, 2025 |
| Claude Sonnet 3.5 | claude-3-5-sonnet-20240620 |
Oct 28, 2025 |
| Claude Sonnet 3 | claude-3-sonnet-20240229 |
Jul 21, 2025 |
| Claude 2.1 | claude-2.1 |
Jul 21, 2025 |
| Claude 2.0 | claude-2.0 |
Jul 21, 2025 |
Resolving User Requests
When a user asks for a model by name, use this table to find the correct model ID:
| User says... | Use this model ID |
|---|---|
| "opus", "most powerful" | claude-opus-4-8 |
| "opus 4.8" | claude-opus-4-8 |
| "opus 4.7" | claude-opus-4-7 |
| "opus 4.6" | claude-opus-4-6 |
| "opus 4.5" | claude-opus-4-5 |
| "opus 4.1" | claude-opus-4-1 |
| "opus 4", "opus 4.0" | claude-opus-4-0 (deprecated — suggest claude-opus-4-8) |
| "sonnet", "balanced" | claude-sonnet-4-6 |
| "sonnet 4.6" | claude-sonnet-4-6 |
| "sonnet 4.5" | claude-sonnet-4-5 |
| "sonnet 4", "sonnet 4.0" | claude-sonnet-4-0 (deprecated — suggest claude-sonnet-4-6) |
| "sonnet 3.7" | Retired — suggest claude-sonnet-4-6 |
| "sonnet 3.5" | Retired — suggest claude-sonnet-4-6 |
| "haiku", "fast", "cheap" | claude-haiku-4-5 |
| "haiku 4.5" | claude-haiku-4-5 |
| "haiku 3.5" | Retired — suggest claude-haiku-4-5 |
| "haiku 3" | Deprecated — suggest claude-haiku-4-5 |
This file covers how to design prompt-building code for effective caching. For language-specific syntax, see the ## Prompt Caching section in each language's README or single-file doc.
The one invariant everything follows from
Prompt caching is a prefix match. Any change anywhere in the prefix invalidates everything after it.
The cache key is derived from the exact bytes of the rendered prompt up to each cache_control breakpoint. A single byte difference at position N — a timestamp, a reordered JSON key, a different tool in the list — invalidates the cache for all breakpoints at positions ≥ N.
Render order is: tools → system → messages. A breakpoint on the last system block caches both tools and system together.
Design the prompt-building path around this constraint. Get the ordering right and most caching works for free. Get it wrong and no amount of cache_control markers will help.
Workflow for optimizing existing code
When asked to add or optimize caching:
- Trace the prompt assembly path. Find where
system,tools, andmessagesare constructed. Identify every input that flows into them. - Classify each input by stability:
- Never changes → belongs early in the prompt, before any breakpoint
- Changes per-session → belongs after the global prefix, cache per-session
- Changes per-turn → belongs at the end, after the last breakpoint
- Changes per-request (timestamps, UUIDs, random IDs) → eliminate or move to the very end
- Check rendered order matches stability order. Stable content must physically precede volatile content. If a timestamp is interpolated into the system prompt header, everything after it is uncacheable regardless of markers.
- Place breakpoints at stability boundaries. See placement patterns below.
- Audit for silent invalidators. See anti-patterns table.
Placement patterns
Large system prompt shared across many requests
Put a breakpoint on the last system text block. If there are tools, they render before system — the marker on the last system block caches tools + system together.
"system": [
{"type": "text", "text": "<large shared prompt>", "cache_control": {"type": "ephemeral"}}
]
Multi-turn conversations
Put a breakpoint on the last content block of the most-recently-appended turn. Each subsequent request reuses the entire prior conversation prefix. Earlier breakpoints remain valid read points, so hits accrue incrementally as the conversation grows.
// Last content block of the last user turn
messages[-1].content[-1].cache_control = {"type": "ephemeral"}
Shared prefix, varying suffix
Many requests share a large fixed preamble (few-shot examples, retrieved docs, instructions) but differ in the final question. Put the breakpoint at the end of the shared portion, not at the end of the whole prompt — otherwise every request writes a distinct cache entry and nothing is ever read.
"messages": [{"role": "user", "content": [
{"type": "text", "text": "<shared context>", "cache_control": {"type": "ephemeral"}},
{"type": "text", "text": "<varying question>"} // no marker — differs every time
]}]
Mid-conversation system messages
Beta, model-gated. When an operator instruction arrives mid-conversation — a mode switch, updated context, dynamically injected state — send it as {"role": "system", "content": "..."} appended to messages[], rather than editing top-level system. Editing top-level system changes the prefix ahead of the entire conversation history, so every cached turn is re-processed uncached; a role: "system" message sits after the history and leaves the cached prefix intact.
// Top-level system stays byte-identical; new instruction goes after the cached history
"system": [{"type": "text", "text": "<stable core>", "cache_control": {"type": "ephemeral"}}],
"messages": [
...history,
{"role": "user", "content": "..."},
{"role": "system", "content": "Terse mode enabled — keep responses under 40 words."}
]
This is also the prompt-injection-safe replacement for embedding operator instructions as text inside a user turn (the <system-reminder> pattern): both have the same caching profile, but role: "system" is the non-spoofable operator channel, whereas text inside user/tool content can be forged by anything that writes to user-visible input.
Requires anthropic-beta: mid-conversation-system-2026-04-07. Must follow a role: "user" message (or an assistant message ending in a server tool result); cannot be messages[0] — use top-level system for the initial prompt. Content is text-only. Model-gated — unsupported models return a 400 (BadRequestError: role 'system' is not supported on this model); catch that error and fall back to putting the instruction in a user-turn <system-reminder> block.
Prompts that change from the beginning every time
Don't cache. If the first 1K tokens differ per request, there is no reusable prefix. Adding cache_control only pays the cache-write premium with zero reads. Leave it off.
Architectural guidance
These are the decisions that matter more than marker placement. Fix these first.
Keep the system prompt frozen. Don't interpolate "current date: X", "mode: Y", "user name: Z" into the system prompt — those sit at the front of the prefix and invalidate everything downstream. Inject dynamic context later in messages instead — as a {"role": "system", ...} message where supported (see § Mid-conversation system messages above), or as text in a user message otherwise. A message at turn 5 invalidates nothing before turn 5.
Don't change tools or model mid-conversation. Tools render at position 0; adding, removing, or reordering a tool invalidates the entire cache. Same for switching models (caches are model-scoped). If you need "modes", don't swap the tool set — give Claude a tool that records the mode transition, or pass the mode as message content. Serialize tools deterministically (sort by name).
Fork operations must reuse the parent's exact prefix. Side computations (summarization, compaction, sub-agents) often spin up a separate API call. If the fork rebuilds system / tools / model with any difference, it misses the parent's cache entirely. Copy the parent's system, tools, and model verbatim, then append fork-specific content at the end.
Silent invalidators
When reviewing code, grep for these inside anything that feeds the prompt prefix:
| Pattern | Why it breaks caching |
|---|---|
datetime.now() / Date.now() / time.time() in system prompt |
Prefix changes every request |
uuid4() / crypto.randomUUID() / request IDs early in content |
Same — every request is unique |
json.dumps(d) without sort_keys=True / iterating a set |
Non-deterministic serialization → prefix bytes differ |
| f-string interpolating session/user ID into system prompt | Per-user prefix; no cross-user sharing |
Conditional system sections (if flag: system += ...) |
Every flag combination is a distinct prefix |
tools=build_tools(user) where set varies per user |
Tools render at position 0; nothing caches across users |
Fix by moving the dynamic piece after the last breakpoint, making it deterministic, or deleting it if it's not load-bearing.
API reference
"cache_control": {"type": "ephemeral"} // 5-minute TTL (default)
"cache_control": {"type": "ephemeral", "ttl": "1h"} // 1-hour TTL
- Max 4
cache_controlbreakpoints per request. - Goes on any content block: system text blocks, tool definitions, message content blocks (
text,image,tool_use,tool_result,document). - Top-level
cache_controlonmessages.create()auto-places on the last cacheable block — simplest option when you don't need fine-grained placement. - Minimum cacheable prefix is model-dependent. Shorter prefixes silently won't cache even with a marker — no error, just
cache_creation_input_tokens: 0:
| Model | Minimum |
|---|---|
| Opus 4.8, Opus 4.7, Opus 4.6, Opus 4.5, Haiku 4.5 | 4096 tokens |
| Sonnet 4.6, Haiku 3.5, Haiku 3 | 2048 tokens |
| Sonnet 4.5, Sonnet 4.1, Sonnet 4, Sonnet 3.7 | 1024 tokens |
A 3K-token prompt caches on Sonnet 4.5 but silently won't on Opus 4.8.
Economics: Cache reads cost ~0.1× base input price. Cache writes cost 1.25× for 5-minute TTL, 2× for 1-hour TTL. Break-even depends on TTL: with 5-minute TTL, two requests break even (1.25× + 0.1× = 1.35× vs 2× uncached); with 1-hour TTL, you need at least three requests (2× + 0.2× = 2.2× vs 3× uncached). The 1-hour TTL keeps entries alive across gaps in bursty traffic, but the doubled write cost means it needs more reads to pay off.
Verifying cache hits
The response usage object reports cache activity:
| Field | Meaning |
|---|---|
cache_creation_input_tokens |
Tokens written to cache this request (you paid the ~1.25× write premium) |
cache_read_input_tokens |
Tokens served from cache this request (you paid ~0.1×) |
input_tokens |
Tokens processed at full price (not cached) |
If cache_read_input_tokens is zero across repeated requests with identical prefixes, a silent invalidator is at work — diff the rendered prompt bytes between two requests to find it.
input_tokens is the uncached remainder only. Total prompt size = input_tokens + cache_creation_input_tokens + cache_read_input_tokens. If your agent ran for hours but input_tokens shows 4K, the rest was served from cache — check the sum, not the single field.
Language-specific access: response.usage.cache_read_input_tokens (Python/TS/Ruby), $message->usage->cacheReadInputTokens (PHP), resp.Usage.CacheReadInputTokens (Go/C#), .usage().cacheReadInputTokens() (Java).
Invalidation hierarchy
Not every parameter change invalidates everything. The API has three cache tiers, and changes only invalidate their own tier and below:
| Change | Tools cache | System cache | Messages cache |
|---|---|---|---|
| Tool definitions (add/remove/reorder) | ❌ | ❌ | ❌ |
| Model switch | ❌ | ❌ | ❌ |
speed, web-search, citations toggle |
✅ | ❌ | ❌ |
| System prompt content | ✅ | ❌ | ❌ |
tool_choice, images, thinking enable/disable |
✅ | ✅ | ❌ |
| Message content | ✅ | ✅ | ❌ |
Implication: you can change tool_choice per-request or toggle thinking without losing the tools+system cache. Don't over-worry about these — only tool-definition and model changes force a full rebuild.
20-block lookback window
Each breakpoint walks backward at most 20 content blocks to find a prior cache entry. If a single turn adds more than 20 blocks (common in agentic loops with many tool_use/tool_result pairs), the next request's breakpoint won't find the previous cache and silently misses.
Fix: place an intermediate breakpoint every ~15 blocks in long turns, or put the marker on a block that's within 20 of the previous turn's last cached block.
Concurrent-request timing
A cache entry becomes readable only after the first response begins streaming. N parallel requests with identical prefixes all pay full price — none can read what the others are still writing.
For fan-out patterns: send 1 request, await the first streamed token (not the full response), then fire the remaining N−1. They'll read the cache the first one just wrote.
Pre-warming the cache
To eliminate the cache-miss latency on the first real request, send a max_tokens: 0 request at startup (or on an interval). The API runs prefill — writing the cache at your cache_control breakpoint — and returns immediately with content: [], stop_reason: "max_tokens", and a populated usage block (zero output tokens billed; normal cache-write charge on cache_creation_input_tokens).
When to pre-warm — pre-warming trades a cache-write charge now for lower TTFT on the next real request. It's worth it when all three hold: (a) first-request latency is user-visible (chat/voice/interactive — not background jobs), (b) the shared prefix is large enough that a cold write is noticeably slow, and (c) there's a moment before traffic to fire it — app startup, worker boot, post-deploy, start of a scheduled window.
| Skip pre-warming when… | Because |
|---|---|
| Traffic is continuous (requests ≤ TTL apart) | The first real request warms the cache and every subsequent one hits it; a separate warm call is a pure extra write |
| The prefix is small or below the cacheable minimum | The cold-write penalty is negligible |
| The prefix varies per request/user | Nothing shared to pre-warm |
| You'd pre-warm many distinct prefixes speculatively | Each is a ~1.25× write; cost can exceed the latency you save |
Scheduled re-warms: only needed when traffic has gaps longer than the TTL. If real requests arrive more often than every 5 minutes, they keep the cache warm on their own — don't add an interval re-warm. For bursty traffic with long idle gaps, either re-warm just under the TTL or switch to ttl: "1h" and re-warm less often.
client.messages.create(
model="claude-opus-4-8",
max_tokens=0,
system=[{
"type": "text",
"text": SYSTEM_PROMPT,
"cache_control": {"type": "ephemeral"},
}],
messages=[{"role": "user", "content": "warmup"}],
)
Breakpoint placement: put cache_control on the last block shared with the real request (the system prompt or tool definitions) — not on the placeholder user message, and not via top-level automatic caching (which would key the cache to the placeholder). The placeholder can be any non-whitespace string; it's read during prefill but never answered.
Rejected combinations: max_tokens: 0 is an invalid_request_error with stream: true, thinking.type: "enabled", output_config.format, tool_choice of {"type":"tool"} or {"type":"any"}, or inside a Message Batches request.
TTL still applies — re-warm at least every 5 minutes for the default cache, or use the 1-hour TTL. This replaces the older max_tokens: 1 workaround (no single-token reply to discard, no output tokens billed, intent is unambiguous).
This file covers the conceptual foundations of tool use with the Claude API. For language-specific code examples, see the python/, typescript/, or other language folders. For decision heuristics on which tools to expose, how to manage context in long-running agents, and caching strategy, see agent-design.md.
User-Defined Tools
Tool Definition Structure
Note: When using the Tool Runner (beta), tool schemas are generated automatically from your function signatures (Python), Zod schemas (TypeScript), annotated classes (Java),
jsonschemastruct tags (Go), orBaseToolsubclasses (Ruby). The raw JSON schema format below is for the manual approach — including PHP'sBetaRunnableTool, which wraps a run closure around a hand-written schema — or SDKs without tool runner support.
Each tool requires a name, description, and JSON Schema for its inputs:
{
"name": "get_weather",
"description": "Get current weather for a location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City and state, e.g., San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Temperature unit"
}
},
"required": ["location"]
}
}
Best practices for tool definitions:
- Use clear, descriptive names (e.g.,
get_weather,search_database,send_email) - Write detailed descriptions — Claude uses these to decide when to use the tool
- Include descriptions for each property
- Use
enumfor parameters with a fixed set of values - Mark truly required parameters in
required; make others optional with defaults
Tool Choice Options
Control when Claude uses tools:
| Value | Behavior |
|---|---|
{"type": "auto"} |
Claude decides whether to use tools (default) |
{"type": "any"} |
Claude must use at least one tool |
{"type": "tool", "name": "..."} |
Claude must use the specified tool |
{"type": "none"} |
Claude cannot use tools |
Any tool_choice value can also include "disable_parallel_tool_use": true to force Claude to use at most one tool per response. By default, Claude may request multiple tool calls in a single response.
Tool Runner vs Manual Loop
Tool Runner (Recommended): The SDK's tool runner handles the agentic loop automatically — it calls the API, detects tool use requests, executes your tool functions, feeds results back to Claude, and repeats until Claude stops calling tools. Available in Python, TypeScript, Java, Go, Ruby, and PHP SDKs (beta). The Python SDK also provides MCP conversion helpers (anthropic.lib.tools.mcp) to convert MCP tools, prompts, and resources for use with the tool runner — see python/claude-api/tool-use.md for details.
Manual Agentic Loop: Use when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval). Loop until stop_reason == "end_turn", always append the full response.content to preserve tool_use blocks, and ensure each tool_result includes the matching tool_use_id.
Stop reasons for server-side tools: When using server-side tools (code execution, web search, etc.), the API runs a server-side sampling loop. If this loop reaches its default limit of 10 iterations, the response will have stop_reason: "pause_turn". To continue, re-send the user message and assistant response and make another API request — the server will resume where it left off. Do NOT add an extra user message like "Continue." — the API detects the trailing server_tool_use block and knows to resume automatically.
# Handle pause_turn in your agentic loop
if response.stop_reason == "pause_turn":
messages = [
{"role": "user", "content": user_query},
{"role": "assistant", "content": response.content},
]
# Make another API request — server resumes automatically
response = client.messages.create(
model="claude-opus-4-8", messages=messages, tools=tools
)
Set a max_continuations limit (e.g., 5) to prevent infinite loops. For the full guide, see: https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons
Security: The tool runner executes your tool functions automatically whenever Claude requests them. For tools with side effects (sending emails, modifying databases, financial transactions), validate inputs within your tool functions and consider requiring confirmation for destructive operations. Use the manual agentic loop if you need human-in-the-loop approval before each tool execution.
Handling Tool Results
When Claude uses a tool, the response contains a tool_use block. You must:
- Execute the tool with the provided input
- Send the result back in a
tool_resultmessage - Continue the conversation
Error handling in tool results: When a tool execution fails, set "is_error": true and provide an informative error message. Claude will typically acknowledge the error and either try a different approach or ask for clarification.
Multiple tool calls: Claude can request multiple tools in a single response. Handle them all before continuing — send all results back in a single user message.
Server-Side Tools: Code Execution
The code execution tool lets Claude run code in a secure, sandboxed container. Unlike user-defined tools, server-side tools run on Anthropic's infrastructure — you don't execute anything client-side. Just include the tool definition and Claude handles the rest.
Key Facts
- Runs in an isolated container (1 CPU, 5 GiB RAM, 5 GiB disk)
- No internet access (fully sandboxed)
- Python 3.11 with data science libraries pre-installed
- Containers persist for 30 days and can be reused across requests
- Free when used with web search/web fetch tools; otherwise $0.05/hour after 1,550 free hours/month per organization
Tool Definition
The tool requires no schema — just declare it in the tools array:
{
"type": "code_execution_20260120",
"name": "code_execution"
}
Claude automatically gains access to bash_code_execution (run shell commands) and text_editor_code_execution (create/view/edit files).
Pre-installed Python Libraries
- Data science: pandas, numpy, scipy, scikit-learn, statsmodels
- Visualization: matplotlib, seaborn
- File processing: openpyxl, xlsxwriter, pillow, pypdf, pdfplumber, python-docx, python-pptx
- Math: sympy, mpmath
- Utilities: tqdm, python-dateutil, pytz, sqlite3
Additional packages can be installed at runtime via pip install.
Supported File Types for Upload
| Type | Extensions |
|---|---|
| Data | CSV, Excel (.xlsx/.xls), JSON, XML |
| Images | JPEG, PNG, GIF, WebP |
| Text | .txt, .md, .py, .js, etc. |
Container Reuse
Reuse containers across requests to maintain state (files, installed packages, variables). Extract the container_id from the first response and pass it to subsequent requests.
Response Structure
The response contains interleaved text and tool result blocks:
text— Claude's explanationserver_tool_use— What Claude is doingbash_code_execution_tool_result— Code execution output (checkreturn_codefor success/failure)text_editor_code_execution_tool_result— File operation results
Security: Always sanitize filenames with
os.path.basename()/path.basename()before writing downloaded files to disk to prevent path traversal attacks. Write files to a dedicated output directory.
Server-Side Tools: Web Search and Web Fetch
Web search and web fetch let Claude search the web and retrieve page content. They run server-side — just include the tool definitions and Claude handles queries, fetching, and result processing automatically.
Tool Definitions
[
{ "type": "web_search_20260209", "name": "web_search" },
{ "type": "web_fetch_20260209", "name": "web_fetch" }
]
Dynamic Filtering (Opus 4.8 / Opus 4.7 / Opus 4.6 / Sonnet 4.6)
The web_search_20260209 and web_fetch_20260209 versions support dynamic filtering — Claude writes and executes code to filter search results before they reach the context window, improving accuracy and token efficiency. Dynamic filtering is built into these tool versions and activates automatically; you do not need to separately declare the code_execution tool or pass any beta header.
{
"tools": [
{ "type": "web_search_20260209", "name": "web_search" },
{ "type": "web_fetch_20260209", "name": "web_fetch" }
]
}
Without dynamic filtering, the previous web_search_20250305 version is also available.
Note: Only include the standalone
code_executiontool when your application needs code execution for its own purposes (data analysis, file processing, visualization) independent of web search. Including it alongside_20260209web tools creates a second execution environment that can confuse the model.
Server-Side Tools: Programmatic Tool Calling
With standard tool use, each tool call is a round trip: Claude calls, the result enters Claude's context, Claude reasons, then calls the next tool. Chained calls accumulate latency and tokens — most of that intermediate data is never needed again.
Programmatic tool calling lets Claude compose those calls into a script. The script runs in the code execution container; when it invokes a tool, the container pauses, the call executes, and the result returns to the running code (not to Claude's context). The script processes it with normal control flow. Only the final output returns to Claude. Use it when chaining many tool calls or when intermediate results are large and should be filtered before reaching the context window.
For full documentation, use WebFetch:
- URL:
https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling
Server-Side Tools: Tool Search
The tool search tool lets Claude dynamically discover tools from large libraries without loading all definitions into the context window. Use it when you have many tools but only a few are relevant to any given request. Discovered tool schemas are appended to the request, not swapped in — this preserves the prompt cache (see agent-design.md §Caching for Agents).
For full documentation, use WebFetch:
- URL:
https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool
Skills
Skills package task-specific instructions that Claude loads only when relevant. Each skill is a folder containing a SKILL.md file. The skill's short description sits in context by default; Claude reads the full file when the current task calls for it. Use skills to keep specialized instructions out of the base system prompt without losing discoverability.
For full documentation, use WebFetch:
- URL:
https://platform.claude.com/docs/en/agents-and-tools/skills
Tool Use Examples
You can provide sample tool calls directly in your tool definitions to demonstrate usage patterns and reduce parameter errors. This helps Claude understand how to correctly format tool inputs, especially for tools with complex schemas.
For full documentation, use WebFetch:
- URL:
https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use
Server-Side Tools: Computer Use
Computer use lets Claude interact with a desktop environment (screenshots, mouse, keyboard). It can be Anthropic-hosted (server-side, like code execution) or self-hosted (you provide the environment and execute actions client-side).
For full documentation, use WebFetch:
- URL:
https://platform.claude.com/docs/en/agents-and-tools/computer-use/overview
Context Editing
Context editing clears stale tool results and thinking blocks from the transcript as a long-running agent accumulates turns. Unlike compaction (which summarizes), context editing prunes — the cleared content is removed, not replaced. Use it when old tool outputs are no longer relevant and you want to keep the transcript lean without losing the conversation structure. Thresholds for what to clear are configurable.
For full documentation, use WebFetch:
- URL:
https://platform.claude.com/docs/en/build-with-claude/context-editing
Server-Side Tools: Advisor (Beta)
The advisor tool lets Claude consult a secondary model during a conversation. The advisor runs its own API call with a model you specify and returns its analysis to the primary model. Use it when you want a second opinion, specialized expertise, or cross-model verification without managing the orchestration yourself.
Tool Definition
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-sonnet-4-6"
}
The model parameter is required — it specifies which model the advisor uses for its own inference. Optional fields: caching, max_uses, allowed_callers, defer_loading, strict.
Beta header required: advisor-tool-2026-03-01. The SDK sets this automatically when using client.beta.messages.create() with advisor tools.
Client-Side Tools: Memory
The memory tool enables Claude to store and retrieve information across conversations through a memory file directory. Claude can create, read, update, and delete files that persist between sessions.
Key Facts
- Client-side tool — you control storage via your implementation
- Supports commands:
view,create,str_replace,insert,delete,rename - Operates on files in a
/memoriesdirectory - The Python, TypeScript, and Java SDKs provide helper classes/functions for implementing the memory backend
Security: Never store API keys, passwords, tokens, or other secrets in memory files. Be cautious with personally identifiable information (PII) — check data privacy regulations (GDPR, CCPA) before persisting user data. The reference implementations have no built-in access control; in multi-user systems, implement per-user memory directories and authentication in your tool handlers.
For full implementation examples, use WebFetch:
- Docs:
https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md
Structured Outputs
Structured outputs constrain Claude's responses to follow a specific JSON schema, guaranteeing valid, parseable output. This is not a separate tool — it enhances the Messages API response format and/or tool parameter validation.
Two features are available:
- JSON outputs (
output_config.format): Control Claude's response format - Strict tool use (
strict: true): Guarantee valid tool parameter schemas
Supported models: Claude Opus 4.8, Claude Sonnet 4.6, and Claude Haiku 4.5. Legacy models (Claude Opus 4.5, Claude Opus 4.1) also support structured outputs.
Recommended: Use
client.messages.parse()which automatically validates responses against your schema. When usingmessages.create()directly, useoutput_config: {format: {...}}. Theoutput_formatconvenience parameter is also accepted by some SDK methods (e.g.,.parse()), butoutput_config.formatis the canonical API-level parameter.
JSON Schema Limitations
Supported:
- Basic types: object, array, string, integer, number, boolean, null
enum,const,anyOf,allOf,$ref/$def- String formats:
date-time,time,date,duration,email,hostname,uri,ipv4,ipv6,uuid additionalProperties: false(required for all objects)
Not supported:
- Recursive schemas
- Numerical constraints (
minimum,maximum,multipleOf) - String constraints (
minLength,maxLength) - Complex array constraints
additionalPropertiesset to anything other thanfalse
The Python and TypeScript SDKs automatically handle unsupported constraints by removing them from the schema sent to the API and validating them client-side.
Important Notes
- First request latency: New schemas incur a one-time compilation cost. Subsequent requests with the same schema use a 24-hour cache.
- Refusals: If Claude refuses for safety reasons (
stop_reason: "refusal"), the output may not match your schema. - Token limits: If
stop_reason: "max_tokens", output may be incomplete. Increasemax_tokens. - Incompatible with: Citations (returns 400 error), message prefilling.
- Works with: Batches API, streaming, token counting, extended thinking.
Tips for Effective Tool Use
- Provide detailed descriptions: Claude relies heavily on descriptions to understand when and how to use tools
- Use specific tool names:
get_current_weatheris better thanweather - Validate inputs: Always validate tool inputs before execution
- Handle errors gracefully: Return informative error messages so Claude can adapt
- Limit tool count: Too many tools can confuse the model — keep the set focused
- Test tool interactions: Verify Claude uses tools correctly in various scenarios
For detailed tool use documentation, use WebFetch:
- URL:
https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview
Installation
npm install @anthropic-ai/sdk
Client Initialization
import Anthropic from "@anthropic-ai/sdk";
// Default — resolves credentials from the environment:
// ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN, or an `ant auth login` profile.
// Prefer this for local dev; don't hardcode a key.
const client = new Anthropic();
// Explicit API key (only when you must inject a specific key)
const client = new Anthropic({ apiKey: "your-api-key" });
Basic Message Request
const response = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
messages: [{ role: "user", content: "What is the capital of France?" }],
});
// response.content is ContentBlock[] — a discriminated union. Narrow by .type
// before accessing .text (TypeScript will error on content[0].text without this).
for (const block of response.content) {
if (block.type === "text") {
console.log(block.text);
}
}
System Prompts
const response = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
system:
"You are a helpful coding assistant. Always provide examples in Python.",
messages: [{ role: "user", content: "How do I read a JSON file?" }],
});
Mid-conversation system messages (beta, model-gated)
For operator instructions that arrive mid-conversation (mode switches, injected state), append {role: "system", ...} to messages instead of editing top-level system — this preserves the cached prefix and carries operator authority. Must follow a user message; cannot be messages[0]. Unsupported models return a 400 (role 'system' is not supported on this model). See shared/prompt-caching.md for when to use this vs. top-level system.
// SDK types for role:"system" in messages are pending — pass the beta header
// directly until the SDK updates, then switch to client.beta.messages.create
// with betas: ["mid-conversation-system-2026-04-07"].
const response = await client.messages.create(
{
model: MODEL_ID, // must support mid-conversation system messages
max_tokens: 16000,
system: [
{ type: "text", text: STABLE_SYSTEM, cache_control: { type: "ephemeral" } },
],
messages: [
...history,
{ role: "user", content: userMessage },
// @ts-expect-error — role:"system" pending SDK types
{ role: "system", content: "Terse mode enabled — keep responses under 40 words." },
],
},
{ headers: { "anthropic-beta": "mid-conversation-system-2026-04-07" } },
);
Vision (Images)
URL
const response = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
messages: [
{
role: "user",
content: [
{
type: "image",
source: { type: "url", url: "https://example.com/image.png" },
},
{ type: "text", text: "Describe this image" },
],
},
],
});
Base64
import fs from "fs";
const imageData = fs.readFileSync("image.png").toString("base64");
const response = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
messages: [
{
role: "user",
content: [
{
type: "image",
source: { type: "base64", media_type: "image/png", data: imageData },
},
{ type: "text", text: "What's in this image?" },
],
},
],
});
Prompt Caching
Caching is a prefix match — any byte change anywhere in the prefix invalidates everything after it. For placement patterns, architectural guidance (frozen system prompt, deterministic tool order, where to put volatile content), and the silent-invalidator audit checklist, read shared/prompt-caching.md.
Automatic Caching (Recommended)
Use top-level cache_control to automatically cache the last cacheable block in the request:
const response = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
cache_control: { type: "ephemeral" }, // auto-caches the last cacheable block
system: "You are an expert on this large document...",
messages: [{ role: "user", content: "Summarize the key points" }],
});
Manual Cache Control
For fine-grained control, add cache_control to specific content blocks:
const response = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
system: [
{
type: "text",
text: "You are an expert on this large document...",
cache_control: { type: "ephemeral" }, // default TTL is 5 minutes
},
],
messages: [{ role: "user", content: "Summarize the key points" }],
});
// With explicit TTL (time-to-live)
const response2 = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
system: [
{
type: "text",
text: "You are an expert on this large document...",
cache_control: { type: "ephemeral", ttl: "1h" }, // 1 hour TTL
},
],
messages: [{ role: "user", content: "Summarize the key points" }],
});
Verifying Cache Hits
console.log(response.usage.cache_creation_input_tokens); // tokens written to cache (~1.25x cost)
console.log(response.usage.cache_read_input_tokens); // tokens served from cache (~0.1x cost)
console.log(response.usage.input_tokens); // uncached tokens (full cost)
If cache_read_input_tokens is zero across repeated identical-prefix requests, a silent invalidator is at work — Date.now() or a UUID in the system prompt, non-deterministic key ordering, or a varying tool set. See shared/prompt-caching.md for the full audit table.
Extended Thinking
Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6: Use adaptive thinking.
budget_tokensis removed on Opus 4.8 and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6. Older models: Usethinking: {type: "enabled", budget_tokens: N}(must be <max_tokens, min 1024).
// Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended)
const response = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
thinking: { type: "adaptive" },
output_config: { effort: "high" }, // low | medium | high | max
messages: [
{ role: "user", content: "Solve this math problem step by step..." },
],
});
for (const block of response.content) {
if (block.type === "thinking") {
console.log("Thinking:", block.thinking);
} else if (block.type === "text") {
console.log("Response:", block.text);
}
}
Error Handling
Use the SDK's typed exception classes — never check error messages with string matching:
import Anthropic from "@anthropic-ai/sdk";
try {
const response = await client.messages.create({...});
} catch (error) {
if (error instanceof Anthropic.BadRequestError) {
console.error("Bad request:", error.message);
} else if (error instanceof Anthropic.AuthenticationError) {
console.error("Invalid API key");
} else if (error instanceof Anthropic.RateLimitError) {
console.error("Rate limited - retry later");
} else if (error instanceof Anthropic.APIError) {
console.error(`API error ${error.status}:`, error.message);
}
}
All classes extend Anthropic.APIError with a typed status field. Check from most specific to least specific. See shared/error-codes.md for the full error code reference.
Multi-Turn Conversations
The API is stateless — send the full conversation history each time. Use Anthropic.MessageParam[] to type the messages array:
const messages: Anthropic.MessageParam[] = [
{ role: "user", content: "My name is Alice." },
{ role: "assistant", content: "Hello Alice! Nice to meet you." },
{ role: "user", content: "What's my name?" },
];
const response = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
messages: messages,
});
Rules:
- Consecutive same-role messages are allowed — the API combines them into a single turn
- First message must be
user - Use SDK types (
Anthropic.MessageParam,Anthropic.Message,Anthropic.Tool, etc.) for all API data structures — don't redefine equivalent interfaces
Compaction (long conversations)
Beta, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6. When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a
compactionblock; you must pass it back on subsequent requests — appendresponse.content, not just the text.
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-8",
max_tokens: 16000,
messages,
context_management: {
edits: [{ type: "compact_20260112" }],
},
});
// Append full content — compaction blocks must be preserved
messages.push({ role: "assistant", content: response.content });
const textBlock = response.content.find(
(b): b is Anthropic.Beta.BetaTextBlock => b.type === "text",
);
return textBlock?.text ?? "";
}
// Compaction triggers automatically when context grows large
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"));
Stop Reasons
The stop_reason field in the response indicates why the model stopped generating:
| Value | Meaning |
|---|---|
end_turn |
Claude finished its response naturally |
max_tokens |
Hit the max_tokens limit — increase it or use streaming |
stop_sequence |
Hit a custom stop sequence |
tool_use |
Claude wants to call a tool — execute it and continue |
pause_turn |
Model paused and can be resumed (agentic flows) |
refusal |
Claude refused for safety reasons — check stop_details |
Structured Stop Details
When stop_reason is "refusal", the response includes a stop_details object with structured information about the refusal:
if (response.stop_reason === "refusal" && response.stop_details) {
console.log(`Category: ${response.stop_details.category}`); // "cyber" | "bio" | null
console.log(`Explanation: ${response.stop_details.explanation}`);
}
Cost Optimization Strategies
1. Use Prompt Caching for Repeated Context
// Automatic caching (simplest — caches the last cacheable block)
const response = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
cache_control: { type: "ephemeral" },
system: largeDocumentText, // e.g., 50KB of context
messages: [{ role: "user", content: "Summarize the key points" }],
});
// First request: full cost
// Subsequent requests: ~90% cheaper for cached portion
2. Use Token Counting Before Requests
const countResponse = await client.messages.countTokens({
model: "claude-opus-4-8",
messages: messages,
system: system,
});
const estimatedInputCost = countResponse.input_tokens * 0.000005; // $5/1M tokens
console.log(`Estimated input cost: $${estimatedInputCost.toFixed(4)}`);
The Batches API (POST /v1/messages/batches) processes Messages API requests asynchronously at 50% of standard prices.
Key Facts
- Up to 100,000 requests or 256 MB per batch
- Most batches complete within 1 hour; maximum 24 hours
- Results available for 29 days after creation
- 50% cost reduction on all token usage
- All Messages API features supported (vision, tools, caching, etc.)
Create a Batch
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const messageBatch = await client.messages.batches.create({
requests: [
{
custom_id: "request-1",
params: {
model: "claude-opus-4-8",
max_tokens: 16000,
messages: [
{ role: "user", content: "Summarize climate change impacts" },
],
},
},
{
custom_id: "request-2",
params: {
model: "claude-opus-4-8",
max_tokens: 16000,
messages: [
{ role: "user", content: "Explain quantum computing basics" },
],
},
},
],
});
console.log(`Batch ID: ${messageBatch.id}`);
console.log(`Status: ${messageBatch.processing_status}`);
Poll for Completion
let batch;
while (true) {
batch = await client.messages.batches.retrieve(messageBatch.id);
if (batch.processing_status === "ended") break;
console.log(
`Status: ${batch.processing_status}, processing: ${batch.request_counts.processing}`,
);
await new Promise((resolve) => setTimeout(resolve, 60_000));
}
console.log("Batch complete!");
console.log(`Succeeded: ${batch.request_counts.succeeded}`);
console.log(`Errored: ${batch.request_counts.errored}`);
Retrieve Results
for await (const result of await client.messages.batches.results(
messageBatch.id,
)) {
switch (result.result.type) {
case "succeeded":
console.log(
`[${result.custom_id}] ${result.result.message.content[0].text.slice(0, 100)}`,
);
break;
case "errored":
if (result.result.error.type === "invalid_request") {
console.log(`[${result.custom_id}] Validation error - fix and retry`);
} else {
console.log(`[${result.custom_id}] Server error - safe to retry`);
}
break;
case "expired":
console.log(`[${result.custom_id}] Expired - resubmit`);
break;
}
}
Cancel a Batch
const cancelled = await client.messages.batches.cancel(messageBatch.id);
console.log(`Status: ${cancelled.processing_status}`); // "canceling"
The Files API uploads files for use in Messages API requests. Reference files via file_id in content blocks, avoiding re-uploads across multiple API calls.
Beta: Pass betas: ["files-api-2025-04-14"] in your API calls (the SDK sets the required header automatically).
Key Facts
- Maximum file size: 500 MB
- Total storage: 100 GB per organization
- Files persist until deleted
- File operations (upload, list, delete) are free; content used in messages is billed as input tokens
- Not available on Amazon Bedrock or Google Vertex AI
Upload a File
import Anthropic, { toFile } from "@anthropic-ai/sdk";
import fs from "fs";
const client = new Anthropic();
const uploaded = await client.beta.files.upload({
file: await toFile(fs.createReadStream("report.pdf"), undefined, {
type: "application/pdf",
}),
betas: ["files-api-2025-04-14"],
});
console.log(`File ID: ${uploaded.id}`);
console.log(`Size: ${uploaded.size_bytes} bytes`);
Use a File in Messages
PDF / Text Document
const response = await client.beta.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
messages: [
{
role: "user",
content: [
{ type: "text", text: "Summarize the key findings in this report." },
{
type: "document",
source: { type: "file", file_id: uploaded.id },
title: "Q4 Report",
citations: { enabled: true },
},
],
},
],
betas: ["files-api-2025-04-14"],
});
console.log(response.content[0].text);
Manage Files
List Files
const files = await client.beta.files.list({
betas: ["files-api-2025-04-14"],
});
for (const f of files.data) {
console.log(`${f.id}: ${f.filename} (${f.size_bytes} bytes)`);
}
Delete a File
await client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w", {
betas: ["files-api-2025-04-14"],
});
Download a File
const response = await client.beta.files.download(
"file_011CNha8iCJcU1wXNR6q4V8w",
{ betas: ["files-api-2025-04-14"] },
);
const content = Buffer.from(await response.arrayBuffer());
await fs.promises.writeFile("output.txt", content);
Quick Start
const stream = client.messages.stream({
model: "claude-opus-4-8",
max_tokens: 64000,
messages: [{ role: "user", content: "Write a story" }],
});
for await (const event of stream) {
if (
event.type === "content_block_delta" &&
event.delta.type === "text_delta"
) {
process.stdout.write(event.delta.text);
}
}
Handling Different Content Types
Opus 4.8 / Opus 4.7 / Opus 4.6: Use
thinking: {type: "adaptive"}. On older models, usethinking: {type: "enabled", budget_tokens: N}instead.
const stream = client.messages.stream({
model: "claude-opus-4-8",
max_tokens: 64000,
thinking: { type: "adaptive" },
messages: [{ role: "user", content: "Analyze this problem" }],
});
for await (const event of stream) {
switch (event.type) {
case "content_block_start":
switch (event.content_block.type) {
case "thinking":
console.log("\n[Thinking...]");
break;
case "text":
console.log("\n[Response:]");
break;
}
break;
case "content_block_delta":
switch (event.delta.type) {
case "thinking_delta":
process.stdout.write(event.delta.thinking);
break;
case "text_delta":
process.stdout.write(event.delta.text);
break;
}
break;
}
}
Streaming with Tool Use (Tool Runner)
Use the tool runner with stream: true. The outer loop iterates over tool runner iterations (messages), the inner loop processes stream events:
import Anthropic from "@anthropic-ai/sdk";
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";
const client = new Anthropic();
const getWeather = betaZodTool({
name: "get_weather",
description: "Get current weather for a location",
inputSchema: z.object({
location: z.string().describe("City and state, e.g., San Francisco, CA"),
}),
run: async ({ location }) => `72°F and sunny in ${location}`,
});
const runner = client.beta.messages.toolRunner({
model: "claude-opus-4-8",
max_tokens: 64000,
tools: [getWeather],
messages: [
{ role: "user", content: "What's the weather in Paris and London?" },
],
stream: true,
});
// Outer loop: each tool runner iteration
for await (const messageStream of runner) {
// Inner loop: stream events for this iteration
for await (const event of messageStream) {
switch (event.type) {
case "content_block_delta":
switch (event.delta.type) {
case "text_delta":
process.stdout.write(event.delta.text);
break;
case "input_json_delta":
// Tool input being streamed
break;
}
break;
}
}
}
Getting the Final Message
const stream = client.messages.stream({
model: "claude-opus-4-8",
max_tokens: 64000,
messages: [{ role: "user", content: "Hello" }],
});
for await (const event of stream) {
// Process events...
}
const finalMessage = await stream.finalMessage();
console.log(`Tokens used: ${finalMessage.usage.output_tokens}`);
Stream Event Types
| Event Type | Description | When it fires |
|---|---|---|
message_start |
Contains message metadata | Once at the beginning |
content_block_start |
New content block beginning | When a text/tool_use block starts |
content_block_delta |
Incremental content update | For each token/chunk |
content_block_stop |
Content block complete | When a block finishes |
message_delta |
Message-level updates | Contains stop_reason, usage |
message_stop |
Message complete | Once at the end |
Best Practices
- Always flush output — Use
process.stdout.write()for immediate display - Handle partial responses — If the stream is interrupted, you may have incomplete content
- Track token usage — The
message_deltaevent contains usage information - Use
finalMessage()— Get the completeAnthropic.Messageobject even when streaming. Don't wrap.on()events innew Promise()—finalMessage()handles all completion/error/abort states internally - Buffer for web UIs — Consider buffering a few tokens before rendering to avoid excessive DOM updates
- Use
stream.on("text", ...)for deltas — Thetextevent provides just the delta string, simpler than manually filteringcontent_block_deltaevents - For agentic loops with streaming — See the Streaming Manual Loop section in tool-use.md for combining
stream()+finalMessage()with a tool-use loop
Raw SSE Format
If using raw HTTP (not SDKs), the stream returns Server-Sent Events:
event: message_start
data: {"type":"message_start","message":{"id":"msg_...","type":"message",...}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}}
event: message_stop
data: {"type":"message_stop"}
For conceptual overview (tool definitions, tool choice, tips), see shared/tool-use-concepts.md.
Tool Runner (Recommended)
Beta: The tool runner is in beta in the TypeScript SDK.
Use betaZodTool with Zod schemas to define tools with a run function, then pass them to client.beta.messages.toolRunner():
import Anthropic from "@anthropic-ai/sdk";
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";
const client = new Anthropic();
const getWeather = betaZodTool({
name: "get_weather",
description: "Get current weather for a location",
inputSchema: z.object({
location: z.string().describe("City and state, e.g., San Francisco, CA"),
unit: z.enum(["celsius", "fahrenheit"]).optional(),
}),
run: async (input) => {
// Your implementation here
return `72°F and sunny in ${input.location}`;
},
});
// The tool runner handles the agentic loop and returns the final message
const finalMessage = await client.beta.messages.toolRunner({
model: "claude-opus-4-8",
max_tokens: 16000,
tools: [getWeather],
messages: [{ role: "user", content: "What's the weather in Paris?" }],
});
console.log(finalMessage.content);
Key benefits of the tool runner:
- No manual loop — the SDK handles calling tools and feeding results back
- Type-safe tool inputs via Zod schemas
- Tool schemas are generated automatically from Zod definitions
- Iteration stops automatically when Claude has no more tool calls
Manual Agentic Loop
Use this when you need fine-grained control (custom logging, conditional tool execution, streaming individual iterations, human-in-the-loop approval):
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const tools: Anthropic.Tool[] = [...]; // Your tool definitions
let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }];
while (true) {
const response = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
tools: tools,
messages: messages,
});
if (response.stop_reason === "end_turn") break;
// Server-side tool hit iteration limit; append assistant turn and re-send to continue
if (response.stop_reason === "pause_turn") {
messages.push({ role: "assistant", content: response.content });
continue;
}
const toolUseBlocks = response.content.filter(
(b): b is Anthropic.ToolUseBlock => b.type === "tool_use",
);
messages.push({ role: "assistant", content: response.content });
const toolResults: Anthropic.ToolResultBlockParam[] = [];
for (const tool of toolUseBlocks) {
const result = await executeTool(tool.name, tool.input);
toolResults.push({
type: "tool_result",
tool_use_id: tool.id,
content: result,
});
}
messages.push({ role: "user", content: toolResults });
}
Streaming Manual Loop
Use client.messages.stream() + finalMessage() instead of .create() when you need streaming within a manual loop. Text deltas are streamed on each iteration; finalMessage() collects the complete Message so you can inspect stop_reason and extract tool-use blocks:
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const tools: Anthropic.Tool[] = [...];
let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }];
while (true) {
const stream = client.messages.stream({
model: "claude-opus-4-8",
max_tokens: 64000,
tools,
messages,
});
// Stream text deltas on each iteration
stream.on("text", (delta) => {
process.stdout.write(delta);
});
// finalMessage() resolves with the complete Message — no need to
// manually wire up .on("message") / .on("error") / .on("abort")
const message = await stream.finalMessage();
if (message.stop_reason === "end_turn") break;
// Server-side tool hit iteration limit; append assistant turn and re-send to continue
if (message.stop_reason === "pause_turn") {
messages.push({ role: "assistant", content: message.content });
continue;
}
const toolUseBlocks = message.content.filter(
(b): b is Anthropic.ToolUseBlock => b.type === "tool_use",
);
messages.push({ role: "assistant", content: message.content });
const toolResults: Anthropic.ToolResultBlockParam[] = [];
for (const tool of toolUseBlocks) {
const result = await executeTool(tool.name, tool.input);
toolResults.push({
type: "tool_result",
tool_use_id: tool.id,
content: result,
});
}
messages.push({ role: "user", content: toolResults });
}
Important: Don't wrap
.on()events innew Promise()to collect the final message — usestream.finalMessage()instead. The SDK handles all error/abort/completion states internally.
Error handling in the loop: Use the SDK's typed exceptions (e.g.,
Anthropic.RateLimitError,Anthropic.APIError) — see Error Handling for examples. Don't check error messages with string matching.
SDK types: Use
Anthropic.MessageParam,Anthropic.Tool,Anthropic.ToolUseBlock,Anthropic.ToolResultBlockParam,Anthropic.Message, etc. for all API-related data structures. Don't redefine equivalent interfaces.
Handling Tool Results
const response = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
tools: tools,
messages: [{ role: "user", content: "What's the weather in Paris?" }],
});
for (const block of response.content) {
if (block.type === "tool_use") {
const result = await executeTool(block.name, block.input);
const followup = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
tools: tools,
messages: [
{ role: "user", content: "What's the weather in Paris?" },
{ role: "assistant", content: response.content },
{
role: "user",
content: [
{ type: "tool_result", tool_use_id: block.id, content: result },
],
},
],
});
}
}
Tool Choice
const response = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
tools: tools,
tool_choice: { type: "tool", name: "get_weather" },
messages: [{ role: "user", content: "What's the weather in Paris?" }],
});
Server-Side Tools
Version-suffixed type literals; name is fixed per interface. Pass plain object literals — the ToolUnion type is satisfied structurally. The name/type pair must match the interface: mixing str_replace_based_edit_tool (20250728 name) with text_editor_20250124 (which expects str_replace_editor) is a TS2322.
Don't type-annotate as Tool[] — Tool is just the custom-tool variant. Let structural typing infer from the tools param, or annotate as Anthropic.Messages.ToolUnion[] if you must:
// ✓ let inference work — no annotation
const response = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
tools: [
{ type: "text_editor_20250728", name: "str_replace_based_edit_tool" },
{ type: "bash_20250124", name: "bash" },
{ type: "web_search_20260209", name: "web_search" },
{ type: "code_execution_20260120", name: "code_execution" },
],
messages: [{ role: "user", content: "..." }],
});
// ✗ this is a TS2352 — Tool is the CUSTOM tool variant only
// const tools: Anthropic.Tool[] = [{ type: "text_editor_20250728", ... }]
| Interface | name |
type |
|---|---|---|
ToolTextEditor20250124 |
str_replace_editor |
text_editor_20250124 |
ToolTextEditor20250429 |
str_replace_based_edit_tool |
text_editor_20250429 |
ToolTextEditor20250728 |
str_replace_based_edit_tool |
text_editor_20250728 |
ToolBash20250124 |
bash |
bash_20250124 |
WebSearchTool20260209 |
web_search |
web_search_20260209 |
WebFetchTool20260209 |
web_fetch |
web_fetch_20260209 |
CodeExecutionTool20260120 |
code_execution |
code_execution_20260120 |
Don't mix beta and non-beta types: if you call client.beta.messages.create(), the response content is BetaContentBlock[] — you cannot pass that to a non-beta ContentBlockParam[] without narrowing each element.
Code Execution
Basic Usage
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
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_20260120", name: "code_execution" }],
});
Reading Local Files (ESM note)
__dirname doesn't exist in ES modules. For script-relative paths use import.meta.url:
import { readFileSync } from "fs";
import { fileURLToPath } from "url";
import { dirname, join } from "path";
const __dirname = dirname(fileURLToPath(import.meta.url));
const pdfBytes = readFileSync(join(__dirname, "sample.pdf"));
Or use a CWD-relative path if the script runs from a known directory: readFileSync("./sample.pdf").
Upload Files for Analysis
import Anthropic, { toFile } from "@anthropic-ai/sdk";
import { createReadStream } from "fs";
const client = new Anthropic();
// 1. Upload a file
const uploaded = await client.beta.files.upload({
file: await toFile(createReadStream("sales_data.csv"), undefined, {
type: "text/csv",
}),
betas: ["files-api-2025-04-14"],
});
// 2. Pass to code execution
// Code execution is GA; Files API is still beta (pass via RequestOptions)
const response = await client.messages.create(
{
model: "claude-opus-4-8",
max_tokens: 16000,
messages: [
{
role: "user",
content: [
{
type: "text",
text: "Analyze this sales data. Show trends and create a visualization.",
},
{ type: "container_upload", file_id: uploaded.id },
],
},
],
tools: [{ type: "code_execution_20260120", name: "code_execution" }],
},
{ headers: { "anthropic-beta": "files-api-2025-04-14" } },
);
Retrieve Generated Files
import path from "path";
import fs from "fs";
const OUTPUT_DIR = "./claude_outputs";
await fs.promises.mkdir(OUTPUT_DIR, { recursive: true });
for (const block of response.content) {
if (block.type === "bash_code_execution_tool_result") {
const result = block.content;
if (result.type === "bash_code_execution_result" && result.content) {
for (const fileRef of result.content) {
if (fileRef.type === "bash_code_execution_output") {
const metadata = await client.beta.files.retrieveMetadata(
fileRef.file_id,
);
const downloadResponse = await client.beta.files.download(fileRef.file_id);
const fileBytes = Buffer.from(await downloadResponse.arrayBuffer());
const safeName = path.basename(metadata.filename);
if (!safeName || safeName === "." || safeName === "..") {
console.warn(`Skipping invalid filename: ${metadata.filename}`);
continue;
}
const outputPath = path.join(OUTPUT_DIR, safeName);
await fs.promises.writeFile(outputPath, fileBytes);
console.log(`Saved: ${outputPath}`);
}
}
}
}
}
Container Reuse
// First request: set up environment
const response1 = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
messages: [
{
role: "user",
content: "Install tabulate and create data.json with sample user data",
},
],
tools: [{ type: "code_execution_20260120", name: "code_execution" }],
});
// Reuse container
// container is nullable — set only when using server-side code execution
const containerId = response1.container!.id;
const response2 = await client.messages.create({
container: containerId,
model: "claude-opus-4-8",
max_tokens: 16000,
messages: [
{
role: "user",
content: "Read data.json and display as a formatted table",
},
],
tools: [{ type: "code_execution_20260120", name: "code_execution" }],
});
Memory Tool
Basic Usage
const response = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
messages: [
{
role: "user",
content: "Remember that my preferred language is TypeScript.",
},
],
tools: [{ type: "memory_20250818", name: "memory" }],
});
SDK Memory Helper
Use betaMemoryTool with a MemoryToolHandlers implementation:
import {
betaMemoryTool,
type MemoryToolHandlers,
} from "@anthropic-ai/sdk/helpers/beta/memory";
const handlers: MemoryToolHandlers = {
async view(command) { ... },
async create(command) { ... },
async str_replace(command) { ... },
async insert(command) { ... },
async delete(command) { ... },
async rename(command) { ... },
};
const memory = betaMemoryTool(handlers);
const runner = client.beta.messages.toolRunner({
model: "claude-opus-4-8",
max_tokens: 16000,
tools: [memory],
messages: [{ role: "user", content: "Remember my preferences" }],
});
for await (const message of runner) {
console.log(message);
}
For full implementation examples, use WebFetch:
https://github.com/anthropics/anthropic-sdk-typescript/blob/main/examples/tools-helpers-memory.ts
Structured Outputs
JSON Outputs (Zod — Recommended)
import Anthropic from "@anthropic-ai/sdk";
import { z } from "zod";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
const ContactInfoSchema = z.object({
name: z.string(),
email: z.string(),
plan: z.string(),
interests: z.array(z.string()),
demo_requested: z.boolean(),
});
const client = new Anthropic();
const response = await client.messages.parse({
model: "claude-opus-4-8",
max_tokens: 16000,
messages: [
{
role: "user",
content:
"Extract: Jane Doe (jane@co.com) wants Enterprise, interested in API and SDKs, wants a demo.",
},
],
output_config: {
format: zodOutputFormat(ContactInfoSchema),
},
});
// parsed_output is null if parsing failed — assert or guard
console.log(response.parsed_output!.name); // "Jane Doe"
Strict Tool Use
const response = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 16000,
messages: [
{
role: "user",
content: "Book a flight to Tokyo for 2 passengers on March 15",
},
],
tools: [
{
name: "book_flight",
description: "Book a flight to a destination",
strict: true,
input_schema: {
type: "object",
properties: {
destination: { type: "string" },
date: { type: "string", format: "date" },
passengers: {
type: "integer",
enum: [1, 2, 3, 4, 5, 6, 7, 8],
},
},
required: ["destination", "date", "passengers"],
additionalProperties: false,
},
},
],
});
Bindings not shown here: This README covers the most common managed-agents flows for TypeScript. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the TypeScript SDK repo or the relevant docs page from
shared/live-sources.mdrather than guess. Do not extrapolate from cURL shapes or another language's SDK.
Agents are persistent — create once, reference by ID. Store the agent ID returned by
agents.createand pass it to every subsequentsessions.create; do not callagents.createin the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is inshared/live-sources.md. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path.
Installation
npm install @anthropic-ai/sdk
Client Initialization
import Anthropic from "@anthropic-ai/sdk";
// Default — resolves credentials from the environment:
// ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN, or an `ant auth login` profile.
// Prefer this for local dev; don't hardcode a key.
const client = new Anthropic();
// Explicit API key (only when you must inject a specific key)
const client = new Anthropic({ apiKey: "your-api-key" });
Create an Environment
const environment = await client.beta.environments.create(
{
name: "my-dev-env",
config: {
type: "cloud",
networking: { type: "unrestricted" },
},
},
);
console.log(environment.id); // env_...
Create an Agent (required first step)
⚠️ There is no inline agent config.
model/system/toolslive on the agent object, not the session. Always start withagents.create()— the session only takesagent: { type: "agent", id: agent.id }.
Minimal
// 1. Create the agent (reusable, versioned)
const agent = await client.beta.agents.create(
{
name: "Coding Assistant",
model: "claude-opus-4-8",
tools: [{ type: "agent_toolset_20260401", default_config: { enabled: true } }],
},
);
// 2. Start a session
const session = await client.beta.sessions.create(
{
agent: { type: "agent", id: agent.id, version: agent.version },
environment_id: environment.id,
},
);
console.log(session.id, session.status);
With system prompt and custom tools
const agent = await client.beta.agents.create(
{
name: "Code Reviewer",
model: "claude-opus-4-8",
system: "You are a senior code reviewer.",
tools: [
{ type: "agent_toolset_20260401", default_config: { enabled: true } },
{
type: "custom",
name: "run_tests",
description: "Run the test suite",
input_schema: {
type: "object",
properties: {
test_path: { type: "string", description: "Path to test file" },
},
required: ["test_path"],
},
},
],
},
);
const session = await client.beta.sessions.create(
{
agent: { type: "agent", id: agent.id, version: agent.version },
environment_id: environment.id,
title: "Code review session",
resources: [
{
type: "github_repository",
url: "https://github.com/owner/repo",
mount_path: "/workspace/repo",
authorization_token: process.env.GITHUB_TOKEN,
branch: "main",
},
],
},
);
Send a User Message
await client.beta.sessions.events.send(
session.id,
{
events: [
{
type: "user.message",
content: [{ type: "text", text: "Review the auth module" }],
},
],
},
);
💡 Stream-first: Open the stream before (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See Steering Patterns.
Stream Events (SSE)
// Stream-first: open stream and send concurrently
const [events] = await Promise.all([
collectStream(session.id),
client.beta.sessions.events.send(
session.id,
{ events: [{ type: "user.message", content: [{ type: "text", text: "..." }] }] },
),
]);
// Standalone stream iteration:
const stream = await client.beta.sessions.events.stream(
session.id,
);
for await (const event of stream) {
switch (event.type) {
case "agent.message":
for (const block of event.content) {
if (block.type === "text") {
process.stdout.write(block.text);
}
}
break;
case "agent.custom_tool_use":
// Custom tool invocation — session is now idle
console.log(`\nCustom tool call: ${event.name}`);
console.log(`Input: ${JSON.stringify(event.input)}`);
break;
case "session.status_idle":
console.log("\n--- Agent idle ---");
break;
case "session.status_terminated":
console.log("\n--- Session terminated ---");
break;
}
}
Provide Custom Tool Result
await client.beta.sessions.events.send(
session.id,
{
events: [
{
type: "user.custom_tool_result",
custom_tool_use_id: "sevt_abc123",
content: [{ type: "text", text: "All 42 tests passed." }],
},
],
},
);
Poll Events
const events = await client.beta.sessions.events.list(
session.id,
);
for (const event of events.data) {
console.log(`${event.type}: ${event.id}`);
}
Full Streaming Loop with Custom Tools
function runCustomTool(toolName: string, toolInput: unknown): string {
if (toolName === "run_tests") {
// Your tool implementation here
return "All tests passed.";
}
return `Unknown tool: ${toolName}`;
}
async function runSession(client: Anthropic, sessionId: string) {
while (true) {
const stream = await client.beta.sessions.events.stream(
sessionId,
);
const toolCalls: Anthropic.Beta.Sessions.BetaManagedAgentsAgentCustomToolUseEvent[] = [];
for await (const event of stream) {
if (event.type === "agent.message") {
for (const block of event.content) {
if (block.type === "text") {
process.stdout.write(block.text);
}
}
} else if (event.type === "agent.custom_tool_use") {
toolCalls.push(event);
} else if (event.type === "session.status_idle") {
break;
} else if (event.type === "session.status_terminated") {
return;
}
}
if (toolCalls.length === 0) break;
// Process custom tool calls
const results = toolCalls.map((call) => ({
type: "user.custom_tool_result" as const,
custom_tool_use_id: call.id,
content: [{ type: "text" as const, text: runCustomTool(call.name, call.input) }],
}));
await client.beta.sessions.events.send(
sessionId,
{ events: results },
);
}
}
Upload a File
import fs from "fs";
const file = await client.beta.files.upload({
file: fs.createReadStream("data.csv"),
purpose: "agent",
});
// Use in a session
const session = await client.beta.sessions.create(
{
agent: { type: "agent", id: agent.id, version: agent.version },
environment_id: environment.id,
resources: [{ type: "file", file_id: file.id, mount_path: "/workspace/data.csv" }],
},
);
List and Download Session Files
List files the agent wrote to /mnt/session/outputs/ during a session, then download them.
import fs from "fs";
// List files associated with a session
const files = await client.beta.files.list({
scope_id: session.id,
betas: ["managed-agents-2026-04-01"],
});
for (const f of files.data) {
console.log(f.filename, f.size_bytes);
// Download and save to disk
const resp = await client.beta.files.download(f.id);
const buffer = Buffer.from(await resp.arrayBuffer());
fs.writeFileSync(f.filename, buffer);
}
💡 There's a brief indexing lag (~1–3s) between
session.status_idleand output files appearing infiles.list. Retry once or twice if the list is empty.
Session Management
// Get session details
const session = await client.beta.sessions.retrieve("sesn_011CZxAbc123Def456");
console.log(session.status, session.usage);
// List sessions
const sessions = await client.beta.sessions.list();
// Delete a session
await client.beta.sessions.delete("sesn_011CZxAbc123Def456");
// Archive a session
await client.beta.sessions.archive("sesn_011CZxAbc123Def456");
MCP Server Integration
// Agent declares MCP server (no auth here — auth goes in a vault)
const agent = await client.beta.agents.create({
name: "MCP Agent",
model: "claude-opus-4-8",
mcp_servers: [
{ type: "url", name: "my-tools", url: "https://my-mcp-server.example.com/sse" },
],
tools: [
{ type: "agent_toolset_20260401", default_config: { enabled: true } },
{ type: "mcp_toolset", mcp_server_name: "my-tools" },
],
});
// Session attaches vault(s) containing credentials for those MCP server URLs
const session = await client.beta.sessions.create({
agent: agent.id,
environment_id: environment.id,
vault_ids: [vault.id],
});
See shared/managed-agents-tools.md §Vaults for creating vaults and adding credentials.
When to Use WebFetch
Use WebFetch to get the latest documentation when:
- User asks for "latest" or "current" information
- Cached data seems incorrect
- User asks about features not covered here
Live documentation URLs are in shared/live-sources.md.
Common Pitfalls
- Don't truncate inputs when passing files or content to the API. If the content is too long to fit in the context window, notify the user and discuss options (chunking, summarization, etc.) rather than silently truncating.
- Opus 4.8 / 4.7 thinking: Adaptive only.
thinking: {type: "enabled", budget_tokens: N}returns 400 —budget_tokensis fully removed (along withtemperature,top_p,top_k). Usethinking: {type: "adaptive"}. Opus 4.8 inherits this surface from 4.7 with no new breaking changes. - Opus 4.6 / Sonnet 4.6 thinking: Use
thinking: {type: "adaptive"}— do NOT usebudget_tokensfor new 4.6 code (deprecated on both Opus 4.6 and Sonnet 4.6; for gradual migration of existing code, see the transitional escape hatch inshared/model-migration.md— note this carve-out does not apply to Opus 4.7 or 4.8). For older models,budget_tokensmust be less thanmax_tokens(minimum 1024). This will throw an error if you get it wrong. - 4.6/4.7/4.8 family prefill removed: Assistant message prefills (last-assistant-turn prefills) return a 400 error on Opus 4.6, Opus 4.7, Opus 4.8, and Sonnet 4.6. Use structured outputs (
output_config.format) or system prompt instructions to control response format instead. - Confirm migration scope before editing: When a user asks to migrate code to a newer Claude model without naming a specific file, directory, or file list, ask which scope to apply first — the entire working directory, a specific subdirectory, or a specific set of files. Do not start editing until the user confirms. Imperative phrasings like "migrate my codebase", "move my project to X", "upgrade to Sonnet 4.6", or bare "migrate to Opus 4.8" are still ambiguous — they tell you what to do but not where, so ask. Proceed without asking only when the prompt names an exact file, a specific directory, or an explicit file list ("migrate
app.py", "migrate everything underservices/", "updatea.pyandb.py"). Seeshared/model-migration.mdStep 0. max_tokensdefaults: Don't lowballmax_tokens— hitting the cap truncates output mid-thought and requires a retry. For non-streaming requests, default to~16000(keeps responses under SDK HTTP timeouts). For streaming requests, default to~64000(timeouts aren't a concern, so give the model room). Only go lower when you have a hard reason: classification (~256), cost caps, deliberately short outputs, ormax_tokens: 0for cache pre-warming (seeshared/prompt-caching.md→ Pre-warming).- 128K output tokens: Opus 4.6, Opus 4.7, and Opus 4.8 support up to 128K
max_tokens, but the SDKs require streaming for values that large to avoid HTTP timeouts. Use.stream()with.get_final_message()/.finalMessage(). - Tool call JSON parsing (4.6/4.7/4.8 family): Opus 4.6, Opus 4.7, Opus 4.8, and Sonnet 4.6 may produce different JSON string escaping in tool call
inputfields (e.g., Unicode or forward-slash escaping). Always parse tool inputs withjson.loads()/JSON.parse()— never do raw string matching on the serialized input. - Structured outputs (all models): Use
output_config: {format: {...}}instead of the deprecatedoutput_formatparameter onmessages.create(). This is a general API change, not 4.6-specific. - Don't reimplement SDK functionality: The SDK provides high-level helpers — use them instead of building from scratch. Specifically: use
stream.finalMessage()instead of wrapping.on()events innew Promise(); use typed exception classes (Anthropic.RateLimitError, etc.) instead of string-matching error messages; use SDK types (Anthropic.MessageParam,Anthropic.Tool,Anthropic.Message, etc.) instead of redefining equivalent interfaces. - Don't define custom types for SDK data structures: The SDK exports types for all API objects. Use
Anthropic.MessageParamfor messages,Anthropic.Toolfor tool definitions,Anthropic.ToolUseBlock/Anthropic.ToolResultBlockParamfor tool results,Anthropic.Messagefor responses. Defining your owninterface ChatMessage { role: string; content: unknown }duplicates what the SDK already provides and loses type safety. - Report and document output: For tasks that produce reports, documents, or visualizations, the code execution sandbox has
python-docx,python-pptx,matplotlib,pillow, andpypdfpre-installed. Claude can generate formatted files (DOCX, PDF, charts) and return them via the Files API — consider this for "report" or "document" type requests instead of plain stdout text.