API агента
Агент сохраняет диалог, планирует вызовы моделей и возвращает текст или медиа, используя существующий баланс. Подготовка, анализ вложений, сжатие контекста и извлечение JSON оплачиваются по обычным тарифам моделей. Отдельной наценки за агента нет. Доступность новых запусков зависит от витрины. Выключение новых запусков сохраняет доступ к существующей истории, скачиванию, остановке и завершению начатой работы.
Все пути ниже имеют префикс /api/v1. Используйте API-ключ или сессию
витрины, как описано в аутентификации. Пользователя и
витрину определяет сервер.
Выбор моделей
GET /agent/models возвращает публичный каталог, цены и проверенные
возможности маршрутов. Основная модель по умолчанию — gpt-6.1-sol.
Она используется для ответов, анализа изображений и JSON, если маршрут
поддерживает операцию. Для анализа изображений и JSON чат может предложить
другую модель и запросить согласие до её запуска. Вызов инструментов всегда
пробуется на выбранной LLM. Проверенный маршрут Responses
для Sol/grsai поддерживает ответы, извлечение JSON и оркестрацию, включая
нативные вызовы инструментов и продолжение диалога. У Gemini 3.8 Flash также
есть проверенные маршруты с инструментами. Название модели само по себе
не подтверждает её возможности.
GET /agent/settings возвращает настройки и их version. Для изменения
вызовите PUT /agent/settings:
{
"expectedVersion": 0,
"settings": {
"orchestratorModelId": "gpt-6.1-sol",
"fallbackModelIds": ["claude-sonnet-5-5"],
"imageModelId": "gpt-image-2",
"videoModelId": "veo3.1-fast",
"musicModelId": "suno",
"routingPolicy": "balanced",
"defaultMaxCostMicroUsd": "2000000"
}
}Доступны политики economy, balanced и quality. Смена публичной модели
при ручном выборе результата требует согласия, если дополнительные модели
не разрешены. Резерв используется после подтверждённой ошибки с освобождённым
денежным резервом. Неизвестный результат запроса сначала проходит сверку.
Если результат не подтверждён к окончанию сверки, денежный резерв освобождается
и агент пробует совместимого резервного провайдера той же модели, если он есть.
Публичный LLM API использует те же правила. До начала ответа прерванный вызов может дождаться сверки и перейти к резерву в пределах времени запроса. Закрытие соединения запрещает дальнейшие попытки. Прерванный SSE-поток не перезапускается через другого провайдера: расходы проходят сверку, а денежный резерв без подтверждённого результата освобождается. Настройки фиксируются при приёме запуска; последующие изменения действуют на новые запуски.
imageModelId, videoModelId и musicModelId — предпочтительные модели
генерации. Явный запрос в чате имеет приоритет. Если модель не подходит,
например по количеству референсов, агент может выбрать другую и объяснить
причину. Предпочтения проекта важнее пользовательских значений по умолчанию.
Эти настройки не закрепляют модель результата и не требуют подтверждения
для выбора совместимой альтернативы.
Диалог и запуск
Создайте диалог через POST /agent/conversations. Можно передать title,
projectId, profileId, defaultWorkflowId и settings. Для ручного выбора
модели результата укажите mode: "manual" и selectedModelId.
Ручной выбор LLM сохраняет агентские инструменты, включая генерацию медиа;
он не закрепляет модель изображения, видео или музыки. Агент всегда пробует
выбранную LLM с нативными инструментами, даже если проверки отсутствуют или
раньше завершались неудачей. Предупреждения о доступности и совместимости
информационные: они не приостанавливают запуск и не требуют смены модели.
Резервную LLM тоже можно выбрать без предварительной проверки инструментов;
она запускается после фактического сбоя и сверки расходов предыдущего вызова.
Получите диалоги через GET /agent/conversations в порядке последней
активности. Параметр q ищет по названиям и тексту сообщений, cursor
загружает следующую страницу. Для переименования используйте
PATCH /agent/conversations/{conversationId} (title, expectedVersion).
Для удаления — DELETE /agent/conversations/{conversationId}; активные
запуски будут остановлены. В автоматическом режиме агент даёт диалогу без
названия короткое имя по смыслу задачи.
Отправьте задачу в POST /agent/conversations/{conversationId}/messages:
{
"clientMessageId": "my-task-001",
"content": [{"type": "text", "text": "Создай квадратное изображение товара"}],
"maxCostMicroUsd": "2000000"
}Ответ содержит conversationId, messageId, runId и status. При повторе
сохраняйте clientMessageId и тело: тот же ключ с другими данными вызывает
конфликт. В диалоге допускается один активный запуск.
Пока запуск работает, deliveryMode: "followup" ставит отдельный следующий
запрос в очередь с собственным лимитом. Могут ожидать до 20 запросов;
они выполняются по порядку и видят предыдущие ответы. Если представление
запуска возвращает canSteer: true, режим deliveryMode: "steer" добавляет
текст текущему автоматическому запуску на следующей границе шага. Сохраняйте
его maxCostMicroUsd: этот режим не меняет модель, файлы, workflow или
схему финального результата.
Денежные поля MicroUsd — строки с целым количеством миллионных долей USD:
1000000 означает один USD. Лимит запуска включает списания и обязательства
по начатым операциям. Он отличается от доступного баланса. Подписка хранения
имеет отдельный явный процесс котировки и оплаты.
GET /agent/runs/{runId} возвращает шаги, расходы и ожидаемые решения.
Подключитесь к GET /agent/conversations/{conversationId}/events для SSE.
При восстановлении передавайте последнюю последовательность в
Last-Event-ID. Для JSON используйте
GET /agent/conversations/{conversationId}/event-history?afterSequence=0.
События упорядочены в пределах диалога.
Ответы, остановка и продолжение
Запуск может ожидать уточнение, согласие на модель, бюджет или завершение
медиа. Ответ на уточнение отправляется в тот же messages endpoint с
replyToRunId и текущим questionId. Сохраняйте maxCostMicroUsd запуска.
Для решения о смене модели вызовите POST /agent/runs/{runId}/decisions
с заголовком Idempotency-Key, полученными pendingActionId, version,
proposalHash и input: {"accept": true}. Устаревшее или истёкшее решение
не разрешает новую операцию.
input: {"accept": false} отклоняет предложенную модель, снимает ожидание
решения и продолжает запуск с сохранением выбранной модели. Если она может
выполнить операцию, работа продолжается на ней. При отказе от замены для
оркестрации агент пробует нативные инструменты выбранной LLM, даже после
сбоев или известных ограничений инструментов. Для других операций, например
анализа изображений и извлечения данных, по-прежнему нужен совместимый
маршрут; иначе возможен model_capability_unavailable. Отклонённая модель
не вызывается. Отказ от замены не отменяет запрос.
POST /agent/runs/{runId}/stop запрещает зависимые действия и запрашивает
прерывание активного HTTP-запроса к LLM. Уже принятая провайдером операция
может завершиться и оплачиваться. Неизвестный исход остаётся на сверке:
остановка сама по себе не означает возврат или повторный платный запрос.
Для запуска, который можно продолжить, измените общий лимит через
PATCH /agent/runs/{runId}/budget, передав maxCostMicroUsd и текущую версию
бюджета как expectedVersion. Затем вызовите
POST /agent/runs/{runId}/resume. Завершённые шаги используются повторно.
Вложения и прошлый контекст
Создайте загрузку вложения через
POST /agent/conversations/{conversationId}/attachments с name, mime
и sizeBytes. Отправьте исходные байты методом PUT на полученный uploadUrl,
не передавая API-ключ платформы. Завершите загрузку вызовом
POST /agent/attachments/{attachmentId}/complete. Сервер проверяет размер,
фактический тип, декодирование изображения и создаёт неизменяемый оригинал.
Сообщение может содержать до десяти файлов, каждый не более 25 MiB:
{
"type": "attachment",
"attachmentId": "attachment-uuid",
"usageIntent": "analyze"
}Для редактирования по маске приложите исходное фото и PNG-маску в одном
сообщении. В блок маски добавьте
"maskFor": {"type": "attachment", "id": "original-uuid"};
для готовой генерации используйте тип "artifact". Белое обозначает
область изменения, чёрное — область сохранения. В просмотрщике референса
есть кисть, ластик, отмена штрихов и масштабирование. Маска занимает один
из десяти слотов файлов. Платформа отправляет оригинал и маску вместе
с инструкцией редактирования; модель должна принимать несколько фото.
Допустимы роли auto, analyze, reference, both. Локальное извлечение
текста бесплатно; модельный анализ входит в бюджет запуска. Неподдерживаемая
модальность возвращает явную ошибку. Референс не требует платного анализа
сам по себе. Референсы диалога истекают через трое суток после завершения
загрузки, незавершённые загрузки — через 24 часа. Чтение и использование
референса не продлевает срок. Минутная задача удаляет файлы и повторяет
попытки при сбоях хранилища; S3 lifecycle дополнительно очищает временные
объекты. Файлы проекта и сохранённые платные копии живут по правилам подписки,
без трёхдневного ограничения по возрасту. Новые файлы агента находятся
в публичном хранилище: любой обладатель прямой ссылки может прочитать файл
до физического удаления. API по-прежнему проверяет владельца и разрешения.
Подключите прошлые диалоги, запуски или артефакты через
PUT /agent/conversations/{conversationId}/context-references с
expectedVersion и references: каждый содержит targetType и targetId.
Для диалога допустим ID или URL текущей витрины. URL разбирается локально,
без HTTP-запроса. Пустой список отзывает доступ. Поиск использует локальный
полнотекстовый индекс, а чтение возвращает ограниченные фрагменты.
Рекурсивные ссылки не расширяют доступ. Запуск фиксирует границу источника:
новые сообщения не меняют уже принятый контекст.
Проекты и сценарии
GET и POST /agent/projects возвращают и создают проекты бренда.
Проект содержит инструкции, настройки бренда, модели и неизменяемые версии.
PATCH /agent/projects/{projectId} требует expectedVersion; изменения
не переписывают активные запуски. Файлам проекта нужен активный пакет хранения.
Импортируйте доступный результат через
POST /agent/projects/{projectId}/assets/import с artifactId, ролью role
и Idempotency-Key. Операция создаёт независимую копию и возвращает ID
для проверки статуса. Удаление исходного диалога не удаляет такую копию;
модерационный отзыв исходника по-прежнему закрывает доступ.
GET /agent/profiles возвращает профили. GET /agent/workflows — готовые
версионированные сценарии: карточка товара, сценарий и видео, обложка и музыка.
GET /agent/workflows/{workflowId} возвращает входную схему и граф шагов.
Передавайте workflowId, workflowVersion, workflowInput в сообщении.
Завершённые узлы не запускаются повторно после рестарта. Недостающие данные
вызывают уточнение до платной операции.
GET /agent/artifacts поддерживает фильтры kind, conversationId, runId,
modelId, query, status и пагинацию cursor/limit. Cursor привязан к
пользователю, витрине и фильтрам. Пустая страница с nextCursor допускает
продолжение после отзыва результатов. Повторное использование передаёт
type: "artifact", artifactId и конкретную version без новой загрузки.
GET /agent/artifacts/{artifactId} возвращает исходные generationId и
outputIndex доступного результата владельца на текущей витрине.
GET /generation/{generationId} возвращает промпт, разрешение, остальные
параметры запроса и сведения о генерации. Если исходной генерации нет,
generationId равен null.
Навыки и подзадачи
В режиме Auto агент может применять встроенные навыки: рекламный визуал, редактирование изображения, видеораскадровка и планирование кампании. Инструкции загружаются при необходимости; версия навыка закрепляется в запуске и отображается в истории действий.
Для составной задачи агент может отдельно подготовить рекламный текст и визуальную концепцию. Допускаются две подзадачи на запрос, каждая с лимитом до трети бюджета и сроком до 60 секунд. Они используют текущую модель оркестратора, получают только подготовленный контекст и возвращают текст. Медиа создаёт основной агент. Расходы подзадач входят в общий лимит запроса; остановка запроса распространяется на них. Для обычной генерации одного изображения делегирование не требуется.
Проверенный JSON
Укажите закрытую outputSchema и structuredOutputMode: "auto" либо
"extract". Поддерживаемое подмножество JSON Schema запрещает внешние ссылки,
открытые свойства и чрезмерную глубину. Некорректная схема отклоняется до
списаний.
В режиме auto известные поля платформы могут заполняться без модели;
иначе используется отдельный оплачиваемый проход. extract всегда использует
модель извлечения. После ошибки допускается один оплачиваемый repair в том же
бюджете. Пауза извлечения продолжает финализацию, не повторяя генерацию медиа.
GET /agent/runs/{runId}/result возвращает mainOutcome, revision, артефакты
и structuredResult. Значение value есть только при успешной валидации.
Ошибка извлечения сохраняет основные результаты и их списания. В ответе есть
хеш схемы, исходные шаги, completion извлечения и его стоимость. Просмотр
или скачивание не создаёт нового вызова модели.
Хранение и вебхуки
GET /agent/storage/plans возвращает текущие месячные пакеты. Получите
котировку через POST /agent/storage/quote, затем явно примите её через
POST /agent/storage/subscribe с ID, версией квоты, выбором автопродления
и Idempotency-Key. Котировка показывает сумму, баланс после оплаты и период.
При улучшении плана списывается только разница цен за оставшуюся часть
оплаченного периода. Прошедшее время остаётся по старой цене, дата списания
не меняется. При следующем продлении списывается месячная цена нового плана.
Продление списывает общий баланс только при включённом автопродлении.
Отмена продления сохраняет доступ к файлам и оплаченному объёму до конца периода.
После окончания оплаченного периода при отказе оплаты или отмене продления
даётся 72 часа на оплату либо выгрузку. Сохранение новых файлов и модельное
чтение архива приостановлены. После grace файлы удаляются.
POST /agent/storage/retain запускает идемпотентное копирование доступного
источника в платное хранилище. Проверяйте
GET /agent/storage/operations/{operationId}: HTTP 202 означает приём задачи,
а не готовую копию. GET /agent/storage/files возвращает файлы с пагинацией.
Удаление освобождает квоту и не создаёт дополнительного списания.
Создайте lifecycle webhook через POST /agent/webhooks с HTTPS url,
eventTypes и scope пользователя, проекта или диалога. Сохраните секрет
подписи из ответа: он показывается один раз. Повторы доставки сохраняют ID
события. Отозвать получателя можно через
DELETE /agent/webhooks/{webhookId}.
TypeScript-клиент экспортирует verifyAgentWebhook для проверки HMAC по
исходным байтам и допустимого времени подписи. Получатель должен устранять
дубликаты проверенных ID. Приватные адреса и DNS rebinding блокируются.