anthropics/claude-api

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. (Exception: the prompt-audit subcommand is non-interactive and does not stop here - it records non-Anthropic provider markers in its report's stated assumptions and never proposes switching a non-Anthropic file to the Anthropic SDK.)

Output Requirement

When the user asks you to add, modify, or implement a Claude feature, your code must call Claude through one of:

1. 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.
2. 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.

If WebFetch or repository access fails (network restricted, timeouts, clone blocked): do not keep retrying - write code from the patterns and namespace/package tables in the {lang}/ file, run the compiler or interpreter on it, and iterate on the error output. For statically-typed SDKs (C#, Java, Go) a compile-fix loop against local errors reaches working code faster than blocked network research.

Defaults

Unless the user requests otherwise:

For the Claude model version, please use Claude Opus 5, which you can access via the exact model string claude-opus-5. 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

Warning: API Drift - Your Training Prior May Be Stale

Several common Claude API shapes changed in 2025-2026. If you recall a pattern from training, verify it against the {lang}/ files in this skill before writing - the rows below are the most frequent drift points:

Area	Stale prior	Current API
Extended thinking	thinking: {type: "enabled", budget_tokens: N}	On Claude 4.6+ models: thinking: {type: "adaptive"}. budget_tokens is deprecated on Opus 4.6 / Sonnet 4.6 and rejected with a 400 on Fable 5/5.1 / Sonnet 5 / Opus 5 / 4.8 / 4.7. Pre-4.6 models still use budget_tokens.
Web search / web fetch tool type	web_search_20250305, web_fetch_20250910	web_search_20260209, web_fetch_20260209 (dynamic filtering) on Opus 5/4.8/4.7/4.6, Sonnet 5, and Sonnet 4.6. Older models keep the basic variants; on Vertex AI only basic web_search_20250305 is available (web fetch is not on Vertex) - see the Server Tools QR below.
PHP parameter names	snake_case wire names as named args (max_tokens)	Top-level named args are camelCase (maxTokens). Nested array keys vary by feature (e.g. 'taskBudget', 'skillID', 'mcp_server_name') - copy the exact key from the documented example; do not bulk-convert.
Managed Agents credentials	Keep secrets host-side via custom tools (the only option before vaults shipped)	Vault environment_variable credentials - stored by Anthropic, substituted at egress, never visible in the sandbox (shared/managed-agents-tools.md -> Vaults). Host-side custom tools remain the fallback for self-hosted sandboxes.
Files API / Skills	client.beta.files.* / client.beta.skills.* with beta files-api-2025-04-14 / skills-2025-10-02	Out of beta: client.files.* / client.skills.*, no beta header. In current SDKs client.beta.files / client.beta.skills have breaking shape changes from previous versions, matching the stable namespaces - migrate per shared/live-sources.md -> Files API / Skills Guide.

The {lang}/ files in this skill are authoritative over recalled patterns.

---

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. After the per-target changes are applied, audit the in-scope prompt text, tool descriptions, and request code against shared/prompt-audit.md - prompting written for the source model is part of every migration, and it does not announce itself.
prompt-audit	Audit existing prompts, skills, and tool descriptions for dated patterns ("cruft") written for older models. Read shared/prompt-audit.md immediately and follow it in order: Step 0 (establish scope and target model from the request and the repository - state the assumptions in the report, do not stop to ask), inventory, provenance, then the pattern scan. Produce both deliverables in full - the audit report (findings with file:line, pattern, why it's obsolete for the target model, confidence) and a proposed diff - without pausing for confirmation; apply edits only if the request explicitly asked for them. Do not summarize the guide - execute it.
upgrade	Upgrade the project's Anthropic SDK dependency across a major version - currently the Python SDK, anthropic 0.x -> 1.x. Trailing words may name the language and/or a scope (upgrade python, upgrade python sdk src/). Read python/claude-api/sdk-upgrade.md immediately and follow it in order: Step 0 (confirm scope, then establish the current and target versions - a published 1.x must exist before you write a pin), the Step 1 inventory, each numbered section, then verification and the report. Do not summarize the guide - execute it. If the detected or named language has no sdk-upgrade.md in this skill, say that no major-version upgrade guide is bundled for that SDK yet and point the user at that SDK's CHANGELOG (repositories in shared/live-sources.md); do not improvise one from the Python guide. This is not model migration - to move code to a newer Claude model, use migrate.
cost-optimize	Reduce what existing Claude API code costs to run, without sacrificing output quality. Read shared/cost-optimization.md immediately and follow it in order: Step 0 (establish scope, quality bar, and baseline), the token profile - measured through the Usage and Cost Admin API when the user has an Admin API key, from the app's own response.usage logs when it has those (ask), or estimated from the code otherwise - then a savings-ranked shortlist of levers (quoted in dollars, % of bill, or relative buckets depending on which of those data sources you have), free wins (caching, input-token hygiene, loop hygiene, output-token hygiene, batch) before tradeoffs (budgets, effort, model choice, multi-model); any lever that earns a place becomes its own diff - proposed by default, applied and measured against the eval covering the traffic it touches when the user asks and approves - and "no changes recommended" is a valid outcome. Two standing rules: every run that exercises the model spends real money, so get the user's approval first; and when context for a lever is missing, work through it interactively with the user - this workflow is not expected to one-shot the audit. Do not summarize the guide - execute it; presenting the profile and the ranked plan to the user is part of executing it.

---

Language Detection

Before reading code examples, determine which language the user is working in (exception: for the prompt-audit subcommand, skip this section's ask steps - the audit is non-interactive and its inventory is language-agnostic; when no language is inferable, proceed without asking and state the assumption in the report):

1. Look at project files to infer the language:

   • *.py, requirements.txt, pyproject.toml, setup.py, Pipfile -> Python - read from python/
   • *.ts, *.tsx, package.json, tsconfig.json -> TypeScript - read from typescript/
   • *.js, *.jsx (no .ts files present) -> TypeScript - JS uses the same SDK, read from typescript/
   • *.java, pom.xml, build.gradle -> Java - read from java/
   • *.kt, *.kts, build.gradle.kts -> Java - Kotlin uses the Java SDK, read from java/
   • *.scala, build.sbt -> Java - Scala uses the Java SDK, read from java/
   • *.go, go.mod -> Go - read from go/
   • *.rb, Gemfile -> Ruby - read from ruby/
   • *.cs, *.csproj -> C# - read from csharp/
   • *.php, composer.json -> PHP - read from php/

2. 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?"

3. 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."

4. 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

5. If user needs cURL/raw HTTP examples, read from curl/.

Language-Specific Feature Support

Every SDK language above supports both the beta Tool Runner and Managed Agents (beta) - Python (@beta_tool decorator), TypeScript (betaZodTool + Zod), Java (annotated classes), Go (BetaToolRunner in the toolrunner pkg), Ruby (BaseTool + tool_runner), C# (BetaToolRunner + raw JSON schema), PHP (BetaRunnableTool + toolRunner()); code entry points are in the Tool Use Patterns quick reference below. cURL is raw HTTP (no SDK features) and supports Managed Agents.

Managed Agents code examples: see the reading guide in the ## Managed Agents (Beta) section below.

---

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. "Simplest" means the least code you own: for a hosted, scheduled, or memory-backed agent, Managed Agents is usually the simplest option (no loop code, no state files, no scheduler), even though it's a bigger platform.

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
Agent that runs on a schedule (cron, "every night")	Agent	Managed Agents - scheduled deployments	Deployments fire sessions autonomously; no client-side scheduler

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 the agentic loop - its per-turn hooks still give you approval gates, logging, error interception, and conditional execution (see shared/tool-use-concepts.md) - or the manual loop when you want to own the entire loop yourself.

Cloud-provider access. Claude Platform on AWS is Anthropic-operated with same-day API parity - see shared/claude-platform-on-aws.md for client setup. For per-feature availability on Claude Platform on AWS, Amazon Bedrock, Google Vertex AI, and Microsoft Foundry, see shared/platform-availability.md - that table is the single source of truth in this skill; do not infer availability from anywhere else.

Building an Agent: Four Approaches

Once you've decided you actually need an agent (open-ended, model-driven tool use), there are four distinct ways to build one. Two independent questions separate them: who supplies the harness (the agent loop + context management) and who supplies the deployment (the infra the agent runs on). The Tool Runner and the Claude Agent SDK both supply a harness only - you still host and deploy them yourself - which is why they're easy to conflate. Managed Agents (CMA) is the only option that supplies both the harness and managed deployment; the manual loop supplies neither.

#	Approach	You write	Harness & deployment	Tools available	Use when
1	Claude API - manual loop	The while stop_reason == "tool_use" loop yourself	You build the harness; you host	Only tools you define	You want to own the entire loop - no beta dependency, or a control flow the Tool Runner's per-turn hooks don't fit
2	Claude API - Tool Runner (client.beta.messages.tool_runner + @beta_tool / betaZodTool)	Just the tool functions	SDK supplies the loop (harness only); you host	Only tools you define	A custom-tool agent without hand-writing the loop (most cases). Per-turn hooks still give you approval gates, error interception, result modification (e.g. cache_control), retries, streaming, and compaction
3	Managed Agents (REST, beta)	Agent config + your tool results	Anthropic supplies the harness and hosts a per-session sandbox (harness + deployment)	Anthropic-hosted sandbox (bash, files, code exec) + Skills/MCP + your tools	You want Anthropic to run the loop and host the per-session workspace; persisted/versioned configs; long-running sessions
4	Claude Agent SDK - separate product (claude-agent-sdk / @anthropic-ai/claude-agent-sdk)	A prompt + options	SDK supplies the Claude Code harness + built-in tools (harness only); you host	Built-in Read/Write/Edit/Bash/Glob/Grep/WebSearch/WebFetch + MCP + subagents	You want a batteries-included coding/filesystem agent running on your own infra

The harness/deployment split is the key mental model: options 1, 2, and 4 all leave deployment to you; only option 3 (CMA) adds managed deployment. Options 1-3 are what this skill generates; option 4 is a different library with its own docs - see the disambiguation below.

Tool Runner != Claude Agent SDK. These sound alike but are different packages:

• Tool Runner is part of the regular Anthropic API SDK (anthropic / @anthropic-ai/sdk), reached via client.beta.messages.tool_runner. It automates the request -> execute -> loop cycle for tools you define. No built-in tools, no filesystem access, no sandbox - you supply every tool and host the compute. It is option 2 above, a thin helper over POST /v1/messages.
• Claude Agent SDK (claude-agent-sdk / @anthropic-ai/claude-agent-sdk) is Claude Code packaged as a library. It ships built-in tools (file read/write/edit, bash, grep, web search), the full agent loop, context management, hooks, subagents, permissions, and sessions. You call query(prompt, options) and it drives everything.

Both are harness-only - you host and deploy them. The difference is scope of harness: the Tool Runner loops over tools you define (with per-turn hooks for approval, interception, result modification, and retries - but no buil