Перейти к основному содержанию
agno — Python-фреймворк для агентов: одна сущность Agent получает модель, инструкции и инструменты и сама решает, что вызвать. На SpeShu.AI его ставят, когда нужен агент с собственной логикой — цикл вызовов инструментов, память диалога, база знаний — над моделями, выбираемыми из одного каталога и оплачиваемыми в рублях.
Настраиваются ровно две вещи: base_url = "https://speshu.ai/api/v1" и API-ключ. agno говорит с провайдерами через класс OpenAILike — это штатный путь для любого OpenAI-совместимого эндпоинта, и под SpeShu.AI менять в нём ничего, кроме адреса и ключа, не нужно.
Python

Установка

Пакет openai обязателен: OpenAILike работает поверх официального клиента, а не через собственный HTTP-стек. Требуется Python 3.10 или новее.

Настройка

Сначала получите ключ и проверьте его — запрос баланса бесплатный:
cURL
Затем возьмите идентификатор модели из каталога. Не зашивайте его в код: состав каталога меняется, модели уходят и переименовываются, и зашитый идентификатор начинает падать с 404 model_not_found без предупреждения.
cURL
Значение id подставляется в id= ровно как есть — с двоеточиями и слэшами, если они есть в названии. Разбор ответа — в Каталоге моделей. Дальше — весь код приложения. Модель создаётся один раз и переиспользуется всеми агентами:
Python
Параметры OpenAILike — id, name, api_key, base_url; остальное наследуется от OpenAIChat, поэтому доступны temperature, top_p, frequency_penalty, max_completion_tokens, timeout, default_headers, extra_body. Эта сигнатура соответствует ветке agno 2.x; в более старых версиях класс назывался иначе, но путь «класс OpenAI-совместимой модели с base_url» остаётся тем же.
agno по умолчанию считает провайдером OpenAI и требует переменную OPENAI_API_KEY, даже когда модель подключена явно. Если агент без причины просит ключ OpenAI — вы задали base_url не для всех компонентов: проверьте модель агента, эмбеддер и модель структурированного вывода. Все три задаются явно.

Первый рабочий агент

Python
Инструменты в agno — обычные функции Python: имя, аннотации и docstring. Схему вызова модель выводит сама, поэтому текст после трёх кавычек пишется для модели, а не для человека.

Что дальше настраивается

Потоковая передача

Python
agno сам разбирает SSE-кадры и печатает delta по мере прихода. Формат кадра, кадр со списанием и поведение при обрыве разобраны в гайде Потоковая передача.
Разрыв соединения не отменяет генерацию — она доходит до конца и оплачивается. Подробности в том же гайде.

Вызов функций

Цикл вызовов agno выполняет сам: модель возвращает tool_calls, фреймворк вызывает ваши функции и отправляет результат обратно. Вам остаётся написать функции и не бросать из них исключение наружу. Полный цикл, схемы и tool_choice — в гайде Вызов функций. Стоит ограничить число шагов: без ограничения модель может зациклиться на неудачном инструменте и съесть бюджет.

Структурированный вывод

Python
Параметр response_model= (pydantic-модель в качестве результата) актуален для agno 2.x. Ветка 1.x использовала parse_response=True вместе с response_model. Проверьте версию в вашем окружении: на контракт ответа SpeShu.AI это не влияет — разбор JSON Schema — в гайде по структурированному выводу.

Генерация медиа из агента

Генерация изображений, видео, аудио и музыки не идёт через chat-эндпоинт, поэтому agno её не покрывает. Оформите её обычным инструментом — агент вызовет его так же, как погоду:
Python
Идентификаторы медиа-моделей — литералы: каталог GET /api/v1/media/models публичный и стабильный, в отличие от текстовых. Деньги списываются при создании задачи, а не при успехе. Полный контракт — в Создании задачи, статусы — в Статусе задачи.

База знаний и эмбеддинги

В API SpeShu.AI нет эндпоинта /embeddings. Любая knowledge-конструкция agno (Knowledge, AgentKnowledge, векторная база) требует эмбеддера, и провайдер эмбеддингов по умолчанию OpenAIEmbedder agno пойдёт именно сюда и получит 404. Два честных варианта:Вариант A — эмбеддинги у стороннего провайдера. Задайте эмбеддер явно и укажите ему чужой base_url и чужой ключ. Генерация при этом остаётся на SpeShu.AI.Вариант B — без эмбеддингов. Оставьте агенту только инструменты: поиск по вашей БД, файловое хранилище, HTTP-вызовы к внутренним сервисам. Часто этого достаточно, и схема не усложняется.Вариант A выглядит так — переменные окружения здесь отдельные:
Python
Идентификаторы текстовых моделей по-прежнему берите из GET /api/v1/models, а не задавайте константой.

Типичные проблемы

Проверьте адрес: должно быть ровно https://speshu.ai/api/v1 — с /v1 и без слэша на конце. Вариант без /v1 отдаст 404 на любом маршруте, вариант со слэшем на конце — тоже. Второе, что стоит проверить: ключ передан в api_key полностью, с префиксом sk-.
Ключ не дошёл до запроса. Проверьте, что переменная SPESHU_API_KEY не пуста и что вы не забыли api_key= в конструкторе OpenAILike. Подробности — в разделе Аутентификация.
Идентификатор устарел или скопирован с ошибкой. Возьмите id заново из GET /api/v1/models и подставьте как есть. Список в коде устаревает молча — список в конфиге тоже.
agno по умолчанию работает с OpenAI, поэтому лишний запрос ключа означает, что base_url задан не для всех компонентов: модели агента, эмбеддера базы знаний и модели структурированного вывода. Второй симптом — инструменты не вызываются: у функции нет docstring либо он слишком общий, а текст после трёх кавычек и есть инструкция для вызова. Отдельно проверьте, что выбранная модель вообще поддерживает вызов функций.
Клиентский таймаут короче серверного. Для потока ставьте 900–1000 секунд: сервер отдаёт поток до 15 минут, обычный запрос — до 300. Таблица потолков — в разделе Лимиты. Все коды и три формата ошибок — на странице Ошибки.

Что дальше

Вызов функций

Как модель вызывает код вашей стороны

Потоковая передача

SSE, [DONE] и кадр со списанием

Структурированный вывод

JSON Schema и валидация результата

Создание медиа-задачи

Генерация изображений, видео и аудио

Учёт средств

Как читать usage.cost.total_cost

Модели и цены

Каталог и выбор модели под задачу