Зачем подключать ИИ-агента к своему приложению через API

Что такое API ИИ-агента?

API ИИ-агента позволяет вашему собственному ПО отправить сообщение агенту, которого вы уже создали, и получить его ответ. Агент сохраняет свои инструкции, знания, модель, инструменты и правила безопасности. Ваше приложение только отправляет вопрос.

В этом отличие от «голого» API модели. API модели дает генерацию текста, а все остальное оставляет вам: промпты, поиск по документам, память, лимиты запросов, биллинг. REST API от IMFA дает управляемого агента, у которого все это уже есть, за одним ключом, привязанным к агенту.

Агента вы создаете в конструкторе ИИ-чат-ботов. API это еще одно место, где он может отвечать, наряду с вашим сайтом, WhatsApp, Instagram, Facebook, Telegram, Discord и голосовой линией.

Когда стоит подключать агента через API?

Используйте API, когда разговор происходит внутри вашего собственного продукта:

• Вашему приложению или клиентскому порталу нужен помощник, который знает ваши правила, без второго чат-бота, которого придется поддерживать.
• Ваш бэкенд должен отвечать на вопросы из другой системы, например со страниц заказов, сервиса бронирования или внутренней панели.
• Вы хотите видеть лиды в своей CRM. API возвращает лиды, которые агент собрал во всех каналах, и их можно синхронизировать по расписанию.
• Вам нужна история переписки для отчетов или контроля качества.

Если вам нужна только кнопка чата на сайте, проще встроить виджет одной строкой кода. API нужен, когда интерфейсом служит ваш продукт, а не виджет.

Как работает API агента IMFA

Базовый URL: https://site.imfa.app/v1. Каждый вызов требует ключ агента и должен идти из доверенного серверного кода, никогда из браузера или мобильного приложения.

1. Опубликуйте агента. Задайте в IMFA его инструкции, знания, модель и инструменты, проверьте реальные вопросы и опубликуйте. API работает с опубликованной версией.
2. Создайте ключ. Откройте раздел API агента или экран API Keys и сгенерируйте ключ. Он показывается один раз и хранится только в виде хеша. Храните его в переменной окружения на сервере, например IMFA_API_KEY.
3. Отправьте запрос в чат. POST /v1/agents/{slug}/chat с заголовком Authorization: Bearer <key>, уникальным Idempotency-Key (от 8 до 128 символов) и JSON-телом с message и необязательным sessionId. В ответе приходят sessionId и usage.credits.
4. Продолжите разговор. В первом сообщении не передавайте sessionId, а затем отправляйте тот, что получили. Агент помнит контекст.
5. Смотрите, что произошло. GET /v1/agents/{slug}/sessions выводит список разговоров, GET /v1/agents/{slug}/sessions/{sessionId}/messages читает один из них, а GET /v1/agents/{slug}/leads возвращает собранные лиды. Списки по умолчанию содержат 20 элементов, максимум 100, с курсором. GET /v1/agents подтверждает, какого агента обслуживает ключ.

Ограничения прописаны явно: используются первые 4 000 символов сообщения, тело запроса ограничено 64 000 байт, а ошибки типизированы (валидация, аутентификация, кредиты, лимит запросов, сервер). Ответ 429 приходит с Retry-After, а 402 означает, что у владельца закончились кредиты.

Почему стоит использовать API агента, а не строить все самому

Вы экономите месяцы инфраструктурной работы. Поиск по документам, сессии, лимиты запросов, повторные попытки, учет кредитов и защита от prompt injection уже работают. Вашей команде достаточно написать один HTTP-запрос.

Один агент, одно поведение. Ответ в вашем приложении совпадает с ответом на сайте и в WhatsApp, потому что это тот же агент. Обновите его один раз в IMFA, и изменения появятся везде.

Повторные запросы безопасны. Благодаря ключу идемпотентности повтор после сбоя сети возвращает исходный ответ, а не списывает оплату за второй ход.

Лиды больше не разбросаны по разным местам. Забирайте все собранные лиды через один эндпоинт, из какого бы канала они ни пришли.

Полностью кастомное решение по-прежнему возможно. Если вам нужно контролировать каждый уровень, «голый» API модели дает такой контроль, но строить и поддерживать все придется самим. ИИ-агенты для программирования, такие как Codex и Claude Code, тоже могут управлять агентами IMFA через MCP, а ваш сервер обслуживает клиентов по REST-ключу.

Частые вопросы об API ИИ-агента

Можно ли вызывать API ИИ-агента прямо из браузера?

Нет. Ключ расходует кредиты владельца и должен оставаться на доверенном сервере. API не открывает широкий доступ из браузера. Пусть браузер обращается к вашему собственному защищенному эндпоинту, а тот уже вызывает IMFA.

Как аутентифицировать запрос к API агента IMFA?

Создайте ключ агента в разделе API агента или на экране API Keys, затем отправляйте Authorization: Bearer YOUR_API_KEY из серверного кода. Токен MCP это другие учетные данные, и здесь он не работает.

Как продолжить тот же разговор через API?

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

Зачем для чата нужен Idempotency-Key?

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

Использует ли API агента мои знания и инструменты?

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

Что будет, если сработает лимит запросов или закончатся кредиты?

При превышении лимита вы получите 429 с заголовком Retry-After, а когда у владельца закончатся кредиты, 402. Обрабатывайте в интеграции каждый задокументированный код ответа.