AI Workflows

How to Build a Custom AI Agent with Claude Agent SDK

Learn step-by-step how to build a custom AI agent using the Claude Agent SDK for various applications.

4 min read

Learn step-by-step how to build a custom AI agent using the Claude Agent SDK for various applications. This powerful SDK enables developers to integrate Claude's robust AI capabilities into their own applications with minimal effort.

Setting Up the Claude Agent SDK

The first step in building with the Claude Agent SDK is to prepare your development environment properly.

prerequisites

  • Node.js: Install Node.js (v16 or later recommended).
  • TypeScript Support (optional): Install TypeScript globally if using .ts files.
  • Claude API Key: Obtain an API key from your Claude developer console.
  • SDK Installation: Install the Claude Agent SDK via npm.

Installation and Configuration

Run the following command to install the SDK:

Install the SDK

npm install @anthropic-ai/agent-sdk
# Installs the Claude Agent SDK

Once installed, add your Claude API key to a .env file or directly in your configuration script. This will authenticate SDK usage.

bash
# Example .env file
CLAUDE_API_KEY=your-api-key-here

For TypeScript users, ensure your tsconfig.json file is configured to support ES modules.

Creating Your First AI Agent

Once the setup is complete, we can implement a basic AI agent.

steps

  1. Import the query Method
    Start by importing the query method from the SDK. This initializes an agent loop.

    javascript
    import { query } from "@anthropic-ai/agent-sdk";
  2. Define the Prompt and Settings
    Configure your agent by setting up a prompt, defining permissions, and customizing supported tools.

    javascript
    const options = {
        prompt: "Please review the images in the current folder and create a summary.",
        model: "claude-v1",
        workingDirectory: "/path/to/images",
        apiKey: "your-api-key-here",
        tools: ["readWrite", "bashExecution"],
    };
  3. Execute the Query
    Pass the options to the query method and iterate over the output.

    javascript
    (async () => {
        for await (const message of query(options)) {
            console.log("Agent response:", message.content);
        }
    })();

Handling Agent Responses

After configuring the agent, the next step is to process its responses effectively.

Run the Code

node your-agent.js
# Logs agent messages, showing progress and results
# Agent response: Summary of image contents generated

The SDK provides responses as an asynchronous stream of messages. Each message contains details like reasoning and output. You can extract and display the relevant content for user-facing interactions.

Building Enhanced Features with Claude Agent SDK

Using Warp Oz for Remote Agent Execution

Warp Oz allows you to run agents in a cloud environment. This is particularly useful when you need agents to perform long-running tasks without relying on the local machine.

steps

  1. Install the Warp Oz SDK

    Install the Warp SDK to enable remote execution.

    bash
    npm install @warp/oz-sdk
    # Installs the Warp Oz SDK
  2. Create a Cloud Environment

    Set up a remote execution environment using the Warp Oz web console or CLI.

  3. Configure Remote Runs

    javascript
    import { OzAPI } from "@warp/oz-sdk";
    
    const ozClient = new OzAPI({ apiKey: "your-warp-api-key-here" });
    
    (async () => {
        const run = await ozClient.run({
            prompt: "Analyze repository and generate a README.",
            environmentId: "your-environment-id",
        });
        console.log("Run started:", run.id);
    })();

Conclusion and Final Thoughts

FAQ

How does the Claude Agent SDK differ from the Claude Client SDK?

The Claude Agent SDK provides a fully functional agent loop out of the box, including tools like file I/O and web search. In contrast, the Client SDK is a basic wrapper for the API, requiring additional implementation for advanced features.

Can I customize agent behavior at runtime?

Yes, the SDK allows options such as tools, permissions, and prompts to be customized for each query, enabling dynamic behavior based on the specific task.

What are typical use cases for the Claude Agent SDK?

It’s commonly used for file analysis, task automation, and building interactive UIs. Its ability to configure permissions and tools makes it flexible for various domains.


Official reference: Claude Agent SDK documentation.