Run AI Attack Simulation red team sessions

Red teaming is the practice of attacking your own system the way an adversary would, so you find weaknesses before someone else does. For an LLM application, that means sending prompts designed to jailbreak the model, leak its system prompt, extract sensitive data, or redirect it away from its task. HiddenLayer AI Attack Simulation automates this. With the Python SDK, you can run a red team session against any target you can call from Python: a hosted model, an internal API, a chatbot behind a web UI, or an agent.

How a session works

In an SDK-driven session, HiddenLayer generates the attacks and judges the results. Your code only connects the attacker to your target.

You start a session

You call start_session with a name, a label for your target, and settings such as the execution strategy. HiddenLayer creates a workflow and returns a session object with a workflow_id.

HiddenLayer generates attack prompts

HiddenLayer produces attack prompts based on the objectives and techniques you select.

Your handler calls the target

For each attack prompt, the SDK calls a function you write, called the handler. The handler sends the prompt to your application or model and returns the reply as a string. The SDK submits that reply back to HiddenLayer.

HiddenLayer judges and reports

HiddenLayer decides whether each attack succeeded and may continue a multi-turn conversation. When the session finishes, it produces an evaluation report that you can retrieve with the SDK or view in the Console.

Because your code calls the target, HiddenLayer never needs network access to your application or credentials for it.

All AI Attack Simulation endpoints are in beta. The SDK emits a hiddenlayer.BetaWarning when you call them, including through the session helpers. Beta APIs have no compatibility guarantees, and their parameters and responses can change between SDK versions. To hide the warning, call warnings.filterwarnings("ignore", category=hiddenlayer.BetaWarning). See the Beta API FAQ.

Before you begin

Install the SDK and configure credentials. See Installation and Authentication and configuration.
Set HIDDENLAYER_CLIENT_ID and HIDDENLAYER_CLIENT_SECRET in your environment, or set HIDDENLAYER_TOKEN to a bearer token. Every example on this page reads credentials from the environment.
Your tenant needs access to AI Attack Simulation.
You need a way to call your target from Python. The examples use a placeholder function so they run without extra packages. Install whatever your real target needs, such as openai or httpx.

For your first run, use a small static prompt set (execution_strategy_type="static_prompt_set") to confirm that your handler and target work before you start a larger adaptive evaluation. See Execution strategies.

Run a session with the async client

The recommended approach uses AsyncHiddenLayer and run_with_callback_parallel, which processes several attack prompts at the same time. The SDK example notebooks use this pattern. The handler receives four arguments:

Argument	Description
`attack_prompt`	The attack prompt to send to your target.
`history`	Earlier turns in this attack conversation, as a list of dicts with `role` and `content` keys. Use it if your target is stateless and needs the full conversation.
`session_id`	The ID of this attack conversation. Useful if your target keeps its own conversation state.
`target_system_prompt`	The `target_system_prompt` you passed to `start_session`.

It must return the target’s reply as a string.

red_team_async.py

import asyncio
import sys
from typing import Any, Dict, List, Optional

import hiddenlayer
from hiddenlayer import AsyncHiddenLayer
from hiddenlayer.lib.red_team_exceptions import RedTeamSessionError

TARGET_MODEL = "my-support-bot"  # Free-form label for your target
TARGET_SYSTEM_PROMPT = "You are a helpful customer support assistant."


async def call_target(prompt: str, history: List[Dict[str, Any]], system_prompt: str) -> str:
    """Placeholder target. Replace the body with a call to your application or model."""
    # >>> CALL YOUR APP HERE <<<
    # For example: send `history` plus `prompt` to your chat API and return the reply text.
    await asyncio.sleep(0.1)
    return "I'm sorry, I can only help with questions about your account."


async def handler(
    attack_prompt: Optional[str],
    history: Optional[List[Dict[str, Any]]],
    session_id: Optional[str],
    target_system_prompt: Optional[str],
) -> str:
    reply = await call_target(attack_prompt or "", history or [], target_system_prompt or "")
    # Return a non-empty string. The SDK example notebooks return " " when the target replies with nothing.
    return reply or " "


async def main() -> int:
    # Reads HIDDENLAYER_CLIENT_ID and HIDDENLAYER_CLIENT_SECRET (or HIDDENLAYER_TOKEN).
    async with AsyncHiddenLayer() as client:
        workflow_id = None
        try:
            session = await client.evaluation_sessions.red_team.start_session(
                name="Support bot red team",
                target_model=TARGET_MODEL,
                target_system_prompt=TARGET_SYSTEM_PROMPT,
                execution_strategy_type="random",
                max_turns=3,
                max_parallel_techniques=3,
            )
            workflow_id = session.workflow_id
            print(f"Session started: {workflow_id}")

            await session.run_with_callback_parallel(handler)
            print("Session complete.")

            results = await client.evaluations.red_team.retrieve_evaluation_results(workflow_id)
        except RedTeamSessionError as e:
            # Includes PollTimeoutError and "Workflow failed: ..." errors.
            print(f"Red team session error: {e} (workflow: {workflow_id})", file=sys.stderr)
            return 1
        except hiddenlayer.APIStatusError as e:
            print(f"HiddenLayer API error {e.status_code}: {e.message} (workflow: {workflow_id})", file=sys.stderr)
            return 1
        except hiddenlayer.APIConnectionError as e:
            print(f"Could not reach HiddenLayer: {e} (workflow: {workflow_id})", file=sys.stderr)
            return 1

    print(f"Status: {results.status}")
    if results.result.evaluation_report:
        print("\nEvaluation report:\n")
        print(results.result.evaluation_report)

    report = results.result.report or {}
    summary = report.get("summary")
    if isinstance(summary, dict):
        print(f"\nTotal sessions: {summary.get('total_sessions')}")
        print(f"Success rate:   {summary.get('success_rate_pct')}%")
        print(f"Successful:     {summary.get('success_total')} / {summary.get('attempts_total')}")
        print(f"Errors:         {summary.get('error_total')}")
    return 0


if __name__ == "__main__":
    sys.exit(asyncio.run(main()))

Expected result: the script prints the workflow ID right away, then runs until HiddenLayer finishes the session. This can take several minutes. It then prints the final status, the text evaluation report, and summary counts. The session and its report also appear in the Console.

Print or log the workflow_id as soon as the session starts. If your script stops, you need it to resume, check status, or terminate the session.

Variant: target an OpenAI model

This handler sends each attack prompt to an OpenAI chat model. It requires pip install openai and an OPENAI_API_KEY environment variable. It follows the SDK’s red_team_openai.ipynb notebook.

red_team_openai_handler.py

import os
from typing import Any, Dict, List, Optional

from openai import AsyncOpenAI

openai_client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"])
TARGET_MODEL = "gpt-4o-mini"
TARGET_SYSTEM_PROMPT = "You are a helpful AI assistant."


async def handler(
    attack_prompt: Optional[str],
    history: Optional[List[Dict[str, Any]]],
    session_id: Optional[str],
    target_system_prompt: Optional[str],
) -> str:
    messages: List[Dict[str, Any]] = [{"role": "system", "content": TARGET_SYSTEM_PROMPT}]
    messages.extend(history or [])
    messages.append({"role": "user", "content": attack_prompt or ""})
    response = await openai_client.chat.completions.create(model=TARGET_MODEL, messages=messages)
    return response.choices[0].message.content or " "

Use this handler in place of the placeholder in the main example, and pass target_model=TARGET_MODEL and target_system_prompt=TARGET_SYSTEM_PROMPT to start_session.

Control parallelism

run_with_callback_parallel(handler, max_parallel=None, poll_batch_interval=0.5) runs up to max_parallel handler calls at once. If you leave max_parallel as None, it uses the session’s max_parallel_techniques. Set it lower if your target has rate limits. If any handler call raises an exception, the SDK cancels the remaining in-flight calls and re-raises the exception. Handle expected target errors inside your handler if you want the session to continue.

start_session parameters

client.evaluation_sessions.red_team.start_session(...) accepts these keyword arguments. Defaults are the SDK defaults. Where the SDK sends nothing, the HiddenLayer service applies its own default.

Parameter	Default	Description
`name`	Required	Name of the evaluation, shown in the Console.
`target_model`	Required	Free-form label for your target. Because your code calls the target, HiddenLayer does not validate this value against a model catalog.
`target_system_prompt`	`""`	Your target’s system prompt. It gives the attacker context and is passed to your handler.
`objective_ids`	Not sent	List of objective IDs to test, for example `["HLO.01", "HLO.03"]`. See Basic custom attack for objective IDs and names.
`execution_strategy_type`	`"random"`	`"single"`, `"random"`, or `"static_prompt_set"`. Any other value raises `ValueError`.
`prompt_set_id`	Not sent	ID of a prompt set. Required when `execution_strategy_type="static_prompt_set"`. The SDK does not check this for you.
`max_turns`	`3`	Maximum conversation turns per attack session. Applies to `single` and `random`.
`n_random_techniques`	`1`	Number of random techniques to use with the `random` strategy.
`max_parallel_techniques`	`1`	Number of techniques to run in parallel. Also the default `max_parallel` for `run_with_callback_parallel`.
`sessions_per_technique`	`1`	Number of attack sessions per technique. With a static prompt set, the number of attempts per prompt.
`attacker_guidance`	Not sent	Plain-language text that focuses the attacker within your objectives. HiddenLayer rejects text that contains code, markup, or other disallowed characters with a 422 error. Ignored by `static_prompt_set`.
`severity_mapping`	Not sent	Dict that maps objective IDs to `"CRITICAL"`, `"HIGH"`, `"MEDIUM"`, `"LOW"`, or `"NONE"`. Used to derive each session’s severity.
`config_id`	Not sent	ID of a preset configuration. Any parameter you also pass overrides the preset value.
`hiddenlayer_project_id`	`None`	HiddenLayer project ID or alias to associate the session with.
`attacker_model`, `refusal_judge_model`, `objective_judge_model`, `evaluation_report_model`	Not sent	Overrides for the models HiddenLayer uses internally. The service default applies if omitted.
`attacker_max_generation_attempts`	`2`	Maximum attempts for the attacker to generate a prompt per turn.
`poll_interval`	`2.0`	Seconds between checks for the next attack prompt.
`poll_max_wait`	`None`	Overall time limit, in seconds, for polling for attack prompts. See Timeouts.

Read the results

After the session completes, call client.evaluations.red_team.retrieve_evaluation_results(workflow_id). The response has workflow_id, run_id, status, and a result object with these fields:

Field	Type	Description
`result.evaluation_report`	`str` or `None`	A text evaluation report.
`result.report`	`dict` or `None`	Structured results, such as summary counts and per-objective results.
`result.settings`	`dict` or `None`	The settings the session ran with.
`result.usage`	`dict` or `None`	Usage information.
`result.attacker_results`	`dict` or `None`	Attacker results.

The SDK types result.report as a plain dict, so its keys are not guaranteed. The keys used below come from the SDK example notebooks: report["summary"] with total_sessions, success_rate_pct, success_total, attempts_total, and error_total, and report["by_objective"], which maps each objective ID to a dict with success and attempts. Use .get() and check types so your code keeps working if the structure changes.

print_results.py

import asyncio
import sys

import hiddenlayer
from hiddenlayer import AsyncHiddenLayer


async def main(workflow_id: str) -> None:
    async with AsyncHiddenLayer() as client:
        try:
            results = await client.evaluations.red_team.retrieve_evaluation_results(workflow_id)
        except hiddenlayer.NotFoundError:
            sys.exit(f"No workflow found with ID {workflow_id}. Check the ID and environment (region).")
        except hiddenlayer.APIStatusError as e:
            sys.exit(f"HiddenLayer API error {e.status_code}: {e.message}")

    report = results.result.report or {}
    by_objective = report.get("by_objective")
    if isinstance(by_objective, dict):
        for objective_id, stats in by_objective.items():
            if not isinstance(stats, dict):
                continue
            success = stats.get("success", 0)
            attempts = stats.get("attempts", 0)
            outcome = "PASS" if success == 0 else "FAIL"
            print(f"{objective_id}: {success}/{attempts} attacks succeeded [{outcome}]")


if __name__ == "__main__":
    asyncio.run(main(sys.argv[1]))

Run it with the workflow ID as an argument, for example python print_results.py <workflow_id>. An objective is marked FAIL if at least one attack against it succeeded.

Run a session with the sync client

If your code is not asynchronous, use HiddenLayer and run_with_callback. The handler is a regular function. The sync session processes one attack prompt at a time, so it is slower than the parallel async approach.

red_team_sync.py

import sys
from typing import Any, Dict, List, Optional

import hiddenlayer
from hiddenlayer import HiddenLayer
from hiddenlayer.lib.red_team_exceptions import RedTeamSessionError


def call_target(prompt: str, history: List[Dict[str, Any]], system_prompt: str) -> str:
    """Placeholder target. Replace the body with a call to your application or model."""
    # >>> CALL YOUR APP HERE <<<
    return "I'm sorry, I can't help with that."


def handler(
    attack_prompt: Optional[str],
    history: Optional[List[Dict[str, Any]]],
    session_id: Optional[str],
    target_system_prompt: Optional[str],
) -> str:
    return call_target(attack_prompt or "", history or [], target_system_prompt or "") or " "


with HiddenLayer() as client:
    try:
        session = client.evaluation_sessions.red_team.start_session(
            name="Support bot red team (sync)",
            target_model="my-support-bot",
            target_system_prompt="You are a helpful customer support assistant.",
            execution_strategy_type="random",
        )
        print(f"Session started: {session.workflow_id}")

        session.run_with_callback(handler)

        results = client.evaluations.red_team.retrieve_evaluation_results(session.workflow_id)
    except RedTeamSessionError as e:
        sys.exit(f"Red team session error: {e}")
    except hiddenlayer.APIStatusError as e:
        sys.exit(f"HiddenLayer API error {e.status_code}: {e.message}")
    except hiddenlayer.APIConnectionError as e:
        sys.exit(f"Could not reach HiddenLayer: {e}")

print(results.result.evaluation_report)

Expected result: the same as the async example, but attack prompts are handled one at a time. Sessions also expose lower-level methods if you need more control: iterate_actions() yields each ready attack action, and get_next_action(block=True) returns the next one. The async session also provides get_available_actions(max_actions=10). If you use these, you must submit each target reply yourself with client.evaluations.red_team.submit_target_response(workflow_id=..., session_id=..., target_response=...). run_with_callback and run_with_callback_parallel do this for you.

Execution strategies

Set execution_strategy_type to choose how HiddenLayer builds attacks:

Strategy	What it does	Related parameters
`"random"` (default)	AI-generated, adaptive attacks that mix in additional randomly selected techniques per session for variety.	`max_turns`, `n_random_techniques`
`"single"`	AI-generated, adaptive attacks without the random technique mixing.	`max_turns`
`"static_prompt_set"`	Replays a fixed set of prompts. Useful for first-time setup checks, regression testing, and benchmarking.	`prompt_set_id` (required), `sessions_per_technique`

The exact behavioral difference between single and random is not documented in the SDK. The descriptions above follow the existing usage examples and need confirmation.

For static_prompt_set, pass a prompt set ID. The SDK example notebook mentions these built-in sets: do-anything-now-ape, financial-assistant-basic, and financial-assistant-advanced. You can also copy the ID of a prompt set you uploaded from the Console.

# Inside an async function, where `client` is an AsyncHiddenLayer instance:
session = await client.evaluation_sessions.red_team.start_session(
    name="Static prompt regression test",
    target_model="my-support-bot",
    execution_strategy_type="static_prompt_set",
    prompt_set_id="do-anything-now-ape",
)

Monitor a session

Call client.evaluations.red_team.retrieve_status(workflow_id) to check progress, for example from a separate process or dashboard. Useful fields include:

Field	Description
`status`	Workflow status, for example `RUNNING`. Terminal statuses are `COMPLETED`, `FAILED`, `CANCELLED`, `TERMINATED`, and `TIMED_OUT`.
`phase`	Current phase of the workflow.
`progress_completed`, `progress_total`	Progress counters.
`total_sessions`, `active_sessions`, `completed_sessions`, `failed_sessions`	Attack session counts.
`elapsed_seconds`, `eta_seconds`	Elapsed time and estimated time remaining.
`error`, `message`	Error details and status messages, when present.

monitor.py

import sys

import hiddenlayer
from hiddenlayer import HiddenLayer

workflow_id = sys.argv[1]

with HiddenLayer() as client:
    try:
        status = client.evaluations.red_team.retrieve_status(workflow_id)
    except hiddenlayer.NotFoundError:
        sys.exit(f"No workflow found with ID {workflow_id}.")
    except hiddenlayer.APIStatusError as e:
        sys.exit(f"HiddenLayer API error {e.status_code}: {e.message}")

print(f"{status.name}: {status.status} (phase: {status.phase})")
print(f"Progress: {status.progress_completed}/{status.progress_total}")
if status.error:
    print(f"Error: {status.error}")

Resume a session

If your script stops while a session is running, the workflow continues to exist on the HiddenLayer side. Reconnect to it with resume_session(workflow_id, *, poll_interval=2.0, poll_max_wait=None, max_parallel_techniques=None), then drive it again with your handler. If you do not pass max_parallel_techniques, the resumed session uses 1.

resume.py

import asyncio
import sys
from typing import Any, Dict, List, Optional

import hiddenlayer
from hiddenlayer import AsyncHiddenLayer
from hiddenlayer.lib.red_team_exceptions import RedTeamSessionError


async def handler(
    attack_prompt: Optional[str],
    history: Optional[List[Dict[str, Any]]],
    session_id: Optional[str],
    target_system_prompt: Optional[str],
) -> str:
    # >>> CALL YOUR APP HERE <<< (use the same handler as the original run)
    return "I'm sorry, I can't help with that."


async def main(workflow_id: str) -> None:
    async with AsyncHiddenLayer() as client:
        try:
            session = await client.evaluation_sessions.red_team.resume_session(
                workflow_id, max_parallel_techniques=3
            )
            status = await client.evaluations.red_team.retrieve_status(workflow_id)
            print(f"Resumed {session.workflow_id}: {status.status}")

            if status.status == "RUNNING":
                await session.run_with_callback_parallel(handler)

            results = await client.evaluations.red_team.retrieve_evaluation_results(workflow_id)
        except (RedTeamSessionError, hiddenlayer.APIStatusError) as e:
            sys.exit(f"Could not resume workflow {workflow_id}: {e}")

    print(results.result.evaluation_report)


if __name__ == "__main__":
    asyncio.run(main(sys.argv[1]))

Terminate a session

To stop a running session, call terminate_session(workflow_id).

Terminating a session is irreversible. The workflow stops and cannot be restarted. Confirm the workflow ID before you run this.

terminate.py

import sys

import hiddenlayer
from hiddenlayer import HiddenLayer
from hiddenlayer.lib.red_team_exceptions import RedTeamSessionError

workflow_id = sys.argv[1]

with HiddenLayer() as client:
    try:
        client.evaluation_sessions.red_team.terminate_session(workflow_id)
    except (RedTeamSessionError, hiddenlayer.APIStatusError) as e:
        sys.exit(f"Could not terminate workflow {workflow_id}: {e}")

print(f"Terminated {workflow_id}")

The async client provides the same method: await client.evaluation_sessions.red_team.terminate_session(workflow_id).

Timeouts

Red team sessions can run for a long time. Two separate limits apply:

poll_max_wait (on start_session and resume_session, default None): an overall time limit, in seconds, measured from when the session object is created. The SDK checks it while it polls for attack prompts. When exceeded, it raises a plain Exception with a message like Polling timed out after ..., not PollTimeoutError. With the default None, there is no limit.
wait_for_completion: after all attack prompts are handled, run_with_callback and run_with_callback_parallel call wait_for_completion() with its defaults (poll_interval=3.0, max_wait=300.0). If the workflow does not reach a terminal status within 300 seconds, it raises PollTimeoutError. If the workflow status is FAILED, it raises RedTeamSessionError with the message Workflow failed: ....

A client-side timeout does not stop the workflow on the HiddenLayer side. After a timeout, check the status with retrieve_status, fetch results later, or resume the session. You can also call session.wait_for_completion(max_wait=...) yourself with a longer limit, or max_wait=None for no limit.

from hiddenlayer.lib.red_team_exceptions import PollTimeoutError


async def run_with_timeouts(session, handler) -> None:
    """`session` comes from start_session or resume_session on an AsyncHiddenLayer client."""
    try:
        await session.run_with_callback_parallel(handler)
    except PollTimeoutError:
        # All prompts were handled, but the workflow is still finalizing. Wait longer.
        await session.wait_for_completion(max_wait=900.0)
    except Exception as e:
        if str(e).startswith("Polling timed out"):
            print(f"poll_max_wait exceeded; workflow {session.workflow_id} may still be running.")
        else:
            raise

Error handling

Import the session helper exceptions from hiddenlayer.lib.red_team_exceptions:

Exception	Raised when
`RedTeamSessionError`	Base class for the exceptions below. Also raised directly when the workflow fails.
`PollTimeoutError`	`wait_for_completion` exceeds `max_wait`.
`WorkflowNotFoundError`	Intended for a workflow ID that does not exist.
`InvalidSessionError`	Intended for an invalid attack session ID when submitting a target response.

The session helpers map HTTP errors to WorkflowNotFoundError and InvalidSessionError by catching httpx.HTTPStatusError. However, the SDK client raises hiddenlayer.APIStatusError subclasses, such as hiddenlayer.NotFoundError, rather than httpx.HTTPStatusError. In practice you may receive hiddenlayer.NotFoundError or hiddenlayer.BadRequestError instead. This behavior needs confirmation. Until then, catch both RedTeamSessionError and hiddenlayer.APIStatusError, as the examples on this page do.

Also handle errors from your own target inside the handler. An unhandled exception in the handler stops run_with_callback_parallel and cancels other in-flight handler calls. See Error handling for the full SDK exception hierarchy.

Common errors and fixes

ValueError: execution_strategy_type must be 'single', 'random', or 'static_prompt_set'.

You passed an unsupported strategy name. Use one of the three lowercase values.

The static_prompt_set session fails or runs no prompts

Check that you passed prompt_set_id. The SDK does not validate that it is present. Confirm the ID in the Console.

UnprocessableEntityError (422) when starting a session

A parameter failed validation. A common cause is attacker_guidance that contains code, JSON, XML, markdown, or other characters outside plain sentence punctuation. Another is a severity_mapping key that is not a known objective ID. Print e.body for details.

PollTimeoutError: Workflow did not complete within 300.0s

Your handler finished, but the workflow took longer than five minutes to finalize. The workflow is still running. Call session.wait_for_completion(max_wait=...) with a longer limit, or check retrieve_status later and then fetch the results.

Exception: Polling timed out after ...

The poll_max_wait limit you set was exceeded. Increase it, or leave it as None. Resume the session with resume_session to continue.

RedTeamSessionError: Workflow failed: ...

HiddenLayer reported the workflow as FAILED. The message includes the error from the workflow status. Check that your handler returns meaningful strings and that your target is reachable, then start a new session.

NotFoundError (404) for a workflow ID

The workflow ID is wrong, or you are connected to a different environment (region) than the one that created it.

AuthenticationError (401) or PermissionDeniedError (403)

Check your credentials and environment, and confirm that your tenant has access to AI Attack Simulation. See Authentication and configuration.

More examples

The SDK repository includes example notebooks for different kinds of targets: an OpenAI model, a custom HTTP API, a web chat UI driven by Playwright, a static prompt set, a webhook-based target, a WebSocket target, and a generic template. For more background and Console-based workflows, see:

​How a session works

​Before you begin

​Run a session with the async client

​Control parallelism

​start_session parameters

​Read the results

​Run a session with the sync client

​Execution strategies

​Monitor a session

​Resume a session

​Terminate a session

​Timeouts

​Error handling

​Common errors and fixes

​More examples

How a session works

Before you begin

Run a session with the async client

Control parallelism

start_session parameters

Read the results

Run a session with the sync client

Execution strategies

Monitor a session

Resume a session

Terminate a session

Timeouts

Error handling

Common errors and fixes

More examples