Welcome to Agent SDK! This is the first unit in your journey toward building sophisticated AI-powered development environments. Throughout this course, we'll transform Claude Code from a simple assistant into a powerful automation platform tailored to your team's needs.

In this lesson, we'll explore the Agent SDK, a set of Python and TypeScript libraries that let us build AI agents programmatically. We'll learn when to use the SDK versus the command-line interface (CLI), understand the core concepts, and write our first agent. By the end of this lesson, we'll have a solid foundation for creating custom automation workflows.

The Agent SDK consists of official libraries from Anthropic that enable us to build AI agents in Python and TypeScript. Think of it as the programmatic interface to Claude's capabilities: rather than interacting through a chat interface or CLI tool, we can embed Claude's reasoning and tool use directly into our applications.

The SDK provides fine-grained control over how Claude interacts with our codebase. We can control tool permissions, manage multi-turn conversations, and integrate custom functionality. This makes it ideal for building production-grade automation that needs to be reliable, maintainable, and secure.

While the CLI tool claude -p offers quick access to Claude's capabilities through shell commands, the Agent SDK gives us the full power of a programming language to orchestrate complex workflows.

The CLI shines in scenarios where we need quick, scriptable automation that integrates with existing tooling. We should reach for claude -p when working on:

• Shell scripting and one-off automation tasks
• Git hooks for pre-commit or pre-push validation
• CI/CD pipeline steps that need AI analysis
• Quick exploratory tasks during development
• Integration with other command-line tools via pipes

The command-line interface is perfect for these use cases because it requires minimal setup, integrates naturally with shell scripts, and produces text output that we can easily capture, parse, or redirect.

The Agent SDK becomes the better choice when we need to build applications with more sophisticated requirements. We should use the SDK when our automation needs:

• Multi-turn conversations that maintain context
• Session persistence and state management
• Custom tool development and integration
• Complex control flow and decision logic
• Production deployment with reliability guarantees
• Fine-grained permission and security controls

For example, building an automated documentation reviewer that analyzes multiple files, makes suggestions, waits for human feedback, and then validates changes requires the structure and control that only a programming language can provide. Similarly, a PR analysis bot that needs to coordinate multiple tools, manage state, and integrate with external APIs benefits from the SDK's capabilities.

Let's see how the same task looks with both approaches. Suppose we want Claude to review a documentation file. Here's the CLI version:

This works great for a quick check. Now here's a similar version using the Python SDK:

The SDK version is more verbose, but notice what we gain: streamed responses, permission control, and easy integration with application logic.

One important detail: allowed_tools is not a strict allowlist. It marks tools as pre-approved when permission checks are active. For unattended automation with permission_mode="bypassPermissions", disallowed_tools is usually the better way to enforce boundaries.

Before we can build our first agent, we need to install the Python SDK. The installation is straightforward using pip:

Before running queries, set the ANTHROPIC_API_KEY environment variable so the SDK can authenticate. In this course environment, the key is already configured for the practice tasks, so you do not need to set it manually here.

Now let's write our first agent using the Python SDK. This simple example will list all Markdown files in a documentation directory:

This agent uses the query function, which is the primary way to interact with Claude through the SDK. The function streams messages back to us asynchronously, allowing us to process responses as they arrive rather than waiting for everything to complete.

Note: allowed_tools=["Glob", "Read"] pre-approves those tools; it is not a strict allowlist.

Let's break down the key components of our first agent:

• async for iteration: We use async for because the SDK streams responses, giving us real-time updates as Claude reasons and uses tools.
• prompt: This is our natural language instruction to Claude, just as we'd type in a chat interface.
• ClaudeAgentOptions: This configuration object controls the agent's capabilities and behavior.
• allowed_tools: Pre-approves tools when permission checks are active.
• disallowed_tools: Explicitly blocks tools from being used.

The streaming approach means we can show progress to users, handle long-running operations gracefully, and even cancel operations if needed. Each message we receive could be Claude's reasoning, a tool call, or the final result.

The SDK is also available for TypeScript, with an API that mirrors the Python version closely. Here's the same agent in TypeScript:

The structure is nearly identical: we import the query function, provide a prompt and options, and iterate over the streamed messages. The main difference is syntactic: TypeScript uses camelCase (allowedTools), while Python uses snake_case (allowed_tools). This consistency makes it easy to work with both versions depending on our project's needs.

As in Python, allowedTools pre-approves tools rather than acting as a strict allowlist.

To install the TypeScript SDK in a Node.js project, run:

Let's build something more useful: a link checker that verifies all URLs in a documentation file.

This uses disallowed_tools with bypassPermissions, which is a better fit for unattended automation. The agent can still read the file and fetch links, but risky or unrelated tools are explicitly blocked.

allowed_tools and disallowed_tools do different things:

• allowed_tools pre-approves tools when permission checks are active.
• disallowed_tools explicitly blocks tools from being used.

With permission_mode="default", allowed_tools is useful for reducing prompts:

With permission_mode="bypassPermissions", the SDK does not prompt, so disallowed_tools is usually the better choice for enforcing boundaries:

This follows the principle of least privilege and makes automated agents safer and more predictable.

We've covered the foundations of the Agent SDK: what it is, when to use it versus the CLI, and how to build basic agents. We've seen how to set up the SDK, configure tool permissions, and work with streaming responses. We've also built two practical examples: a file lister and a link checker.

The key takeaway is that the Agent SDK gives us programmatic control over Claude's capabilities. While claude -p is perfect for quick automation and shell scripting, the SDK enables us to build production applications with complex workflows, custom tools, and fine-grained security.

A useful rule of thumb is that allowed_tools pre-approves tools, while disallowed_tools is better for enforcing boundaries in unattended automation.

Now it's time to put this knowledge into practice! In the upcoming exercises, we'll build agents that solve real-world problems, giving us hands-on experience with the SDK's capabilities and patterns.