# ClbotAgent **Repository Path**: hallo128/clbot-agent ## Basic Information - **Project Name**: ClbotAgent - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 6 - **Forks**: 1 - **Created**: 2026-02-19 - **Last Updated**: 2026-03-24 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Multi-Agent System 基于 LangGraph 的 ReAct 模式多 Agent 系统，支持聊天和会议纪要整理。 ## 架构设计 ``` ┌─────────────────────────────────────┐ │ 客户端层 │ └─────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ 主路由 Agent │ │ (意图识别 + 路由决策) │ └─────────────────────────────────────┘ │ │ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ │ 聊天 Agent │ │ 会议纪要 Agent │ └─────────────────┘ └─────────────────┘ │ │ └────────┬────────┘ ▼ ┌─────────────────────────────────────┐ │ ConversationSummaryBufferMemory │ └─────────────────────────────────────┘ ``` ## 功能特性 - **多 Agent 路由**: 主 Agent 自动识别意图并路由 - **聊天 Agent**: ReAct 模式，支持工具调用 - **会议纪要 Agent**: 结构化输出，Markdown 格式 - **记忆存储**: 自动保存对话历史 - **API 服务**: FastAPI，支持桌面机器人调用 ## 快速开始 ```bash # 环境准备 python3.11 -m venv .venv source .venv/bin/activate pip install -r requirements.txt # 设置API-Key cp .env.example .env # 运行方式选择 python -m src.run_agent # 交互式命令行 python -m src.run_service # HTTP API 服务 python src/examples/run_api_example.py # Python 代码调用示例 ``` ## 三种运行方式 ### 1. run_agent.py - 交互式命令行 直接与 Agent 对话，适合测试和调试。 ```bash python -m src.run_agent ``` 输入内容直接回车，AI 自动识别意图。输入 `quit`/`exit` 退出，输入 `clear` 清空记忆。 --- ### 2. run_service.py - HTTP API 服务 启动 FastAPI 服务，提供 HTTP 接口。 ```bash python -m src.run_service # 默认端口 8000，访问 http://localhost:8000/docs 查看 API 文档 ``` **接口说明：** | 接口 | 方法 | 参数 | 说明 | |------|------|------|------| | `/health` | GET | - | 健康检查 | | `/chat` | POST | `message`(必填), `session_id`(可选) | 对话接口 | **请求示例：** ```bash curl -X POST http://localhost:8000/chat \ -H "Content-Type: application/json" \ -d '{"message": "你好", "session_id": "user_001"}' ``` **响应：** ```json { "reply": "你好！有什么可以帮你的？", "session_id": "user_001", "intent": "chat" } ``` --- ### 3. run_api.py - Python 库调用 可直接 import 到其他 Python 项目中使用。 #### 安装依赖 ```bash pip install -r requirements.txt ``` #### 函数接口 | 函数 | 类型 | 说明 | |------|------|------| | `run_agent()` | 同步 | 推荐用于同步脚本 | | `arun_agent()` | 异步 | 推荐用于 FastAPI 等异步框架 | #### 参数说明 | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | `content` | str | ✅ 是 | 用户输入内容 | | `session_id` | str | ❌ 否 | 会话 ID，不传自动生成 UUID。传入相同 ID 可保持对话上下文 | | `intent` | Intent | ❌ 否 | 预定义意图。`Intent.CHAT` 跳过 LLM 判断直接聊天；`Intent.MEETING` 跳过 LLM 判断直接生成会议纪要。不传则由 LLM 自动判断 | #### 返回值 ```python reply, session_id, intent = run_agent("你好", session_id="user_001") # reply: str - Agent 回复内容 # session_id: str - 实际使用的会话 ID # intent: str - "chat" 或 "meeting" ``` #### 使用示例 ```python from src.run_api import run_agent, arun_agent, Intent # 同步调用（自动判断意图） reply, sid, intent = run_agent("你好", session_id="user_001") # 同步调用（指定意图，跳过 LLM 判断） reply, sid, intent = run_agent("会议内容...", session_id="user_001", intent=Intent.MEETING) # 异步调用 reply, sid, intent = await arun_agent("你好", session_id="user_001") ``` 更多示例见：`src/examples/run_api_example.py` --- ## 测试 ## 文档指南 项目提供了完整的开发文档，位于 `docs/` 目录。 ### 📚 推荐阅读顺序 | 顺序 | 文件 | 内容 | 适合人群 | | --- | ---------------------------------------------------- | ---------- | ---- | | 1 | [docs/01-README.md](./docs/01-README.md) | 项目简介和概念入门 | 所有人 | | 2 | [docs/02-QUICKSTART.md](./docs/02-QUICKSTART.md) | 5 分钟快速运行 | 首次使用 | | 3 | [docs/03-ARCHITECTURE.md](./docs/03-ARCHITECTURE.md) | 系统架构和设计 | 理解整体 | | 4 | [docs/04-CORE.md](./docs/04-CORE.md) | 核心配置模块 | 开发者 | | 5 | [docs/05-SCHEMA.md](./docs/05-SCHEMA.md) | 数据结构定义 | 开发者 | | 6 | [docs/06-MEMORY.md](./docs/06-MEMORY.md) | 记忆管理模块 | 开发者 | | 7 | [docs/07-AGENTS.md](./docs/07-AGENTS.md) | Agent 实现详解 | 开发者 | | 8 | [docs/08-TESTING.md](./docs/08-TESTING.md) | 测试指南 | 开发者 | ### 文件关系 ``` docs/ ├── 01-README.md # 入口：项目概览 │ # 链接到其他所有文档 │ ├── 02-QUICKSTART.md # 快速运行 │ # 依赖：01-README │ ├── 03-ARCHITECTURE.md # 系统架构 │ # 依赖：01-README, 02-QUICKSTART │ # 概述所有模块，为后续详细文档做铺垫 │ ├── 04-CORE.md # 核心配置 │ # 依赖：03-ARCHITECTURE │ # 最底层模块，被其他模块依赖 │ ├── 05-SCHEMA.md # 数据结构 │ # 依赖：03-ARCHITECTURE, 04-CORE │ # 定义数据类型，被 Agent 使用 │ ├── 06-MEMORY.md # 记忆管理 │ # 依赖：03-ARCHITECTURE, 04-CORE │ # 提供对话历史功能 │ ├── 07-AGENTS.md # Agent 实现 ⭐ 核心 │ # 依赖：03-ARCHITECTURE, 04-CORE, 05-SCHEMA, 06-MEMORY │ # 整合所有模块，实现核心业务逻辑 │ └── 08-TESTING.md # 测试指南 # 依赖：04-CORE, 05-SCHEMA, 07-AGENTS # 确保代码质量 ``` ### 学习路径 ``` 新手入门路径： 01-README.md → 02-QUICKSTART.md → 03-ARCHITECTURE.md 开发者路径： 01-README.md → 02-QUICKSTART.md → 03-ARCHITECTURE.md → 04-CORE → 05-SCHEMA → 06-MEMORY → 07-AGENTS → 08-TESTING.md ``` --- ## 环境配置 ### 创建虚拟环境 ```bash # 切到包管理目录（专门管理包环境），如果没有则创建 mkdir ~/venv cd ~/venv # 查看 Python 版本 python3 --version # 创建虚拟环境（推荐使用 Python 3.11 或 3.12） python3.11 -m venv llm_env # 激活虚拟环境 source llm_env/bin/activate # 选择解释器的目录：~/venv/llm_env/bin/python ``` ### 安装项目依赖 ```bash # 进入项目目录 cd ./ClbotAgent # 激活虚拟环境（如尚未激活） source ~/venv/llm_env/bin/activate # 安装依赖 pip install -r requirements.txt # 验证安装版本 pip list | grep "langchain\|openai\|pydantic" ``` ### 设置 API Key ```bash # 复制环境变量配置文件 cp .env.example .env # 编辑 .env 文件，填入你的 API Key # OPENAI_API_KEY=your_key_here # 或使用其他支持的供应商 ``` ### 支持的 LLM 供应商 在 `.env` 文件中设置： ```bash # OpenAI LLM_PROVIDER=openai OPENAI_API_KEY=sk-... # DeepSeek LLM_PROVIDER=deepseek DEEPSEEK_API_KEY=sk-... # 月之暗面 (Moonshot) LLM_PROVIDER=kimi KIMI_API_KEY=sk-... # 字节豆包 LLM_PROVIDER=doubao DOUBAO_API_KEY=sk-... # 阿里通义 LLM_PROVIDER=qwen QWEN_API_KEY=sk-... ``` ## 项目结构 ``` src/ ├── agents/ # Agent 定义 │ ├── router_agent.py # 路由 Agent（意图识别） │ ├── chat_agent.py # 聊天 Agent（ReAct 模式） │ ├── meeting_agent.py # 会议纪要 Agent │ ├── factory.py # 工厂函数 │ ├── tools.py # 工具定义 │ └── prompts.py # 提示词 ├── core/ # 核心配置 ├── schema/ # 结构化输出 ├── memory/ # 记忆存储 ├── session/ # Session 管理（多用户隔离） ├── run_agent.py # 交互式命令行入口 ├── run_api.py # Python 库接口（可被其他项目导入） ├── run_service.py # HTTP API 服务 └── examples/ # 使用示例 └── run_api_example.py tests/ # 测试 (84 tests) docs/ # 文档 ``` ## License MIT