Boxのカスタム・スキルを作ってみる
watsonx OrchestrateはAIアシスタント構築のためのプラットフォームです。様々なアプリケーションと連携する1500以上のスキルが提供されます。Boxのスキルも提供され、例えば、フォルダの作成、フォルダ内のファイルの一覧の取得などの操作をチャットから呼び出して実行することが可能です。ですが、例えば、コラボレーターの追加などのスキルは現状提供されていません。今回は、コラボレーターを追加するスキルをカスタム・スキルとして実装し、watsonx Orchestrateから実行してみたいと思います。
Boxアプリケーションの作成
今回はOauthを用いてwatsonx Orchestrateを連携させるため、Box側にアプリケーションの設定が必要です。
Boxの開発者コンソールにログインし、マイアプリ＞アプリの新規作成 からカスタムアプリを作成します。認証方法としてはOauth2を選択してください。
クライアントIDとクライアント・シークレットが表示されるのでメモしておいてください。
リダイレクトURIとしては以下の値を追加してください。
https://dl.watson-orchestrate.ibm.com/mfe_connectors/api/v1/oauth/_callback
また、今回はコラボレーション設定を変更するので、「Boxに格納されているすべてのファイルとフォルダへの書き込み」にチェックを入れてください。
変更を保存してBox側の設定は終了です。
OpenAPI定義の作成
watsonx Orchestrateからスキルとして業務処理を呼び出す際には、OpenAPI定義を準備する必要があります。BoxのAPIのOpenAPI定義を探したのですが、見つからなかったため、watsonx Orchestrateが提供するOpenAPI Builderの機能を用いてAPI定義を作成しました。OpenaAPIはAPIの説明が記載されいているWebサイトのURLを指定することで生成AIがOpenAPI定義を作成してくれる機能です。完全に動作するものが生成されることはまれですが、ゼロから作成するよりははるかに簡単に作成することが可能です。
OpenAPIBuilderから以下のURLを指定して、生成してみました。
https://ja.developer.box.com/reference/post-collaborations/
ほぼ正しく生成できましたが、いくつか変更しました。
- integerやbooleanで返すべきサンプルの値が"1","true"などの文字列になっていたため修正
- セキュリティ設定が基本認証になっていたため、Oauthに変更
- created_byの戻りが間違っているので修正（Boxのドキュメントでは配列になっているのですが、実際にPostmanで試したところ、オブジェクトで返ってきていました)
参考までにセキュリティ設定の部分は以下の様に変更しました。他にも、メソッドのセキュリティ設定を行うことも忘れないでください。
スキルの追加/Enhance/Publish
watsonx Orchestrateのスキル・スタジオより、先ほど作成したOpenAPIファイルを読み込みます。問題が無ければ以下の様に検証をパスし、追加が出来るはずです。
次に、スキルのEnhanceとPublishを行います。ここでは、スキルの入出力パラメータの表示形式や、スキルを呼び出す際のフレーズの指定、次に実行するタスクの設定などを行うことが可能です。今回は詳細な設定は行いませんが、スキルを呼び出すフレーズを日本語で追加してみます。
Publishボタンをクリックして完了です。
アプリの接続
スキル・カタログから先ほど追加したスキルを検索、追加し、アプリの接続ボタンをクリックします。
Boxのログイン画面とアクセス許可画面が表示されるので許可します。ここで接続が拒否される場合は、Client_IDとClient_Secretが正しいことと、Box側でフォルダの書き込み権限が付与されていること、OpenAPIでのスコープの設定が正しいことなどを確認してください。
スキルの動作確認
では、チャット画面からスキルを呼び出してみましょう。
チャットに、「コラボレーションを追加したい」と入力すると以下の様なフォームが表示されるはずです。
必要な値を入力し、正しくスキルが動作することを確認します。
実は最初一部パラメータが必須項目とされていたために、正しく実行することができなかったため、スキルのエンハンス画面より必須のチェックを外しました。
実行時エラーの問題判別
その後別の問題が発生しましたが、原因はレスポンスの型定義と、実際の戻りの型の不一致でした。Postmanでレスポンスを確認したところ、Boxのドキュメントと異なっていたために生じた問題でした。現状、watsonx Orchestrateでは、エラーの詳細を確認したり、トレースを設定することができないため、実行時のエラーの問題を特定するには経験が必要です。今回のケースでは、呼び出し時にBox側の処理は完了していることはBox側で確認できたので、戻りのパースの問題だと思い確認したところ原因を特定することができました。
試しに戻りの型定義をシンプルなものにして動作確認することなども有用です。
その他の考慮点
今回はBoxが提供しているAPIをそのままスキルとして実装しました。そのため、FileIDを直接指定したりと、実際の業務で使用するにはあまり使い勝手のよくないスキルとなっています。実際の業務使用においては、例えばBoxのフォルダを選択できるようにしたり、目的によって自動的にファイル/フォルダIDが設定されるようにする等、工夫が必要です。（watsonx Orhcestrateでは、リストに動的に値をセットする機能や、パラメータとして初期値を与えるようなことも可能ですので、それらを活用して実装することになります。）
まとめ
いかがでしたでしょうか？今回はBoxのAPIをカスタム・スキルとして定義する手順について説明しました。
watsonx Orchestrateは事前定義された1500以上のスキルを提供しますが、実現したユースケースを全てカバーできるとは限りません。その場合にはカスタムスキルを定義することで対応可能です。スキルの定義は、初めて実装する場合にはかなり苦労しますが、慣れてくるとスムーズに定義することが可能です。また、製品としてもなるべく労力を少なくOpenAPI定義などを作成できるように、AIを用いた支援機能を提供しています。
watsonx Orchestrateに関する最新情報についてはこちらでも発信中ですので是非ご覧ください。