Letakkan ejen OpenAI Agents SDK pada WhatsApp

Bagaimanakah mesej WhatsApp menjadi satu larian ejen?

Melalui satu route dalam aplikasi anda sendiri yang dipanggil oleh Meta. Tetapkan destinasi webhook nombor itu kepadanya, dengan rahsia rawak yang panjang dalam laluan. Route itu menjawab GET pengesahan Meta dengan memulangkan hub.challenge sebagai teks biasa, menerima setiap POST, membalas 200 serta-merta dan meletakkan kerja dalam baris gilir, kerana Meta mencuba semula respons yang lambat dan anda akan menjalankan ejen dua kali.

Seorang pekerja kemudian membaca penghantar dan teks daripada payload lalu memanggil Runner.run. Hantar satu sesi yang id-nya ialah nombor penghantar: SDK menyimpan perbualan di bawah id itu, jadi mesej seterusnya daripada pelanggan yang sama menyambung dari tempat yang terakhir, dan dua pelanggan tidak pernah berkongsi sejarah. SQLiteSession mencukupi untuk bermula; SDK juga menyediakan sesi Redis dan SQLAlchemy untuk beberapa pekerja.

Rahsia dalam URL ialah pengesahan di sini. Meta menandatangani penghantaran dengan app secret milik Tech Provider, jadi pengepala tandatangan tidak dapat disahkan oleh pelanggan.

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

Mengapakah kod anda yang patut menghantar balasan, bukan ejen?

Kerana satu peraturan yang tidak boleh dilanggar ialah peraturan masa, dan kod menguatkuasakannya lebih baik daripada prompt. Meta membuka tetingkap khidmat pelanggan 24 jam apabila pelanggan menulis. Di dalamnya, teks bebas diterima. Di luarnya, hanya template yang diluluskan diterima, dan teks bebas akan dipulangkan dengan ralat 131047.

Pekerja yang menjawab mesej yang baru tiba sentiasa berada dalam tetingkap, jadi menghantar result.final_output sebagai teks adalah selamat secara reka bentuk. Kerja yang berlaku kemudian, seperti susulan pagi esok atau peringatan, patut melalui laluan berasingan yang menghantar template dan tidak pernah teks bebas.

Ejen masih boleh mempunyai alat. Berikan function tool untuk mencari maklumat, seperti pesanan atau tempahan, dan biarkan penghantaran WhatsApp dalam pekerja. Dengan cara itu token akses juga jauh daripada apa-apa yang boleh dipanggil oleh model dengan argumen sewenang-wenangnya.

Bolehkah ejen menggunakan pelayan MCP EasyCoexistence?

Boleh, melalui MCPServerStreamableHttp, tetapi penyediaannya lebih daripada sekadar pengepala. SDK menerima sama ada pengepala Authorization atau httpx.Auth dalam params["auth"]. Pelayan MCP EasyCoexistence mengeluarkan token OAuth sendiri selepas log masuk melalui pelayar, dengan pendaftaran klien dinamik dan PKCE, jadi kunci statik tidak wujud. SDK Python MCP menyediakan OAuthClientProvider, pengendali pengesahan HTTP yang menjalankan aliran itu dengan PKCE dan pembaharuan token, dan itulah yang diletakkan dalam params["auth"].

Ia berbaloi apabila ejen patut membuat keputusan sendiri: menyemak kesihatan nombor, membaca status template, atau memilih antara send_message dan send_template berdasarkan peraturan dalam huraian alat. Untuk kaunter hadapan yang hanya menjawab, pekerja di atas lebih ringkas dan kurang berisiko rosak.

Dalam kedua-dua keadaan, webhook tetap diperlukan. MCP ialah permintaan dan respons, dan mesej pelanggan hanya boleh sampai kepada ejen melalui route yang dipanggil oleh Meta.

Kesilapan biasa

• Menjalankan ejen sebelum memulangkan 200 kepada Meta. Respons yang lambat dicuba semula, dan pelanggan menerima dua jawapan.
• Menggunakan satu sesi untuk semua pelanggan. Kuncikan pada nombor penghantar, jika tidak sejarah akan bercampur.
• Membenarkan susulan yang tertunda menghantar teks bebas. Selepas 24 jam ia gagal dengan 131047; hantar template sebaliknya.

Soalan lazim

Teruskan membaca