Skip to main content

Update State

Updates specific key-value pairs in a session's state.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.

Inputs​

  • Session ID - (string) Unique identifier for the conversation session.
  • State Changes - (object) Object containing key-value pairs to update in state. Keys will be added or modified, existing keys not mentioned will remain unchanged.

Outputs​

  • Updated State - (object) The full state after the update, containing all key-value pairs.

How It Works​

The Update State node modifies session state:

  1. Input Validation - Verifies that Session ID and State Changes are provided
  2. Session Lookup - Retrieves the session from the session service
  3. Event Creation - Creates a state update event with the specified changes
  4. State Merge - Merges the changes into the existing state (adds new keys, updates existing ones)
  5. Session Update - Appends the event to the session history
  6. Output - Returns the complete updated state

Common Use Cases​

  • Storing Workflow Data - Save intermediate results during workflow execution
  • Agent Communication - Pass data between agents via shared state
  • User Preferences - Store user settings and preferences
  • Progress Tracking - Track workflow progress and status
  • Context Management - Maintain conversation context across agent interactions
  • Feature Flags - Set flags to control workflow behavior

Error Handling​

The node will return errors in the following cases:

  • Missing required fields:
    • "Session ID is required"
    • "State changes are required and must be an object"
  • Session not found - "Session with ID {{session_id}} not found"
  • Invalid state changes - State Changes must be a valid object/dictionary
  • Update failure - "Failed to update state" with details
  • Service unavailable - Cannot connect to the session service

Usage Notes​

  • Merge Behavior - Updates merge with existing state; they don't replace the entire state
  • Adding Keys - New keys are added to the state
  • Updating Keys - Existing keys are updated with new values
  • Preserving Keys - Keys not mentioned in State Changes remain unchanged
  • Nested Objects - You can update nested objects by providing the full path or structure
  • Value Types - State values can be strings, numbers, booleans, objects, arrays, or null
  • Event History - Each update is recorded as an event in the session history

State Update Behavior​

Initial state:

{
  "user_name": "Alice",
  "score": 100
}

State Changes:

{
  "score": 150,
  "level": "expert"
}

Result:

{
  "user_name": "Alice",
  "score": 150,
  "level": "expert"
}

Example Usage​

Adding new data:

  • Session ID: "session-123"
  • State Changes: 
    {
      "analysis_complete": true,
      "result": "positive",
      "confidence": 0.92
    }

Updating existing values:

  • Session ID: "session-123"
  • State Changes: 
    {
      "step": 3,
      "status": "in_progress"
    }

Storing complex data:

  • Session ID: "session-123"
  • State Changes: 
    \{
      "user_profile": \{
        "name": "John Doe",
        "preferences": \{
          "language": "en",
          "timezone": "UTC"
        \}
      \},
      "search_results": [
        \{"title": "Result 1", "score": 0.95\},
        \{"title": "Result 2", "score": 0.87\}
      ]
    \}

Best Practices​

  • Use Descriptive Keys - Choose clear, meaningful key names
  • Validate Input - Ensure State Changes is a valid object before passing it
  • Avoid Overwriting - Be careful not to overwrite important state data unintentionally
  • Type Consistency - Maintain consistent value types for the same keys
  • State Size - Keep state reasonably sized; very large states may impact performance
  • Error Handling - Enable Continue On Error if state updates are non-critical

Integration Patterns​

Sequential Updates:

  1. Get State to read current values
  2. Compute new values based on current state
  3. Update State with the changes

Conditional Updates:

  1. Get State to check current values
  2. Use conditional logic to determine updates
  3. Update State only if conditions are met

Agent Workflow:

  1. LLM Agent sets Output Key to write to state
  2. Get State to retrieve agent results
  3. Update State to add additional context
  4. Next agent uses updated state

Working with Nested Objects​

To update nested values, provide the complete structure:

Updating a nested value:

{
  "user_profile": {
    "preferences": {
      "theme": "dark"
    }
  }
}

This will merge with existing user_profile and preferences objects.

Performance Considerations​

  • State Size - Large states increase storage and processing time
  • Update Frequency - Frequent updates create more events in session history
  • Nested Complexity - Deeply nested structures may impact performance
  • Concurrent Updates - Multiple concurrent updates may lead to race conditions

Troubleshooting​

  • State Not Updating - Verify Session ID is correct and session exists
  • Keys Not Appearing - Check that State Changes is a valid object
  • Unexpected Values - Use Get State to inspect the current state
  • Merge Issues - Understand that updates merge, they don't replace the entire state