Core Abstractions
The SDK centers on a few key abstractions. An Agent encapsulates a system prompt, a model configuration, available tools, guardrails, and handoff targets. The Runner executes the agentic loop, managing the cycle of model calls, tool execution, and stop condition evaluation.
Tools are defined as typed functions that the agent can call. Guardrails are input/output validators that run before and after model calls. Handoffs allow one agent to transfer control to another agent, enabling multi-agent architectures.
Agent Configuration
An Agent is configured with: a name, a system prompt (instructions), a model, tools, guardrails, and handoff targets. The system prompt defines the agent's behavior and constraints. Tools define what actions the agent can take. Guardrails define safety boundaries.
The SDK supports both Python function tools (decorated with @tool) and MCP server tools. This means you can mix local function tools with remote MCP services in a single agent.
Tracing and Observability
The SDK includes built-in tracing that records every step of agent execution: model calls, tool invocations, guardrail checks, and handoffs. Traces can be viewed in the Anthropic console or exported to custom backends.
Tracing is critical for debugging production agents. When an agent produces unexpected results, the trace shows exactly which decisions it made, which tools it called, and where things went wrong.
Key Concept
Agents as Configuration, Not Code
The SDK treats agent behavior as configuration rather than imperative code. You declare what the agent should do (system prompt), what it can do (tools), what it must not do (guardrails), and who it can delegate to (handoffs). The Runner handles the execution mechanics. This declarative approach makes agents easier to test, modify, and reason about.
Exam Traps
Confusing the Agent SDK with the base Claude API
The Agent SDK is a higher-level framework built on top of the Claude API. The base API provides message completion; the SDK provides agentic loop management, tool orchestration, and guardrails.
Thinking handoffs require custom code
Handoffs are a first-class concept in the SDK. You configure them declaratively as part of the Agent definition, not by writing custom routing logic.
Overlooking the tracing system
The SDK's built-in tracing is a key feature for production deployments. The exam may ask about debugging agent behavior, and tracing is the primary tool.
Check Your Understanding
You need to build a customer service agent that can handle billing questions itself but should hand off complex technical issues to a specialized technical support agent. Using the Claude Agent SDK, how should you structure this?
Build Exercise
Build a Multi-Agent Handoff System
What you'll learn
- Configure Agent instances with the SDK
- Implement tool functions
- Set up agent-to-agent handoffs
- Use tracing to debug agent behavior
Install the Claude Agent SDK and create a basic Agent with a system prompt and one tool.
WHY: Understanding the Agent abstraction is the foundation for all SDK work.
YOU SHOULD SEE: An agent that responds to queries and can call your defined tool.
Create a second Agent with different tools and system prompt. Configure a handoff from the first agent to the second.
WHY: Handoffs enable specialization — each agent focuses on what it does best.
YOU SHOULD SEE: The first agent can transfer control to the second agent when appropriate.
Add an input guardrail to the first agent that checks for inappropriate content before processing.
WHY: Guardrails in the SDK are declarative — you define them as part of agent configuration.
YOU SHOULD SEE: The agent rejects inappropriate inputs with a guardrail error before reaching the model.
Run a conversation through the system and examine the trace output. Identify the handoff point and tool calls.
WHY: Tracing is essential for debugging and understanding agent behavior in production.
YOU SHOULD SEE: A trace showing model calls, tool executions, the handoff event, and the second agent's processing.
Sources
- Claude Agent SDK Documentation— Anthropic Documentation
- Agent SDK Python Repository— Anthropic GitHub
- Building Effective Agents— Anthropic Documentation