claude-agent-sdk-master

<h1 align="center"> <strong>Claude Agent SDK Master</strong> </h1> <p align="center"> <strong>🎓 A progressive learning tutorial to master Claude Agent SDK from scratch</strong> </p> <p align="center"> <a href="#-quick-start">Quick Start</a> • <a href="#-learning-path">Learning Path</a> • <a href="#-project-structure">Project Structure</a> • <a href="#-core-concepts">Core Concepts</a> • <a href="#-related-resources">Related Resources</a> </p> --- ## 💡 Project Positioning Claude Agent SDK Master is a **progressive learning tutorial series**, serving as a prelude and technical foundation for the [Proma](https://github.com/ErlichLiu/proma-oss.git) open-source project, aiming to: - 🎯 Help developers **systematically master** the core concepts and advanced features of Claude Agent SDK - 🔨 Understand Agent state management and user experience transformation through **practical, runnable projects** - 🌟 Provide high-quality Agent SDK **learning resources** for the open-source community - 🚀 Cultivate **AI-native application development thinking** and prepare for contributions to projects like Proma ### 🤔 Why is this tutorial needed? The potential of Agent SDK far exceeds its current development level. Even Claude's official Claude Code and Cowork might only touch **10%** of the SDK's capabilities. The application space for Agent SDK is vast, but compared to simply applying LLM APIs and other Agents that require orchestration, it requires you to: - Deeply understand **state management** and **streaming response** mechanisms - Redesign **user experience** and **interaction patterns** - Master more complex **nested states** and **tool calling** logic **The mission of this tutorial: to truly understand the design of Agent SDK and be able to elegantly apply these states.** --- ## Project Sponsor MiniMax This tutorial recommends using the MiniMax API for a smoother and more cost-effective way to complete the Claude Agent SDK learning process, fully compatible with all features (subscribing to the Coding Plan allows you to generate a Coding Plan api key to learn and apply to this tutorial).  MiniMax api access and registration address, you can also receive an 88% discount!：https://platform.minimaxi.com/subscribe/coding-plan?code=cVcgRF3hAQ&source=link --- ## 📖 Learning Path This series adopts a **progressive learning path**, with each chapter building on the previous one. It is recommended to study in order: | Chapter | Topic | Core Content | Status | |------|------|----------|------| | **Chapter 1** | 🚀 [Quick Start](./01-quick-start) | Workspace, Session, Context Management, Streaming Conversation | ✅ Completed | | **Chapter 2** | 🔧 [Tools and MCP](./02-tools-and-mcp) | MCP Tools Integration, Tool Calling, Actual Agent Capabilities | ✅ Completed | | **Chapter 3** | 🖼️ Multimodal Support | Image, File Upload Processing, Multimedia Rendering | 📋 Planned | | **Chapter 4** | 🎨 Advanced Features | Custom System Prompt, Cost Tracking, Streaming Optimization | 📋 Planned | > **💡 Tip**: This tutorial is continuously updated with the actual development progress of [Proma](https://github.com/ErlichLiu/proma-oss.git). --- ## ⚡ Quick Start ### Prerequisites - **Node.js** 18+ - **pnpm** package manager (recommended) - **Anthropic API Key (MiniMax API is recommended)** [Click to get minimax api key](https://platform.minimaxi.com/login) (or any other API that supports Anthropic /v1/messages) ### Start Learning in Three Steps ```bash # 1️⃣ Clone the repository git clone https://github.com/ErlichLiu/claude-agent-sdk-master.git cd claude-agent-sdk-master # 2️⃣ Enter the first chapter tutorial cd 01-quick-start # 3️⃣ Install dependencies pnpm install # 4️⃣ Configure API Key cp .env.local.example .env.local # Edit .env.local, fill in your ANTHROPIC_API_KEY and optional ANTHROPIC_BASE_URL # 5️⃣ Start the development server pnpm dev ``` Visit [http://localhost:3000](http://localhost:3000) to start your Agent SDK learning journey! 🎉 ### 🎮 Start with 00-Playground (Recommended) If you want to **quickly experience** the core features of Agent SDK, it is recommended to start with 00-Playground: ```bash # Enter the 00-playground directory cd 00-playground # Install dependencies pnpm install # Configure API Key cp .env.example .env.local # Edit .env.local, fill in your ANTHROPIC_API_KEY # Start interactive testing pnpm play ``` **Advantages of Playground:** - 📝 **Core code is streamlined**: `playground.ts` has only ~120 lines, focusing on SDK calls - ⚡ **Instant feedback**: Modify the code and run it immediately to see the effect - 🔧 **Interactive configuration**: Dynamically switch tools, output modes, etc. through commands - 🎯 **Zero UI interference**: Pure command line, focusing on understanding the SDK mechanism Suitable for developers who want to **quickly modify code and understand SDK behavior**. See [Playground README](./00-playground/README.md) for details. --- ## 📂 Project Structure ``` claude-agent-sdk-master/ │ ├── 00-playground/ # 🎮 SDK Interactive Testing Environment (Recommended for Beginners) │ ├── playground.ts # Core SDK Call Code │ ├── lib/ # Configuration and CLI Modules │ └── utils/ # Print Output Tools │ ├── 01-quick-start/ # 🚀 Chapter 1: Quick Start │ ├── app/ # Next.js App Router │ ├── components/ # UI Components (Three-Column Layout, Markdown, etc.) │ ├── lib/storage/ # JSONL File Storage Implementation │ ├── packages/core/ # Core Type Definitions (Monorepo) │ ├── README.md # Detailed Tutorial Documentation │ └── CLAUDE.md # Claude Code Development Guide │ ├── 02-tools-and-mcp/ # 🔧 Chapter 2: Tools and MCP (Under Development) │ └── ... │ ├── 03-multimodal/ # 🖼️ Chapter 3: Multimodal Support (Planned) │ └── ... │ ├── 04-advanced/ # 🎨 Chapter 4: Advanced Features (Planned) │ └── ... │ └── README.md # 📖 This File (Series Tutorial Overview) ``` --- ## 🎯 Core Concepts > **The essence of software, ultimately, is the elegant handling of state.** This is the core philosophy that runs through this tutorial series. Whether it is: - Claude Agent SDK's **Session State** - React's **Component State** - Proma's **Application State** Mastering the **essence of state** allows you to understand the essence of modern software development. ## ✨ Tutorial Features - 📚 **Complete System**: From basic to advanced, covering the complete capabilities of Agent SDK - 🔄 **Progressive Learning**: Each chapter builds on the previous one, step by step - 💻 **Practice-Oriented**: Each chapter is a **runnable complete project**, learning and practicing at the same time - 📖 **Detailed Documentation**: Each project is equipped with detailed README and CLAUDE.md development guides - 🤖 **AI Collaboration Practice**: Most of the content is written by Claude Code, demonstrating best practices for AI-assisted development - 🇨🇳 **Chinese Priority**: High-quality Chinese technical documentation to lower the learning threshold --- ## 🔗 Related Resources ### Official Documentation - [Claude Agent SDK Official Documentation](https://platform.claude.com/docs/en/agent-sdk/typescript) - TypeScript SDK Official Guide - [Anthropic API Documentation](https://docs.anthropic.com/) - Complete Claude API Documentation - [MiniMax API Documentation](https://platform.minimaxi.com/docs/guides/text-generation) - Complete MiniMax API Documentation ### Related Projects - [Proma](https://github.com/ErlichLiu/proma-oss.git) - Complete open-source product based on Agent SDK (coming soon) - [Claude Code](https://claude.ai/code) - Anthropic Official Code Editor - [MCP Servers](https://github.com/anthropics/mcp-servers) - Model Context Protocol Server Implementation - [Craft Agent OSS](https://github.com/lukilabs/craft-agents-oss) - This project design reference, recommended for learning ### Technology Stack - [Next.js Documentation](https://nextjs.org/docs) - Complete App Router Guide - [Shadcn UI](https://ui.shadcn.com) - UI Component Library - [Tailwind CSS](https://tailwindcss.com/docs) - Atomic CSS Framework --- ## 🤝 Contribution Welcome to submit Issues and Pull Requests! If this project is helpful to you: - ⭐ **Star this project** - Let more people see this tutorial - 🐛 **Report Bug** - Please submit an Issue if you find a problem - 📖 **Improve Documentation** - Welcome PR if you find errors or have suggestions for improvement - 💡 **Share Experience** - Share your learning experience in Discussion - 🚀 **Contribute to Proma** - Welcome to contribute to the [Proma](https://github.com/your-proma-link) project after learning this tutorial ### How to Contribute 1. Fork this repository 2. Create your feature branch (`git checkout -b feature/AmazingFeature`) 3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) 4. Push to the branch (`git push origin feature/AmazingFeature`) 5. Open a Pull Request --- ## ❓ Common Questions <details> <summary><strong>Q: What basic knowledge do I need?</strong></summary> - **Required**: JavaScript/TypeScript basics, React basics - **Recommended**: Next.js understanding, asynchronous programming experience - **Bonus**: Experience using LLM API </details> <details> <summary><strong>Q: What is the difference between Agent SDK and directly calling Claude API?</strong></summary> Agent SDK provides a higher level of abstraction: - **Automatic Context Management**: No need to manually stitch messages - **File System Integration**: Agent can read and write local files - **Tool Calling Encapsulation**: Built-in Tool Calling and MCP support - **Session Persistence**: Automatically store conversation history Suitable for building **persistent, stateful AI applications**, rather than simple question and answer. </details> <details> <summary><strong>Q: Why choose Next.js?</strong></summary> - **App Router**: Native support for Server Actions and streaming responses - **Full-Stack Capabilities**: API Routes facilitate building backend logic - **Development Experience**: Hot reloading, TypeScript support, modern toolchain - **Rich Ecosystem**: Seamless integration with Shadcn UI, Tailwind CSS, etc. Of course, you can also integrate Agent SDK into any Node.js framework and Python framework, and it does not mean that NextJS is used in formal production projects. </details> <details> <summary><strong>Q: Will this tutorial be continuously updated?</strong></summary> Yes! This tutorial is continuously updated with the development progress of the **Proma project**: - ✅ Chapter 1 completed - 🚧 Chapter 2 under development (tool calling) - 📋 Chapters 3 and 4 planned Follow this repository to get the latest update notifications. </details> --- ## 📄 License MIT License - Free to use, welcome to improve and share --- ## Star History [](https://www.star-history.com/#ErlichLiu/claude-agent-sdk-master.git&type=date&legend=top-left) <p align="center"> <strong>🎓 Start Learning:</strong> <a href="./01-quick-start">Chapter 1: Quick Start</a> </p> <p align="center"> <i>This tutorial was created with the assistance of Claude Code ✨</i><br> <i>Continuously updated with Proma development progress</i><br> <i>If it helps you, welcome to Star ⭐️</i> </p>