Variables

Las variables se usan para almacenar y recuperar datos en diferentes turnos de conversación. Permiten que los agentes recuerden información y mantengan el contexto. Cuando escribes instrucciones de solicitud para tu agente, puedes incluir referencias a estas variables.

Tipos de variables

El compilador de agentes admite dos tipos distintos de variables en las instrucciones: variables estáticas y variables dinámicas.

Elegir el tipo correcto depende de si el valor de la variable debe cambiar durante la sesión del usuario y de cuánto necesitas optimizar la latencia.

Variables estáticas

Las variables estáticas se compilan directamente en la solicitud del agente antes de que se realice la llamada al modelo. Actúan como una sustitución de texto directa de 1:1 y se actualizan con poca frecuencia.

Las variables estáticas maximizan la calidad de las instrucciones y son adecuadas para instrucciones condicionales en muchas situaciones. Usa variables estáticas para datos de configuración, reglas de negocios rígidas o cargas útiles contextuales grandes que no cambian durante la vida útil de una sola conversación.

Para hacer referencia a una variable estática por su nombre en tus instrucciones, usa llaves dobles: {{variable_name}}.

Por ejemplo, si creas un agente de comercio minorista con un catálogo de productos estático y grande, puedes usar una instrucción como la siguiente:

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

Variables dinámicas

Las variables dinámicas se pueden actualizar en cualquier momento durante una conversación con herramientas, devoluciones de llamada o solicitudes a la API. No se sustituyen directamente en el texto de la solicitud. En cambio, cuando se actualizan, sus valores nuevos se agregan como eventos state update al historial de conversaciones. Por ejemplo: <state_update>var_name: value</state_update>.

Usa variables dinámicas para la información extraída del usuario durante la sesión, los resultados recuperados de las APIs externas (herramientas) o cualquier estado que cambie a medida que avanza la conversación.

Las siguientes desventajas se aplican a las variables dinámicas:

  • Las variables dinámicas se agregan al historial de conversaciones, por lo que, si una sesión larga supera el límite de la ventana de contexto, el agente puede olvidar los valores de las variables que se pierden cuando se recorta el historial.
  • Las variables dinámicas podrían generar un cumplimiento de instrucciones ligeramente inferior en comparación con las variables estáticas. Esto se debe a que los valores de las variables se definen más lejos de las instrucciones. Esto también puede agregar latencia, ya que el pensamiento del modelo debe encontrar el valor más lejos de la instrucción.

Para hacer referencia a una variable dinámica por su nombre en tus instrucciones, usa llaves simples: {variable_name}.

Por ejemplo, si creas un agente que necesita autenticar a un usuario y, luego, buscar los detalles específicos de su cuenta con una herramienta, puedes usar una instrucción como la siguiente:

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.

Datos de variables

Las variables tienen los siguientes datos:

  • Nombre: Nombre de la variable con snake case
  • Tipo: Tipo de datos subyacente:
    • Texto: Valores de cadenas
    • Número: Valores numéricos
    • Sí/No: Valores booleanos
    • Objeto personalizado: Proporcionas un esquema para el objeto
    • Lista: Lista de variables. Proporciona valores como una lista delimitada por comas.
  • Valor predeterminado: Valor predeterminado para la variable
  • Descripción: Descripción opcional de la variable

Actualiza los valores de las variables

El agente no puede actualizar el valor de una variable, pero las herramientas y las devoluciones de llamada sí pueden hacerlo.

Las variables del agente usan el estado de contexto del ADK, que se puede usar para actualizar variables. Una variable global llamada context está disponible para usar en el código de tu herramienta de Python. Por ejemplo, puedes usar la siguiente instrucción en una herramienta de Python para actualizar una variable con las funciones del ADK:

context.state["variable_name"] = value

Variables de contexto de sesión integradas

Además de las variables personalizadas, las herramientas de OpenAPI y MCP pueden hacer referencia a variables de contexto de sesión integradas. Estas están disponibles de forma predeterminada y se pueden pasar dentro de los encabezados HTTP o los parámetros de solicitud. No se puede hacer referencia a estas variables en las instrucciones ni se pueden anular de forma manual. Las siguientes variables integradas están disponibles:

  • $context.project_id, $context.project_number, $context.location, $context.app_id, $context.session_id, $context.turn_index para IDs de recursos a nivel de la app o de la sesión.
  • $context.variables.variable_name para un valor de variable de agente específico.
  • $context.variables para todos los valores de las variables del agente como un objeto.