​
Overview

The init function initializes a new or existing Lucidic session for tracking and monitoring AI agent workflows. It sets up the SDK with your credentials, configures providers, and starts or continues a session.

​
Syntax

lai.init(
    session_name: Optional[str] = None,
    session_id: Optional[str] = None,
    api_key: Optional[str] = None,
    agent_id: Optional[str] = None,
    task: Optional[str] = None,
    providers: Optional[List[ProviderType]] = [],
    production_monitoring: Optional[bool] = False,
    mass_sim_id: Optional[str] = None,
    experiment_id: Optional[str] = None,
    rubrics: Optional[list] = None,
    tags: Optional[list] = None,
    masking_function = None,
    auto_end: Optional[bool] = True,
) -> str

​
Parameters

​
session_name
string
The display name for this session. Used for easy identification in the Lucidic dashboard. If not provided, the session will be created without a name.
​
session_id
string
ID for the session. If not provided, a random ID will be generated and returned by init().
​
api_key
string
Your Lucidic API key for authentication. If not provided, the SDK will use the LUCIDIC_API_KEY environment variable.
​
agent_id
string
Your agent identifier. If not provided, the SDK will use the LUCIDIC_AGENT_ID environment variable.
​
task
string
A high-level description of the task or workflow being performed in this session.
​
providers
List[ProviderType]
default:"[]"
List of LLM providers to automatically instrument. Supported values: "openai", "anthropic", "langchain", "pydantic_ai", "openai_agents".
​
production_monitoring
boolean
default:"False"
Flag to enable production monitoring mode. Can also be set via LUCIDIC_PRODUCTION_MONITORING environment variable.
​
mass_sim_id
string
ID of a mass simulation to include this session in. Use with create_mass_sim().
​
experiment_id
string
ID of an experiment to include this session in. Experiments must be created in the dashboard first. The experiment ID can be found in the experiment URL.
​
rubrics
list
List of evaluation criteria for this session. Used for automated evaluation workflows.
​
tags
list
List of tags to categorize and filter sessions in the dashboard.
​
masking_function
callable
Custom function to mask sensitive data before sending to Lucidic. Function should accept text and return masked text.
​
auto_end
boolean
default:"True"
Automatically end the session when the process exits. Ensures data is not lost on unexpected termination.

​
Returns

Returns the session ID as a string.

​
Authentication

​
Setting up Credentials

You need to provide your Lucidic API key and Agent ID to use the SDK. There are several ways to do this: Set these environment variables in your shell or .env file: 
export LUCIDIC_API_KEY=your-api-key
export LUCIDIC_AGENT_ID=your-agent-id
Then initialize without passing credentials: 
import lucidicai as lai

lai.init(
    session_name="My Session",
    providers=["openai"]
)

​
Option 2: Direct Parameters

Pass credentials directly to the init function: 
import lucidicai as lai

lai.init(
    session_name="My Session",
    api_key="your-api-key",   
    agent_id="your-agent-id",         
    providers=["openai"]
)

​
Option 3: Using python-dotenv

For local development, you can use a .env file: 
# .env file
LUCIDIC_API_KEY=your-api-key
LUCIDIC_AGENT_ID=your-agent-id

from dotenv import load_dotenv
import lucidicai as lai

load_dotenv()  # Load environment variables from .env file

lai.init(
    session_name="My Session",
    providers=["anthropic"]
)

​
Getting Your Credentials

  1. Log in to the Lucidic Dashboard
  2. Navigate to your agent settings
  3. Copy your API Key and Agent ID
  4. Store them securely - never commit them to version control

​
Security Best Practices

  • Never hardcode credentials in your source code
  • Use environment variables for production deployments
  • Add .env to .gitignore if using dotenv
  • Rotate API keys regularly for enhanced security
  • Use different keys for development and production

​
Examples

​
Basic Usage

import lucidicai as lai

# Initialize with minimal configuration
session_id = lai.init()

# any llm calls after this will automatically be traced
# ...

​
With Provider Integration

import lucidicai as lai
from openai import OpenAI

# Initialize with OpenAI provider
lai.init(
    session_name="AI Assistant",
    providers=["openai"],
    task="Answer customer questions"
)

# OpenAI calls are now automatically tracked
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

​
Production Configuration

import lucidicai as lai

def mask_pii(text):
    # Custom logic to mask sensitive information
    return text.replace("SSN:", "XXX-XX-")

lai.init(
    session_name="Production Agent",
    production_monitoring=True,
    masking_function=mask_pii,
    tags=["production", "v2.0", "customer-service"],
    rubrics=["response_quality", "task_completion"],
    auto_end=True  # Ensures session ends even on crashes
)

​
Mass Simulation Usage

import lucidicai as lai

# First create a mass simulation
mass_sim_id = lai.create_mass_sim(
    mass_sim_name="Load Test",
    total_num_sessions=1000
)

# Then initialize sessions as part of the simulation
lai.init(
    session_name="Test Session 1",
    mass_sim_id=mass_sim_id
)

​
Experiment Usage

import lucidicai as lai

# Experiments must be created in the dashboard first
# The experiment ID can be found in the URL after creation
EXPERIMENT_ID = "exp-123abc-456def"  # From dashboard URL

# Add sessions to the experiment
lai.init(
    session_name="Performance Test 1",
    experiment_id=EXPERIMENT_ID,
    task="Test checkout flow performance"
)

# Your agent workflow here
process_checkout()

# End the session with evaluation
lai.end_session(
    session_eval_reason="Checkout completed successfully"
)

​
Notes

  • Either api_key or LUCIDIC_API_KEY environment variable must be set
  • Either agent_id or LUCIDIC_AGENT_ID environment variable must be set
  • The SDK can only have one active session at a time
  • If a session is already active, calling init will switch to the new session.
  • init(...) binds the created session to the current async/thread context for correct attribution in concurrent environments
  • Prefer with lai.session(...) for self-contained workflows; see Session Context
  • The auto_end feature ensures your session data is preserved even on unexpected exits
  • Provider instrumentation happens automatically once configured

​
Error Handling

from lucidicai.errors import APIKeyVerificationError, InvalidOperationError

try:
    lai.init(session_name="My Session")
except APIKeyVerificationError:
    print("Please set your LUCIDIC_API_KEY environment variable")
except InvalidOperationError:
    print("Something went wrong. Please double check IDs passed to init()")