# agent-dome

**Repository Path**: fz6/agent-dome

## Basic Information

- **Project Name**: agent-dome
- **Description**: agent智能体模版
- **Primary Language**: NodeJS
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-22
- **Last Updated**: 2026-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能体系统 - 快速开始指南

## 🎯 项目概述

基于 **LangGraph** 流程编排的智能体系统，支持根据用户意图自动识别并路由到专业的 Sub-Agent。采用前后端分离架构，Hub-Sub 模式设计，支持 A2A 通信和流式响应。

## 📁 项目结构

```
agent_dome/
├── frontend/                    # React + TypeScript 前端应用
│   ├── src/
│   │   ├── components/          # 可复用组件
│   │   │   ├── ChatInterface.tsx    # 聊天界面（支持进度显示）
│   │   │   └── AgentMonitor.tsx     # Agent 监控面板
│   │   ├── services/            # API 服务
│   │   │   └── agent.service.ts     # Agent 交互服务
│   │   ├── store/               # Zustand 状态管理
│   │   │   └── agentStore.ts        # Agent 状态存储
│   │   └── types/               # TypeScript 类型定义
│   └── package.json
│
├── backend/                     # NestJS + TypeScript 后端应用
│   ├── src/
│   │   ├── modules/
│   │   │   ├── agent-hub/           # Agent Hub 中心协调器
│   │   │   │   ├── hub.controller.ts
│   │   │   │   └── hub.service.ts
│   │   │   ├── sub-agent/           # Sub-Agent 模块
│   │   │   │   ├── base-sub-agent.ts
│   │   │   │   └── agents/
│   │   │   │       ├── echo.agent.ts           # 通用聊天 Agent
│   │   │   │       ├── calculator.agent.ts     # 数学计算 Agent ✨
│   │   │   │       └── code-assistant.agent.ts # 编程助手 Agent ✨
│   │   │   ├── langgraph/           # LangGraph 流程编排 ✨
│   │   │   │   ├── intent-recognizer.service.ts  # 意图识别
│   │   │   │   ├── orchestrator.service.ts       # 流程编排
│   │   │   │   └── langgraph.module.ts
│   │   │   ├── a2a/                 # A2A 通信模块
│   │   │   │   ├── a2a.service.ts
│   │   │   │   └── message-bus.service.ts
│   │   │   └── stream/              # 流式响应模块
│   │   │       ├── sse.service.ts
│   │   │       └── stream.controller.ts
│   │   ├── common/
│   │   │   └── interfaces/      # 公共接口定义
│   │   ├── app.module.ts        # 主模块
│   │   └── main.ts              # 入口文件
│   └── package.json
│
├── start.sh                     # 一键启动脚本
├── README.md                    # 本文件
├── ARCHITECTURE.md              # 架构设计文档
├── LANGGRAPH_ORCHESTRATION.md   # LangGraph 编排详细文档 ✨
└── LANGGRAPH_QUICKSTART.md      # LangGraph 快速开始 ✨
```

## 🌟 核心特性

### ✨ 基于 LangGraph 的智能路由
- **意图识别**: 使用 LLM 自动识别用户意图（聊天、计算、代码等）
- **动态路由**: 根据意图自动调用最合适的专业 Agent
- **流式响应**: 支持实时流式输出，带进度显示

### 🤖 已集成的 Agent

| Agent | 意图类型 | 能力标签 | 功能描述 |
|-------|---------|----------|----------|
| **Echo Agent** | `chat` | `echo`, `test`, `simple`, `chat`, `ai` | 通用聊天、问候 |
| **Calculator Agent** ✨ | `calculate` | `calculate`, `math`, `arithmetic` | 数学计算、算术题 |
| **Code Assistant** ✨ | `code` | `code`, `programming`, `development`, `debug` | 编程助手、代码生成 |

## 🔧 环境要求

- Node.js >= 16.x
- npm >= 8.x
- 通义千问 API Key（配置在 `backend/.env`）

## 📦 安装步骤

### 方式一：一键安装（推荐）

```bash
chmod +x start.sh
./start.sh
```

### 方式二：手动安装

#### 1. 安装后端依赖

```bash
cd backend
npm install
```

#### 2. 安装前端依赖

```bash
cd ../frontend
npm install
```

## 🚀 启动应用

### 方式一：分别启动

#### 启动后端服务

```bash
cd backend
# 开发模式（支持热重载）
npm run start:dev

# 生产模式
npm run start:prod
```

后端服务将在 http://localhost:3002 启动

#### 启动前端服务

```bash
cd frontend
npm start
```

前端服务将在 http://localhost:8001 启动

### 方式二：使用启动脚本

```bash
chmod +x start.sh
./start.sh
```

## 💡 使用示例

### 1. 查看已注册的 Agent

```bash
curl http://localhost:3002/api/hub/agents
```

响应示例：

```json
{
  "success": true,
  "data": [
    {
      "id": "echo-agent-1",
      "name": "Echo Agent (Qwen Powered)",
      "capabilities": ["echo", "test", "simple", "chat", "ai"],
      "status": "idle"
    },
    {
      "id": "calculator-agent",
      "name": "Calculator Agent (计算助手)",
      "capabilities": ["calculate", "math", "arithmetic"],
      "status": "idle"
    },
    {
      "id": "code-assistant-agent",
      "name": "Code Assistant (编程助手)",
      "capabilities": ["code", "programming", "development", "debug"],
      "status": "idle"
    }
  ]
}
```

### 2. 提交任务（自动路由）

```bash
curl -X POST http://localhost:3002/api/hub/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "type": "auto",
    "payload": {
      "message": "1+1 等于几？"
    },
    "metadata": {
      "sessionId": "test-session-1"
    }
  }'
```

**系统会自动**：
1. 识别为 `calculate` 意图
2. 路由到 CalculatorAgent
3. 返回计算结果

### 3. 监听 SSE 流

在新终端窗口运行：

```bash
curl -N http://localhost:3002/api/stream/sse?sessionId=test-session-1
```

### 4. 查看 Hub 状态

```bash
curl http://localhost:3002/api/hub/status
```

响应示例：

```json
{
  "success": true,
  "data": {
    "activeAgents": 0,
    "totalAgents": 3,
    "pendingTasks": 0,
    "processingTasks": 0,
    "uptime": 45.69
  }
}
```

## 🎨 前端功能

访问前端应用 http://localhost:8001 后，你将看到：

### 1. 💬 聊天对话
- 发送消息进行对话
- **实时进度显示**（提交 → 连接 → 思考 → 回复 → 完成）
- 流式展示 AI 回复内容
- 支持多轮对话

### 2. 📊 健康监控
- Hub 状态统计（总 Agent 数、活跃数、任务队列）
- 所有已注册 Agent 列表
- 实时状态刷新（只在页面可见时轮询）

## 🔍 API 端点

### Hub 相关

- `GET /api/hub/agents` - 获取所有已注册的 Agent
- `GET /api/hub/status` - 获取 Hub 状态
- `POST /api/hub/tasks` - 提交新任务
- `GET /api/hub/agents/search?capability=echo` - 根据能力查找 Agent

### 流式响应

- `GET /api/stream/sse?sessionId={session-id}` - SSE 流式端点
- `GET /api/stream/health` - 健康检查

## 🧪 测试场景

### 测试 1: 计算意图
```
发送："1+1 等于几？"
→ 识别为 calculate 意图
→ 路由到 CalculatorAgent
→ 返回："计算结果：1+1 = 2"
```

### 测试 2: 代码意图
```
发送："写一个 Python 的 Hello World"
→ 识别为 code 意图
→ 路由到 CodeAssistantAgent
→ 返回：
```python
print("Hello, World!")
```
```

### 测试 3: 聊天意图
```
发送："你好"
→ 识别为 chat 意图
→ 路由到 EchoAgent
→ 返回："你好！很高兴见到你..."
```

## 🛠️ 添加自定义 Sub-Agent

### 1. 创建新的 Agent 类

在 `backend/src/modules/sub-agent/agents/` 目录下创建文件：

```typescript
import { BaseSubAgent } from '../base-sub-agent';
import { Task, AgentResponse, StreamChunk } from '../../common/interfaces/agent.interface';

export class WeatherAgent extends BaseSubAgent {
  constructor() {
    super('weather-agent', '天气助手', ['weather', 'forecast']);
  }
  
  async handle(task: Task): Promise<AgentResponse> {
    const city = task.payload?.city;
    const weather = await this.fetchWeather(city);
    
    return {
      taskId: task.id,
      success: true,
      data: { city, weather }
    };
  }
  
  async *handleStream(task: Task): AsyncGenerator<StreamChunk> {
    const sessionId = task.metadata?.sessionId || 'unknown';
    
    yield {
      sessionId,
      agentId: this.id,
      type: 'status',
      content: { message: '正在查询天气...' },
      timestamp: Date.now()
    };
    
    // 模拟流式输出
    yield {
      sessionId,
      agentId: this.id,
      type: 'data',
      content: { chunk: `今天${city}的天气晴朗...` },
      timestamp: Date.now()
    };
  }
  
  private async fetchWeather(city: string) {
    // 实现天气查询逻辑
    return { temperature: 25, condition: '晴朗' };
  }
}
```

### 2. 双重注册机制

根据项目规范，需要同时注册到 **AgentHub** 和 **LangGraph 编排器**：

修改 `backend/src/modules/sub-agent/sub-agent.module.ts`:

```typescript
import { Module, OnModuleInit } from '@nestjs/common';
import { AgentHub } from '../agent-hub/hub.service';
import { WeatherAgent } from './agents/weather.agent';
import { IntentType } from '../langgraph/intent-recognizer.service';
import { LangGraphOrchestratorService } from '../langgraph/orchestrator.service';

@Module({
  providers: [WeatherAgent],
  exports: []
})
export class SubAgentModule implements OnModuleInit {
  constructor(
    private readonly hub: AgentHub,
    private readonly orchestrator: LangGraphOrchestratorService
  ) {}

  onModuleInit() {
    // 1. 注册到 AgentHub（用于状态监控）
    const weatherAgent = new WeatherAgent();
    this.hub.registerSubAgent(weatherAgent);
    
    // 2. 注册到 LangGraph 编排器（用于意图识别路由）
    this.orchestrator.registerAgent(IntentType.WEATHER, weatherAgent);
  }
}
```

### 3. 测试新 Agent

```bash
curl -X POST http://localhost:3002/api/hub/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "type": "auto",
    "payload": {
      "message": "北京今天天气如何？"
    },
    "metadata": {
      "sessionId": "weather-test-1"
    }
  }'
```

## 🔗 A2A 通信示例

Agent 之间可以通过 MessageBus 进行通信：

```typescript
// 发送请求给其他 Agent
const response = await this.a2aService.sendRequest(
  this.id,
  'other-agent-id',
  { action: 'help', data: '...' }
);

// 广播消息
this.a2aService.broadcast(this.id, {
  event: 'status_update',
  status: 'busy'
});
```

## ⚠️ 故障排除

### 后端启动失败

1. **端口占用**: 检查端口 3002 是否被占用
   ```bash
   lsof -ti:3002 | xargs kill -9
   ```
2. **依赖未安装**: 确保执行 `npm install`
3. **查看详细错误**: 查看 `logs/backend.log`

### 前端无法连接后端

1. 确认后端服务已启动
2. 检查浏览器控制台的 CORS 错误
3. 确认 API 地址配置正确

### SSE 连接失败

1. 确保 sessionId 参数正确传递
2. 检查网络连接
3. 查看后端日志确认 SSE 服务正常

### LangGraph 不工作

1. 检查 IntentRecognizerService 是否正确初始化
2. 确认 Agent 已注册到 LangGraph 编排器
3. 查看后端日志中的意图识别信息

## 📚 文档索引

- [`ARCHITECTURE.md`](./ARCHITECTURE.md) - 详细架构设计文档
- [`LANGGRAPH_ORCHESTRATION.md`](./LANGGRAPH_ORCHESTRATION.md) - LangGraph 编排完整指南
- [`LANGGRAPH_QUICKSTART.md`](./LANGGRAPH_QUICKSTART.md) - LangGraph 快速开始
- [`BUGFIX_MONITOR_PAGE.md`](./BUGFIX_MONITOR_PAGE.md) - 监控页面修复记录
- [`FEATURE_PROCESSING_PROGRESS.md`](./FEATURE_PROCESSING_PROGRESS.md) - 处理进度显示功能

## 🎯 下一步

1. ✅ 阅读 [`LANGGRAPH_QUICKSTART.md`](./LANGGRAPH_QUICKSTART.md) 了解如何使用智能路由
2. ✅ 访问前端应用体验对话功能
3. ✅ 尝试创建自己的 Sub-Agent
4. ✅ 实现更复杂的 A2A 协作场景

## 💻 技术栈

### 前端
- **框架**: React 18 + TypeScript
- **状态管理**: Zustand
- **HTTP 客户端**: Axios
- **SSE 客户端**: 原生 EventSource

### 后端
- **框架**: NestJS
- **语言**: TypeScript
- **流程编排**: LangChain + LangGraph ✨
- **LLM 模型**: 通义千问 Qwen-plus
- **SSE 服务**: 自定义实现
- **消息总线**: 基于 Subject 的实现

---

**最后更新**: 2026-03-26  
**版本**: v2.0 (with LangGraph)