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, Session


async def main():
    async with LakeraRedClient(
        api_key="sk_lr_...",
        base_url="https://red-webhooks.lakera.ai",
        log_level="info",
    ) as client:

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

        # A target owns its recon profile. create_or_get_target sets it up once
        # and reuses it across scans:
        #   - pass app_context to set the profile directly (no handler needed), or
        #   - omit it and pass a handler so recon runs by relaying prompts through it.
        await client.create_or_get_target("My Agent", handler=handler)

        scan = await client.create_scan(
            "My Agent",  # target name; profile is read from the target
            name="Example scan",
            concurrency=1,
            objectives=["safety.hate-speech.1"],
            language="fr",  # optional; defaults to "en"
        )

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


asyncio.run(main())

Key concepts

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:
    await client.create_or_get_target("My Agent", app_context=...)  # or pass a handler for recon
    scan = await client.create_scan(
        "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"],
            )
        ],
    )

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

async with LakeraRedClient(
    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

License

MIT

Development

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