Подключите агента OpenAI Agents SDK к WhatsApp

Как сообщение из WhatsApp превращается в запуск агента?

Через маршрут в вашем приложении, который вызывает Meta. Укажите его как адрес вебхука номера и добавьте в путь длинный случайный секрет. Маршрут отвечает на проверочный GET от Meta, возвращая hub.challenge обычным текстом, принимает каждый POST, сразу отвечает 200 и ставит работу в очередь: Meta повторяет медленные ответы, и агент запустился бы дважды.

Затем воркер берёт из тела запроса отправителя и текст и вызывает Runner.run. Передайте сессию, id которой равен номеру отправителя: SDK хранит диалог под этим id, поэтому следующее сообщение того же клиента продолжает разговор с того места, где он закончился, а истории двух клиентов никогда не смешиваются. Для начала достаточно SQLiteSession; для нескольких воркеров SDK также поставляется с сессиями Redis и SQLAlchemy.

Секрет в URL здесь служит аутентификацией. Meta подписывает доставки секретом приложения Tech Provider, поэтому клиент не может проверить заголовок подписи.

import os, httpx
from agents import Agent, Runner, SQLiteSession

agent = Agent(name="Front desk", instructions="Answer briefly and politely.")
URL = f"https://graph.facebook.com/v25.0/{os.environ['PHONE_NUMBER_ID']}/messages"

async def handle(sender: str, text: str) -> None:
    session = SQLiteSession(sender, "whatsapp.db")
    result = await Runner.run(agent, text, session=session)
    async with httpx.AsyncClient() as http:
        await http.post(
            URL,
            headers={"Authorization": f"Bearer {os.environ['WA_TOKEN']}"},
            json={"messaging_product": "whatsapp", "to": sender,
                  "type": "text", "text": {"body": result.final_output}},
        )

Почему ответ должен отправлять ваш код, а не агент?

Потому что единственное правило, которое нельзя нарушать, связано со временем, а код соблюдает его надёжнее, чем промпт. Когда клиент пишет, Meta открывает окно обслуживания клиентов на 24 часа. Внутри него проходит свободный текст. Вне его проходит только одобренный шаблон, а свободный текст возвращается с ошибкой 131047.

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

У агента по-прежнему могут быть инструменты. Дайте ему инструменты-функции (function tools) для поиска данных, например заказа или бронирования, а отправку в WhatsApp оставьте воркеру. Так токен доступа остаётся вне всего, что модель может вызвать с произвольными аргументами.

Может ли агент использовать сервер EasyCoexistence MCP?

Может, через MCPServerStreamableHttp, но настройка сложнее, чем один заголовок. SDK принимает либо заголовок Authorization, либо httpx.Auth в params["auth"]. Сервер EasyCoexistence MCP выдаёт собственные токены OAuth после входа в браузере, с динамической регистрацией клиентов и PKCE, поэтому статического ключа не существует. MCP Python SDK содержит OAuthClientProvider, обработчик HTTP-аутентификации, который проходит этот процесс с PKCE и обновлением токена, и именно он указывается в params["auth"].

Это оправданно, когда агент должен решать сам: проверить состояние номера, прочитать статус шаблона или выбрать между send_message и send_template по правилам из описаний инструментов. Если агент на входе только отвечает, воркер, описанный выше, короче, и в нём меньше мест для сбоев.

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

Распространённые ошибки

• Запуск агента до того, как Meta получила 200. Медленный ответ повторяется, и клиент получает два ответа.
• Одна сессия на всех клиентов. Привяжите её к номеру отправителя, иначе истории смешаются.
• Отложенное напоминание со свободным текстом. Через 24 часа оно завершится ошибкой 131047; отправляйте шаблон.

Часто задаваемые вопросы

Читайте дальше