Создание агентских приложений с AceDataCloud AI Chat v2

Конечная точка чата может возвращать текст. Конечная точка агента может проверять файл, искать в интернете, вызывать авторизованный инструмент, запрашивать недостающую информацию и передавать каждый шаг обратно в ваш интерфейс.

В этом заключается практическое различие AceDataCloud AI Chat v2. Конечная точка POST https://api.acedata.cloud/aichat2/conversations сохраняет простой стиль запросов исходного API разговоров, добавляя при этом мультимодальные блоки контента, автономное многораундовое использование инструментов, MCP-подключения, структурированные потоковые события, возобновляемые разговоры и CRUD-действия с разговорами.

Архитектура AI Chat v2: мультимодальные входные данные, инструменты агента и структурированные события

Это руководство сосредоточено на интеграционных решениях, которые важны при переходе от базового чат-бота к производственному агентскому интерфейсу.

Что меняется в AI Chat v2?

AI Chat v2 — это комплексное обновление исходного интерфейса /aichat/conversations. Его основные возможности:

  • Мультимодальный ввод: отправляйте упорядоченные блоки text, image_url и file_url в одном массиве message.
  • Автономное использование инструментов: модель может вызывать встроенные инструменты и авторизованные пользователем MCP-серверы в нескольких раундах.
  • Типизированная потоковая передача: отображайте текст, активность инструментов, цитаты, карточки, артефакты, ошибки и данные о завершении как отдельные события.
  • Пауза и возобновление: обрабатывайте событие ask_user_question и продолжайте тот же разговор с результатом инструмента.
  • Управление разговорами: получайте, пакетно получайте, обновляйте и удаляйте через действия на той же конечной точке.
  • Обратно совместимые запросы: существующие клиенты с model + question могут перейти, изменив путь конечной точки.

Важный архитектурный сдвиг состоит в том, что вашему фронтенду больше не нужно рассматривать ответ как одну непрозрачную строку. Он может стать рабочим пространством, управляемым событиями.

Начните с обратно совместимого пути

Миграция с наименьшим риском намеренно минимальна. Сохраните существующее тело запроса и измените только конечную точку:

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": "Summarize the three most important points in this request.",
    "stateful": true
  }'

В режиме JSON ответ сохраняет привычную структуру:

{
  "answer": "...",
  "id": "conversation-uuid"
}

Сохраните возвращённый id. Его отправка в следующем запросе продолжает управляемый разговор без необходимости повторно отправлять клиенту всю историю сообщений.

Значение stateful по умолчанию равно true. Явно установите его в false, когда раунд не должен сохраняться.

Этот первый шаг миграции позволяет вам проверить аутентификацию, доступность модели, задержку и поведение приложения перед внедрением инструментов или нового потокового UI.

Используйте message, когда важны порядок и модальность

Старое поле question удобно для текстовых подсказок. Для текста, смешанного с изображениями или файлами, используйте упорядоченный массив message:

{
  "model": "YOUR_SUPPORTED_MODEL",
  "stateful": true,
  "message": [
    {
      "type": "text",
      "text": "Read the attached report and compare its chart with this screenshot. Return five findings."
    },
    {
      "type": "file_url",
      "file_url": {
        "url": "https://example.com/report.pdf"
      }
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/dashboard.png"
      }
    }
  ]
}

Поддерживаемые блоки контента:

Блок Обязательное значение Лучшее применение
text text Инструкции, контекст и вопросы
image_url image_url.url Скриншоты, диаграммы, изображения товаров
file_url file_url.url PDF, CSV, TXT и другие файлы

AI Chat v2 по-прежнему распознаёт старый массив references. Расширения изображений преобразуются в блоки изображений, в то время как другие URL становятся блоками файлов. Эта совместимость полезна во время миграции, но message — лучший долгосрочный контракт, когда важен порядок контента.

Проектируйте клиент вокруг событий, а не только токенов

Выберите формат ответа с помощью заголовка accept:

Клиент Заголовок Формат
UI браузера text/event-stream Server-Sent Events
Node, Python, CLI, worker application/x-ndjson Одно JSON-событие на строку
Простой бэкенд-запрос application/json Финальный объект {answer, id}

Минимальный Python-потребитель NDJSON может собирать текст, сохраняя при этом другие типы событий:

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": "Research the topic, cite sources, and return a concise brief.",
    "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("tool started:", event.get("tool_name"))
        elif event_type == "tool_result":
            print("tool finished; error =", event.get("is_error"))
        elif event_type == "citation":
            print("source:", event)
        elif event_type == "artifact":
            print("artifact:", event)
        elif event_type == "error":
            raise RuntimeError(event.get("message", "unknown agent error"))
        elif event_type == "done":
            print("usage:", event.get("usage"))
            print("terminal reason:", event.get("terminal_reason"))

print("".join(answer))

Производственные интерфейсы должны определять рендерер или обработчик для каждого семейства событий:

  • text_delta обновляет область ответа.
  • tool_use и tool_result управляют состояниями активности и представлениями аудита.
  • citation прикрепляет источники к соответствующему выводу.
  • card отображает структурированные предварительные просмотры.
  • artifact предоставляет отдельный сгенерированный результат.
  • thinking следует обрабатывать только тогда, когда выбранная модель его предоставляет.
  • error завершает или восстанавливает текущий раунд.
  • done закрывает поток и записывает использование токенов вместе с причиной завершения.

Если вашему интерфейсу нужен только финальный ответ, объедините content из каждого text_delta. Это эквивалентно answer, возвращаемому в режиме JSON.

Позвольте агенту использовать инструменты — но сделайте активность видимой

Вызов инструментов включён по умолчанию. AI Chat v2 может использовать встроенные возможности, такие как веб-поиск, извлечение страниц и чтение файлов. Он также может подключать авторизованные пользователем MCP-подключения, такие как Google Drive, Notion, Slack или GitHub.

Поток ясно показывает границу:

{"type":"tool_use","tool_id":"toolu_01","tool_name":"web_search","input":{"query":"topic"}}
{"type":"tool_result","tool_id":"toolu_01","output":"...","is_error":false}

Сопоставляйте tool_use и tool_result по tool_id. Это поддерживает индикаторы прогресса, измерения задержек, обработку ошибок и понятный оператору журнал аудита.

Используйте max_turns, чтобы ограничить количество автономных раундов использования инструментов, которые могут происходить в одном запросе. Допустимый диапазон составляет 1–500; документированное значение по умолчанию — 500. Более низкое значение сокращает неограниченное выполнение. Установка max_turns: 1 принудительно задаёт один ответ и предотвращает вызовы инструментов.

Практический шаблон внедрения:

  1. Начните в режиме JSON без инструментов в UI продукта.
  2. Добавьте NDJSON или SSE и отображайте text_delta вместе с done.
  3. Показывайте активность инструментов как свёрнутую временную шкалу.
  4. Добавьте отображение цитат и артефактов.
  5. Установите осознанное значение max_turns на основе сложности задачи и допустимых затрат.
  6. Включайте подключения с возможностью записи только после проверки их модели подтверждения.

Обрабатывайте вопросы как возобновляемую машину состояний

Агенту иногда требуется уточнение. В таком случае поток может выдать ask_user_question, и разговор переходит в состояние awaiting_user_input.

Ваш клиент должен:

  1. Сохранить id разговора и tool_id.
  2. Отобразить вопрос и его варианты.
  3. Собрать ответ пользователя.
  4. Отправить другой запрос с тем же id разговора.
  5. Вернуть ответ через tool_results для ожидающего вызова инструмента. Это более надежно, чем делать вид, что агент может завершить работу при отсутствии информации. Это также делает возможными этапы утверждения для чувствительных действий.

Разделяйте интерактивное и автономное выполнение

Для вебхуков, заданий CI/CD и систем мониторинга async: true возвращает идентификатор задачи, пока работа продолжается. Результат можно получить позже или доставить на URL-адрес обратного вызова HTTP(S).

Автономный доступ на запись должен быть явным. AI Chat v2 поддерживает allowed_skills, allowed_mcp_servers или эквивалентный объект unattended_policy. Пустой список не авторизует никаких возможностей. Предварительная авторизация не обходит собственный механизм безопасности коннектора; навык, который не поддерживает автономное подтверждение, все равно должен выполнять пробный запуск или отказываться от записи.

Это различие важно: доступность подключения — не то же самое, что разрешение действовать без присутствия человека.

Контрольный список для продакшена

Перед запуском агентного интерфейса проверьте:

  • Учетные данные API хранятся на стороне сервера, а не в коде браузера.
  • Имена моделей берутся из текущего списка поддерживаемых моделей, а не из жестко заданных предположений.
  • Парсер потока допускает частичные сетевые фрагменты и неизвестные типы событий.
  • События инструментов сопоставляются по tool_id, а ошибки записываются.
  • max_turns устанавливается намеренно.
  • URL-адреса цитат и артефактов отображаются безопасно.
  • ask_user_question сохраняет достаточно состояния, чтобы позже возобновить работу.
  • Подключения с возможностью записи сохраняют подтверждение или узко ограниченную автономную авторизацию.
  • done.usage и terminal_reason передаются в систему наблюдаемости.
  • Политики удаления и хранения разговоров соответствуют требованиям вашего продукта.

Кратчайший путь от чат-бота к агенту

AI Chat v2 не требует полной переработки. Начните со смены конечной точки и сохранения текущего тела запроса. Затем перейдите к мультимодальным блокам message, внедрите структурированную потоковую передачу, отображайте прогресс работы инструментов и добавьте обработку приостановки и возобновления.

В результате получится клиент, который может вырасти от простых ответов до проверяемого агентного рабочего процесса — без изобретения отдельного протокола для файлов, инструментов, цитат, артефактов или уточнений пользователя.

Официальные ресурсы