lakera-red-sdk 0.2.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.

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