Claude Agent Sdk

Claude Agent SDK

Build autonomous AI agents that read files, run commands, edit code, search the web, and more. The SDK provides the same tools, agent loop, and context management that power Claude Code.

Core Concept

The key design principle: give Claude a computer. By providing tools to run bash commands, edit files, create files, and search files, Claude can work like humans do on any digital task.

Agent Loop Pattern

Effective agents follow this feedback loop: gather context → take action → verify work → repeat

┌─────────────────────────────────────────────────────┐
│                    AGENT LOOP                       │
├─────────────────────────────────────────────────────┤
│  1. GATHER CONTEXT                                  │
│     - Read files, search codebase                   │
│     - Use subagents for parallel information        │
│     - Query external APIs via MCP                   │
│                                                     │
│  2. TAKE ACTION                                     │
│     - Execute tools (Read, Write, Edit, Bash)       │
│     - Generate and run code                         │
│     - Call external services                        │
│                                                     │
│  3. VERIFY WORK                                     │
│     - Run linters, tests, type checkers             │
│     - Visual feedback (screenshots)                 │
│     - LLM-as-judge for fuzzy validation             │
│     - Apply deterministic rules                     │
└─────────────────────────────────────────────────────┘

Quick Start

Installation

npm install -g @anthropic-ai/claude-code
npm install @anthropic-ai/claude-agent-sdk
export ANTHROPIC_API_KEY=your-api-key

Minimal Agent (TypeScript)

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
  for await (const message of query({
    prompt: "What files are in this directory?",
    options: {
      model: "opus",
      allowedTools: ["Glob", "Read"],
      maxTurns: 250
    }
  })) {
    if (message.type === "assistant") {
      for (const block of message.message.content) {
        if ("text" in block) console.log(block.text);
      }
    }
  }
}
main();

Minimal Agent (Python)

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="What files are in this directory?",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"])
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Reference Documentation

For detailed implementation patterns, see:

• [apireference.md](references/apireference.md): Complete API, options, hooks, subagents, V2 API
• [PATTERNS.md](references/PATTERNS.md): Code review, research, automation, chat patterns
• [TOOLS.md](references/TOOLS.md): Built-in tools and MCP integration
• [PRODUCTION.md](references/PRODUCTION.md): Deployment, sandboxing, security, monitoring

Scripts

• [createagent.ts](scripts/createagent.ts): Generate new agent projects from templates

Built-in Tools

| Tool | Purpose | |------|---------| | Read | Read any file in working directory | | Write | Create new files | | Edit | Make precise edits to existing files | | Bash | Run terminal commands | | Glob | Find files by pattern | | Grep | Search file contents with regex | | WebSearch | Search the web | | WebFetch | Fetch and parse web pages | | Task | Spawn subagents for parallel work |

Agent Types by Use Case

Code Review Agent: allowedTools: ["Read", "Glob", "Grep"] File Automation Agent: allowedTools: ["Read", "Write", "Edit", "Bash", "Glob"] Research Agent: allowedTools: ["WebSearch", "WebFetch", "Read", "Write"] Multi-Agent Orchestrator: allowedTools: ["Read", "Glob", "Grep", "Task"]

Key Options

options: {
  model: "opus" | "sonnet" | "haiku",  // Model selection
  maxTurns: 250,                        // Max agent iterations
  allowedTools: [...],                  // Tools available to agent
  permissionMode: "default" | "acceptEdits" | "bypassPermissions",
  systemPrompt: "...",                  // Custom system instructions
  settingSources: ["project"],          // Load skills from .claude/skills/
  outputFormat: { type: "json_schema", schema: {...} }  // Structured output
}

Message Stream Types

for await (const message of query({...})) {
  switch (message.type) {
    case "system":    // Session init, available tools
    case "assistant": // Claude's responses and tool calls
    case "result":    // Final result with cost info
  }
}

When to Use Each Pattern

Simple task, single file: Direct query with basic tools Complex analysis: Add structured output schema Large codebase: Use subagents for parallel search External integrations: Add MCP servers for custom tools Production deployment: Add hooks for auditing and guardrails

Verification Strategies

1. Linting/Type checking: Run after code generation
2. Visual feedback: Screenshot renders for UI work
3. Deterministic rules: Hooks that check specific conditions
4. LLM-as-judge: Subagent evaluates output quality

Context Engineering

The file system represents information that could be pulled into context:

• Use CLAUDE.md for project-level instructions
• Organize data folders for agentic search
• Let Claude use grep/tail on large files
• Use subagents to isolate context and return summaries

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AlexAtmtit
• Source: AlexAtmtit/custom-skills
• License: MIT

Install and usage instructions live in the source repository linked above.