ember-agent

Готовый к запуску агент на базе ember: настройка в TOML — запуск одной командой.

• CLI-команда: ember-agent (короткая, удобная в терминале)
• На PyPI пакет публикуется как: emberio-labs-ember-agent

$ ember-agent --version
ember-agent 0.2.0

Возможности

• Конфигурация в одном TOML-файле: системный промпт, провайдер LLM (ключ, модель, base_url), MCP-инструменты.
• Интерактивный диалог в терминале или разовый запрос (--message) для скриптов.
• Красивый вывод в интерактиве: баннер приветствия в рамке (версия, провайдер, модель, инструменты), диалог в виде чата (подпись 🤖 ember-agent, приглашение «Ваш ответ: »), markdown-рендер ответов, потоковая печать (где доступна), команды сессии /help и /reset, показ процесса вызова инструментов (🔧/✔/✖), Ctrl+C отменяет ответ.
• Провайдеры: mock (без сети и ключей, для экспериментов и тестов) и openai (OpenAI и любые OpenAI-совместимые API: OpenRouter, Groq, vLLM, LM Studio и т.п.).
• Модель задаётся провайдеру ([provider] model) — как часть «подключения к LLM».
• Инструменты по MCP: stdio-процессы и streamable HTTP-серверы.
• Работает на Python 3.12+.

Установка

Из PyPI:

pip install emberio-labs-ember-agent

Из исходников (Poetry):

git clone https://github.com/emberio-labs/ember-agent.git
cd ember-agent
poetry install

Настройка

Скопируйте пример конфигурации и отредактируйте под себя:

cp config.example.toml config.toml

Все секции конфигурации опциональны: пустой файл создаст агента на MockProvider, который работает без сети и API-ключей.

[agent]
system_prompt = "Ты полезный и краткий помощник."   # как агент себя ведёт

[provider]
type = "mock"                  # "mock" | "openai"
model = "gpt-4o-mini"          # модель подключения LLM (для type = "openai")
api_key_env = "OPENAI_API_KEY" # откуда брать ключ (для type = "openai")

[[mcp.servers]]                       # внешние инструменты (опционально)
transport = "stdio"                   # "stdio" | "http"
command = "python"
args = ["path/to/server.py"]

Полный пример с комментариями — в config.example.toml. Для реального провайдера задайте переменную окружения с ключом, например OPENAI_API_KEY. Если модель не указана, провайдер берёт свою по умолчанию (gpt-4o-mini у OpenAI).

Запуск

Интерактивный диалог:

ember-agent run

В начале сессии печатается баннер в рамке: версия, провайдер, модель и подключённые инструменты. Дальше идёт диалог в виде чата: ответы агента помечены подписью 🤖 ember-agent, свой ввод начинается по приглашению «Ваш ответ: ». Внутри диалога доступны команды:

• /help — справка по командам;
• /reset — начать новый диалог (сбросить историю);
• выход: exit, quit, выход, Ctrl+D, или Ctrl+C дважды.

Ответы рендерятся как markdown (заголовки, списки, код-блоки); там, где потоковая печать доступна (агент без инструментов), текст появляется по мере генерации. При вызове инструментов виден процесс: 🔧 имя(аргументы) и результат ✔ / ошибка ✖. Ctrl+C прерывает текущий ответ, не завершая сессию.

Разовый запрос — без диалога, удобно для скриптов:

ember-agent run -m "Привет! Коротко: кто ты?"

Явно указать файл конфигурации:

ember-agent run -c path/to/config.toml

Альтернативный запуск через Python (без установки в окружение):

python -m ember_agent run -m "Привет"

Разработка

poetry install                      # установка зависимостей (включая dev)
poetry run pytest                   # тесты
poetry run ruff check ember_agent tests   # линтер
poetry run mypy                     # статическая типизация

Код в ember_agent/, тесты — в tests/. Формат конфигурации описан в config.example.toml.

Релиз

Публикация новой версии на PyPI автоматизирована через GitHub Actions (workflow .github/workflows/publish.yml):

1. Поднимите версию в pyproject.toml (version = "0.2.0") и закоммитьте изменение, например: chore: bump version to 0.2.0.

2. Создайте и запушьте git-тег, совпадающий с версией:

   git tag v0.2.0
   git push origin v0.2.0
   

3. Workflow соберёт wheel и sdist (poetry build) и опубликует их на PyPI. Ветка main при этом не нужна — достаточно тега.

Публикация использует Trusted Publishing (OIDC): секреты в GitHub не хранятся. Для этого владельцу нужно один раз настроить publisher на PyPI (и, опционально, на TestPyPI для проверок):

• PyPI: https://pypi.org/manage/account/publishing/
• TestPyPI: https://test.pypi.org/manage/account/publishing/

Поля формы одинаковы для PyPI и TestPyPI:

После настройки публикацию можно проверить вручную на TestPyPI: GitHub → Actions → Publish → Run workflow. На боевой PyPI пакет уходит только по git-тегу v*.

Лицензия

MIT — см. LICENSE.