HTTP API

Инструменты HTTP API позволяют добавлять вызовы внешних REST API прямо к узлам воркфлоу, чтобы голосовые агенты могли обращаться к внутренним или внешним системам во время звонка по решению LLM и согласно вашим инструкциям. Это похоже на вызов функций в агентных платформах и полностью настраивается под ваш процесс.

Что такое HTTP-инструмент?

HTTP-инструмент — это определение REST API, которое LLM может вызвать во время выполнения. Типовые сценарии использования:

Вызов эндпоинтов вашего бэкенда
Запуск автоматизаций n8n
Синхронизация данных с CRM
Получение данных из внешних API: погода, цены, наличие и т. д.
Запись, обновление и чтение данных через REST API

LLM решает:

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

На основе:

Ваших промптов: инструкций на уровне узла на простом английском или любом другом языке
Названия инструмента
Описания инструмента
Определений параметров

Определение HTTP-инструмента

1. Название инструмента

Должно быть понятным и отражать действие.
Примеры: capture_lead_interest, fetch_weather, create_crm_contact и т. д.

2. Описание инструмента

Крайне важно
По нему LLM решает, когда использовать инструмент.
Пишите простым, явным английским: англоязычные описания и инструкции LLM распознаёт и вызывает надёжнее, чем русскоязычные.

Плохо: “API to capture data” Хорошо: “This tool is to capture interest. Use this tool when the user clearly expresses interest in the product or wants to be contacted”

3. Настройка эндпоинта

Полный URL, который обязательно содержит http:// или https://
Поддерживает REST-методы

Частая ошибка: забыть https:// в URL.

4. Аутентификация и заголовки

Добавьте пользовательские заголовки
Прикрепите переиспользуемые учётные данные на вкладке Аутентификация у инструмента (см. раздел «Учётные данные» ниже)
Работает с внутренними сервисами и сторонними API

5. Параметры

У каждого параметра должны быть:

Имя
Тип
Описание
Признак обязательности

Описания параметров важнее, чем типы. Рекомендации:

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

Пример:

interest (string): “Set to true if the user clearly shows intent to buy or wants follow-up. Otherwise false.”

Размещение параметров (location)

По умолчанию размещение каждого параметра выбирается автоматически по HTTP-методу: для POST/PUT/PATCH параметры уходят в тело запроса, для GET/DELETE — в query-строку. Это поведение значения location: "auto" — дефолта, при котором инструмент собирает запрос ровно так же, как до появления этой настройки. Через поле location (в REST API, SDK и MCP) отдельный параметр можно отправить в конкретное место запроса:

`location`	Куда попадает параметр
`auto`	По методу: тело для `POST`/`PUT`/`PATCH`, query для `GET`/`DELETE` (дефолт)
`query`	Всегда в query-строку URL — в том числе для `POST` (частый паттерн внешних API)
`body`	Всегда в тело запроса (JSON-поле или form-поле — зависит от типа тела)
`form`	В form-поле тела; доступно только при `body_type: "form"`

Правила валидации: body и form запрещены для GET/DELETE (у них нет тела по спецификации), form требует body_type: "form". Имена параметров должны быть уникальны и не пересекаться с preset_parameters — иначе конфигурация отклоняется с 422.

Параметр, использованный в шаблоне URL (/users/{{user_id}}), при location: "auto" по-прежнему отправляется и по обычному правилу метода — то есть может дублироваться в path и в body/query. Это осознанное поведение для обратной совместимости.

6. Тип тела запроса (body_type)

Поле body_type задаёт кодировку тела (в REST API, SDK и MCP; дефолт — json):

`body_type`	Кодировка	Content-Type
`json`	Параметры сериализуются в JSON-тело (`POST`/`PUT`/`PATCH`) или query-строку (`GET`/`DELETE`)	`application/json` (проставляет Агентика)
`form`	Параметры отправляются как `application/x-www-form-urlencoded`-поля	`application/x-www-form-urlencoded`
`raw`	Тело — отрендеренный шаблон `body_template` (произвольный формат: XML, SOAP, обычный текст и т. д.)	Задаётся вами в заголовках — заголовок обязателен

Режим form нужен для API вида Renovatio, где все методы — POST с urlencoded-телом: скалярные параметры уходят обычными полями, а вложенные структуры (объект/массив) автоматически сериализуются в JSON-строку внутри form-поля — ровно как это делают такие API.

{
  "method": "POST",
  "url": "https://app.rnova.org/api/public/createAppointment",
  "body_type": "form",
  "parameters": [
    { "name": "doctor_id", "type": "number", "description": "ID врача", "required": true },
    { "name": "services", "type": "array", "description": "Список услуг", "required": true }
  ]
}

При body_type: "form" можно задать свой заголовок Content-Type, но его media type обязан быть application/x-www-form-urlencoded (параметры вроде charset допускаются) — конфликтующий заголовок отклоняется с 422, потому что запрос ушёл бы с телом и заголовком, которые противоречат друг другу. Для body_type: "json" пользовательский Content-Type из заголовков остаётся нетронутым.

Raw-тело: body_template

Режим raw отправляет телом ровно то, что написано в body_template, с подстановкой переменных — для API с фиксированным форматом тела: XML/SOAP, обычный текст, экзотические JSON-схемы, подписанные полезные нагрузки. Типичный кейс — SOAP:

{
  "method": "POST",
  "url": "https://api.example.com/soap",
  "body_type": "raw",
  "body_template": "<soap:Envelope><patient>{{patient_name}}</patient><phone>{{preset_arguments.phone}}</phone></soap:Envelope>",
  "headers": { "Content-Type": "application/soap+xml; charset=utf-8" },
  "parameters": [
    { "name": "patient_name", "type": "string", "description": "Имя пациента", "required": true }
  ],
  "preset_parameters": [
    { "name": "phone", "type": "string", "value_template": "{{initial_context.phone}}", "required": true }
  ]
}

Синтаксис шаблона. Заполнитель — {{имя}}. Допускаются:

краткие имена объявленных параметров и preset_parameters ({{patient_name}}, {{phone}});
встроенные переменные current_time, current_time_<часовой пояс> (IANA, например current_time_Europe/Moscow), current_weekday и current_weekday_<часовой пояс>;
пути по группам рантайма: initial_context.*, gathered_context.*, arguments.* (аргументы LLM), preset_arguments.* (разрешённые пресеты). Пути arguments.* и preset_arguments.* проверяются на сохранении против объявленных параметров; initial_context.*/gathered_context.* — нет, их значения известны только на звонке.

Семантика кратких имён в raw-шаблоне отличается от шаблона URL. В URL краткое имя резолвится из объединения initial+gathered+arguments; в raw-шаблоне — из аргументов LLM, где одноимённый пресет перекрывает аргумент. Когда нужна точность, используйте полные пути: {{arguments.x}} — это именно аргумент LLM, {{preset_arguments.x}} — именно пресет, {{initial_context.x}} — именно контекст.

Правила валидации (422 при сохранении):

raw доступен только для POST/PUT/PATCH — raw всегда отправляет тело; параметры при этом идут в query-строку (location: "auto" работает как query, явные body/form запрещены — тело занято шаблоном); credential_placement: "form" с raw тоже запрещён (доступны header и query);
заголовок Content-Type обязателен (имя ищется без учёта регистра; дубли ключей разного регистра — 422); media type может быть любым — тело ваше;
фильтр-синтаксис ({{x | fallback:y}}) в raw-шаблоне не поддерживается и отклоняется;
исходный шаблон и отрендеренное UTF-8 тело ограничены 64 KiB каждое.

Поведение на звонке — строгий рендер. Порядок сборки: сначала пресеты разрешаются из начального и извлечённого контекста, затем рендерится тело. Любая отсутствующая переменная (нет такого пути в контексте или значении) — ошибка выполнения до отправки запроса, с именем пути в сообщении (значения в сообщение не попадают). Никаких тихих подстановок: пустая строка вместо значения, fallback-фильтры и трансформация литеральных \n отсутствуют как класс — всё, что вы написали в шаблоне (и что пришло в значениях), уходит в тело байт-в-байт. Это защищает XML/SOAP и подписанные полезные нагрузки от «молчаливых улучшений», но означает, что необязательную переменную без значения в шаблон писать нельзя. Единственное исключение — сами пресеты: их value_template разрешается общим рендерером до входа в raw-тело, поэтому литеральный \n внутри value_template пресета превратится в настоящий перевод строки (для подписанных полезных нагрузок не используйте \n в value_template пресетов).

Учётные данные

Секрет, которым инструмент аутентифицируется, не является частью самого инструмента. Это отдельный переиспользуемый объект учётных данных, принадлежащий вашей организации; инструмент ссылается на него по UUID. Одни учётные данные могут обслуживать сразу несколько инструментов — HTTP-инструмент, MCP-инструмент, получение данных перед звонком — и их ротация обновляет все сразу.

Создание учётных данных

Откройте инструмент, перейдите на вкладку Аутентификация и нажмите + рядом с выпадающим списком. Задайте имя (уникальное в организации — дубликат отклоняется с кодом 409), необязательное описание и выберите тип:

Тип	Что Агентика отправляет с каждым запросом
Bearer-токен	`Authorization: Bearer <token>`
API-ключ	Ваши имя и значение заголовка, например `X-API-Key: <api_key>`
Basic-аутентификация	`Authorization: Basic <base64(username:password)>`
Пользовательский заголовок	Любая пара «имя заголовка — значение», которую вы укажете

То же самое доступно через API:

curl -X POST https://your-agentika-instance/api/v1/credentials/ \
  -H "Authorization: Bearer $AGENTIKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "CRM production",
        "credential_type": "bearer_token",
        "credential_data": {"token": "sk-live-…"}
      }'

Каждому типу нужны свои поля, и запрос без них отклоняется: api_key требует header_name + api_key, bearer_token — token, basic_auth — username + password, custom_header — header_name + header_value.

Выбор учётных данных в инструменте

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

Размещение секрета (credential_placement)

По умолчанию (credential_placement: "header") секрет уходит заголовком авторизации — так, как описано выше. Некоторые API требуют ключ иначе: Renovatio ждёт его form-полем api_key в теле, некоторые сервисы — query-параметром вида ?api_key=…. Поле credential_placement (в REST API, SDK и MCP) задаёт, куда именно инжектируется секрет:

`credential_placement`	Куда попадает секрет	Ограничения
`header`	Заголовок авторизации по типу учётных данных (дефолт)	`credential_field` запрещён
`form`	Form-поле тела запроса (поле `credential_field`)	Только `body_type: "form"` и методы с телом (`POST`/`PUT`/`PATCH`)
`query`	Query-параметр URL (имя `credential_field`)	Любой метод и тип тела

{
  "method": "POST",
  "url": "https://app.rnova.org/api/public/getAppointments",
  "body_type": "form",
  "credential_uuid": "…",
  "credential_placement": "form",
  "credential_field": "api_key"
}

Правила валидации (отклоняются с 422 при сохранении): режимы form/query работают только с учётными данными типа API-ключ и требуют credential_uuid и непустой credential_field (латиница, цифры, _, ., -, до 128 символов); имя credential_field не может совпадать с именем параметра, preset-параметра или статического query-параметра из URL — иначе секрет был бы перезаписан пользовательскими данными. Поведение на звонке тоже различается. Для header сохраняется прежнее поведение: если учётные данные не нашлись, запрос всё равно уйдёт без авторизации (апстрим ответит 401). Для form/query действует принцип fail-closed: учётные данные не найдены (включая чужую организацию), не того типа, без значения api_key — запрос не отправляется вообще, инструмент возвращает ошибку выполнения. Секрет инжектируется последним, после всех пользовательских параметров, и существует только в исходящем запросе: в определении инструмента, промпте и логах его нет. Ответ API перед возвратом агенту проходит редацию — если апстрим эхом вернул ключ (в JSON, в теле ответа или в сообщении ошибки), каждое его представление заменяется на [REDACTED].

Секрет в теле или query-строке более уязвим к эху апстрима и его логам доступа, чем заголовок. Держите header, если API не требует иного, и предпочитайте узко ограниченные ключи на каждый инструмент.

При экспорте бандла credential_uuid вырезается, поэтому инструмент с размещением form/query импортируется со сброшенным в header размещением и очищенным credential_field (с заметкой в предупреждениях импорта) — после перепривязки учётных данных выберите размещение заново.

Если учётные данные удалены или принадлежат другой организации, запрос при размещении header всё равно уйдёт — но без заголовка авторизации, что обычно проявляется как 401 от вашего API. Если инструмент внезапно начал падать на авторизации, проверьте, что его учётные данные ещё существуют.

Ротация учётных данных

Поскольку инструменты ссылаются на UUID, ротация — это одно обновление: все инструменты, указывающие на эти учётные данные, подхватят новый секрет без правок:

curl -X PUT https://your-agentika-instance/api/v1/credentials/{credential_uuid} \
  -H "Authorization: Bearer $AGENTIKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"credential_type": "bearer_token", "credential_data": {"token": "sk-live-new…"}}'

Редактирование и удаление учётных данных сейчас доступны только через API; интерфейс умеет показывать список и создавать новые. DELETE /api/v1/credentials/{credential_uuid} — мягкое удаление: учётные данные пропадают из списка выбора и перестают применяться к запросам.

Что хранится

Значения учётных данных хранятся на сервере в базе данных Агентики и используются только для сборки исходящего заголовка авторизации. API их не возвращает: все эндпоинты учётных данных — список, получение, создание, обновление — отдают только UUID, имя, описание, тип и временные метки. Эндпоинт, который читает секрет, отсутствует.

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

Прикрепление инструментов к узлам воркфлоу

К одному узлу можно прикрепить несколько инструментов
Все созданные инструменты будут доступны для выбора в узле
Инструменты можно вызывать, только когда они прикреплены к этому узлу
LLM выберет, какой из них вызвать

Внутри узла направляйте LLM через простые английские инструкции — на них модель надёжнее распознаёт и вызывает инструменты. Пример: “If the user shows interest in speaking to sales or wants a callback, immediately call the capture_lead_interest tool and set interest to true.” Такая инструкция часто становится решающим фактором для корректного использования инструмента.

Логика вызова инструментов: как думает LLM

LLM учитывает:

Произнесённое намерение пользователя
Инструкции в промпте узла
Название и описание инструмента
Описания параметров

Если они четко согласованы, инструмент вызывается автоматически. Плохие названия или расплывчатые описания приводят к:

Пропущенным вызовам инструментов
Неверным параметрам
Выдуманным значениям

Ключевые рекомендации

Называйте инструменты понятно
Пишите подробные описания, ориентированные на действие
Сначала держите параметры простыми
Всегда указывайте http/https в URL
Используйте простой английский в инструкциях узла
Прикрепляйте к каждому узлу только релевантные инструменты

Чётко описанные инструменты + понятные промпты = надежные голосовые агенты, готовые к продакшену.

Начало работы

Основные понятия

Конфигурации

Конструктор голосовых агентов

Телефония

Интеграции

Что такое HTTP-инструмент?

Определение HTTP-инструмента

1. Название инструмента

2. Описание инструмента

3. Настройка эндпоинта

4. Аутентификация и заголовки

5. Параметры

Размещение параметров (location)

6. Тип тела запроса (body_type)

Raw-тело: body_template

Учётные данные

Создание учётных данных

Выбор учётных данных в инструменте

Размещение секрета (credential_placement)

Ротация учётных данных

Что хранится

Прикрепление инструментов к узлам воркфлоу

Логика вызова инструментов: как думает LLM

Ключевые рекомендации

​Что такое HTTP-инструмент?

​Определение HTTP-инструмента

​1. Название инструмента

​2. Описание инструмента

​3. Настройка эндпоинта

​4. Аутентификация и заголовки

​5. Параметры

​Размещение параметров (location)

​6. Тип тела запроса (body_type)

​Raw-тело: body_template

​Учётные данные

​Создание учётных данных

​Выбор учётных данных в инструменте

​Размещение секрета (credential_placement)

​Ротация учётных данных

​Что хранится

​Прикрепление инструментов к узлам воркфлоу

​Логика вызова инструментов: как думает LLM

​Ключевые рекомендации

Что такое HTTP-инструмент?

Определение HTTP-инструмента

1. Название инструмента

2. Описание инструмента

3. Настройка эндпоинта

4. Аутентификация и заголовки

5. Параметры

Размещение параметров (location)

6. Тип тела запроса (body_type)

Raw-тело: body_template

Учётные данные

Создание учётных данных

Выбор учётных данных в инструменте

Размещение секрета (credential_placement)

Ротация учётных данных

Что хранится

Прикрепление инструментов к узлам воркфлоу

Логика вызова инструментов: как думает LLM

Ключевые рекомендации