GenericAgent Frontend Interfaces: Telegram, QQ, WeChat, and Desktop UIs

GenericAgent provides nine production-ready frontend interfaces spanning Telegram, QQ, WeChat, WeCom, DingTalk, Feishu, Streamlit web UI, Qt GUI, and desktop pet widgets, all implemented in the frontends/ package and unified through the AgentChatMixin abstraction.

The lsdefine/GenericAgent repository ships with a comprehensive suite of frontend adapters that bridge the core LLM orchestrator to popular chat platforms and desktop environments. These GenericAgent frontend interfaces reside in the frontends/ directory, each handling platform-specific authentication, message formatting, and streaming response delivery while maintaining identical agent logic across all channels.

Chat Platform Bot Interfaces

Telegram Bot (frontends/tgapp.py)

The Telegram implementation uses the python-telegram-bot library to create an asynchronous polling loop. It receives messages via ApplicationBuilder, forwards prompts to GeneraticAgent.put_task(), and streams HTML-formatted replies back to users according to the source in frontends/tgapp.py.

QQ Bot (frontends/qqapp.py)

Built on the official botpy SDK, the QQ adapter creates a QQBot client that handles C2CMessage and GroupMessage events. The QQApp class (subclassing AgentChatMixin) manages command parsing, splits long replies automatically, and supports text, photo, and document transmission as implemented in frontends/qqapp.py.

WeChat Official Account (frontends/wechatapp.py)

This interface implements a low-level HTTP/QR-login client (WxBotClient). After authentication, it polls getupdates to extract user text, drives the agent with prompts, and handles file uploads via CDN with automatic encryption/decryption for media messages.

WeCom (Enterprise WeChat) (frontends/wecomapp.py)

Using the wecom_aibot_sdk WebSocket client, the WeCom adapter routes incoming messages through WeComApp (an AgentChatMixin implementation). Responses are streamed as markdown cards suitable for enterprise environments.

DingTalk (frontends/dingtalkapp.py)

The DingTalk frontend relies on the dingtalk-stream SDK for real-time message reception. It forwards chatbot messages to DingTalkApp, then dispatches batched markdown responses via HTTP API.

Feishu/Lark (frontends/fsapp.py)

Powered by the official lark-oapi SDK, this WebSocket-based interface listens for events indefinitely, constructs user-friendly text representations, and replies using send_message supporting text, images, files, and interactive cards.

Desktop and Web Interfaces

Streamlit Web UI (frontends/stapp.py)

The primary web interface provides a full-screen Streamlit application hosting a chat window with streaming output display. It interacts with the core agent through agent.put_task() and includes controls for LLM switching, abort commands, and autonomous mode toggling.

Qt GUI (frontends/qtapp.py)

A minimal Qt-based graphical client embedding the same message-routing logic found in chat-style frontends, suitable for native desktop applications.

Desktop Pet Widget (frontends/desktop_pet.pyw)

Optional animated desktop companions that expose a tiny HTTP endpoint (/) for status updates from the Streamlit UI. These can be launched as subprocesses from any interface to provide visual feedback during agent operations.

Shared Architecture: The AgentChatMixin Pattern

All GenericAgent frontend interfaces share a common contract implemented through AgentChatMixin in frontends/chatapp_common.py. This abstraction supplies:

• Task tracking and conversation state management
• Command handling (e.g., /stop, /llm <model>)
• Automatic message splitting for long responses
• Standardized interaction flow: initialize GeneraticAgent → authenticate with platform → receive message → agent.put_task(prompt, source="<platform>") → consume streaming queue → format and send response

This design isolates transport-specific code while keeping agent logic identical across Telegram bots, QQ groups, WeChat accounts, and web UIs.

Running GenericAgent Frontends

Starting the Telegram Bot

pip install python-telegram-bot

# Configure mykey.py with tg_bot_token and tg_allowed_users

python -m frontends.tgapp

The entry point creates a socket lock on port 19527, validates the allow-list, starts the agent daemon thread, and launches the polling loop.

Launching the QQ Adapter

pip install qq-botpy

# Populate mykey.py with qq_app_id, qq_app_secret, and qq_allowed_users

python -m frontends.qqapp

This establishes a single-instance lock on port 19528 and runs the async botpy client.

Running the Feishu/Lark Bot

pip install lark-oapi

# Set fs_app_id and fs_app_secret in mykey.py

python -m frontends.fsapp

The main() function initializes the Lark client, registers handle_message as the event callback, and maintains a persistent WebSocket connection.

Deploying the Streamlit Interface

pip install streamlit
streamlit run frontends/stapp.py

The UI loads the agent via @st.cache_resource, renders the sidebar controls, and streams responses using the agent_backend_stream generator.

Summary

• GenericAgent supports nine distinct frontend interfaces across mobile chat platforms and desktop environments.
• Chat platforms (Telegram, QQ, WeChat, WeCom, DingTalk, Feishu) each have dedicated adapters in frontends/ using their respective official SDKs.
• Desktop options include Streamlit web UI, Qt GUI, and optional desktop pet widgets.
• All implementations rely on AgentChatMixin from frontends/chatapp_common.py for consistent command handling and message streaming.
• Each frontend follows the same five-step contract: initialize agent, authenticate, receive message, push task via put_task(), and stream formatted responses.

Frequently Asked Questions

What SDKs does GenericAgent use for Telegram and QQ?

The Telegram frontend uses the python-telegram-bot library with asynchronous ApplicationBuilder polling, while the QQ frontend builds on the official botpy SDK to handle C2C and group messages.

Can GenericAgent reply with images and files, not just text?

Yes. The QQ adapter supports photo and document messages, the Feishu interface handles images and files via send_message, and the WeChat implementation manages CDN uploads with automatic encryption for media content.

How do I prevent multiple instances of the same frontend from running?

Each production frontend implements socket-based single-instance locks. The Telegram bot uses port 19527, while the QQ bot uses port 19528, ensuring only one process per interface runs simultaneously.

Is there a way to run GenericAgent without a chat platform?

Yes. The Streamlit web UI (frontends/stapp.py) and Qt GUI (frontends/qtapp.py) provide standalone graphical interfaces that interact directly with the core agent without requiring third-party messaging platform accounts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}