← 16.517.10 →
838 words Slides

17.1 Agent SDK Overview

Course: Claude Code - Enterprise Development

Section: Claude Agent SDK

Video Length: 3-4 minutes

Presenter: Daniel Treasure

Opening Hook

"You've been using Claude Code as a CLI—great for interactive work. But what if you need to embed Claude agents in your applications? Build long-running workflows, integrate with production systems, or orchestrate teams of agents? That's where the SDK comes in."

Key Talking Points

What to say:

  • "The SDK is a programmatic interface to Claude agents. You define agents in Python or TypeScript, not in the terminal."
  • "CLI is for interactive use: one-off tasks, quick automation. SDK is for applications: stateful, persistent, integrated."
  • "With the SDK, you can: manage agent lifecycle, handle permissions with callbacks, orchestrate multiple agents, stream responses."
  • "We'll spend the next 9 videos building production agent workflows with the SDK."

What to show on screen:

  • Side-by-side: CLI command vs. SDK code
  • Simple Python example showing agent definition
  • Agent running inside an application context
  • CLI output vs. SDK streaming output

Demo Plan

[00:00 - 01:00] CLI vs. SDK Decision Tree 1. Show decision matrix on screen: - Interactive? One-off? → CLI - Application? Persistent? Long-running? → SDK - Multiple agents? Orchestration? → SDK 2. Show real scenarios: "I'm debugging code quickly" (CLI) vs. "I'm building a code review service" (SDK) 3. Emphasize: both are valid. Use the right tool for the job.

[01:00 - 02:00] SDK Basics (Python) 1. Show minimal Python agent: python from claude_code import Agent agent = Agent(model="claude-sonnet-4-5-20250929", system_prompt="You are a helpful assistant") result = agent.run("What is 2+2?") 2. Break down: model selection, system prompt, tools available 3. Show execution: agent runs, returns result object 4. Contrast with CLI: CLI is claude code "What is 2+2?", SDK is programmatic

[02:00 - 03:00] Use Cases & Examples 1. Code review service: Agent reads pull requests, generates feedback 2. Data pipeline: Agent transforms data, logs progress, handles errors 3. Multi-agent orchestration: Parent agent delegates tasks to subagents 4. Streaming response UI: Agent streams analysis, UI updates in real-time 5. Permission-gated actions: Agent requests approval before executing writes

[03:00 - 03:30] Preview of Next Videos 1. Mention: 17.2-17.3 will show setup for Python and TypeScript 2. Mention: 17.4-17.5 will show advanced features (streaming, permissions) 3. Mention: 17.6-17.9 will show production patterns (sessions, custom tools, subagents)

Code Examples & Commands

Minimal SDK Example (Python):

from claude_code import Agent

# Define an agent
agent = Agent(
    model="claude-sonnet-4-5-20250929",
    system_prompt="You are a code reviewer. Analyze code for quality, security, and performance."
)

# Run the agent
result = agent.run("Review this Python function for security issues: def login(username, password): return db.query(f'SELECT * FROM users WHERE username = {username} AND password = {password}')")

# Access result
print(f"Status: {result.status}")
print(f"Output: {result.output}")

CLI Equivalent:

claude code "Review this Python function for security issues: ..."

Comparison: | Aspect | CLI | SDK | |--------|-----|-----| | Interface | Terminal commands | Python/TypeScript API | | Persistence | Per-session | Application lifetime | | State | Lost after exit | Maintained in memory | | Permissions | Interactive prompts | Callback handlers | | Streaming | Limited | Full control | | Orchestration | Manual (CLI loops) | Programmatic |

Gotchas & Tips

Gotcha 1: Model Selection - SDK defaults to specific models; make sure you're using the right one for your use case - Tip: Use claude-sonnet for most tasks, claude-opus for complex reasoning

Gotcha 2: API Key Management - SDK needs ANTHROPIC_API_KEY set in environment - If using MCP tools, credentials must be available to SDK context

Gotcha 3: Tool Availability - Not all CLI tools are available in SDK yet - Check: Read, Grep, Bash, Glob are core; custom tools depend on implementation

Tip 1: Start with CLI, Migrate to SDK - Prototype workflows in CLI first - Once validated, move to SDK for production

Tip 2: Error Handling - SDK requires explicit error handling (try/except) - CLI is more forgiving

Tip 3: Environment Variables - Pass configuration to agents via environment, not hardcoding

Lead-out

"You now understand the SDK's place in the Claude ecosystem. Next video, we'll dive into Python SDK setup—installing the package, creating your first agent, and running it from a script."

Reference URLs

  • Anthropic Python SDK: https://github.com/anthropics/anthropic-sdk-python
  • Anthropic TypeScript SDK: https://github.com/anthropics/anthropic-sdk-typescript
  • Claude Code Agent SDK: [official docs]
  • API Reference: https://docs.anthropic.com/

Prep Reading

  • Install Python 3.10+ and Node.js 18+ (5 min)
  • Review Anthropic SDK structure (5 min)

Notes for Daniel

  • Tone: Position the SDK as the "production" version—not harder, just more intentional.
  • Common misconception: Some developers think CLI and SDK are mutually exclusive. Clarify: they're complementary. Use CLI for learning/debugging, SDK for applications.
  • Enterprise angle: Mention that enterprises use SDK for: code review services, deployment pipelines, data transformation, incident response.
  • Pacing: This is an overview, so keep it high-level. Deep dives come in 17.2-17.10.