Claude Agent SDK Template

A starter template for building AI agents with the Anthropic Claude Agent SDK.

Features

• Express REST API server with TypeScript
• Session management with persistence
• Cost tracking and instrumentation
• Ready for MCP (Model Context Protocol) integration
• Hot reload development mode
• Comprehensive SDK documentation included

Project Structure

├── server/
│   ├── sdk-server.ts           # Express REST API (main entry point)
│   └── lib/
│       ├── ai-client.ts        # Claude SDK wrapper
│       ├── session-manager.ts  # Session lifecycle & persistence
│       ├── instrumentor.ts     # Cost/metrics tracking
│       └── orchestrator-prompt.ts  # System prompt (customize this!)
├── agent/.claude/              # Claude SDK configuration
├── claude_sdk/                 # SDK documentation & guides
│   ├── overview.md             # SDK overview
│   ├── typescript_sdk.md       # TypeScript SDK reference
│   ├── session_management.md   # Session handling guide
│   ├── custom_tools.md         # Creating custom tools
│   ├── mcp.md                  # MCP integration guide
│   ├── subagents.md            # Working with subagents
│   ├── system_prompts.md       # System prompt best practices
│   └── ...                     # More guides
├── .env.example                # Environment variables template
├── package.json
└── tsconfig.json

Quick Start

1. Clone or Fork

git clone https://github.com/anthropics/claude-agent-sdk-template.git
cd claude-agent-sdk-template

2. Install Dependencies

npm install

3. Configure Environment

cp .env.example .env

Edit .env and add your API keys:

• ANTHROPIC_API_KEY - Required. Get from Anthropic Console
• FAL_KEY - Optional. For image/video generation via fal.ai

4. Run the Server

Development mode (with hot reload):

npm run dev

Production mode:

npm start

Server runs on http://localhost:3002 by default.

API Endpoints

Endpoint	Method	Description
/generate	POST	Send a prompt to the agent
/sessions	GET	List all active sessions
/sessions/:id	GET	Get session statistics
/sessions/:id/continue	POST	Continue an existing session
/health	GET	Health check

Example Request

curl -X POST http://localhost:3002/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello, what can you help me with?"}'

Example Response

{
  "response": "I'm a helpful AI Agent...",
  "sessionId": "abc123",
  "stats": {
    "messageCount": 2,
    "turnCount": 1
  },
  "instrumentation": {
    "totalCost": 0.0012,
    "inputTokens": 150,
    "outputTokens": 200
  }
}

Customization

1. Define Your Agent's Role

Edit server/lib/orchestrator-prompt.ts to customize your agent's system prompt:

export const ORCHESTRATOR_SYSTEM_PROMPT = `You are a [YOUR AGENT TYPE].

Your job is to help users with [SPECIFIC TASKS].

## Available Tools
- [List capabilities]

## Workflow
1. [Step 1]
2. [Step 2]
...
`;

2. Configure Tools

Edit server/lib/ai-client.ts to modify allowed tools:

allowedTools: ['Read', 'Write', 'Glob', 'Bash', 'Task', 'Skill']

3. Add MCP Servers

Create or edit agent/.claude/settings.json:

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "npx",
      "args": ["-y", "@your-org/mcp-server"]
    }
  }
}

4. Add Custom Endpoints

Extend server/sdk-server.ts with additional routes as needed.

Architecture

Client Request
    ↓
Express Server (/generate)
    ↓
SessionManager (create/retrieve session)
    ↓
AIClient.queryWithSession()
    ├→ SDK Query with system prompt
    ├→ Streams messages via async generator
    └→ SessionManager persists messages
    ↓
SDKInstrumentor (tracks costs/metrics)
    ↓
JSON Response (text + stats + costs)

Environment Variables

Variable	Required	Description
ANTHROPIC_API_KEY	Yes	Your Anthropic API key
PORT	No	Server port (default: 3002)
NODE_ENV	No	Environment (development/production)
CLAUDE_CODE_MAX_OUTPUT_TOKENS	No	Max output tokens (default: 16384)
FAL_KEY	No	fal.ai API key for image/video

Documentation

The claude_sdk/ folder contains comprehensive documentation for the Claude Agent SDK:

Document	Description
overview.md	SDK overview and core concepts
typescript_sdk.md	TypeScript SDK reference
session_management.md	Managing agent sessions
custom_tools.md	Creating custom tools
mcp.md	MCP (Model Context Protocol) integration
subagents.md	Working with subagents
system_prompts.md	System prompt best practices
Agent_skills.md	Building agent skills
permissions.md	Permission handling
tracking_costs.md	Cost tracking and monitoring
streaming_input.md	Streaming input handling

License

MIT