Guides
Start typing to search…

Webhookの利用

このチャプターのゴール

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

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

Webhookとは？

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



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

例

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

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

Make
https://www.make.com/en

Zapier
https://zapier.com/

利用例:
https://note.com/makunugi/n/n198fd6c8bcb4
Notionに自動サマリーを記述するAIメンター
https://www.youtube.com/watch?v=3pD7jXqHV30


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

Webhookの３つの種類

miiboのWebhookには３つの種類があります。

  1. 通常のWebhook
  2. miiboエージェントと連携
  3. Custom Actionと連携
連携タイプ 用途
通常のWebhookWebhookを自由に設定できます。外部のAPIと連携を設定し、あらゆるAPIと疎通が可能です。
miiboエージェントmiiboで作成した別のエージェント呼び出して利用したいときに利用します。マルチエージェントの連携を行いたいときに有効です。

例: 専門知識を考えてもらうエージェントに質問し、応答結果を利用する
Custom Actionと連携miiboのCustom Actionで作成した機能を呼び出して利用します。


共通の設定内容

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の発火タイミングを設定できます。
発火タイミングは下記のいずれかです。

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

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つから選択可能です。

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

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


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

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


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


6. ペイロード(JSON)

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

7. APIのレスポンスをプロンプトに含める

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

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


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

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

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

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

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

Custom Actionとの連携

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

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



高度なカスタマイズ

ステートを利用する

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

  • 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}

Updated 2 months ago

Did this page help you?