21 会话变量
您可以使用自定义、代理定义的会话变量在用户会话期间向代理提供其他上下文数据点。
什么是会话变量？
定制的、代理定义的会话变量在用户会话期间向代理提供其他上下文数据点。这些变量可用于各种目的，包括设置工具中的参数值，向代理提供整体说明，以及提供有关调用者和/或嵌入代理的应用程序上下文信息。
这是一个简化的场景，我们正在建立一个客户支持代理。客户支持座席集成在零售网站中。用户登录零售网站时，客户端应用程序（用户 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}}? - userName
- PreferredSalutation
- 当前 UserGeo
座席事先不知道用户与零售网站交互，不知道用户位置是什么，也不知道用户购物车中的内容。原则上，客户端应用程序可以知道这些值的全部或部分，并将请求中的这些值传递给代理。下面是向代理发送请求的示例，包括会话参数。
注意：
此示例说明此请求的外观。它不代表执行决定。"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 坎昆的天气怎么样？”
这些会话参数的另一个用途是在工具中设置参数值。例如，SQL 查询可以使用会话参数 ｛{sessionParam.CartID}} 检索购物车的内容：
Select productID, productName, productDescription,
productPrice from cartTable where cartID ==
{{sessionVariable.cartID}} 会话变量由代理开发人员在创建其代理时定义，这些属性的值由客户机应用程序在创建或恢复会话时设置。
您可以在创建新会话变量时配置以下设置：
| 设置 | 说明 |
|---|---|
| 必需的变量 | 启用此项可使代理每次调用都需要此会话变量。禁用会使会话变量对于每个调用都是可选的。 |
| 日志变量 | 启用以在日志和跟踪中捕获会话变量的值。禁用可防止变量出现在日志中。我们建议为具有敏感数据的变量禁用此设置。 |
| 名称 | 会话变量的名称。使用描述性名称可使您和其他用户轻松确定变量的用途。 |
| 默认值 | 如果未在调用调用中定义其他值，则会为会话变量指定默认值。如果留空，则必须将值分配为调用调用的一部分。 |
| 说明 | 会话变量的说明。提供有用的说明，以便您和其他用户能够了解会话变量的功能。 |
示例：在工具配置中使用会话变量
可以在 SQL 工具配置中使用会话变量作为 SQL 查询本身的一部分。
在此示例中，会话变量 geo 用于筛选 SQL 查询的结果：
您可以在同一查询中使用会话变量和工具参数。在下面的示例中，titleID 参数由代理设置，而会话变量 geo 由调用应用程序提供。
系统生成的会话变量
会话变量在远程 MCP 服务器连接到代理且 MCP 服务器需要验证（如 Bearer 标记）时自动生成。
会话变量保存 Bearer 令牌的值。无法更改此系统生成的会话变量的名称，该变量是必需的变量。从画布中删除 MCP 节点时，将删除系统变量。
在 Playground 中，为系统生成的会话变量提供值。在这种情况下，需要提供 Bearer 标记才能使用 MCP 服务器。您可以选择在 MCP 节点配置期间使用的相同（或不同的）标记。
在部署代理时也是如此。您需要提供授权令牌。有关更多信息，请参阅从操场将值分配给会话变量。
示例：调用已部署端点时为会话变量赋值
在此示例中，有两个会话变量：userLocation 和 UserName，客户机应用程序正在通过 body 的 metadata 字段传递会话变量值。我们将演示如何通过 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>" 
请参阅代理流说明中的会话变量
您可以在代理说明和工具配置（包括 SQL 和提示工具查询）中引用会话变量。
- 单击“Playground（操场）”中的“SQL or Prompt（SQL 或提示）”工具节点。
