Building Custom AI Agents with Claude Agent SDK: A Step-by-Step Guide

Introduction

The era of AI chatbots that simply answer questions is behind us. In 2026, the frontier has shifted to AI agents — autonomous programs that plan, reason, call tools, and execute multi-step tasks with minimal human intervention. According to Deloitte's 2025 enterprise AI survey, over 60% of enterprises are now piloting agentic AI workflows, up from under 10% just two years ago. The shift from "AI that answers" to "AI that acts" is well underway.

At the center of this movement is the Claude Agent SDK, an open-source framework released by Anthropic that gives developers the exact same tooling that powers Claude Code — Anthropic's own agentic coding assistant. If you've ever wanted to build an agent that can read files, write code, search the web, query databases, and orchestrate sub-tasks, this SDK is the most direct path from idea to production.

In this guide, we'll walk through building a custom AI agent from scratch, connecting it to real-world data sources like commerce APIs, and deploying it with the guardrails production workloads demand.

What Is the Claude Agent SDK?

The Claude Agent SDK is an open-source Python and TypeScript framework for building AI agents on top of Anthropic's Claude models. As Anthropic described in their blog post on building effective agents, the best agent architectures are often surprisingly simple — and the SDK reflects that philosophy.

Out of the box, the SDK provides a rich set of built-in tools:

• Read, Write, Edit — File system operations for reading, creating, and modifying files
• Bash — Execute shell commands with timeout and background support
• Glob, Grep — Fast file search by pattern and content search via regex
• WebSearch, WebFetch — Search the internet and fetch web page contents
• Agent — Spawn subagents for parallel and delegated work

The pricing model is straightforward: the SDK itself is free and open-source. You pay only for Claude API tokens consumed during agent execution. This makes it accessible for experimentation while scaling linearly with production usage.

What sets the Claude Agent SDK apart from frameworks like LangChain or CrewAI is its tight integration with Claude's native tool-calling capabilities. There's no translation layer — the tools are first-class citizens in the model's reasoning loop.

Setting Up Your First Agent

Getting started takes less than five minutes. Install the SDK and create a minimal agent:

pip install claude-agent-sdk

The SDK exposes two primary interfaces: query() for simple one-shot tasks, and ClaudeSDKClient for interactive, stateful conversations. For most automation use cases, query() is all you need:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        model="claude-sonnet-4-6",
        tools=["Read", "Write", "Bash", "WebSearch"],
    )
    async for message in query(prompt="Analyze the sales data in data.csv and create a summary report", options=options):
        if hasattr(message, 'result'):
            print(message.result)

asyncio.run(main())

When the agent runs, it enters an autonomous loop: it reads the prompt, decides which tools to invoke, executes them, interprets the results, and continues until the task is complete. The agent might read data.csv with the Read tool, run pandas commands via Bash, and write a Markdown report using Write — all without you specifying the steps.

For TypeScript developers, the setup is equally concise:

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

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

const messages = query({
  prompt: "Analyze the sales data in data.csv and create a summary report",
  options: {
    model: "claude-sonnet-4-6",
    tools: ["Read", "Write", "Bash", "WebSearch"],
  },
});

for await (const message of messages) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

The key insight here is that you don't orchestrate the steps — the model does. You describe the goal, and the agent figures out the tool-calling sequence. This is the fundamental difference between a tool-using LLM and an agent.

Connecting External Data Sources via MCP

Built-in tools cover local operations, but real-world agents need access to external systems — databases, APIs, SaaS platforms, and proprietary data sources. This is where the Model Context Protocol (MCP) comes in.

MCP is an open standard that defines how AI models connect to external tools and data sources. Think of it as a USB-C port for AI: any MCP-compatible server can plug into any MCP-compatible client. The Claude Agent SDK has first-class MCP support.

MCP Integration for Commerce Data

Where things get powerful is when you connect MCP servers that expose rich, domain-specific capabilities. For example, you can connect the APIClaw MCP server to give your agent access to real-time Amazon product data, market analytics, and competitor intelligence:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        model="claude-sonnet-4-6",
        mcp_servers={
            "apiclaw": {
                "type": "http",
                "url": "https://api.apiclaw.io/mcp",
                "headers": {"Authorization": "Bearer hms_xxx"},
            }
        },
    )
    async for message in query(
        prompt="Find the top 10 yoga mat products under $30 with monthly sales > 500",
        options=options,
    ):
        if hasattr(message, 'result'):
            print(message.result)

asyncio.run(main())

The agent automatically discovers the tools exposed by the MCP server — product search, keyword analysis, market trends, competitor lookup — and uses them as needed to fulfill the prompt. No manual tool wiring required.

This pattern is incredibly powerful for ecommerce automation. Imagine an agent that:

1. Searches for trending product categories using APIClaw's market data
2. Identifies gaps where demand exceeds supply
3. Analyzes competitor pricing and review sentiment
4. Generates a sourcing recommendation report

All from a single natural-language prompt.

Get started by installing APIClaw Skills in your AI agent — no code required.

Multi-Agent Orchestration Patterns

Single agents work well for focused tasks, but complex workflows benefit from breaking work across multiple agents. The Claude Agent SDK's built-in Agent tool enables this natively — and as Nader Dabit's guide on Claude Agent SDK illustrates, the orchestration patterns are more straightforward than you might expect.

The Orchestrator-Worker Pattern

The most common pattern is an orchestrator agent that plans the work and delegates to specialized subagents. You achieve this by including the Agent tool in your options — the model itself decides when to spawn subagents:

options = ClaudeAgentOptions(
    model="claude-sonnet-4-6",
    tools=["Agent", "Read", "Write"],
    system_prompt="""You are a research orchestrator. Break complex research
    tasks into subtasks and delegate to subagents. Each subagent should focus
    on one specific aspect. Synthesize their results into a final report.""",
)

async for message in query(
    prompt="""Research the US yoga mat market:
    1. Find top 20 products by revenue (use product search)
    2. Analyze keyword trends for "yoga mat" variations
    3. Identify pricing sweet spots and gaps
    4. Summarize findings with actionable recommendations""",
    options=options,
):
    if hasattr(message, 'result'):
        print(message.result)

When the orchestrator invokes the Agent tool, it spawns a subagent that runs independently. A critical design detail: all intermediate tool calls within a subagent stay contained — only the final result message returns to the orchestrator. This keeps the parent agent's context window clean and focused.

The Pipeline Pattern

For sequential workflows where each stage's output feeds the next, a pipeline pattern works well. Instead of one orchestrator managing everything, each agent processes its input and hands off to the next stage. For example, a product research pipeline might flow as: data collection agent → analysis agent → report generation agent.

This pattern is particularly effective when each stage requires different tools or different levels of model capability. The data collection stage might use claude-haiku-4-5 for simple API calls (cheaper and faster), while the analysis stage uses claude-sonnet-4-6 for deeper reasoning, and the final report stage uses claude-opus-4-6 for polished writing.

When Not to Use Multi-Agent

It's worth noting that not every problem needs multiple agents. Anthropic's own guidance is clear: start with a single agent and add complexity only when a single context window can't hold the full task. Subagents add latency and token cost, so use them when you genuinely need parallel execution or specialized tool sets.

Production Considerations

Moving from prototype to production introduces a set of concerns that the SDK alone doesn't solve. Here are the patterns we've found most effective when deploying agent-based systems.

Cost Controls

Claude API tokens add up quickly in agentic workflows, where a single task might involve dozens of tool calls. The SDK provides built-in guardrails:

options = ClaudeAgentOptions(
    model="claude-sonnet-4-6",
    max_turns=50,             # Cap autonomous loop iterations
    max_budget_usd=1.00,      # Hard spend limit per run ($1)
)

For multi-tenant systems, track per-user token consumption and enforce budgets at the application layer.

State Persistence

Agents are stateless by default — each query() call starts fresh. For long-running workflows or conversational agents that need memory, use the ClaudeSDKClient class which supports session management, or persist state externally:

• Redis for session-level state (current task context, recent tool results)
• PostgreSQL for durable state (conversation history, task outcomes, audit logs)
• Object storage for artifacts (generated reports, exported files)

Error Handling and Retries

Agentic workflows are inherently non-deterministic. The same prompt might produce different tool-calling sequences on different runs. Design for resilience:

• Set max_turns to prevent infinite loops
• Set max_budget_usd to cap spending on runaway agents
• Log all tool calls and results for debugging
• Use permission_mode="dontAsk" for fully automated pipelines, or "default" when human oversight is needed

Security and Permissions

The SDK's permission system controls which tools the agent can use and what operations are allowed. For production deployments:

options = ClaudeAgentOptions(
    model="claude-sonnet-4-6",
    allowed_tools=["Read", "Grep", "WebSearch"],  # Whitelist specific tools
    disallowed_tools=["Bash"],                     # Explicitly deny dangerous tools
    permission_mode="dontAsk",                     # No interactive prompts in automation
)

This ensures agents can't execute arbitrary shell commands, modify system files, or access tools beyond their intended scope.

Conclusion

The Claude Agent SDK collapses the distance between "AI that answers questions" and "AI that gets things done." With query() for simple automation, MCP for external data access, and subagents for complex orchestration, you can build production-grade agent systems that handle real-world workflows end-to-end.

The most impactful agents aren't the most complex — they're the ones connected to the right data. An agent with access to structured, real-time product data through APIClaw's MCP server can automate competitive analysis, pricing optimization, and market research workflows that previously required hours of manual work.

See the full endpoint reference in our API documentation. Start with 1,000 free API credits — sign up here.