Variáveis

As variáveis são usadas para armazenar e recuperar dados em várias rodadas de conversa. Elas permitem que os agentes se lembrem de informações e mantenham o contexto. Ao escrever instruções de comando para seu agente, você pode incluir referências a essas variáveis.

Tipos de variáveis

O criador de agentes é compatível com dois tipos de variáveis nas instruções: estáticas e dinâmicas.

A escolha do tipo certo depende de se o valor da variável precisa mudar durante a sessão do usuário e de quanto você precisa otimizar para latência.

Variáveis estáticas

As variáveis estáticas são compiladas diretamente no comando do agente antes da chamada do modelo. Elas funcionam como uma substituição direta de texto individual e são atualizadas com pouca frequência.

Variáveis estáticas maximizam a qualidade do seguimento de instruções e são adequadas para instruções condicionais em muitos cenários. Use variáveis estáticas para dados de configuração, regras de negócios rígidas ou grandes payloads contextuais que não mudam durante uma única conversa.

Para fazer referência a uma variável estática por nome nas instruções, use chaves duplas: {{variable_name}}.

Por exemplo, se você estiver criando um agente de varejo com um catálogo de produtos grande e estático, poderá usar uma instrução como:

You are a helpful shopping assistant.
Please follow these business rules: {{business_rules}}.

Aviso: a atualização de valores de variáveis estáticas invalida o cache de comandos, o que pode aumentar a latência de chamada do modelo.

Variáveis dinâmicas

As variáveis dinâmicas podem ser atualizadas a qualquer momento durante uma conversa por ferramentas, callbacks ou solicitações de API. Eles não são substituídos diretamente no texto do comando. Em vez disso, quando são atualizados, os novos valores são anexados como eventos state update ao histórico de conversas. Por exemplo: <state_update>var_name: value</state_update>.

Use variáveis dinâmicas para informações extraídas do usuário durante a sessão, saídas recuperadas de APIs externas (ferramentas) ou qualquer estado que mude conforme a conversa avança.

As seguintes desvantagens se aplicam às variáveis dinâmicas:

• As variáveis dinâmicas são anexadas ao histórico de conversas. Portanto, se uma sessão longa exceder o limite da janela de contexto, o agente poderá esquecer valores de variáveis que são perdidos ao cortar o histórico.
• As variáveis dinâmicas podem levar a uma adesão às instruções um pouco menor em comparação com as variáveis estáticas. Isso acontece porque os valores das variáveis são definidos mais longe das instruções. Isso também pode adicionar latência, já que o raciocínio do modelo precisa encontrar o valor mais distante da instrução.

Para fazer referência a uma variável dinâmica por nome nas instruções, use chaves simples: {variable_name}.

Por exemplo, se você estiver criando um agente que precisa autenticar um usuário e depois pesquisar os detalhes específicos da conta dele usando uma ferramenta, use uma instrução como:

If the user asks for their balance, call the {@TOOL: LookupBalance}.
The tool will update the {current_account_balance} variable.
Always share the {current_account_balance} with the user.

Dados variáveis

As variáveis têm os seguintes dados:

• Nome: nome da variável usando snake case
• Tipo: tipo de dados subjacente:
  • Texto: valores de string
  • Número: valores numéricos
  • Sim/Não: valores booleanos
  • Objeto personalizado: você fornece um esquema para o objeto.
  • Lista: lista de variáveis. Forneça os valores como uma lista delimitada por vírgulas.
• Valor padrão: valor padrão da variável
• Descrição: descrição opcional da variável.

Como atualizar valores de variáveis

O próprio agente não pode atualizar o valor de uma variável, mas ferramentas e callbacks podem.

As variáveis do agente usam o estado do contexto do ADK, que pode ser usado para atualizar variáveis. Uma variável global chamada context está disponível para uso no código da sua ferramenta Python. Por exemplo, você pode usar a seguinte instrução em uma ferramenta Python para atualizar uma variável usando recursos do ADK:

context.state["variable_name"] = value

Aviso: se você atualizar uma variável com um before_model_callback, o valor atualizado da variável não vai ficar visível para o modelo até a próxima vez que a conversa for retomada.

Variáveis de contexto de sessão incorporadas

Além das variáveis personalizadas, as ferramentas OpenAPI e MCP podem referenciar variáveis de contexto de sessão integradas. Eles estão disponíveis por padrão e podem ser transmitidos em cabeçalhos HTTP ou parâmetros de solicitação. Essas variáveis não podem ser referenciadas em instruções nem substituídas manualmente. As seguintes variáveis integradas estão disponíveis:

• $context.project_id, $context.project_number, $context.location, $context.app_id, $context.session_id e $context.turn_index para IDs de recursos no nível do app/da sessão.
• $context.variables.variable_name para um valor específico de variável de agente.
• $context.variables para todos os valores de variável de agente como um objeto.