Claude 4.6 Agent Tool Use Patterns for Production (2026)

Most production failures with Claude-driven agents in 2026 are not model failures. They are loop-design failures: the agent runs forever, calls tools serially when it could fan out, accumulates a 600-kilotoken transcript that no one ever evicts, or quietly drops a tool error and confidently asserts a wrong answer. Claude 4.6 agent tool use patterns are the small set of choices — parallel dispatch, sub-agent fan-out, tiered memory, structured retries, and prompt caching — that decide whether a deployed agent stays inside a sane cost and latency envelope or burns a five-figure monthly bill on retries. The model itself is rarely the bottleneck once Sonnet 4.6 and Opus 4.6 land; the orchestration around it is.

Architecture at a glance

This post is a working architect’s view of those patterns. We walk through how Claude 4.6 issues tool calls, how to write the loop that handles them, when to spawn sub-agents versus keep one thread, how to lay out memory across three tiers, and the specific failure modes that recur in every production deployment.

Context: what changed in the 4.6 generation

Claude 4.6 is best understood as the iteration where Anthropic optimised tool-use accuracy and parallel-tool emission rather than raw reasoning. Sonnet 4.6 carries a 1M-token context option, Opus 4.6 stays at 200K but answers harder planning questions, and both expose extended_thinking and prompt caching with cache_control breakpoints. For agent builders, the practical effect is that you can keep more state in-context and pay less to re-read it.

The previous generation already had a tool_use content block, but the loop semantics were largely the developer’s responsibility. In 4.6, three changes matter most. First, the model emits multiple tool_use blocks per assistant turn far more often when the task admits parallelism, which means your dispatcher must handle a list, not a single call. Second, extended_thinking is exposed as a first-class block with a budget_tokens parameter, so planning is no longer a hand-rolled chain-of-thought. Third, the Anthropic Agent SDK in 2026 standardises a sub-agent primitive that runs an inner Claude call with an isolated context and returns only a summary to the parent — what used to require glue code is now a library call.

The other reason this matters in 2026 is cost geometry. The cache_control mechanism lets you mark a prefix of your prompt as cacheable for five minutes (or one hour with ttl=1h), and cache hits read at roughly a tenth of the input-token price. That changes which patterns are economical: long-running agents that re-feed the same system prompt and tool catalogue dozens of times per session are now bandwidth-limited rather than cost-limited, provided you set the breakpoints right. The architectural decisions in this article all assume that lever is in use. For the broader memory picture across agent generations, see our companion piece on agent memory layering for long-running workflows, which complements the loop-side view here.

A quick orientation to the source-of-truth surfaces: the Anthropic Messages API and the tools parameter are documented under the Anthropic platform reference for tool use, and the Model Context Protocol that several agents in this article speak to is specified at Model Context Protocol. Both are stable enough to build against today.

The core reference architecture

A production Claude 4.6 agent is a loop around the Messages API that holds five subsystems: a planner using extended_thinking, a tool registry, a dispatcher that runs tool_use blocks (in parallel where possible), a result reducer that builds tool_result messages, and a tiered memory store. Sub-agents attach as a special tool that spawns an inner loop with its own context. Everything else — observability, rate limiting, eval — wraps this skeleton.

Figure 1 — The minimal production agent: a single Messages-API loop with a parallel dispatcher, three memory tiers, and sub-agents that attach as a tool.

The orchestrator is intentionally thin. It does not interpret the model’s text; it interprets the stop_reason and the typed content blocks. The model decides what to do next; the orchestrator decides how to execute that decision safely. That separation is what lets you reason about correctness, cost, and timeouts independently. When teams conflate the two — for example, by parsing model prose to decide on retries — every failure becomes a prompt-engineering problem and nothing is ever testable.

The tool registry is a typed contract. Each tool has a JSON schema for its inputs and a Python (or TypeScript) handler that takes the validated arguments and returns either a serialisable result or a structured error. The schema is what Claude sees; the handler is what your infrastructure runs. The dispatcher’s job is to take the tool_use blocks from one assistant turn, validate each against its schema, dispatch them in parallel where they are independent, collect the results with timeouts, and assemble them into the next user-turn message as a list of tool_result blocks — preserving the tool_use_id so Claude can match each result back to its call.

Here is the loop in its minimal form, with the 2026 SDK conventions:

# anthropic >= 0.40 ; python >= 3.11
import anthropic, asyncio, json
from typing import Any

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY
MODEL = "claude-sonnet-4-6"
MAX_TURNS = 12

TOOLS = [
    {
        "name": "search_docs",
        "description": "Full-text search over the product docs corpus.",
        "input_schema": {
            "type": "object",
            "properties": {"q": {"type": "string"}, "k": {"type": "integer", "default": 5}},
            "required": ["q"],
        },
    },
    {
        "name": "run_sql",
        "description": "Run a read-only SQL query against the analytics warehouse.",
        "input_schema": {
            "type": "object",
            "properties": {"sql": {"type": "string"}},
            "required": ["sql"],
        },
    },
]

HANDLERS = {
    "search_docs": lambda args: docs_index.search(args["q"], k=args.get("k", 5)),
    "run_sql":     lambda args: warehouse.read_only(args["sql"], timeout=15),
}

async def dispatch(tool_use_blocks: list[dict]) -> list[dict]:
    async def run_one(block):
        try:
            result = await asyncio.to_thread(HANDLERS[block["name"]], block["input"])
            return {"type": "tool_result", "tool_use_id": block["id"],
                    "content": json.dumps(result)[:8000]}
        except Exception as e:
            return {"type": "tool_result", "tool_use_id": block["id"],
                    "is_error": True, "content": f"{type(e).__name__}: {e}"}
    return await asyncio.gather(*(run_one(b) for b in tool_use_blocks))

async def agent_loop(user_msg: str) -> str:
    messages = [{"role": "user", "content": user_msg}]
    for turn in range(MAX_TURNS):
        resp = client.messages.create(
            model=MODEL, max_tokens=4096, tools=TOOLS,
            system=[{"type": "text", "text": SYSTEM_PROMPT,
                     "cache_control": {"type": "ephemeral"}}],
            messages=messages,
        )
        messages.append({"role": "assistant", "content": resp.content})
        if resp.stop_reason == "end_turn":
            return "".join(b.text for b in resp.content if b.type == "text")
        if resp.stop_reason == "tool_use":
            tool_uses = [b.model_dump() for b in resp.content if b.type == "tool_use"]
            results = await dispatch(tool_uses)
            messages.append({"role": "user", "content": results})
            continue
        raise RuntimeError(f"unhandled stop_reason: {resp.stop_reason}")
    raise RuntimeError("max turns exceeded")

That is the entire skeleton. Every production system in this article is a refinement of those forty lines: smarter dispatch, smarter memory, smarter halting. Note three details. The cache_control marker on the system block tells Anthropic to cache the prompt prefix; you pay full input rate the first call and roughly 10% on subsequent calls within the TTL. The dispatcher runs tools in parallel via asyncio.gather, which is the only correct response to a list of tool_use blocks — running them sequentially throws away the model’s planning work. And the loop halts on stop_reason == "end_turn", never on the text content, because text without an end_turn is just thinking.

Deep dive: the five patterns that decide production behaviour

Parallel tool use — what Claude emits and how to handle it

Claude 4.6 frequently returns two to five tool_use blocks in a single assistant message when the planner determines they are independent. The model has been trained to recognise tasks like “compare X and Y” or “fetch data for these three customers” as parallelisable. The wrong thing to do is loop through them serially; the right thing is to dispatch them concurrently and return all tool_result blocks in a single subsequent user message, in any order — Claude matches them by tool_use_id.

The sequence below shows the canonical multi-turn loop with a parallel batch, a partial failure, and a retry. This is the shape of every well-behaved agent transcript:

Figure 2 — A typical Claude 4.6 turn pattern: model emits three tool_use blocks in parallel, one fails, the orchestrator surfaces is_error=true, and the model decides to retry only the failed one.

A subtle but important rule: every tool_use block in an assistant turn must be answered with a tool_result block (matching tool_use_id) before the next assistant turn. If you drop one — for example because a tool timed out and you chose not to report it — the next API call returns an invalid_request_error complaining about an unmatched tool_use_id. Always respond, even if the response is {"is_error": True, "content": "timeout after 30s"}. Surfacing the failure to the model is what lets it decide whether to retry, fall back, or surrender.

The retry policy itself deserves explicit design. Idempotent reads (search_docs, run_sql over read replicas, HTTP GETs) can be retried automatically inside the dispatcher with exponential backoff before the failure ever reaches Claude — that saves a full round-trip and a turn of context. Non-idempotent writes must never be auto-retried; surface them as is_error=True and let the model decide whether to confirm with the user or take a different approach. The split is the same one you would draw in any distributed system, and the agent loop does not exempt you from it.

Two anti-patterns recur. The first is putting the parallel-dispatch logic inside the tool handler — “I’ll have search_docs call run_sql if it needs to”. That hides the parallelism from Claude and silently slows the loop. The second is collapsing tool_result content into a single string. Keep results structured (JSON is fine) and truncated to a known character budget per tool — typically 4-16 KB — so a chatty tool cannot blow the context window in one turn.

Sub-agents — when isolation beats sharing

The sub-agent pattern is the single highest-leverage move for long-running Claude 4.6 workflows because it bounds context bloat: a parent agent calls a sub-agent for a self-contained task, the sub-agent runs its own loop with its own (much smaller) context, and only its final summary returns to the parent. The parent stays lean; cost stays linear in the number of branches rather than quadratic in turns.

Figure 3 — The decision is mechanical once you know token budget and parallel speed-up: independent context plus >40k expected tokens or >1.5x parallel gain pushes to sub-agents.

In the Anthropic Agent SDK 2026, a sub-agent is exposed to the parent as a tool with a spawn semantics. The handler takes a brief and a tool subset, runs an inner agent_loop with its own message history, and returns the assistant’s final text:

SUBAGENT_TOOLS = [t for t in TOOLS if t["name"] in {"search_docs", "run_sql"}]

async def spawn_subagent(args: dict) -> str:
    """Tool handler that runs an inner Claude 4.6 loop in isolation."""
    sub_messages = [{"role": "user", "content": args["brief"]}]
    for _ in range(8):
        r = client.messages.create(
            model="claude-sonnet-4-6", max_tokens=2048,
            tools=SUBAGENT_TOOLS, messages=sub_messages,
            system="You are a research sub-agent. Return a tight summary, "
                   "no preamble, max 500 words.",
        )
        sub_messages.append({"role": "assistant", "content": r.content})
        if r.stop_reason == "end_turn":
            return "".join(b.text for b in r.content if b.type == "text")
        if r.stop_reason == "tool_use":
            tools = [b.model_dump() for b in r.content if b.type == "tool_use"]
            sub_messages.append({"role": "user", "content": await dispatch(tools)})
    return "[subagent: max turns reached]"

# Register as a tool exposed to the parent
TOOLS.append({
    "name": "research_subagent",
    "description": "Spawn an isolated research sub-agent for a focused question. "
                   "Use when the question would take >5 of your own turns.",
    "input_schema": {
        "type": "object",
        "properties": {"brief": {"type": "string"}},
        "required": ["brief"],
    },
})
HANDLERS["research_subagent"] = lambda a: asyncio.run(spawn_subagent(a))

The decision of when to spawn is mechanical, not aesthetic. If the sub-task is independent of the parent’s running state, will likely cost more than 40K tokens to resolve in-line, or can be parallelised with sibling sub-tasks for at least a 1.5x wall-clock gain, spawn. Otherwise, keep it in-line. Sub-agents pay for themselves because each one re-pays only its own brief and its own tool catalogue rather than dragging the parent’s full transcript into every call. In practice, three to five parallel sub-agents is the sweet spot before coordination overhead and rate limits dominate.

The non-obvious cost is the brief. A sloppy brief means the sub-agent wanders and burns its own budget; a precise brief is what makes the pattern economical. Treat the brief like a function signature: state the question, the success criterion, the input data, the output format, and any hard constraints. The parent’s planning step should produce briefs explicitly.

One more discipline: cap each sub-agent’s max_turns independently and lower than the parent’s. A parent with max_turns=15 calling four sub-agents each at max_turns=6 gives you a worst-case 15 + 4 * 6 = 39 inner Anthropic calls, which is the right order of magnitude. The same parent calling sub-agents with no inner cap can balloon to hundreds before a single human notices. Sub-agents do not relax the halting discipline; they multiply the surface where you have to apply it.

Memory architecture — three tiers, three eviction policies

Production Claude 4.6 agents need three memory tiers — ephemeral (the context window itself), session (Redis or Postgres holding the last N turns and a rolling summary), and persistent (vector DB plus long-term KV) — because each tier has a different cost, latency, and durability profile and no single store handles all three.

Figure 4 — The three memory tiers and how data flows between them; the rolling summariser is what keeps the context window from drifting toward its hard limit.

The ephemeral tier is the context window plus prompt-cache breakpoints. Anything in here costs full input tokens until cached, then about 10% on cache hits within the 5-minute or 1-hour TTL. You want the system prompt, the tool catalogue, and any large static reference (a code repo manifest, a customer record) all marked with a single cache_control breakpoint at the largest stable prefix you can identify. Order matters: cache hits require an exact prefix match, so put volatile content (the user message, recent tool results) strictly after the cacheable prefix.

The session tier holds the last 30-100 turns plus a rolling summary keyed by run_id. After each turn the orchestrator appends the new messages, and a background task triggered every K turns compresses everything older than the last 20 turns into a 1-2K-token summary that replaces them in the context window. The pattern matters more than the store; Redis works for small teams, Postgres with JSONB for larger ones. Cross-reference with our deeper treatment of long-running agent memory tiers and write-through patterns for the write-back details.

The persistent tier is vector retrieval plus a small KV store of stable facts. The vector DB (pgvector for most teams, a dedicated store at scale) holds historical transcripts, documents, and tool outputs indexed by embedding. A retrieval step at the top of each turn pulls top-k chunks and appends them to the context after the cacheable prefix. The KV store holds atomic facts that should not be re-derived — user preferences, account IDs, prior decisions — keyed by user or tenant.

The rule of thumb: ephemeral for the current turn, session for the current task, persistent for the next session. Crossing those boundaries (writing every turn to the vector DB, for example) is what makes memory subsystems expensive and slow.

Planning with extended_thinking and explicit scratchpads

extended_thinking is Claude 4.6’s first-class scratchpad: you set a budget_tokens (typically 4K-16K) and the model returns a thinking content block before the tool_use or text blocks. You do not show that block to users, but you must echo it back in the messages array on the next turn or the model loses the plan. Used well, it cuts the number of turns substantially for multi-step tasks because the model commits to a plan up front rather than re-discovering it on every loop iteration.

resp = client.messages.create(
    model="claude-opus-4-6",  # planning tasks benefit from Opus
    max_tokens=8192,
    thinking={"type": "enabled", "budget_tokens": 8000},
    tools=TOOLS, messages=messages,
)
# resp.content now contains [ThinkingBlock, ToolUseBlock, ToolUseBlock, ...]
# Persist the ThinkingBlock back into messages on the next turn.
messages.append({"role": "assistant", "content": resp.content})

The trade-off is latency and tokens. An 8K-token thinking budget adds wall-clock time and adds those tokens to your input bill on subsequent turns. The pattern that works: enable extended_thinking on the first turn of a task (where planning value is highest) and on the last turn (where synthesis value is highest), and disable it on intermediate tool-call turns where the work is mechanical dispatch. Some teams flip this — always-on extended_thinking with a small 2K budget — and that is also defensible; what is not defensible is leaving it on with a 16K budget for 20 turns.

State machine and halting — the boring part that breaks first

Every agent runs as a state machine, and the most common production incident is a missing halt condition. The five states are planning, tool-call, waiting, reducing, and recovering; transitions are driven by stop_reason, tool outcomes, and budget checks. Build it explicitly.

Figure 5 — The five-state machine that every Claude 4.6 agent implicitly runs; making the halt transitions explicit is what prevents runaway loops.

Halt conditions worth enforcing as code rather than prompt instructions: a hard max_turns cap (8-15 for most tasks, 50 only when extended_thinking has explicitly planned that many), a token budget per run (sum input + output across all turns and abort when exceeded), a wall-clock deadline (the agent loses if it takes more than, say, three minutes for an interactive task), and a per-tool retry limit so a flapping downstream cannot pull the whole agent into a hot loop. Tag every halt with a reason so observability can distinguish “finished correctly” from “ran out of budget” from “tool unavailable”, because those have very different remediation paths.

Trade-offs and failure modes

When NOT to use an agent loop at all

The agent loop is the wrong tool when the task is a single, well-specified transformation: classification, extraction, translation, summarisation of a fixed-length input. A single messages.create call with strict output (JSON mode or a single tool the model is forced to call) is cheaper, faster, and more reliable. The agent pattern earns its overhead only when the model genuinely needs to interleave reasoning with external observations — code generation that compiles and tests, multi-source research, multi-step database operations. If you can write down the steps in advance and they will not change, write them down and call the API once per step from your own orchestrator.

A second case where the loop is wrong: latency-bounded interactive UX. A loop with three turns at one second each is a three-second wait before the user sees a final answer. For chat interfaces, prefer a single streaming call with the tools surfaced as suggestions (“would you like me to run X?”) that the user explicitly approves, unless the task truly cannot be answered without tool data.

Runaway loops, hallucinated arguments, and context bloat

Three failure modes account for the majority of production incidents. Runaway loops happen when the model keeps emitting tool_use with no progress — usually because a tool keeps returning empty results and the model retries with marginally different arguments. The fix is the hard max_turns cap above plus a “no-progress” detector that compares the last two tool-call signatures and forces an end_turn if they are identical.

Hallucinated tool arguments — Claude inventing a parameter name not in the schema or passing a wrong type — should already be caught by Pydantic or jsonschema validation in the dispatcher. The right response is to return an is_error=True tool_result with the validation message, not to silently coerce. Claude 4.6 is good at reading those errors and correcting itself within one turn; the bug is letting an invalid call through.

Context bloat is the slow killer. Each turn appends thousands of tokens of tool results to the messages array, and by turn ten the input is bigger than the original prompt by an order of magnitude. The mitigations stack: truncate every tool_result content to a known byte budget, summarise older turns into a rolling summary (see memory section), and split the work into sub-agents whose contexts do not bleed into the parent. None of these is optional at scale.

Tool schema drift and the silent regression

The least visible failure mode is tool schema drift: someone changes a tool’s input schema, the dispatcher accepts both old and new shapes, but Claude is still being told the old schema and quietly produces the wrong field names. Pin the schema in a single source of truth — typically a Pydantic model or a TypeBox schema — and generate both the API-facing JSON schema and the handler’s argument types from it. Add a contract test that asserts the schema sent to Anthropic round-trips through the handler. This catches the drift at CI time rather than at 3 AM.

A related issue: cost-from-caching regressions. If anything before your cache_control breakpoint changes between calls — even whitespace — the cache misses and you silently pay 10x. Treat the cacheable prefix as immutable per session and assert on the first response’s cache_read_input_tokens field in CI.

A final, rarer mode worth naming: model-version pinning drift. If you pin to a generic alias like claude-sonnet-4 rather than a dated revision like claude-sonnet-4-6-20260420, an upstream point release can shift tool-use formatting in ways your dispatcher tolerates but your evals do not. The cost is not catastrophic — Claude 4.6 is backward-compatible at the API level — but the behaviour shift can quietly raise turn counts by 10-20% on edge-case prompts. Pin to a dated model in production and roll forward deliberately, with a small offline eval suite that exercises your top three workflows on the candidate model before you flip the flag.

Practical recommendations

Build the boring scaffolding first. The model gets better every six months; your loop, memory, and observability get better only when you write them.

• Implement a single agent_loop with explicit max_turns, max_input_tokens, and deadline_seconds parameters. Tag every halt with a reason.
• Dispatch tools in parallel via asyncio.gather; never iterate tool_use blocks serially.
• Always return a tool_result for every tool_use_id, including timeouts and validation failures, with is_error=True where appropriate.
• Mark the system prompt and tool catalogue with cache_control: ephemeral and put all volatile content strictly after that breakpoint.
• Spawn sub-agents when a sub-task is independent and likely > 40K tokens; brief them like function signatures.
• Use extended_thinking with a 4K-8K budget on the first and last turn only; turn it off for mechanical dispatch turns.
• Truncate every tool_result content to a known byte budget (4-16 KB) before appending.
• Run a CI contract test that the tool schema in code matches the schema Anthropic receives.
• Log cache_read_input_tokens and input_tokens per turn; alert when cache-hit ratio drops below your baseline.
• For inference-side cost geometry that interacts with prompt caching, study KV cache optimisation for LLM inference — the same memory mechanics determine why caching works.

For deeper grounding in the underlying transformer mechanics that make routing and caching possible at all, our piece on the mixture-of-experts LLM architecture covers the model-internal counterpart to these orchestration patterns.

FAQ

When should I use Opus 4.6 over Sonnet 4.6 for an agent?

Use Opus 4.6 when planning quality dominates the cost equation — long-horizon tasks where one bad plan costs many turns. Use Sonnet 4.6 for high-throughput mechanical tool dispatch where the planning is already done. A common pattern is hybrid: Opus on the first turn with extended_thinking to produce the plan, then Sonnet on subsequent turns executing that plan against tools. Cost is roughly 5x in Opus’s favour for the planning premium, but you avoid the turn-count blow-up that bad planning causes.

How do I parse multiple tool_use blocks reliably?

Iterate resp.content filtering for block.type == "tool_use", dispatch all of them concurrently with asyncio.gather, and return a single user message whose content is a list of tool_result blocks each tagged with the original tool_use_id. Order in the returned list does not matter; Anthropic matches by ID. Never send the next assistant turn until every tool_use_id has a corresponding result, even if the result is is_error=True.

What is the right max_turns for a long-running agent?

Set max_turns to the smallest number that lets your most complex realistic task finish, then add 25%. For most production tasks that is 8-15; research-style fan-out with sub-agents may need 30-50, but only if the planner explicitly forecast that many. Treat hitting max_turns as an incident, not a soft failure: log the full transcript, the last plan, and the budget consumed, because it usually means a tool is degraded or the prompt has changed.

How does prompt caching interact with tool definitions?

Tool definitions are part of the cacheable prefix when you place the cache_control breakpoint after the tools array in your request, which the SDK does by default if you mark the system block. As long as the tools list is byte-identical between calls within the TTL, cache hits include them. Adding or removing a tool invalidates the cache; renaming a tool’s description does too. Keep the tool catalogue stable per session and version it explicitly when you change it.

When do sub-agents cost more than they save?

When the sub-task is small (< 5K tokens), highly dependent on parent state (so the brief must drag most of the parent context anyway), or sequential rather than parallel. The crossover is roughly: if the sub-agent’s prompt-plus-tool-catalogue is larger than what it would have added to the parent’s transcript in-line, you have lost. Measure with usage.input_tokens from both paths on a representative task before committing to the pattern.

How do I prevent the agent from making expensive or destructive tool calls?

Two layers. First, design tools to be safe by default: read-only by default, write tools behind explicit confirm=True parameters, destructive tools behind a separate API key. Second, gate the dispatcher: before executing any tool whose name starts with write_, delete_, send_, or pay_, route through a human-in-the-loop step (Slack approval, UI confirmat