セッション変数

21 セッション変数

カスタムのエージェント定義セッション変数を使用して、ユーザー・セッション中にエージェントに追加のコンテキスト・データ・ポイントを提供できます。

セッション変数とは

カスタムのエージェント定義セッション変数は、ユーザー・セッション中にエージェントに追加のコンテキスト・データポイントを提供します。変数は、ツールでのパラメータ値の設定、エージェントへの全体的な指示の提供、コール元やエージェントが埋め込まれているアプリケーションに関するコンテキスト情報の提供など、様々な目的で使用できます。

カスタマー・サポート・エージェントを構築する簡略化されたシナリオを次に示します。カスタマー・サポート・エージェントは、小売Webサイトに統合されています。ユーザーが小売Webサイトにログインすると、そのユーザーに関する情報がクライアント・アプリケーション(ユーザーID、ユーザー名、ジオロケーション、使用デバイス、ショッピング・カートIDなど)によって取得され、その情報はダウンストリーム・サポート・エージェントが使用できます。AIDPのエージェント指示フィールド内でこれらのセッション・パラメータを使用する方法の例を見てみましょう。

You are a customer support agent for the retail website belts-and-buckles.com, specializing in the sales of belts and buckles. Your objective is to answer questions that customers have about their current and past orders, answer questions about items they put in their shopping cart, and answer general questions about belts-and-buckles.com.  
A few guidelines before your start:  
    You are interacting with user {{sessionVariable.userName}}. Always start with a welcome message: Hello {{sessionVariable.preferredSalutation}} {{sessionVariable.userName}}! What’s the weather like today in {{sessionVariable.currentUserGeo}}?

前述の例では、3つのセッション変数が使用されています。

userName
優先挨拶
現在のユーザー位置

エージェントは、ユーザーが小売Webサイトとやり取りしていること、ユーザーのロケーションが何であるか、またはユーザーのショッピング・カートの内容に関するコンテキストがないことを事前に把握していません。原則として、クライアント・アプリケーションはこれらの値のすべてまたはサブセットを認識し、リクエスト内の値をエージェントに渡すことができます。次に、セッション・パラメータなど、エージェントへのリクエストの外観の例を示します。

ノート:

次の例では、このリクエストの外観を説明します。これは、実装決定の代理ではありません。

"input": [  
{ "role": "user", 
         "content": [  
{ "type": "input_text”,  
	  "text": "What material is the belt Mr Outcast made of?", 
	  “variables”: [“userName”: “Paul”, “preferredSalutation”: “Hon”, “cartID”: NULL, “currentUserGeo”: “Cancun, MX”]  
} 
  ]  
} 
]

「こんにちは、ポールさん、今日のカンクン、Mxの天気はどうですか?」と返答します。

これらのセッション・パラメータのもう1つの用途は、ツールでパラメータ値を設定することです。たとえば、SQL問合せでは、セッション・パラメータ{{sessionParam.CartID}}}を使用してショッピング・カートの内容を取得できます。

Select productID, productName, productDescription, 
productPrice from cartTable where cartID == 
{{sessionVariable.cartID}}

セッション変数は、エージェントの作成時にエージェント開発者によって定義され、セッションの作成時または再開時にクライアント・アプリケーションによってこれらの属性の値が設定されます。

新しいセッション変数を作成するときに、次の設定を構成できます。

設定	説明
必須変数	エージェントの呼出しごとに、このセッション変数を必須にできるようにします。無効化すると、起動コールごとにセッション変数がオプションになります。
ログ変数	ログおよびトレースでセッション変数の値を取得できるようにします。無効にすると、変数がログに表示されなくなります。この設定は、機密データを含む変数に対して無効にすることをお薦めします。
名前	セッション変数の名前です。わかりやすい名前を使用して、自分および他のユーザーが変数の目的を簡単に判断できるようにします。
デフォルト値	定義されている場合、呼出しコールで別の値が定義されていない場合は、デフォルト値がセッション変数に割り当てられます。空白のままにした場合は、呼出しコールの一部として値を割り当てる必要があります。
説明	セッション変数の説明。自分および他のユーザーがセッション変数の機能を理解できるように、役立つ説明を入力します。

例: ツール構成でのセッション変数の使用

SQL問合せ自体の一部として、SQLツール構成でセッション変数を使用できます。

この例では、セッション変数geoを使用してSQL問合せの結果をフィルタ処理します。

エージェント・ツールのSQLツール・ウィンドウが表示されます。「パラメータ」タブが選択され、ユーザーが{{sessionvariables.ge}と入力してsessionvariables.geoを選択します。

同じ問合せ内でセッション変数およびツール・パラメータを使用できます。次の例では、titleIDパラメータがエージェントによって設定され、セッション変数geoがコール側アプリケーションによって指定されています。

$エージェントのSQLツール・ウィンドウが表示されます。「パラメータ」タブが開きます。問合せフィールドで、ユーザーは'where market_code= {{sessionvariables.geo}}およびtitle = {{titleID}}を定義しました。$

システム生成のセッション変数

セッション変数は、リモートMCPサーバーがエージェントに接続され、MCPサーバーがBearerトークンなどの認証を必要とするときに自動的に生成されます。

session変数は、Bearerトークンの値を保持します。このシステム生成セッション変数の名前は変更できず、必須変数です。システム変数は、MCPノードがキャンバスから削除されると削除されます。

エージェントの「変数」タブが表示されます。sessionvariables.cred.mcp.GitHub.bearerの詳細が強調表示されています。

プレイグラウンドでは、システム生成のセッション変数の値を指定します。この場合、MCPサーバーを使用するにはBearerトークンを提供する必要があります。MCPノードの構成時に使用したものと同じ(または異なる)トークンを選択できます。

「セッション変数」ダイアログが表示されます。sessionvariables.cred.mcp.GitHub.bearerが強調表示され、認証トークンのドロップダウン・リストが表示されます。

エージェントをデプロイする場合も同様です。認可トークンを指定する必要があります。詳細は、「プレイグラウンドからのセッション変数への値の割当て」を参照してください。

例: デプロイ済エンドポイントのコール時のセッション変数への値の割当て

この例では、クライアント・アプリケーションがbodyのmetadataフィールドを介してセッション変数値を渡すuserLocationとUserNameの2つのセッション変数があります。PythonおよびOCI CLIを使用して値を割り当てる方法をデモンストレーションします。

Pythonリクエスト・ライブラリを使用する場合、ペイロードは次のようになります。

body = { 

            "isStreamEnabled" : False, 

            "trace" : False, 
            "input" :[{ 
                "role":"User", 
                "content":[{ 
                    "type" : "INPUT_TEXT", 
                    "text" : “Hello how can you help me?”                  
                }] 
            }], 

            "metadata": { 
            "sessionvariables.userLocation": "Canada",  
            "sessionvariables.UserName": "George" 
        } 
        } 

response = requests.post( 
url = <insert-chat-url>,  
params = None,  
auth = <insert-oci-signer>, 
json = body, 
headers={“x-session-id": <insert-a-session-key>,} 
)

または、OCI CLIを使用する場合、ペイロードは次のようになります。

oci raw-request \ 
  --http-method POST \ 
  --auth security_token \ 
  --request-body '{ 
    "isStreamEnabled": false, 
    "input": [ 
      { 
        "role": "user", 
        "content": [ 
          { 
            "type": "INPUT_TEXT", 
            "text": "Hello how can you help me?" 
          } 
        ] 
      } 
    ], 
    "metadata": { 
      "sessionvariables.userName": "George", 
      "sessionvariables.userLocation": "Canada"}" 
    } 
  }' \ 
  --request-headers '{ 
    "x-session-id": "george-session-may11" 
  }' \ 
  --target-uri "<insert-your-agent-flow-uri>"