Serve an Agent through Telegram

Expose one persistent Agent through AgentOS's Telegram webhook interface. Streaming is enabled by default, and group chats only trigger the bot when it is mentioned or when a user replies to one of its messages.

basic.py

"""
Serve an Agent through Telegram
===============================

Expose one persistent Agent through AgentOS's Telegram webhook interface.
Streaming is enabled by default, and group chats only trigger the bot when it
is mentioned or when a user replies to one of its messages.

Prerequisites: TELEGRAM_TOKEN, OPENAI_API_KEY, and the `agno[telegram]` extra
Run: .venvs/demo/bin/python cookbook/05_agent_os/18_telegram/basic.py
Try in Telegram: Send /start, ask "Remember that my project is Cedar", then ask "What is my project?"
"""

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from agno.os.interfaces.telegram import Telegram

# ---------------------------------------------------------------------------
# Create Database
# ---------------------------------------------------------------------------

db = SqliteDb(
    id="telegram-basic-db",
    db_file="tmp/telegram_basic.db",
)

# ---------------------------------------------------------------------------
# Create Agent
# ---------------------------------------------------------------------------

telegram_assistant = Agent(
    id="telegram-assistant",
    name="Telegram Assistant",
    model=OpenAIResponses(id="gpt-5.5"),
    db=db,
    instructions=[
        "You are a helpful assistant on Telegram.",
        "Keep responses concise, friendly, and easy to read in a chat.",
        "Remember facts from earlier messages in the same conversation.",
    ],
    add_history_to_context=True,
    num_history_runs=3,
    markdown=True,
)

# ---------------------------------------------------------------------------
# Create AgentOS
# ---------------------------------------------------------------------------

agent_os = AgentOS(
    id="telegram-basic-os",
    description="AgentOS serving one persistent Telegram assistant.",
    agents=[telegram_assistant],
    interfaces=[
        Telegram(
            agent=telegram_assistant,
            prefix="/telegram",
            reply_to_mentions_only=True,
            reply_to_bot_messages=True,
        )
    ],
)
app = agent_os.get_app()

# ---------------------------------------------------------------------------
# Run AgentOS
# ---------------------------------------------------------------------------

if __name__ == "__main__":
    agent_os.serve(app=app)

Run the Example

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

Install dependencies

uv pip install -U "agno[os,telegram]" openai

Export environment variables

export OPENAI_API_KEY="your_openai_api_key_here"
export TELEGRAM_WEBHOOK_SECRET_TOKEN="your-random-webhook-secret"
unset APP_ENV
export TELEGRAM_TOKEN="your_telegram_token_here"

Create the bot and expose the server

Follow Telegram setup to create the bot with BotFather and obtain its token. Create two bots for the multiple-instance example. Use a random webhook secret containing only letters, numbers, underscores, and hyphens (1–256 characters). Keep webhook verification enabled for this public endpoint.

Install ngrok and run ngrok http 7777 in another terminal. Copy its public HTTPS URL and keep the tunnel running.

Run the example

Save the code above as basic.py, then run:

python basic.py

Register the webhook

Keep Python running. In a second terminal, set the same bot token(s) and webhook secret as above, then register each bot using your tunnel's public HTTPS origin:

export TELEGRAM_PUBLIC_URL="https://your-tunnel.ngrok-free.app"
curl -X POST "https://api.telegram.org/bot$TELEGRAM_TOKEN/setWebhook" --data-urlencode "url=$TELEGRAM_PUBLIC_URL/telegram/webhook" --data-urlencode "secret_token=$TELEGRAM_WEBHOOK_SECRET_TOKEN"

Confirm each response reports ok: true, then message the bot. Telegram keeps one webhook per bot; rerun registration after the tunnel URL changes. The two instances share this process's webhook secret, so use the same secret in both registrations.

Full source: cookbook/05_agent_os/18_telegram/basic.py