НадTavern (AgentUI): объясняем просто

Это инструмент, который помогает слать запросы к ИИ (OpenAI, Gemini, Claude) через простой конвейер из блоков (узлов). Вы кликаете мышкой, соединяете блоки — и получаете ответ в том же формате, в каком спрашивали.

Коротко: было сложно — стало просто.

Что вы можете сделать

Принять запрос от клиента как есть (OpenAI/Gemini/Claude).
При желании подменить его или дополнить.
Отправить к нужному провайдеру (или прямо «пробросить» как есть).
Склеить финальный ответ в том формате, который ждёт клиент.

Как это работает в 5 шагов

Клиент шлёт HTTP‑запрос на ваш сервер.
Сервер понимает формат (OpenAI/Gemini/Claude) и делает «унифицированный» вид.
Загружается ваш пайплайн (схема из узлов) из файла pipeline.json.
Узлы запускаются по очереди «волнами» и обмениваются результатами.
Последний узел отдаёт ответ клиенту в нужном формате.

Если страшно — не бойтесь: всё это уже настроено из коробки.

Быстрый старт

Вариант A (Windows, авто‑настройка .venv):

Запустите run_agentui.bat двойным кликом или из консоли.
Скрипт сам:
- создаст локальное окружение .venv в каталоге проекта;
- обновит pip;
- установит зависимости из requirements.txt;
- поднимет сервер и откроет редактор в браузере.
Переменные окружения (опционально перед запуском): HOST=127.0.0.1 PORT=7860

Вариант B (Linux/macOS, авто‑настройка .venv):

Сделайте исполняемым и запустите:
- chmod +x run_agentui.sh
- ./run_agentui.sh
Скрипт сделает то же самое: .venv + установка зависимостей + старт сервера.

Вариант C (ручной запуск, если хотите контролировать шаги):

Установите Python 3.10+.
Создайте и активируйте .venv:
- Windows (cmd): py -m venv .venv && ..venv\Scripts\activate
- Linux/macOS (bash): python3 -m venv .venv && source .venv/bin/activate
Установите зависимости и стартуйте сервер:
- pip install -r requirements.txt
- python -m uvicorn agentui.api.server:app --host 127.0.0.1 --port 7860

Откройте в браузере:

http://127.0.0.1:7860/ui/editor.html — визуальный редактор узлов
http://127.0.0.1:7860/ui/pipeline.html — редактор «сырых» JSON настроек пайплайна
http://127.0.0.1:7860/ — простая страница с примером запроса

Где лежат важные файлы

API сервер: agentui/api/server.py
Исполнитель узлов: agentui/pipeline/executor.py
Шаблоны и макросы: agentui/pipeline/templating.py
Определение провайдера (OpenAI/Gemini/Claude): agentui/common/vendors.py
Активный пайплайн: pipeline.json
Пресеты (готовые пайплайны): папка presets
Визуальный редактор (страница): static/editor.html
Логика сериализации/соединений: static/js/serialization.js
Настройка Prompt Manager UI: static/js/pm-ui.js
Справка по переменным: docs/VARIABLES.md

Что такое «узлы»

Представьте конструктор Лего. Узел — это кубик. Соединяете кубики — получаете конвейер (пайплайн). В проекте есть 4 базовых узла:

SetVars — завести свои переменные.
- Пример: MY_KEY, REGION, MAX_TOKENS.
- Потом в шаблонах вы можете писать MY_KEY или {{ MAX_TOKENS }}.
RawForward — «пробросить» входящий запрос как есть дальше (reverse‑proxy).
- Полезно, когда вы не хотите ничего менять.
ProviderCall — аккуратно собрать JSON для провайдера (OpenAI/Gemini/Claude) из «кусочков текста» (Prompt Blocks) и отправить.
- Это удобно, если вы хотите дописать системное сообщение, переписать текст пользователя и т.п.
Return — оформить финальный ответ под тот формат, который ждёт клиент.
- Если клиент прислал в стиле OpenAI, вернём в стиле OpenAI; можно принудительно выбрать формат.

Узлы соединяются линиями «из выхода в вход». Так вы задаёте порядок.

Простые «заклинания» (макросы), которые работают в шаблонах

VAR:путь — взять значение из входящего запроса.
- Например: VAR:incoming.headers.authorization
OUT:n1.что‑то — взять кусочек результата из узла n1.
OUT1 — взять «самый понятный текст» из узла n1 (короткая форма).
PROMPT — умный фрагмент JSON, который автоматически соберётся из ваших Prompt Blocks для выбранного провайдера.
{{ путь }} — вставка без кавычек (подходит для чисел/массивов/объектов).
{{ путь|default(значение) }} — вставка с безопасным дефолтом.

Пример 1 (OpenAI, фрагмент шаблона тела запроса): { "model": "{{ model }}", PROMPT, "temperature": {{ incoming.json.temperature|default(0.7) }} }

Пример 2 (вставим токен из заголовка в заголовки запроса): {"Authorization":"Bearer VAR:incoming.headers.authorization"}

Подробная шпаргалка — в файле docs/VARIABLES.md.

Первый рабочий пайплайн за 3 минуты

Цель: взять сообщение пользователя, немного «пригладить» его и вернуть ответ в стиле OpenAI.

Добавьте узел SetVars (можно пропустить).
Добавьте узел ProviderCall.
- В инспекторе выберите провайдера (например, openai).
- В Prompt Blocks создайте блоки:
  - system: «Ты — помощник. Отвечай коротко.»
  - user: «VAR:chat.last_user — перепиши текст красивее.»
- В шаблоне тела (template) не трогайте структуру — там уже есть PROMPT.
Добавьте узел Return.
- Оставьте «auto», чтобы формат ответа совпал с входящим.
Соедините ProviderCall → Return.
Нажмите «Сохранить пайплайн».
Отправьте запрос на POST /v1/chat/completions (можно со страницы /).

Если что‑то не работает — смотрите журнал (консоль) и всплывающие подсказки в UI.

Полезные адреса (админка)

GET /admin/pipeline — получить текущий пайплайн.
POST /admin/pipeline — сохранить пайплайн.
GET /admin/presets — список пресетов.
GET/POST /admin/presets/{name} — загрузить/сохранить пресет.
GET /admin/trace/stream — «живой» поток событий исполнения. Редактор подсвечивает узлы (начал/успешно/ошибка).

Это уже настроено в agentui/api/server.py.

Где смотреть логи

Сервер пишет в консоль шаги узлов и ответы провайдеров.
В UI редакторе видно подсветку состояний узлов (события из /admin/trace/stream).
При необходимости включите/отключите подробность логов в коде узлов agentui/pipeline/executor.py.

Важная безопасность (прочитайте!)

Никогда не храните реальные ключи в файлах в репозитории (pipeline.json, пресеты).
Передавайте ключи через заголовки запроса клиента:
- OpenAI: Authorization: Bearer XXXXXX
- Anthropic: x-api-key: XXXXXX
- Gemini: ?key=XXXXXX в URL
В шаблонах используйте подстановки из входящего запроса: VAR:incoming.headers.authorization, VAR:incoming.headers.x-api-key, VAR:incoming.api_keys.key.
В логах при разработке печатаются заголовки и тело. Для продакшена выключайте или маскируйте их.

Частые ошибки и быстрые решения

«Соединения между узлами пропадают»
- Нажмите «Загрузить пайплайн» ещё раз: редактор терпеливо дождётся DOM и восстановит линии.
«Шаблон JSON ругается на запятые/скобки»
- Убедитесь, что PROMPT стоит без лишних запятых вокруг; числа/массивы вставляйте через {{ ... }}.
«Нет ответа от провайдера»
- Проверьте ключ и URL/endpoint в конфигурации узла ProviderCall (инспектор справа).
«Нужен просто прокси без изменений»
- Используйте узел RawForward первым, а потом Return.

Для любопытных (необязательно)

Код устроен так:

Сервер создаётся здесь: agentui/api/server.py
Исполнение узлов и «волны» — здесь: PipelineExecutor.run()
Провайдерный вызов и Prompt Blocks — здесь: ProviderCallNode.run()
Простой шаблонизатор (две скобки): render_template_simple()

Этого достаточно, чтобы понимать, куда заглянуть, если захотите кое‑что подкрутить.

Удачи! Запускайте редактор, соединяйте узлы и получайте ответы без боли.

12 KiB Raw Permalink Blame History Unescape Escape

НадTavern (AgentUI): объясняем просто

12 KiB

Raw Permalink Blame History