Metadata-Version: 2.4
Name: AgentEngine
Version: 0.1.4
Summary: AgentEngine 智能体框架
Author: Shuangrui Chen, Simeng Bian, Jingyuan Li, Mingchen Wan
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: elasticsearch>=8.17.2
Requires-Dist: exa_py>=1.9.1
Requires-Dist: fastapi>=0.115.12
Requires-Dist: httpx>=0.28.1
Requires-Dist: numpy>=1.26.4
Requires-Dist: openai>=1.69.0
Requires-Dist: psycopg2>=2.9.10
Requires-Dist: pydantic>=2.11.1
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: PyYAML>=6.0.1
Requires-Dist: Requests>=2.32.3
Requires-Dist: rich>=13.9.4
Requires-Dist: setuptools>=75.1.0
Requires-Dist: starlette>=0.46.1
Requires-Dist: unstructured>=0.17.2
Requires-Dist: uvicorn>=0.34.0
Requires-Dist: websockets>=15.0.1
Provides-Extra: quality
Requires-Dist: ruff>=0.9.0; extra == "quality"
Provides-Extra: test
Requires-Dist: pytest>=8.1.0; extra == "test"
Provides-Extra: dev
Requires-Dist: AgentEngine[quality,test]; extra == "dev"

# AgentEngine

AgentEngine 是一个轻量化、低代码的Agent SDK，提供了丰富的 Agent 工具集、流式输出能力和语音服务、数据清洗服务集成。

## 安装方式

```bash
pip install AgentEngine
```

或者从源代码安装：

```bash
git clone https://github.com/yourusername/AgentEngine.git
cd AgentEngine
pip install -e .
```

## 使用方式

```python
import AgentEngine
from AgentEngine.core import CoreAgent, OpenAIModel, MessageObserver
from AgentEngine.core.tools import EXASearchTool, FinalAnswerFormatTool
```

### 创建基本 Agent

```python
# 创建消息观察者
observer = MessageObserver()

# 创建模型（model和Agent必须使用同一个observer）
model = OpenAIModel(
    observer=observer,
    model_id="your-model-id",
    api_key="your-api-key",
    api_base="your-api-base"
)

# 创建工具
search_tool = EXASearchTool(exa_api_key="your-exa-key", max_results=5)
final_answer_tool = FinalAnswerFormatTool(llm=model, system_prompt="自定义提示词")

# 创建Agent
agent = CoreAgent(
    observer=observer,
    tools=[search_tool, final_answer_tool],
    model=model,
    name="my_agent",
    max_steps=5
)

# 运行Agent
result = agent.run("你的问题")
```

### 使用数据清洗服务

```python
from AgentEngine.data_cleanse import cleanse_data, DataCleanseService

# 直接清洗单个文档
result = cleanse_data(
    source="path/to/document.pdf",
    source_type="file"
)

# 或启动清洗服务进行任务管理
service = DataCleanseService(num_workers=3)
service.start()

# 创建清洗任务
task_id = service.create_task(
    source="https://example.com",
    source_type="url"
)

# 获取任务结果
task = service.get_task(task_id)
print(f"任务状态: {task['status']}")

# 停止服务
service.stop()
```

## 主要特性

- 继承 SmolAgent 的核心能力
- 支持多种 Agent 工具:
  - 博查 (Bocha) 搜索工具
  - EXA 专业网络检索工具
  - 本地知识库检索工具
  - 格式化输出工具
- 模型流式输出支持
- 可扩展的消息观察者模式
- 集成语音服务 (STT & TTS)
- 数据清洗服务:
  - 处理多种文档格式（PDF、Word、HTML等）
  - 批量处理多源文档
  - 任务队列管理和并行处理
  - REST API接口支持

## 核心组件

### CoreAgent

AgentEngine 的核心是 `CoreAgent` 类，它继承并增强了 SmolAgent 的 `CodeAgent`，提供以下关键能力：

- **Python代码执行**：支持解析和执行Python代码，能够动态处理任务
- **多语言支持**：内置中英文提示词模板，可根据需要切换语言
- **流式输出**：通过 MessageObserver 实现模型输出的实时流式显示
- **步骤追踪**：记录并展示Agent执行的每个步骤，便于调试和监控
- **自定义工具集成**：轻松集成自定义工具，扩展Agent能力
- **错误处理**：完善的错误处理机制，提高稳定性
- **状态管理**：维护和传递执行状态，支持复杂任务的连续处理

CoreAgent 实现了ReAct框架的思考-行动-观察循环：
1. **思考**：使用大语言模型生成解决方案代码
2. **行动**：执行生成的Python代码
3. **观察**：收集执行结果和日志
4. **重复**：根据观察结果继续思考和执行，直到任务完成

### MessageObserver

消息观察者模式的核心实现，用于处理 Agent 的流式输出：

- **流式输出捕获**：实时捕获模型生成的token
- **过程类型区分**：根据不同的处理阶段（模型输出、代码解析、执行日志等）格式化输出
- **多语言支持**：支持中英文输出格式
- **统一接口**：为不同来源的消息提供统一处理方式

ProcessType枚举定义了以下处理阶段：
- `STEP_COUNT`: 当前执行步骤
- `MODEL_OUTPUT`: 模型流式输出
- `PARSE`: 代码解析结果
- `EXECUTION_LOGS`: 代码执行结果
- `AGENT_NEW_RUN`: Agent基本信息
- `FINAL_ANSWER`: 最终总结结果

### 工具集

- **BoChaSearchTool**: 博查搜索工具，通过API接口获取网络搜索结果
- **EXASearchTool**: EXA搜索工具，提供高质量的网络搜索能力，支持结果自动总结
- **KBSearchTool**: 知识库检索工具，用于搜索和获取本地知识库中的相关信息
- **FinalAnswerFormatTool**: 输出格式化工具，根据自定义系统提示词优化最终输出格式

### 数据清洗服务

基于Unstructured IO构建的文档处理服务，提供以下功能：

- **多格式支持**：处理PDF、Word、HTML、Email等多种格式
- **多源处理**：支持文件、URL和原始文本处理
- **并行处理**：维护任务队列实现并行清洗（默认3线程）
- **REST API**：提供HTTP接口进行任务管理和结果检索
- **任务转发**：将处理结果转发至外部服务
- **状态追踪**：跟踪和查询任务处理状态
- **持久化**：可选的任务信息持久化存储

支持的文档格式：

| 文档类型 | 表格支持 | 策略选项 |
|---------|---------|---------|
| CSV/TSV文件 | 是 | 无 |
| 电子邮件 (.eml/.msg) | 否 | 无 |
| 文档类 (.docx/.doc/.odt/.rtf) | 是 | 无 |
| 表格类 (.xlsx/.xls) | 是 | 无 |
| 演示类 (.pptx/.ppt) | 是 | 无 |
| PDF文档 | 是 | auto/fast/hi_res/ocr_only |
| 图像文件 | 是 | auto/hi_res/ocr_only |
| HTML/XML | 否 | 无 |
| 纯文本/代码文件 | 否 | 无 |
| Markdown/ReStructured Text | 是 | 无 |

使用方式：
```bash
# 启动服务
python -m data_cleanse --host 0.0.0.0 --port 8000 --workers 3 --data-dir ./data
```

更多详细使用说明，请参考 [数据清洗服务文档](doc/data_cleanse_service.md)。

### 语音服务

提供统一的语音识别(STT)和语音合成(TTS)服务，支持WebSocket实时通信：

- **语音识别(STT)**: 通过WebSocket连接进行实时音频转写
- **语音合成(TTS)**: 通过WebSocket流式传输将文本转换为音频
- **单一端口**: 两种服务在同一端口上运行，简化部署和使用
- **流式处理**: 支持实时流式音频识别和合成，提供低延迟体验

## 使用语音服务

```bash
python -m AgentEngine.service.voice_service --env .env --port 8000
```

更多详细使用说明，请参考 [语音服务文档](doc/voice_service.md)。

## 开发团队

- Shuangrui Chen
- Simeng Bian
- Jingyuan Li
- Mingchen Wan
- Yichen Xia

## Known Issues

- 上传服务没有正确调用批处理能力 @Shuangrui Chen
- 新知识库上传应当刷新文件列表组件 @Yichen Xia
- 去除上传完成按钮 @Yichen Xia
- 新知识库名上传文件后应当锁死 @Yichen Xia
- 创建知识库完成后回到创建知识库会出现错误，并且上传组件回到一个错误版本 @Yichen Xia
- /kb/create逻辑清理 @Yichen Xia
- 命名重复性校验问题 @Yichen Xia
- 搜索结果数据库保存没有清理机制和需要重新设计表字段 @Jingyuan Li @Yichen Xia

- agent非工具节点，不需要final_answer直接输出 @Shuangrui Chen
- 本地知识库检索具备图片关联能力 @Simeng Bian

4月2日 问题梳理
- 前端问答页面重构 @Jingyuan Li @Mingchen Wan
  - 查看历史对话不显示step中的Token消耗，查看历史对话与回答展示使用统一逻辑 @Jingyuan Li
  - 对话过程被中断，过程记录需要保存 @Jingyuan Li
- 对话界面上传文件 @Jingyuan Li
- 问答页面只展示出了用户名称，图标和描述没有展示
- 对话不支持并发，无用户概念。同一时刻多人提问，会产生conversation_id冲突
- voice.env文件合并入.env文件 @Jingyuan Li
- 历史对话需要对话完成之后自动生成 @Jingyuan Li
- 问答页面缺少停止对话按钮 @Jingyuan Li
- 多轮对话轮数限制

- 配置页面“应用名称”和“详情描述”无法实时输入 @Yichen Xia
- 配置页面步骤一需要整体放大，减少周边遗留的空白 @Yichen Xia
- 配置页面步骤二进入时需要加载默认配置 @Yichen Xia
- 配置页面支持中英文

## Future Features

- Observer全量重构到Callback架构
- 提供NL2SQL能力
- Embedding模型抽象化
- 多用户使用能力
- 提供DeepDoc数据清洗能力
- 提供向量知识库自动化Summary与自动化识别入库
- 提供可视化工具能力
- 提供邮件发送、提醒发送能力
- 提供文搜图、图搜图能力
- 多模态对话能力

## 版本信息

当前版本: 0.1.4

## 如何运行
- 启动es docker容器
- 根目录下创建voice.env
```
APPID=8316863819
TOKEN=BIGaOBcc5M-uezzEXQKJgN7MDeDhwLjp

# STT Config
RESOURCEID=volc.bigasr.sauc.duration
WS_URL=wss://openspeech.bytedance.com/api/v3/sauc/bigmodel
SEG_DURATION=100
STREAMING=true
FORMAT=pcm
CHANNEL=1
RATE=16000
BITS=16
CODEC=raw
COMPRESSION=false


# TTS Config
CLUSTER=volcano_tts
VOICE_TYPE=zh_male_jieshuonansheng_mars_bigtts
SPEED_RATIO=1.3
```
- 根目录下创建.env
```
ELASTICSEARCH_HOST=https://localhost:9200
ELASTICSEARCH_API_KEY=UTJqNTZaVUJ4SVpJVFlxVDR6NXA6a2hXRWhhZnZRNzJUV2duNlN6dnZyZw==
JINA_API_URL=https://api.jina.ai/v1/embeddings
JINA_MODEL=jina-clip-v2
JINA_API_KEY=jina_8974beb929f54f75b34189baa6af3384LabI_OpPdFd_SAJ6T8zRm-8rwnaJ
CREATE_TEST_KB=False
ELASTICSEARCH_SERVICE=http://localhost:8000
DATA_CLEANSE_SERVICE=http://localhost:8001


# 前端配置
APP_APP_NAME='智能问答'
APP_APP_DESCRIPTION='定制化智能问答助手，基于理解复杂问题并提供精准解答。支持知识检索、Agent配置，为您提供专业、高效的信息服务和决策支持。'
APP_ICON_TYPE='preset'
APP_ICON_INDEX='0'
APP_ICON_COLOR='#235fe1'
APP_CUSTOM_ICON_URL=''

# 模型配置
LLM_MODEL_NAME='deepseek-ai/DeepSeek-V3'
LLM_DISPLAY_NAME='deepseek-V3'
LLM_API_API_KEY=sk-igdyctwzxymykufnlikqaasiqznsvdcadtdyizuxixtftfmm
LLM_API_MODEL_URL=https://api.siliconflow.cn

LLMSECONDARY_MODEL_NAME='deepseek-ai/DeepSeek-R1-Distill-Qwen-7B'
LLMSECONDARY_DISPLAY_NAME='DeepSeek-Qwen-7B'
LLMSECONDARY_API_API_KEY='sk-igdyctwzxymykufnlikqaasiqznsvdcadtdyizuxixtftfmm'
LLMSECONDARY_API_MODEL_URL='https://api.siliconflow.cn/v1'

EMBEDDING_MODEL_NAME='jina-clip-v2'
EMBEDDING_DISPLAY_NAME='jina-clip-v2'
EMBEDDING_API_API_KEY='jina_bcdd8036bbd94333b2dcfe1ed7af10c0Bs0IQxt_WuiDsa7gwPJ5kUhqF-Ia'
EMBEDDING_API_MODEL_URL='https://api.jina.ai/v1/embeddings'

RERANK_MODEL_NAME=''
RERANK_DISPLAY_NAME=''
RERANK_API_API_KEY=''
RERANK_API_MODEL_URL=''

STT_MODEL_NAME='stt_model'
STT_DISPLAY_NAME='Volcano STT'
STT_API_API_KEY=''
STT_API_MODEL_URL=''

TTS_MODEL_NAME='tts_model'
TTS_DISPLAY_NAME='Volcano TTS'
TTS_API_API_KEY=''
TTS_API_MODEL_URL=''

# 知识库配置
SELECTED_SELECTED_KNOWLEDGE_BASES='ljy_kb'
SELECTED_SELECTED_KB_NAMES='ljy_kb'
SELECTED_SELECTED_KB_MODELS='jina-clip-v2'
SELECTED_SELECTED_KB_SOURCES='elasticsearch'

# EXA-tools配置
EXA_API_KEY=8c7b42fa-d6bf-4b61-ae8d-5b2786388145
```
- 启动后端服务
```commandline
python -m AgentEngine.service.agent_run_service
python -m AgentEngine.service.conversation_management_service
python -m AgentEngine.service.elasticsearch_service
python -m AgentEngine.service.data_cleanse_service
python -m AgentEngine.service.voice_service --env ./voice.env
```
