Updating variables with an agent

Configure saving customer answers and updating counters and lists through agent instructions.

First allow the agent to read and write the required variables.

Save several answers

The agent can save several variables in the same scope in one action: for example, a city, item quantity, and permission to call from one message. One action can change up to 100 variables belonging to the project, one lead, or one dialog. All fields are checked before saving: if any value has an invalid type or is unavailable to the agent, the entire group of changes is rejected. Variables omitted by the agent stay unchanged.

In the variable definition, provide a clear description, instructions for the agent, and value constraints. Use the description to explain the field's purpose, such as “Number of items in the order”, and the instructions to specify when to fill it and which client answer to use.

Example instruction: “When the client provides a city and item quantity, save them together in this lead's city and quantity variables. Save permission to call in call_allowed only after the client explicitly answers.”

Clearing a variable removes its value; an unset value is not the same as 0 or false. A regular assignment replaces an entire array or object. To change part of a value, use the operations in the following section.

Updating counters, lists, and other values

The agent can update a saved value without reading it first. Enable Read and write access and describe the intended action, for example:

• Number: “After the order is confirmed, increase this lead's orders_count by 1.” A specified number can be added or subtracted.
• List: “Add the selected product to product_ids, keep the existing products, and avoid duplicates.” Items can be added at the beginning or end, added only when absent, or removed. Regular addition preserves duplicates; uniqueness checks compare the complete item.
• Text: “Append the new note to notes, keeping previous notes.” Text can be added at the beginning or end.
• Boolean: “Toggle reminder_enabled to the opposite value.”
• Date: “Save the current time in last_contact_at” or “Move next_contact_at forward by 2 days.” Shifting requires an existing date and uses minutes, hours, or days; a day means 24 hours.
• Object: “Update city in delivery_address, keeping the other fields.” Individual top-level fields can be changed or removed. A nested object in an updated field is replaced completely, not merged field by field.

When a number, text, boolean, or list is unset, a relative change starts from 0, empty text, false, or an empty list respectively. The final value must match the variable's type and constraints.

For initial values, use a rule such as “Save source only if the variable has no value yet.” Values of 0, false, an empty string, and an empty list already count as set and are not replaced by this action.

Relative changes can be combined with regular assignments in one group: for example, saving the city and increasing the order counter together. The same checks apply as when saving several answers: either all changes are saved or none are.

Random numbers

For a number variable, the agent can generate a random integer in a specified range and save it immediately. Both bounds are included, and all numbers in the range are equally likely.

For example: “Choose a random integer from 1 to 3 and save it in the lead variable offer_variant. Use the saved variant in subsequent conversations.”

Generating again replaces the previous number. To keep the variant fixed, specify: “First check offer_variant. If it already has a value, use it; otherwise generate and save a number from 1 to 3.” Reading the variable again does not change it. The range must match the number variable's constraints.

Why a variable was not changed

Check these conditions in order:

1. For a substitution, verify the system name inside {{...}} and confirm that the selected source has a value: the project, current lead, or current dialog.
2. For a custom variable, confirm that its definition exists under Settings -> Variables.
3. If the agent reads or changes a variable through a tool, confirm that it has been added in Variables with the required access.
4. For a change, select Read and write rather than Read only.
5. In a group chat or comments, identify the intended participant unambiguously.
6. Save and publish the agent changes, and confirm that the live dialog uses the new version.

When the participant or write access is ambiguous, the safe result is to leave the value unchanged and explain what needs clarification.