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
.tsfiles. - 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 SDKOnce installed, add your Claude API key to a .env file or directly in your configuration script. This will authenticate SDK usage.
# Example .env file
CLAUDE_API_KEY=your-api-key-hereFor 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
Import the
queryMethod
Start by importing thequerymethod from the SDK. This initializes an agent loop.javascriptimport { query } from "@anthropic-ai/agent-sdk";Define the Prompt and Settings
Configure your agent by setting up a prompt, defining permissions, and customizing supported tools.javascriptconst 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"], };Execute the Query
Pass the options to thequerymethod 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 generatedThe 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
Install the Warp Oz SDK
Install the Warp SDK to enable remote execution.
bashnpm install @warp/oz-sdk # Installs the Warp Oz SDKCreate a Cloud Environment
Set up a remote execution environment using the Warp Oz web console or CLI.
Configure Remote Runs
javascriptimport { 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.