このチャプターのゴール

Webhookによる外部API連携の方法が理解できている

※本チャプターでは、一部エンジニアリングの知識が必要になります。

Webhookとは？

Webhookとは、サービス(アプリケーション)の何らかのアクションを他のアプリケーションへリアルタイムに通知する仕組みのことです。特定のイベントが発生した際、指定したURLにリクエストを送信します。
この仕組みにより、miiboと様々なサービスやAPIを連携させることが可能になります。

miibo webhooksを使うことにより、簡単に下記のようなインテグレーションを実現できます。

例

miiboのエージェントが応答を返したタイミングで、Slackに通知を送る
miiboのエージェントが予定を聞いたら、カレンダーに予定を追加する
miiboのエージェントが特定のお問い合わせを受けたら、Slackに通知する
miiboのエージェントにツイートを行わせる
miiboのエージェントに対して外部のAPIから専門知識を与え、応答をカスタマイズする

MakeやZapierなどのIPaaSサービスと組み合わせると、様々なサービスと手軽に連携可能です。

MakMake：https://www.make.com/en

Zapier：https://zapier.com/

利用例：

Function callingをプログラミングなしで使い倒す方法

Notionに自動サマリーを記述するAIメンター

また、自分で作成した他のmiiboのエージェントを呼び出して応答を利用したり、Custom Action機能を利用して独自に実装した機能を呼び出すことも可能です。

Webhookの利用目的

Webhookを追加する際、以下の2つの利用目的から選択します：

アクションとして利用

ユーザーの発言やAIの判断に基づいて外部システムに対して操作を実行します。

例：メール送信、データベース更新、他システムへの通知等

インプットとして利用

外部API等から情報を取得し、その結果をAIの回答生成時にプロンプトに含めて活用します。
選択すると「プロンプト挿入時のプレフィックス」を入力できるようになります。

例：天気情報の取得、データベース検索結果の参照等

Webhookの連携タイプ

miiboのWebhookには4つの連携タイプがあります。

通常のWebhook
miiboエージェントと連携
Custom Actionと連携
MCP SSE (AI Server連携)

連携タイプ	用途
通常のWebhook	Webhookを自由に設定できます。外部のAPIと連携を設定し、あらゆるAPIと疎通が可能です。
miiboエージェント	miiboで作成した別のエージェント呼び出して利用したいときに利用します。マルチエージェントの連携を行いたいときに有効です。例: 専門知識を考えてもらうエージェントに質問し、応答結果を利用する
Custom Actionと連携	miiboのCustom Actionで作成した機能を呼び出して利用します。
MCP SSE (AI Server連携)	Model Context Protocol (MCP) を使用してAIサーバーと連携します。

共通の設定内容

1. Webhookの名前

Webhookの名前を設定します。Webhook一覧画面で表示されます。
動作には影響を与えません。

2. URL

Webhookのリクエストを送信する先のURLを設定します。
通常、外部APIのエンドポイントのになります。miiboエージェントとの連携とCustom Actionの連携を行う場合は、値は自動で挿入されます。

3. メソッド

Webhookのリクエストを送信する際のリクエストの方法を指定します。
連携するAPIの仕様に合わせて変更してください。 miiboエージェントとの連携やCustom Actionとの連携を行う場合は「POST」になります。(自動で挿入されます。)

4. 認証ヘッダー / ヘッダー

Webhookのリクエストを送信される場合のヘッダー情報を入力します。
miiboエージェントとの連携やCustom Actionとの連携を行う場合は自動で挿入されます。暗号化しセキュアに管理する情報に関しては、認証ヘッダーに入力してください。

5. トリガー

Webhookの発火タイミングを設定できます。
発火タイミングは下記のいずれかです。

AIによってタイミングを判断させる
ユーザーが発話をしたタイミング
エージェントが応答を返したタイミング

AIによってタイミングを判断させる (OpenAI モデルのみ)

AIによってタイミングを判断させ、Webhookを発火させます。
技術的には「Function Calling」という仕組みを利用します。プロンプトを記述し、そのタイミングに合致した場合に発火します。

ex:

「カレンダーに日程を登録したい会話がなされた」
「ユーザーが困っていそうだったら検索を行う」
「ユーザーから要望があった」

Functionの名前

Functionの名前を指定してください。発火時の「functionName」というパラメータになります。

必ずアルファベット表記である必要があります。

Functionの詳細

Functionの内容を記述します。どういった会話の内容をトリガーとしたいのか、詳細に記述してください。下記は、ユーザーからのお問い合わせを検知しています。

Function Callingのパラメータ

OpenAI APIの定めるFunction CallingのパラメーターのJSONを指定します。

OpenAI API公式のDoc

パラメータの例

    {
        "type": "object",
        "properties": {
            "question": {
                "type": "string",
                "description": "お問い合わせの質問を入力してください。"
            },
            "email": {
                "type": "string",
                "description": "ユーザーのメールアドレスです。"
            }
        },
        "required": [
            "question","email"
        ]
    }

type
「object」を指定してください。
properties:
必ず指定してください。この配下に複数のオブジェクトを指定できます。

                "question": {
                    "type": "string",
                    "description": "お問い合わせの質問を入力してください。"
                },

上記のquestionは任意のパラメータです。
任意のパラメータを設定し、descriptionに説明を記述しましょう。

required
requiredには、発火時に取得が必須なパラメータを指定します。

"required": [
    "question","email"
]

OpenAI APIでFunction Callingを利用する際に指定するJSONの内、「parameters」配下のオブジェクトを記載します。parameters　は含めないでください。

Function Callingで取得できるパラメータは、下記のようにWebhookのURLやペイロードに挿入できます。

(例) 「area」というパラメータをFunction Callingで取得した場合

@{area} という文字列を利用することで、パラメータで文字列をリプレイスすることができます。

URLへの挿入

https://xxxxx/com?area=@{area}

ペイロードへの挿入

{
  "area": "@{area}"
}

Function Callingで抽出されたパラメータは「呼び出しの結果をステートに保存する」をオンにしておくと、ステートに保存することもできます。

ユーザーの発話をトリガーにする

トリガーの種類で「ユーザーが発話をした」を選択します。

トリガーの条件は下記の5つから選択可能です。

何らかの発話があったら
下記の値のいずれかと一致したら
下記の値のいずれかが含まれたら
下記のステートが存在したら
下記のステートが存在しなかったら

エージェントの応答をトリガーにする

エージェントが応答をした際に発火します。トリガーの種類で「エージェントが応答を返した」を選択します。

トリガーの条件は下記の３つから選択可能です。

何らかの発話があったら
下記の値のいずれかと一致したら
下記の値のいずれかが含まれたら
下記のステートが存在したら
下記のステートが存在しなかったら

6. ペイロード(JSON)

ペイロードにJSONを指定すると、リクエスト時のBodyに任意のパラメータを追加できます。(JSON形式)
後述する変数が利用可能です。

インプットとして利用時の設定

プロンプト挿入時のプレフィックス

Webhookで得られた結果をプロンプトに挿入し、再度LLMによる応答の生成を行うことができます。
Webhookの結果を利用したRAGを構築することができます。

設定したプロンプトのプレフィックス(冒頭分)に続く形でWebhookのレスポンスが「ベースプロンプト」に挿入されます。

他のmiiboのエージェントとの連携

作成した他のエージェントを呼び出すことができます。
呼び出すエージェントを選択しましょう。

APIキーがすでに有効の場合は自動で値が挿入されます。発行されてない場合は「APIキーの発行」をクリックして発行してください。

ペイロードなどの設定も自動で挿入されます。カスタマイズも可能ですが、基本的にそのまま利用できます。

各種設定の仕組みは、「共通の設定」と同様です。

Custom Actionとの連携

作成したCustom Actionを呼び出すことができます。

ペイロードなどの設定も自動で挿入されます。

MCP SSE (AI Server連携) との連携

MCP SSE連携を使用すると、Model Context Protocol対応のAIサーバーと連携できます。

設定項目

URL (MCP Server)
「/mcp」を含む、末尾が「/sse」で終わるURLを指定します。例：https://example.com/mcp/xxxx/sse
MCP制御プロンプト
MCPのtool選定に必要な情報を補足します。この情報と会話履歴を加味してMCPの連携サービスが選定されます。プロンプトには、どういった際にどういったツールを呼ぶかを指定できます。

※ この機能はβ版のため、仕様が変更される可能性があります。

高度なカスタマイズ

ステートを利用する

下記の項目では、ステートや一部の特殊記号を利用することができます。

WebhookのURL
Webhookのペイロード(JSON)
Webhookをプロンプトで利用する場合のプレフィックス

ペイロード(JSON)の例

{
  "趣味":"#{hobby}"
}

プロンプトプレフィックスの例

下記は関連すルAPIから得られたレスポンスです。このレスポンスを参考に応答をしてください。
また、ユーザーの下記の情報を踏まえて応答を行なってください。

趣味: #{hobby}
困りごと: #{trouble}

その他の変数を利用する

下記の項目では、特別な変数を利用することができます。

WebhookのURL
Webhookのペイロード(JSON)
Webhookをプロンプトで利用する場合のプレフィックス

利用可能な変数。

変数	説明
@{query}	生成された検索クエリーで置き換えます
@{function_callingで取得した値}	Function Callingで取得したパラメータの値で置き換えます。	例: @{area}
@{utterance}	ユーザーの発話で置き換えます。
@{thirdPartyToken}	APIのリクエストやWebチャット画面に渡されたサードパーティートークンで置き換えます。	例: `{ "token" : "@{thirdPartyToken}"}`
@{sessionId}	現在のセッションのIDを格納します。ただし、会話の開始時の発話に対しては空欄が返ります。また、URLへの埋め込みはできません。
@{history}	会話の直近の履歴を埋め込むことができます。デフォルトのhistoryパラメータではなく、historyを任意の箇所に埋め込みたい時に利用します。	`"utterance" : "下記はユーザーの会話の履歴です。\n@{history}"```

例：ペイロードJSONにthirdPartyTokenを含める

{
  "token":"@{thirdPartyToken}"
}

例：WebhookのURLに生成されたクエリーを含める

https://example.xxx/xxx?query=@{query}

例：Funciton Callingで取得されたエリア名をURLに含める

https://example.xxx/xxx?area=@{area}