State Components¶

A state component defines how an agent or workflow manages persistent data across interactions. States track conversation context, user preferences, session variables, and any other data that needs to survive between executions.

Creating a State¶

PythonUI

Coming Soon

The Python SDK for local development is not yet publicly available.

from flow_sdk.cli_client import CLIClient

client = CLIClient(config)

state = client.states.create({
    "name": "Support Session State",
    "slug": "support-session-state",
    "description": "Tracks conversation context for customer support agents",
    "schema_definition": {
        "customer_id": {"type": "string"},
        "customer_name": {"type": "string"},
        "account_tier": {"type": "string", "enum": ["free", "starter", "pro", "enterprise"]},
        "ticket_ids": {"type": "array", "items": {"type": "string"}},
        "escalated": {"type": "boolean"},
        "sentiment_score": {"type": "number"},
    },
    "persistence": "session",
    "initial_values": {
        "ticket_ids": [],
        "escalated": False,
        "sentiment_score": 0.0,
    },
    "tags": ["support", "session"],
})

Navigate to Components > States > New. Define schema, persistence mode, and initial values. Click Create.

Configuration¶

Field	Type	Required	Description
`name`	string	Yes	Display name
`slug`	string	Yes	URL-safe identifier
`schema_definition`	dict	No	JSON Schema defining the state shape
`persistence`	enum	No	Persistence mode (default: `session`)
`initial_values`	dict	No	Default values when state is initialized

Persistence Modes¶

State components support three persistence modes that control how long data is retained:

Mode	Lifetime	Use Case
`none`	Single execution only	Temporary scratch data within one request
`session`	Duration of a conversation session	Multi-turn agent conversations, wizard flows
`long_term`	Persisted across sessions	User preferences, accumulated knowledge, profile data

graph TD
    None["none<br/><i>Single execution</i>"]
    Session["session<br/><i>Conversation lifetime</i>"]
    LongTerm["long_term<br/><i>Cross-session persistence</i>"]

    None -.->|"Discarded after execution"| X1["Gone"]
    Session -.->|"Cleared when session ends"| X2["Gone"]
    LongTerm -.->|"Persisted in database"| DB["Database"]

Session State¶

Session state is the most common mode. It persists data across multiple executions within a single conversation session and is automatically cleaned up when the session ends.

Coming Soon

The Python SDK for local development is not yet publicly available.

state = client.states.create({
    "name": "Conversation Context",
    "slug": "conversation-context",
    "persistence": "session",
    "schema_definition": {
        "messages_sent": {"type": "integer"},
        "topics_discussed": {"type": "array", "items": {"type": "string"}},
        "resolved": {"type": "boolean"},
    },
    "initial_values": {
        "messages_sent": 0,
        "topics_discussed": [],
        "resolved": False,
    },
})

Long-Term State¶

Long-term state survives across sessions. Use it for data that should accumulate over time, like user preferences or historical context.

Coming Soon

The Python SDK for local development is not yet publicly available.

state = client.states.create({
    "name": "User Preferences",
    "slug": "user-preferences",
    "persistence": "long_term",
    "schema_definition": {
        "preferred_language": {"type": "string"},
        "timezone": {"type": "string"},
        "notification_settings": {
            "type": "object",
            "properties": {
                "email": {"type": "boolean"},
                "slack": {"type": "boolean"},
            },
        },
        "interaction_count": {"type": "integer"},
    },
    "initial_values": {
        "preferred_language": "en",
        "timezone": "UTC",
        "notification_settings": {"email": True, "slack": False},
        "interaction_count": 0,
    },
})

Schema Definition¶

The schema_definition field uses JSON Schema syntax to define the structure of the state. This serves as both documentation and runtime validation -- the platform validates state mutations against the schema.

schema_definition={
    # Simple types
    "customer_id": {"type": "string"},
    "total_spent": {"type": "number"},
    "is_premium": {"type": "boolean"},

    # Arrays
    "recent_orders": {
        "type": "array",
        "items": {"type": "string"},
        "maxItems": 10,
    },

    # Nested objects
    "preferences": {
        "type": "object",
        "properties": {
            "theme": {"type": "string", "enum": ["light", "dark"]},
            "page_size": {"type": "integer", "minimum": 10, "maximum": 100},
        },
    },
}

Connecting State to Agents¶

Reference a state component from an agent using state_ref:

Coming Soon

The Python SDK for local development is not yet publicly available.

agent = client.agents.create({
    "name": "Support Agent",
    "slug": "support-agent",
    "model_ref": model.id,
    "state_ref": state.id,        # State component reference
    "enable_conversations": True,  # Required for session persistence
    "tool_refs": [...],
})

When the agent runs, the state is loaded at the start of each execution and saved after the execution completes. Tools and prompt templates can read from and write to the state.

State Transitions¶

State evolves over the course of a session. Each agent execution can read the current state and update it based on the conversation:

Execution 1: User says "Hi, I need help with my bill"
  State before: {messages_sent: 0, topics_discussed: [], resolved: false}
  State after:  {messages_sent: 1, topics_discussed: ["billing"], resolved: false}

Execution 2: User says "The charge on March 15 is wrong"
  State before: {messages_sent: 1, topics_discussed: ["billing"], resolved: false}
  State after:  {messages_sent: 2, topics_discussed: ["billing", "dispute"], resolved: false}

Execution 3: Agent resolves the issue
  State before: {messages_sent: 2, topics_discussed: ["billing", "dispute"], resolved: false}
  State after:  {messages_sent: 3, topics_discussed: ["billing", "dispute"], resolved: true}

Initial Values¶

The initial_values field sets the starting state for new sessions. Any field defined in the schema but not included in initial_values starts as null.

Coming Soon

The Python SDK for local development is not yet publicly available.

state = client.states.create({
    "name": "Wizard Flow State",
    "slug": "wizard-flow-state",
    "persistence": "session",
    "schema_definition": {
        "current_step": {"type": "integer"},
        "total_steps": {"type": "integer"},
        "completed_steps": {"type": "array", "items": {"type": "integer"}},
        "form_data": {"type": "object"},
    },
    "initial_values": {
        "current_step": 1,
        "total_steps": 5,
        "completed_steps": [],
        "form_data": {},
    },
})

Defensive defaults

Always provide initial values for arrays and objects. An agent encountering null where it expects a list may behave unpredictably. Initialize collections to empty values ([], {}) rather than leaving them undefined.