The Definitive Guide to the Claude Agent SDK

Anthropic's Claude Agent SDK, the programmatic engine behind Claude Code, packages an autonomous agent harness into a TypeScript and Python client library, handling multi-turn tool loops, automatic context compaction, built-in file system and Bash tools, native Model Context Protocol support, and session persistence. The SDK, renamed from the Claude Code SDK, replaces the manual orchestration cycles required by the raw Messages API, where application code must inspect responses, execute tools, and submit follow-up requests itself. The guide also covers pairing the SDK with Bifrost, an open-source Go AI gateway by Maxim AI, for routing, rate limits, and governance in production agent loops.

TL;DR Building autonomous agents with raw foundation model APIs has historically required teams to handcraft fragile tool loops, manually parse structured responses, and engineer custom context window truncation routines. The Claude Agent SDK, developed by Anthropic as the programmatic engine behind Claude Code, fundamentally shifts this paradigm by packaging an autonomous execution harness directly into a client library. Bifrost https://www.getmaxim.ai/bifrost , an open-source AI gateway https://github.com/maximhq/bifrost built in Go by Maxim AI, pairs naturally with the SDK by handling routing, rate limits, and governance whenever agent loops invoke underlying language models in production. This guide provides a comprehensive technical exploration of the SDK architecture, implementation patterns, and enterprise operational practices. The Claude Agent SDK is a developer library in TypeScript and Python that provides an autonomous agent harness, executing multi-turn tool loops, managing dynamic context compaction, and orchestrating external tools on local machines. Originally distributed as the Claude Code SDK, Anthropic renamed the package to the Claude Agent SDK to reflect a broader vision beyond command-line interface utilities. While the standard Anthropic Messages API client @anthropic-ai/sdk in TypeScript or anthropic in Python merely sends messages and receives static completions, the Agent SDK operates as an autonomous agent runtime. When using the raw Messages API, application code must inspect every model response, detect tool invocation requests, execute the requested functions locally, package the outputs as tool result blocks, and submit a follow-up request. If an agent requires eight iterative queries to resolve a database migration script, the application must execute eight separate orchestration cycles. The Claude Agent SDK internalizes this entire execution lifecycle. A developer specifies a high-level goal through a unified query interface, provisions permissions and tools, and allows the SDK to manage tool evaluation, output parsing, error retries, and intermediate reasoning steps until the task reaches completion. | Capability Dimension | Anthropic Messages API Client | Claude Agent SDK | |---|---|---| | Execution Model | Single-turn request and response | Autonomous multi-turn agent loop | | Tool Orchestration | Manual execution and feedback loops | Built-in execution engine for tools | | Built-in System Tools | None user supplies all schemas | File system, Bash, Grep, Glob, Web fetch | | Context Management | Manual message array slicing | Automatic context compaction and pruning | | Protocol Integration | Manual API bindings | Native Model Context Protocol MCP support | | Session Persistence | Application-managed database state | Built-in session saving and resumption | The internal runtime of the Claude Agent SDK is structured around a continuous loop: Context Assembly, Thought Formulation, Action Invocation, and Observation Processing. ┌──────────────────────────┐ │ User Task / Trigger │ └────────────┬─────────────┘ │ ▼ ┌──────────────────────────┐ ┌─────────▶│ Context Assembly │ │ │ System, History, Caching │ └────────────┬─────────────┘ │ │ │ ▼ │ ┌──────────────────────────┐ │ │ Thought Formulation │ │ │ Reasoning / CoT Step │ │ └────────────┬─────────────┘ │ │ Loop Continuation ▼ Observation Ingestion ┌──────────────────────────┐ │ │ Action Invocation │ │ │ Built-in Tools / MCP │ │ └────────────┬─────────────┘ │ │ │ ▼ │ ┌──────────────────────────┐ │ │ Observation Processing │ │ │ Output Parsing / Errors │ │ └────────────┬─────────────┘ │ │ └───────────────────────┴────────────── Task Complete? ──▶ Final Result During Context Assembly, the engine gathers project settings, active environment parameters, available tool declarations, and prior conversation turns. The SDK applies prompt caching techniques to minimize latency and token expenditures during repeated turns. In the Thought Formulation phase, Claude generates structured reasoning regarding which steps are required to achieve the objective. The SDK exposes this process via streaming response chunks, enabling real-time visibility into the internal plan before execution begins. During Action Invocation, the runtime intercepts the tool call generated by the model, evaluates user-defined permission rules, and initiates execution. Depending on configuration, the tool might execute directly in the local process, trigger an external shell command, or dispatch a payload to a remote server. Finally, Observation Processing takes the execution payload, formats stdout, stderr, or structured JSON data, and inserts the result back into the agent context. If the observation contains error output such as a compiler failure or syntax issue , Claude parses the diagnostic information on the subsequent turn and self-corrects. Context management remains a core strength of this architecture. Long-running agent tasks naturally accumulate tens of thousands of tokens. The SDK incorporates automatic context compaction routines, summarizing older message turns, discarding transient tool outputs that are no longer necessary, and preserving critical state flags to prevent context exhaustion. To eliminate repetitive boilerplate, the Claude Agent SDK includes a suite of native tools configured to run safely inside the executing host environment: Read , Write , Edit Glob , Grep Bash WebSearch , WebFetch Permission modes govern how these tools execute. By default, developers can select from multiple permission tiers: default : Prompts the host or invokes user approval callbacks before executing destructive operations such as arbitrary shell scripts or file overwrites . plan : Restricts the agent to read-only tools bypassPermissions : Allows fully autonomous execution without human-in-the-loop validation, typically reserved for ephemeral containers or sandboxed cloud workers. While built-in tools cover local system operations, production agent deployments require access to proprietary databases, internal microservices, and SaaS platforms. The Claude Agent SDK natively implements the Model Context Protocol MCP https://modelcontextprotocol.io , an open standard specifying how foundation models discover and execute external tools. The SDK can instantiate in-process MCP servers or connect to remote servers over standard transport layers such as standard input/output or Server-Sent Events . By utilizing an MCP gateway https://www.getmaxim.ai/bifrost/resources/mcp-gateway like Bifrost https://www.getmaxim.ai/bifrost , engineering teams can centralize tool definitions, enforce authentication credentials, and decouple agent logic from backend integrations. js import { query, createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk"; import { z } from "zod"; // Define custom tool logic using the SDK MCP helper const databaseServer = createSdkMcpServer { name: "internal-analytics", version: "1.0.0", tools: tool "query user metrics", "Retrieves daily active metrics for a specified account tier", { tier: z.enum "starter", "growth", "enterprise" }, async { tier } = { // Implementation logic connecting to internal database const metrics = await fetchMetricsFromDatabase tier ; return { content: { type: "text", text: JSON.stringify metrics } }; } } ; // Pass the custom MCP server into the query context const agentStream = query { prompt: "Analyze enterprise customer drop-offs over the last seven days.", options: { mcpServers: databaseServer , allowedTools: "query user metrics", "Read", "Write" , permissionMode: "default" } } ; Using Bifrost as an MCP gateway https://docs.getbifrost.ai/mcp/gateway enables teams to register internal APIs as MCP tools without rewriting application code. Furthermore, administrators can apply MCP tool filtering https://docs.getbifrost.ai/features/governance/mcp-tools across various projects to ensure agents only see the specific tools authorized for their role. Moving beyond simple scripts requires patterns that support state isolation, deterministic control, and operational resilience. The Claude Agent SDK provides native primitives for these advanced workflows: Complex tasks often overwhelm a single agent's reasoning trajectory. The SDK supports spawning specialized subagents with isolated context windows. A primary coordinator agent can spin up a dedicated "Code Reviewer" agent or "Security Auditor" agent, pass it a scoped prompt, collect its synthesized findings, and continue without cluttering the primary agent's token budget. ┌────────────────────────────────┐ │ Coordinator Agent Loop │ │ Main Orchestration Context │ └───────┬────────────────┬───────┘ │ │ Spawn Subagent │ │ Spawn Subagent ▼ ▼ ┌─────────────────────────┐ ┌─────────────────────────┐ │ Security Auditor │ │ Dependency Checker │ │ Isolated Context & │ │ Scoped File Access & │ │ Static Analysis Tools │ │ Package Manifest View │ └────────────┬────────────┘ └────────────┬────────────┘ │ │ └───────────────┬────────────────┘ │ Return Findings ▼ ┌────────────────────────────────┐ │ Synthesized Action Plan │ └────────────────────────────────┘ To integrate agents with enterprise security monitoring and audit logging, the SDK exposes deterministic hooks at key execution phases: beforeTurn : Inspects or alters the prompt before submission to the model. onToolCall : Intercepts specific tool invocations to log arguments, sanitize inputs, or block disallowed flags. afterTurn : Processes model outputs, calculates intermediate costs, or emits custom metrics to external telemetry collectors. Autonomous workflows may run across several hours or pause while waiting for human authorization. The SDK manages session state via deterministic identifiers. Developers can serialize an active session, terminate the runtime process, and later restore the identical execution tree using resumeSession , maintaining complete conversational memory and tool history without replay overhead. Deploying the Claude Agent SDK inside organizations introduces operational challenges around credential isolation, unbounded cost loops, and data exfiltration. Because agents run in autonomous loops, an unconstrained prompt can trigger hundreds of successive model calls in minutes, quickly consuming API budgets or triggering rate limits. Centralized control requires separating the agent execution environment from the model access credentials. Using an AI gateway solves this by enforcing policies upstream from the LLM provider. Beyond routing, Bifrost https://www.getmaxim.ai/bifrost applies governance https://www.getmaxim.ai/bifrost/resources/governance and security controls virtual keys, budgets, guardrails, audit logs centrally, and Bifrost Edge https://www.getmaxim.ai/bifrost/edge extends that same governance and security to AI traffic on employee machines, with endpoint enforcement https://docs.getbifrost.ai/edge/security on each device. To prevent unauthorized operations on developer laptops, Bifrost Edge runs locally to monitor developer tooling, inspect outgoing agent traffic, and apply app governance https://docs.getbifrost.ai/edge/app-governance alongside MCP governance https://docs.getbifrost.ai/edge/mcp-governance . If an agent attempts to invoke an unauthorized MCP server or transmit unredacted API tokens, policies enforced at the endpoint block the request before network egress occurs. At the gateway layer, virtual keys https://docs.getbifrost.ai/features/governance/virtual-keys restrict individual agent instances to predefined token allocations and budget limits https://docs.getbifrost.ai/features/governance/budget-and-limits . Real-time guardrails https://docs.getbifrost.ai/enterprise/guardrails scan incoming and outgoing payloads for personally identifiable information PII or hardcoded credentials, while immutable audit logs https://docs.getbifrost.ai/enterprise/audit-logs maintain verifiable records for SOC 2, HIPAA, and GDPR compliance. While the Claude Agent SDK relies on Anthropic's Messages protocol, enterprise architectures often demand redundancy across multiple cloud hosts, including direct Anthropic endpoints, Amazon Bedrock, and Google Vertex AI. If direct Anthropic endpoints encounter 5xx errors or sudden rate limit restrictions, autonomous agent loops fail abruptly unless upstream failover handles the disruption. Bifrost https://www.getmaxim.ai/bifrost addresses this by providing an Anthropic-compatible reverse proxy endpoint. The Agent SDK communicates directly with Bifrost over HTTP by configuring standard environment variables. ┌──────────────────────────────────┐ │ Claude Agent SDK Client │ │ TypeScript or Python Process │ └────────────────┬─────────────────┘ │ ANTHROPIC BASE URL HTTP ▼ ┌──────────────────────────────────┐ │ Bifrost AI Gateway │ │ - 11µs Latency Overhead │ │ - Virtual Keys & Budgets │ │ - Semantic Caching │ └────┬───────────┬────────────┬────┘ │ │ │ Primary Path │ │ Fallback 1 │ Fallback 2 ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │Anthropic │ │AWS │ │Google │ │Direct API│ │Bedrock │ │Vertex AI │ └──────────┘ └──────────┘ └──────────┘ When an agent executes, Bifrost adds only 11 microseconds of overhead per request at 5,000 requests per second in sustained benchmarks https://www.getmaxim.ai/bifrost/resources/benchmarks . If the primary Anthropic API experiences service disruption, Bifrost automatically executes automatic fallbacks https://docs.getbifrost.ai/features/fallbacks , translating the request payload to AWS Bedrock https://docs.getbifrost.ai/providers/supported-providers/bedrock or Google Vertex AI https://docs.getbifrost.ai/providers/supported-providers/vertex transparently. The agent process maintains uninterrupted execution without modifying code or restarting active sessions. Additionally, semantic caching https://docs.getbifrost.ai/features/semantic-caching optimizes agent workloads. Identical exploration queries such as running repetitive directory scans or static codebase queries return cached responses instantly, significantly reducing execution latency and model costs across extensive testing suites. Setting up a resilient agent using the Claude Agent SDK in Python or TypeScript requires only a few steps. The following implementation configures an autonomous code refactoring agent that routes its requests through a secure gateway. Point the Anthropic client configuration to your local or VPC-hosted gateway instance and specify a virtual key for budget tracking: Point the SDK to the Bifrost gateway export ANTHROPIC BASE URL="http://localhost:8080/v1" export ANTHROPIC API KEY="vk-agent-refactor-prod-4820" The Python package claude-agent-sdk manages the underlying process and streams events as execution advances: python import asyncio import os from claude agent sdk import query, AgentOptions async def run refactor agent : Configure agent parameters and runtime options options = AgentOptions cwd="/workspace/service-auth", allowed tools= "Read", "Edit", "Glob", "Grep", "Bash" , permission mode="default", max turns=25, env={ "ANTHROPIC BASE URL": os.environ.get "ANTHROPIC BASE URL" , "ANTHROPIC API KEY": os.environ.get "ANTHROPIC API KEY" } prompt = "Scan the repository for deprecated cryptographic hashing functions. " "Replace SHA-1 usages with SHA-256 in all utility helpers, run test suites " "via pytest, and output a markdown summary of altered files." print "Initiating Claude Agent execution loop..." Execute query and stream output events async for message in query prompt=prompt, options=options : if message.type == "thought": print f" REASONING : {message.content}" elif message.type == "tool use": print f" ACTION : Invoking {message.tool} with parameters: {message.input}" elif message.type == "tool result": print f" OBSERVATION : Tool completed with status {message.status}" elif message.type == "result": print "\n=== FINAL REPORT ===" print message.result if name == " main ": asyncio.run run refactor agent For teams standardizing on Node.js or Bun runtimes, the TypeScript package @anthropic-ai/claude-agent-sdk offers complete type definitions and Zod validation: js import { query } from "@anthropic-ai/claude-agent-sdk"; async function main { const agentEvents = query { prompt: "Audit internal dependencies in package.json, upgrade minor versions, and verify the build.", options: { cwd: process.cwd , allowedTools: "Read", "Edit", "Bash" , permissionMode: "plan", // Require plan validation before altering files maxTurns: 15 } } ; for await const event of agentEvents { switch event.type { case "thought": console.log Thinking : ${event.text} ; break; case "tool call": console.log Tool Call : ${event.toolName} ; break; case "result": console.log "Execution finished successfully:", event.result ; break; case "error": console.error "Agent error encountered:", event.error ; break; } } } main .catch console.error ; To monitor these executions at scale, Bifrost outputs distributed traces using native OpenTelemetry integration https://docs.getbifrost.ai/features/observability/otel , allowing operations teams to visualize total turn durations, individual tool latency, and token consumption directly inside platforms like Grafana, Datadog, or New Relic. Choosing the right layer of abstraction depends on application requirements, desired customization depth, and model diversity. | Evaluation Factor | Claude Agent SDK | Raw Messages API | LangChain / LangGraph | |---|---|---|---| | Primary Focus | Autonomous local execution and coding | Raw LLM prompt-response | Multi-model graph workflows | | Model Compatibility | Claude models expandable via gateway | Claude family exclusively | Provider-agnostic | | Tool Loop Management | Fully automated internal runtime | Manual implementation required | Framework-orchestrated nodes | | System Tools | Native file system and terminal tools | Custom code required | Modular library connectors | | MCP Integration | Native client and server hooks | Custom JSON-RPC wrappers | Third-party community adapters | | Overhead | Low compiled CLI runtime harness | Minimal stateless HTTP | Moderate heavy abstractions | | Context Management | Native automatic compaction | Manual array slicing | Memory modules and checkpointers | The Claude Agent SDK offers unmatched speed and developer convenience when deploying autonomous agents focused on local code manipulation, file system interaction, and command execution. Conversely, teams building multi-model pipelines with complex DAG routing structures across disparate non-Claude models often rely on LangGraph or custom runtimes. Claude Code is an interactive, terminal-based AI coding assistant designed for direct human interaction. The Claude Agent SDK is the programmatic software library that extracts and exposes the underlying agent harness of Claude Code, enabling developers to build custom headless agents, automated background workflows, and programmatic integrations using Python or TypeScript. By default, the SDK communicates using Anthropic Messages formatting and targets the Claude model family. However, by setting the ANTHROPIC BASE URL environment variable to point to Bifrost https://www.getmaxim.ai/bifrost , teams can use translation layers to route requests to other models or distribute calls across AWS Bedrock and Google Vertex AI while maintaining full agent loop functionality. The SDK includes built-in context compaction algorithms that continuously track active message tokens. When approaching model limits, the harness summarizes earlier conversational turns, prunes verbose tool output blocks, and retains essential state variables, allowing the agent to sustain multi-hour operations without encountering maximum token errors. The SDK includes native implementations for Read , Write , and Edit for file system manipulation; Glob and Grep for code search; Bash for terminal command execution; and WebSearch and WebFetch for internet access. Additional capabilities can be attached dynamically via custom functions or Model Context Protocol MCP servers. Teams can configure maxTurns directly within the SDK options to enforce turn limits on tasks. In enterprise environments, routing traffic through an AI gateway like Bifrost allows platform engineers to assign virtual keys https://docs.getbifrost.ai/features/governance/virtual-keys with hard financial spending caps and rate limits, cutting off agent loops automatically if usage exceeds allocated budgets. Yes, the SDK provides configurable permission modes such as plan and default , alongside custom permission callbacks. When an agent attempts an operation marked as sensitive, such as executing terminal commands or updating source files, the runtime halts and requests authorization before applying modifications. The Claude Agent SDK provides a modern foundation for building autonomous AI agents that manipulate files, execute shell commands, and interact with complex developer toolchains. Moving these autonomous loops into production environments requires dedicated infrastructure to handle protocol translation, provider redundancy, and spend governance. Engineering teams deploying agentic systems at scale can explore the Bifrost overview https://docs.getbifrost.ai/overview , review documentation on governing CLI agents https://docs.getbifrost.ai/cli-agents/claude-code , inspect the open-source GitHub repository https://github.com/maximhq/bifrost , or request a Bifrost demo https://getmaxim.ai/bifrost/book-a-demo to implement centralized multi-provider routing and security controls.