---
title: "Нативный API в AI-агентах"
description: "Нативный API в AI-агентах. Документация и инструкции по использованию и настройке облачных сервисов Timeweb Cloud."
---

# Нативный API

> Полный индекс документации для ИИ-агентов: [llms.txt](https://timeweb.cloud/llms.txt).

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

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

В каждом запросе необходимо [указывать API-токен](https://timeweb.cloud/docs/ai-agents/manage-agents/api-access-key). 

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

```shell
--header "authorization: Bearer $TOKEN"
```

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

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

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

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

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

## ID агента

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

![Access ID агента](https://content.timeweb.com/assets/db0b0fec-eb95-470b-b5c2-dba90b964c9f.png?width=2170&height=1750)

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

При использовании нативного API применяются настройки, указанные в разделе «[Плейграунд](https://timeweb.cloud/docs/ai-agents/manage-agents/playground)».

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

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

**Запрос**:

```shell
POST /api/v1/cloud-ai/agents/{access_id}/call
```

cURL

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

Python

```py
import requests

url = "https://api.timeweb.cloud/api/v1/cloud-ai/agents/<access_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())
```

Node.js

```js
const request = require('request');

const options = {
  method: 'POST',
  url: 'https://api.timeweb.cloud/api/v1/cloud-ai/agents/<access_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 сообщения из чата.
    

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

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

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

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

-   `stop` — ответ сгенерирован полностью, без ошибок;
-   `length` — ответ не уместился в [максимальное количество токенов](https://timeweb.cloud/docs/ai-agents/manage-agents/playground#nastrojki-agenta), поэтому генерация была прервана;
-   `content_filter` — сработал фильтр провайдера, предоставляющего доступ к AI (например, OpenAI или xAI), и генерация была остановлена. Под фильтрами подразумевается, например, цензурирование некоторых тем со стороны провайдера;
-   `error` — во время генерации произошла ошибка. Чтобы узнать причину, [создайте тикет в поддержку](https://timeweb.cloud/my/support/help-question) и приложите тело ответа.