Lesson 45: The Claude Agent SDK

Day 45 of 50 · ~7 min read · Phase 6: Mastery

The Opening Question

You've spent the last 44 lessons learning Claude Code: the terminal interface, the agentic loop, the tools, the CLAUDE.md conventions, the MCP integrations, the plugins and skills.

But here's what might not be obvious: Claude Code is built on something else. It's not a monolith. It's a specialized application built on top of a more fundamental library.

Here's the question: What if you don't want Claude Code's terminal interface? What if you want to build your own agent, in Python or TypeScript, with a different interface? What tools and framework would you use?

That's the Claude Agent SDK.

Discovery

Question 1: What is the Claude Agent SDK, and how does it relate to Claude Code?

Let's start with the fundamental relationship.

Claude Code is a consumer application — a command-line tool that you interact with directly. But it's built on top of a developer library called the Claude Agent SDK.

Think of it like this:

• Claude Code = VS Code (the user-facing application)
• Claude Agent SDK = Visual Studio Code Extension API (the framework others build on)

The SDK is available in two languages: Python and TypeScript/Node.js.

Here's what the SDK gives you:

• The ability to define custom tools (read, write, execute commands, HTTP, search)
• An agentic loop that handles reasoning and tool use automatically
• Session management for conversations
• Context window management
• Error handling and retries

Claude Code uses the SDK under the hood. But you can also use the SDK directly to build:

• Custom agents with their own interfaces
• Headless agents that run in CI/CD pipelines
• Domain-specific agents (a "security reviewer" agent, a "frontend specialist" agent)
• Agents embedded in other applications
• Multi-agent systems where agents coordinate with each other

Pause and think: Why would someone build a custom agent instead of just using Claude Code?

The answer: when you need a specialized interface, different behavior, or integration into a larger system.

Question 2: What's the core structure of an agent built with the SDK?

Every agent built with the SDK has the same basic anatomy:

System Prompt — Instructions that define the agent's role, rules, and constraints.

You are a security reviewer. Your job is to analyze code for vulnerabilities.
When reviewing, check for SQL injection, XSS, CSRF, authentication flaws, etc.
Always be specific about findings and suggest fixes.

Tools — Functions the agent can call to interact with the world. The SDK includes built-in tools like:

• bash — run shell commands
• read_file, write_file, edit_file — interact with filesystem
• web_search — search the internet
• http_request — make HTTP calls
• Custom tools you define

Model — The underlying Claude model (currently Claude 3.5 Sonnet for agents).

Sessions — Persistent conversation state that survives across multiple messages.

Here's a minimal agent in TypeScript:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const response = await client.messages.create({
  model: "claude-3-5-sonnet-20241022",
  max_tokens: 4096,
  system: "You are a helpful coding assistant. Help the user write better code.",
  tools: [
    {
      name: "bash",
      description: "Run a shell command",
      input_schema: { /* ... */ }
    },
    {
      name: "read_file",
      description: "Read a file from disk",
      input_schema: { /* ... */ }
    }
  ],
  messages: [
    {
      role: "user",
      content: "Add TypeScript to my project"
    }
  ]
});

The agent loops automatically: if it calls a tool, processes the result, and continues the conversation.

Question 3: How do you define custom tools?

The built-in tools (bash, read_file, etc.) handle common tasks. But what if you need something custom?

For example, imagine you're building a code review agent that needs to:

• Query your code review database
• Post comments to GitHub
• Fetch test coverage metrics

You can define these as custom tools:

const tools = [
  {
    name: "query_code_review_db",
    description: "Query the code review database for previous reviews",
    input_schema: {
      type: "object",
      properties: {
        repo: { type: "string", description: "Repository name" },
        file: { type: "string", description: "File path" }
      },
      required: ["repo", "file"]
    }
  },
  {
    name: "post_github_comment",
    description: "Post a comment on a GitHub PR",
    input_schema: {
      type: "object",
      properties: {
        repo: { type: "string" },
        pr_number: { type: "number" },
        comment: { type: "string" }
      },
      required: ["repo", "pr_number", "comment"]
    }
  }
];

When the agent calls these tools, your code handles the execution. This is how you integrate agents with your specific systems.

Pause and think: What systems do you work with that an agent might need to query or modify?

Question 4: When should you use the SDK directly instead of Claude Code?

This is the practical question: when does it make sense to learn the SDK instead of just using Claude Code?

Use Claude Code when:

• You're working on a project and need to interact with Claude in real-time
• You want the built-in terminal interface and convenience
• Your workflows fit Claude Code's model

Use the Agent SDK when:

• You're building a service that needs AI capabilities (embedding an agent in your app)
• You need a specialized interface or behavior
• You're building for CI/CD or headless environments
• You want to create domain-specific agents
• You're building a multi-agent system
• You need fine-grained control over the agentic loop

The key difference: Claude Code is a tool for you. The SDK is a library for developers building systems.

The Insight

The Claude Agent SDK is the foundational library that powers Claude Code. It provides the tools, session management, and agentic loop that you can use to build custom agents in Python or TypeScript. Claude Code is a specialized consumer application built on the SDK, but the SDK itself is open for developers to build their own AI agents with custom interfaces, tools, and behaviors.

The mental model: The Agent SDK is like a game engine. Claude Code is like a game built on that engine. The engine handles the hard parts (physics, rendering, events). Game developers use the engine to create specific games. You can use Claude Code as-is, or use the engine to build something completely different.

Try It

Let's build a minimal agent with the Agent SDK.

1. Install the SDK:

   npm install @anthropic-ai/sdk
   

2. Create a simple agent script:

   // agent.ts
   import Anthropic from "@anthropic-ai/sdk";
   
   const client = new Anthropic();
   
   async function chat(userMessage: string) {
     const response = await client.messages.create({
       model: "claude-3-5-sonnet-20241022",
       max_tokens: 1024,
       system: "You are a helpful assistant.",
       messages: [
         { role: "user", content: userMessage }
       ]
    });
   
     console.log(response.content[0].type === 'text' ? response.content[0].text : '');
   }
   
   chat("What's 2 + 2?");
   

3. Run it:

   npx ts-node agent.ts
   

4. Add a tool. Modify the agent to include the bash tool and handle tool calls in a loop. See the Agent SDK documentation for the full agentic loop implementation.

5. Notice the difference: You're directly calling the API, managing tools, handling responses. This is more control than Claude Code, but also more responsibility.

Key Concepts Introduced

Bridge to Lesson 46

You now understand the foundation: what the Agent SDK is and where Claude Code comes from. But understanding the architecture is different from using it.

Tomorrow's question: How do you actually build a functional agent with the SDK? What does the agentic loop look like in practice?

We'll write a real agent, handle tool calls, manage errors, and see the loop in action.

← Back to Curriculum · Lesson 46 →