Uruchom agenta OpenAI Agents SDK w WhatsApp

Jak wiadomość z WhatsApp staje się uruchomieniem agenta?

Przez trasę w Twojej aplikacji, którą wywołuje Meta. Ustaw jej adres jako adres docelowy webhooka numeru, z długim losowym sekretem w ścieżce. Trasa odpowiada na weryfikacyjne żądanie GET od Meta, zwracając hub.challenge jako zwykły tekst, przyjmuje każde żądanie POST, od razu odpowiada kodem 200 i kolejkuje pracę, ponieważ Meta ponawia wolne odpowiedzi i agent zostałby uruchomiony dwukrotnie.

Proces roboczy odczytuje z payloadu nadawcę i tekst, po czym wywołuje Runner.run. Przekaż sesję, której identyfikatorem jest numer nadawcy: SDK zapisuje rozmowę pod tym identyfikatorem, więc kolejna wiadomość tego samego klienta kontynuuje poprzednią, a dwóch klientów nigdy nie dzieli historii. Na początek wystarczy SQLiteSession; SDK zawiera też sesje Redis i SQLAlchemy dla kilku procesów roboczych.

Sekret w adresie URL pełni tu rolę uwierzytelniania. Meta podpisuje dostawy sekretem aplikacji Tech Provider, więc klient nie może zweryfikować nagłówka z podpisem.

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}},
        )

Dlaczego odpowiedź powinien wysyłać Twój kod, a nie agent?

Ponieważ jedyna reguła, której nie wolno złamać, dotyczy czasu, a kod egzekwuje ją lepiej niż prompt. Meta otwiera 24-godzinne okno obsługi klienta, gdy klient napisze. W jego trakcie przechodzi dowolny tekst. Poza nim przechodzi tylko zatwierdzony szablon, a dowolny tekst wraca z błędem 131047.

Proces roboczy, który odpowiada na wiadomość dopiero co otrzymaną, zawsze mieści się w oknie, więc wysyłanie result.final_output jako tekstu jest bezpieczne z założenia. Zadania odroczone, takie jak kontakt następnego ranka czy przypomnienie, powinny iść osobną ścieżką, która wysyła szablon, nigdy dowolny tekst.

Agent nadal może mieć narzędzia. Daj mu narzędzia funkcyjne do sprawdzania informacji, na przykład zamówienia lub rezerwacji, a wysyłkę do WhatsApp zostaw w procesie roboczym. Dzięki temu token dostępu nie trafia do niczego, co model może wywołać z dowolnymi argumentami.

Czy agent może korzystać z serwera MCP EasyCoexistence?

Może, przez MCPServerStreamableHttp, ale konfiguracja jest bardziej złożona niż sam nagłówek. SDK przyjmuje nagłówek Authorization albo httpx.Auth w params["auth"]. Serwer MCP EasyCoexistence wydaje własne tokeny OAuth po zalogowaniu w przeglądarce, z dynamiczną rejestracją klienta i PKCE, więc statyczny klucz nie istnieje. MCP Python SDK zawiera OAuthClientProvider, czyli procedurę uwierzytelniania HTTP, która przeprowadza ten przepływ z PKCE i odświeżaniem tokenu, i to trafia do params["auth"].

Warto, gdy agent ma sam decydować: sprawdzić kondycję numeru, odczytać status szablonu albo wybrać między send_message a send_template według reguł z opisów narzędzi. Dla recepcji, która tylko odpowiada, proces roboczy opisany wyżej jest krótszy i ma mniej miejsc na błąd.

Tak czy inaczej webhook zostaje. MCP działa w modelu żądanie i odpowiedź, a wiadomość klienta może dotrzeć do agenta tylko przez trasę, którą wywołuje Meta.

Typowe błędy

• Uruchamianie agenta przed zwróceniem kodu 200 do Meta. Wolna odpowiedź jest ponawiana, a klient dostaje dwie odpowiedzi.
• Jedna sesja dla wszystkich klientów. Oprzyj ją na numerze nadawcy, bo inaczej historie się mieszają.
• Wysyłanie dowolnego tekstu w opóźnionym kontakcie. Po 24 godzinach kończy się to błędem 131047; wyślij szablon.

Najczęściej zadawane pytania

Czytaj dalej