Claude API#

The claude-api skill in anthropics/skills is the authoritative reference for building applications on Anthropic's Claude API. It covers two distinct product surfaces — the Claude API (direct SDK calls and tool-use workflows) and Managed Agents (Anthropic-hosted stateful agents) — plus supporting topics like prompt caching, model versions, thinking/effort parameters, and model migration 1.

Entry point: skills/claude-api/SKILL.md — includes trigger conditions, surface selection decision tree, architecture notes, and current model reference. Language-agnostic concept docs live in skills/claude-api/shared/; language-specific examples are under {lang}/managed-agents/README.md 2.

Trigger conditions: The skill activates when code imports anthropic, @anthropic-ai/sdk, or claude_agent_sdk; when users ask about Claude API, Anthropic SDK, or Managed Agents; or when modifying Claude-specific features (caching, thinking, tool use, batches, files, memory). It is skipped for OpenAI/other-provider SDKs or provider-neutral code 3.

Choosing a Surface#

Start with the simplest tier that meets your needs 4:

5

Third-party providers: Managed Agents is not available on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry. Use Claude API + tool use for all use cases on those platforms 6.

Before reaching for the agent tier, verify all four criteria apply: Complexity (multi-step, hard to fully specify in advance), Value (outcome justifies cost/latency), Viability (Claude is capable at this task type), and Cost of error (errors can be caught and recovered from). If any criterion fails, stay at a simpler tier 7.

Claude API Surface#

All Claude API usage routes through POST /v1/messages. Tools and output constraints are features of this single endpoint.

Tool use options 8:

• SDK tool runner — define tools via decorators/Zod schemas; the SDK handles the call-execute-loop automatically.
• Manual loop — write the loop yourself for approval gates, custom logging, or conditional execution.

Supporting endpoints feed into or supplement the Messages API 9:

• POST /v1/messages/batches — batch processing
• POST /v1/files — file uploads
• GET /v1/models / GET /v1/models/{id} — live model capability and context-window discovery

Current default model: Always use claude-opus-4-7 unless the user specifies otherwise 10. Full model table with IDs and pricing is in SKILL.md lines 166–171.

Thinking & Effort 11:

• New code should use thinking: {type: "adaptive"} — budget_tokens is deprecated on Opus 4.6+ and removed on Opus 4.7.
• Control compute depth via output_config: {effort: "low"|"medium"|"high"|"max"|"xhigh"}. "xhigh" is Opus 4.7-only and the default in Claude Code; "max" is Opus-tier only.
• Full migration notes: shared/model-migration.md.

Managed Agents#

Managed Agents is an Anthropic-hosted service where the agent loop and tool-execution sandbox run on Anthropic's infrastructure (or your own, with self-hosted sandboxes). All SDK methods are under the client.beta.* namespace and require the beta header anthropic-beta: managed-agents-2026-04-01 12.

Two-Step Mandatory Flow#

1. Create an agent once (POST /v1/agents): store model, system prompt, tools, MCP servers, and skills. This creates a persisted, versioned config. Store the returned agent.id 13.
2. Start a session per run (POST /v1/sessions): reference the agent by ID. Each session provisions a workspace container. Never call agents.create() on every run — it accumulates orphaned agents 14.

Three Configuration Tiers#

15

Built-in Tools (agent_toolset_20260401)#

Eight built-in tools run inside the session container 16: bash, read, write, edit, glob, grep, web_fetch, web_search.

Three tool types are available 17:

• Prebuilt agent tools — run on Anthropic's (or your self-hosted) infrastructure
• MCP tools — capabilities from connected MCP servers
• Custom tools — your application handles execution via the agent.custom_tool_use event / user.custom_tool_result response round-trip

Event Stream#

Sessions emit 17+ typed events across three namespaces:

• Agent — agent.message, agent.thinking, agent.tool_use, agent.tool_result, agent.mcp_tool_use, agent.custom_tool_use, agent.thread_context_compacted
• Session status — session.status_idle, session.status_running, session.status_rescheduled, session.status_terminated, session.error
• Span — span.model_request_start/end, span.outcome_evaluation_*

Events can be received via SSE stream (GET .../events/stream), polling (GET .../events), or webhooks 18.

Client Patterns#

Key patterns from managed-agents-client-patterns.md:

• Stream-first ordering — open the SSE stream before sending events; opening after may miss early status transitions 19.
• Lossless reconnect — on reconnect, fetch history via events.list(), then dedup against the live stream on event ID 20.
• UI state via processed_at — client-sent events appear twice (once with processed_at: null, once with a timestamp); use this to track pending → acknowledged state 21.
• Interrupt — send user.interrupt; the session finishes its current safe boundary before going idle 22.

Key API Endpoints#

Full reference: shared/managed-agents-api-reference.md. Core endpoints 23:

Agents have no delete operation — archive is permanent and read-only 24.

Language Support#

25

Language-specific implementation guides: python/managed-agents/README.md, typescript/managed-agents/README.md, and equivalents for Go, Ruby, PHP, Java, and cURL under their respective {lang}/managed-agents/ directories 2.

Key Files Reference#