Production-ready template for building sophisticated AI agents with the Claude Code SDK. From research assistants to complex multi-agent systems, this boilerplate provides everything you need to go from prototype to production.
# 1. Copy this boilerplate
cp -r agent_boilerplate my_agent && cd my_agent
# 2. Install dependencies
uv sync
# 3. Set up your API key
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY
# 4. Run your agent
python agent.py- ✅ Multi-turn conversations with context management
- ✅ Tool integration (WebSearch, Read, Write, Bash, custom tools)
- ✅ Custom Python scripts via Bash tool
- ✅ MCP server support for external integrations (GitHub, databases, etc.)
- ✅ Async/sync support for different deployment contexts
- ✅ Subagents - Delegate to specialized expert agents
- ✅ Output styles - Different communication templates for different audiences
- ✅ Slash commands - Reusable prompt templates
- ✅ Hooks - Automated compliance and audit trails
- ✅ Memory - Persistent context via CLAUDE.md
- ✅ Multiple deployment options (CLI, Web UI, REST API, Docker)
- ✅ Comprehensive tests (unit + integration)
- ✅ Security best practices
- ✅ Monitoring and logging
agent_boilerplate/
├── agent.py # Main agent module
├── CLAUDE.md # Agent memory/context
├── GUIDE.md # Complete step-by-step guide
│
├── .claude/ # Advanced configuration
│ ├── agents/ # Subagent definitions
│ ├── commands/ # Slash commands
│ ├── output-styles/ # Communication templates
│ ├── hooks/ # Automation scripts
│ └── settings.local.json # Hook configuration
│
├── scripts/ # Custom Python tools
├── data/ # Agent data files
├── tests/ # Test suite
│
└── deployment/ # Deployment options
├── cli/ # Command-line interface
├── streamlit/ # Web UI (MVP)
├── fastapi/ # REST API (Production)
└── docker/ # Containerization
from agent import send_query_simple
# Simple query
result = await send_query_simple("What is AI?")
print(result)
# Multi-turn conversation
result1 = await send_query_simple("What is the capital of France?")
result2 = await send_query_simple(
"What's the population?",
continue_conversation=True
)from agent import send_query
# With custom configuration
result, messages = await send_query(
prompt="Analyze the data in data/example.json",
output_style="concise",
allowed_tools=["Read", "Bash"],
permission_mode="default"
)# GitHub integration
github_mcp = {
"github": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"],
"env": {"GITHUB_PERSONAL_ACCESS_TOKEN": os.environ.get("GITHUB_TOKEN")}
}
}
result, _ = await send_query(
"Check issues in anthropics/claude-code-sdk-python",
mcp_servers=github_mcp,
allowed_tools=["mcp__github"]
)# Interactive mode
python deployment/cli/cli.py -i
# Single query
python deployment/cli/cli.py "Hello, agent!"# Install and run
uv add streamlit
streamlit run deployment/streamlit/app.py
# Deploy to cloud
# → Push to GitHub
# → Deploy on share.streamlit.io# Install and run
uv add fastapi uvicorn
uvicorn deployment.fastapi.api:app
# Test API
curl -X POST http://localhost:8000/query \
-H "Content-Type: application/json" \
-d '{"prompt": "Hello!"}'
# Deploy to cloud
railway up # or: fly deploy# Run with Docker Compose
docker-compose up agent-api
# Deploy to cloud
# AWS ECS, Google Cloud Run, Azure Container Instances
# See deployment/docker/README.md for details# Install test dependencies
uv add pytest pytest-asyncio
# Run all tests
pytest tests/ -v
# Run specific test
pytest tests/test_agent.py::test_basic -vEdit CLAUDE.md with your domain knowledge and guidelines.
Create scripts in scripts/ directory:
# scripts/my_tool.py
import sys
import json
def process(data):
# Your logic here
return {"result": data}
if __name__ == "__main__":
result = process(sys.argv[1])
print(json.dumps(result))Add markdown files to .claude/agents/:
---
name: expert-analyst
description: Expert in data analysis
tools: Bash, Read
---
You are a data analysis expert...Create templates in .claude/output-styles/:
---
name: executive
description: Brief, KPI-focused communication
---
## Principles
- Lead with key insight
- Use bullet points
- Include metricsAdd automation in .claude/hooks/ and configure in settings.local.json.
- GUIDE.md - Complete step-by-step guide (READ THIS FIRST!)
- deployment/cli/README.md - CLI deployment guide
- deployment/streamlit/README.md - Streamlit deployment guide
- deployment/fastapi/README.md - FastAPI deployment guide
- deployment/docker/README.md - Docker deployment guide
# Required
ANTHROPIC_API_KEY=your_key_here
# Optional (for specific features)
GITHUB_TOKEN=your_github_tokenClaudeCodeOptions(
model="claude-sonnet-4-20250514", # Model selection
max_turns=50, # Conversation limit
allowed_tools=["Read", "Bash"], # Tool permissions
permission_mode="default", # default, plan, acceptEdits
system_prompt="...", # Custom system prompt
mcp_servers={...}, # MCP integrations
)This boilerplate implements patterns from the Claude Code SDK tutorial series:
- Research Agent - Web search + multimodal analysis
- Chief of Staff - Multi-agent orchestration + governance
- Observability Agent - External system integration via MCP
- ✅ Security: Environment variables, API auth, input validation
- ✅ Monitoring: Logging, metrics, error tracking
- ✅ Cost management: Token limits, model selection, caching
- ✅ Scaling: Async processing, concurrent queries, load balancing
- ✅ Testing: Unit tests, integration tests, E2E tests
See GUIDE.md section 8 for detailed best practices.
- Customer Support - Handle inquiries, troubleshoot issues, access knowledge base
- Data Analysis - Process datasets, generate insights, create visualizations
- DevOps - Monitor systems, analyze logs, automate workflows
- Research - Gather information, synthesize findings, generate reports
- Content Creation - Write, edit, format content for different audiences
This is a boilerplate template - customize it for your needs! Some ideas:
- Add more deployment options (AWS Lambda, Google Cloud Functions)
- Create industry-specific templates (healthcare, finance, legal)
- Add more example scripts and tools
- Improve test coverage
- Add monitoring dashboards
This boilerplate is part of the Anthropic Cookbook and follows the same license.
- Issues: Report bugs or request features
- Discussions: Ask questions, share ideas
- Documentation: Check GUIDE.md for detailed help
Built with ❤️ using the Claude Code SDK
Ready to build your agent? Start with GUIDE.md →