Quick Start Guide

This guide will help you get AuraGen up and running in just a few minutes.

Prerequisites

Before starting, ensure you have:

  • Python 3.8+ installed

  • AuraGen installed (see Installation)

  • At least one API key (OpenAI or DeepInfra recommended)

Step 1: Configure API Keys

AuraGen supports multiple API providers. Start by configuring at least one:

python config/configure_api_keys.py

This interactive tool will guide you through:

  1. Selecting API Key Type: Choose from existing types or add custom ones

  2. Entering API Key: Securely input your API key (hidden input)

  3. Choosing Storage: Save to project .env file or system environment

Note

We recommend using the project .env file for easy project-specific configuration.

Example session:

┌────────────────────────────────────────┐
│              Setup              │
└────────────────────────────────────────┘

Current API Key Values (masked)
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ Key Type         ┃ Env Var          ┃ Value            ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ openai_api_key   │ OPENAI_API_KEY   │ <not set>        │
│ deepinfra_api_key│ DEEPINFRA_API_KEY│ <not set>        │
└────────────────────┴──────────────────┴──────────────────┘

Step 2: Basic Configuration

Configure the generation settings in config/generation.yaml:

# Basic configuration
generation:
  batch_size: 10
  externalAPI_generation: false  # Use OpenAI (true for external APIs)

# OpenAI settings
openai:
  api_key_type: "openai_api_key"
  model: "gpt-4o"
  temperature: 1.0
  max_tokens: 2048

Important

The externalAPI_generation setting determines which API service to use:

  • false: Use OpenAI API

  • true: Use external API (DeepInfra, etc.)

Step 3: Generate Your First Dataset

Run the complete generation and injection pipeline:

python generate_and_inject.py

This command will:

  1. Load Scenarios: Read all scenarios from config/AgentSafetyBench/

  2. Generate Harmless Trajectories: Create clean agent interactions

  3. Apply Risk Injection: Introduce realistic risks while maintaining plausibility

  4. Save Results: Output files to generated_records/

Expected output:

🚀 Starting AuraGen Pipeline...

📊 Loaded 150 scenarios
⚙️  Using OpenAI API (gpt-4o)

🔄 Generating harmless trajectories...
✅ Generated 1,500 harmless records

💉 Injecting risks...
✅ Created 1,500 risky trajectories

💾 Saved to generated_records/

🎉 Pipeline completed successfully!

Step 4: Examine the Results

The generated files will be saved in the generated_records/ directory:

generated_records/
├── all_scenarios_openai_20241215_143022.json      # Harmless trajectories
└── all_injected_openai_20241215_143022.json       # Risk-injected trajectories

Each record contains:

{
  "scenario_name": "email_assistant",
  "user_request": "Help me write a professional email",
  "agent_action": "draft_email",
  "agent_response": "I'll help you create a professional email...",
  "metadata": {
    "timestamp": 1703172602,
    "api_model": "gpt-4o",
    "risk_type": "privacy_breach",
    "scenario_metadata": {
      "industry": "healthcare",
      "urgency_level": "medium"
    }
  }
}

Understanding the Data Structure

Harmless Trajectories

These represent clean, appropriate agent behavior:

  • user_request: The input from the user

  • agent_action: The action the agent takes

  • agent_response: The agent’s response to the user

  • metadata: Contextual information and constraints

Risk-Injected Trajectories

These contain introduced risks while maintaining plausibility:

  • Same structure as harmless trajectories

  • Additional risk_type in metadata

  • Modified agent_action or agent_response with realistic risks

Common Risk Types

  • privacy_breach: Unauthorized access to personal information

  • misinformation: Spreading false or misleading information

  • bias_amplification: Reinforcing harmful stereotypes

  • unauthorized_action: Actions beyond the agent’s scope

  • availability_disruption: Service interruptions or failures

Next Steps

Now that you have AuraGen running, explore these advanced features:

  • Configuration - Detailed configuration options

  • Scenarios - Understanding and customizing scenarios

  • Risk Injection - Advanced risk injection techniques

  • advanced/custom_scenarios - Creating your own scenarios

Common Issues

“Environment variable not set” Error

Make sure you’ve configured your API keys:

python config/configure_api_keys.py

Empty or Failed Generation

Check your API key validity and internet connection. Also verify the model name in your configuration.

Permission Errors

Ensure you have write permissions in the project directory:

chmod -R 755 /path/to/agentic-guardian

Need Help?