Getting Started with Claude Code Agent SDK — Build Autonomous Agents Fast

What Is the Agent SDK?

The Claude Code Agent SDK is a framework for building autonomous agents powered by Claude models. Unlike simple API calls, an agent receives a goal, selects tools on its own, evaluates results, and executes a multi-step reasoning loop to reach a solution.

Traditional chatbots work in a single request-response cycle. With the Agent SDK, you can complete complex workflows — read files, identify issues, apply fixes, run tests, and report results — all from a single instruction.

Setup

Initialize your project and install the SDK.

mkdir my-agent && cd my-agent
npm init -y
npm install @anthropic-ai/claude-code --save

For TypeScript development, add type definitions as well.

npm install typescript @types/node --save-dev
npx tsc --init

Set your ANTHROPIC_API_KEY environment variable, and you’re ready to go.

export ANTHROPIC_API_KEY="sk-ant-..."

A Minimal Agent

Here’s a simple agent that can interact with the file system.

import { Claude } from "@anthropic-ai/claude-code";

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  maxTurns: 10,
});

async function main() {
  const result = await agent.run(
    "List all TODO comments in the src directory and sort them by priority"
  );
  console.log(result.text);
}

main();

The maxTurns parameter limits the maximum number of steps the agent can take. Always set this as a safeguard against infinite loops.

Defining Custom Tools

The real power of the Agent SDK lies in custom tools. By giving the agent access to external APIs or databases, you unlock much more practical automation.

import { Claude, Tool } from "@anthropic-ai/claude-code";

const fetchIssueTool: Tool = {
  name: "fetch_github_issue",
  description: "Fetch a GitHub issue",
  parameters: {
    type: "object",
    properties: {
      owner: { type: "string", description: "Repository owner" },
      repo: { type: "string", description: "Repository name" },
      number: { type: "number", description: "Issue number" },
    },
    required: ["owner", "repo", "number"],
  },
  async execute({ owner, repo, number }) {
    const res = await fetch(
      `https://api.github.com/repos/${owner}/${repo}/issues/${number}`,
      { headers: { Authorization: `token ${process.env.GITHUB_TOKEN}` } }
    );
    return await res.json();
  },
};

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  tools: [fetchIssueTool],
  maxTurns: 15,
});

With this definition, the agent calls fetch_github_issue when needed and decides its next action based on the retrieved information.

How Multi-Step Execution Works

Internally, the Agent SDK runs the following loop:

1. Planning — Break down the user’s instruction into required steps
2. Tool Selection — Choose the optimal tool from what’s available
3. Execution — Run the tool and capture results
4. Evaluation — Check if the goal has been achieved
5. Repeat or Complete — Loop back to step 1 if unfinished, or generate a final answer

This loop eliminates the need to hardcode every procedure in advance, enabling flexible processing that adapts to the situation.

Practical Example: Automated PR Review Agent

Let’s build a real-world use case — an automated Pull Request review agent.

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  tools: [fetchIssueTool, readFileTool, postCommentTool],
  maxTurns: 20,
  systemPrompt: `You are a code review expert.
Read the PR diff and review it for:
- Potential bugs
- Security risks
- Performance issues
- Improvement suggestions`,
});

const result = await agent.run(
  "Review PR #42 and leave comments if there are any issues"
);

By specifying the agent’s role and evaluation criteria in systemPrompt, you get consistent and reliable reviews.

Error Handling and Retries

Robust error handling is essential for production environments.

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  maxTurns: 10,
  onError: (error, context) => {
    console.error(`Error at step ${context.turn}:`, error.message);
    if (context.turn >= 3) {
      return "abort"; // Abort after 3 failures
    }
    return "retry"; // Retry otherwise
  },
});

Summary and Next Steps

With the Agent SDK, you can automate complex multi-step tasks instead of relying on single-shot AI responses. Start with small tasks like file organization or log analysis, then gradually add tools to expand your agent’s capabilities.

For the basics of Claude Code, check out the Getting Started Guide. For API-driven development, see the API Development Guide. For CLI integration, refer to CLI Tool Development.

For more details, visit the official Anthropic documentation and the Claude Code GitHub repository.