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
- 偏好稱謂
- 目前使用者地理位置
專員事先不知道使用者與零售網站互動，不知道使用者地點為何，也不知道使用者購物車中的內容。原則上，從屬端應用程式可以知道這些值的所有或子集，並將要求中的這些值傳送給代理程式。以下是對代理程式提出之要求的範例，包括階段作業參數。
附註：
此範例說明此要求的外觀。它並非代表實作決策。"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”]
}
]
}
] 服務人員會回答：「保羅先生，今天在墨西哥坎昆的天氣如何？」
這些階段作業參數的另一個用途是在設定工具中的參數值。例如，SQL 查詢可以使用階段作業參數 {{sessionParam.CartID}} 來擷取購物車的內容：
Select productID, productName, productDescription,
productPrice from cartTable where cartID ==
{{sessionVariable.cartID}} 階段作業變數是由代理程式開發人員在建立其代理程式時所定義，而這些屬性的值則是由從屬端應用程式在建立或繼續階段作業時所設定。
建立新的階段作業變數時，您可以設定下列設定值：
| 設定 | 描述 |
|---|---|
| 必要變數 | 啟用即可讓代理程式的每個呼叫都需要此階段作業變數。停用會讓每次呼叫的階段作業變數成為選擇性。 |
| 日誌變數 | 啟用即可擷取日誌和追蹤中階段作業變數的值。停用可防止變數出現在日誌中。建議對含有機密資料的變數停用此設定。 |
| 名稱 | 階段作業變數的名稱。使用描述性名稱可讓您與其他使用者輕鬆決定變數的用途。 |
| 預設值 | 如果定義了預設值，如果呼叫呼叫中未定義另一個值，系統就會將預設值指派給階段作業變數。如果保留空白，則必須將值指派為呼叫的一部分。 |
| 描述 | 階段作業變數的描述。提供有用的描述，讓您和其他使用者能夠瞭解階段作業變數的功能。 |
範例：在工具組態中使用階段作業變數
您可以在 SQL 工具組態中使用階段作業變數作為 SQL 查詢本身的一部分。
在此範例中，使用階段作業變數 geo 來篩選 SQL 查詢的結果：
您可以在同一個查詢中使用階段作業變數和工具參數。在下面的範例中，當呼叫應用程式提供階段作業變數 geo 時，代理程式會設定 titleID 參數。
系統產生的階段作業變數
當遠端 MCP 伺服器連線至代理程式且 MCP 伺服器需要認證 (例如 Bearer 權杖) 時，會自動產生階段作業變數。
![將會顯示 [Add custom MCP Server] (新增自訂 MCP 伺服器) 對話方塊。警告訊息](img/sessionvariables-mcp1.png "將會顯示 [Add custom MCP Server] (新增自訂 MCP 伺服器) 對話方塊。警告訊息")
階段作業變數會保留 Bearer 權杖的值。無法變更此系統產生階段作業變數的名稱，且為必要變數。當 MCP 節點從工作區移除時，系統變數就會被刪除。
在「操場」中，您提供系統產生之階段作業變數的值。在此情況下，您必須提供 Bearer 權杖才能使用 MCP 伺服器。您可以選取在 MCP 節點組態期間使用的相同 (或其他) 記號。
部署代理程式時也同樣適用。您需要提供授權權杖。如需詳細資訊，請參閱從 Playground 指定值給階段作業變數。
範例：呼叫建置的端點時指派值給階段作業變數
在此範例中，您有兩個階段作業變數：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>" 
