Claude Agent SDK: Python, TypeScript, Pricing & Setup (2026)

The Claude Agent SDK is useful when a normal model call is too small a unit of work. Instead of manually wiring a prompt, tool call, approval step, and follow-up request, you give an agent a task and define the boundaries around what it may do. The important design question is not “how do I make Claude call a tool?” It is “which actions can this agent take without surprising the person or system that owns it?”

This guide focuses on that boundary: the agent loop, tools, permissions, MCP servers, sessions, and a provider gateway. It does not claim that every feature is available in every SDK release. Check the official Claude Code SDK documentation before pinning a package or model.

Claude Agent SDK vs the Messages API

Use the Messages API when your application owns the loop: send a request, inspect the response, execute a known function, and send the result back. Use the Agent SDK when you want a coding-agent style loop with built-in tool orchestration, streamed events, permission decisions, and resumable sessions.

That distinction affects testing. A Messages API unit test can assert one response. An agent test must also assert the tool policy, maximum turns, filesystem scope, network access, and behavior when a user denies an action.

TypeScript and Python quickstart

Anthropic’s current Agent SDK documentation lists packages for both TypeScript and Python. Install the package in a project-specific environment, then pin the version you reviewed:

npm install @anthropic-ai/claude-agent-sdk
# or, in a Python virtual environment
pip install claude-agent-sdk

The package is only the runtime layer. You still need authentication, a model/provider configuration, a working directory, and a permission policy. Treat installation success as a dependency check—not proof that an agent is safe to run against a production repository. The official quickstart is the source of truth for the first query and version-specific options.

For pricing, budget the model/API usage and tool runtime separately. The SDK does not make a multi-step agent run equivalent to one text request: tool calls, retries, context growth, and subagents can all change the final cost. Put a budget and correlation ID at the gateway layer when the application uses SandBase.

The minimal architecture

Keep four layers separate:

1. Task input — the user request and project context.
2. Agent runtime — the SDK loop, model selection, and session state.
3. Tool boundary — filesystem, shell, web, and MCP tools with explicit permissions.
4. Provider gateway — authentication, routing, budgets, and observability.

The fourth layer is where a gateway such as SandBase can help when an application needs one integration for multiple LLM providers plus image, video, or data APIs. Keep the provider and gateway responsibilities visible: the SDK still owns the agent behavior, while the gateway handles the model/API connection and policy you configure.

A safe first run

Start in a read-only or plan-style permission mode. Give the agent one repository and one narrow task. Set a turn limit, log every tool request, and require approval for shell commands, writes, and network access. A useful first acceptance test is a denied action: the agent should explain the denial and continue or stop cleanly rather than silently retrying with a broader tool.

The SDK documentation and Claude Code CLI reference describe non-interactive output, allowed and disallowed tools, permission modes, and session continuation. Those controls are more important than a clever system prompt because they remain inspectable at runtime.

MCP without losing the boundary

MCP makes external tools discoverable, but discovery is not authorization. Treat each MCP server as an untrusted integration until you have reviewed its tools, inputs, side effects, and data handling. Expose only the tools the task needs. Add timeouts and validate returned data before passing it into a second tool.

For a production agent, record:

• the MCP server identity and version;
• the tool name and normalized arguments;
• the approval decision;
• latency, retries, and failure reason;
• the session and user/request identifier.

This gives you a trace that is useful for debugging and for cost analysis. See our MCP vs function calling comparison for the protocol trade-off.

Sessions and resumability

Resuming a session is convenient, but it also extends the authority of an earlier request. Expire sessions, bind them to a user and project, and re-check permissions after a resume. Do not assume that a previous approval should authorize a new file, repository, or network destination.

Persist summaries and IDs rather than blindly persisting every tool result. Large logs can contain credentials, personal data, or stale instructions. Redact secrets before storage and make retention a product decision.

Putting a gateway behind the agent

A provider gateway is most useful when you need routing, budget controls, or a consistent API surface across providers. Keep these concerns outside the agent prompt:

• resolve the model and fallback before the run;
• attach a request budget and correlation ID;
• enforce rate limits at the gateway;
• capture input/output token usage and provider latency;
• fail closed when the selected provider is unavailable.

Do not describe a gateway as making models equivalent. Context limits, tool behavior, safety filters, and streaming semantics can differ even when an endpoint accepts a familiar request shape. Our OpenAI API alternatives guide covers that compatibility boundary.

Production checklist

• Pin and review SDK versions.
• Use least-privilege tool permissions.
• Cap turns, tokens, wall-clock time, and spend.
• Require approval for destructive or external actions.
• Log tool calls with secrets redacted.
• Test denial, timeout, malformed output, and provider failure paths.
• Revalidate permissions when resuming a session.
• Keep a human escalation path for ambiguous tasks.

The Agent SDK is a runtime for controlled autonomy, not a replacement for application security. Start with a narrow task, measure the failure modes, and expand authority only when the evidence supports it.

Sources

• Anthropic Claude Code SDK documentation, retrieved 2026-08-23.
• Anthropic MCP documentation, retrieved 2026-08-23.
• Anthropic CLI reference, retrieved 2026-08-23.