Telegram OpenAI AgentKit

A lightweight Telegram bot wrapper that enables Telegram users to chat directly with AgentKit-powered AI agents — upload, switch, and interact with workflows seamlessly through a simple Telegram interface.

Features:

• 🤖 Direct Workflow Integration - Upload Agent Builder exported workflows and chat with them via Telegram
• 🔄 Multi-Workflow Support - Register and switch between multiple workflows per user
• 📤 Easy Updates - Update existing workflows with new versions using /update
• 💬 Conversation Sessions - Maintains conversation history using OpenAI Agents SDK
• 📦 Zero Config - Just upload your exported agent builder workflows as-is with no code changes needed
• ⚡ Built on Latest Tech - Uses python-telegram-bot 21.x and openai-agents SDK

---

Table of Contents

• Quick Start
  • Prerequisites
  • Setup
• Usage
  • Create & Upload a Workflow
• Development
  • Running in Docker
  • Code Quality Tools
    • Formatting with Black
    • Linting with Ruff
    • Type Checking with Mypy
    • Development Workflow
• License & Contact

Quick Start

Prerequisites

• Python >=3.12 (version specified in .tool-versions recommended)
• Poetry (installation guide)

Setup

# Clone the repository
git clone https://github.com/hschickdevs/telegram-openai-agentkit.git
cd telegram-openai-agentkit

# Install dependencies with Poetry
poetry install

# Configure environment variables
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY and TELEGRAM_BOT_TOKEN

# Run the bot
poetry run python -m src

Usage

After starting the bot, see existing commands with /help.

Create & Upload a Workflow:

1. Create a new workflow in the OpenAI Agent Builder tool.

   Make sure to create an End node in your workflow, otherwise the responses will be empty.

2. Once finished, click the Code button -> Agents SDK -> and copy the code snippet as Python:

   

3. Save the code snippet as a .py or .txt file on your local machine (e.g., my_workflow.py or my_workflow.txt).

4. Use /upload in Telegram and send the file when prompted.

5. Give your workflow a name when prompted.

6. Once the workflow is registered, you can activate it with /activate <workflow_name>.

Chat normally after activating a workflow - it just works! 🚀

Development

Running in Docker

Ensure that you have set your environment variables in a .env file (see above).

docker compose up -d

Code Quality Tools

This project uses several tools to maintain code quality:

Formatting with Black

# Format all Python files
poetry run black .

# Check formatting without making changes
poetry run black --check .

Linting with Ruff

# Run linter on all files
poetry run ruff check .

# Auto-fix issues where possible
poetry run ruff check --fix .

# Watch mode for development
poetry run ruff check --watch .

Type Checking with Mypy

# Run type checker
poetry run mypy src/

# Check specific file
poetry run mypy src/bot/app.py

Development Workflow

# Install all dependencies (including dev)
poetry install

# Run all quality checks before committing
poetry run black .
poetry run ruff check --fix .
poetry run mypy src/

License & Contact

This project is licensed under the Apache License 2.0 (open-source, free for personal and commercial use).

Reach out to me on Telegram if you have any questions or feedback!

Built with ❤️ for the OpenAI AgentKit community