세션 변수

21 세션 변수

사용자 정의 에이전트 정의 세션 변수를 사용하여 사용자 세션 중에 에이전트에 추가 컨텍스트 데이터 포인트를 제공할 수 있습니다.

세션 변수란?

사용자 정의 에이전트 정의 세션 변수는 사용자 세션 중 에이전트에 추가 컨텍스트 데이터 포인트를 제공합니다. 이 변수는 도구에서 매개변수 값 설정, 에이전트에 전체 지침 제공, 에이전트가 포함된 호출자 및/또는 응용 프로그램에 대한 컨텍스트 정보 제공 등 다양한 용도로 사용할 수 있습니다.

다음은 고객 지원 에이전트를 구축하는 간단한 시나리오입니다. 고객 지원 에이전트는 소매 웹사이트 내에 통합되어 있습니다. 사용자가 소매 웹 사이트에 로그인하면 해당 사용자에 대한 정보가 클라이언트 응용 프로그램(userID, 사용자 이름, 지리적 위치, 사용된 장치, 장바구니 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}}?

위의 예제에서는 세 개의 세션 변수가 사용됩니다.

사용자 이름
선호 인사말
현재 사용자 지오

에이전트는 소매 웹 사이트와 상호 작용하는 사용자에 대한 사전 지식이 없으며 사용자 위치가 무엇인지 알지 못하거나 사용자의 쇼핑 카트에 있는 내용에 대한 컨텍스트가 없습니다. 원칙적으로 클라이언트 응용 프로그램은 이러한 값의 전부 또는 일부를 알고 이러한 값을 요청으로 에이전트에 전달할 수 있습니다. 다음은 세션 매개 변수를 포함하여 에이전트에 대한 요청이 어떻게 나타날 수 있는지에 대한 예입니다.

주:

이 예에서는 이 요청의 모양을 보여줍니다. 구현 결정을 대표하지 않습니다.

"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 query 자체의 일부로 사용할 수 있습니다.

이 예제에서 세션 변수 geo는 SQL 질의 결과를 필터링하는 데 사용됩니다.

에이전트 도구의 SQL 도구 창이 표시됩니다. 매개 변수 탭이 선택되고 사용자가 {{sessionvariables.ge를 입력하여 sessionvariables.geo를 선택합니다.

동일한 query 내에서 세션 변수와 도구 파라미터를 사용할 수 있습니다. 아래 예제에서 titleID 매개변수는 에이전트에 의해 설정되고 세션 변수 geo는 호출 응용 프로그램에 의해 제공됩니다.

$에이전트에 대한 SQL 도구 창이 표시됩니다. 매개변수 탭이 열려 있습니다. 질의 필드에서 사용자가 'where market_code= {{sessionvariables.geo}} 및 title = {{titleID}}'를 정의했습니다.$

시스템 생성 세션 변수

세션 변수는 원격 MCP 서버가 에이전트에 연결되어 있고 MCP 서버에 Bearer 토큰과 같은 인증이 필요할 때 자동으로 생성됩니다.

Add custom MCP server(사용자 정의 MCP 서버 추가) 대화 상자가 표시됩니다. 경고 메시지

세션 변수는 Bearer 토큰의 값을 보유합니다. 이 시스템 생성 세션 변수의 이름은 변경할 수 없으며 필수 변수입니다. MCP 노드가 캔버스에서 제거되면 시스템 변수가 삭제됩니다.

에이전트의 Variables 탭이 표시됩니다. sessionvariables.cred.mcp.GitHub.bearer에 대한 세부정보가 강조 표시됩니다.

플레이그라운드에서 시스템 생성 세션 변수에 대한 값을 제공합니다. 이 경우 MCP 서버를 사용하려면 Bearer 토큰을 제공해야 합니다. MCP 노드 구성 중 사용한 것과 동일한(또는 다른) 토큰을 선택할 수 있습니다.

세션 변수 대화상자가 표시됩니다. sessionvariables.cred.mcp.GitHub.bearer가 강조 표시되고 인증 토큰의 드롭다운 목록이 표시됩니다.

에이전트를 배치하는 경우에도 마찬가지입니다. 권한 부여 토큰을 제공해야 합니다. 자세한 내용은 재생장에서 세션 변수에 값 지정을 참조하십시오.

예: 배치된 끝점을 호출할 때 세션 변수에 값 지정

이 예제에는 두 개의 세션 변수가 있습니다. 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>"