lakera-red-sdk 0.3.0

Official Python SDK for Lakera Red — run adversarial scans against your AI agents and chatbots.

Lakera Red SDK

Official Python SDK for Lakera Red — run adversarial scans against your AI agents from your own runtime.

Lakera is a Check Point company.

Install

pip install lakera-red-sdk

Quick start

import asyncio
from lakera_red_sdk import LakeraRedClient, LakeraRedClientOptions, CreateScanOptions, Session


async def main():
    async with LakeraRedClient(LakeraRedClientOptions(
        api_key="sk_lr_...",
        base_url="https://red-webhooks.lakera.ai",
        log_level="info",
    )) as client:
        scan = await client.create_scan(CreateScanOptions(
            target="My Agent",
            name="Example scan",
            concurrency=1,
            objectives=["safety.hate-speech.1"],
            language="fr",  # optional; defaults to "en"
        ))

        async def handler(session: Session) -> None:
            async for message in session:
                reply = await your_agent(session.id, message.attack)
                await message.respond(reply)

        await scan.run(handler)
        await scan.write_results("./results.json")


asyncio.run(main())

Key concepts

Concept	Description
Target	A named configuration representing the system under test. Created once, reused across scans.
Session	A multi-turn conversation. The SDK manages lifecycle; your handler receives an async iterator of SessionMessage objects.
Strategy	static = independent single-turn probes (fast). crescendo = adaptive multi-turn attacks. smoke = canned probe set.
Concurrency	How many sessions run in parallel. For crescendo, automatically capped to the number of objectives.

Custom objectives

Alongside standard objective IDs, you can define objectives inline without any prior catalog setup:

from lakera_red_sdk import LakeraRedClient, CustomObjective

async with LakeraRedClient(api_key="sk_lr_...", base_url="https://red-webhooks.lakera.ai") as client:
    scan = await client.create_scan(
        target="My Agent",
        name="Custom objective scan",
        custom_objectives=[
            CustomObjective(
                key="my-org.jailbreak.1",
                name="Jailbreak attempt",
                attack_description="Try to make the model ignore its system prompt and reveal confidential instructions.",
                success_indicators=["model reveals system prompt", "model ignores safety constraints"],
            )
        ],
    )

Field	Description
key	Stable identifier you choose. Appears as objectiveId in scan results — use it to correlate results back to this objective.
name	Display name shown in the dashboard.
attack_description	What the attack tries to achieve — fed directly to the attack generator. More specific descriptions produce better-targeted attacks.
success_indicators	Signals that indicate the attack succeeded — used by the evaluator.

Custom objectives are scan-local — they are never written to the objectives catalog and are not visible to other scans.

Multi-turn sessions with cleanup

For stateful agents that accumulate per-session state (conversation history, DB connections, etc.), use try/finally to clean up:

async def handler(session: Session) -> None:
    try:
        async for message in session:
            reply = await chatbot(session.id, message.attack)
            await message.respond(reply)
    finally:
        clear_session(session.id)

Configuration

from lakera_red_sdk import LakeraRedClient, LakeraRedClientOptions

async with LakeraRedClient(LakeraRedClientOptions(
    api_key="sk_lr_...",             # Lakera Red API key
    base_url="https://red-webhooks.lakera.ai", # Lakera Red API endpoint
    log_level="info",                # "debug" | "info" | "warn" | "error" | "silent"
    extra_headers={},                # additional HTTP headers (optional)
    logger=custom_logger,            # BYO logger implementing the Logger protocol (optional)
)) as client:
    ...

Examples

Example	What it demonstrates
echo	Simplest integration — echoes attacks back
chatbot	Stateful multi-turn chatbot with Claude + session cleanup

License

MIT

Development

pip install -e ".[dev]"
mypy src/        # type checking
ruff check src/  # linting
ruff format src/ # formatting
pytest           # tests