Подключите собственного ИИ-агента к WhatsApp: любой фреймворк (LangGraph, ADK, свой код) через вебхук-эндпоинт

Почти любого ИИ-агента можно подключить к WhatsApp без переписывания. Запустите своего агента, созданного на LangGraph, Google ADK, CrewAI или на вашем коде, за HTTPS-эндпоинтом, затем добавьте его в MonoChat как ИИ Harness с провайдером «Собственный»: URL эндпоинта и общий секрет. Поместите узел «ИИ-агент» в сценарий, подключите номер WhatsApp, и ваш агент будет отвечать клиентам в WhatsApp и во всех остальных каналах, которые подключает MonoChat, с общими входящими и передачей диалога человеку вокруг него.

Это руководство для команд, у которых уже есть агент или которым нужен полный контроль над его работой. В нём рассказано, когда имеет смысл подключать собственного агента, за что отвечает ваш эндпоинт, как выглядит настройка в MonoChat и какие детали важны в продакшене.

Зачем подключать собственного агента?

Большинство платформ клиентских сообщений поставляются с одним встроенным ИИ-агентом. Это удобно, пока:

• Ваш агент уже создан. Ваши разработчики месяцами делали граф на LangGraph или мультиагентную систему на ADK, с оценками и тестами. Пересоздание в конструкторе ботов вендора выбрасывает эту работу.
• Вам нужна собственная логика. Правила ценообразования, проверки права на услугу, шаги соответствия требованиям или внутренние системы, до которых может добраться только ваш код.
• Вы хотите выбирать фреймворк. Фреймворки быстро меняются. Сегодня это LangGraph, в следующем году может быть что-то другое. Ваши каналы и входящие не должны меняться вместе с ним.
• Данные должны оставаться у вас. Некоторые организации хотят, чтобы рассуждения агента и вызовы инструментов выполнялись на их собственной инфраструктуре.

Agent Harness от MonoChat создан для этого: подключите собственный фреймворк агентов и сохраните всё вокруг него (каналы, входящие, людей) в одном месте.

Как работает собственный harness

Представьте это как разделение труда.

MonoChat отвечает за уровень диалога:

• Официальные подключения к WhatsApp, Instagram, Messenger, TikTok, Telegram, веб-чату, SMS и голосу (MonoChat — официальный бизнес-партнёр Meta).
• Сценарий, который определяет, когда вызывается агент, с помощью узла «ИИ-агент».
• Общие входящие команды, где человек может подхватить диалог с полной историей.

Ваш эндпоинт отвечает за агента:

• Получение диалога от MonoChat.
• Запуск вашего агента: его рассуждения, инструменты, память.
• Возврат ответа агента.

Между ними стоит общий секрет — значение, известное обеим сторонам, чтобы ваш эндпоинт мог проверить, что запрос пришёл из вашего аккаунта MonoChat. MonoChat определяет точный формат запроса и ответа, который реализует ваш эндпоинт; если у вас его ещё нет, свяжитесь с нами, и мы передадим его вашим разработчикам.

Что должен делать ваш эндпоинт

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

Проверяйте каждый запрос

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

Разделяйте диалоги

Клиенты пишут параллельно. Убедитесь, что состояние агента, память и любые рабочие файлы относятся к одному диалогу, чтобы данные одного клиента никогда не попали в ответ другому.

Отвечайте сообщениями размером для чата

Агенты, созданные для веб-приложений, склонны писать длинные форматированные ответы. WhatsApp читают на телефоне. Попросите агента писать короткие сообщения, по одному вопросу за раз, и не использовать в ответах сложную разметку Markdown.

Падайте громко, а не тихо

Если инструмент завершился по тайм-ауту или провайдер модели вернул ошибку, возвращайте понятный отказ, а не недописанный ответ. Предсказуемый отказ позволяет сценарию поступить правильно, например передать диалог человеку.

Будьте быстрыми

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

Шаг за шагом в MonoChat

1. Разверните агента за HTTPS

Разместите своего агента на LangGraph, ADK, CrewAI или собственного на вашем сервере или в облаке, доступным по HTTPS. Реализуйте формат запроса и ответа MonoChat и проверку общего секрета.

2. Добавьте ИИ Harness с провайдером «Собственный»

В MonoChat добавьте ИИ Harness, выберите «Собственный» и введите URL эндпоинта и общий секрет. Harness добавляется один раз, и его можно использовать в любом количестве сценариев.

3. Добавьте узел «ИИ-агент» в сценарий

В сценарии, принимающем входящие диалоги, добавьте узел «ИИ-агент» и выберите свой собственный harness. Используйте окружающий сценарий для того, что сценарии делают лучше всего: приветствие, маршрутизация по языку или теме, рабочее время и путь к человеку.

4. Задайте бюджет на запуск

Каждый узел «ИИ-агент» поддерживает лимиты бюджета на запуск. Используйте их как страховку рядом с ограничениями, которые вы уже применяете в собственном коде.

5. Подключите WhatsApp и другие каналы

Подключите номер WhatsApp Business, затем привяжите тот же сценарий к другим используемым каналам. Дополнительной работы по интеграции для каждого канала нет: ваш эндпоинт видит диалоги, а не API каналов.

6. Протестируйте и запустите

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

Заметки по фреймворкам

LangGraph. Граф из узлов и рёбер естественно подходит для путей поддержки (сортировка, поиск, решение, эскалация). Оберните скомпилированный граф в небольшой HTTP-сервис, загружайте состояние диалога при каждом запросе и возвращайте итоговое сообщение.

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

CrewAI. Команды агентов с ролями хорошо работают для задач с чёткой передачей, например исследование, а затем ответ. Для чата делайте команды небольшими: каждый дополнительный агент добавляет задержку.

Ваш собственный код. Часто хватает простого цикла с API модели и несколькими функциями. Вы сохраняете полный контроль, а MonoChat даёт каналы и входящие.

Передача диалога: решайте в сценарии

Решите в сценарии, какие диалоги передаются человеку и какая команда их получает, и напишите агента так, чтобы он честно говорил клиенту, когда не может помочь, а не гадал. Затем сценарий передаёт диалог нужной команде в общих входящих с полной историей. Business Messaging Policy WhatsApp также ожидает, что автоматические ответы предлагают понятный путь к человеку.

Держите агента и внутри вашего бизнеса. С 15 января 2026 года WhatsApp не допускает на платформе ИИ-ассистентов общего назначения; агенты, обслуживающие ваших клиентов, допустимы. Это правило объясняет наше руководство по политике WhatsApp для ИИ-чат-ботов.

Когда не стоит создавать своего

Собственный агент — самый гибкий вариант, но и тот, который вам придётся поддерживать. Если вы начинаете с нуля, встроенный вариант запустит вас быстрее, и ничего не нужно размещать:

• Встроенный harness MonoChat на ваших ИИ-моделях MonoChat.
• OpenAI Agents SDK, работающий внутри MonoChat (руководство).
• Claude Agent SDK или Pi, работающие на агентном раннере MonoChat (руководство по Claude).
• Облачные агенты: OpenAI Agents API или Claude Managed Agents с вашим собственным ключом.

Поскольку все варианты используют один и тот же узел «ИИ-агент», вы можете начать с одного и позже перейти на собственного агента, не трогая каналы и передачу диалога. Сравните их на странице Agent Harness.