OpenAI Agents SDK のエージェントを WhatsApp で動かす

WhatsApp のメッセージはどのようにエージェントの実行になりますか？

Meta が呼び出す、自社アプリ内のルートを経由します。電話番号の Webhook の送信先にそのルートを設定し、パスには長くランダムなシークレットを含めてください。ルートは、Meta の検証用 GET に対して 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 をテキストとして送る方法は構造上安全です。翌朝のフォローアップやリマインダーなど、後から行う処理は別の経路に分け、フリーテキストではなく必ずメッセージテンプレートを送ってください。

エージェントにツールを持たせることもできます。注文や予約の照会などにはファンクションツールを渡し、WhatsApp への送信はワーカー側に残してください。そうすれば、モデルが任意の引数で呼び出せるものの中に、アクセストークンが入りません。

エージェントから EasyCoexistence の MCP サーバーを使えますか？

使えます。MCPServerStreamableHttp を通じて接続できますが、ヘッダーを足すだけより設定は多くなります。SDK は params["auth"] に Authorization ヘッダーまたは httpx.Auth を受け付けます。EasyCoexistence の MCP サーバーは、ブラウザーでのサインイン後に動的クライアント登録と PKCE を使って独自の OAuth トークンを発行するため、固定のキーはありません。MCP Python SDK には、PKCE とトークン更新を含むそのフローを実行する HTTP 認証ハンドラーの OAuthClientProvider があり、これを params["auth"] に渡します。

この方法が向くのは、エージェント自身に判断させたい場合です。たとえば、番号の接続状態を確認する、メッセージテンプレートの状態を読む、ツールの説明にあるルールに従って send_message と send_template を選ぶ、といった用途です。応答するだけの窓口であれば、前述のワーカーのほうが短く済み、問題も起きにくくなります。

どちらの方法でも Webhook は必要です。MCP はリクエストとレスポンスの仕組みであり、顧客のメッセージがエージェントに届く経路は、Meta が呼び出すルートだけだからです。

よくある間違い

• Meta に 200 を返す前にエージェントを実行する。遅い応答はリトライされ、顧客に回答が 2 回届きます。
• 全顧客で 1 つのセッションを使う。送信者の番号をキーにしないと、履歴が混ざります。
• 遅れて送るフォローアップでフリーテキストを使う。24 時間を過ぎると 131047 で失敗するため、メッセージテンプレートを送ってください。

よくある質問

続きを読む