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

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

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

---

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

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

---

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

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

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

---

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

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

Вариант B (Linux/macOS, авто‑настройка .venv):
- Сделайте исполняемым и запустите:
  - chmod +x [run_agentui.sh](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](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/api/server.py)
- Исполнитель узлов: [`agentui/pipeline/executor.py`](agentui/pipeline/executor.py)
- Шаблоны и макросы: [`agentui/pipeline/templating.py`](agentui/pipeline/templating.py)
- Определение провайдера (OpenAI/Gemini/Claude): [`agentui/common/vendors.py`](agentui/common/vendors.py)
- Активный пайплайн: [`pipeline.json`](pipeline.json)
- Пресеты (готовые пайплайны): папка [`presets`](presets/)
- Визуальный редактор (страница): [`static/editor.html`](static/editor.html)
- Логика сериализации/соединений: [`static/js/serialization.js`](static/js/serialization.js)
- Настройка Prompt Manager UI: [`static/js/pm-ui.js`](static/js/pm-ui.js)
- Справка по переменным: [`docs/VARIABLES.md`](docs/VARIABLES.md)

---

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

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

1) SetVars — завести свои переменные.
   - Пример: MY_KEY, REGION, MAX_TOKENS.
   - Потом в шаблонах вы можете писать [[MY_KEY]] или {{ MAX_TOKENS }}.

2) RawForward — «пробросить» входящий запрос как есть дальше (reverse‑proxy).
   - Полезно, когда вы не хотите ничего менять.

3) ProviderCall — аккуратно собрать JSON для провайдера (OpenAI/Gemini/Claude) из «кусочков текста» (Prompt Blocks) и отправить.
   - Это удобно, если вы хотите дописать системное сообщение, переписать текст пользователя и т.п.

4) 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`](docs/VARIABLES.md).

---

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

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

1) Добавьте узел SetVars (можно пропустить).
2) Добавьте узел ProviderCall.
   - В инспекторе выберите провайдера (например, openai).
   - В Prompt Blocks создайте блоки:
     - system: «Ты — помощник. Отвечай коротко.»
     - user: «[[VAR:chat.last_user]] — перепиши текст красивее.»
   - В шаблоне тела (template) не трогайте структуру — там уже есть [[PROMPT]].
3) Добавьте узел Return.
   - Оставьте «auto», чтобы формат ответа совпал с входящим.
4) Соедините ProviderCall → Return.
5) Нажмите «Сохранить пайплайн».
6) Отправьте запрос на 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`](agentui/api/server.py).

---

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

- Сервер пишет в консоль шаги узлов и ответы провайдеров.
- В UI редакторе видно подсветку состояний узлов (события из /admin/trace/stream).
- При необходимости включите/отключите подробность логов в коде узлов [`agentui/pipeline/executor.py`](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`](agentui/api/server.py)
- Исполнение узлов и «волны» — здесь: [`PipelineExecutor.run()`](agentui/pipeline/executor.py:136)
- Провайдерный вызов и Prompt Blocks — здесь: [`ProviderCallNode.run()`](agentui/pipeline/executor.py:650)
- Простой шаблонизатор (две скобки): [`render_template_simple()`](agentui/pipeline/templating.py:187)

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

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