Claude Agent SDK Guide

Build custom AI agents powered by Claude. Same infrastructure as Claude Code.

Installation

TypeScript

npm install @anthropic-ai/claude-agent-sdk

Python

pip install claude-agent-sdk

Core Features

Context Management

Automatic compaction ensures your agent doesn't run out of context during extended operations.

Tool Ecosystem

Built-in capabilities:

• File operations - Read, write, edit files
• Code execution - Run bash commands safely
• Web search - Access real-time information
• MCP extensibility - Add custom tools via Model Context Protocol

Permission Controls

{
  allowedTools: ['Read', 'Write', 'Bash'],  // Explicit allowlist
  disallowedTools: ['WebSearch'],            // Explicit blocklist
  permissionMode: 'default' | 'strict'       // Overall strategy
}

Authentication Providers

Anthropic API (Default)

export ANTHROPIC_API_KEY=sk-ant-...

Amazon Bedrock

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=us-east-1

Google Vertex AI

export CLAUDE_CODE_USE_VERTEX=1
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
export VERTEX_REGION=us-central1
export VERTEX_PROJECT_ID=your-project

Microsoft Foundry

export CLAUDE_CODE_USE_FOUNDRY=1
# Azure credentials configuration

File-Based Configuration

.claude/agents/

.claude/skills/

SKILL.md

.claude/commands/

.claude/settings.json

CLAUDE.md

Enable project settings:

{
  settingSources: ['project']
}

Code Examples

TypeScript: Basic Agent

import { Agent } from '@anthropic-ai/claude-agent-sdk';

const agent = new Agent({
  model: 'claude-sonnet-4-20250514',
  allowedTools: ['Read', 'Write', 'Bash'],
  systemPrompt: `You are a code review assistant.
    Analyze code for bugs, security issues, and best practices.`,
});

const result = await agent.run({
  prompt: 'Review the code in src/auth.ts for security issues',
});

console.log(result.output);

TypeScript: Agent with MCP Tools

import { Agent } from '@anthropic-ai/claude-agent-sdk';

const agent = new Agent({
  model: 'claude-sonnet-4-20250514',
  mcpServers: {
    database: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-postgres'],
      env: { DATABASE_URL: process.env.DATABASE_URL },
    },
  },
});

const result = await agent.run({
  prompt: 'List all users who signed up in the last 24 hours',
});

Python: Basic Agent

from claude_agent_sdk import Agent

agent = Agent(
    model="claude-sonnet-4-20250514",
    allowed_tools=["Read", "Write", "Bash"],
    system_prompt="""You are a code review assistant.
    Analyze code for bugs, security issues, and best practices.""",
)

result = agent.run(
    prompt="Review the code in src/auth.py for security issues"
)

print(result.output)

Python: Agent with Custom Permissions

from claude_agent_sdk import Agent, PermissionMode

agent = Agent(
    model="claude-sonnet-4-20250514",
    permission_mode=PermissionMode.STRICT,
    allowed_tools=["Read", "Grep", "Glob"],
    disallowed_tools=["Bash"],  # Extra safety
)

result = agent.run(
    prompt="Find all TODO comments in the codebase"
)

Agent Types & Use Cases

Coding Agents

• SRE Diagnostics - Analyze logs, identify issues, suggest fixes
• Security Auditing - Scan for vulnerabilities, check dependencies
• Incident Triage - Correlate alerts, gather context, draft runbooks
• Code Review - Enforce standards, catch bugs, suggest improvements

Business Agents

• Legal Review - Analyze contracts, flag risks, summarize terms
• Financial Analysis - Process reports, identify anomalies, forecast
• Customer Support - Handle tickets, route issues, draft responses
• Content Creation - Generate docs, edit copy, ensure consistency

Best Practices

Start Simple

Begin with minimal tool access and expand as needed:

// Start here
allowedTools: ['Read']

// Then add as required
allowedTools: ['Read', 'Grep', 'Glob']

// Only if truly needed
allowedTools: ['Read', 'Write', 'Bash']

Use Subagents for Complex Tasks

Break large tasks into specialized subagents:

.claude/agents/
├── code-reviewer.md      # Reviews code changes
├── test-writer.md        # Generates tests
└── doc-generator.md      # Creates documentation

Handle Errors Gracefully

try {
  const result = await agent.run({ prompt });
  if (result.error) {
    console.error('Agent error:', result.error);
  }
} catch (error) {
  console.error('SDK error:', error);
}

Monitor Agent Behavior

const agent = new Agent({
  onToolUse: (tool, input) => {
    console.log(`Tool: ${tool}, Input: ${JSON.stringify(input)}`);
  },
  onThinking: (thought) => {
    console.log(`Thinking: ${thought}`);
  },
});

Project Scaffolding

Use

/agent-sdk:agent-scaffold

Template Files

assets/typescript/package.json

scripts/typescript/agent.ts

assets/python/pyproject.toml

scripts/python/agent.py

assets/env-*.example

references/claude/*.md

Tool Mapping

System Prompts

Coding Agent:

You are a coding assistant that helps developers write better code.
Analyze code for bugs, security issues, and best practices.

Business Agent:

You are a business analyst assistant.
Help with document analysis, data extraction, and report generation.

Resources

• TypeScript: anthropics/claude-agent-sdk-typescript
• Python: anthropics/claude-agent-sdk-python
• Docs: platform.claude.com/docs/en/agent-sdk/overview