# Building Agents with the Claude Agent SDK
Last year, we shared our experience with clients on [building effective agents](https://www.anthropic.com/engineering/building-effective-agents). Since then, we released [Claude Code](https://www.anthropic.com/claude-code) — an **agent-based coding solution** designed to boost internal development efficiency at Anthropic.
Over recent months, Claude Code has evolved far beyond coding. At Anthropic, we now [use it](https://www.anthropic.com/news/how-anthropic-teams-use-claude-code) for:
- Deep research
- Video creation
- Note-taking
- Data analysis
- And many other non-coding applications
It powers nearly all of our internal agent loops.
To reflect this broader scope, we are renaming **Claude Code SDK** to **Claude Agent SDK** — a framework equally capable of powering diverse agent types.
---
## Why We Built the Claude Agent SDK
We’ll cover:
1. **Core design principles** guiding the SDK
2. How to build custom agents
3. Best practices from real-world deployments
---
## Design Principles
The [key design principle](https://www.youtube.com/watch?v=vLIDHi-1PVU) is that Claude should have **access to real tools programmers use daily** — enabling:
- File search
- File creation and editing
- Code linting (**linting checks for style issues or potential bugs**)
- Code execution and debugging
- Iterative testing until success
With terminal access, Claude can operate like a human programmer.
**Key insight:**
Granting Claude these tools makes it effective at *non*-coding tasks too. It can:
- Run bash commands
- Handle and search files
- Read CSVs
- Build visualizations
- Interpret metrics
- Automate digital workflows
**Core principle:** *Give your agent a computer, and let it work like a person.*
---
## Creating New Agent Types
With Claude Agent SDK, you can build:
- **Financial Agents**
Evaluate investments via APIs, data storage, and computational logic.
- **Personal Assistant Agents**
Manage calendars, book trips, prepare briefings, and integrate enterprise data.
- **Customer Support Agents**
Handle ambiguous support tickets, check APIs, reply to users, and escalate.
- **Deep Research Agents**
Search large document sets, cross-check information, and compile reports.
**Foundation:** The SDK provides basic components (called **"primitives"**) to automate any workflow.
---
### Future Ecosystem Potential
As AI agent ecosystems mature, SDKs like Claude Agent SDK may integrate with **publishing & monetization platforms** such as [AiToEarn官网](https://aitoearn.ai/) — enabling:
- AI-powered multi-platform content generation
- Cross-network publishing (Douyin, Kwai, WeChat, Bilibili, Rednote, Facebook, Instagram, LinkedIn, Threads, YouTube, Pinterest, X/Twitter)
- Analytics and AI model ranking ([AI模型排名](https://rank.aitoearn.ai))
Such integrations let agents autonomously create, publish, and monetize high-impact content.
---
## Building the Agent Loop
In **Claude Code**, the workflow is:
**Gather context → Take action → Verify work → Repeat**
This loop applies to many agent types. Let’s illustrate with **an email agent example**.
---
### 1️⃣ Gathering Context
Agents need to **fetch and update their own context** — not just rely on prompt inputs.
- **File system as context:**
Information stored on disk can be pulled into the model's context.
- **Managing large files:**
Claude may use bash (`grep`, `tail`) to selectively load file parts.
- **Context engineering:**
Organizing data (e.g., all past conversations inside `"Conversations"` folder) improves relevance.
**Tip:**
Agentic search is more transparent than [semantic search](https://www.anthropic.com/news/contextual-retrieval), though semantic search may offer speed at the cost of accuracy.
---
### 2️⃣ Subagents
[**Subagents**](https://docs.claude.com/en/api/agent-sdk/subagents) enable:
1. **Parallel work** — multiple tasks at once
2. **Context isolation** — each has its own window, returning only relevant info
Email agent example:
Launch multiple search subagents in parallel, each scanning emails for different query types.
---
### 3️⃣ Compaction
Long-running agents risk hitting context size limits.
**Compaction** (via `/compact` command) automatically summarizes old messages.
---
## Taking Action
Once context is set, agents need **tools** and methods to act.
### Tools
[**Tools**](https://www.anthropic.com/engineering/writing-tools-for-agents) are command-like capabilities, prominently surfaced in Claude’s context selection.
**Best practice:** Make primary actions explicit tools. For an email agent:
- `fetchInbox`
- `searchEmails`
Learn to create [custom tools](https://docs.claude.com/en/api/agent-sdk/custom-tools).
---
### Bash and Scripting
Bash is a **general-purpose execution environment**.
Example:
Email agent extracts info from PDF attachments by:
1. Downloading PDF
2. Converting to text
3. Searching for keywords
---
### Code Generation
Code enables **precise**, **reusable**, and **complex** actions.
Example:
[File creation feature](https://www.anthropic.com/news/create-files) uses Python scripts to build Excel, PPT, and Word files.
Email agent use case:
Create custom rules for incoming emails by writing executable code.
---
### MCP Integrations
The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) standardizes service integrations.
Advantages:
- Built-in authentication
- Prebuilt integrations (Slack, GitHub, Google Drive, Asana, etc.)
- Focus on agent logic, not OAuth
Example:
Email agent can query Slack messages or check assigned Asana tasks via MCP.
See [MCP server list](https://github.com/modelcontextprotocol/servers).
---
## Validating Work
Smart agents **verify and refine outputs**.
### Rules-based feedback
Example: TypeScript linting → deeper static analysis.
### Email agent checks
- Verify email address validity (error if invalid)
- Warn if user contacted address before
### Visual feedback
For UI/email agents: screenshots or renderings validate layout, style, hierarchy, and responsiveness.
Use MCP with Playwright to:
- Capture screenshots of HTML output
- Test multiple viewport sizes
- Validate interactive elements
---
## LLM as a Judge
A secondary LLM can review outputs against **fuzzy, qualitative rules** (e.g., tone consistency).
Trade-off: extra latency + variable reliability.
---
## Testing & Improving Agents
**Checklist:**
- Missing context? Improve search API/data organization.
- Frequent failure? Add detection rules in tools.
- Can't self-correct? Provide better or alternative tools.
- Performance drops after updates? Use representative test sets for evaluation.
---
## Getting Started
Claude Agent SDK gives Claude **computer-like capabilities**:
- Write files
- Execute commands
- Iterate results
**Agent loop:** Gather context → Take action → Verify work.
Start here: [SDK Overview](https://docs.claude.com/en/api/agent-sdk/overview)
Migration guide: [Upgrade Path](https://docs.claude.com/en/docs/claude-code/sdk/migration-guide)
---
### Scaling & Monetization
For teams monetizing AI creativity, [AiToEarn官网](https://aitoearn.ai/) offers:
- Open-source content monetization
- Multi-platform publishing
- Analytics & model ranking
Channels include Douyin, Kwai, WeChat, Bilibili, Rednote, Facebook, Instagram, LinkedIn, Threads, YouTube, Pinterest, X/Twitter.
---
## Acknowledgments
Editing by: Molly Vorwerck, Suzanne Wang, Alex Isken, Cat Wu, Keir Bradwell, Alexander Bricken, Ashwin Bhat.
---
**Original link:** [Building Agents with the Claude Agent SDK](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk)
