tg-cs-agent（tg cs 特工）

Telegram Customer Service Agent

RAG-powered Telegram customer service bot using Claude + Telethon + ChromaDB.

Architecture

• Telegram: Telethon userbot (not Bot API) — appears as a real user
• AI: Claude via Anthropic API with RAG context from local markdown docs
• Knowledge Base: ChromaDB + multilingual sentence-transformers embeddings
• Handoff: Auto-escalation to human agent when AI can't help

Prerequisites

• Python 3.11+
• Telegram account with API credentials (get from https://my.telegram.org)
• Anthropic API key
• Telethon session (logged in via tgctl-telethon login or manual auth)

Setup New Bot

1. Create project

mkdir -p ~/tg-cs-bot && cd ~/tg-cs-bot
cp -r <skill_dir>/scripts/*.py .
pip install anthropic chromadb sentence-transformers python-dotenv telethon

2. Configure environment

Create .env:

ANTHROPIC_API_KEY=<key>
ANTHROPIC_BASE_URL=https://api.anthropic.com
TELEGRAM_API_ID=<id>
TELEGRAM_API_HASH=<hash>
TELEGRAM_PROFILE=default
MODEL=claude-sonnet-4-20250514
KNOWLEDGE_DIR=docs
MAX_HISTORY=20
HANDOFF_CHAT_ID=<admin_telegram_id_or_username>

3. Add knowledge base

Put markdown files in docs/ directory. The bot splits by ## headers and vectorizes with paraphrase-multilingual-MiniLM-L12-v2 for multilingual support.

4. Login to Telegram (first time only)

python3 -c "
from telethon import TelegramClient
import asyncio
async def login():
    c = TelegramClient('~/.tgctl-telethon/default/session', API_ID, 'API_HASH')
    await c.start()
    print('Logged in:', (await c.get_me()).first_name)
asyncio.run(login())
"

5. Run

python3 main.py

Managing the Bot

• Start: python3 main.py (or use the start.sh script)
• Stop: Ctrl+C or kill the process
• Add knowledge: Drop .md files in docs/, restart bot
• Clear user history: User sends /clear
• Request human: User sends /human

Customization

System Prompt

Edit config.py → __post_init__ → self.system_prompt to change:

• Bot personality and tone
• Language rules
• Handoff trigger conditions
• Platform-specific instructions

Embedding Model

In knowledge.py, change model_name for different language support:

• paraphrase-multilingual-MiniLM-L12-v2 — multilingual (recommended)
• all-MiniLM-L6-v2 — English only, faster
• shibing624/text2vec-base-chinese — Chinese optimized

Handoff Behavior

The bot adds [HANDOFF] to responses when it can't help. This triggers:

1. Notification to HANDOFF_CHAT_ID with user info
2. A message to the user that human support is coming

File Structure

tg-cs-bot/
├── main.py              # Entry point, message routing
├── config.py            # Config + system prompt
├── agent.py             # Claude RAG agent
├── knowledge.py         # ChromaDB knowledge base
├── telegram_client.py   # Telethon wrapper
├── .env                 # Secrets (not committed)
├── docs/                # Knowledge base markdown files
│   ├── platform.md
│   ├── faq.md
│   └── ...
└── requirements.txt

Troubleshooting

• database is locked: Kill all Python processes, delete session.session-journal, rebuild session with sqlite dump/restore
• Not logged in: Run the login step again
• Poor RAG results: Check embedding model matches your docs language, use multilingual model for mixed content
• Bot not responding: Check [READY] Listening for messages... in logs, verify Telegram connection