Claude Agent SDK 完整指南

TL;DR

• The Claude Agent SDK programmatically exposes the agent harness powering Claude Code, managing the autonomous context, reasoning, and tool-execution loop in local application processes.
• Native capabilities include built-in file operations, shell execution via Bash, Model Context Protocol (MCP) server support, context compaction, and subagent orchestration.
• Developers can configure the SDK in TypeScript or Python with fine-grained permission modes, deterministic lifecycle hooks, and cross-session state resumption.
• In production, routing agent requests through Bifrost provides multi-provider failover, virtual key budgets, and 11 microseconds of gateway overhead at 5,000 requests per second.
• Endpoint AI governance tools like Bifrost Edge extend gateway-level security policies directly to local developer environments executing agent tasks.

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, an open-source AI gateway 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.

What is the Claude Agent SDK?

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.

Core Architecture: The Claude Agent Loop and Execution Model

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.

Built-in System Tools

To eliminate repetitive boilerplate, the Claude Agent SDK includes a suite of native tools configured to run safely inside the executing host environment:

• File System Operations (Read, Write, Edit): These primitives allow agents to inspect directory structures, load source files, and execute precise replacements. The Edit tool performs targeted string substitutions rather than rewriting entire files, significantly conserving completion tokens.
• Code Navigation (Glob, Grep): Rather than relying on slow, sequential folder walks, the SDK integrates optimized search utilities. Agents can quickly locate files matching glob patterns or search entire trees for regular expressions to build contextual awareness before modifying code.
• Shell Execution (Bash): The Bash tool gives the agent terminal execution capabilities, allowing it to invoke linters, test runners, build systems, or deployment scripts. Developers can restrict execution through working directory parameters and timeout boundaries.
• Network and Retrieval (WebSearch, WebFetch): Agents can retrieve external web content, research live API documentation, or inspect remote endpoints to resolve technical requirements without human intervention.

Permission modes govern how these tools execute. By default, developers can select from multiple permission tiers:

1. default: Prompts the host or invokes user approval callbacks before executing destructive operations (such as arbitrary shell scripts or file overwrites).
2. plan: Restricts the agent to read-only tools (Read, Glob, Grep), preventing modifications until an explicit execution plan is reviewed.
3. bypassPermissions: Allows fully autonomous execution without human-in-the-loop validation, typically reserved for ephemeral containers or sandboxed cloud workers.

Extending Agents with the Model Context Protocol (MCP)

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), 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 like Bifrost, engineering teams can centralize tool definitions, enforce authentication credentials, and decouple agent logic from backend integrations.

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 enables teams to register internal APIs as MCP tools without rewriting application code. Furthermore, administrators can apply MCP tool filtering across various projects to ensure agents only see the specific tools authorized for their role.

Production Patterns: Subagents, Hooks, and Session Resumption

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:

Subagent Delegation

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     │
                     └────────────────────────────────┘

Lifecycle Hooks

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.

Session Resumption and Persistence

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.

Governing and Securing Claude Agent SDK Workflows

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 applies governance and security controls (virtual keys, budgets, guardrails, audit logs) centrally, and Bifrost Edge extends that same governance and security to AI traffic on employee machines, with endpoint enforcement 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 alongside 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 restrict individual agent instances to predefined token allocations and budget limits. Real-time guardrails scan incoming and outgoing payloads for personally identifiable information (PII) or hardcoded credentials, while immutable audit logs maintain verifiable records for SOC 2, HIPAA, and GDPR compliance.

Routing and Multi-Provider Infrastructure with Bifrost

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 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. If the primary Anthropic API experiences service disruption, Bifrost automatically executes automatic fallbacks, translating the request payload to AWS Bedrock or Google Vertex AI transparently. The agent process maintains uninterrupted execution without modifying code or restarting active sessions.

Additionally, 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.

Practical Implementation: Building an End-to-End Autonomous Agent

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.

1. Environment Configuration

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"

2. Python Agent Implementation

The Python package (claude-agent-sdk) manages the underlying process and streams events as execution advances:

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())

3. TypeScript Agent Implementation

For teams standardizing on Node.js or Bun runtimes, the TypeScript package (@anthropic-ai/claude-agent-sdk) offers complete type definitions and Zod validation:

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, allowing operations teams to visualize total turn durations, individual tool latency, and token consumption directly inside platforms like Grafana, Datadog, or New Relic.

Comparison: Claude Agent SDK vs. Alternative Frameworks

Choosing the right layer of abstraction depends on application requirements, desired customization depth, and model diversity.

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.

Frequently Asked Questions

What is the difference between Claude Code and the Claude Agent SDK?

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.

Can the Claude Agent SDK use models other than Claude?

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, 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.

How does the Claude Agent SDK handle context window exhaustion?

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.

What tools are available by default in the Claude Agent SDK?

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.

How can teams control costs and prevent runaway agent loops?

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 with hard financial spending caps and rate limits, cutting off agent loops automatically if usage exceeds allocated budgets.

Does the Claude Agent SDK support human-in-the-loop approvals?

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.

Getting Started with Production Agent Infrastructure

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, review documentation on governing CLI agents, inspect the open-source GitHub repository, or request a Bifrost demo to implement centralized multi-provider routing and security controls.

Sources

• Anthropic Claude Agent SDK TypeScript Repository: https://github.com/anthropics/claude-agent-sdk-typescript
• Anthropic Claude Agent SDK Python Repository: https://github.com/anthropics/claude-agent-sdk-python
• Model Context Protocol (MCP) Specification: https://modelcontextprotocol.io
• Anthropic Research on Building Effective Agents: https://www.anthropic.com/research/building-effective-agents