Claude Agent 模板

这是一个使用Vercel AI SDK，Claude Agent SDK以及自定义MCP工具构建AI代理的Next.js模板。

概述

此模板提供了一个完整的基于Claude Haiku 4.5构建AI代理的基础。它展示了如何创建自定义工具、集成外部服务以及构建具有实时流传输功能的交互式聊天界面。

基于：

• Vercel AI SDK Reasoning Starter - 基础的Next.js + AI SDK设置
• Claude Agent SDK - 多轮代理工作流程和MCP工具

特性

• 多轮代理工作流程 - 基于Claude Agent SDK进行复杂任务执行
• 自定义MCP工具 - 易于扩展且类型安全的工具系统
• 实时流传输 - 使用服务器发送事件以实现响应式的用户体验
• 现代堆栈 - Next.js 15, React 19, Tailwind CSS, TypeScript
• 内置工具 - 文件操作、Bash命令、网络搜索等

快速开始

先决条件

• Node.js 18+
• pnpm（或npm/yarn）
• 以下任一认证方式之一：
  • Anthropic API Key（获取一个），或者
  • Claude Code CLI（安装指南）

设置

1. 克隆并安装依赖

   git clone <your-repo-url>
   cd claude-agent-template
   pnpm install
   

2. 认证设置（选择一种）

   选项A：使用API Key（推荐用于生产环境）

   复制.env.example到.env并添加您的API密钥：

   cp .env.example .env
   # 编辑.env文件并添加：ANTHROPIC_API_KEY=your_api_key_here
   

   选项B：使用Claude Code CLI

   如果您已安装并认证了Claude Code CLI：

   claude auth login
   # 不需要.env文件 - SDK将使用CLI认证
   

3. 运行开发服务器

   pnpm dev
   

   在浏览器中打开http://localhost:3000。

架构

系统概述

代理系统由三个核心组件构成：

1. 代理API (app/api/agent/route.ts) - 处理请求、管理对话状态并流式传输响应
2. MCP工具 (lib/mcp-tools/) - 扩展代理能力的自定义工具
3. 聊天UI (components/agent-chat.tsx) - 具有实时流传输功能的交互界面

消息流

用户输入
  ↓
POST /api/agent → query({ prompt, options })
  ↓
代理在多个回合中执行工具
  ↓
服务器发送事件流至客户端
  ↓
UI显示工具使用情况及结果

代理配置

• 模型：Claude Haiku 4.5 (claude-haiku-4-5)
• 内置工具：读取、写入、Bash、Grep、Glob、WebSearch
• 自定义工具：通过MCP（模型上下文协议）定义
• 最大回合数：每次对话10个回合
• 流传输：是（服务器发送事件）

开发工作流

此模板旨在与Claude Code无缝协作，利用自定义斜杠命令和专门的子代理来简化您的开发过程。

Git 工作树管理

包含的wt脚本简化了为特性分支创建隔离的工作树，允许您同时处理多个特性而不需切换上下文：

./wt feature/new-feature              # 为新分支创建工作树
./wt feature/existing-branch          # 为现有分支创建工作树

该脚本自动：

• 在../feature/new-feature创建新的git工作树
• 将.env文件复制到新工作树
• 使用pnpm install安装依赖

示例工作流：

# 在主分支上工作
./wt feature/add-auth               # 为认证特性创建工作树
cd ../feature/add-auth              # 切换到新工作树
pnpm dev                            # 启动此分支的开发服务器

使用子代理管理GitHub问题

此模板包括一个自定义斜杠命令(/solve-github-issue)，展示了Claude Code强大的子代理架构：

子代理：

1. github-issue-planner - 分析GitHub问题并创建全面的实施计划
2. github-issue-manager - 管理问题生命周期（更新、测试结果、关闭）

与Claude Code一起使用：

/solve-github-issue 42              # 分析并规划问题#42的实施

自动化工作流：

1. 规划者子代理分析问题及相关上下文
2. 创建详细的实施计划，包括文件位置和步骤
3. 您审查并实施解决方案
4. 管理者子代理自动更新问题的测试结果并关闭它

此工作流展示了如何使用Claude Code的自定义斜杠命令和专门的子代理构建智能开发自动化。

查看.claude/commands/solve-github-issue.md和.claude/agents/以了解实现细节。

文档

• TOOLS.md - 创建自定义MCP工具的完整指南
• TROUBLESHOOTING.md - 常见问题及其解决方案
• CLAUDE.md - 开发环境设置和工作流（包括项目结构）

资源

• Vercel AI SDK
• Claude Agent SDK
• 模型上下文协议
• Next.js 文档

贡献

贡献指南：

• 保持工具专注且简单
• 清晰地记录参数
• 处理所有错误案例
• 编写描述性的系统提示
• 使用各种输入进行测试

许可证

MIT