Thinking and Effort

Purpose and Scope

Thinking and effort are Claude Messages features for controlling reasoning behavior and token expenditure from the TypeScript SDK. In the Claude documentation, extended thinking gives Claude more room for complex reasoning and can return thinking-related content before the final answer. Adaptive thinking lets supported models decide dynamically when thinking is useful, while the effort parameter controls how eagerly the model spends tokens across the response. This page explains how those product concepts map onto the SDK surfaces exposed by client.messages and client.beta.messages, so application developers can choose the right request shape without treating thinking as a separate subsystem.

Sources: src/resources/messages/index.ts, src/resources/beta/messages/index.ts

The SDK does not implement reasoning locally. It provides generated TypeScript resources, exported request and response types, stream event types, and beta resource namespaces that serialize your request to the Claude API. That distinction matters for debugging: if a model rejects a manual thinking budget or interprets effort differently, the behavior comes from API and model support rules, while the SDK is responsible for exposing fields, sending requests, streaming events, and preserving typed response blocks. The generated stable Messages barrel exports thinking-related response block and delta types such as RedactedThinkingBlock, SignatureDelta, and OutputTokensDetails; the beta barrel exposes a broader experimental set including compaction and edit-related types.

Sources: src/resources/messages/index.ts, src/resources/beta/messages/index.ts

Core Concepts

Use effort when you want a single, model-supported control over response thoroughness and token efficiency. The official Claude docs describe effort as affecting all output tokens, including text explanations, tool calls, function arguments, and extended thinking when thinking is enabled. That makes it the simplest knob for latency, cost, and capability tradeoffs. In practice, omitting effort is equivalent to high effort according to the docs, while lower values bias toward conserving tokens and higher values bias toward more thorough responses. Because this is a request parameter on the Messages API, it belongs in the same call where you set model, messages, and max_tokens.

Use adaptive thinking when you want the model to decide whether a task needs visible or internal reasoning. The official docs position adaptive thinking as the recommended mode for newer Claude models and explain that some models always use adaptive thinking or reject fixed thinking budgets. Manual extended thinking with budget_tokens is therefore a compatibility choice for models that still support it, not a universal default. The SDK’s stable and beta Messages exports contain thinking-oriented block and stream type names, but the application still needs to follow the model matrix documented by Anthropic when choosing between thinking: { type: 'adaptive' }, thinking: { type: 'enabled', budget_tokens: N }, thinking: { type: 'disabled' }, and effort.

Relevant Source Files

• src/resources/messages/index.ts - Stable Messages barrel that re-exports the Messages resource and public response, content block, streaming delta, and thinking-related types used by normal client.messages calls.
• src/resources/beta/messages/index.ts - Beta Messages barrel that re-exports beta batches plus the expanded beta message type family, including compaction, clear-thinking edit, advisor, diagnostics, and beta thinking-turn types.
• src/internal/detect-platform.ts - Runtime detection helper used by the SDK to attach Stainless language, package, OS, architecture, runtime, and runtime-version metadata headers for Node, Deno, Edge, browser, and unknown runtimes.
• src/resources/beta/messages.ts - Short beta namespace bridge that re-exports the generated beta messages index from ./messages/index, making client.beta.messages resolve to the generated beta resource tree.
• src/resources/beta/messages/batches.ts - Beta Message Batches resource showing how beta message endpoints add beta=true routing and anthropic-beta headers for batch processing.
• src/resources/beta/messages/messages.ts - Generated beta Messages resource implementation for the beta message creation and streaming surface referenced by the beta barrel exports.

System-to-Code Mapping

The stable SDK path starts at the generated src/resources/messages/index.ts barrel. That file exports Messages, batch types, content block types, raw stream event types, and thinking-adjacent public types. For thinking workflows, the important design is that response content is represented as typed blocks and streaming is represented as typed deltas. A final message can contain text blocks, redacted thinking blocks, citations, tool-use blocks, or other content depending on the request and model behavior. A stream can deliver raw message events, content block starts and stops, message deltas, text deltas, JSON input deltas, citation deltas, and signature deltas. Your code should therefore branch on block or event type rather than assuming every response is plain text.

Sources: src/resources/messages/index.ts

The beta SDK path widens the same idea. src/resources/beta/messages.ts re-exports ./messages/index, and src/resources/beta/messages/index.ts exports both beta batches and the beta Messages resource. The beta barrel includes types whose names point to additional experimental workflows: BetaAllThinkingTurns, BetaClearThinking20251015Edit, BetaCompact20260112Edit, BetaCompactionBlock, BetaCompactionContentBlockDelta, BetaCompactionIterationUsage, and context-management response types. For developers, this means beta thinking and compaction capabilities are accessed through client.beta.messages and beta-specific request headers or parameters, not by importing a separate reasoning client.

Sources: src/resources/beta/messages.ts, src/resources/beta/messages/index.ts, src/resources/beta/messages/messages.ts

Request Patterns

A minimal effort-oriented call looks like an ordinary Messages request with one additional model-control field. Choose the model first, then decide whether you are using adaptive thinking, explicit thinking, or only effort. Keep max_tokens large enough for both reasoning-related output and final answer text, because token limits still apply to the total response. When streaming, treat thinking and answer content as separate typed events if they appear; do not concatenate unknown delta types into user-visible prose unless your product intentionally displays them.

import Anthropic from '@anthropic-ai/sdk';
 
const client = new Anthropic();
 
const message = await client.messages.create({
  model: 'claude-sonnet-5',
  max_tokens: 2048,
  effort: 'medium',
  thinking: { type: 'adaptive' },
  messages: [
    { role: 'user', content: 'Compare two migration plans and recommend one.' },
  ],
});
 
for (const block of message.content) {
  if (block.type === 'text') console.log(block.text);
}

The same rules apply when you move from single requests to batches. The beta batch resource sends message-creation requests to /v1/messages/batches?beta=true, adds the message-batches-2024-09-24 beta header, and accepts each batch item’s normal message params. If those params include thinking or effort fields that are valid for the selected model, the batch API processes them as part of each individual message request. Batches are useful when many complex reasoning tasks can run asynchronously, but they are not a streaming interface; use streaming when your application needs incremental deltas, and batches when throughput matters more than immediate token-by-token feedback.

Sources: src/resources/beta/messages/batches.ts

Streaming, Compaction, and Runtime Behavior

Streaming thinking workflows should be written as event processors. The stable message exports include raw message stream event types and content block delta types, while the beta exports include beta compaction deltas and iteration usage types. This shape encourages a reducer-style implementation: initialize state on content block start, append text or structured deltas as they arrive, record signatures or usage metadata separately, and finalize the block on stop events. That approach also keeps your UI resilient when a model emits redacted thinking, hidden thinking, signatures, tool calls, or compaction events rather than ordinary answer text.

Compaction is a beta-oriented concept exposed in the generated beta type surface through names such as BetaCompact20260112Edit, BetaCompactionBlock, BetaCompactionContentBlockDelta, and BetaCompactionIterationUsage. In long-running or agentic conversations, compaction-related responses can help represent summarization or context-management work as structured content instead of opaque text. Treat those beta types as part of the beta Messages contract: isolate them behind your own adapter, check the exact beta headers and model requirements in the API docs, and avoid assuming the shape is identical to stable message content. The generated beta namespace makes these capabilities discoverable while preserving a boundary between stable and experimental behavior.

Sources: src/resources/beta/messages/index.ts, src/resources/beta/messages/messages.ts

Runtime behavior is also relevant for production thinking workloads because longer reasoning and streaming sessions can expose environment differences. The SDK’s platform detector identifies Deno, Edge Runtime, Node, browser, and unknown environments, then builds X-Stainless-* metadata such as package version, OS, architecture, runtime, and runtime version. These headers do not change reasoning semantics, but they help the SDK and API observe where requests originate. If you see different network or stream behavior across Node, Deno, Vercel Edge, or browser-enabled deployments, separate transport/runtime troubleshooting from Messages request-shape troubleshooting.

Sources: src/internal/detect-platform.ts

Compact Reference

Next Steps

When adding thinking or effort to an application, first choose the Claude model and verify the current model-specific thinking mode in the official docs. Then implement the SDK call as a normal Messages request, with a typed response parser that branches on content block and stream event types. For interactive products, test both non-streaming and streaming paths because thinking, redaction, signatures, and compaction are easiest to handle correctly when the reducer is designed up front. For high-throughput offline work, evaluate Message Batches after the single-request behavior is correct, and keep beta compaction or edit handling isolated so it can evolve with the beta API.