LangChain エージェントに WhatsApp 番号を持たせる

LangChain エージェントは WhatsApp のツールをどう読み込みますか？

LangChain の MCP クライアントである MCPAdapter を使います。MCP サーバーのツールが、通常の LangChain ツールとして create_agent に渡されます。langchain[mcp] のバージョン 1.4.0 以降が必要で、現在はベータ版です。

認証は FastMCP に任せます。クライアントで auth="oauth" を指定すると、探索、動的クライアント登録、ブラウザへのリダイレクト、トークン交換まで、OAuth 2.1 のフロー全体が実行されます。EasyCoexistence の MCP サーバーが求めるのはこの方式なので、キーを作成して貼り付ける手間はありません。既定ではトークンはメモリ上にのみ保持され、実行のたびにブラウザでの手順が繰り返されます。トークンストアを備えた FastMCP の OAuth プロバイダーを使うと、実行をまたいで保持できます。

読み込みが終わると、エージェントは各ツールを説明付きで認識します。最初に使うのは list_numbers です。ほかのすべてのツールが、これで得た connection_id を必要とするためです。そのあとに send_message、send_template、list_templates、get_number_health などが続きます。

from fastmcp.client import Client
from langchain.agents import create_agent
from langchain.mcp import MCPAdapter

URL = "https://easycoexistence.com/api/mcp"

async def build_agent(model: str):
    async with MCPAdapter(Client(URL, auth="oauth")) as adapter:
        tools = await adapter.list_tools()
        return create_agent(model, tools)

WhatsApp の受信メッセージは、どうやってエージェントに届きますか？

Webhook を使います。MCP では実現できないためです。MCP はリクエストとレスポンスのプロトコルなので、お客様が書き込んだときにサーバーからクライアントを起動する仕組みがありません。

番号の Webhook の送信先を、お客様自身のアプリケーション内のルートに設定します。URL パスには長いランダムなシークレットを含めてください。このルートは、Meta の検証用 GET にチャレンジ値をそのまま返し、各 POST を受け付けて、すぐに 200 を返したうえで処理をキューに入れます。その後ワーカーがペイロードから送信者とテキストを取り出し、エージェントを呼び出します。このとき送信者の電話番号をスレッド ID にすると、メモリがお客様ごとに分かれます。

検証には X-Hub-Signature-256 ヘッダーではなく、URL 内のシークレットを使ってください。Meta は Tech Provider のアプリシークレットで署名しますが、これは共有されないため、お客様側ではこのヘッダーを検証できません。

エージェントは MCP と Cloud API のどちらで送信すべきですか？

どちらでも動作します。違いは、ルールをどこで管理するかです。MCP ツールは、WhatsApp のルールを説明文に含んでいます。たとえば send_message は 24 時間ウィンドウ内でのみ使え、まだ書き込んでいない相手に連絡するには send_template を使う、といった内容です。モデルはこの説明を読んで、多くの場合は正しいツールを選びます。エージェントが自由に判断する場面では、これが役立ちます。

エージェントの役割が限られている場合は、番号のアクセストークンで Cloud API の messages エンドポイントに送信する自作のシンプルなツールのほうが簡単です。たとえば、いま書き込んだ相手にだけ返信する場合です。その場合、ウィンドウの確認はお客様のコード側に置くことになります。絶対に破ってはならないルールは、そこに置くべきです。ウィンドウ外でフリーテキストを送るとエラー 131047 が返り、お客様には何も届きません。

よくある間違い

• MCP が受信メッセージを届けてくれると期待すること。Webhook のルートがなければ、エージェントはお客様の発言を受け取れません。
• OAuth のトークンをサーバーのメモリ上に置いたままにすること。再起動のたびにブラウザでのサインインが必要になります。トークンストアで永続化してください。
• 全員のお客様で 1 つのスレッドを使うこと。エージェントのメモリは、送信者の電話番号をキーにしてください。

よくある質問

続きを読む