Skip to main content

Create Session

Creates a new session for managing conversation state and artifacts in agent workflows.

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​

  • App Name - (string) Identifies which agent application this conversation belongs to.
  • User ID - (string) Links the conversation to a particular user.
  • State - (object) Initial state data for the session. Acts as a scratchpad for the agent during the interaction.

Options​

  • Session Service - Session storage backend. Options:
    • Memory - Temporary storage (lost when workflow stops)
    • Database - Persistent storage in a database
    • Robomotion - Managed by Robomotion API (default)
  • Database URL - (string) The database connection URL, required if Session Service is set to Database.
  • Artifact Service - Artifact storage backend. Options:
    • Memory - Temporary storage (lost when workflow stops)
    • GCS - Google Cloud Storage for persistent storage
    • Robomotion - Managed by Robomotion API (default)
  • GCS Bucket - (string) The name of the GCS bucket, required if Artifact Service is set to GCS.
  • GCS Service Account - (Credentials) Service account credentials for GCS access, required if Artifact Service is set to GCS.

Outputs​

  • Session ID - (string) A unique identifier for this specific conversation thread, essential for retrieving it later.

How It Works​

The Create Session node initializes a new conversation session:

  1. Auto-Detection - Detects if running in Robomotion environment and auto-configures if using Robomotion services
  2. Service Configuration - Sets up the selected session and artifact services
  3. Session Creation - Creates a new session with the provided App Name, User ID, and initial state
  4. Artifact Service Setup - Configures the artifact service (Memory, GCS, or Robomotion)
  5. ID Generation - Generates and returns a unique Session ID for future reference

Common Use Cases​

  • Starting Conversations - Begin a new conversation with an agent
  • User Sessions - Create separate sessions for different users
  • Application Context - Initialize sessions for specific applications or use cases
  • State Management - Set up initial context and data for agent workflows
  • Multi-Tenant Systems - Isolate sessions by user and application
  • Persistent Conversations - Enable conversation history that survives workflow restarts

Error Handling​

The node will return errors in the following cases:

  • Missing required fields:
    • "App Name is required for Robomotion sessions" (when using Robomotion service)
    • "User ID is required for Robomotion sessions" (when using Robomotion service)
    • "Database URL is required when using database session service"
    • "GCS bucket is required when using GCS artifact service"
    • "GCS service account is required when using GCS artifact service"
  • Service unavailable - Cannot connect to the selected storage backend
  • Authentication failure - Invalid credentials for database or GCS
  • Robomotion context error - "Robomotion Session Service can only work with Agents and Application robots"
  • Permission errors - Insufficient permissions for storage operations

Usage Notes​

  • Auto-Detection - When running in Robomotion cloud, the service automatically detects context and configures Robomotion services
  • Service Selection - Choose between Memory (temporary), Database (persistent), or Robomotion (managed) based on your needs
  • State Initialization - The State input can be an empty object {} or contain initial key-value pairs
  • Session Persistence - Database and Robomotion services persist sessions across workflow restarts; Memory does not
  • GCS Setup - For GCS artifact service, you need a valid service account with storage permissions
  • Database Support - Database service supports PostgreSQL and other SQL databases via connection URL
  • Robomotion Benefits - Robomotion services are managed, scaled, and require no additional configuration

Service Comparison​

Memory:

  • Pros: Fast, no setup required
  • Cons: Lost on restart, not suitable for production
  • Use Case: Development and testing

Database:

  • Pros: Persistent, full control
  • Cons: Requires database setup and maintenance
  • Use Case: Self-hosted production deployments

Robomotion:

  • Pros: Managed, persistent, scaled automatically
  • Cons: Requires Robomotion cloud environment
  • Use Case: Production deployments on Robomotion platform

Example Usage​

Creating a session with Memory services:

  • App Name: "customer-support"
  • User ID: "user-12345"
  • State: {"language": "en", "priority": "high"}
  • Session Service: Memory
  • Artifact Service: Memory

Creating a session with Robomotion services:

  • App Name: "sales-assistant"
  • User ID: "user-67890"
  • State: {}
  • Session Service: Robomotion
  • Artifact Service: Robomotion

Creating a session with Database + GCS:

  • App Name: "data-analyzer"
  • User ID: "user-11111"
  • State: {"dataset": "q4-sales"}
  • Session Service: Database
  • Database URL: "postgresql://user:pass@localhost:5432/agents"
  • Artifact Service: GCS
  • GCS Bucket: "my-artifacts-bucket"
  • GCS Service Account: (credentials from vault)