Pasang agen OpenAI Agents SDK di WhatsApp

Bagaimana pesan WhatsApp menjadi satu proses agen?

Lewat sebuah route di aplikasi Anda sendiri yang dipanggil Meta. Arahkan tujuan webhook nomor ke route itu, dengan rahasia acak yang panjang di path-nya. Route menjawab GET verifikasi dari Meta dengan mengembalikan hub.challenge sebagai teks biasa, menerima setiap POST, langsung merespons 200 dan memasukkan pekerjaan ke antrean, karena Meta mencoba kembali respons yang lambat dan agen Anda akan berjalan dua kali.

Sebuah worker kemudian membaca pengirim dan teks dari payload lalu memanggil Runner.run. Berikan sesi yang id-nya adalah nomor pengirim: SDK menyimpan percakapan di bawah id itu, sehingga pesan berikutnya dari pelanggan yang sama melanjutkan dari titik terakhir, dan dua pelanggan tidak pernah berbagi riwayat. SQLiteSession sudah cukup untuk memulai; SDK juga menyediakan sesi Redis dan SQLAlchemy untuk beberapa worker.

Rahasia di URL berfungsi sebagai autentikasi di sini. Meta menandatangani pengiriman dengan app secret milik Tech Provider, sehingga pelanggan tidak bisa memvalidasi header tanda tangan.

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

Mengapa kode Anda yang mengirim balasan, bukan agen?

Karena satu aturan yang tidak boleh dilanggar adalah aturan waktu, dan kode menegakkannya lebih baik daripada prompt. Meta membuka jendela layanan pelanggan 24 jam saat pelanggan menulis. Di dalamnya, teks bebas diterima. Di luarnya, hanya template yang disetujui yang bisa dikirim, dan teks bebas akan kembali dengan kesalahan 131047.

Worker yang menjawab pesan yang baru saja tiba selalu berada di dalam jendela, jadi mengirim result.final_output sebagai teks aman secara desain. Pekerjaan yang berjalan belakangan, seperti tindak lanjut esok pagi atau pengingat, sebaiknya lewat jalur terpisah yang mengirim template dan tidak pernah teks bebas.

Agen tetap bisa memakai tool. Berikan function tool untuk mencari data, misalnya pesanan atau reservasi, dan biarkan pengiriman WhatsApp ada di worker. Dengan begitu token akses juga tidak berada dalam jangkauan apa pun yang bisa dipanggil model dengan argumen sembarang.

Bisakah agen memakai server MCP EasyCoexistence?

Bisa, lewat MCPServerStreamableHttp, dengan penyiapan yang lebih banyak daripada sekadar header. SDK menerima header Authorization atau httpx.Auth di params["auth"]. Server MCP EasyCoexistence menerbitkan token OAuth sendiri setelah login lewat browser, dengan dynamic client registration dan PKCE, jadi kunci statis tidak ada. MCP Python SDK menyediakan OAuthClientProvider, handler autentikasi HTTP yang menjalankan alur itu lengkap dengan PKCE dan pembaruan token, dan itulah yang dimasukkan ke params["auth"].

Layak dipakai bila agen harus memutuskan sendiri: memeriksa kesehatan sebuah nomor, membaca status template, atau memilih antara send_message dan send_template berdasarkan aturan di deskripsi tool. Untuk meja depan yang hanya menjawab, worker di atas lebih singkat dan lebih kecil kemungkinan bermasalah.

Bagaimanapun, webhook tetap diperlukan. MCP bekerja dengan permintaan dan respons, dan pesan pelanggan hanya bisa sampai ke agen lewat route yang dipanggil Meta.

Kesalahan umum

• Menjalankan agen sebelum mengembalikan 200 ke Meta. Respons yang lambat dicoba kembali, dan pelanggan menerima dua jawaban.
• Memakai satu sesi untuk semua pelanggan. Kunci pada nomor pengirim, atau riwayat akan bercampur.
• Membiarkan tindak lanjut yang tertunda mengirim teks bebas. Setelah 24 jam pengiriman gagal dengan 131047; kirim template.

Pertanyaan yang sering diajukan

Lanjut membaca