APP · 33.1 %
Applications and integration
This domain covers integrating the Messages API into an application: message format, reading stop_reason, errors, rate limits and batch processing. It also tests operational choices: model IDs, third-party platforms and change discipline.
A stateless API
The Messages API keeps nothing between calls: the application resends the full history every turn, so input cost grows with the conversation. It adds no system prompt, unlike claude.ai or Claude Code: behavior depends only on what you send. In the Agent SDK, without a systemPrompt option, only a minimal prompt applies, and the claude_code preset restores CLI behavior.
Returning tool results
All tool_result blocks of a turn go in a single user message, right after the assistant message and before any text. There is no tool role: everything goes through user and assistant. Adding text after every result teaches Claude to end its turn, which produces empty responses with end_turn.
Read `stop_reason` before the content
max_tokens signals truncated output: an incomplete tool_use is retried with a higher cap. pause_turn signals that a server tool hit its iteration limit: send the response back unchanged so Claude resumes. refusal arrives with HTTP 200, so only stop_reason tells it apart from a success.
Streaming: where signals arrive
When streaming, stop_reason is null in message_start and only arrives in message_delta. An error that occurs after the 200 arrives as an error event in the stream, since the HTTP status has already been sent. Streaming improves perceived latency and protects long requests from idle-connection drops, without lowering cost.
Errors, retries and idempotency
The SDK already retries transient errors twice (connection, 408, 409, 429, 5xx): a homemade loop on top multiplies calls. Code branches on the status and error.type, never on message text, because new types can appear without a new API version; log the request-id for support. A retry is safe only on an idempotent operation: an idempotency key keeps a side-effecting tool from running twice.
Rate limits and concurrency
Limits follow a token bucket: capacity refills continuously, and a burst can trigger a 429 below the per-minute quota. Cache reads do not count toward ITPM, and max_tokens does not enter OTPM. For a large volume with a deadline, a bounded concurrency pool that honors retry-after gives a steady rate, and an async handler uses AsyncAnthropic so it does not block the event loop.
Message Batches API
Batch costs 50% of standard price in exchange for an unguaranteed delay: most batches finish in under an hour, but only the 24-hour expiry is a commitment. Results come back in arbitrary order and are matched by custom_id. Validation of params is asynchronous: an invalid request comes back errored, unbilled, without blocking the others.
What recent models reject
Since Claude 4.6, prefilling the last assistant turn returns a 400: use structured outputs or the system prompt instead. thinking and redacted_thinking blocks are sent back exactly as received, because the API checks their integrity. Several recent models (Opus 5.5, Sonnet 5.5, Fable 5.2) reject tool_choice any or tool: use auto with strict tool use, and let the application loop enforce step order.
Model IDs and lifecycle
Since the 4.6 generation, the dateless ID (claude-sonnet-4-6) is a fixed snapshot; before, the short alias followed the latest dated snapshot. Pinning fixes the weights, not availability: each ID has its own retirement date, announced at least 60 days ahead for public models, after which requests fail. So migrate early, backed by evals, and use the Console usage export to find keys still calling the old model.
Third-party platforms and hard constraints
On Google Cloud (Google managed) or Bedrock, the message shape stays the same, but authentication, endpoints, model IDs and features change: no Files API and no URL sources on Google managed, for example. Residency requirements remove options before any cost comparison. On the Claude API, inference_geo accepts global or us, whereas Google Cloud (Google managed) offers an eu multi-region endpoint.
PDF documents
Each PDF page is converted to an image and its text is extracted: both are billed, roughly 1,500 to 3,000 text tokens plus at most 1,568 image tokens per page. Cost therefore depends on page count, not file size. Placing the PDF before the question improves results.
Version prompts and changes
Prompts, model IDs, schemas and eval sets live in version control, go through review and are promoted on an eval score: an incident can then name the faulty version and roll back. The docs set success criteria and empirical tests as prerequisites for any prompt work. A structural change and a behavior change ship separately, with tests that first pin the behavior to preserve.
AGT · 14.7 %
Agents and workflows
Anthropic separates workflows, where code decides the next step, from agents, where the model decides. Most questions check that you pick the simplest architecture that works, and that control points rest on code or structured data.
Workflow or agent
There is one criterion: who picks the next step. If code fixes the path, it is a workflow, however many calls or tools it uses; if the model decides from the results so far, it is an agent. A workflow brings predictability and controlled cost, an agent trades latency and cost for flexibility, and that tradeoff has to be justified.
Start with the simplest solution
Anthropic recommends adding complexity only when it improves a measured result. A single well-built call, with retrieval or examples in the prompt, is often enough. A knowledge base under 200,000 tokens (about 500 pages) can go whole into the prompt, and prompt caching makes that approach fast and cheap.
Workflow patterns
Prompt chaining: fixed steps, with a programmatic check (a gate) between them. Routing: classify the input, then send it to a specialized handler. Parallelization: subtasks defined in advance in code (sectioning) or the same task run several times (voting). Orchestrator-workers: an LLM decomposes the task based on the input, useful when subtasks are unpredictable, such as the number of files to change.
Frameworks: understand what they generate
Frameworks speed up the start but add layers that hide the real prompts and responses, which makes debugging harder. Anthropic advises starting with the API directly, since most patterns take a few lines of code. With a framework, understand the underlying code: wrong assumptions about what it does are a common source of error.
A loop driven by `stop_reason`
A hand-written agent loop reads stop_reason on every response: tool_use, run the tools and return all results in one user message; pause_turn, send the content back unchanged to continue; end_turn, stop. The tool_use blocks of one turn are unordered, and each expects its tool_result. An iteration cap and a budget act as a safety net, and the presence of text never signals the end.
Absolute rules belong in a hook
An instruction, in the prompt or in CLAUDE.md, stays subject to the model's judgment: Claude reads it as context, with no guarantee it complies. A hook runs code at a fixed point of the lifecycle, every time: PostToolUse to format every edited file, PreToolUse to block a call. When a question says 'always', 'never' or 'without exception', look for the deterministic mechanism.
Subagents: an isolated context
A subagent starts with its own context: it sees neither the main conversation's history nor the files already read, and receives only the delegation prompt. Its tool calls stay inside it, and only its final message comes back. That isolation protects the main context (read 40 files, report only the synthesis), provided the delegation prompt carries every constraint that matters. The one exception is a fork, which copies the current conversation.
Structured handoffs between agents
An agent can only use what it receives. Require structured records from each subagent (path, symbol, lines, snippet), an explicit failure report (section, error type, partial results, whether a retry is possible) and the provenance of each claim (customer, tool, inference, verification status). A dependency between steps is checked in code, on a structured field, never on a word such as 'done'. An empty result marked as successful makes the error invisible downstream.
Agent SDK: loaded settings and loop results
The settingSources option decides what the SDK loads from disk: "project" for the project's CLAUDE.md, skills, hooks and permissions, "user" for ~/.claude. Omitted, it equals ["user", "project", "local"]; set explicitly, it must list every source you need. When the loop ends, the ResultMessage carries a subtype: the result text exists only on success, while cost, usage and session_id are present on every subtype. max_turns and max_budget_usd bound a run that otherwise continues until Claude stops.
Managed Agents or Agent SDK
With Managed Agents, Anthropic hosts the loop, the sandbox and tool execution; sessions are stateful and stored server-side, which suits long-running and asynchronous work. That storage has a price: no HIPAA eligibility, and ZDR only in the self-hosted variant. The Agent SDK runs in your application's process, which spawns one claude subprocess per session and owns hosting, persistence and scaling. A retention requirement can decide before any other criterion.