Гайд · Agno 2.8 · AgentOS

Как собрать ИИ-агента на Agno:tools, MCP и Telegram

Q: Нужен ли MCP сразу или хватит обычных tools?

Для первого запуска хватит @tool и одного toolkit. MCP подключайте, когда нужен стандартный доступ к файлам, git, документации или нескольким серверам без ручной обвязки каждого API.

Пошагово: Agent → tools и MCP → Telegram Interface — рабочий контур под контент и лиды без n8n и LangGraph

Канал Maya Pro

Коротко. Готовый бот в Telegram отвечает в чате. Свой ИИ-агент на Agno умеет вызвать tools и MCP, пройти цепочку шагов и принести превью туда, где вы уже работаете — чаще всего в Telegram.

Ниже — рабочий контур: Agent → tools/MCP → Telegram Interface под контент и лиды, без n8n и без LangGraph. Публикация наружу — отдельно, после одобрения человека.

agno-agent — zsh

$ pip install -U "agno[os,telegram,mcp]"
# Agent → tools/MCP → preview в Telegram
→ HITL approve → публикация отдельно

Зачем собирать своего ИИ-агента, а не ставить готовый бот

Готовый бот в Telegram отвечает в чате и на этом останавливается. Свой ИИ-агент умеет другое: взять задачу, вызвать нужные инструменты, пройти цепочку шагов и принести результат туда, где вы уже работаете — чаще всего в Telegram.

Спрос на таких помощников растёт. В поиске часто спрашивают, как создать ИИ-агента с нуля, как сделать ИИ-агента для Telegram и как подключить инструменты без зоопарка сервисов. Параллельно крупные игроки анонсируют «универсальных агентов для бизнеса» — но предпринимателю и маркетологу часто нужен не чужой продукт «на всё», а свой узкий контур: ресёрч → черновик → превью → решение человека → публикация.

Коротко. Готовый бот = диалог. Свой агент = диалог + действия + контроль. Если цель — контент и лиды, выгоднее собрать контур под себя, чем подгонять универсальный чат под процессы.

Что такое Agno простыми словами (раньше Phidata)

Agno — это Python-библиотека и платформа для сборки ИИ-агентов. Раньше проект назывался Phidata. Сейчас на PyPI ставят пакет agno (актуальная линейка 2.8.x). Старые туториалы с phidata и импортами from phi... для новой версии не подходят.

У Agno три уровня, которые важно не смешивать:

Agent — один «сотрудник»: модель + инструкции + инструменты.
Team / Workflow — команда или конвейер из нескольких агентов.
AgentOS — runtime: поднимает API, интерфейсы (в том числе Telegram), память в вашей базе, панель управления.

Маркер: простыми словами. AgentOS — это «операционка» для агентов: не просто скрипт в терминале, а сервис, который принимает сообщения, хранит сессии и отдаёт ответы наружу (в Telegram, API и т.д.).

Agno позиционирует себя как SDK + runtime + control plane: можно начать с одного файла на Python и вырасти до команды агентов с выводом в мессенджер. Репозиторий открытый (Apache-2.0). Для русскоязычного поиска бренд Agno почти не ищут — поэтому в материале опираемся на родовые задачи: «создать ИИ-агента», «MCP-сервер», «ИИ-агент в Telegram».

Минимальный контур: Agent → tools и MCP → Telegram

Не нужно сразу строить «мультиагентную империю». Рабочий минимум выглядит так:

Запрос человека
    ↓
Agent (модель + инструкции)
    ↓
tools / MCPTools (поиск, файлы, API)
    ↓
AgentOS + Telegram Interface (превью в чат)
    ↓
Человек одобряет → публикация отдельно

Что это даёт на практике

Один агент отвечает и умеет действовать (tools).
MCP подключает готовые серверы инструментов без ручной обвязки каждого API.
Telegram — канал доставки для вас и команды, а не «ещё один сайт».
Публикация наружу (канал, блог, WordPress) — отдельный шаг после одобрения. Превью в чате ≠ автопостинг.

Маркер: простыми словами. Tool (инструмент) — функция, которую агент может вызвать сам: поискать в вебе, прочитать файл, отправить сообщение. Без tools агент только пишет текст. С tools он делает действия.

Контур Agno · не hero

Поток: Agent → tools/MCP → Telegram → HITL

На схеме «пакет» задачи идёт по рабочему минимуму гайда: агент вызывает tools и MCP, отдаёт превью в Telegram, затем ждёт человека. Публикация — отдельный шаг, не автопилот.

Agent — модель + инструкции, точка входа запроса.
tools / MCPTools — действия и внешние серверы без ручной обвязки каждого API.
Telegram preview — черновик в чат; HITL решает, выпускать ли дальше.

Дальше — установка и первый Agent на Python: окружение, зависимости и ответ без лишних интеграций.

Редакционная метафора контура, не скриншот AgentOS. Превью в Telegram ≠ автопостинг.

Установка и первый Agent на Python

Ниже — путь, который новичок может повторить. Нужны: Python 3.9+, терминал, ключ к модели (OpenAI, Anthropic или другой провайдер, который поддерживает Agno). Из России оплата зарубежных API часто идёт через карты/посредников или локальные обёртки — заложите этот шаг заранее. Telegram при этом работает штатно.

Окружение и зависимости

Шаг 1. Создайте папку проекта и виртуальное окружение.

mkdir agno-agent && cd agno-agent
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

Шаг 2. Установите Agno и нужные дополнения.

pip install -U agno
# для MCP:
pip install "agno[mcp]"
# для AgentOS + Telegram:
pip install "agno[os,telegram]"

Шаг 3. Положите ключи в .env (не коммитьте файл в git):

OPENAI_API_KEY=sk-...
TELEGRAM_TOKEN=...   # позже, от BotFather

Признак успеха шага: python -c "import agno; print(agno.__version__)" печатает версию (ожидайте линейку 2.8.x). Если видите ошибки импорта phi — вы по старой инструкции.

Первый ответ без лишних интеграций

Минимальный агент — один файл, без Telegram и без MCP:

from agno.agent import Agent
from agno.models.openai import OpenAIChat

agent = Agent(
    name="Helper",
    model=OpenAIChat(id="gpt-4o-mini"),
    instructions="Отвечай коротко на русском. Ты помощник маркетолога.",
    markdown=True,
)

agent.print_response("Сформулируй 3 идеи поста для Telegram-канала про автоматизацию")

Признак успеха: в терминале появился связный ответ на русском. Типичные ошибки новичка

Старый импорт from phi.agent import Agent → ставьте agno, импорты agno.*.
Нет ключа API → модель не ответит; проверьте .env и экспорт переменных.
Слишком «толстая» модель с первого дня → для теста берите лёгкую и дешёвую.

Пока этот файл работает, можно добавлять tools. Не прыгайте сразу в webhook Telegram.

Tools: как дать агенту реальные действия

Чат без инструментов — это черновик. Tools превращают агента в исполнителя: найти факты, прочитать файл, вызвать API, отправить сообщение.

Встроенные tools и свои `@tool`

В Agno есть готовые наборы (toolkits) — например, веб-поиск. Имена в актуальной версии заканчиваются на Tools (после миграции с Phidata: было DuckDuckGo(), стало DuckDuckGoTools()).

Свой инструмент — обычная Python-функция. Декоратор @tool из agno.tools добавляет флаги вроде подтверждения человеком:

from agno.tools import tool

@tool(requires_confirmation=True)
def publish_draft(text: str) -> str:
    """Готовит текст к публикации. Без подтверждения человека не публикует."""
    return f"Черновик принят ({len(text)} символов). Ждёт одобрения."

Маркер: простыми словами. HITL (human-in-the-loop) — человек в контуре: агент предлагает действие, вы подтверждаете или правите, и только потом идёт следующий шаг. Для контента и лидов это страховка от «опубликовал ерунду в канал».

Почему нельзя сваливать все tools в один контекст

Каждый tool занимает место в контексте модели: описание, схема аргументов, результаты вызовов. Если повесить на одного агента «всё подряд» — поиск, почта, CRM, файлы, десять MCP-серверов — модель путается, отвечает дольше и дороже.

Правило: одному агенту — узкая роль и 3–7 инструментов под эту роль. Остальное — другим агентам в Team/Workflow.

Коротко. Много tools ≠ умнее агент. Узкий набор = стабильнее результат.

MCP-сервер рядом с агентом

MCP простыми словами (не путать с «сервером для 1С»)

В поиске «MCP-сервер» часто путают с интеграциями для 1С. Здесь речь о другом.

Маркер: простыми словами. MCP (Model Context Protocol) — единый способ подключить к ИИ внешние инструменты и данные: файлы, поиск, документацию, API. MCP-сервер отдаёт набор tools по стандарту; агент подключается как клиент и вызывает их.

MCP tools — это не «ещё один чат», а каталог действий, которые агент может выполнить через протокол.

Подключение MCPTools: stdio и HTTP

В Agno ставят pip install "agno[mcp]", подключают MCPTools / MultiMCPTools из agno.tools.mcp.

Два основных транспорта:

stdio — по умолчанию. Агент запускает локальную команду (часто через npx или uvx) и общается с MCP-сервером через стандартный ввод/вывод.
streamable-http / SSE — подключение по URL к уже поднятому HTTP-серверу MCP.

Пример идеи (stdio):

from agno.tools.mcp import MCPTools

mcp_tools = MCPTools(command="uvx mcp-server-git")

Пример идеи (HTTP):

mcp_tools = MCPTools(
    transport="streamable-http",
    url="https://example.com/mcp",
)

Lifecycle важен: явные await connect() / await close(), async context manager или автоподключение в AgentOS. Опасная связка: reload=True в AgentOS вместе с MCP — ломает lifespan. Для обновления схемы tools смотрите refresh_connection=True.

Документация по MCP в Agno: обзор MCPTools.

MCP на Python в контуре агента

AgentOS умеет сам отдавать MCP наружу (mcp_server=True на /mcp) — тогда Cursor или Claude Desktop могут подключиться к вашему контуру как к MCP-серверу. Для маркетолога это значит: один раз собрали агентную логику — и ей могут пользоваться и бот в Telegram, и редактор с MCP.

Признак успеха: агент в логе реально вызывает tool с MCP-сервера (не только «придумывает» ответ). Если вызовов нет — проверьте connect, команду сервера и что tool попал в список агента.

От одного агента к команде: Team и Workflow

Когда хватает одного Agent

Одного агента достаточно, если задача одна и та же: ответить в чате, сделать короткий ресёрч, набросать пост. На старте так и делайте — проще отладить ключи, tools и Telegram.

Переходите к команде, когда появляется конвейер: «сначала факты → потом текст → потом проверка → потом превью».

Мультиагентная цепочка под контент

Маркер: простыми словами. Team — несколько агентов с ролями, которые решают задачу вместе. Workflow — явные шаги конвейера (шаг 1 → шаг 2 → шаг 3). В поиске это часто называют «мультиагентные системы»; не путайте с банковскими «субагентами».

Типовая цепочка для контента и лидов:

Research Agent — MCP/веб-tools → факты и тезисы.
Draft Agent — инструкции под тон бренда → черновик поста.
Critic (опционально) — проверка длины, оффера, запрещённых обещаний.
HITL — requires_confirmation или approval в AgentOS.
Telegram — превью вам в личку; правки ответом в чате.

Так вы закрываете интент «создание мультиагентной системы» практикой, а не теорией графов.

Вывод в Telegram: Interface, бот и webhook

Нативный Telegram Interface в Agno появился в линейке 2.5.x (весна 2026): агенты, команды и workflow принимают сообщения из Telegram, поддерживают мультимодальный вход и стриминг через правки сообщения.

Установка: pip install "agno[os,telegram]". Токен — у @BotFather. В production задайте TELEGRAM_WEBHOOK_SECRET_TOKEN. Локально обычно: APP_ENV=development + туннель (ngrok и аналоги) на POST /telegram/webhook.

Сессии вида tg:{entity}:{chat_id}. Команда /new для новой темы работает, если настроена база. Стриминг ограничивается лимитами Telegram (~1 правка сообщения в секунду). В группах по умолчанию бот отвечает на упоминания и реплаи. Длинные ответы режутся по 4096 символов.

Официальный разбор интерфейса: Telegram Interface в docs Agno.

Маркер: простыми словами. Telegram Interface — вход: Telegram шлёт апдейты на ваш webhook, AgentOS кормит ими агента. TelegramTools — выход: агент сам вызывает отправку сообщения/фото/документа. Для превью черновика в чат часто нужны оба паттерна. Interface ≠ Tools.

ИИ-агент для Telegram vs «нейросеть-бот с картинками»

В выдаче много запросов про «нейросеть бот в телеграм» — часто это генерация картинок или развлекательные чаты. Наш контур другой: агент с tools/MCP под задачи бизнеса (контент, лиды, превью постов), а не бот «нарисуй котика».

Если бот уехал в генерацию фото — сузьте инструкции, уберите лишние image-tools, явно пропишите цель: «только текст постов и ответы по лидам».

ChatGPT-бот в Telegram — чем наш контур другой

Простой «телеграм бот ChatGPT» = прокси к одной модели. Контур на Agno = модель + tools/MCP + (при необходимости) команда агентов + HITL + сессии в вашей БД. Подключить ChatGPT к боту можно за вечер; получить управляемый контент-конвейер — только если добавить инструменты, роли и контроль человека.

Контент и лиды: research → черновик → preview в Telegram

Схема, которую можно внедрить без n8n и без LangGraph:

Research Agent собирает факты (MCP filesystem/search или веб-toolkit).
Draft Agent пишет пост под канал.
Workflow отдаёт черновик в Telegram Interface — вы читаете превью.
Правите ответом в чате или подтверждаете tool с requires_confirmation.
Публикация: вручную, через Make/WordPress или отдельный шаг автопостинга — после одобрения.

Ориентир по времени на контент с ИИ в открытых обзорах рынка бывает сильным (ускорение подготовки постов в разы), но цифры зависят от ниши и процесса. Важнее механика: превью в Telegram снимает страх «агент сам всё выложил».

HITL перед публикацией

Включите подтверждение на опасных действиях: публикация, рассылка, изменение CRM. Агент готовит — человек жмёт «да». Для канала это обязательный слой, даже если кажется «долго».

Автопостинг после одобрения

Автопостинг в Telegram — отдельный коммерческий хвост. Agno даёт агента и канал связи; «выложить в канал по расписанию» обычно делают отдельным шагом (скрипт, Make, WordPress-плагин). В гайде честно разделяйте: preview (Agno + Telegram) и publish (ваш публикатор).

Чем Agno удобнее n8n и LangGraph на этой задаче

На сайте Kovcheg уже разбирались соседние стеки — здесь только выбор под задачу «Python-агент → MCP → Telegram».

Ось	Agno	LangGraph	n8n
Суть	Python SDK + свой runtime AgentOS	Граф состояний и checkpoint	Визуальный no-code оркестратор
Tools / MCP	Нативные MCPTools, AgentOS как MCP-сервер	Через адаптеры экосистемы	Ноды и интеграции
Telegram	Нативный Interface (webhook, стрим)	Свой слой бота	Telegram Trigger / ноды
Когда брать	Self-hosted контур на Python без сборки оркестратора с нуля	Сложный resumable graph	Нет желания писать Python

Если нужен визуальный сценарий без кода — n8n. Если нужен тяжёлый граф с долгими checkpoint — LangGraph. Если нужен быстрый путь «агент + MCP + Telegram на Python» — Agno попадает точнее.

Стартовая точка по продукту: документация Agno.

Ошибки первого запуска

Старые импорты Phidata

Симптом: ModuleNotFoundError: phi или странные имена toolkit без суффикса Tools. Лечение: пакет agno, импорты agno.*, toolkit ...Tools, параметр хранилища в v2 — db= (не storage=), ответ прогона — RunOutput (не RunResponse). Apps вроде старых Slack/AGUI-обёрток уступили место interfaces внутри AgentOS.

Ключи API и лимиты Telegram

Нет OPENAI_API_KEY / ключа провайдера → тишина или явная ошибка авторизации.
Нет TELEGRAM_TOKEN → Interface не поднимется.
В production без TELEGRAM_WEBHOOK_SECRET_TOKEN — риск чужих webhook-вызовов.
Стрим «мигает» редко — это лимит правок Telegram, не баг модели.
Privacy mode в BotFather: в группах бот может не видеть обычные сообщения без @mention.

Из России заранее проверьте, чем платите за API модели. Telegram-токен бесплатен.

Слишком много tools / MCP в одном агенте

Симптом: агент вызывает не тот tool, «забывает» задачу, раздувает счёт. Лечение: один агент — одна роль; MultiMCPTools только с нужными серверами; остальное — во втором агенте команды.

Ещё одна ловушка: reload=True + MCP в AgentOS. Не включайте hot-reload на MCP-контуре.

Чек-лист: агент готов к боевому контуру

import agno без ошибок, версия 2.8.x
Первый Agent отвечает в терминале без Telegram
Подключён минимум tools (или один MCP) и в логе видны реальные вызовы
Узкий набор tools, нет «склада на все случаи»
AgentOS поднят, Telegram webhook принимает апдейты
Превью черновика приходит в личку
HITL на публикации включён
Автопостинг отделён от превью и включается только после approve
Секреты не в git, webhook secret задан для production
Инструкции агента запрещают уход в Generative-фото вместо лидов/текста

Итог. Боевой контур — это не «бот ответил раз», а стабильный путь: задача → tools/MCP → превью в Telegram → человек → публикация.

FAQ

Чем Agno отличается от ChatGPT-бота в Telegram?

ChatGPT-бот — прокси к модели. Agno даёт агента с tools/MCP, команды агентов, AgentOS и нативный Telegram Interface с сессиями и HITL.

Нужен ли MCP сразу или хватит обычных tools?

Для первого запуска хватит @tool и одного toolkit. MCP подключайте, когда нужен стандартный доступ к файлам, git, документации или нескольким серверам без ручной обвязки каждого API.

Как собрать мультиагентную систему без «банковских субагентов» в голове?

Думайте ролями: research, draft, critic. Соберите Team или Workflow. «Субагент» в банковском смысле к ИИ-команде не относится.

Подойдёт ли Python-стек маркетологу без бэкенда?

Да, если готовы к копированию рабочих примеров и установке пакетов по инструкции. Сложность — не «написать фреймворк», а аккуратно пройти install → ключи → один Agent → Telegram. Если Python совсем не ваш формат, смотрите no-code (n8n/Make), но этот гайд заточен под Agno.

Как не увести бота в генерацию фото вместо лидов?

Уберите image-tools, пропишите в instructions цель (текст, лиды, превью постов), ограничьте MCP-серверы. Проверьте privacy mode и команды бота, чтобы в группах он не реагировал на весь оффтоп.

Что проверяли по источникам

Актуальный пакет и линейка Agno 2.8.x (PyPI / релизы).
Официальные docs: Agent, MCPTools, Telegram Interface, миграции Phidata→Agno и v1→v2.
Отличия от LangGraph / n8n / OpenAI Agents SDK — только по оси выбора стека.
Рыночный фон: спрос на бизнес-агентов и ускорение контент-процессов с ИИ в открытых публикациях.