api.aiのIntentsの概要

https://api.ai/docs/intents

# Intents
Intentは、ユーザが言うこととソフトウェアによって取られるべきアクションのマッピングを表す。
Intentインターフェースは下記のセクションを持つ:
- User says
- Action
- Reponse
- Contesxts

## User Says
### Example(`"`)とTemplate(`@`)モデル
User Saysに入力された各表現は2つのモデルのうち1つに紐付けられる。例えば、Example Mode（`"`アイコンで表現されている）かTemplate Mode（`@`アイコンで表現されている)

**Example**は自然言語で記述され、パラメータの値を抽出できるようにアノテーションが付けられる。
**Templates**はアノテーションの代わりにEntityへの直接参照を含む。Entityの名前は@の接頭辞がつく。
これらを切り替えるには、`"`や`@`アイコンをクリックする。
わかりやすく、機械学習のスピードが速いので、templatesよりもexamplesを使うことを推奨する。たくさんのexampleを追加することによって、Agentはより賢くなる。



### Example Annotation
**Annotation**は単語やフレーズとEntityを関連づける処理である。

#### Automatic Annotation
User saysセクションにexamplesを追加したとき、自動でアノテーションが付けられる。システムが単語やフレーズと既存のユーザやシステムエンティティやハイライトとの合致を検知する。検知された各Entityには自動的にパラメータ名が割り当てられる。


#### Editing Automated Examples
アノテーションがつけられたexamplesをクリックするとレビューウィンドウが開き、割り当てられたパラメータを編集することができる。また、Actionセクションのパラメーターテーブルからも編集することができる

レビューウィンドウとパラメータテーブル内の自動アノテーションの結果は同期される。レビューウィンドウ内で何かを変更した場合には、パラメータテーブルにおける対応する項目が自動的に更新される。逆もまた然り。

レビューウィンドウとパラメータテーブルの変更は、スコープが異なることに注意。

- レビューウィンドウ内の変更は同じアノテーションを含む他のexamplesに影響しない
- パラメータテーブル内の変更は同じアノテーションを持つ全てのUser saysのexamplesに適用される 

3種類の変更がある

- ことなるEntityをexamplesのアノテーションの一部に割り当てる
- パラメータ名を変更する
- アノテーションを削除する（単語とEntityの関連を削除する）


##### Local cahnges (in one example)
- 1つのexample内のアノテーションに異なるEntityを割り当てるために、ハイライトされたフレーズをクリックする。ポップアップが現れてEntityを選択できるようになる。
- 1つのexample内のパラメータ名を変更するためには、exampleをクリックしてレビューウィンドウ内でパラメータ名を編集する
- アノテーションを削除するには、ポップアップ内の瓶のアイコンをクリックするか、行内の☓アイコンをクリックする

##### Changes for entire intent (in the parameter table)
- 全てexamplesの同色でハイライトされた部分に異なるEntityを割り当てるには、パラメータテーブル内のパラメータをクリックする。ポップアップウィンドウの中で、既存のシステムEntityかデベロッパーEntityを選択する。
- 全てのexamplesのアノテーションに対するパラメータ名を削除するには、パラメータテーブル内でパラメータ名を編集する。
- 全てのexamplesから特定のアノテーションを削除するには、パラメータテーブル内の対応する行の右側にあるアイコンをクリックして'DELETE'を選択する。


#### Manual Annotation
必要であれば、単語やフレーズを選んで対応するEntityを手動で変更することができる。


### Searh Option
特定のexampleやtemplatesを見つけたい場合、User saysセクション内でキーワードを検索することができる


### Action
このセクションはアクション名のフィールドとパラメータテーブルからなる。
アクション名は手動で定義する。これは自前のあp類ケーションで特定のアクションを発火するためのトリガーとなる単語となる。
パラメータはUser saysセクションのexampleやtemplatesから自動的に入力されるか、手動で編集する。


### Response
このセクションでは、Agentのレスポンスを定義できる。これはIntentが発火したときに自身のアプリケーションによって提供される。

#### Text Response
Intentごとにテキストレスポンスの幾つかのバリエーションを加えてやることでAgentの雄弁さを向上できる。同じIntentが1回以上発火した場合、すべてのオプションが使われるまで、異なるテキストレスポンスが再現しなくなる。これはヒューマンライクな会話を実現する手助けになる。


##### References to Parameter Values
レスポンスはパラメータの値への参照を含むことができる。
パラメータテーブルでパラメータが与えられている場合、Text responseフィールド内で下記のフォーマットを使うことによってパラメータの値を参照できる
`$parameter_name`

これらは特別なパラメータの値のタイプで、自動的にはパラメータテーブルに現れない。

値の特別なタイプを参照する必要がある場合、パラメータテーブルに新しいパラメータを追加しなければならず、その値をマニュアルで定義する。そうすると`$parameter_name`としてレスポンス内から参照できる。

下記のフォーマットを使おう
- `$parameter_name.original` - パラメータのオリジナルの値を参照
- `$parameter_name_for_composite_entity.inner_alias` - 復号したEntityコンポーネントの1つの値を参照
- `#content_name.parameter_name` - 定義されたContextにおける他のIntent内のパラメータの値を参照


##### Cpecial Characters
$や#をAgentのテキストレスポンスに含めたい場合、後ろに続く値の周りをブラケットで囲む。例えば、`${100}`や`${$number}`といったように。ちょっと違う気もする。
中括弧をテキストレスポンスで使う場合は、2つ続ければ良い。`{{`→`{`


##### Handling Empty Parameter Values
Intentが発火した後に、いくつかパラメータがemptyでリターンできるような方法で設計されたIntentの場合、空の値を持つパラメータを参照を含むはテキストレスポンスは、テキストレスポンスとして与えられない。他のバリエーションを用意する必要がある。

例えば、あるIntentが2角パラメータを持ち、どちらの値も空でテキストレスポンス内で値を参照したい場合、少なくとも4つのバリエーションをテキストレスポンスに含める必要がある。

- どちらのパラメータも参照するパターン
- 1つめのパラメータを参照するパターン
- 2つめのパラメータを参照するパターン
- どちらのパラメータも参照しないパターン


##### Emojis
レスポンス内に絵文字を表示したい場合、希望する絵文字をResponseフィールド内にコピペすればOK。


#### Rich Messages
one-click integration（Facebook Messenger, Kik, Slack, Telegram）を使う場合、リッチメッセージ（画像、カード、クイックリプライ等）を直接intent内で定義できる。


## Contexts
Contextsは以前の会話や外部ソース（ユーザのプロフィールやデバイス情報など）から得られた情報を渡すために利用する。会話の流れの管理にも使える。

Intent名のすぐ下にある'Define context'をクリックすると、Contextを定義する事ができる。

Input ContextはIntentがマッチする前提を表す。

## Intents priority
Intentの優先度を設定することで、入力フレーズが複数のIntentにマッチした場合に1つをだけ選択されるようにすることができる。Intentの優先度はIntent名の横にある色付きドットをクリックすることで変更できる。（デフォルトはNormaltとなっている）

## Fallback Intents
Fallback Intentsはユーザの入力がIntentや有効なビルトインのSmall Talkにマッチしなかったときに発火する。

新しいAgentを作成したときにデフォルトのFallback Intentが自動生成され、編集することもできる。

偶発アクションやさまざまな入力Contextに対するレスポンスを作りたい場合、Fallback Intentを新たに追加することができる。各Fallback Intentに対して一意な入力インプットの集合体をセットする。

Fallback Intentの追加方法
- 左メニューからIntentをクリック
- CREATE INTENTボタンの右側にある3ドットボタンをクリックしてオプションを開く
- 'Create Fallback Intent'をクリック

Fallback Intentは、'Text response'内において下記のフォーマットによってcontextからのパラメータの値を参照することができる。
`#context_name.parameter_name`

特定のフレーズやバリエーションがfallbackの入力として分類されるようにしたい場合、通常のIntentを作成し、それらのフレーズを'User says'に入力する。そして、Fallback Intentの中に設定してあるものと同じアクションとText Responseを定義する。

## Referencing Parameter Values in Fallback Intents
省略

## Follow-up intents
自然な人間の会話には確認とフォローアップ（提案？）が多くある。例えば

User: Get me a cab.
Agent: Your cab an meet you at the corner of 5th and Broad street in 12 mins.
User: Ahh, can you repeat that please?

とか

User: I want 2 hamburgers and one Cola. 
Agent: Do you want fries with that? 
User: Sure, sounds good, thanks 

Follow-up Intentsはこの手の会話の流れを簡単に構築し、カスタマイズすることができる。API.AIのこの機能を使って、今動作している「親」Intentによって与えられた会話のシチュエーションを定義することができる。

手動でContextを定義することによって、このようなことができる。Follow-up Intentsは簡単な会話のプロセスを簡単に作ることができる。（現在、Follow-up Intentsは英語版のみで利用可能）

## Batch operations with intents
Intentsを他のAgentにコピーしたり移動したりするためには、Intentの一覧を表示してIntentのリストにマウスオーバーする。チェックボックスがIntent名の左側に表示されるので、一度に操作したいものにチェックを付け、オペレーションを選択する。


## Download and Upload Intents
省略