Telegram AI Assistant Bot

Telegram AI Assistant Bot

概述

Telegram AI Assistant Bot 是一个以推理为核心的 AI Agent，名为 Cortex-R，旨在通过 Telegram 与用户交互。它使用多个 Model Context Protocol（MCP）服务执行各种任务，例如网页搜索、文档处理、数学计算以及 Google 服务集成（如 Gmail 和 Google Sheets）。该机器人使用 stdio 和 sse 传输协议与这些 MCP 服务通信。

功能

• Telegram 集成：机器人通过 Telegram 与用户交互，响应用户的查询和任务。
• 多 MCP 服务支持：利用多个 MCP 服务实现多种功能。
  • Gmail 集成，用于电子邮件管理。
  • Google Sheets 集成，用于电子表格操作。
  • 使用 DuckDuckGo 的网页搜索功能。
  • 文档处理和语义搜索。
  • 数学计算。
• 动态工具发现：在初始化期间自动发现 MCP 服务中的工具。
• 可自定义的 Agent 策略：支持保守、重试一次和全部探索等不同策略。
• 记忆管理：检索和存储记忆项，以增强任务解决能力。
• 可配置的角色设定：允许自定义语气、详略程度和行为方式。

架构

该机器人由以下组件构建：

1. Telegram 机器人集成

该机器人使用 python-telegram-bot 库在 telegram_agent.py 中实现。它处理用户消息以及 /start 和 /help 等命令。用户查询由 Cortex-R Agent 处理。

2. 核心组件

• Agent 循环（core/loop.py）：管理 Agent 的主执行循环，包括感知、规划和工具执行。
• 会话管理（core/session.py）：使用 stdio 和 sse 传输协议处理与多个 MCP 服务的通信。
• 策略（core/strategy.py）：实现用于决策的规划策略。

3. MCP 服务

该机器人与以下 MCP 服务交互：

• Gmail 服务（gmail_server.py）：管理电子邮件操作，例如发送、读取和移至垃圾箱。
• Google Sheets 服务（mcp_gdrive_server.py）：处理创建、更新和共享 Google Sheets 等电子表格操作。
• 网页搜索服务（mcp_server_3.py）：使用 DuckDuckGo 执行网页搜索并获取网页内容。
• 文档处理服务（mcp_server_2.py）：处理文档，以便进行语义搜索和索引。
• 数学服务（mcp_server_1.py）：执行数学计算。

4. 配置

• 配置文件（config/profiles.yaml）：定义 Agent 设置，包括策略、记忆配置和 MCP 服务详细信息。
• 模型（config/models.json）：指定用于文本生成和嵌入的模型。
• 环境变量（.env）：存储 API 密钥和文件路径等敏感信息。

工作流

1. 初始化：

   • 机器人从 profiles.yaml 加载 MCP 服务配置。
   • 初始化 MultiMCP 调度器，以发现所有已配置 MCP 服务中的工具。

2. 用户交互：

   • 用户通过 Telegram 与机器人交互。
   • 机器人处理用户消息，并确定完成任务所需的工具。

3. 任务执行：

   • Agent 使用感知来理解用户查询。
   • 使用定义的策略规划下一步操作。
   • 从相应的 MCP 服务中执行所需工具。
   • 获取结果并回复用户。

4. 记忆管理：

   • 将工具输出和用户查询存储为记忆项。
   • 检索相关记忆以辅助解决任务。

配置

环境变量

在 .env 文件中设置以下变量：

• GEMINI_API_KEY：Gemini 模型的 API 密钥。
• SERVICE_ACCOUNT_PATH：Google 服务账号 JSON 文件的路径。
• DRIVE_FOLDER_ID：用于存储文件的 Google Drive 文件夹 ID。
• CREDENTIALS_PATH：OAuth 客户端凭据文件的路径。
• TOKEN_PATH：Google API 的令牌文件路径。

MCP 服务配置

在 config/profiles.yaml 中定义 MCP 服务：

mcp_servers:
  - id: gmail
    type: stdio
    script: gmail_server.py
    cwd: <path-to-server>
  - id: gdrive
    type: stdio
    script: mcp_gdrive_server.py
    cwd: <path-to-server>
  - id: math
    type: sse
    script: mcp_server_1.py
    url: http://localhost:8000/sse
    cwd: <path-to-server>
  - id: documents
    type: stdio
    script: mcp_server_2.py
    cwd: <path-to-server>
  - id: websearch
    type: stdio
    script: mcp_server_3.py
    cwd: <path-to-server>

安装

1. 克隆仓库：

   git clone <repository-url>
   cd <repository-folder>
   

2. 使用 uv 同步依赖：

   uv sync
   

3. 在 .env 中设置环境变量。
4. 启动 Telegram 机器人：

   uv run telegram_agent.py
   

使用方法

• 在 Telegram 上使用 /start 命令启动机器人。
• 向机器人发送查询或任务，例如：
  • “查找当前 F1 排名，并将其分享到 Google Sheet。”
  • “向 [email protected] 发送一封主题为 ‘Meeting Update’ 的电子邮件。”

贡献

欢迎贡献！请遵循以下步骤：

1. Fork 此仓库。
2. 为你的功能或错误修复创建一个新分支。
3. 提交 pull request，并详细描述所做的更改。

许可证

本项目采用 MIT License。详情请参阅 LICENSE 文件。