# agent-project

**Repository Path**: llm_agent/agent-project

## Basic Information

- **Project Name**: agent-project
- **Description**: SalesGPT 是一个上下文感知的 AI 销售助手，具备阶段判断、历史对话管理、工具调用及基于产品知识库生成响应等核心能力
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-08
- **Last Updated**: 2025-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

```python
.
├── sales_gpt_control.py       # 销售智能体的“控制器”模型封装，负责对话阶段管理、历史记录、调用 Agent 工具等核心流程。
├── sales_gpt.py               # 程序主入口，负责加载配置、初始化 SalesGPT 实例，并执行对话交互逻辑（例如 `ask(agent, input)`）。
├── product_knowledge.py       # 产品知识库构建模块，用于构建和加载产品信息的向量索引，生成 Agent 工具。
│
├── Readme.md                  # 项目主说明文档，介绍项目用途、运行方式、依赖环境等。
├── SalesGPT.md                # 专门介绍 SalesGPT 实现原理、链路结构、关键组件的技术文档（更偏技术解读）。
└── sample_product_catalog.txt # 示例产品知识库数据，包含用于构建向量搜索库的问界产品信息。
```

## **SalesGPT 核心逻辑概述**

`SalesGPT` 是一个支持上下文理解的 AI 销售助手，具备如下能力：

1. **阶段感知（Stage Awareness）**：通过历史对话自动判断当前处于销售流程的哪一个阶段（如介绍、资格确认、价值主张等）。
2. **多模态对话生成（With or Without Tools）**：根据是否启用工具能力，使用不同的对话链（Chain）来生成响应。
3. **工具调用能力（Tool Use）**：在对话中动态调用工具（如查找产品信息、推荐系统等）以增强对话能力。
4. **完整历史上下文维护（Conversation History）**：全程记录对话轮数并提供给 LLM，确保上下文连续性。
5. **知识驱动响应（Product Knowledge Grounding）**：对话内容基于企业产品知识库，减少幻觉、增强相关性。

## 案例说明

- `对齐企业架构`

| 项目             | 当前实现                                                | 企业实践                                                     |
| ---------------- | ------------------------------------------------------- | ------------------------------------------------------------ |
| **控制器抽象**   | `SalesGPT` 类统一封装对话阶段控制、工具管理、Agent 推理 | 企业中通常也有 `AgentManager` 或 `SessionManager` 控制核心对话逻辑 |
| **销售阶段建模** | 使用 `conversation_stage_dict` 手动建模销售阶段         | 企业也会预定义阶段流程（例如“线索→意向→跟进→转化”），甚至对接 CRM 状态机 |

- `工程可维护性 —— 存在明显提升空间`

| 项目         | 当前实现                                                     | 企业实践                                                     |
| ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| **配置管理** | 写死在代码中，如销售阶段、公司信息、员工名等                 | 企业通常通过配置中心或数据库配置，如 JSON / YAML / DB 管理   |
| **状态管理** | 使用类属性 `conversation_history`、`current_conversation_stage` | 企业会使用 Redis / DB 做会话状态持久化，支持容错与多用户并发 |
| **日志打印** | 使用 `print`                                                 | 企业中会统一接入日志框架，如 ELK、Datadog、Sentry 做监控与报警 |

✅ **改进建议**：

- 所有可变信息（角色名、公司信息、阶段定义）应外部注入（配置或数据库）
- 会话状态要持久化（如存到 Redis / MongoDB）
- Agent 推理日志要接入链路追踪系统（如 OpenTelemetry）

## 调用顺序梳理（执行链路）

```yaml
1. 初始化 SalesGPT（SalesGPT.from_llm(...)）
│
├─ 初始化阶段判断器（StageAnalyzerChain）
├─ 初始化纯文本对话链（SalesConversationChain）
├─（可选）构造工具链 Tool + Prompt + Agent + Executor
│
└─ 构造 SalesGPT 实例（带所有组件）

2. 开始对话：seed_agent()
│
└─ 设置当前阶段为 “介绍阶段” + 清空对话历史
text

3. 用户输入：human_step(user_input)
│
└─ 将用户输入记录进 conversation_history
text


4. 判断阶段：determine_conversation_stage()
│
├─ 拼接对话历史文本
├─ 使用 stage_analyzer_chain 分析当前应处于哪一阶段
└─ 更新 current_conversation_stage
text


5. AI 生成回复：step() → _call({})
│
├─ 判断是否 use_tools：
│   ├─ True  → 调用 sales_agent_executor（支持工具）
│   └─ False → 调用 sales_conversation_utterance_chain（普通 Chain）
│
├─ 输入构造包括：
│   销售员信息、公司信息、当前阶段、历史对话、目的等
│
└─ 添加 AI 回复到 conversation_history
```

- 完整对话循环如下

```yaml
seed_agent()                       ← 初始设置
↓
human_step("你好，我想了解下问界M7")
↓
determine_conversation_stage()     ← 自动识别当前对话阶段（如“价值主张”）
↓
step()                             ← AI 基于阶段、上下文生成回复（可含工具调用）
↓
human_step(...)                    ← 用户继续发言
↓
determine_conversation_stage()
↓
step()
...
```

## 核心模块解释与作用

| 模块名                    | 类型                  | 说明                                                   |
| ------------------------- | --------------------- | ------------------------------------------------------ |
| `SalesGPT`                | 控制器类              | 核心智能体类，负责对话阶段管理、输入输出组织、工具调用 |
| `conversation_stage_dict` | 字典                  | 销售阶段的 ID → 描述映射，决定对话走向                 |
| `StageAnalyzerChain`      | Chain                 | 根据对话历史判断当前销售阶段                           |
| `SalesConversationChain`  | Chain                 | 普通的对话生成链，不含工具                             |
| `sales_agent_executor`    | AgentExecutor（可选） | 使用工具的 Agent 推理器，增强功能（如知识检索）        |
| `conversation_history`    | List[str]             | 对话历史上下文                                         |
| `from_llm()`              | 类方法                | 实例构造器，接入 llm、构造 tool+prompt、初始化控制器   |

## 总结：SalesGPT 架构能力一览

| 能力           | 说明                                                |
| -------------- | --------------------------------------------------- |
| ✅ 对话阶段感知 | 自动判断处于销售流程的哪一阶段                      |
| ✅ 记忆与上下文 | 每轮对话都纳入历史，驱动 LLM 生成上下文相关回复     |
| ✅ 工具调用能力 | 工具可以是搜索产品手册、推荐系统等增强工具          |
| ✅ 产品知识支持 | Agent 提问时基于 product_catalog 进行构造提示词     |
| ✅ 模块分离设计 | Chain、Prompt、Agent、Executor 分离，便于调试和扩展 |