Нативный API

Вы можете взаимодействовать с AI-агентами при помощи нативного API.

Аутентификация

Если в настройках AI-агента выбран приватный тип API, в каждом запросе необходимо указывать API-токен. При выборе публичного типа API, для отправки запросов, токен не потребуется.

Токен передается в формате:

    

      

    
    --header "authorization: Bearer $TOKEN"
  

В cURL-примерах вы можете:

• указать токен вручную, заменив $TOKEN на ваш реальный токен в каждом запросе;
• или использовать переменную окружения, чтобы не вставлять токен каждый раз:

    

      

    
    export TOKEN=ваш_токен_доступа
  

В этом случае менять заголовок в примерах не потребуется — переменная $TOKEN будет подставляться автоматически.

В примерах на Python и Node.js токен указывается напрямую в коде и обозначается как {{token}}. Мы рекомендуем хранить его в переменных окружения или конфигурационных файлах, а не в коде, чтобы избежать утечек.

ID агента

Для работы с агентом также требуется его ID. Вы можете найти его во вкладке «Дашборд» в панели управления агентом.

Настройка агента

При использовании нативного API применяются настройки, указанные в разделе «Плейграунд».

Отправка сообщения агенту

Метод позволяет отправить сообщение AI-агенту и получить ответ.

Запрос:

    

      

    
    POST /api/v1/cloud-ai/agents/{agent_id}/call
  

    

      

    
    curl --request POST \
  --url https://api.timeweb.cloud/api/v1/cloud-ai/agents/<agent_id>/call \
  --header "authorization: Bearer $TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "message": "Привет!",
    "parent_message_id": "3adfea84-bcdb-44b5-8914-92035e75ec24"
  }'
  

Параметры:

• message — текст запроса к агенту.

• parent_message_id — ID сообщения для продолжения диалога. Параметр необязательный. В качестве значения можно использовать не только последний ответ, но и любой другой ID сообщения из чата.

Пример ответа:

    

      

    
    {
  "message": "ответ агента",
  "id": "340b7381-2834-4b98-a51c-e68f8d0abd5b",
  "response_id": "ed08981f-126b-49e7-856d-d122b3a53f26"
}
  

Значение id из ответа можно использовать как parent_message_id в следующих запросах.

Поле finish_reason указывает на причину завершения генерации ответа. Возможно четыре значения:

• stop — ответ сгенерирован полностью, без ошибок;
• lenght — ответ не уместился в максимальное количество токенов, поэтому генерация была прервана;
• content_filter — сработал фильтр провайдера, предоставляющего доступ к AI (например, OpenAI или xAI), и генерация была остановлена. Под фильтрами подразумевается, например, цензурирование некоторых тем со стороны провайдера;
• error — во время генерации произошла ошибка. Чтобы узнать причину, создайте тикет в поддержку и приложите тело ответа.