Bir OpenAI Agents SDK ajanını WhatsApp'a taşıyın

Bir WhatsApp mesajı nasıl ajan çalıştırmasına dönüşür?

Meta'nın çağırdığı, kendi uygulamanızdaki bir rota üzerinden. Numaranın webhook hedefini bu rotaya ayarlayın ve yola uzun, rastgele bir gizli anahtar koyun. Rota, Meta'nın doğrulama GET isteğini hub.challenge değerini düz metin olarak döndürerek yanıtlar, her POST isteğini kabul eder, hemen 200 döner ve işi kuyruğa alır; çünkü Meta yavaş yanıtları yeniden dener ve ajanı iki kez çalıştırırsınız.

Ardından bir worker, gönderenin numarasını ve metni payload'dan okur ve Runner.run çağırır. Kimliği gönderenin numarası olan bir oturum verin: SDK konuşmayı bu kimlik altında saklar, böylece aynı müşterinin sonraki mesajı kaldığı yerden devam eder ve iki müşteri asla aynı geçmişi paylaşmaz. Başlamak için SQLiteSession yeterlidir; birden fazla worker için SDK Redis ve SQLAlchemy oturumlarıyla da gelir.

Buradaki kimlik doğrulama, URL'deki gizli anahtardır. Meta gönderimleri Tech Provider'ın app secret'ı ile imzalar, bu yüzden imza başlığını müşteri doğrulayamaz.

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

Yanıtı neden ajan değil, kodunuz göndermeli?

Çünkü asla çiğnenmemesi gereken tek kural bir zamanlama kuralıdır ve kod bunu bir prompttan daha iyi uygular. Meta, müşteri yazdığında 24 saatlik bir müşteri hizmetleri penceresi açar. Pencere içinde serbest metin gider. Pencere dışında yalnızca onaylı bir şablon gider; serbest metin 131047 hatasıyla geri döner.

Az önce gelen mesaja yanıt veren bir worker her zaman pencerenin içindedir, bu yüzden result.final_output çıktısını metin olarak göndermek tasarım gereği güvenlidir. Daha sonra yapılan işler, ertesi sabahki bir takip ya da bir hatırlatma, ayrı bir yoldan geçmeli; bu yol şablon gönderir, asla serbest metin göndermez.

Ajanın yine de araçları olabilir. Bir sipariş veya randevu gibi şeyleri sorgulamak için ona function tool'lar verin, WhatsApp gönderimini ise worker'da tutun. Bu, erişim token'ını da modelin rastgele argümanlarla çağırabileceği her şeyin dışında tutar.

Ajan EasyCoexistence MCP sunucusunu kullanabilir mi?

Kullanabilir, MCPServerStreamableHttp ile, ama bir başlıktan daha fazla kurulumla. SDK, params["auth"] içinde bir Authorization başlığı ya da bir httpx.Auth kabul eder. EasyCoexistence MCP sunucusu, tarayıcıda oturum açıldıktan sonra dinamik istemci kaydı ve PKCE ile kendi OAuth token'larını verir, dolayısıyla statik bir anahtar yoktur. MCP Python SDK'sı, bu akışı PKCE ve token yenilemeyle çalıştıran bir HTTP kimlik doğrulama işleyicisi olan OAuthClientProvider ile gelir ve params["auth"] içine konan budur.

Ajanın kendi başına karar vermesi gerektiğinde işe yarar: bir numaranın sağlığını kontrol etmek, şablon durumunu okumak ya da araç açıklamalarındaki kurallara göre send_message ile send_template arasında seçim yapmak. Yalnızca yanıtlayan bir karşılama masası için yukarıdaki worker daha kısadır ve ters gidecek daha az şey barındırır.

Her iki durumda da webhook kalır. MCP istek ve yanıttan ibarettir ve bir müşterinin mesajı ajana yalnızca Meta'nın çağırdığı rota üzerinden ulaşabilir.

Yaygın hatalar

• Meta'ya 200 döndürmeden önce ajanı çalıştırmak. Yavaş yanıt yeniden denenir ve müşteri iki cevap alır.
• Her müşteri için tek bir oturum kullanmak. Oturumu gönderenin numarasına göre anahtarlayın, yoksa geçmişler karışır.
• Gecikmiş bir takibin serbest metin göndermesine izin vermek. 24 saat sonra 131047 hatasıyla başarısız olur; bunun yerine şablon gönderin.

Sık sorulan sorular

Okumaya devam edin