Variables Management

Overview

Variables can store user characteristics such as language preferences and behavioral habits. Through variable management, AI agents can dynamically memorize user information and generate personalized responses.

• Core mechanism: Variables store data in the form of key-value pairs.
• Assignment logic: The large language model automatically analyzes the semantics of user input, matches corresponding variables, and dynamically assigns values.
• Application scenario: Declare variable usage in prompts. For example, change the response languages based on the user’s language preference.

Type of variables

You can leverage system variables and user variables to address diverse business requirements. They differ in the following aspects:

Type	Control	Data source	Read/write
System preset variables
• App user variables	Preset by the platform	User behavior/device environment	Write only by the system
• Memory variables	Preset by the platform	Long-term user interaction data	Write only by the system
• Role variables	Preset by the platform	Panel settings	Write only by the system
Custom variables	Defined by developers	Proactively provided by the user or dynamically generated in a session	Omni-channel read and write

App user variables

Store app users’ static information associated with smart devices to optimize the services of agents in home scenarios.

• Typical scenario

  • Weather report: Get the local real-time weather based on the home latitude and longitude variables.
  • Device control: Locate devices and adjust their attributes based on variables like room information, home device category, and device AI command attributes. For example, adjust the brightness of lights in the bedroom.

• Available variables

  Variable name	Description	Default value	Support channels	Remarks
  sys.categories	Home device category	Automatically generated by the system	Tuya, SmartLife, and OEM App	Read only
  sys.homeLatitude	Home latitude coordinates	Automatically generated by the system	Tuya, SmartLife, and OEM App	Read only
  sys.rooms	Rooms in a home	Automatically generated by the system	Tuya, SmartLife, and OEM App	Read only
  sys.currentTime	Current time in the time zone when the specified home is located	Automatically generated by the system	Tuya, SmartLife, and OEM App	Read only
  sys.homeLongitude	Home longitude coordinates	Automatically generated by the system	Tuya, SmartLife, and OEM App	Read only
  sys.deviceNames	List of device names	Automatically generated by the system	Tuya, SmartLife, and OEM App	Read only
  sys.attributes	AI command attributes for home devices	Automatically generated by the system	Tuya, SmartLife, and OEM App	Read only

• Rules:

  • How to enable: The variables are disabled by default. You can manually enable them on the developer platform.
  • Data permissions:
    • The data is obtained from the SmartLife app, Tuya app, and OEM apps only.
    • The data is automatically generated by the system and cannot be modified manually. For example, when the user moves to another place and updates the longitude and latitude, a positioning request needs to be retriggered.

Role variables

Role variables are used exclusively in business panel scenarios such as AI dolls and smart speakers. Users can customize role attributes to enhance the interactive fidelity.

• Typical scenario

  • Child companion robot: Users can set role names (such as “Little Helper Lele”) via the role_name variable.

• Default variables

  Variable name	Description	Support channels	Remarks
  sys.roleName	Role name	AI toy panel	Read only
  sys.roleIntroduce	Role description	AI toy panel	Read only
  sys.roleSupplementDesc	Supplemental description of the role	AI toy panel	Read only

• Rules:

  • You need to enable variables on the developer platform before you can use them.
  • End users: The end users can modify the value of a role variable. The modifications take effect immediately without redeploying the agent.

  For more information, see Use variables.

Memory variables

Store personalized data that users need to retain for a long time during their interaction with agents. Support persistent reading and writing across sessions.

• Typical scenario

  • Content matching based on interests: The sys.memoryInterests variable records user-selected hobbies and preferences, enabling the system to recommend relevant content and tailor responses during conversations.
  • Understand user habits through memory integration: The sys.memoryHistoryChatSummary variable stores summaries of past conversations, maintaining contextual continuity to deliver more relevant responses.

• Default variables

  Variable name	Description	Support channels	Remarks
  sys.memoryUserFullName	Name. Record and summarize the user’s name to facilitate personalized communication.	Omni-channel	Summarize each session
  sys.memoryInterests	Hobbies and interests. Record user hobbies and interests to enable personalized content recommendations.	Omni-channel	Same as above
  sys.memoryAge	Age. Record the user’s age information to optimize the interaction experience.	Omni-channel	Same as above
  sys.memoryBirthday	Birthday. Record the user’s birthday information to enable reminders or greetings.	Omni-channel	Same as above
  sys.memoryProfession	Profession. Record the user’s profession information to better understand their needs.	Omni-channel	Same as above
  sys.memoryGoalsAndWishes	Goals and wishes. Record the user’s goals and wishes to facilitate personalized support.	Omni-channel	Same as above
  sys.memoryPetsKeptAtHome	Record the pets in the user’s home to enable personalized interactions.	Omni-channel	Same as above
  sys.memoryHistoryChatSummary	Summarize the user’s historical conversations to maintain contextual continuity.	Omni-channel	Same as above

• Typical scenario

  • Content matching based on interests: The sys.memoryInterests variable records user-selected hobbies and preferences, enabling the system to recommend relevant content and tailor responses during conversations.
  • Understand user habits through memory integration: The sys.memoryHistoryChatSummary variable stores summaries of past conversations, maintaining contextual continuity to deliver more relevant responses.

• Rules:

  • How to enable: The variables are disabled by default. You can manually enable them on the developer platform.
  • Data permissions:
    • The data is available in all deployment channels of the agent.
    • The data is automatically generated by the system and cannot be modified manually. For example, when the user moves to another place and updates the longitude and latitude, a positioning request needs to be retriggered.

Custom variables

You can fully customize variable types to capture temporary states or extend business needs during dynamic interactions between users and agents, such as user roles or real-time emotions.

• Typical scenario
  • Emotional awareness: Dynamically adjust the tone of the response by using the current_mood variable. Value range is 0 to 10.
  • Identity adaptation: Switch the agent’s response strategy by using the user_role variable, such as “parent” and “guest”.
• Definition recommendation

Examples of custom variables

Variable name	Variable description	Scenario
custom_moodLevel	User’s real-time sentiment value (0 to 10 rating)	When the user’s sentiment value is detected to be ≥ 7, use a more positive tone to respond.
custom_interactionFrequency	Statistics of user interactions on the day	If daily interactions reach ≥ 5 times, push a care reminder: “Would you like to take a break?”
custom_preferredTopic	The most recent hashtags that users follow	Prioritize recipe-related content based on custom_preferredTopic=#cooking.

Use variables

1. Log in to the Tuya Developer Platform.

2. Choose AI Agent > Agent Dev > My Agent, and click Create Agent or Agent Management.

   

   Variables Management

3. Scroll down to the Variables section and click + on the right.

   

   Variables Management

4. Manage variables. On the Edit Variables page, you can create custom variables, enable system variables, or enable role variable management.

   • Create a custom variable: In the section of Custom Variables, click Add, enter the variable name, description, and default value, and then click Save. It is recommended that precise variable names and descriptions be provided to enhance the agent’s accuracy in hitting user data.

     

     Variables Management

   • Enable system variables. Turn on the switch to enable app user variables and memory variables. Once enabled, the variable information will be automatically quoted by system prompts.

     

     Variables Management

     If you want to add a special description, you can add the usage scenario of the variable in prompts.

   • Enable role variable management: Role variables are designed for scenarios requiring predefined roles, such as AI toys and smart speakers. Role variables must be used with the panels of the specific categories. This enables end users to customize agent roles, voice tones, personalities, and other features.

     1. Turn on the switch to enable the role variables group.

        

        Variables Management

     2. On the page of Preset Role Management, click Add Preset Role to add official roles or custom roles.

        

        Variables Management

     3. After variables are enabled, once the agent development and device linkage are completed, the preset role information will be visible on the panel when used with the AI toy panel.