Сценарии API bota.chat: агент с профилем, каталог, копия

Во всех примерах:

BASE=https://framesuite.app/api/v1
KEY=user_XXXXXXXXXXXXXXXX
ASSISTANT=53

Сценарий: агент с экраном-профилем и страницей на сайте

Задача: агент в стиле кастомного GPT — с аватаром, автором, описанием и вариантами сообщений; в каталоге «Помощники» его карточка ведёт на страницу сайта /base/razbor-reziume/, где встроен чат. Всё, включая картинку и документы страницы на двух языках, уходит одним POST.

1. Подготовить файлы. avatar.png — аватар (png, jpeg, webp или gif до 5 МБ). page-en.md и page-ru.md — документы страницы агента для OnPress: frontmatter с lang: en и lang: ru, строка вставки чата , тело с H2 и FAQ. Формат и пример — Свойства config, раздел про page_markdown. slug агента задаём сами, чтобы вставка в документе ссылалась на него ещё до создания.

2. Создать агента одним запросом. Картинка — data URL, сервер сохранит её и вернёт в image свой адрес. Английская страница — в page_markdown, русская — в locales.ru.page_markdown. Категория должна быть среди вкладок приветственного экрана, тег — тот, по которому отбирает каталог.

python3 - <<'EOF' > agent.json
import base64, json
img = base64.b64encode(open("avatar.png", "rb").read()).decode()
print(json.dumps({
    "label": "Разбор резюме",
    "slug": "razbor-reziume",
    "action": "send",
    "display_type": "image-tile",
    "image": f"data:image/png;base64,{img}",
    "subtitle": "Найду слабые места в резюме и предложу правки",
    "prompt": "Ты карьерный консультант. Разбирай резюме пользователя по пунктам.",
    "prompt_target": "system",
    "categories": ["Производительность"],
    "tags": ["customgpt"],
    "profile_author": "Команда bota.chat",
    "profile_author_url": "https://bota.chat/",
    "page_url": "/base/razbor-reziume/",
    "page_markdown": open("page-en.md").read(),
    "prepared_suggestions": [
        {"text": "Проверь моё резюме"},
        {"text": "Как описать опыт без стажа?"},
        {"text": "Сделай резюме короче"},
        {"text": "Подбери ключевые навыки"}
    ],
    "locales": {
        "en": {
            "label": "CV review",
            "subtitle": "I will find weak spots in your CV and suggest fixes",
            "profile_author": "bota.chat team",
            "prepared_suggestions": [{"text": "Review my CV"}, {"text": "Make my CV shorter"}]
        },
        "ru": {"page_markdown": open("page-ru.md").read()}
    }
}, ensure_ascii=False))
EOF

AGENT=$(curl -s -X POST "$BASE/assistants/$ASSISTANT/agents" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  --data-binary @agent.json | jq -r .agent.id)

В ответе image — уже https://framesuite.app/storage/welcome-cards/….png. Если 422, ключ в errors покажет поле: image — картинка не прошла, profile_author_url — не http(s)-ссылка. Переводы можно добавить и позже: locales в PUT сливается с сохранёнными, языки добавляются по одному.

3. Опубликовать страницу на сайте. Документы из page_markdown и locales.ru.page_markdown публикуются на сайт как есть, методом POST /pages/markdown API сайта OnPress; русскую версию связывают с английской как перевод. Вставка onpress/assistant в документе встраивает на страницу чат ассистента, открытый профилем агента (см. Домены, Telegram, встраивание). Карточка каталога теперь ведёт на эту страницу: путь page_url достраивается от домена сайта, на котором открыт каталог, а на служебном адресе /f/… — от своего домена ассистента.

4. Ссылка на профиль в чате ассистента — на случай, когда страница не нужна:

echo "https://framesuite.app/f/x8OA7Azs4hBy?agent=razbor-reziume&agent_view=profile"

Если агент должен открываться профилем и по клику на приветственном экране, добавьте слаг экрана в profile_screens: {"profile_screens": ["LQmAMDZFO44o"]}. Остальной config при этом не изменится — он сливается по ключам.

Сценарий: настроить каталог «Помощники»

Задача: каталог со своими текстами на русском и английском, английскими подписями вкладок, без дублирующей категории и только с агентами тега customgpt.

1. Посмотреть, какие вкладки уже есть. Публичный метод отдаёт ровно то, что увидит посетитель.

curl -s "https://framesuite.app/f/x8OA7Azs4hBy/agents-catalog?locale=ru" \
  | jq '[.categories[] | {category, label}]'

Нужной категории нет — добавьте вкладку в секцию-переключатель приветственного экрана (её можно скрыть на витрине), см. Первые экраны.

2. Снять текущие тексты, чтобы видеть исходное состояние. agents_catalog сливается по ключам, поэтому присланное в шаге 3 не сотрёт остальные тексты; целиком заменяется только список hidden_categories.

curl -s "$BASE/assistants/$ASSISTANT/templates" -H "Authorization: Bearer $KEY" \
  | jq '.templates.agents_catalog' > catalog-before.json

3. Записать тексты, подписи вкладок и скрытые категории.

curl -s -X PUT "$BASE/assistants/$ASSISTANT/templates" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"agents_catalog": {
    "title": {"ru": "Помощники", "en": "Assistants"},
    "subtitle": {"ru": "Готовые помощники под конкретные задачи.", "en": "Ready-made assistants for specific tasks."},
    "sidebar_label": {"ru": "Помощники", "en": "Assistants"},
    "search_placeholder": {"ru": "Поиск помощников", "en": "Search assistants"},
    "categories": {"Изображения": {"en": "Images"}, "Образ жизни": {"en": "Lifestyle"}},
    "hidden_categories": ["Создайте изображения"]
  }}'

4. Пометить агентов тегом. Остальной config агента не трогается, но сам массив tags заменяется целиком — присылайте полный список тегов агента.

for ID in 3676 3678 3679; do
  curl -s -X PUT "$BASE/assistants/$ASSISTANT/agents/$ID" \
    -H "Authorization: Bearer $KEY" \
    -H "Content-Type: application/json" \
    -d '{"tags": ["customgpt"]}' > /dev/null
done

5. Сделать тег тегом каталога, чтобы пункт «Помощники» и голый ?lib=agents показывали только помеченных агентов:

curl -s -X PUT "$BASE/assistants/$ASSISTANT/templates" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"sidebar": {"agents_tag": "customgpt"}}'

Разовая ссылка с отбором работает и без этой настройки:

https://framesuite.app/f/x8OA7Azs4hBy?lib=agents&tag=customgpt

6. Включить пункт в боковой панели — "agents" в sidebar_pages через PUT /assistants/{assistantId}/features, см. Возможности, сайдбар и задержка.

Публичный метод кэширует ответ на 5 минут — изменения видны не сразу.

Сценарий: скопировать агента

Задача: сделать копию удачного агента — у этого же ассистента для эксперимента или у другого своего ассистента. Метода копирования в API нет (кнопка «Копировать» есть только в дашборде), агент переносится списком и созданием — повторяем то, что делает дашборд.

1. Снять агента и убрать служебные поля. source_id указывает на оригинал, root_id остаётся от оригинала — копии в аналитике схлопываются с ним.

SRC=3676
TARGET=$ASSISTANT
curl -s "$BASE/assistants/$ASSISTANT/agents" -H "Authorization: Bearer $KEY" \
| jq --argjson id $SRC '.agents[] | select(.id == $id)
    | .source_id = .id
    | del(.id, .slug, .order, .category, .cached_responses, .page_url)
    | .label = .label + " (копия)"' > copy.json

page_url убираем, как дашборд: два агента с одним адресом страницы на сайте не нужны. При копировании в другого ассистента уберите и frame_id, если он есть, а в profile_screens оставьте только слаги экранов нового ассистента: фрейм и приветственные экраны принадлежат исходному.

2. Создать копию.

NEW=$(curl -s -X POST "$BASE/assistants/$TARGET/agents" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  --data-binary @copy.json | jq -r .agent.id)

Копия встаёт в конец списка, slug собирается из нового названия, кэш ответов пустой.

3. Перенести файлы базы знаний, если они нужны: скачать их через API нельзя, загрузите исходные файлы заново в POST /agents/$NEW/knowledge.

Дальше

Агенты — объект агента и все методы.
Экран-профиль и ссылки — параметры ссылок на агента.
Каталог «Помощники» — как каталог собирает вкладки и карточки.