v2 API へのマイグレーション

アシスタントとスキルの使用をサポートする watsonx Assistant v2 ランタイムAPIは、2018年11月に導入された。この API には、v1 ランタイム API に勝る大きな利点があります。例えば、自動の状態管理、簡単なデプロイメント、スキルのバージョン管理、検索スキルなどの新機能を利用できる点です。

v2 API は、サービス・プランに関係なく、追加コストなしですべてのユーザーが使用できます。

現在、v2 API は、既存アシスタントとのランタイムの対話のみをサポートしています。ワークスペースを作成または変更するオーサリング・アプリケーションは、引き続き v1 API を使用する必要があります。

概要

v2 API を使用すると、クライアント・アプリはアシスタントと通信します。アシスタントは、自動状態管理、スキルのバージョン管理、デプロイメントの容易性など、いくつかの機能を提供するオーケストレーション層です。

アシスタントとのすべての通信は、_セッション_のコンテキスト内で行われます。これにより、会話の期間中、会話状態が維持されます。状態データ (ダイアログまたはクライアント・アプリケーションで定義されているコンテキスト変数を含む) は watsonx Assistant によって自動的に保管されるので、アプリケーション側でアクションを取る必要はありません。

状態データは、セッションを明示的に削除するか、アクティブでないためにセッションがタイムアウトになるまで保持されます。

自分で状態を管理する場合、v2 API には、v1 API のように機能するステートレス message メソッドも用意されています。ステートレス message メソッドを使用する場合、セッションを明示的に作成または削除する必要はなく、コンテキストの保守はアプリの責任となります。ステートレス message メソッドについて詳しくは、「API リファレンス」を参照してください。

v1 API を使用してユーザー入力をワークスペースに直接送信する既存のアプリケーションがある場合、そのアプリケーションを v2 API を使用するようにマイグレーションする作業は簡単です。

Assistant ID

v2 ランタイム API は、アシスタントにメッセージを送信します。 **「アシスタント設定 (Assistant Settings)」**ページで、アシスタント ID を見つけます。アプリケーションは、この ID を使用してアシスタントと通信します。サービス資格情報は、v1 API でも v2 API でも同じです。

現在、アシスタント ID を検索するための API サポートはありません。アシスタント ID を見つけるには、watsonx Assistant ユーザー・インターフェースを使用する必要があります。

v2 ランタイム API の呼び出し

アシスタントを作成した後、 v1 ランタイムAPIの代わりに v2 ランタイムAPIを使用するようにクライアントアプリケーションを更新することができます。

会話で最初のメッセージを送信する前に、 v2 Create a session メソッドを使用してセッションを作成する。返されたセッション ID を保存します。

service
.createSession({
 assistant_id: assistantId,
})
.then(res => {
 sessionId = res.session_id;
})

session_id = service.create_session(
   assistant_id = assistant_id
).get_result()['session_id']

CreateSessionOptions createSessionOptions = new CreateSessionOptions.Builder(assistantId).build();
SessionResponse session = service.createSession(createSessionOptions).execute().getResult();
String sessionId = session.getSessionId();

アシスタントにユーザー入力を送信するには、 v2 Send user input to assistant メソッドを使用します。 v1 API の場合のようにワークスペース ID を指定するのではなく、アシスタント ID とセッション ID を指定します。

service
  .message({
    assistant_id: assistantId,
    session_id: sessionId,
    input: messageInput
  })

 response = service.message(
    assistant_id,
    session_id,
    input = message_input
 ).get_result()

 MessageInput input = new MessageInput.Builder().text(inputText).build();
 MessageOptions messageOptions = new MessageOptions.Builder(assistantId, sessionId)
   .input(input)
   .build();
 MessageResponse response = service.message(messageOptions)
   .execute()
   .getResult();

基本的なメッセージ構造は変わっていません。特に、ユーザー入力は以前と変わらず input.text として送信されます。

会話終了後、セッションを削除するには、 v2 Delete session メソッドを使用します。

service
  .deleteSession({
    assistant_id: assistantId,
    session_id: sessionId,
  })

service.delete_session(
    assistant_id = assistant_id,
    session_id = session_id
)

DeleteSessionOptions deleteSessionOptions = new DeleteSessionOptions.Builder(assistantId, sessionId
  .build();
service.deleteSession(deleteSessionOptions).execute();

セッションを明示的に削除しない場合は、構成されたタイムアウト期間が経過した後に自動的に削除されますタイムアウト期間は、プランによって異なります。

単純なクライアント・アプリケーションの文脈で v2 APIの例を見るには、 APIを使用したカスタム・クライアントの構築を参照してください。

v2 の応答形式の処理

アプリケーションでアクセスする必要がある応答の部分によっては、v2 ランタイムの応答形式を処理するようにアプリケーションを更新しなければならない場合があります。

text オブジェクトには、以前と変わらず、あらゆる応答タイプ (option や output.generic など) の出力が返されます。このような応答を処理するアプリケーション・コードは、変更せずに使用できるはずです。
検出されたインテントおよびエンティティーは、応答 JSON のルートにではなく、output オブジェクトの一部として返されるようになりました。
会話コンテキストは、次の 2 つのオブジェクトに分類されるようになりました。
- グローバルコンテキストには、アシスタントのすべてのスキルで共有されるシステムレベルのコンテキストデータが含まれます。
- スキルコンテキストには、ダイアログスキルで使用されるユーザ定義のコンテキスト変数が含まれます。
ただし、会話コンテキストを含め、状態データはアシスタントによって保持されるようになったので、アプリケーションからコンテキストにアクセスする必要はまったくない可能性があります (アシスタントに状態を保持させるを参照)。

v2 レスポンスフォーマットの完全な文書については、 v2 API Referenceを参照のこと。

アシスタントに状態を保持させる

ほとんどのアプリケーションでは、状態を維持するために含まれるコードを削除できるようになった。コンテキストを保存し、会話の順番が来るたびに watsonx Assistant にコンテキストを送り返す必要はなくなりました。コンテキストは watsonx Assistant によって自動的に保持され、以前と同様にダイアログからアクセスできます。

v2 API では、デフォルトではクライアント・アプリケーションへの応答にコンテキストが含まれないことに注意してください。ただし、それでも必要に応じてコードからコンテキスト変数にアクセスできます。

現在でも、context オブジェクトをメッセージ入力の一部として送信することは可能です。含めるコンテキスト変数は、 watsonx Assistantが保持するコンテキストの一部として保存されます。 (送信するコンテキスト変数がコンテキストに既に存在する場合は、それまで保管されていた値が新しい値で上書きされます)。

送信するコンテキスト・オブジェクトが v2 フォーマットに準拠していることを確認してください。アプリケーションから送信されるユーザー定義のコンテキスト変数は、すべてスキルコンテキストの一部である必要があります。通常、設定する必要がある唯一のグローバルコンテキスト変数は、プラスプランとプレミアムプランで課金目的で使用される system.user_id です。
現在でも、グローバル・コンテキストとスキル・コンテキストのコンテキスト変数を取得することは可能です。 context オブジェクトをメッセージ応答に含めるには、メッセージ入力オプションで return_context プロパティーを使用します。詳しくは、ダイアログでのコンテキスト・データへのアクセスを参照してください。