Agent For Telegram

英语 | 简体中文

Telegram代理机器人

项目目的

这个仓库提供了一个开源且可扩展的现代Telegram机器人示例，用于产品推荐和智能对话。它旨在为开发者和初学者提供帮助，使他们能够：

• 学习如何构建一个集产品推荐、AI聊天和工具/插件调用于一体的Telegram机器人
• 使用模型上下文协议（MCP）将大型语言模型（LLM）与外部API集成
• 探索代码结构、国际化、环境变量管理以及开源开发的最佳实践
• 快速适应、扩展或集成该机器人以用于自己的项目、商业用途，或作为构建AI驱动助手的参考

主要特点：

• 开源、文档齐全且符合PEP8规范的代码库
• 插件就绪：轻松添加新工具、API或大型语言模型（LLM）提供商
• 支持多轮对话、意图识别和丰富的商品信息
• 国际化友好，易于本地化
• 非常适合学习、快速原型制作和生产集成

关键词与用例

这个仓库非常适合对以下内容感兴趣的人：

• 构建一个用于电子商务、产品推荐或购物辅助的Telegram机器人
• 使用Python和异步框架创建一个AI聊天机器人或对话式AI助手
• 集成如OpenAI、Monica或自定义提供商等大型语言模型（LLMs）
• 实现插件系统、工具调用和函数调用工作流（RAG、代理、自动化）
• 在聊天机器人中管理多轮对话、用户上下文和记忆
• 开发客户支持机器人、市场交易机器人或智能购物助手
• 学习开源、可扩展且对开发者友好的机器人架构的最佳实践
• 使用MCP（模型上下文协议）实现统一的API和工具集成
• 快速原型制作、模板项目以及适用于AI驱动机器人的生产就绪启动套件

关键词： Telegram机器人、AI聊天机器人、产品推荐、电子商务、大型语言模型（LLM）、OpenAI、Monica、插件、工具调用、上下文管理、Python、异步、开源、多轮对话、智能体、自动化、检索增强生成（RAG）、函数调用、集成、最佳实践、模板、入门项目、应用商店、客户支持、购物机器人、对话式人工智能、API集成、可扩展、可扩展性、开发者友好、MCP、fastmcp、工具注册、插件生态系统、聊天智能体、记忆、上下文、API编排。

______________________________________________________________________

基本概念

1. 电报机器人

Telegram机器人是一个自动化程序，它在Telegram聊天中与用户互动，处理消息、命令、发送富文本、图片、按钮等。它通过官方的Telegram API与用户进行通信。

2. 人工智能代理（或AI智能体）

AI Agent通常指的是与大型语言模型（如GPT、Monica、OpenAI等）集成的智能模块。它能够理解用户意图，进行自然语言对话、问答，甚至判断用户需求（例如，是否推荐产品）。

3. MCP（模型上下文协议）

MCP（模型上下文协议） 这是一个为人工智能时代设计的开放、通用协议。其主要目标是标准化和简化开发者与大型语言模型（LLMs）、人工智能工具以及多轮对话代理的交互方式。MCP（假设为某协议名称，此处直译为“多协议中心”或根据具体上下文命名）提供了模型服务调用、工具注册、上下文管理和插件扩展的统一接口，使得各种人工智能能力能够无缝集成和协同工作。

MCP的关键概念和特性

• 统一模型调用： 通过标准协议调用任何大型语言模型（如OpenAI、本地模型、Monica等）或AI服务，无论供应商或后端如何。
• 工具注册： 注册可由模型或编排器调用的自定义工具（函数、API、插件），以实现函数调用、检索增强生成（RAG）以及代理工作流。
• 上下文管理： 维护和管理多轮对话上下文、用户状态以及工具输出，支持高级对话和记忆功能。
• 插件/工具生态系统： 轻松通过外部插件、API或业务逻辑扩展大型语言模型（LLMs），实现可组合且模块化的AI应用。
• 多模型与多工具协作： 在一个工作流中协调多个模型和工具，支持复杂的代理和自动化场景。
• 标准化协议： 将应用程序逻辑与特定的大型语言模型（LLM）提供商或工具实现解耦，使人工智能系统更易于移植和维护。

示例用例

• 人工智能聊天机器人与代理 构建能够聊天、回答问题并以统一方式调用外部工具（如搜索、产品推荐、订单追踪）的机器人。
• 智能助手： 将大型语言模型（LLMs）与业务API、数据库或自定义逻辑集成，以实现高级自动化和决策支持。
• 插件赋能的大型语言模型应用： 允许用户或开发人员在运行时注册新的工具/插件，即时扩展代理的功能。
• 多轮对话系统： 管理对话历史、用户资料和上下文，以实现个性化、连贯的交互体验。

什么是fastmcp？

fastmcp（注：这个词汇在中文中没有直接对应的翻译，它可能是某个特定领域或技术中的术语，根据音译和常规翻译习惯，可暂译为“快速MCP”，但具体含义需结合上下文确定。） 这是MCP协议最流行且可投入生产的Python实现版本。它提供了：

• 高性能异步服务器和客户端 用于可扩展、并发的人工智能应用
• 极简工具注册几秒钟内将任意Python函数或API注册为工具
• 自动OpenAPI/JSON模式生成 用于工具接口
• 自动生成的Python/JS客户端 便于集成
• 丰富的上下文和内存管理 用于高级代理工作流
• 广泛的插件和扩展支持
• 在真实世界的人工智能机器人、助手和自动化系统中经过实战检验

示例：统一工具调用

使用 MCP/fastmcp，您可以将一个 Python 函数注册为工具：

from fastmcp import MCPServer

server = MCPServer()

@server.tool()
def get_weather(city: str) -> str:
    """Get the weather for a city."""
    # ... call weather API ...
    return f"The weather in {city} is sunny."

现在，任何通过MCP连接的大型语言模型（LLM）或代理都可以调用 get_weather 作为一种工具，该协议将自动处理输入/输出、上下文以及错误管理。

生态系统与社区

• 网站： gofastmcp.com 可以翻译为“快速前往MCP（可能指某个特定网站、平台或服务）的网站”。不过，具体翻译可能还需根据“MCP”在该网站中的具体含义来调整。如果“MCP”没有特定含义，或者是一个通用的缩写，那么“快速前往MCP的网站”是一个比较通用的翻译
• GitHub： jlowin/fastmcp（注：这可能是一个项目或代码库的名称，直接翻译为中文保持原样，若需具体含义需根据上下文确定）
• 开源、不断增长的插件生态系统以及活跃的开发者社区

MCP和fastmcp是构建下一代人工智能机器人、助手、自动化工具以及支持插件的大型语言模型（LLM）应用的理想选择。它们使开发者能够以最小的阻力创建灵活、可扩展且面向未来的AI系统。

______________________________________________________________________

工作流图

flowchart TD
    A["User"] -->|"Send message"| B["Telegram Bot"]
    B -->|"Intent recognition"| C{"Is it product search?"}
    C -- "Yes" --> D["MCP Service"]
    D -->|"Return product list"| B
    C -- "No" --> E["AI Agent (GPT/LLM)"]
    E -->|"Return chat reply"| B
    B -->|"Send reply"| A

    %% Explanations
    B -.-> F1["Telegram Bot: Handles user messages, commands, and integrates with AI/MCP."]
    E -.-> F2["AI Agent: Uses LLM (like GPT) to chat, answer, or judge intent."]
    D -.-> F3["MCP: Modular Commerce Platform, provides product recommendation API."]

______________________________________________________________________

一个用于产品推荐和智能聊天的Telegram机器人，支持多大型语言模型（LLM）提供商、国际化以及开源最佳实践。

特点/特性

• 通过MCP服务进行产品推荐
• 智能意图识别（区分推荐与聊天）
• 多供应商LLM支持（monica/openai/mcp）
• 所有配置均通过环境变量进行
• 国际化：英文代码，双语注释
• 结构化产品富文本和内联按钮
• 完成单元测试
• 开源最佳实践：PEP8、文档、需求、设置、.env 示例

目录结构

.
├── handlers/                  # Message and command handlers
│   ├── commands.py
│   └── message.py
├── client.py                  # MCP client wrapper
├── gpt_service.py             # GPT service wrapper
├── utils/                     # Utility modules
│   ├── context.py
│   └── logging.py
├── main.py                    # Entry point
├── requirements.txt           # Dependencies
├── .env                       # Environment variables
├── .gitignore
├── README.md                  # English documentation
├── README_zh.md               # Chinese documentation
└── tests/                     # Unit tests
    └── test_basic.py

快速入门

我们建议使用 紫外线 用于快速、现代的Python依赖管理和虚拟环境。

1. 安装 uv（如果尚未安装）：

   pip install uv
   # or
   pipx install uv

1. 创建并激活一个虚拟环境：

   uv venv .venv
   # Windows
   .venv\Scripts\activate
   # macOS/Linux
   source .venv/bin/activate

1. 安装依赖项：

   uv pip install -r requirements.txt

1. 启动机器人：

   uv run client.py

或者，如果你愿意，也可以使用标准的 pip 和 Python。

环境变量

看 .env.example 对于所有必需的变量。最重要的环境变量包括：

• TELEGRAM_TOKEN - 电报机器人令牌
• MCP_SERVER_URL - MCP服务端点URL
• SHOP_URL - 商店页面URL
• SERVICE_URL - 客户服务网址
• SERVICE_USERNAME - 客户服务用户名
• POLICY_URL - 隐私政策网址
• LLM_PROVIDER - 大语言模型（LLM）提供商（例如。， monica， openai）
• MONICA_API_KEY - Monica API密钥（如果使用Monica）
• OPENAI_API_KEY - OpenAI API密钥（如使用OpenAI）
• OPENAI_MODEL - OpenAI模型名称（默认： gpt-4o)
• ASSETS_URL_PREFIX - 资产（图像）URL 前缀
• PROXY_URL - 代理URL（如需）

你可以复制 .env.example to .env 并填写你自己的价值观。

命令

• /start - 启动机器人
• /shop - 浏览产品
• /trackorder - 跟踪您的订单
• /help - 帮助
• /contact - 联系客服
• /language - 切换语言
• /policy - 隐私政策
• /feedback - 反馈

示例

screenshot

做出贡献

欢迎提交拉取请求！

许可证

麻省理工学院（MIT）

致谢

感谢所有贡献者和开源社区！