telegram-agenium

Turn any Telegram bot into an agent:// endpoint. Part of the Agenium agent-to-agent protocol.

Features

• Bot as Agent — Register a Telegram bot as agent://botname.telegram and handle messages from both Telegram users AND the agent:// protocol
• Agent Caller — Call other agent:// agents from your bot and return results to Telegram users
• Webhook Bridge — Telegram webhook → agent:// message conversion
• Auto Agent Card — Serves /.well-known/agent.json automatically

Install

pip install telegram-agenium

Quick Start

import asyncio
from telegram_agenium import AgeniumBot

bot = AgeniumBot(
    token="BOT_TOKEN",
    agent_name="mybot",
    agent_domain="telegram",
)

@bot.on_telegram_message
async def handle_telegram(update, context):
    result = await bot.call_agent("agent://search.agenium", update.message.text)
    await update.message.reply_text(result)

@bot.on_agent_message
async def handle_agent(message):
    return {"response": f"Bot received: {message['content']}"}

# Starts both Telegram polling + agent:// HTTP server
asyncio.run(bot.start(port=8080))

How It Works

When you run bot.start(port=8080), the SDK:

1. Starts Telegram bot polling (receiving user messages)
2. Starts an HTTP server on the given port with:
   • GET /.well-known/agent.json — Agent card (for discovery)
   • POST /agent/message — Receives agent:// protocol messages
   • GET /health — Health check

Other agents can send messages to your bot via HTTP using the Agenium protocol frames.

Components

Module	Description
AgeniumBot	Main class — Telegram bot + agent server
AgentServer	Standalone agent:// HTTP server
AgentCaller	Call other agents via agent:// URIs
WebhookBridge	Bridge Telegram webhooks to agent://
converter	Convert between Telegram and agent:// formats
types	Protocol frames, agent cards, message types

Protocol

Messages follow the Agenium protocol frame format:

{
  "version": "1.0",
  "messageId": "abc123",
  "type": "REQUEST",
  "sessionId": "sess456",
  "timestamp": 1707840000,
  "payload": {
    "method": "message",
    "params": { "content": "Hello!" }
  }
}

DNS Resolution

Agent URIs like agent://search.agenium are resolved via the Agenium DNS server at 185.204.169.26:3000.

Domain Registration

Supports optional domain registration on the Agenium DNS system using a marketplace API key (dom_<64 hex>). Pass api_key parameter to auto-register your agent on startup. Get your API key from the Telegram Domain Marketplace.

License

MIT

Bug Reporting

This project includes optional bug reporting to the Agenium monitoring server.

Configuration

Set the following environment variables to enable bug reporting:

BUG_REPORT_URL=http://130.185.123.153:3100
BUG_REPORT_TOKEN=your_token_here

Bug reporting is disabled by default — it only activates when BUG_REPORT_TOKEN is set. Reports are sent asynchronously (fire and forget) and never block the main application.