Skip to main content

​
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,
    dataset_item_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 for tracking sessions in production environments. When enabled, sessions appear in the Production Monitoring dashboard with comprehensive metrics on cost, performance, and errors. Can also be set via LUCIDIC_PRODUCTION_MONITORING environment variable. See Production Monitoring for details.
​
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.
​
dataset_item_id
string
ID of a dataset item being tested in this session. Links the session to a specific test case from a dataset. Use when running dataset tests to track which test case each session corresponds to. See Working with Datasets for details.
​
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,  # Enables production monitoring dashboard
    masking_function=mask_pii,
    tags=["production", "v2.0", "customer-service"],
    rubrics=["response_quality", "task_completion"],
    auto_end=True  # Ensures session ends even on crashes
)

# Sessions with production_monitoring=True will appear in the Production dashboard
# with metrics on cost, performance, errors, and more

​
Dataset Testing

import lucidicai as lai

# When running dataset tests, link sessions to dataset items
dataset_items = lai.get_dataset_items(dataset_id="test_suite_v1")

for item in dataset_items:
    session_id = lai.init(
        session_name=f"Test: {item['name']}",
        dataset_item_id=item['id'],  # Links to specific test case
        rubrics=["correctness", "completeness"]
    )

    # Run your agent with the test input
    result = my_agent.process(item['input'])

    # Validate against expected output
    success = result == item['expected_output']
    lai.end_session(is_successful=success)

​
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()")