Variables

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

Tipos de variables

El compilador de agentes admite dos tipos de variables distintos 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 instrucción del agente antes de que se realice la llamada al modelo. Actúan como una sustitución directa de texto 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 los datos de configuración, las reglas empresariales rígidas o las cargas útiles contextuales grandes que no cambian durante una sola conversación.

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

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

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

Advertencia: Actualizar los valores de las variables estáticas invalida el almacenamiento en caché de instrucciones, lo que puede generar una mayor latencia en las llamadas al modelo.

Variables dinámicas

Las variables dinámicas se pueden actualizar en cualquier momento durante una conversación a través de herramientas, devoluciones de llamada o solicitudes a la API. No se sustituyen directamente en el texto de la instrucción. 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 APIs externas (herramientas) o cualquier estado que cambie a medida que avanza la conversación.

Las variables dinámicas tienen las siguientes desventajas:

• 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 menor 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 necesita encontrar el valor más lejos de la instrucción.

Para hacer referencia a una variable dinámica por 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 de su cuenta específica 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 variables

Las variables tienen los siguientes datos:

• Name: Es el nombre de la variable en minúsculas con guiones bajos.
• Tipo: Es el 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: Es una lista de variables. Proporciona valores como una lista delimitada por comas.
• Valor predeterminado: Es el valor predeterminado de la variable.
• Descripción: Descripción opcional de la variable

Actualiza los valores de las variables

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

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

context.state["variable_name"] = value

Advertencia: Las plantillas de instrucciones se renderizan entre la devolución de llamada before_agent y la devolución de llamada before_model. Las actualizaciones de variables que se realizan en una devolución de llamada before_agent se aplican de inmediato en el turno actual, mientras que las actualizaciones de variables que se realizan en una devolución de llamada before_model no se ven en las instrucciones renderizadas hasta el siguiente turno de conversación. Haz referencia a las variables actualizadas por las devoluciones de llamada de before_model como variables estáticas {{variable_name}} en lugar de variables dinámicas {variable_name}, ya que las devoluciones de llamada de before_model no agregan eventos <state_update> al historial de conversaciones.

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. 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 reemplazar de forma manual. Están disponibles las siguientes variables integradas:

• $context.project_id, $context.project_number, $context.location, $context.app_id, $context.session_id y $context.turn_index para los 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 variable de agente como un objeto.