{"slug": "i-built-a-telegram-ai-agent-that-can-actually-use-tools-o-o", "title": "I Built a Telegram AI Agent That Can Actually Use Tools O.O", "summary": "A developer has built Hexzie (HexTelegram), a Telegram-based AI assistant that combines a Node.js/Telegraf front end with a Go tool runner so an OpenAI-compatible model can call tools such as shell execution, file read/write, web search, web fetch, site reconnaissance and screenshots. The agent loop allows up to eight rounds of tool calls, and the bot edits a single live progress message to show streamed reasoning and tool status before replacing it with the final answer.", "body_md": "I've been building **Hexzie (HexTelegram)** a Telegram-based AI assistant that goes beyond just sending text back and forth.\n\nThe idea was simple:\n\nWhat if an AI assistant inside Telegram could actually use tools, inspect files, execute commands, search the web, and interact with Telegram itself?\n\nSo I built it.\n\n**HexTelegram (HTG)** — AI Telegram bot by **HexzoNetwork**\n\n⚠️ **Project in active development**, some features may still be in progress.\n\n**Hexzie** is a powerful and modern Telegram AI assistant built with:\n\n`tools-go`) — shell, files, web, screenshots, sysinfo`/` — no workspace jail`shell_exec` (any command), `file_read` / `file_write` / `file_list` from `web_search` (Bing), `web_fetch`, `web_check` (site recon), `web_screenshot` (chromium → PNG)`get_chat`\n**Hexzie** is an AI Telegram assistant built with **Node.js + Telegraf**, with a Go-based tool runner underneath.\n\nThe AI communicates through an **OpenAI compatible API**, allowing the model to decide when it needs to call a tool.\n\nThe architecture roughly looks like this:\n\n```\nTelegram\n   │\n   ▼\nTelegraf\n   │\n   ▼\nAuthentication\n   │\n   ▼\nPrompt / Context Builder\n   │\n   ▼\nAgent Loop\n   │\n   ├──► AI API\n   │      │\n   │      └── tool_calls\n   │\n   ├──► Go Tool Runner\n   │      ├── shell\n   │      ├── files\n   │      ├── web\n   │      ├── screenshots\n   │      ├── calculator\n   │      └── system info\n   │\n   └──► Telegram Tools\n          ├── send / edit / delete\n          ├── photo / document / buttons\n          ├── forward / pin\n          └── get_chat\n```\n\nThe important part is that the AI isn't limited to generating text.\n\nIt can **act**.\n\nThe Telegram side is written in Node.js using **Telegraf**.\n\nThat makes handling Telegram updates, messages, callbacks, photos, documents, and streaming relatively straightforward.\n\nFor the lower level tools, I used Go.\n\nThe Go runner handles things like:\n\n```\nshell_exec\nfile_read\nfile_write\nfile_list\nweb_fetch\nweb_search\nweb_check\nweb_screenshot\nget_time\ncalc\nsysinfo\n```\n\nThis gives the project a nice separation:\n\n```\nNode.js\n└── AI + Telegram + agent orchestration\n\nGo\n└── System / filesystem / web tools\n```\n\nOne of the most interesting parts is the agentic loop.\n\nA simplified version looks like:\n\n```\nUser message\n     │\n     ▼\nBuild context\n     │\n     ▼\nSend messages + tools to model\n     │\n     ▼\nDoes the model request a tool?\n     │\n   ┌─┴─┐\n  YES  NO\n   │    │\n   ▼    ▼\nRun    Final\ntool   answer\n   │\n   ▼\nAdd tool result\n   │\n   ▼\nAsk model again\n```\n\nHexzie currently allows up to **8 agent rounds**.\n\nFor example, a request could theoretically become:\n\n```\nUser:\n\"Check this website and tell me what server it's running on.\"\n\nAI:\n→ web_check()\n\nTool:\n→ returns HTTP/server/technology information\n\nAI:\n→ analyzes result\n\nTelegram:\n→ final response\n```\n\nThe model isn't just answering from its training data.\n\nIt's interacting with the environment through structured tools.\n\nI also wanted the bot to feel less like a traditional Telegram bot.\n\nInstead of:\n\n```\nUser → wait → huge response\n```\n\nHexzie keeps a single progress message and edits it while the agent works.\n\nWhile the model streams its reasoning, the message shows the action, a status, and a live custom line plus rotating tips:\n\n``` php\n> - 💭 Thinking\n|-> Reading request.\n| |-> - I should inspect the site's headers before summarizing.\nTips: SSE: Super Speedy Edits.\n```\n\nthen, while a tool runs:\n\n``` php\n> - 🔍 Checking site https://example.com\n|-> Running tool.\n| |-> - Comparing server headers to identify the stack.\nTips: Punch trees, hug servers!\n```\n\nand when it finishes, the same message is replaced with the actual answer.\n\nTips rotate every ~5 seconds, and the custom line is based on the model's own streamed reasoning when available falling back to themed statuses when it isn't.\n\nThis makes tool execution feel much more transparent.\n\nThere's another problem with AI bots:\n\nWhat happens if a user sends another message while the previous request is still running?\n\nInstead of letting requests pile up indefinitely, Hexzie keeps track of the newest request per chat.\n\nConceptually:\n\n```\nRequest A ────────────────X\n                            \\\nRequest B ──────────────────► active\n```\n\nIf request A becomes stale, it is aborted and its progress message is marked as skipped instead of eventually producing an outdated response.\n\nThis matters quite a lot once an agent can perform slow operations like web requests or multiple tool calls.\n\nHexzie also supports an API pool.\n\nInstead of depending on a single endpoint:\n\n```\nAPI #1\nAPI #2\nAPI #3\nAPI #4\n```\n\nThe bot can rotate endpoints when network errors or server-side failures occur.\n\nFor certain HTTP failures (like 502/503/504), it also retries with backoff before falling back to a non-streaming request.\n\nAPIs can be added and live-tested from Telegram itself with `/addapi <url> <key>`.\n\nThis is useful for self-hosted or multi-provider OpenAI-compatible setups where availability can vary.\n\nThe bot has two layers of conversation context.\n\nFirst, it keeps recent conversation turns in memory.\n\nThen, when the conversation gets large, older context is summarized by the model.\n\n```\nRecent messages\n      │\n      ├── keep directly (~12 turns)\n      │\nOlder messages\n      │\n      ▼\nAI summary\n      │\n      ▼\nmemory.json\n```\n\nThis keeps the context from growing indefinitely while preserving useful information.\n\nBecause Hexzie lives inside Telegram, I didn't want the AI to only have generic computer tools.\n\nIt also has Telegram-specific operations.\n\nFor example:\n\n```\ntg_send_message\ntg_send_buttons\ntg_send_photo\ntg_send_document\ntg_edit_message\ntg_delete_message\ntg_forward\ntg_chat_action\ntg_get_chat\ntg_pin\ntg_unpin\n```\n\nThat means the model can reason about Telegram as an environment instead of treating it as just a chat interface.\n\nHexzie can also operate in groups without responding to every single message.\n\nYou can trigger it with:\n\n```\n/talk explain this\n```\n\nor:\n\n```\n/t explain this\n```\n\nIt also supports prefixes such as:\n\n```\n=explain this\n~explain this\n|explain this\n```\n\nand mentions:\n\n```\n@Hexzie explain this\n```\n\nReplying directly to the bot also works.\n\nThis makes it possible to have the AI participate in a group without turning the chat into an AI-generated message flood.\n\nThis is probably the most important part of the project.\n\nHexzie can execute shell commands and access files.\n\nThat is **extremely powerful** and also **extremely dangerous**.\n\nAccess is controlled by user ID:\n\n```\n{\n  \"telegramToken\": \"PASTE_FROM_BOTFATHER\",\n  \"ownerUserId\": 123456789,\n  \"allowedUserIds\": [],\n  \"baseURL\": \"https://your-provider/v1\",\n  \"apiKey\": \"sk-...\",\n  \"model\": \"jmbot/mimo-v2.6-flash\",\n  \"systemPrompt\": \"\",\n  \"temperature\": 0.7,\n  \"maxTokens\": 2048\n}\n```\n\nOnly the owner and explicitly allowed user IDs can use the bot everyone else is silently ignored, even in groups. Owner only commands handle user and API management.\n\nSince shell/file tools run from `/` by default, you can also harden it with an optional sandbox:\n\n```\n\"shell\": {\n  \"workDir\": \"/home/you/sandbox\",\n  \"defaultTimeoutSec\": 30,\n  \"maxOutputChars\": 8000,\n  \"blockedPatterns\": [\"rm -rf /\", \"mkfs\", \":(){:|:&};:\"]\n}\n```\n\nGive the bot only the access you're comfortable with it acts with exactly the permissions you give it.\n\n**I need help about adding tools and secure the ai from becoming threat for system please check out my github and project and discuss at comment below!**", "url": "https://wpnews.pro/news/i-built-a-telegram-ai-agent-that-can-actually-use-tools-o-o", "canonical_source": "https://dev.to/hexzonetwork/i-built-a-telegram-ai-agent-that-can-actually-use-tools-oo-2cgc", "published_at": "2026-09-26 15:17:03+00:00", "updated_at": "2026-09-26 15:30:04.043717+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "large-language-models", "developer-tools"], "entities": ["Hexzie", "HexTelegram", "HexzoNetwork", "Telegram", "Telegraf", "Node.js", "Go", "OpenAI"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/i-built-a-telegram-ai-agent-that-can-actually-use-tools-o-o", "markdown": "https://wpnews.pro/news/i-built-a-telegram-ai-agent-that-can-actually-use-tools-o-o.md", "text": "https://wpnews.pro/news/i-built-a-telegram-ai-agent-that-can-actually-use-tools-o-o.txt", "jsonld": "https://wpnews.pro/news/i-built-a-telegram-ai-agent-that-can-actually-use-tools-o-o.jsonld"}}