### Configure CAI .env File

Source: https://aliasrobotics.github.io/cai/cai_installation

Example content for the .env file used by CAI to load configuration and API keys. Users must provide their actual API keys or placeholders as indicated.

```dotenv
OPENAI_API_KEY="sk-1234" 
# OPENAI_API_KEY MUST BE FILLED-IN. 
# It should contain either "sk-123" (as a placeholder) 
# or your actual API key. 
# See https://github.com/aliasrobotics/cai/issues/27

ANTHROPIC_API_KEY=""
OLLAMA=""
PROMPT_TOOLKIT_NO_CPR=1
```

--------------------------------

### Install CAI Pro on Windows WSL

Source: https://aliasrobotics.github.io/cai/Installation_Guide_for_CAI_Pro_v0

Instructions for installing CAI Pro on Windows using WSL. This involves updating apt, installing git, Python 3, and venv, creating and activating a virtual environment, installing the CAI framework, creating a .env file, and launching CAI.

```bash
sudo apt-get update && \
sudo apt-get install -y git python3-pip python3-venv

# Create the virtual environment
python3 -m venv cai_env

# Install the package from the local directory
source cai_env/bin/activate && pip install cai-framework

# Generate a .env file and set up with defaults
echo -e 'OPENAI_API_KEY="sk-1234"\nANTHROPIC_API_KEY=""\nOLLAMA=""\nPROMPT_TOOLKIT_NO_CPR=1\nCAI_STREAM=false' > .env

# Launch CAI
cai  # first launch it can take up to 30 seconds
```

--------------------------------

### Install CAI Pro on Ubuntu

Source: https://aliasrobotics.github.io/cai/Installation_Guide_for_CAI_Pro_v0

Commands to install CAI Pro on Ubuntu 24.04. This involves updating packages, creating and activating a virtual environment, and installing the CAI framework using a provided API key.

```bash
sudo apt update
python3.12 -m venv cai_env
source cai_env/bin/activate
pip install --index-url https://packages.aliasrobotics.com:664/<api-key>/ cai-framework
cai –tui
```

--------------------------------

### Ubuntu: Install CAI Framework and Dependencies

Source: https://aliasrobotics.github.io/cai/cai_installation

Installs Git, Python 3.12, and pip for Ubuntu, creates a virtual environment, installs the CAI framework, and sets up a default .env file. Tested on Ubuntu 24.04 and 20.04 with minor differences in package installation.

```bash
# For Ubuntu 24.04
sudo apt-get update && \
    sudo apt-get install -y git python3-pip python3.12-venv

# For Ubuntu 20.04 (may require adding deadsnakes PPA for Python 3.12)
sudo apt-get update && \
    sudo apt-get install -y software-properties-common

# Fetch Python 3.12 (if not available)
sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-dev -y

# Create the virtual environment
python3.12 -m venv cai_env

# Install the package from the local directory
source cai_env/bin/activate && pip install cai-framework

# Generate a .env file and set up with defaults
echo -e 'OPENAI_API_KEY="sk-1234"\nANTHROPIC_API_KEY=""\nOLLAMA=""\nPROMPT_TOOLKIT_NO_CPR=1' > .env

# Launch CAI
cai  # first launch it can take up to 30 seconds
```

--------------------------------

### Install CAI Pro on macOS

Source: https://aliasrobotics.github.io/cai/Installation_Guide_for_CAI_Pro_v0

Steps to install CAI Pro on macOS using Homebrew. This includes installing Homebrew, git, and Python 3.12, setting up a virtual environment, installing the CAI framework, creating a .env file, and launching CAI.

```bash
# Install homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew update && \
brew install git python@3.12

# Create virtual environment
python3.12 -m venv cai_env

# Install the package from the local directory
source cai_env/bin/activate && pip install cai-framework

# Generate a .env file and set up with defaults
echo -e 'OPENAI_API_KEY="sk-1234"\nANTHROPIC_API_KEY=""\nOLLAMA=""\nPROMPT_TOOLKIT_NO_CPR=1\nCAI_STREAM=false' > .env

# Launch CAI
cai  # first launch it can take up to 30 seconds
```

--------------------------------

### Windows WSL: Install CAI Framework and Dependencies

Source: https://aliasrobotics.github.io/cai/cai_installation

Installs Git, Python 3, and venv on WSL, creates a virtual environment, installs the CAI framework, and sets up a default .env file. Assumes WSL is already installed following Microsoft's instructions.

```bash
sudo apt-get update && \
    sudo apt-get install -y git python3-pip python3-venv

# Create the virtual environment
python3 -m venv cai_env

# Install the package from the local directory
source cai_env/bin/activate && pip install cai-framework

# Generate a .env file and set up with defaults
echo -e 'OPENAI_API_KEY="sk-1234"\nANTHROPIC_API_KEY=""\nOLLAMA=""\nPROMPT_TOOLKIT_NO_CPR=1' > .env

# Launch CAI
cai  # first launch it can take up to 30 seconds
```

--------------------------------

### Install CAI Framework using pip

Source: https://aliasrobotics.github.io/cai/cai_installation

This command installs the CAI framework using pip, the Python package installer. Ensure you have Python and pip installed on your system.

```bash
pip install cai-framework
```

--------------------------------

### Configure CAI for Getting Started

Source: https://aliasrobotics.github.io/cai/environment_variables

Essential environment variables for initial CAI setup, including model selection, agent type, and optional cost control.

```shell
# Required: Model selection
CAI_MODEL="alias1"                    # or gpt-4o, claude-sonnet-4.5, ollama/qwen2.5:72b

# Recommended: Agent type
CAI_AGENT_TYPE="redteam_agent"        # See available agents with /agent command

# Optional but useful: Cost control
CAI_PRICE_LIMIT="1"                   # Maximum spend in dollars

```

--------------------------------

### OS X: Install CAI Framework and Dependencies

Source: https://aliasrobotics.github.io/cai/cai_installation

Installs Git and Python 3.12 using Homebrew, creates a virtual environment, installs the CAI framework, and sets up a default .env file. This is for macOS users.

```bash
brew update && \
    brew install git python@3.12

# Create virtual environment
python3.12 -m venv cai_env

# Install the package from the local directory
source cai_env/bin/activate && pip install cai-framework

# Generate a .env file and set up with defaults
echo -e 'OPENAI_API_KEY="sk-1234"\nANTHROPIC_API_KEY=""\nOLLAMA=""\nPROMPT_TOOLKIT_NO_CPR=1' > .env

# Launch CAI
cai  # first launch it can take up to 30 seconds
```

--------------------------------

### Install CAI Pro on Android (Kali via UserLand)

Source: https://aliasrobotics.github.io/cai/Installation_Guide_for_CAI_Pro_v0

Detailed steps for installing CAI Pro on Android using Kali Linux via UserLand. This includes installing UserLand, Kali, updating apt keys, installing Python 3.12, cloning CAI's source, setting up a virtual environment, and launching CAI.

```bash
# Get new apt keys
wget http://http.kali.org/kali/pool/main/k/kali-archive-keyring/kali-archive-keyring_2024.1_all.deb

# Install new apt keys
sudo dpkg -i kali-archive-keyring_2024.1_all.deb && rm kali-archive-keyring_2024.1_all.deb

# Update APT repository
sudo apt-get update

# CAI requires python 3.12, lets install it (CAI for kali in Android)
sudo apt-get update && sudo apt-get install -y git python3-pip build-essential zlib1g-dev \
libncurses5-dev libgdbm-dev libnss3-dev libssl-dev libreadline-dev libffi-dev libsqlite3-dev \
wget libbz2-dev pkg-config

wget https://www.python.org/ftp/python/3.12.4/Python-3.12.4.tar.xz
tar xf Python-3.12.4.tar.xz
cd Python-3.12.4
./configure --enable-optimizations
sudo make altinstall  # This command takes long to execute

# Clone CAI's source code
git clone https://github.com/aliasrobotics/cai && cd cai

# Create virtual environment
python3.12 -m venv cai_env

# Install the package from the local directory
source cai_env/bin/activate && pip3 install -e .

# Generate a .env file and set up
cp .env.example .env  # edit here your keys/models

# Launch CAI
cai
```

--------------------------------

### Install MkDocs and Material Theme

Source: https://aliasrobotics.github.io/cai/cai_faq

Installs MkDocs, a static site generator for project documentation, and the Material theme, a popular theme for MkDocs, using pip. This is the first step to running the documentation locally.

```python
pip install mkdocs mkdocs-material

```

--------------------------------

### Install Dependencies and Initialize Submodules

Source: https://aliasrobotics.github.io/cai/cai_benchmark

This code snippet shows the commands to initialize Git submodules and install Python dependencies required for the project. It ensures all necessary external code is fetched and project requirements are met.

```shell
git submodule update --init --recursive
pip install cvss
```

--------------------------------

### Copy Example agents.yml Configuration

Source: https://aliasrobotics.github.io/cai/multi_agent

This command copies the example agents.yml file to your current directory, serving as a template for your custom configuration.

```bash
cp agents.yml.example agents.yml
```

--------------------------------

### On Trace Start Method in Python

Source: https://aliasrobotics.github.io/cai/ref/tracing/setup

Handles the event when a trace begins. It iterates through all registered `TracingProcessor` instances and calls their respective `on_trace_start` method, passing the `Trace` object. This ensures all processors are notified of the trace's commencement.

```python
def on_trace_start(self, trace: Trace) -> None:
    """
    Called when a trace is started.
    """
    for processor in self._processors:
        processor.on_trace_start(trace)
```

--------------------------------

### CAI Continue Mode Quick Start Examples

Source: https://aliasrobotics.github.io/cai/continue_mode

Demonstrates how to use the `--continue` flag with different prompts for various tasks like telling jokes, analyzing code, and running security audits.

```bash
cai --continue --prompt "tell me a joke about security"
cai --continue --prompt "find all SQL injection vulnerabilities in this codebase"
cai --continue --prompt "perform a comprehensive security audit"
```

--------------------------------

### On Span Start Method in Python

Source: https://aliasrobotics.github.io/cai/ref/tracing/setup

Processes the event signifying the beginning of a span. It invokes the `on_span_start` method for every `TracingProcessor` in the list, providing the `Span` object. This ensures all configured processors are aware of new span creations.

```python
def on_span_start(self, span: Span[Any]) -> None:
    """
    Called when a span is started.
    """
    for processor in self._processors:
        processor.on_span_start(span)
```

--------------------------------

### Verify CAI Installation and Benchmark Directory

Source: https://aliasrobotics.github.io/cai/benchmarking/running_benchmarks

Tests the CAI installation by running a simple Python command and lists the contents of the benchmarks directory. This confirms that the framework is correctly set up and accessible.

```bash
# Test basic functionality
python -c "from cai import cli; print('CAI installed successfully!')"

# Check benchmarks directory
ls benchmarks/

```

--------------------------------

### Install CAI Framework and Dependencies

Source: https://aliasrobotics.github.io/cai/benchmarking/running_benchmarks

Installs the CAI framework and benchmark-specific Python packages using pip. Ensures all necessary libraries are available for running evaluations.

```bash
# Install base dependencies
pip install cai-framework

# Install benchmark-specific requirements
pip install cvss

```

--------------------------------

### Android: Install CAI Framework and Python 3.12

Source: https://aliasrobotics.github.io/cai/cai_installation

Installs CAI on Android via UserLand and Kali Linux. This involves updating apt keys, installing Python 3.12 from source, cloning the CAI repository, setting up a virtual environment, and installing the framework locally. Requires significant time for Python compilation.

```bash
# Get new apt keys
wget http://http.kali.org/kali/pool/main/k/kali-archive-keyring/kali-archive-keyring_2024.1_all.deb

# Install new apt keys
sudo dpkg -i kali-archive-keyring_2024.1_all.deb && rm kali-archive-keyring_2024.1_all.deb

# Update APT repository
sudo apt-get update

# CAI requieres python 3.12, lets install it (CAI for kali in Android)
sudo apt-get update && sudo apt-get install -y git python3-pip build-essential zlib1g-dev libncurses5-dev libgdbm-dev libnss3-dev libssl-dev libreadline-dev libffi-dev libsqlite3-dev wget libbz2-dev pkg-config
wget https://www.python.org/ftp/python/3.12.4/Python-3.12.4.tar.xz
tar xf Python-3.12.4.tar.xz
cd ./configure --enable-optimizations
sudo make altinstall # This command takes long to execute

# Clone CAI's source code
git clone https://github.com/aliasrobotics/cai && cd cai

# Create virtual environment
python3.12 -m venv cai_env

# Install the package from the local directory
source cai_env/bin/activate && pip3 install -e .

# Generate a .env file and set up
cp .env.example .env  # edit here your keys/models

# Launch CAI
cai
```

--------------------------------

### Launch CAI CLI with Initial Prompt

Source: https://aliasrobotics.github.io/cai/cli/cli_index

Launches the CAI CLI and provides an initial prompt to guide the AI agent. Useful for starting a specific task immediately upon launch.

```bash
cai --prompt "scan 192.168.1.1 for open ports"
```

--------------------------------

### Run SecEval Benchmark with Ollama

Source: https://aliasrobotics.github.io/cai/cai_benchmark

Example of running the SecEval benchmark using the 'ollama/qwen2.5:14b' model and 'ollama' backend. It specifies the model, dataset, evaluation type, and backend.

```python
python benchmarks/eval.py --model ollama/qwen2.5:14b --dataset_file benchmarks/seceval/eval/datasets/questions-2.json --eval seceval --backend ollama
```

--------------------------------

### Run CTI Bench Benchmark with Openrouter

Source: https://aliasrobotics.github.io/cai/cai_benchmark

Example of running the CTI Bench benchmark with the 'qwen/qwen3-32b:free' model and 'openrouter' backend. It specifies the model, dataset, evaluation type, and backend.

```python
python benchmarks/eval.py --model qwen/qwen3-32b:free  --dataset_file benchmarks/cti_bench/data/cti-mcq1.tsv --eval cti_bench --backend openrouter
```

--------------------------------

### Abstract Trace Start Method

Source: https://aliasrobotics.github.io/cai/ref/tracing

Defines the abstract method `start` for initiating a trace. It takes an optional boolean argument `mark_as_current` to designate the trace as the current one. This method is part of the tracing interface.

```python
@abc.abstractmethod
def start(self, mark_as_current: bool = False):
    """
    Start the trace.

    Args:
        mark_as_current: If true, the trace will be marked as the current trace.
    """
    pass

```

--------------------------------

### Run Cybermetric Benchmark with Ollama

Source: https://aliasrobotics.github.io/cai/cai_benchmark

Example of running the Cybermetric benchmark using the 'ollama/qwen2.5:14b' model and 'ollama' backend. It specifies the model, dataset, evaluation type, and backend.

```python
python benchmarks/eval.py --model ollama/qwen2.5:14b --dataset_file benchmarks/cybermetric/CyberMetric-2-v1.json --eval cybermetric --backend ollama
```

--------------------------------

### Run Cybermetric Benchmark with OpenAI

Source: https://aliasrobotics.github.io/cai/cai_benchmark

Example of running the Cybermetric benchmark using the 'gpt-4o-mini' model and 'openai' backend. It specifies the model, dataset, evaluation type, and backend.

```python
python benchmarks/eval.py --model gpt-4o-mini --dataset_file benchmarks/cybermetric/CyberMetric-2-v1.json --eval cybermetric --backend openai
```

--------------------------------

### Serve MkDocs Documentation Locally

Source: https://aliasrobotics.github.io/cai/cai_faq

Starts a local development server for MkDocs documentation. This allows you to preview the documentation in your web browser as you make changes, typically accessible at http://127.0.0.1:8000.

```shell
python -m mkdocs serve

```

--------------------------------

### Include Recommended Handoff Prompt Instructions

Source: https://aliasrobotics.github.io/cai/handoffs

Provides an example of how to enhance an agent's instructions by incorporating recommended handoff prompt prefixes. This ensures that LLMs properly understand and utilize the handoff functionality.

```python
from cai.sdk.agents import Agent
from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX

billing_agent = Agent(
    name="Phising Agent",
    instructions=f"{RECOMMENDED_PROMPT_PREFIX}
    <Fill in the rest of your prompt here>.",
)


```

--------------------------------

### Get System Prompt (get_system_prompt)

Source: https://aliasrobotics.github.io/cai/ref/agent

Retrieves the system prompt configured for the agent. The system prompt guides the agent's behavior and responses.

```APIDOC
## GET /agents/{agent_id}/system_prompt

### Description
Retrieves the system prompt associated with a specific agent.

### Method
GET

### Endpoint
`/agents/{agent_id}/system_prompt`

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The unique identifier of the agent whose system prompt is to be retrieved.

### Response
#### Success Response (200)
- **system_prompt** (string | null) - The system prompt of the agent, or null if no system prompt is set.

#### Response Example
```json
{
  "system_prompt": "You are a helpful assistant."
}
```
```

--------------------------------

### Get Current Span in Python

Source: https://aliasrobotics.github.io/cai/ref/tracing/setup

Returns the currently active span, if one is present. This is crucial for monitoring and debugging operations within the Cai SDK.

```python
def get_current_span(self) -> Span[Any] | None:
    """
    Returns the currently active span, if any.
    """
    return Scope.get_current_span()

```

--------------------------------

### Get Current Trace in Python

Source: https://aliasrobotics.github.io/cai/ref/tracing/setup

Retrieves the currently active trace, if one exists. This function is essential for context propagation within the Cai SDK's tracing module.

```python
def get_current_trace(self) -> Trace | None:
    """
    Returns the currently active trace, if any.
    """
    return Scope.get_current_trace()

```

--------------------------------

### Example Display of Configured API Keys

Source: https://aliasrobotics.github.io/cai/tui/sidebar_features

Illustrates how configured API keys are displayed in the CAI TUI's Keys tab, showing provider names and masked keys for security. It highlights the format for ALIAS1 and other common providers.

```text
ALIAS_API_KEY:sk-12hk......2t4
OpenAI_API_KEY: sk-...abc123 
ANTHROPIC_API_KEY: sk-ant-...xyz789 

```

--------------------------------

### Create Higher Level Traces with context manager

Source: https://aliasrobotics.github.io/cai/tracing

This example demonstrates how to group multiple `Runner.run` calls within a single trace using the `trace` context manager. It defines an agent and then executes two sequential runs, both falling under the 'Joke workflow' trace. The `trace` context manager automatically handles starting and ending the trace.

```python
from cai.sdk.agents import Agent, Runner, trace

async def main():
    agent = Agent(name="Joke generator", instructions="Tell funny jokes.")

    with trace("Joke workflow"):
        first_result = await Runner.run(agent, "Tell me a joke")
        second_result = await Runner.run(agent, f"Rate this joke: {first_result.final_output}")
        print(f"Joke: {first_result.final_output}")
        print(f"Rating: {second_result.final_output}")

```

--------------------------------

### Initialize OpenAI Voice Model Provider

Source: https://aliasrobotics.github.io/cai/ref/voice/models/openai_provider

Initializes the OpenAI voice model provider. It accepts an API key, base URL, an optional pre-configured OpenAI client, organization, and project. If an OpenAI client is provided, API key and base URL should not be. Otherwise, it stores credentials for later client creation.

```python
def __init__(
    self,
    *,
    api_key: str | None = None,
    base_url: str | None = None,
    openai_client: AsyncOpenAI | None = None,
    organization: str | None = None,
    project: str | None = None,
) -> None:
    """Create a new OpenAI voice model provider.

    Args:
        api_key: The API key to use for the OpenAI client. If not provided, we will use the
            default API key.
        base_url: The base URL to use for the OpenAI client. If not provided, we will use the
            default base URL.
        openai_client: An optional OpenAI client to use. If not provided, we will create a new
            OpenAI client using the api_key and base_url.
        organization: The organization to use for the OpenAI client.
        project: The project to use for the OpenAI client.
    """
    if openai_client is not None:
        assert api_key is None and base_url is None,
            ("Don't provide api_key or base_url if you provide openai_client")
        self._client: AsyncOpenAI | None = openai_client
    else:
        self._client = None
        self._stored_api_key = api_key
        self._stored_base_url = base_url
        self._stored_organization = organization
        self._stored_project = project

```

--------------------------------

### Integrate CAI with Burp Suite via MCP

Source: https://aliasrobotics.github.io/cai/cli/advanced_usage

Guides through integrating CAI with Burp Suite using the Message Conversion Protocol (MCP). It covers starting the Burp Suite MCP server, loading it into CAI, adding Burp tools to an agent, and using Burp tools within CAI.

```shell
# Start Burp Suite MCP server
# (in separate terminal)
burp-mcp-server --port 9876

# In CAI
CAI> /mcp load http://localhost:9876/sse burp
CAI> /mcp tools burp
CAI> /mcp add redteam_agent burp

# Use Burp tools
CAI> Use Burp to scan https://target.com
```

--------------------------------

### Check Docker Daemon Status and Start

Source: https://aliasrobotics.github.io/cai/benchmarking/running_benchmarks

These commands are used to troubleshoot issues with Docker containers failing to start. `docker ps` lists currently running containers, and `sudo systemctl start docker` (on Linux) attempts to start the Docker daemon if it is not running.

```shell
# Solution: Check Docker daemon
docker ps
sudo systemctl start docker  # Linux

```

--------------------------------

### CAI CLI: Basic Parallel Agent Setup using Commands

Source: https://aliasrobotics.github.io/cai/cli/advanced_usage

Demonstrates how to add agents to a parallel configuration, list them, run a command across all agents, and merge the results using CAI CLI commands.

```bash
# Launch CAI
cai

# Add agents to parallel configuration
CAI> /parallel add redteam_agent alias1
CAI> /parallel add blueteam_agent alias1
CAI> /parallel add bug_bounter_agent gpt-4o

# List configured agents
CAI> /parallel list

# Execute on all agents
CAI> /parallel run "analyze the security of target.com"

# Merge results
CAI> /parallel merge

```

--------------------------------

### Start Abstract Method for Span in Python

Source: https://aliasrobotics.github.io/cai/ref/tracing/spans

Defines the abstract `start` method for the Span class. This method is responsible for initiating a span's lifecycle, with an optional parameter to mark it as the currently active span. Implementations must provide the logic for starting the span and potentially updating the tracing context.

```python
@abc.abstractmethod
def start(self, mark_as_current: bool = False):
    """
    Start the span.

    Args:
        mark_as_current: If true, the span will be marked as the current span.
    """
    pass
```

--------------------------------

### Install Dependencies for Privacy Benchmarks

Source: https://aliasrobotics.github.io/cai/benchmarking/privacy_benchmarks

Installs necessary Python dependencies, including the 'cvss' library, required for running privacy benchmarks and potentially other related security evaluations.

```bash
# Install dependencies
pip install cvss
```

--------------------------------

### Connect to MCP Filesystem Server with MCPServerStdio

Source: https://aliasrobotics.github.io/cai/mcp

Connects to the MCP filesystem server using the MCPServerStdio class. This server runs as a subprocess and is used to access local files. It takes a command and arguments to start the server process. The `list_tools()` method is used to retrieve available tools from the server.

```python
async with MCPServerStdio(
    params={
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
    }
) as server:
    tools = await server.list_tools()
```

--------------------------------

### Run Evaluation Script with Arguments

Source: https://aliasrobotics.github.io/cai/cai_benchmark

This command demonstrates how to execute the main evaluation script. It includes placeholders for model name, dataset file, evaluation type, and backend, showing the core functionality of the script.

```python
python benchmarks/eval.py --model MODEL_NAME --dataset_file INPUT_FILE --eval EVAL_TYPE --backend BACKEND
```

--------------------------------

### OpenAIVoiceModelProvider Initialization and Client Management (Python)

Source: https://aliasrobotics.github.io/cai/ref/voice/models/openai_provider

This Python code defines the OpenAIVoiceModelProvider class, which inherits from VoiceModelProvider. It handles initialization with optional OpenAI client parameters or credentials, and lazily loads the OpenAI client to avoid errors when no API key is set. Dependencies include the VoiceModelProvider base class and the AsyncOpenAI client.

```python
class OpenAIVoiceModelProvider(VoiceModelProvider):
    """A voice model provider that uses OpenAI models."""

    def __init__(
        self,
        *,
        api_key: str | None = None,
        base_url: str | None = None,
        openai_client: AsyncOpenAI | None = None,
        organization: str | None = None,
        project: str | None = None,
    ) -> None:
        """Create a new OpenAI voice model provider.

        Args:
            api_key: The API key to use for the OpenAI client. If not provided, we will use the
                default API key.
            base_url: The base URL to use for the OpenAI client. If not provided, we will use the
                default base URL.
            openai_client: An optional OpenAI client to use. If not provided, we will create a new
                OpenAI client using the api_key and base_url.
            organization: The organization to use for the OpenAI client.
            project: The project to use for the OpenAI client.
        """
        if openai_client is not None:
            assert api_key is None and base_url is None,
                ("Don't provide api_key or base_url if you provide openai_client")
            self._client: AsyncOpenAI | None = openai_client
        else:
            self._client = None
            self._stored_api_key = api_key
            self._stored_base_url = base_url
            self._stored_organization = organization
            self._stored_project = project

    # We lazy load the client in case you never actually use OpenAIProvider(). Otherwise
    # AsyncOpenAI() raises an error if you don't have an API key set.
    def _get_client(self) -> AsyncOpenAI:
        if self._client is None:
            self._client = _openai_shared.get_default_openai_client() or AsyncOpenAI(
                api_key=self._stored_api_key or _openai_shared.get_default_openai_key(),
                base_url=self._stored_base_url,
                organization=self._stored_organization,
                project=self._stored_project,
                http_client=shared_http_client(),
            )

        return self._client
```

--------------------------------

### Register Tracing Processor in Python

Source: https://aliasrobotics.github.io/cai/ref/tracing/setup

Adds a TracingProcessor to the list of active processors. Each added processor will receive all traces and spans. This method is part of the Cai SDK's tracing setup.

```python
def register_processor(self, processor: TracingProcessor):
    """
    Add a processor to the list of processors. Each processor will receive all traces/spans.
    """
    self._multi_processor.add_tracing_processor(processor)

```

--------------------------------

### Run CTI Bench Benchmark (ATE2) with Openrouter

Source: https://aliasrobotics.github.io/cai/cai_benchmark

Example of running the CTI Bench (ATE2) benchmark with the 'qwen/qwen3-32b:free' model and 'openrouter' backend. It specifies the model, dataset, evaluation type, and backend.

```python
python benchmarks/eval.py --model qwen/qwen3-32b:free  --dataset_file benchmarks/cti_bench/data/cti-ate2.tsv --eval cti_bench --backend openrouter
```

--------------------------------

### Environment & Configuration Commands

Source: https://aliasrobotics.github.io/cai/cli/commands_reference

Commands for viewing and configuring environment variables and settings.

```APIDOC
## POST /config or /cfg

### Description
Display and configure environment variables.

### Method
POST

### Endpoint
/config or /cfg

### Parameters
#### Query Parameters
- **VARIABLE=value** (string) - Optional - Set a configuration variable directly.
- **set <number> <value>** (string) - Optional - Set a configuration variable using its number and new value.

### Request Example
```json
{
  "command": "/config CAI_MAX_TURNS=50"
}
```

### Response
#### Success Response (200)
- **configuration** (object) - A dictionary of current configuration variables and their values.

#### Response Example
```json
{
  "configuration": {
    "CAI_MODEL": "alias1",
    "CAI_AGENT_TYPE": "redteam_agent",
    "CAI_MAX_TURNS": "50"
  }
}
```

## POST /env or /e

### Description
Display current environment variables.

### Method
POST

### Endpoint
/env or /e

### Parameters
#### Query Parameters
- **pattern** (string) - Optional - A filter pattern to search for environment variables (e.g., "CAI", "CTF").

### Request Example
```json
{
  "command": "/env CAI"
}
```

### Response
#### Success Response (200)
- **environment_variables** (object) - A dictionary of environment variables matching the pattern (or all if no pattern is provided).

#### Response Example
```json
{
  "environment_variables": {
    "CAI_MODEL": "alias1",
    "CAI_PRICE_LIMIT": "1.0"
  }
}
```

## POST /workspace or /ws

### Description
Manage workspace directories.

### Method
POST

### Endpoint
/workspace or /ws

### Parameters
#### Query Parameters
- **subcommand** (string) - Required - The subcommand to execute: `show`, `pwd`, `set <path>`, `list`, or `ls`.
- **path** (string) - Optional - The path to set as the workspace directory (used with `set` subcommand).

### Request Example
```json
{
  "command": "/workspace set /home/user/pentests"
}
```

### Response
#### Success Response (200)
- **message** (string) - A message indicating the result of the operation (e.g., current directory, list of files, confirmation).

#### Response Example
```json
{
  "message": "Workspace set to /home/user/pentests."
}
```

## POST /virtualization or /virt

### Description
Manage Docker-based virtualization environments.

### Method
POST

### Endpoint
/virtualization or /virt

### Parameters
#### Query Parameters
- **subcommand** (string) - Required - The subcommand to execute: `list`, `set <container_id>`, `clear`, or `info`.
- **container_id** (string) - Optional - The ID or name of the container to set as active (used with `set` subcommand).

### Request Example
```json
{
  "command": "/virt set ubuntu_ctf"
}
```

### Response
#### Success Response (200)
- **message** (string) - A message indicating the result of the operation (e.g., list of containers, status, confirmation).

#### Response Example
```json
{
  "message": "Active container set to ubuntu_ctf."
}
```
```

--------------------------------

### Update Git Submodules and Install Dependencies

Source: https://aliasrobotics.github.io/cai/benchmarking/running_benchmarks

This command sequence is used to resolve 'Module not found' errors. It first updates all Git submodules to ensure all necessary code is present, and then installs the 'cvss' Python package, which might be a required dependency.

```shell
# Solution: Update submodules
git submodule update --init --recursive
pip install cvss

```

--------------------------------

### Optimize CAI Costs with Model Selection

Source: https://aliasrobotics.github.io/cai/cli/advanced_usage

This example shows how to use cheaper models for initial reconnaissance and more powerful models for complex analysis. It demonstrates switching to a balanced model like 'alias1' for general tasks and 'gpt-4o' for in-depth analysis.

```shell
# Use cheaper models for reconnaissance
CAI> /agent redteam_agent
CAI> /model alias1  # Balanced cost/performance

# Use powerful models for complex analysis
CAI> /model gpt-4o
CAI> Analyze complex vulnerability chain
```

--------------------------------

### Python: Initialize Assistant Message Stream and Content Part

Source: https://aliasrobotics.github.io/cai/ref/models/openai_chatcompletions

This Python snippet demonstrates the initialization of a new assistant message stream and its first content part. It sets up the necessary state for tracking text content and creates an `ResponseOutputMessage` with an 'in_progress' status. It then yields events to notify consumers about the added message and its initial content part. Dependencies include `FAKE_RESPONSES_ID`, `ResponseOutputText`, `ResponseOutputMessage`, `ResponseOutputItemAddedEvent`, and `ResponseContentPartAddedEvent`.

```python
if not state.text_content_index_and_output:
                            # Initialize a content tracker for streaming text
                            state.text_content_index_and_output = (
                                0 if not state.refusal_content_index_and_output else 1,
                                ResponseOutputText(
                                    text="",
                                    type="output_text",
                                    annotations=[],
                                ),
                            )
                            # Start a new assistant message stream
                            assistant_item = ResponseOutputMessage(
                                id=FAKE_RESPONSES_ID,
                                content=[],
                                role="assistant",
                                type="message",
                                status="in_progress",
                            )
                            # Notify consumers of the start of a new output message + first content part
                            yield ResponseOutputItemAddedEvent(
                                item=assistant_item,
                                output_index=0,
                                type="response.output_item.added",
                            )
                            yield ResponseContentPartAddedEvent(
                                content_index=state.text_content_index_and_output[0],
                                item_id=FAKE_RESPONSES_ID,
                                output_index=0,
                                part=ResponseOutputText(
                                    text="",
                                    type="output_text",
                                    annotations=[],
                                ),
                                type="response.content_part.added",
                            )
```

--------------------------------

### Example Script for Autonomous Security Audit

Source: https://aliasrobotics.github.io/cai/continue_mode

This example script illustrates autonomous vulnerability scanning using CAI's continuation feature. It shows how to leverage the `--continue` flag for automated security audits.

```python
# examples/continue_mode_security_audit.py
# Shows autonomous vulnerability scanning with --continue
python examples/continue_mode_security_audit.py
```

--------------------------------

### Example Script for Continuous Joke Telling

Source: https://aliasrobotics.github.io/cai/continue_mode

This example script demonstrates how to use the `--continue` flag for continuous joke telling. It is intended to showcase the interactive and ongoing nature of the CAI agent's capabilities in a fun context.

```python
# examples/continue_mode_jokes.py
# Demonstrates continuous joke telling with --continue flag
python examples/continue_mode_jokes.py
```

--------------------------------

### BatchTraceProcessor Initialization and Export Logic (Python)

Source: https://aliasrobotics.github.io/cai/ref/tracing/processors

This snippet details the initialization of the BatchTraceProcessor, including setting up the queue, worker thread, and export triggers. It also outlines the logic for exporting batches of spans and traces based on queue size, schedule delay, and a force flush option. Dependencies include `queue`, `threading`, `time`, and a logger.

```python
class BatchTraceProcessor(TracingProcessor):
    """Some implementation notes:
    1. Using Queue, which is thread-safe.
    2. Using a background thread to export spans, to minimize any performance issues.
    3. Spans are stored in memory until they are exported.
    """

    def __init__(
        self,
        exporter: TracingExporter,
        max_queue_size: int = 8192,
        max_batch_size: int = 128,
        schedule_delay: float = 5.0,
        export_trigger_ratio: float = 0.7,
    ):
        """
        Args:
            exporter: The exporter to use.
            max_queue_size: The maximum number of spans to store in the queue. After this, we will
                start dropping spans.
            max_batch_size: The maximum number of spans to export in a single batch.
            schedule_delay: The delay between checks for new spans to export.
            export_trigger_ratio: The ratio of the queue size at which we will trigger an export.
        """
        self._exporter = exporter
        self._queue: queue.Queue[Trace | Span[Any]] = queue.Queue(maxsize=max_queue_size)
        self._max_queue_size = max_queue_size
        self._max_batch_size = max_batch_size
        self._schedule_delay = schedule_delay
        self._shutdown_event = threading.Event()

        # The queue size threshold at which we export immediately.
        self._export_trigger_size = int(max_queue_size * export_trigger_ratio)

        # Track when we next *must* perform a scheduled export
        self._next_export_time = time.time() + self._schedule_delay

        self._shutdown_event = threading.Event()
        self._worker_thread = threading.Thread(target=self._run, daemon=True)
        self._worker_thread.start()

    def on_trace_start(self, trace: Trace) -> None:
        try:
            self._queue.put_nowait(trace)
        except queue.Full:
            logger.warning("Queue is full, dropping trace.")

    def on_trace_end(self, trace: Trace) -> None:
        # We send traces via on_trace_start, so we don't need to do anything here.
        pass

    def on_span_start(self, span: Span[Any]) -> None:
        # We send spans via on_span_end, so we don't need to do anything here.
        pass

    def on_span_end(self, span: Span[Any]) -> None:
        try:
            self._queue.put_nowait(span)
        except queue.Full:
            logger.warning("Queue is full, dropping span.")

    def shutdown(self, timeout: float | None = None):
        """
        Called when the application stops. We signal our thread to stop, then join it.
        """
        self._shutdown_event.set()
        self._worker_thread.join(timeout=timeout)

    def force_flush(self):
        """
        Forces an immediate flush of all queued spans.
        """
        self._export_batches(force=True)

    def _run(self):
        while not self._shutdown_event.is_set():
            current_time = time.time()
            queue_size = self._queue.qsize()

            # If it's time for a scheduled flush or queue is above the trigger threshold
            if current_time >= self._next_export_time or queue_size >= self._export_trigger_size:
                self._export_batches(force=False)
                # Reset the next scheduled flush time
                self._next_export_time = time.time() + self._schedule_delay
            else:
                # Sleep a short interval so we don't busy-wait.
                time.sleep(0.2)

        # Final drain after shutdown
        self._export_batches(force=True)

    def _export_batches(self, force: bool = False):
        """Drains the queue and exports in batches. If force=True, export everything.
        Otherwise, export up to `max_batch_size` repeatedly until the queue is empty or below a
        certain threshold.
        """
        while True:
            items_to_export: list[Span[Any] | Trace] = []

            # Gather a batch of spans up to max_batch_size
            while not self._queue.empty() and (
                force or len(items_to_export) < self._max_batch_size
            ):
                try:
                    items_to_export.append(self._queue.get_nowait())
                except queue.Empty:

```