Описание статьи: AI Chat v2 сохраняет простой способ вызова исходного диалогового интерфейса, одновременно добавляя мультимодальный ввод, структурированный поток событий, автоматический вызов инструментов, приостановку и возобновление, асинхронное выполнение и управление сессиями. Эта статья начинается с миграции, которая почти не требует переписывания кода, и объясняет, как эти изменения влияют на реальную разработку продуктов.
Многие чат-интерфейсы очень удобны на этапе демонстрации: передаёшь вопрос, ждёшь, пока модель вернёт текст, а затем показываешь его на странице.
По мере развития продукта всё уже не сводится к «одному вопросу — одному ответу». Пользователи загружают PDF и скриншоты, модели нужно искать веб-страницы, читать файлы и даже вызывать уже авторизованные инструменты GitHub, Notion и другие. Одна задача может продолжаться несколько раундов и по пути останавливаться, чтобы уточнить недостающую информацию. В этот момент, если интерфейс по-прежнему возвращает лишь одну постоянно растущую строку текста, фронтенду трудно понять, что делает модель, а бэкенду — определить, действительно ли задача завершена.
Именно эту проблему решает API Ace Data Cloud AI Chat v2. Он не отменяет исходный способ ведения диалога, а на основе совместимости с простыми вызовами разбивает один ответ на события, которые программа может распознавать и обрабатывать: основной текст остаётся основным текстом, вызовы инструментов — вызовами инструментов, а цитаты, файлы, ошибки и финальный статус имеют свои чётко определённые места.

Рисунок: AI Chat v2 больше не сжимает всю задачу в один фрагмент текста, а сохраняет структуру ввода, инструментов и событий вывода.
¶ Миграцию можно начать с изменения одного адреса
Если проект использует старый /aichat/conversations, не нужно сначала переписывать структуру сообщений или создавать интерфейс Agent. V2 продолжает принимать исходные поля, такие как model, question, stateful, id, references и preset. Для минимальной миграции достаточно изменить адрес запроса на:
https://api.acedata.cloud/aichat2/conversations
Самый базовый запрос по-прежнему остаётся коротким:
curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \
-H 'accept: application/json' \
-H 'authorization: Bearer YOUR_API_TOKEN' \
-H 'content-type: application/json' \
-d '{
"model": "YOUR_SUPPORTED_MODEL",
"question": "请概括这份需求里最重要的三个问题。",
"stateful": true
}'
В обычном режиме JSON интерфейс по-прежнему возвращает привычный результат:
{
"answer": "...",
"id": "conversation-uuid"
}
Сохраните возвращённый id; если в следующем запросе передать тот же id, диалог можно будет продолжить. Значение stateful по умолчанию — true; оно используется для управления загрузкой и продолжением контекста сохранённой сессии.
Этот шаг хорошо подходит для реальных проектов: сначала проверьте авторизацию, модель, задержку и нормальную работу старой бизнес-логики, а затем постепенно подключайте новые возможности. Миграцию не обязательно объединять с переработкой интерфейса в одном релизе.
¶ Когда в диалог входят файлы и изображения, порядок тоже становится информацией
Старое поле question подходит для чистого текста. В задачах вроде «сначала прочитать отчёт, затем сопоставить его со скриншотом и в конце дать вывод» простого списка вложений уже недостаточно. V2 добавляет структурированный массив message, в который можно по порядку поместить текст, изображения и файлы:
{
"model": "YOUR_SUPPORTED_MODEL",
"stateful": true,
"message": [
{
"type": "text",
"text": "阅读报告,并把其中的趋势与后面的仪表盘截图进行对照。"
},
{
"type": "file_url",
"file_url": {"url": "https://example.com/report.pdf"}
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/dashboard.png"}
}
]
}
Доступные блоки содержимого включают text, image_url и file_url. Важно не только то, что «вложения поддерживаются», но и то, что связи между содержимым не теряются при передаче. Клиент может чётко сообщить модели: какой фрагмент является описанием задачи, какой файл — исходным материалом и что следует сравнить далее.
Чтобы старые клиенты могли мигрировать плавно, V2 по-прежнему распознаёт references. URL с расширениями изображений будут обрабатываться как изображения, а остальные URL — как файлы. Если вы только обновляете интерфейс, можно временно сохранить прежний способ записи; если порядок ввода влияет на понимание, рекомендуется перейти на message.
¶ Потоковый ответ больше не означает только «печатает»
Традиционный потоковый вывод обычно содержит только текстовые приращения. Когда модель начинает поиск, чтение файлов или вызов внешних инструментов, страница выглядит зависшей: пользователь не знает, продолжается ли задача, а разработчик не получает понятного статуса.
AI Chat v2 предоставляет три способа ответа через заголовок запроса accept:
| Сценарий использования | accept |
Способ возврата |
|---|---|---|
| Простой серверный запрос | application/json |
После завершения возвращает {answer, id} |
| Node, Python, CLI или Worker | application/x-ndjson |
Один JSON-событие в каждой строке |
| Web-фронтенд | text/event-stream |
Поток событий SSE |
В режимах NDJSON и SSE возвращаются не только токены, но и набор типизированных событий. text_delta используется для приращений основного текста, tool_use означает, что модель готовится вызвать инструмент, tool_result возвращает результат инструмента, citation предоставляет источник цитирования, card и artifact содержат карточки или артефакты, которые можно отображать отдельно, error обозначает ошибку текущего раунда, а done сообщает использование и причину завершения.
Следующий Python-потребитель одновременно собирает основной текст и сохраняет ключевые состояния:
import json
import os
import requests
url = "https://api.acedata.cloud/aichat2/conversations"
headers = {
"accept": "application/x-ndjson",
"authorization": f"Bearer {os.environ['ACEDATA_API_TOKEN']}",
"content-type": "application/json",
}
payload = {
"model": os.environ["ACEDATA_CHAT_MODEL"],
"question": "Найдите материалы и предоставьте краткий вывод с источниками.",
"stateful": True,
}
with requests.post(url, json=payload, headers=headers,
stream=True, timeout=120) as response:
response.raise_for_status()
answer = []
for raw_line in response.iter_lines():
if not raw_line:
continue
event = json.loads(raw_line)
event_type = event.get("type")
if event_type == "text_delta":
answer.append(event.get("content", ""))
elif event_type == "tool_use":
print("Начало вызова:", event.get("tool_name"))
elif event_type == "tool_result":
print("Ошибка инструмента:", event.get("is_error"))
elif event_type == "error":
raise RuntimeError(event.get("message", "Неизвестная ошибка"))
elif event_type == "done":
print("Использование:", event.get("usage"))
print("Причина завершения:", event.get("terminal_reason"))
print("".join(answer))
Если продукту важен только итоговый текст, достаточно объединить все text_delta.content; если требуется наблюдаемый интерфейс Agent, можно отдельно отображать вызовы инструментов, ссылки, результаты и состояния. Оба требования используют один и тот же интерфейс, и не нужно поддерживать два набора протоколов для «простого чата» и «сложных задач».
¶ Вызовы инструментов доступны по умолчанию, но продукт всё равно должен чётко обозначать границы
V2 позволяет модели по мере необходимости задачи вызывать встроенные возможности, такие как веб-поиск, извлечение страниц и чтение файлов; после подключения и авторизации пользователем соответствующих сервисов также можно использовать инструменты MCP для обработки внешних данных из GitHub, Notion и других источников.
В потоке отдельно появляются tool_use и tool_result, которые сопоставляются через tool_id. На их основе фронтенд может отображать реальный прогресс, а бэкенд — записывать время выполнения каждого инструмента и место сбоя.
То, что инструменты могут вызываться автоматически, не означает, что область выполнения должна быть неограниченной. max_turns используется для ограничения числа итераций Agent в одном запросе, а в документации указан диапазон 1—500; при значении 1 в этом раунде выполняется только один вызов модели, без дальнейшего перехода к вызову инструментов. В производственной среде значение следует задавать активно с учётом сложности задачи, времени ответа и бюджета затрат, а не долго полагаться на большой предел по умолчанию.
Для Webhook, CI/CD или задач мониторинга V2 поддерживает async: true: задача может выполняться в фоновом режиме, а результат можно получить через запрос или callback_url. Однако действия, связанные с отправкой, публикацией и записью, требуют явной предварительной авторизации через allowed_skills, allowed_mcp_servers или unattended_policy.
Подключение решает вопрос «можно ли получить доступ», а политика авторизации — вопрос «можно ли в этот раз действовать от имени пользователя». Эти две вещи нельзя смешивать.
¶ Когда Agent не хватает информации, не нужно делать вид, что задача уже завершена
Сложные задачи часто останавливаются на конкретных вопросах: в какой канал публиковать, какой формат использовать, перезаписывать ли существующий файл. Для этого V2 предоставляет событие ask_user_question. После появления события сессия переходит в состояние ожидания ввода пользователя.
Клиент сохраняет текущий id сессии и соответствующий tool_id, показывает вопрос и собирает ответ, затем использует тот же id сессии и возвращает ответ через tool_results, после чего задача может продолжиться с точки остановки. Этот механизм также подходит для создания точек согласования. Вместо того чтобы позволять модели самостоятельно догадываться при нехватке данных, лучше вернуть недостающий выбор пользователю.
¶ Самими сессиями тоже можно управлять
V2 добавляет лёгкий CRUD для сессий в тот же эндпоинт, различая retrieve, retrieve_batch, update и delete через action.
retrieve_batch возвращает сводки, не содержащие полных messages, что подходит для боковой панели сессий; когда пользователь действительно открывает сессию, затем вызывается retrieve для чтения содержимого. Для длинных сессий серверное упорядочивание контекста также не заменяет сохранённые исходные сообщения сводками. Если необходимо продолжить редактирование статьи, проверить числа или подготовить публикацию, всё равно следует читать оригинальный текст, а не заменять содержимое сводкой.
¶ Перед запуском не проверяйте только «вернулся ли текст»
После подключения интерфейса Agent получение части текста не означает, что текущий раунд уже надёжно завершён; завершение потока также не обязательно означает успешность задачи. Клиент должен обрабатывать error и после получения done записывать usage и terminal_reason. В SSE [DONE] означает только завершение передачи и не может отменить события ошибок, уже появившиеся ранее.
API Token следует хранить только на сервере; парсер потока должен уметь обрабатывать сетевое разбиение и временно неизвестные новые события; вызовы инструментов должны сопоставляться по tool_id; ссылки на источники и результаты необходимо безопасно отображать; для подключений с возможностью записи следует сохранять ручное подтверждение или достаточно узкую авторизацию без надзора. Названия моделей, тарификация и доступные возможности могут обновляться, поэтому при официальной интеграции следует ориентироваться на актуальную документацию, страницу сервиса и консоль, а не надолго жёстко фиксировать примерные настройки.
Самое важное в AI Chat v2 — не добавление ещё нескольких кнопок в окно чата. Он наконец позволяет приложению видеть, что происходит внутри одной задачи AI: когда модель выводит текст, когда вызывает инструменты, где ожидает пользователя и с каким состоянием завершает работу.
Если существующий проект всё ещё представляет собой обычное поле вопросов и ответов, можно сначала изменить адрес интерфейса и продолжить использовать исходное тело запроса. После стабилизации этого шага можно подключить message, NDJSON или SSE, временную шкалу инструментов и приостановку с возобновлением. Обновление может быть небольшим, но оно оставляет достаточно большое пространство для последующей формы продукта.
