Claude Agent SDK? AI, DX & Security Glossary with Diagrams

The Claude Agent SDK is a development kit provided by Anthropic for building AI agents. It is a framework for implementing agents in Python and TypeScript that leverage Claude's Tool Use and multi-turn conversation capabilities.

Directly calling the Claude API to build agents is possible, but it requires implementing the same boilerplate every time: loop processing to return tool call results to the model, error handling, and guardrail configuration. The Claude Agent SDK is an official framework that abstracts this "agent loop," allowing developers to focus on business logic.

Problems the SDK Solves

Agent development requires integrating LLM instructions (system prompts), external tool definitions, and execution result evaluation into a single loop. A naive implementation—appending tool return values to the message history, calling the model again, evaluating the termination condition, and so on—can balloon to hundreds of lines of code.

The SDK condenses this loop into the Agent class. Developers simply define tools as functions and pass them to the Agent. Loop control, token management, and switching between serial and parallel tool execution are all handled by the SDK.

Basic Structure

The core of the SDK is the Agent object. Instantiate it by passing a name, instructions (system prompt), and tools (list of tools), then execute it with Runner.run().

python

from agents import Agent, Runner, function_tool

@function_tool
def get_weather(city: str) -> str:
    return f"The weather in {city} is sunny."

agent = Agent(
    name="weather-bot",
    instructions="When asked about the weather, retrieve it using the tool and respond.",
    tools=[get_weather],
)

result = Runner.run_sync(agent, "What's the weather in Tokyo?")

Tool inputs and outputs are automatically converted to JSON Schema from type annotations, eliminating the need to write schemas by hand. When I first tried this, my impression was that this automatic conversion alone cut the traditional boilerplate by more than half.

Guardrails and Handoffs

To guard against unintended agent behavior, guardrails for inputs and outputs can be configured declaratively. Constraints such as "reject inputs containing personal information" or "retry if the response does not conform to a specific format" can be embedded as part of the agent definition.

There is also a "handoff" feature for coordinating multiple agents. This is a mechanism by which one agent passes control to another mid-process—for example, a first-line customer support agent that detects a technical question and hands it off to a specialist agent. This kind of multi-agent configuration can be achieved without explicit orchestration code.

Integration with MCP

The SDK natively supports connections to MCP (Model Context Protocol) servers. Tool sets exposed by MCP servers can be dynamically added to an Agent's tool list, allowing external capabilities such as database operations and file system access to be incorporated directly into the SDK's agent loop. This means you can replicate in your own agents the same mechanism that Claude Code uses to operate Supabase via an MCP server.

Relationship with Claude Code

Claude Code is a CLI-based coding agent officially provided by Anthropic, and the Claude Agent SDK is used in its internal implementation. In other words, the SDK is positioned as "the building block for creating your own agents like Claude Code." The definition of Agent Skills and the tool execution flow also conform to the SDK's architecture.

That said, the SDK itself is a general-purpose framework and can handle use cases beyond coding—such as sales support, data analysis pipelines, and internal chatbots—using the same design patterns.