ドコモAIエージェントAPI

連携ボットの使い方

はじめに

Agentcraft™ではエージェント作成用のGUIエディタを用意していますが、一問一答や簡単な条件分岐を使うための簡易なエディタです。「連携ボット」を利用することでより高度な対話を作成することができます。

連携ボットの基本仕様

連携ボットはドコモの自然対話プラットフォーム上で動作する、xAIMLのボットである必要があります。このボットを作成するためのリファレンスはxAIML-SUNABAにありますので、こちらを参照してください。
※ドコモAIエージェントAPIでのAIMLの推奨バージョン(ヘッダーに明記)は2.0.0〜2.5.0となります。
　SUNABAの推奨バージョン(2.x.0)とは異なりますのでご注意ください。
※連携ボットでエラーが発生する場合、まずはSUNABAでの動作確認やUTF-8のBOM有無をご確認ください。

連携ボットのインポート方法

Agentcraft™上で、以下の手順でインポートしてください。

  1. 追加したいエージェントを選択
  2. エージェント作成画面の左部にある「設定」ボタンを選択
  3. タブ一覧から「ボット一覧」を選択
  4. 「ボットの追加」ボタンを選択
  5. ボットの名前を入力(任意)
  6. 指定の形式のボットファイルを選択
  7. 追加ボタンを実行
  8. 新しいボットが一覧に表示されることを確認する

インポートファイルの構成について

Agentcraftでは、連携ボットとして以下の3パターンのファイルをインポートできます。

①xAIMLファイルのインポート

単体のxAIMLファイル(拡張子は .aiml)をインポートすることができます。インポートが失敗した場合、xAIMLファイルにエラーがある可能性がありますので、その際は文法やタグの使い方に誤りがないかどうかを確認してください。

②zipファイルのインポート

zipファイルでxAIMLファイルや設定ファイル、辞書ファイル等をまとめてインポートすることも可能です。フォルダ構成に関しては下記の構成を推奨します。

$ tree .
├── aiml
│   └── test.aiml
├── config.json
├── map
│   └── test.map
└── set
    └── test.set

・aimlファイル

対話ルールを記述するファイルです。xAIML形式で記述してください。

・configファイル

連携ボットの各種設定を記述するファイルです。下記のようなjsonを記述します。本項目に関しては外部連携方法で詳しく解説していますのでこちらを参照してください。

{
  "[サービス名]_Url": "http://xxx",
  "[サービス名]_ConnectionRetry": "3",
  "[サービス名]_ConnectionTimeoutSec": "5",
  "[サービス名]_ResponseTimeoutSec": "5",
  "DialogueTimeout": "300",
  "ReplyAgainTimeoutSec": "300"
}

・map,setファイル

連携ボット内で利用する辞書ファイルです。それぞれ拡張子が.mapと.setである必要があります。仕様に関してはXAIML-SUNABAのリファレンスを参照してください。

map仕様

set仕様

③CSVファイルのインポート

質問と回答のみを記述したシンプルな一問一答形式の対話をCSVファイルでインポートすることができます。 カンマ区切りのCSVで、左から”pattern”,”message”,”level”,”partial” を記述してください。

属性 説明 必須 値 初期値
pattern ユーザ発話 ○ 任意のテキスト
message 連携ボットの返答 ○ 任意のテキスト
level マッチングレベル exact ・・・完全一致
surface・・・読み一致
normalization・・・類義語
synonym・・・類義語
hypernym・・・上位概念
regex・・・正規表現
詳しい説明はこちら		 surface
partial 部分一致 true / false true

連携ボットの呼び出し方法

連携ボットはトピック内で呼び出して利用します。連携ボットが返却する発話を取得し、設定した箇所に展開します。利用できる箇所は前処理、条件、メッセージ、後処理です。

当該フォーム内で「$」を入力するとインポート済みの連携ボットの候補が表示されます。設定したい連携ボットを選択してください。

連携ボットとテキストの組み合わせについて

連携ボットと通常テキストは組み合わせて設定することも可能です。その際、連携ボットの文字列の後ろに半角スペースが挿入されますが、こちらはセパレータとして機能しているため、削除しないようにしてください。

（上級編）連携ボット内でのボット間連携について

連携ボットは、その中で更にボットを指定し、複数のボットを連携させてシナリオ構築することが可能です（ボット間連携）。

ボット間連携の設定方法

sraixタグを利用することで他ボットとの連携を実施します。sraixタグの詳細につきましては、こちらをご覧ください。

BotIDの指定

sraixタグではBotIDを指定する必要があります。
Agentcraftでは、このBotIDは連携ボットとしてインポートするタイミングで自動付与されるため、事前にボット間連携先のボットも全てAgentcraftへ連携ボットとしてインポートし、
”BotIDの確認方法”を参考にBotIDを確認し、指定してください。※SUNABAではBotIDを任意に指定可能ですが、Agentcraftに移行した際に変更が必要です。

連携ボットのメタ情報について

連携ボットとメタ情報をやり取りするためのIFについて解説します。

連携ボット側へのメタデータの送信

連携ボットに対してメタデータを送信するには、clientDataを利用します。

clientDataの利用方法に関しては、xAIML-SUNABAのリファレンスや、各SDKの仕様書を参照ください。

SDKを通じてクライアントから送信されるclientDataに関しては、連携ボット側でも同じように取得する事が可能となっています。

基本的にはclientDataを用いてメタデータを送信するようにしてください。

連携ボット側からメタデータの返却

フロントボット側で利用したいメタデータの返却方法について解説します。

predstoreオブジェクトの利用

データの受け渡しに関しては、xAIMLのpredstoreタグを用いたオブジェクトを利用します。predstoreタグの仕様はこちらを参照してください。

predstoreタグを使用することで、ボットの保存領域に設定した値を変更・参照することが可能です。

コマンド欄に呼び出したいBotIDを設定します。
コマンドについては下記のように記述します。

ボット間連携を用いて複数のボット連携を実現している場合、こちらで実装が必要になります。
predstoreを使ったメタデータの送信では、呼び出すボットのBotID指定が必要なため、
”BotIDの確認方法”を参考にBotIDを確認し、指定してください。

メタデータを扱うオブジェクト名

メタデータを扱うオブジェクト名は commandです。 下記のようにpredstoreタグ内に記述して利用します。下記は読み上げテキストのメタデータを操作する例です。

command.utterance=こんにちは

フロントボットが格納する基本的なメタデータの内容についてはメタデータ仕様を参照して下さい。

メタデータの形式

predstoreオブジェクトは基本的にはjson形式となります。各形式のオブジェクトのcommandオブジェクトへの代入方法は下記表を御覧ください。

文字列型

xAIML

<predstore>command.key=value</predstore>

出力されるメタデータ

{ 
  "command": { 
    "key": "value"
  }
}

JSON(Object)

xAIML

<predstore>
  command.key.setJson({"key2": "value2"}) 
</predstore>

出力されるメタデータ

{
  "command": { 
    "key": { 
      "key2": "value2"
    }
  }
}

JSON(Array)

xAIML

<predstore>
  command.key=$(value1 value2 value3)
</predstore>

出力されるメタデータ

{
  "command": {
    "key": [ "value1", "value2", "value3"]
  }
}

xAIMLタグ

xAIML

<predstore>
  command.key=<get name="variable"/>
</predstore>

出力されるメタデータ

{
  "command": {
    "key": "{タグの返却値}"
  }
}

※setJson関数でArrayを代入することはできません。

※predstoreタグ内で利用できるxAIMLタグはstar,sr,get,bot,matcherです。

BotIDの確認方法

sraixを使った連携ボット内でのボット間連携や、predstoreタグを使ったボット間のメタデータの取り扱いはBotIDを指定する必要があります。
Agentcraftでは、このBotIDは連携ボットとしてインポートするタイミングで自動付与され、ダウンロード時にIDが確認できようになっています。
そのため、BotIDを確認したい場合は、連携するボットをAgentcraftに一旦インポートし、それをダウンロードして確認してください。

赤枠内の文字列がBotIDになります。（※下図の場合は、245_170です）

注意事項

setJson関数の取り扱い

setJson関数はネストされたJSONオブジェクトをまとめてセットできる便利な関数ですが、set対象のオブジェクトを完全に上書きする破壊的メソッドです。

そのため、commandオブジェクトに対して直接setJsonすると、フロントボットで設定している基本データが上書きされるため、エージェントの挙動に不具合が出る可能性があります。

  • 一つ下の階層のオブジェクト(例: command.keyなど)を操作するようにすること
  • 必要がない限り基本データのオブジェクトを操作しないようにすること

利用する際は上記に注意してご利用ください。

Agentcraft™のUI側コマンドエリアとの関係性

Agentcraft™のUI側のコマンドエリアに記述しているパラメータと、連携ボット側で操作したパラメータが重複した場合、UI側のコマンドエリアに記述している内容が優先されます。

制限事項

対話の初期化について

自然対話エンジンのボット間連携の使用上、連携ボット側に対してinitTalkingFlagを送ることができません。よって、連携ボット側の対話を初期化したい場合は工夫が必要になります。

例えば、「initTalkingFlagにかかわらず、initを送ったときは必ず初期化する」という形で連携ボット側の初期化を実施しようとした場合、下記のようなAIMLを連携ボット側に記述する必要があります。

<!-- 
発話が来た際に必ず一番最初に実行され("_"、つまり最も優先度の高いtopic)、
発話内容が"init"だった場合(conditionの条件がinit)、
必ず対話状態を初期化してから遷移する(<srai><get name="input"/></srai>)
-->
<topic name="_">
<category>
  <pattern>_</pattern>
  <template>
    <condition name="input">
      <li value="init">
        <think>
          <set name="topic"/>
          <set name="id"/>
        </think>
       </li>
    </condition>
    <srai><get name="input"/></srai>
  </template>
</category>
</topic>

連携ボット側のcommandタグについて

連携ボット側で設定したcommandはフロントボット側で受け取ることができません。そのため、メタデータをやり取りしたい場合は predstoreを用いたデータの受け渡しを実装する必要があります。

連携ボットを利用した外部サービスとの連携

概要

外部のAPIとの接続は、連携ボットに連携機能を実装していくことで実現します。連携ボットに対して連携先のURLやパラメータを記述することで、対話が実行された時にAPIへの接続を実施します。

具体的な実装方法

自然対話エンジンの機能である、汎用CGSの機能を用いて外部APIとの連携を実装します。

リクエスト・レスポンス

xAIML-SUNABAの汎用CGSのリクエストとレスポンスを参照して下さい。

サンプルコード

<?xml version="1.0" encoding="UTF-8"?>
<aiml version="2.0.0" xmlns="http://www.nttdocomo.com/aiml/schema" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.nttdocomo.com/aiml/schema/AIML.xsd">
<category>
  <pattern>汎用CGS</pattern>
  <template>
    <ext name="multicgs">
      <arg name="request">
        {
          "method": "GET",
          "url": "https:// 接続先url/*",
          "header": {"HTTP-Version": "HTTP/1.1","Content-Type":"application/json;charset=utf-8"}
        }
      </arg>
    </ext>
　　<!--　実行結果をJSON形式で取得します。 -->
    <think><predstore>location.setJson(<get name="_ext_multicgs_body"/>)</predstore></think>
    <predstore>location.stateName</predstore>
  </template>
</category>
</aiml>

サンプルコード解説

※Categoryタグで囲まれた範囲が、１つの処理となります。１つのボットに複数のCategoryを記述することは可能ですが、明示的に呼び出さない限りCategoryが複数実行されることはありません。

※Patternタグには、発話とマッチングする条件を記述します。「*」はすべての発話を受け付けます。

※Templateタグには、処理内容を記述します。レスポンス内容だけではなく、条件分岐や変数の使用、計算などの処理も記述可能です。

※接続先URLは適宜置き換える必要があります。

※外部へのリクエストに対するレスポンスは、JSON形式で返却され、「_ext_[サービス名]_JSONキー」(本ケースの場合body)に格納されます。

※レスポンスから情報を取得するにはpredstoreを使用します。