Update state

Overview

The Update state tool lets your agent set one or more dynamic variables while a conversation is in progress. Like other system tools, it only changes the internal state of the conversation — it never calls an external API or a client-side function.

Use it to record information as a call unfolds, for example flagging that a conversation should be escalated, storing a value the user provided, or computing a value derived from other dynamic variables.

Functionality

• Multiple updates per call: A single tool call can assign up to 10 dynamic variables at once.
• Expression-based values: Each value is the result of an expression, which can combine constants, existing dynamic variables, values the LLM extracts from the conversation, and operators.
• LLM extraction only when needed: The tool only asks the LLM to extract parameters for the updates that require it. Updates built entirely from constants and/or existing dynamic variables don’t add any parameters to the function call.
• Immediate availability: Once the tool runs, the updated dynamic variables are available to the rest of the conversation — later prompts, other tool calls, and overrides can all reference them, the same way as any other dynamic variable.

How it works

Each state update assigns the result of an expression to a dynamic variable:

variable_name = expression

An expression is one of the following types, and expressions can be nested inside each other to build more complex logic:

For example, the following state update sets should_escalate to true if the LLM judges the user is frustrated, or if a retry_count dynamic variable is already greater than 3:

should_escalate = (llm: "User sounds frustrated with the conversation") OR (retry_count > 3)

Configuration

Use cases

• Escalation flags: Set a dynamic variable (for example should_escalate) that a downstream system or business rule checks, as shown in the Genesys integration guide.
• Recording extracted information: Store a value the user provided (an order number, a preference, a chosen department) as a dynamic variable for use later in the conversation.
• Derived values: Compute a value from other dynamic variables, such as incrementing a counter or combining two variables into one.

Purpose: Let the agent update one or more dynamic variables based on the conversation, without calling an external API.

Trigger conditions: The LLM should call this tool when:

• The conversation provides information that should be recorded (e.g. an escalation flag, a chosen option, a value the user provided)
• A configured state update depends on a value the LLM must judge or extract from the conversation

Parameters:

The function’s parameters depend on how the tool is configured. Each configured state update that uses an LLM-extracted value adds one property to the schema, named after that update’s dynamic variable and typed as string, number, or boolean. State updates built only from constants or other dynamic variables don’t add any parameters.

Function call format:

1
{
2
  "type": "function",
3
  "function": {
4
    "name": "update_state",
5
    "arguments": "{\"should_escalate\": true}"
6
  }
7
}

Implementation: The agent evaluates every configured expression using the extracted parameters plus the conversation’s current dynamic variables, then assigns the results to the corresponding dynamic variables. No external request is made.

FAQ