Claude Agent SDK Best Practices

Practical rules for taking a Claude Agent SDK agent from a working prototype to something safe to run in production, covering tool scoping, checkpoints, subagents, and sessions.

How to Use This List

Work through each lettered group before deploying an agent that touches real data, real systems, or real users.
Groups are roughly ordered by how early in an agent's lifecycle they matter: scoping and tools first, then safety gates, then delegation and continuity.
Treat this as a review checklist, not a tutorial; each item links back to the page that explains the reasoning in depth.

A - Tool Scoping

Enable only the tool families a task actually needs. An agent that only writes files doesn't need bash, web_search, or web_fetch; every enabled tool is additional surface area the loop can act on unsupervised.
Scope bash to an explicit command allowlist rather than granting an open shell. Unrestricted bash access turns one tool into an arbitrary-code-execution capability; a command allowlist keeps it to the specific operations the task requires.
Restrict file_edit to the paths a task should actually touch. Path or glob restrictions keep a monorepo-wide agent from editing files outside the package or directory it was asked to work on.
Prefer web_fetch over web_search when the URL is already known. web_search is a broader, less predictable capability; reserve it for genuinely open-ended research tasks.
Re-audit tool scope whenever a task's prompt changes meaningfully. Scope decisions made for one version of a task can silently become too broad or too narrow as the task's actual behavior evolves.

B - Human-in-the-Loop Checkpoints

Checkpoint destructive or irreversible actions, not every tool call. Gating harmless reads alongside genuine risks trains reviewers to rubber-stamp approvals without reading them.
Give every checkpoint hook an explicit timeout with a safe default. A hook that can block forever waiting on a human decision can hang a production run; default to reject when the window expires.
Build a real approval channel before deploying to a hosted environment. A blocking terminal prompt has no terminal to read from once an agent runs unattended on a server; route approvals through a queue, dashboard, or webhook instead.
Log every checkpoint decision alongside the call it applied to. Without an audit trail of what was approved or rejected and by whom, checkpoints lose the accountability they're meant to provide.
Layer checkpoints on top of tool scoping, never as a substitute for it. Scoping closes off entire classes of action; checkpoints only catch the specific calls you remembered to flag.

C - Subagents

Delegate only tasks that are genuinely independent. Splitting a task with real dependencies between subagents forces you to manually sequence and pass results, which erases the benefit of delegating in the first place.
Write subagent descriptions as specifically as tool descriptions. A vague description gives the parent model no reliable signal for when to invoke that subagent.
Scope each subagent's tools independently, not by copying the parent's scope. A subagent inherits nothing automatically; grant it only what its specific job requires.
Don't split a simple task into a subagent just to feel thorough. The overhead of a fresh context and a full internal loop isn't worth it for a step a single tool call would handle just as well.
Run independent subagents concurrently when the task allows it. Sequential dispatch of unrelated subagents wastes the parallelism isolation was supposed to enable.

D - Sessions & Continuity

Persist session IDs to storage that outlives the process. The SDK gives you the mechanism to resume; if the ID isn't stored durably, it's gone once the process exits.
Key sessions by a stable task identifier, not a fresh random value per call. A new key on every invocation means you never actually resume anything.
Handle a missing or expired session ID as an explicit failure case. Resuming with a stale ID should fail predictably and fall back to a fresh run, not silently produce an empty session.
Set a retention policy for stored session data. Session history can contain sensitive tool-result output; keeping it forever with no cleanup is a liability, not a convenience.
Don't rely on resume to replay side effects. Resuming restores the record of what already happened; it does not re-run bash commands or re-fetch URLs from the prior session.

E - Deployment & Operations

Match deployment shape to whether a human is present. Local CLI binary runs suit interactive, single-operator workflows; hosted execution suits unattended, scheduled, or multi-tenant workloads.
Rebuild checkpoint routing explicitly when moving from local to hosted. A terminal-based approval flow that worked locally becomes a silent hang or a no-op once the agent runs without a terminal attached.
Move secrets out of local files before deploying to a hosted environment. Read credentials from the platform's secrets manager, not from local environment files that won't exist in that environment.
Add structured logging once no operator is watching a terminal live. Hosted runs need observability built in, since there's no one present to notice a problem as it happens.

FAQs

Which of these groups matters most to do first?

Tool scoping (Group A), since it determines what the agent is capable of at all; checkpoints, subagents, and sessions all build on top of a well-scoped tool set.

Do I need checkpoints if my tools are already narrowly scoped?

If nothing reachable is destructive or irreversible, checkpoints add less value; but most agents that write files, run commands, or call external systems have at least one action worth gating.

Is it ever fine to skip session persistence?

Yes, for genuinely single-shot, stateless tasks where there's nothing meaningful to resume. Persistence matters once a task spans more than one process lifetime.

What's the single most common mistake teams make moving to production?

Assuming local development safety nets (a human watching the terminal, catching a bad checkpoint prompt) carry over automatically to a hosted deployment, when they need to be rebuilt explicitly.

Should every subagent have a checkpoint too?

Only if that subagent's own tool scope includes something destructive or irreversible; checkpoint configuration is set per AgentOptions, so it can differ between parent and subagent as needed.

How often should I re-review an agent's tool scope?

Whenever the underlying task or prompt changes meaningfully, and periodically as a matter of routine, since scope that was correct at launch can drift out of sync with what the agent actually does over time.

Do local CLI binary agents need any of this?

Most of it still applies, tool scoping and thoughtful subagent use in particular, even if checkpoint routing and hosted-specific concerns are simpler for a local, single-operator run.

What's the risk of over-scoping tools too narrowly?

An overly restrictive allowlist can cause the agent to fail mid-task on a legitimate action it needs, forcing you to loosen scope reactively; test the exact operations a task requires before locking down an allowlist.

The Claude Agent SDK Mental Model - the concepts these practices are grounded in
Enabling File Edit, Bash, and Web Tools in the Agent SDK - tool scoping in depth
Adding Human-in-the-Loop Checkpoints to an Agent SDK Workflow - checkpoint mechanics in depth
Delegating Work to Subagents in the Claude Agent SDK - subagent delegation in depth
Persisting Sessions Across Runs with the Claude Agent SDK - session persistence in depth
Claude Agent SDK Deployment Patterns Reference - local vs. hosted deployment trade-offs

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the Claude Agent SDK (latest release, Python and TypeScript). Model names, SDK versions, and pricing move quickly - verify current specifics at platform.claude.com/docs before relying on them.

Claude Agent SDK Best Practices

Practical rules for taking a Claude Agent SDK agent from a working prototype to something safe to run in production, covering tool scoping, checkpoints, subagents, and sessions.

How to Use This List

Work through each lettered group before deploying an agent that touches real data, real systems, or real users.
Groups are roughly ordered by how early in an agent's lifecycle they matter: scoping and tools first, then safety gates, then delegation and continuity.
Treat this as a review checklist, not a tutorial; each item links back to the page that explains the reasoning in depth.

A - Tool Scoping

Enable only the tool families a task actually needs. An agent that only writes files doesn't need bash, web_search, or web_fetch; every enabled tool is additional surface area the loop can act on unsupervised.
Scope bash to an explicit command allowlist rather than granting an open shell. Unrestricted bash access turns one tool into an arbitrary-code-execution capability; a command allowlist keeps it to the specific operations the task requires.
Restrict file_edit to the paths a task should actually touch. Path or glob restrictions keep a monorepo-wide agent from editing files outside the package or directory it was asked to work on.
Prefer web_fetch over web_search when the URL is already known. web_search is a broader, less predictable capability; reserve it for genuinely open-ended research tasks.
Re-audit tool scope whenever a task's prompt changes meaningfully. Scope decisions made for one version of a task can silently become too broad or too narrow as the task's actual behavior evolves.

B - Human-in-the-Loop Checkpoints

Checkpoint destructive or irreversible actions, not every tool call. Gating harmless reads alongside genuine risks trains reviewers to rubber-stamp approvals without reading them.
Give every checkpoint hook an explicit timeout with a safe default. A hook that can block forever waiting on a human decision can hang a production run; default to reject when the window expires.
Build a real approval channel before deploying to a hosted environment. A blocking terminal prompt has no terminal to read from once an agent runs unattended on a server; route approvals through a queue, dashboard, or webhook instead.
Log every checkpoint decision alongside the call it applied to. Without an audit trail of what was approved or rejected and by whom, checkpoints lose the accountability they're meant to provide.
Layer checkpoints on top of tool scoping, never as a substitute for it. Scoping closes off entire classes of action; checkpoints only catch the specific calls you remembered to flag.

C - Subagents

Delegate only tasks that are genuinely independent. Splitting a task with real dependencies between subagents forces you to manually sequence and pass results, which erases the benefit of delegating in the first place.
Write subagent descriptions as specifically as tool descriptions. A vague description gives the parent model no reliable signal for when to invoke that subagent.
Scope each subagent's tools independently, not by copying the parent's scope. A subagent inherits nothing automatically; grant it only what its specific job requires.
Don't split a simple task into a subagent just to feel thorough. The overhead of a fresh context and a full internal loop isn't worth it for a step a single tool call would handle just as well.
Run independent subagents concurrently when the task allows it. Sequential dispatch of unrelated subagents wastes the parallelism isolation was supposed to enable.

D - Sessions & Continuity

Persist session IDs to storage that outlives the process. The SDK gives you the mechanism to resume; if the ID isn't stored durably, it's gone once the process exits.
Key sessions by a stable task identifier, not a fresh random value per call. A new key on every invocation means you never actually resume anything.
Handle a missing or expired session ID as an explicit failure case. Resuming with a stale ID should fail predictably and fall back to a fresh run, not silently produce an empty session.
Set a retention policy for stored session data. Session history can contain sensitive tool-result output; keeping it forever with no cleanup is a liability, not a convenience.
Don't rely on resume to replay side effects. Resuming restores the record of what already happened; it does not re-run bash commands or re-fetch URLs from the prior session.

E - Deployment & Operations

Match deployment shape to whether a human is present. Local CLI binary runs suit interactive, single-operator workflows; hosted execution suits unattended, scheduled, or multi-tenant workloads.
Rebuild checkpoint routing explicitly when moving from local to hosted. A terminal-based approval flow that worked locally becomes a silent hang or a no-op once the agent runs without a terminal attached.
Move secrets out of local files before deploying to a hosted environment. Read credentials from the platform's secrets manager, not from local environment files that won't exist in that environment.
Add structured logging once no operator is watching a terminal live. Hosted runs need observability built in, since there's no one present to notice a problem as it happens.

FAQs

Which of these groups matters most to do first?

Tool scoping (Group A), since it determines what the agent is capable of at all; checkpoints, subagents, and sessions all build on top of a well-scoped tool set.

Do I need checkpoints if my tools are already narrowly scoped?

If nothing reachable is destructive or irreversible, checkpoints add less value; but most agents that write files, run commands, or call external systems have at least one action worth gating.

Is it ever fine to skip session persistence?

Yes, for genuinely single-shot, stateless tasks where there's nothing meaningful to resume. Persistence matters once a task spans more than one process lifetime.

What's the single most common mistake teams make moving to production?

Assuming local development safety nets (a human watching the terminal, catching a bad checkpoint prompt) carry over automatically to a hosted deployment, when they need to be rebuilt explicitly.

Should every subagent have a checkpoint too?

Only if that subagent's own tool scope includes something destructive or irreversible; checkpoint configuration is set per AgentOptions, so it can differ between parent and subagent as needed.

How often should I re-review an agent's tool scope?

Do local CLI binary agents need any of this?

Most of it still applies, tool scoping and thoughtful subagent use in particular, even if checkpoint routing and hosted-specific concerns are simpler for a local, single-operator run.

What's the risk of over-scoping tools too narrowly?

The Claude Agent SDK Mental Model - the concepts these practices are grounded in
Enabling File Edit, Bash, and Web Tools in the Agent SDK - tool scoping in depth
Adding Human-in-the-Loop Checkpoints to an Agent SDK Workflow - checkpoint mechanics in depth
Delegating Work to Subagents in the Claude Agent SDK - subagent delegation in depth
Persisting Sessions Across Runs with the Claude Agent SDK - session persistence in depth
Claude Agent SDK Deployment Patterns Reference - local vs. hosted deployment trade-offs

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the Claude Agent SDK (latest release, Python and TypeScript). Model names, SDK versions, and pricing move quickly - verify current specifics at platform.claude.com/docs before relying on them.

Claude Agent SDK Best Practices

Search Documentation

Claude Agent SDK Best Practices