Building AI Agents: Claude Agent SDK and Claude Code for Coding

As someone who lives and breathes code, I’ve seen plenty of tools come and go, but what’s happening now feels different. The buzz is no longer just about AI assisting us; it’s about AI acting for us. We’re entering the era of AI agents: systems that can understand a goal, create a plan, and execute tasks with a level of autonomy I once only dreamed of.

Anthropic is paving the way. If you’re used to interacting with AI through a helpful tool like the Claude AI Chrome Extension, you’ve only seen the tip of the iceberg. The real power lies in the engine underneath, like thier new model

Claude Sonnet 4.5** . ** Now, Anthropic is letting us harness that engine to build our own agents with their Claude Agent SDK.

If you’ve ever imagined giving an AI a complex coding problem or a data analysis project and having it work through the steps just like a human developer would, then you’re thinking like an agent builder. This is precisely the power the Claude Agent SDK puts directly into your hands. In this guide, I’ll take you deep into this amazing toolkit, exploring how it works and how you can get started building the next generation of AI applications.

What is the Claude Agent SDK? From Coding Assistant to General-Purpose Agent Toolkit

Claude Agent SDK is a collection of libraries and tools designed to bridge the gap between a large language model like Claude and the real world of computing. Think of it as giving Claude a computer of its own—complete with a file system to read and write files, a terminal to execute commands, and a set of tools to interact with APIs and other services.

The project’s journey began with the Claude Code SDK, a specialized “agent harness” built to supercharge developer productivity at Anthropic. The goal was to create an AI assistant that didn’t just suggest code but could actively participate in the development lifecycle: understanding a codebase, writing new features, running tests, and debugging errors.

However, the team quickly realized that the underlying framework was far too powerful to be limited to just coding. The same principles that allow an agent to refactor a Python script can be applied to summarizing research papers, analyzing financial data, or even helping with video production.

To reflect this broader vision, the Claude Code SDK was renamed the Claude Agent SDK. It’s a clear signal to developers: this is your toolkit for building powerful, autonomous agents for almost any conceivable task. It provides the essential scaffolding to let Claude reason, plan, and act in a controlled environment.

READ MORE: Claude 3.5 Sonnet vs GPT4o: Side-by-Side Tests

How the Claude Agent SDK Works ?

To build effective agents, you need more than just a powerful LLM. You need a structured process for interaction, execution, and verification. The Claude Agent SDK is built around a simple yet powerful agentic loop that mirrors how a human expert tackles a complex problem: Gather Context -> Take Action -> Verify Work.

This iterative cycle allows the agent to build understanding, make progress, and self-correct, leading to more reliable and sophisticated outcomes.

Step 1: Gathering Comprehensive Context

Before an agent can act, it needs to understand the problem space. A human developer wouldn’t start coding without reading the project requirements, exploring the existing codebase, and looking at relevant documentation. The Claude Agent SDK equips agents with similar abilities to gather rich context.

• Agentic Search and File System: The SDK gives Claude the ability to navigate a project’s file system. It can list directories, read file contents, and search for specific code snippets or keywords. This is crucial for tasks that require understanding an entire codebase, not just a single file.
• Semantic Search: Beyond simple keyword matching, agents can perform semantic searches. This means they can search for concepts and ideas, not just literal strings. For example, you could ask the agent to “find the function that handles user authentication,” and it could locate the relevant code even if the word “authentication” isn’t explicitly used in the function name.
• Subagents: For truly complex problems, the SDK supports the concept of subagents. A primary agent can delegate smaller, specialized tasks to other agents. For example, a “feature implementation” agent might spawn a “database migration” subagent and a “unit test writing” subagent to handle specific parts of the overall task.

Step 2: Taking Decisive Action with Tools

Once the agent has sufficient context, it’s time to act. This is where the “tool use” capabilities of Claude come into play. The Claude Agent SDK provides a secure and structured way for the model to use predefined tools to interact with its environment.

• The Concept of “Tools”: In the SDK, a tool is essentially a function that the agent can call. This could be anything from a simple calculator to a complex function that interacts with a third-party API. You define the tools, and Claude intelligently decides when and how to use them based on the task at hand.
• Executing Bash & Scripts: One of the most powerful built-in tools is the ability to execute shell commands in a sandboxed environment. This allows the agent to run compilers, linters, test suites, or any other command-line utility, just like a developer would in their terminal.
• Code Generation and Modification: The agent can write new code to files, modify existing files, and even delete them. This is the core of its ability to perform software development tasks, from fixing a bug to scaffolding an entire new service.

Step 3: Verifying the Work and Iterating

Making changes is only half the battle. A good agent, like a good developer, must verify its work. The agentic loop isn’t complete without a feedback mechanism to ensure the actions taken have produced the desired result.

• Defining Rules and Constraints: You can set up rules for the agent. For example, you can require that all generated code must pass a linter and all existing unit tests before the task is considered complete.
• Visual Feedback: In IDE integrations like the one for VS Code, developers can see the agent’s proposed changes in real-time via inline diffs. This “over-the-shoulder” view provides a powerful form of human-in-the-loop verification.
• Using an “LLM as a Judge”: A fascinating verification technique involves using another LLM instance (or even the same one with a different prompt) to act as a “judge.” You can ask it to review the work done by the primary agent against a set of criteria. For instance: “Does this new code adhere to the project’s style guide? Is the logic sound?” This creates a powerful, automated quality control loop.

Getting Started: Your First Steps with the Claude Agent SDK

Ready to build your first agent? Getting started is surprisingly straightforward. The SDK is available as a Python package, making it accessible to a vast community of developers.

Installation and Setup

First, you’ll need to install the SDK using pip. It’s best practice to do this within a virtual environment.

bash
pip install claude-agent-sdk

Next, you’ll need an Anthropic API key. You can get one from the Anthropic console. Once you have your key, you should set it as an environment variable for security.

bash
export ANTHROPIC_API_KEY="your-api-key-here"

The SDK will automatically detect and use this environment variable for authentication, so you don’t need to hardcode your key in your scripts.

Your First Query: A “Hello, World!” Example

With the SDK installed and authenticated, you can make your first call. This simple example demonstrates the basic query function, which is the primary way to interact with an agent.

python
import asyncio
from claude_agent_sdk import ClaudeSDKClient

async def main():
    # Initialize the client. It automatically picks up the API key from your environment.
    client = ClaudeSDKClient()

    # The query function sends a prompt to the Claude agent.
    # The 'model' parameter specifies which Claude model to use.
    response = await client.query(
        "Hello, world! Write a short Python script to print this message.",
        model="claude-3-5-sonnet-20240620"
    )

    # The response contains the agent's final answer.
    print(response)

if __name__ == "__main__":
    asyncio.run(main())

When you run this script, the Claude agent will respond with the Python code to print “Hello, world!”. This simple interaction already shows the power of the SDK: it handles the complex back-and-forth communication with the model, allowing you to focus on the task you want to accomplish.

Unleashing the Power: Building Agents with Custom Tools

The true magic of the Claude Agent SDK is unlocked when you give your agent custom tools. This allows you to extend its capabilities beyond the built-in functions and tailor it to your specific domain or problem.

Defining a Custom Tool with the @tool Decorator

The SDK makes defining a new tool incredibly easy using the @tool decorator. You simply write a standard Python function and decorate it. The function’s name, parameters, and docstring are automatically used to create a description that Claude can understand.

Let’s create a tool that fetches the current price of a stock.

python
import asyncio
from claude_agent_sdk import ClaudeSDKClient, tool

# A mock function to simulate fetching a stock price from an API.
def get_stock_price_from_api(symbol: str) -> float:
    """A mock function to simulate fetching a stock price."""
    # In a real application, this would make an API call.
    if symbol.upper() == "ACME":
        return 125.75
    elif symbol.upper() == "WIDGET":
        return 42.50
    else:
        return 0.0

@tool
def get_stock_price(symbol: str) -> str:
    """
    Fetches the current stock price for a given stock symbol.
    Args:
        symbol (str): The stock symbol, e.g., 'ACME'.
    Returns:
        A string describing the current price or an error message.
    """
    price = get_stock_price_from_api(symbol)
    if price > 0:
        return f"The current price of {symbol.upper()} is ${price}."
    else:
        return f"Could not find the price for symbol {symbol.upper()}."

async def main():
    client = ClaudeSDKClient()
    
    # We pass our custom tool to the query function.
    response = await client.query(
        "What is the current stock price for ACME?",
        tools=[get_stock_price],
        model="claude-3-5-sonnet-20240620"
    )
    
    print(response)

if __name__ == "__main__":
    asyncio.run(main())

How Claude Decides to Use Your Tools

When you run the code above, something remarkable happens.

1. You send the prompt “What is the current stock price for ACME?” to Claude.
2. Along with the prompt, the SDK sends the definition of the get_stock_price tool (derived from its name, parameters, and docstring).
3. Claude analyzes the prompt and recognizes that it needs to find a stock price. It sees that it has a tool perfectly suited for this task.
4. Claude decides to call get_stock_price with the argument symbol='ACME'.
5. The SDK intercepts this decision, executes your actual Python function get_stock_price('ACME'), and captures the return value: "The current price of ACME is $125.75.".
6. The SDK sends this result back to Claude.
7. Claude uses the tool’s output to formulate its final, natural language answer, which is then printed to your console.

This entire reasoning process is handled automatically. The quality of your docstring is critical—it’s the primary way Claude understands what your tool does and how to use it.

Advanced Concepts and Protocols

As you build more complex agents, you’ll encounter some of the deeper concepts that make the SDK robust and secure.

Understanding the Model Context Protocol (MCP)

The Model Context Protocol (MCP) is the communication layer that enables the seamless interaction between Claude and its tools. It’s the standardized format for messages passed back and forth. While the SDK abstracts most of this away, understanding it is helpful. When your code defines a tool with @tool, the SDK is essentially creating an “in-process MCP server” that listens for tool-use requests from Claude, executes the corresponding Python function, and sends the results back.

Managing the Working Directory and State

For tasks that involve file manipulation, the SDK provides a sandboxed working directory. The agent can create, read, and modify files within this directory without affecting your broader system. This is crucial for both security and reproducibility. Managing the state within this directory is key for long-running tasks where an agent might need to pick up where it left off.

Safety First: Tool Permissions and Guardrails

Giving an AI the ability to execute code and shell commands is incredibly powerful, but it also requires strong safety measures. The Claude Agent SDK is built with safety as a core principle. It includes features like:

• Forbidden Command Patterns: The bash tool has built-in protections to block potentially dangerous commands.
• Tool Permissions: You can configure permissions to explicitly control which tools an agent is allowed to use for a given task.
• Human-in-the-Loop: For critical operations, you can design your agent to require human confirmation before executing a command or modifying a file.

**READ MORE: **9 INSANE Claude Sonnet 3.5 Use Cases !

Practical Applications: What Can You Build?

The versatility of the Claude Agent SDK means its applications are limited only by your imagination. It’s already being used to power integrations in major developer tools and can be adapted for countless custom solutions.

Supercharging Developer Environments

The most immediate application is in enhancing developer workflows. A prime example is the Claude Agent integration in JetBrains IDEs. This brings the power of an agentic Claude directly into tools like PyCharm and IntelliJ IDEA. Developers can use the AI chat to ask the agent to perform complex tasks like:

• “Refactor this class to use the repository pattern.”
• “Find any potential security vulnerabilities in this module and suggest fixes.”
• “Write unit tests for the UserService class, ensuring all public methods are covered.”

The agent can read the relevant files, write the new code, and present the changes as a diff, all within the familiar IDE environment. Similarly, the native VS Code extension for Claude Code provides this same deep integration for users of Microsoft’s popular editor.

Custom Coding and DevOps Agents

You can build standalone agents to automate common software development and operations tasks:

• Automated Code Reviewer: An agent that reads a pull request, checks the code against project guidelines, looks for common bugs, and leaves constructive comments.
• Database Migration Assistant: An agent that can connect to a database, inspect its schema, and generate the necessary migration scripts to update it based on new model definitions.
• CI/CD Pipeline Troubleshooter: An agent that can be triggered when a build fails. It can read the error logs, inspect the codebase, and attempt to identify the root cause of the failure.

Beyond Code: Agents for Research and Data Analysis

The SDK’s capabilities extend far beyond programming:

• Research Assistant: Build an agent that can take a research topic, use tools to search the web and academic databases (via APIs), read and summarize relevant papers, and compile a detailed report with citations.
• Data Analyst: Create an agent that can connect to a data source, use tools like Pandas or SQL to clean and analyze the data, generate visualizations, and produce a narrative summary of its findings.
• Content Creation Agent: An agent that can take a simple brief, research the topic, write a draft, and even use tools to find or generate appropriate images for an article.

Conclusion:

The Claude Agent SDK represents a significant step forward in our ability to collaborate with artificial intelligence. It moves us from a paradigm of simple question-and-answer to one of goal-oriented partnership. By providing a robust, secure, and developer-friendly framework for building agents, Anthropic has given us the tools to create applications that can reason, plan, and execute complex tasks autonomously.

Whether you’re looking to automate tedious parts of your development workflow, build a powerful research assistant, or create an entirely new category of AI-powered products, the Claude Agent SDK is your entry point into the exciting future of agentic AI. The journey is just beginning, and the tools are now in your hands.

---

FAQ:

Is the Claude Agent SDK free to use?

The SDK itself is an open-source Python library and is free to download and use. However, it makes API calls to Anthropic’s Claude models, which are subject to standard API pricing. You will be billed for the token usage generated by your agents’ interactions with the Claude models.

What programming languages are supported?

Currently, the official Claude Agent SDK is available for Python. Given Python’s dominance in the AI/ML space, this covers a large portion of the developer community. Community-driven SDKs for other languages may emerge over time.

How does the Claude Agent SDK differ from other agent frameworks like LangChain or LlamaIndex?

While frameworks like LangChain and LlamaIndex are excellent general-purpose toolkits for building LLM applications, the Claude Agent SDK is specifically optimized for deep integration with Claude models. It is designed from the ground up to leverage Claude’s advanced reasoning and tool-use capabilities, and it powers Anthropic’s own first-party products like Claude Code. This results in a highly tuned and cohesive experience when building agents with Claude.

What is the difference between Claude Code and the Claude Agent SDK?

Claude Code is a specific product—an AI coding assistant available in IDEs and the terminal. The Claude Agent SDK is the underlying technology that powers Claude Code. Anthropic has made this powerful SDK available to all developers so they can build their own custom agents, whether for coding or for completely different tasks.

How secure is it to let an AI agent run shell commands?

Security is a primary design consideration of the SDK. The bash tool runs within a sandboxed environment, and there are built-in safeguards to prevent the execution of known dangerous command patterns. However, developers should always follow best practices for security. This includes running agents with the minimum necessary permissions, carefully defining and restricting the tools they can access, and implementing human-in-the-loop checks for any critical or destructive operations.