Claude Agent SDK Guide Skill

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

| Directory | Purpose | |-----------|---------| | .claude/agents/ | Subagent definitions (Markdown) | | .claude/skills/ | Skill files (SKILL.md) | | .claude/commands/ | Slash commands (Markdown) | | .claude/settings.json | Hooks configuration | | CLAUDE.md | Project memory/context |

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 command to generate a new project.

Template Files

| Template | Purpose | |----------|---------| | assets/typescript/package.json | Node.js package config | | scripts/typescript/agent.ts | TypeScript agent entry | | assets/python/pyproject.toml | Python package config | | scripts/python/agent.py | Python agent entry | | assets/env-*.example | Provider config templates | | references/claude/*.md | Subagent/skill/command templates |

Tool Mapping

| User Selection | SDK Tools | |----------------|-----------| | File Operations | Read, Write, Edit, Glob, Grep | | Code Execution | Bash | | Web Search | WebSearch, WebFetch | | MCP Tools | (configured via mcpServers) |

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

Agent Skills: Claude Agent SDK Guide

Install this agent skill to your local

Skill Files