How to Create Agents with Claude Agents SDK

Agents are the glue between AI models and real-world utility: they accept natural-language goals, plan, call tools, manage context, and return reliable results. Anthropic’s Claude Agent SDK (formerly the Claude Code SDK) inherits the same agent that powers Claude Code, so you can now build production-ready agents that safely interact with files, run code, call external APIs, and keep long-lived context. This guide will educate you about the Claude Agent SDK and teach you how to build your own, using a real-world example.

What the Claude Agent SDK gives you

Agent: context management, permission model, session & error management, and tooling that powers Claude Code.
Multi-language SDKs: official TypeScript/Node and Python SDKs, streaming vs single-call modes, examples and demos on GitHub.
Tool/model integration: built-in tools (file ops, Bash, web search), plus the Model Context Protocol (MCP) to attach custom external tools.

Before you start — prerequisites

Here’s what you’d need:

Claude API key: get one from the Claude Console and set ANTHROPIC_API_KEY in your environment.
Runtime & installs:
- Python: pip install claude-agent-sdk (requires Python 3.10+ and Node.js for some features).
- TypeScript/Node: npm install @anthropic-ai/claude-agent-sdk.
(Optional) @anthropic-ai/claude-code CLI if you want local Claude Code integration and the file-based features (subagents, CLAUDE.md, slash commands).

Claude Agent SDK core concepts you need to know

Anthropic

System prompts & settings: define agent role/behavior via system prompts and project-level settings (e.g., CLAUDE.md, .claude files).
Tools: built-in or custom MCP tools that the agent can invoke. Tools are granted via allowedTools / disallowedTools and permissionMode.
MCP (Model Context Protocol): a mechanism to register custom tool servers (external processes or in-process SDK MCP servers) so Claude can call your APIs or functions.
Hooks: deterministic callbacks executed during agent cycles (e.g., pre-tool-use checks) to enforce safety or add logging.
Context memory: the SDK provides context compaction, session forking, and memory features to handle long-running tasks without hitting token limits. (Important for multi-step / long-living agents.)

Claude Agent SDK minimal working example — Python (async streaming)

Below is a tiny, realistic example that uses the Python SDK’s query() helper to ask an agent to greet someone. This uses the streaming interface so you can process intermediate messages.

# quick_start.py
import anyio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock
async def main():
    options = ClaudeAgentOptions(system_prompt=”You are a friendly assistant”, max_turns=1)
    async for message in query(prompt=”Greet Alice”, options=options):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)
if __name__ == “__main__”:
    anyio.run(main)

Notes:

query() returns an async iterator of message objects; handle AssistantMessage, ToolUseBlock, etc. See the Python README for types and examples.

Minimal example — TypeScript / Node

The TypeScript SDK follows similar patterns (install with npm install @anthropic-ai/claude-agent-sdk). A tiny pseudo-example:

import { ClaudeAgentClient, ClaudeAgentOptions } from “@anthropic-ai/claude-agent-sdk”;
async function main() {
  const options: ClaudeAgentOptions = { system_prompt: “You are a helpful assistant” };
  const client = new ClaudeAgentClient(options);
  await client.connect();
  await client.query(“Greet Alice”);
  for await (const msg of client.receiveResponse()) {
    console.log(msg);
  }
  await client.close();
}
main();

(Refer to the SDK docs for exact naming and streaming semantics for TypeScript — they mirror the Python behavior and provide streaming vs. single-call modes.)

Building a production agent — recommended architecture

Design tools first: think in terms of the actions your agent needs (e.g., fetchInbox, createTicket, run_test). Make those tools small, typed, and testable.
Least privilege: only allow the tools the agent needs and set an appropriate permissionMode. Use hooks for safeguards on high-risk tools.
Session & memory strategy: decide what stays in short-term session context vs. longer-term memory (CLAUDE.md or a separate memory tool). Use explicit compaction and summarize or checkpoint memory to avoid context blowups.
Testing harness: run the agent locally with canned prompts, simulate tool failures, and collect logs. The SDK has streaming examples and interactive examples (IPython) to accelerate development.
Monitoring & observability: instrument tool use, errors, and Hook decisions so you can detect drift, unsafe behavior, and performance regressions.

Example: Building a Calculator with Claude Agent SDK

Calculator agent built via Claude Agent SDK

1. Set up your environment

Make sure you have Python 3.9+ installed.
Install the Claude Agent SDK:
pip install claude-agent-sdk
Get your Claude API key from Anthropic and set it in your environment: ANTHROPIC_API_KEY="your_api_key_here"

2. Define the agent’s role

Decide what it should do: perform arithmetic and simple math tasks.
Write a system prompt that guides its behavior, e.g.: You are a smart calculator. You can solve arithmetic problems, handle parentheses, powers, and fractions. Do not answer non-math questions.

3. Create the agent script

Here’s a basic Python file smart_calculator.py:

from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio

async def smart_calculator(user_query: str):
    # Define system instructions
    system_prompt = """
    You are a smart calculator. 
    Solve math problems step by step if needed.
    Handle arithmetic (+, -, *, /), exponents, parentheses, and fractions.
    Respond only with the final answer (and steps if useful).
    """

    # Configure the agent
    options = ClaudeAgentOptions(
        system_prompt=system_prompt,
        allowed_tools=[]  # restrict to pure reasoning
    )

    # Run the agent on the query
    async for message in query(prompt=user_query, options=options):
        print(message.text)

# Test run
if __name__ == "__main__":
    asyncio.run(smart_calculator("What is 98*56-2?")

4. Run and test

Run your file:

python smart_calculator.py

5. Prompt Claude to create the UI and finish

Explain how you’d like your calculator and its UI. Then prompt Claude CLI/SDK to code it. You’ll have a working application.

Safety, security, and governance (short checklist)

Use least privilege for tools.
Put dangerous operations behind hooks and approvals (e.g., destructive Bash commands or sending emails).
Log tool usage, Hook decisions, and errors for auditability.
Treat any code-generation or file-editing outputs as needing validation; consider a human-in-the-loop approval step for high-risk actions.

Troubleshooting quick hits

CLI not found / CLINotFoundError: ensure @anthropic-ai/claude-code or required Claude Code CLI is installed if the SDK expects a local Claude Code instance.
Tool invocation errors: check your MCP server config (stdio vs sdk server) and the tool name namespace — SDK in-process tools use names like mcp__<server>__<tool>.
Context limits/token overflow: enable context compaction and try summarizing older turns to reduce context size.

Examples & learning resources

Official Agent SDK docs (overview, TypeScript, Python) — main reference for APIs and concepts. (https://docs.claude.com/en/api/agent-sdk/overview)
anthropics/claude-agent-sdk-python GitHub repo — installs, quick-start examples, tools, and in-process MCP server examples.
Anthropic engineering blog post: “Building agents with the Claude Agent SDK” — rationale and best practices (good for architecture thinking). (https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk)
Claude Code SDK demos — practical, runnable demos (email agent, code agents) to learn patterns and wiring.

The Bottom Line

When creating agents with the Claude Agent SDK, the smoothest path begins with quick prototyping in-process using SDK MCP tools, followed by moving critical services to external MCP servers once stronger safeguards are needed. Keep tools small and well-typed with clear input and output schemas so agents can combine them without friction. Most importantly, think of the agent as an orchestrator rather than an independent actor, and ensure sensitive actions always stay behind approvals and hooks. You got it!

And if you’re looking to use agents for creating full-stack applications and backend, Bind AI IDE provides an Agent Mode that lets you readily start building, using both Claude and GPT models. Start here!