21 Variáveis de Sessão

Você pode usar variáveis de sessão personalizadas definidas pelo agente para fornecer pontos de dados contextuais adicionais aos seus agentes durante uma sessão do usuário.

O que são Variáveis de Sessão?

Variáveis de sessão personalizadas e definidas pelo agente fornecem pontos de dados contextuais adicionais ao agente durante uma sessão do usuário. As variáveis podem ser usadas para uma variedade de finalidades, incluindo a definição de valores de parâmetros em ferramentas, fornecendo instruções gerais a um agente e fornecendo informações contextuais sobre o chamador e/ou o aplicativo em que o agente está incorporado.

Aqui está um cenário simplificado em que estamos construindo um agente de suporte ao cliente. O agente de suporte ao cliente é integrado em um site de varejo. Quando um usuário faz login no site de varejo, as informações sobre esse usuário são capturadas pelo aplicativo cliente (userID, nome de usuário, localização geográfica, dispositivo usado, carrinho de compras, etc.) e essas informações podem ser usadas pelo agente de suporte downstream. Vejamos um exemplo de como esses parâmetros de sessão podem ser usados no campo de instruções do agente no 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}}?  

Três variáveis de sessão são usadas no exemplo acima:

• userName
• Saudação preferida
• atualUserGeo

O agente não tem conhecimento prévio do usuário que interage com o site de varejo, não sabe o que é a localização do usuário ou não tem contexto sobre o que está no carrinho de compras do usuário. Em princípio, o aplicativo cliente poderia conhecer todos ou um subconjunto desses valores e passar esses valores em uma solicitação para o agente. Veja um exemplo de como poderia ser uma solicitação ao agente, incluindo os parâmetros da sessão.

Observação:

Este exemplo ilustra a aparência dessa solicitação. Não representa uma decisão de implementação.

"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”]  
} 
  ]  
} 
] 

O agente responderia: "Olá, Sr. Paul, como está o tempo hoje em Cancún, Mx?"

Outro uso desses parâmetros de sessão é na definição de valores de parâmetro em ferramentas. Por exemplo, uma consulta SQL pode recuperar o conteúdo de um carrinho de compras usando o parâmetro de sessão {{sessionParam.CartID}} :

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

As variáveis de sessão são definidas pelo desenvolvedor do agente quando ele cria seus agentes e os valores desses atributos são definidos pelo aplicativo cliente quando uma sessão é criada ou retomada.

Você pode configurar as seguintes configurações ao criar uma nova variável de sessão:

Definição	Descrição
Variável obrigatória	Ative para tornar esta variável de sessão obrigatória para cada chamada de chamada do agente. A desativação torna a variável de sessão opcional para cada chamada de chamada.
Variável de log	Ative para capturar o valor da variável de sessão em logs e rastreamentos. A desativação impede que a variável apareça nos logs. Recomendamos desativar essa definição para variáveis com dados confidenciais.
Nome	Nome da variável de sessão. Use um nome descritivo para facilitar a determinação da finalidade da variável por você e outros usuários.
Valor padrão	Se definido, o valor padrão será atribuído à variável de sessão se outro valor não for definido na chamada de chamada. Se deixado em branco, um valor deverá ser atribuído como parte da chamada de chamada.
Descrição	Descrição da variável de sessão. Forneça uma descrição útil para que você e outros usuários possam entender a função da variável de sessão.

Exemplo: Usando Variáveis de Sessão na Configuração de Ferramentas

Você pode usar uma variável de sessão em uma configuração de ferramenta SQL como parte da própria consulta SQL.

Neste exemplo, a variável de sessão geo é usada para filtrar o resultado da consulta SQL:

Você pode usar variáveis de sessão e parâmetros de ferramenta dentro da mesma consulta. No exemplo abaixo, o parâmetro titleID é definido pelo agente enquanto a variável de sessão geo é fornecida pelo aplicativo de chamada.

Variáveis de Sessão Geradas pelo Sistema

As variáveis de sessão são geradas automaticamente quando um servidor MCP remoto está conectado a um agente e esse servidor MCP requer autenticação, como um token de portador.

A variável de sessão contém o valor do token do portador. O nome desta variável de sessão gerada pelo sistema não pode ser alterado e é uma variável obrigatória. A variável do sistema é excluída quando o nó MCP é removido da tela.

No Playground, você fornece um valor para a variável de sessão gerada pelo sistema. Nesse caso, você precisa fornecer um token ao portador para usar o servidor MCP. Você pode selecionar o mesmo (ou outro) token que usou durante a configuração do nó MCP.

O mesmo se aplica se você implantar o agente. Você precisará fornecer o token de autorização. Para obter mais informações, consulte Designar Valores a Variáveis de Sessão do Playground.

Exemplo: Designando Valores a Variáveis de Sessão ao Chamar um Ponto Final Implantado

Neste exemplo, você tem duas variáveis de sessão: userLocation e UserName, o aplicativo cliente está transmitindo valores de variáveis de sessão por meio do campo metadata do body. Demonstraremos como você pode designar valores por meio do Python e da CLI do OCI.

Se você usar a biblioteca de solicitações Python, o payload será o seguinte:

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>,} 
)  

Como alternativa, se você usar a CLI do OCI, o payload será o seguinte:

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>" 

Criar uma Variável de Sessão na Guia Variáveis do Agente

Você pode criar uma nova variável de sessão e adicioná-la ao seu agente na guia Variáveis.

1. Navegue até o agente ao qual você deseja adicionar uma variável de sessão.
2. Clique na guia Variáveis.
   
   

   

   
   
3. Clique em Adicionar variável de sessão.
   
   

   

   
   
4. Selecione esta opção se a variável de sessão for obrigatória.
5. Selecione se o valor da sua variável de sessão deve ser registrado em logs e rastreamentos. Deixe esta configuração desativada para dados confidenciais.
6. Forneça um nome e descrição significativos para sua variável de sessão.
7. Forneça um valor padrão para sua variável de sessão. O valor padrão será atribuído à variável de sessão se nenhum outro valor for atribuído como parte da chamada.
8. Clique em Criar.

Consulte Variáveis de Sessão nas Instruções de Fluxo do Agente

Você pode consultar variáveis de sessão nas instruções do agente e nas configurações da ferramenta, incluindo a consulta da ferramenta SQL e Prompt.

1. Navegue até o fluxo do agente.
2. Clique no nó da ferramenta SQL ou Prompt no Playground.
   
   

   

   
   
3. No campo Consulta, comece a digitar {{sessionvariables.
4. Selecione a variável de sessão na lista de variáveis de sessão existentes.

Exibir Agentes e Ferramentas usando uma Variável de Sessão

Você pode exibir uma lista de agentes e ferramentas usando uma variável de sessão específica na guia Variável do seu agente.

1. Navegue até um agente usando a variável de sessão para a qual deseja exibir agentes e ferramentas relacionados.
2. Clique na guia Variável.
3. Ao lado de Usado em: para sua variável de sessão, clique no menu suspenso. Uma lista de agentes e ferramentas que usam a variável de sessão é exibida.

Atribuir Valores a Variáveis de Sessão do Playground

Você pode atribuir valores a variáveis de sessão a qualquer momento na guia Playground.

1. Navegue até o seu agente.
2. Na parte superior do Playground, clique em Parâmetros de Sessão. Uma lista de todas as variáveis de sessão no seu agente é exibida.
   
   

   

   
   
3. Modifique suas variáveis de sessão. Depois de retomar a sessão do Playground, os últimos valores de variáveis de sessão atribuídos são usados.