Использование API

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

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

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

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

--header "authorization: Bearer $TOKEN"

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

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

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

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

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

ID агента

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

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

Метод позволяет отправить сообщение 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"
  }'

import requests

url = "https://api.timeweb.cloud/api/v1/cloud-ai/agents/<agent_id>/call"

payload = {
    "message": "Привет",
    "parent_message_id": "3adfea84-bcdb-44b5-8914-92035e75ec24"
}
headers = {
    "content-type": "application/json",
    "authorization": "Bearer {{token}}"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://api.timeweb.cloud/api/v1/cloud-ai/agents/<agent_id>/call',
  headers: {'content-type': 'application/json', authorization: 'Bearer {{token}}'},
  body: {message: 'Привет', parent_message_id: '3adfea84-bcdb-44b5-8914-92035e75ec24'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Параметры:

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

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

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

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

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