What is the Claude Agent SDK? A Beginner's Primer for CCA-F Candidates

If you've used Claude through the raw Messages API, you've already built one tiny agent — a "send-message, get-response" loop. The Agent SDK is what happens when you need that loop to be real: multi-step reasoning, tool use, state across turns, observability hooks, and safety controls that actually hold up in production.

This guide is written for developers who know Python or TypeScript, have a passing familiarity with the Claude API, and want to understand what the Agent SDK actually does before reading the reference docs. We'll cover the conceptual model, the primitives, and a worked example. By the end, you should have a confident mental picture of the SDK's design — enough to start building or to recognize the patterns on the CCA-F exam.

Why an SDK? Why not just use the API?

Fair question. The Claude Messages API is intentionally minimal — send messages, receive responses, optionally provide tools. You could build any agent on top of it. So what does the SDK give you?

• The agentic loop, pre-built. Most agents need a loop: model produces a tool call, your code executes the tool, results go back to the model, repeat until done. Writing this once is fine. Writing it correctly with retries, error handling, partial results, and cancellation is more work than it sounds. The SDK ships that loop.
• Subagent isolation. When one agent needs to delegate to another with its own context window, system prompt, and tool set — that's a subagent. The SDK gives you the spawning, parameter-passing, and result-bubbling pattern out of the box.
• Hooks for observability and policy. Logging every tool call, validating arguments before execution, enforcing a deny-list, sending events to your telemetry pipeline — all of that lives in hooks that fire at well-defined points in the lifecycle.
• Session management. If your agent needs to remember things across user requests (between web sessions, between days), the SDK gives you the session abstraction and state-serialization primitives.
• Policy controls. allowedTools and disallowedTools let you constrain what an agent can do at the SDK boundary — independently of how the underlying tools are defined.
• MCP integration as a first-class citizen. Adding an MCP server is a few lines of configuration, not a custom integration.

Could you build all of this yourself? Yes. Should you? Almost never. The SDK is what Anthropic uses to build Claude Code — it's battle-tested in the most demanding agentic workload Anthropic ships.

Rule of thumb: If your agent has more than one tool, runs more than one model turn, or needs to persist state, reach for the SDK. If you're sending a single message and getting a single response, the raw Messages API is fine.

The core concepts

The SDK is built around six primitives. Get fluent with these and the rest of the documentation reads quickly.

1. The agent

An agent is the top-level object. It has:

• A model (which Claude model it uses — typically claude-sonnet-4-6 for general work or claude-opus-4-8 for harder reasoning)
• A system prompt defining its role and rules
• A set of tools it can call
• Optionally: subagents, hooks, session config, MCP servers, policy controls

You instantiate an agent once and reuse it across requests. Each request creates a fresh "run" — an instance of the agentic loop bound to that one user input.

2. Tools

A tool is a function the agent can call. Each tool has a name, a description (the model reads this to decide when to call it), an input schema, and an implementation function in your code.

Tools are the single most important design decision when building an agent. Good tools are:

• Discoverable — the description tells the model exactly when to use it
• Idempotent where possible — calling them twice with the same input does the same thing
• Error-tolerant — they return structured error responses rather than throwing exceptions
• Focused — one tool does one thing well, rather than a kitchen-sink tool

3. Subagents

A subagent is an agent invoked from inside another agent. The parent agent calls the subagent via a tool call (the SDK exposes the spawning as a synthetic tool), the subagent runs its own agentic loop with its own system prompt and tools, and returns a result the parent can consume.

Use subagents for:

• Specialization — a subagent with deep expertise in one domain, with a focused tool set
• Context isolation — the subagent has its own context window, so it can read a large document without polluting the parent's context
• Parallelism — the SDK can spawn multiple subagents concurrently for independent sub-tasks
• Policy boundaries — the subagent inherits its own allowedTools, so you can grant narrower permissions than the parent has

4. Hooks

Hooks are lifecycle callbacks that fire at well-defined points during a run:

• PreToolUse — before a tool is executed; you can validate, deny, or transform the call
• PostToolUse — after a tool returns; you can log, summarize, or transform the result
• SessionStart / SessionEnd — bookend the session lifecycle
• UserPromptSubmit — fires when the user submits a prompt; useful for input validation or routing
• PreCompact / PostCompact — fires around context compaction (when conversations exceed the model's context window)

Hooks are how you make agents observable, auditable, and safe. Every production agent should have at least PreToolUse and PostToolUse hooks wired into your logging and telemetry pipeline.

5. Sessions

A session is a persistent context that survives across runs. Think of it as the agent's memory between requests.

Sessions hold:

• Conversation history (what's been said)
• Any explicitly stored memory (via the memory tool)
• Session-level metadata your code attaches

Sessions can be serialized to a database, replayed for debugging, or shared across multiple agent runs.

6. Policy controls

The SDK exposes two top-level lists for each agent:

• allowedTools — explicit allowlist of tool names the agent may call
• disallowedTools — explicit denylist (takes precedence over allowedTools)

These are critical for safety. Even if you define a "delete all user data" tool somewhere, an agent without that tool on its allowedTools can't call it. Defense in depth: design tools to be safe, then constrain agents to be safer.

A minimal worked example

The cleanest way to internalize the SDK is to see it. Here's a small agent in TypeScript that searches a fake knowledge base and answers questions:

import { Agent, tool } from "@anthropic/agent-sdk";

const searchTool = tool({
  name: "search_docs",
  description: "Search the internal knowledge base for relevant articles. " +
               "Returns up to 5 article snippets matching the query.",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", description: "What to search for." }
    },
    required: ["query"]
  },
  async run({ query }) {
    // In a real app: call your vector DB, BM25 index, etc.
    return {
      results: [
        { title: "Refund policy", snippet: "Refunds within 14 days..." },
        { title: "Shipping FAQ", snippet: "Standard shipping is 3-5 days..." }
      ]
    };
  }
});

const agent = new Agent({
  model: "claude-sonnet-4-6",
  systemPrompt: "You are a customer support agent. Use search_docs to find answers " +
                "before responding. Cite the article title when you do.",
  tools: [searchTool],
  hooks: {
    preToolUse: async (event) => {
      console.log(`[tool call] ${event.tool.name}`, event.input);
    }
  },
  allowedTools: ["search_docs"]
});

const response = await agent.run({
  input: "How long do I have to return an item?"
});

console.log(response.output);

That's a complete production-ready agent in fewer than fifty lines. The SDK is doing the heavy lifting:

• It calls Claude with the system prompt, user input, and tool definitions
• If Claude responds with a tool call, the SDK executes the tool and sends the result back
• The PreToolUse hook fires on every tool call, letting you log to your telemetry system
• If Claude tries to call a tool not on allowedTools, the SDK refuses
• When Claude produces a final answer (no tool call), the SDK returns it

How the SDK fits into a larger architecture

In a production system, the Agent SDK typically sits in a service layer:

• Above the SDK: your HTTP/WebSocket layer routes user requests to the SDK
• Inside the SDK: the agentic loop with Claude, tools, subagents, and hooks
• Below the SDK: your tool implementations call out to databases, APIs, vector stores, MCP servers, etc.
• Alongside the SDK: your telemetry collector receives events from the hooks; your session store persists state between requests

This layered design is what makes the SDK production-friendly. Telemetry is decoupled from agent logic; tools are decoupled from the loop; sessions are decoupled from your HTTP layer.

Common mistakes

• Putting business logic in the system prompt. Logic belongs in tools, where it's testable and observable. The system prompt is for role and rules, not for "when X, do Y" instructions.
• Building one mega-agent with twenty tools. A focused agent with five tools usually outperforms an agent with twenty. Use subagents for delegation.
• Skipping the hooks. Hooks are how you debug, audit, and operate in production. Wire them from day one.
• Forgetting allowedTools. Without an explicit allowlist, the agent inherits everything. Be deliberate.
• Treating tool errors as exceptions. Return structured error responses from tools so Claude can reason about them, retry, or report to the user gracefully.
• Ignoring context-window costs. Long conversations consume tokens linearly. Use session compaction, summarization, or memory tools to keep context manageable.

Where the SDK fits on the CCA-F exam

Claude Agent SDK is 25% of the CCA-F exam — the largest single domain after Tool Use + MCP (also 25%). On the exam you'll be asked to:

• Identify when to use a subagent vs. extending the parent agent
• Choose the right hook for a given observability or policy requirement
• Recognize anti-patterns (mega-agents, system-prompt logic, missing policy controls)
• Debug an agent based on hook output
• Architect session management for a multi-turn use case

Hands-on time with the SDK is the only real preparation for those questions. Reading docs gets you familiar with the names; building agents teaches you to recognize the patterns.

Where to go next

• Read Anthropic's official Agent SDK documentation — it includes language-specific reference for Python and TypeScript
• Try the official quickstart in your preferred language
• Explore our complete CCA-F study guide for the broader curriculum context
• Review the free CCA-F sample questions to test where you stand

FAQ

Python or TypeScript — which should I learn first?

Both are first-class. Pick the one your team already uses. The conceptual model is identical; only the API ergonomics differ.

Can I use the SDK without an Anthropic API key?

No. The SDK still calls Claude through Anthropic's API, so you need a key. You can use Anthropic's free tier for development.

How does the Agent SDK compare to LangChain or LlamaIndex?

The SDK is Claude-specific and Anthropic-maintained. LangChain and LlamaIndex are vendor-neutral. The trade-off: the SDK is opinionated, tightly integrated, and shipped by the same team that ships Claude — which means new Claude features arrive in the SDK day-one. LangChain offers vendor portability but adds an abstraction layer that can lag behind native features.

Does the SDK work with MCP servers I've already built?

Yes. MCP is a first-class integration. You configure MCP servers at the agent level and the SDK handles the wire protocol.

What's the relationship between the Agent SDK and Claude Code?

Claude Code uses the Agent SDK internally. The CLI is built as an SDK consumer. That's why patterns you observe in Claude Code (subagents, hooks, MCP servers, skills) map directly to SDK primitives.

Can the SDK run multiple agents in parallel?

Yes. Subagent spawning is parallelizable — multiple subagents can run concurrently from a parent agent. The SDK manages the concurrency for you.

Is there a streaming API for SDK agents?

Yes. The SDK supports streaming both the final response and the intermediate steps (tool calls, hook events). This is useful for showing progress in UIs.

The bottom line

The Claude Agent SDK is what turns "I can call the Claude API" into "I can build a production agent." It packages the agentic loop, subagent spawning, hooks, sessions, MCP integration, and policy controls into a coherent design that mirrors how Anthropic builds Claude Code.

If you're studying for CCA-F, getting hands-on with the SDK is the single highest-leverage prep activity you can do. Build a small agent. Wire hooks. Spawn a subagent. Plug in an MCP server. The exam tests pattern recognition on these primitives — and recognition only comes from building.