全栈语言图谱nextjs代理

Name: 全栈语言图谱nextjs代理
Author: IBJunior

作者：IBJunior51 星标更新：2025-11-22

安装使用来源：spider==github.com

项目介绍

LangGraph.js AI Agent 模板

一个用于构建具有LangGraph.js的AI代理的生产就绪Next.js模板，支持Model Context Protocol (MCP)集成、人工介入工具审批以及持久会话记忆。

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

功能

动态工具加载与MCP

Model Context Protocol 集成用于动态工具管理
通过Web UI添加工具 - 不需要更改代码
支持stdio和HTTP MCP服务器
工具名称前缀以防止冲突

人工介入工具审批

在执行前进行交互式工具调用审批
具有批准/拒绝/修改选项的细粒度控制
可选自动审批模式适用于可信环境
实时流式传输并暂停工具执行

<div align="center"> <img src="docs/images/tool-approval.png" alt="工具审批对话框" width="600" /> 带有详细参数检查的工具审批对话框 </div>

持久会话记忆

使用PostgreSQL后端的LangGraph检查点
完整的会话历史保存
基于线程的组织
跨会话无缝恢复

实时流式接口

使用Server-Sent Events (SSE)进行实时响应
使用React Query进行乐观UI更新
类型安全的消息处理
错误恢复和优雅降级

现代技术栈

前端: Next.js 15, React 19, TypeScript, Tailwind CSS
后端: Node.js, Prisma ORM, PostgreSQL
AI: LangGraph.js, OpenAI/Google模型
UI: shadcn/ui组件, Lucide图标

快速开始

先决条件

Node.js 18+ 和 pnpm
Docker (用于PostgreSQL)
OpenAI API密钥或Google AI 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_URL="postgresql://user:password@localhost:5434/agent_db"

# AI模型（选择一个或两个）
OPENAI_API_KEY="sk-..."
GOOGLE_API_KEY="..."

# 可选：默认模型
DEFAULT_MODEL="gpt-4o-mini"  # 或 "gemini-1.5-flash"

3. 启动数据库

docker compose up -d

4. 数据库设置

pnpm prisma:generate
pnpm prisma:migrate

5. 运行开发服务器

pnpm dev

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

屏幕截图

<table> <tr> <td align="center"> <img src="docs/images/chat-interface.png" alt="聊天界面" width="400" /> 主要聊天界面 简洁、响应式的流式响应设计 </td> <td align="center"> <img src="docs/images/mcp-configuration.png" alt="MCP配置" width="400" /> MCP服务器管理 轻松设置和配置工具服务器 </td> </tr> <tr> <td align="center"> <img src="docs/images/thread-sidebar.png" alt="线程管理" width="400" /> 线程管理 使用持久历史记录组织对话 </td> <td align="center"> <img src="docs/images/agent-configuration.png" alt="流式响应" width="4 400" /> 代理配置 支持多个模型提供商 </td> </tr> </table>

使用指南

添加MCP服务器

导航到设置 - 点击侧边栏中的齿轮图标
添加MCP服务器 - 点击“添加MCP服务器”按钮
配置服务器：
- 名称：唯一标识符（例如，“filesystem”）
- 类型：选择 stdio 或 http
- 命令：对于stdio服务器（例如，npx @modelcontextprotocol/server-filesystem）
- 参数：命令参数（例如，["/path/to/allow"]）
- URL：对于HTTP服务器

添加MCP服务器 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"
  }
}

工具审批工作流程

代理请求工具 - AI建议使用工具
审批提示 - 界面显示工具详情并请求审批
用户决策：
- ✅ 允许：按请求执行工具
- ❌ 拒绝：跳过工具执行
- ✏️ 修改：在执行前编辑工具参数
继续对话 - 代理根据工具结果回应

架构

高级概述

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Next.js UI   │◄──►│  Agent Service   │◄──►│  LangGraph.js   │
│   (React 19)   │    │  (SSE Streaming) │    │    Agent        │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   React Query   │    │     Prisma       │    │  MCP Clients    │
│   (状态管理)    │    │   (数据库)       │    │   (工具)       │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │   PostgreSQL     │
                       │  (持久化)        │
                       └──────────────────┘

核心组件

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

创建具有代理→工具审批→工具流程的状态图
处理工具审批中断
管理模型绑定和系统提示

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

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

流式服务 (`src/services/agentService.ts`)

使用Server-Sent Events进行实时响应
消息处理和片段聚合
工具审批工作流程处理

聊天钩子 (`src/hooks/useChatThread.ts`)

与React Query集成以实现乐观UI
流管理及错误处理
工具审批用户界面

有关详细的架构文档，请参阅docs/ARCHITECTURE.md。

开发

可用脚本

pnpm dev                 # 启动带有Turbopack的开发服务器
pnpm build              # 生产构建
pnpm start              # 启动生产服务器
pnpm lint               # 运行ESLint
pnpm format             # 使用Prettier格式化
pnpm format:check       # 检查格式

# 数据库
pnpm prisma:generate    # 生成Prisma客户端（在模式更改后）
pnpm prisma:migrate     # 创建并应用迁移
pnpm prisma:studio      # 打开Prisma Studio（数据库UI）

项目结构

src/
├── app/                 # Next.js App Router
│   ├── api/            # API路由
│   └── thread/         # 线程特定页面
├── components/         # React组件
├── hooks/              # 自定义React钩子
├── lib/                # 核心实用程序
│   └── agent/          # 代理相关逻辑
├── services/           # 业务逻辑
└── types/              # TypeScript定义

prisma/
├── schema.prisma       # 数据库模式
└── migrations/         # 数据库迁移

关键文件

代理配置：src/lib/agent/builder.ts, src/lib/agent/mcp.ts
API端点：src/app/api/agent/stream/route.ts
数据库模型：prisma/schema.prisma
主要聊天界面：src/components/Thread.tsx
流式逻辑：src/hooks/useChatThread.ts

贡献

我们欢迎贡献！此项目旨在成为LangGraph.js开发的社区资源。

开始

分叉仓库
创建特性分支：git checkout -b feature/amazing-feature
进行更改并添加测试
提交：git commit -m '添加惊人的功能'
推送：git push origin feature/amazing-feature
打开Pull Request

开发指南

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