Fullstack Langgraph Nextjs Agent

LangGraph.js人工智能代理模板

一个用于使用LangGraph.js构建AI代理的生产就绪Next.js模板，具有模型上下文协议（MCP）集成、人在循环工具批准和持久内存功能。

Demo

_完整的代理工作流程：用户输入→ 工具批准→ 执行→ 流式响应_

    

______________________________________________________________________

需要帮助将其投入生产吗？

我帮助团队设计和优化基于LangGraph的AI代理（RAG、内存、延迟、架构）。

如果你正在这个模板上构建一些严肃的东西，并希望得到实践帮助：

→ 在LinkedIn上给我发私信

很高兴接到一个简短的电话。

______________________________________________________________________

特性

使用MCP进行动态刀具加载

• 模型上下文协议 动态刀具管理集成
• 通过web UI添加工具-无需更改代码
• 支持stdio和HTTP MCP服务器
• 工具名称前缀以防止冲突

人在循环工具批准

• 执行前交互式工具调用审批
• 具有批准/拒绝/修改选项的精细控制
• 适用于受信任环境的可选自动批准模式
• 带有工具执行暂停的实时流媒体

Tool approval dialog with detailed parameter inspection

持久对话记忆

• PostgreSQL后端的LangGraph检查指针
• 完整的对话历史记录保存
• 基于线程的组织
• 跨会话无缝恢复

多模式文件上传

Tool approval dialog with detailed parameter inspection

• 上传带有消息的图像、PDF和文本文件
• S3兼容存储（MinIO用于开发）
• 用于AI消费的自动文件处理
• 支持AWS S3和Cloudflare R2的生产就绪

实时流媒体接口

• 实时响应的服务器发送事件（SSE）
• 使用React Query进行乐观的UI更新
• 类型安全消息处理
• 错误恢复和优雅降级

持久模型设置

• 提供商和型号选择已保存到 localStorage 自动地
• 设置在页面重新加载和线程导航后仍然有效
• 无需后端——启动时零延迟读取

Langfuse的LLM可观察性

• 对代理运行、LLM调用、工具调用和令牌使用的端到端跟踪
• 适用于 朗富士云 或自托管实例
• 通过以下方式切换 LANGFUSE_ENABLED env var——禁用时开销为零
• 看 docs/OBSERVABILITY.md 有关设置说明

现代技术栈

• 前端：Next.js 15、React 19、TypeScript、顺风CSS
• 后端：Node.js、Prisma ORM、PostgreSQL、MinIO/S3
• 人工智能：LangGraph.js、OpenAI/谷歌/人类模型
• 用户界面：shadcn/ui组件，Lucide图标

快速开始

先决条件

• Node.js 18+和pnpm
• Docker（用于PostgreSQL和MinIO）
• OpenAI API密钥、Google AI API密钥或Anthropic API密钥

1.克隆和安装

git clone https://github.com/IBJunior/fullstack-langgraph-nextjs-agent.git
cd fullstack-langgraph-nextjs-agent
pnpm install

2.环境设置

cp .env.example .env.local

编辑 .env.local 根据您的配置：

# Database
DATABASE_URL="postgresql://user:password@localhost:5434/agent_db"

# AI Models (choose one or more)
OPENAI_API_KEY="sk-..."
GOOGLE_API_KEY="..."
ANTHROPIC_API_KEY="sk-ant-..."

# Optional: Default model
DEFAULT_MODEL="gpt-4o-mini"  # or "gemini-1.5-flash" or "claude-sonnet-4-5"

3.启动服务

docker compose up -d  # Starts PostgreSQL and MinIO

4.数据库设置

pnpm prisma:generate
pnpm prisma:migrate

5.运行开发服务器

pnpm dev
# Or use custom port
pnpm dev --port=3005

访问 http://localhost:3000 开始与您的AI代理聊天！

截图

Main Chat Interface

Clean, responsive design with streaming responses

MCP Server Management

Easy setup and configuration of tool servers

Thread Management

Organize conversations with persistent history

Agent Configurations

Multiple model Providers Support

使用指南

添加MCP服务器

1. 导航到“设置” -点击侧边栏中的齿轮图标
2. 添加MCP服务器 -点击“添加MCP服务器”按钮
3. 配置服务器:

- 名字：唯一标识符（例如“文件系统”） - 类型：选择 stdio 或 http - 命令：对于stdio服务器（例如。， npx @modelcontextprotocol/server-filesystem) - 参数：命令参数（例如。， ["/path/to/allow"]) - 统一资源定位符：对于HTTP服务器

Add MCP Server _MCP服务器配置表，带文件系统服务器设置示例_

想建立自己的MCP服务器吗？ 结账 创建mcp服务器 -使用TypeScript、多个框架（MCP SDK或FastMCP）和内置调试工具，在几秒钟内即可完成脚手架生产就绪的MCP服务器。

MCP服务器配置示例

文件系统服务器（stdio）

{
  "name": "filesystem",
  "type": "stdio",
  "command": "npx",
  "args": ["@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
}

HTTP API服务器

{
  "name": "web-api",
  "type": "http",
  "url": "http://localhost:8080/mcp",
  "headers": {
    "Authorization": "Bearer your-token"
  }
}

备注：一些HTTP MCP服务器需要OAuth 2.0身份验证。看 OAuth文档 了解详情。

工具审批工作流

1. 代理请求工具 -AI建议使用工具
2. 审批提示 -界面显示工具详细信息并请求批准
3. 用户决策:

- ✅ 允许：按要求执行工具 - ❌ 拒绝：跳过工具执行 - ✏️ 修改：执行前编辑工具参数

1. 继续对话 -代理以工具结果进行响应

建筑

高级概述

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Next.js UI   │◄──►│  Agent Service   │◄──►│  LangGraph.js   │
│   (React 19)   │    │  (SSE Streaming) │    │    Agent        │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   React Query   │    │     Prisma       │    │  MCP Clients    │
│   (State Mgmt)  │    │   (Database)     │    │   (Tools)       │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                  ┌──────────────────────────────┐
                  │   PostgreSQL  │  MinIO/S3    │
                  │  (Persistence)│ (File Store) │
                  └──────────────────────────────┘

核心组件

代理生成器(src/lib/agent/builder.ts)

• 使用代理创建状态图→工具_批准→工具流
• 处理工具批准中断
• 管理模型绑定和系统提示

MCP集成(src/lib/agent/mcp.ts)

• 从数据库存储的MCP服务器动态加载工具
• 支持stdio和HTTP传输
• 用于预防冲突的工具名称前缀

流媒体服务(src/services/agentService.ts)

• 服务器发送事件以获得实时响应
• 消息处理和块聚合
• 工具审批工作流处理

聊天挂钩(src/hooks/useChatThread.ts)

• 面向乐观UI的React Query集成
• 流管理和错误处理
• 工具审批用户界面

文件存储(src/lib/storage/)

• 与MinIO（开发）或AWS S3（生产）兼容的S3存储
• AI的文件验证、上传和内容处理
• 基于base64转换的多模式消息构建

有关详细的体系结构文档，请参阅 docs/ARCHITECTURE.md.

发展

可用脚本

pnpm dev                 # Start development server with Turbopack
pnpm build              # Production build
pnpm start              # Start production server
pnpm lint               # Run ESLint
pnpm format             # Format with Prettier
pnpm format:check       # Check formatting

# Database
pnpm prisma:generate    # Generate Prisma client (after schema changes)
pnpm prisma:migrate     # Create and apply migrations
pnpm prisma:studio      # Open Prisma Studio (database UI)

项目结构

src/
├── app/                 # Next.js App Router
│   ├── api/            # API routes (stream, upload, mcp-servers)
│   └── thread/         # Thread-specific pages
├── components/         # React components
├── hooks/              # Custom React hooks
├── lib/                # Core utilities
│   ├── agent/          # Agent-related logic
│   └── storage/        # File upload & S3 utilities
├── services/           # Business logic
└── types/              # TypeScript definitions

prisma/
├── schema.prisma       # Database schema
└── migrations/         # Database migrations

关键文件

• 代理配置: src/lib/agent/builder.ts, src/lib/agent/mcp.ts
• API终点: src/app/api/agent/stream/route.ts, src/app/api/agent/upload/route.ts
• 文件存储: src/lib/storage/ （验证、上传、内容处理）
• 数据库模型: prisma/schema.prisma
• 主聊天界面: src/components/Thread.tsx, src/components/MessageInput.tsx
• 流逻辑: src/hooks/useChatThread.ts

贡献

我们欢迎捐款！该项目旨在成为LangGraph.js开发的社区资源。

入门指南

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/amazing-feature
3. 进行更改并添加测试
4. 承诺： git commit -m 'Add amazing feature'
5. 推： git push origin feature/amazing-feature
6. 打开拉取请求

开发指南

• 遵循TypeScript严格模式
• 使用Prettier进行格式化
• 为公共API添加JSDoc注释
• 彻底测试MCP服务器集成
• 更新新功能的文档

学习资源

LangGraph.js

• LangGraph.js文档
• StateGraph API参考
• 检查点指南

模型上下文协议（MCP）

• MCP规范
• MCP服务器存储库
• 构建MCP服务器

Next.js和React

• Next.js 15文档
• React 19发布说明
• React查询（TanStack查询）

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• LangChain 令人难以置信的人工智能框架
• 模型上下文协议 用于工具集成标准
• Next.js 令人惊叹的React框架团队

______________________________________________________________________

准备好构建下一个AI代理了吗？

开始使用

______________________________________________________________________

如果此仓库对您有所帮助，并且您希望在生产中实施它的指导，请随时联系 领英.