Claude Agent SDK

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.