Beeuniを自社製品のエージェント用バックエンドとして使う

Beeuni APIまたはTypeScript SDKを使って、アプリケーションからエージェントのセッションを作成します。インターフェースとユーザーへの対応は自社製品が担い、Beeuniはエージェントのツールを実行して、メッセージやファイルを返します。

サプライヤーを比較する購買ツールを想像してみてください。ユーザーが商品と承認済みのサプライヤーを選ぶと、エージェントがその公開カタログページを訪れ、接続済みのドキュメントサービスから価格表を読み取り、比較シートを作成します。サインインやレビューはアプリケーションが担当し、Beeuniのセッションは資料を集めて比較を実行します。

インターフェースから送信するタスクを定義する

入力、許可する操作、出力形式、失敗するケースを列挙します。カタログの例では、承認済みサプライヤーのページ、接続済みカタログ文書への参照、比較する項目を指定します。商品ごとに1行を設け、提示価格と通貨、情報源への参照を含めるよう求めます。寸法が記載されていない場合は不明と明示する必要があります。このタスクでは発注を行わないものとします。

• アプリケーションの責任： ユーザーを認証し、各タスクにアクセスできる人を決め、入力を検証し、結果を表示します。
• プロジェクト設定： この種類の作業に必要なエージェント、モデル、スキル、使用を許可するツールを選びます。
• セッションでの作業： リクエストを送信し、進捗を追跡し、返されたメッセージと出力ファイルを確認します。

必要な情報源へのアクセスをセッションに付与する

タスクに必要なブラウザーとコネクターツールをプロジェクトに設定します。非公開のドキュメントサービスの場合は、アカウントを接続し、該当するコネクターへのアクセスをエージェントに許可します。リクエストにリンクを含めるだけでは、アクセスは許可されません。選択するアカウントとアクセスを許可する情報源は、タスクを送信した顧客に対応するものにしてください。アカウントのアクセスについては、コネクターガイドで説明しています。

これにより、エージェントはそれらのツールを通じて選択された文書を読み、公開されている商品ページを訪れ、商品コードや入り数を照合するスクリプトを作成できます。取得した値、情報源の場所、取得日時を結果と一緒に保存するよう指示してください。カタログを読み取れない場合や、ページで別のログインが必要な場合は、価格をでっち上げるのではなく、その情報が欠けていることをインターフェースに返します。

認証情報をサーバーに保持する

SDKガイドでは、@beeuni/sdkのインストール、クライアントの作成、リクエストの認証方法を紹介しています。APIキーはブラウザーのコードに含めず、サーバーに保持してください。

各顧客がアクセスできるBeeuniプロジェクトを決めます。必要に応じて顧客ごとにファイルと接続済みアカウントを分離し、リクエストを転送する前にサーバーでアクセス権を確認します。利用できるサインイン方法については、認証ガイドで説明しています。

進捗を表示し、再接続に対応する

SDKは、セッションの作成、準備完了の待機、リクエストの送信に対応しています。完全なサンプルでは、イベントの受信と応答の読み取りを扱っています。それらのイベントを使って、実際の進捗を表示してください。「サプライヤーのページを開いています」「商品を比較しています」「結果の準備ができました」は、それぞれ観測できる作業や状態に対応している必要があります。

比較ごとに、アプリケーション内にタスクレコードを作成します。選択した情報源への参照、要求された列、BeeuniのプロジェクトIDとセッションIDを保存し、出力先が利用可能になったらその場所も保存します。このレコードによって、レビュー画面とすでに進行中の作業を結び付けます。

Application task record — illustrative fields, not an SDK payload
app_task_id
approved_source_references
requested_columns
beeuni_project_id
beeuni_session_id
output_reference
review_status

ユーザーがサプライヤーのカタログを3つ選び、その後ページを再読み込みする場合を考えてみましょう。再読み込みされたインターフェースは、アプリケーションのタスクと、それに対応する既存のBeeuniセッションを検索します。保存された進捗を読み取り、その作業の追跡を再開します。ページを読み込むたびに別のセッションを作成すると、タスクが重複してしまいます。

サーバーが送信確認を受け取る前に、接続が切れることもあります。これは結果が不確かな状態であり、何も起きなかった証拠ではありません。リクエストを再送する前に、セッションを確認してください。それでも受理されたかどうか判断できない場合は、自動的に別の比較を開始するのではなく、不確かな状態であることを表示します。

アプリケーションで結果を確認する

カタログの比較では、必須の列、ファイルが読み取り可能かどうか、情報源への参照、対応付けできなかった商品を確認します。入り数の違いは、よくある落とし穴です。12個入り1箱の価格と1個当たりの価格を、そのまま比較することはできません。提示された金額と単位を保持し、情報源によって換算の根拠が裏付けられる場合に限り、単位をそろえた価格を追加してください。

レビュー画面では、ユーザーが価格の根拠となる情報源を開き、未解決の対応付けを確認できるようにする必要があります。一部の行にレビューが必要でも、ファイル自体は準備できている場合があります。アプリケーションでは、これらの状態を分けて管理してください。

文脈を失わずに結果を修正できるようにする

2社のサプライヤーが、同じ椅子に異なる名前を使っているとします。エージェントはそれらを別々の商品として扱いますが、レビュアーは同じ商品だと気付きます。有用な修正指示には、情報源の該当する2行と、意図する関係を含めます。たとえば「これらを同じ商品として比較してください。ただし、記載されている仕上げと入り数は別々に保持してください」と伝えます。「やり直して」とだけ送ると、何が間違っていたのかをエージェントが推測しなければなりません。

その修正指示をタスクに紐付けて記録し、以前の出力も引き続き利用できるようにします。次の結果では、商品の対応付けが修正される一方で、別の行が変更される可能性があります。修正後の比較と以前の版を表示し、レビュアーが両方を確認できるようにしてください。ダウンロードボタンでどの版を提供するかを決め、どの版が承認されたかを記録します。

承認によって、比較結果を社内の購買画面に公開することもあるでしょう。サプライヤーへの発注は、それ自体の権限と確認を必要とする別の操作です。エージェントに購買ツールへのアクセスを付与する前に、アプリケーションでその境界を定義してください。スプレッドシートが完成しただけで、自動的に発注されるようにしてはいけません。

1回のリクエストで開始できる作業量を決める

カタログの数や1回のリクエストで許可する作業量など、実用的な送信上限を設定します。短い価格表を3つ比較することと、商品アーカイブ全体を照合することは異なります。開始前に受け付け可能な範囲を表示し、ユーザーがリクエストを縮小したり、バックグラウンドジョブを選んだりできるようにします。

メッセージの長さから最終的な請求額を計算するのではなく、利用できる場合はプラットフォームから使用量と料金の情報を読み取ってください。自社製品で厳密な支出上限やキャンセルの保証が必要な場合は、連携の仕組みがそれをどのように実現しているかを確認します。カウントダウンや停止ボタンがあるだけでは、作業と課金が停止したことにはなりません。

手作業で確認できるケースで連携を試す

期待される解釈が分かっている少数のカタログを用意しておきます。具体的には、読みやすい価格表、読み取り不能なスキャン、2種類の通貨、入り数の不一致、明確に対応付けられない商品を含むものです。モデル、指示、プロジェクト設定を変更するときに、これらを使います。エージェントが未解決のまま残した内容も含め、出力された行と情報源への参照を比較してください。

また、実行中にページを離れてから戻り、結果が表示された後に修正指示を送ってみてください。どの出力がダウンロードされるか、別のサインイン済みユーザーがそのタスクにアクセスできるかも確認します。カタログが正しく解釈されていても、アプリケーションが誤った版を表示したり、本来アクセスできないアカウントに公開してしまったりする可能性があります。エージェントの結果と、その周囲のインターフェースを一緒にテストしてください。