Get started with AI Guardrails

Background

AI Guardrails protects large language model (LLM) applications against threats such as prompt injection, jailbreaking, and data exfiltration. Scanners are the core capability of AI Guardrails. They are real-time policies that monitor and intercept traffic flowing into and out of your LLMs and applications. Guardrails identify undesirable content by using keywords, regular expressions, AI-generated definitions, or proprietary scanning models.

AI Guardrails scan prompts. It also measures testing and efficacy metrics against those prompts.

INFO

Scanners is a legacy term. Note how AI Guardrails uses the scanners endpoint for guardrails functionality.

Overview

With this guide you can learn how to:

Send a scan request
Send a prompt to the default provider
Create a project
Add a scanner to a project

This guide is intended for users who are new to AI Guardrails. It assumes basic knowledge of:

REST APIs and HTTP requests
Python programming
LLM concepts and terminology

Before you begin

Before you begin, make sure you have:

An AI Security account: An active account to access the AI Security API. If you don't have an account, contact F5 support.
Required permissions: Permissions to create tokens, send scan requests, create projects, and manage scanners. For more information, see Permissions in AI Security.
A global API token: A token to authenticate your requests. For instructions, see First steps with AI Security.
An installed Python SDK: The AI Security Python Software Development Kit (SDK). See Install the SDK for instructions.
A configured LLM provider: At least one LLM provider added to your AI Security account. See First steps with AI Security for instructions.

SDK usage

The following examples use the Python SDK. This is how you should interact with the AI Security API.

Send a scan request

A scan request verifies text input against enabled scanners. A global token runs against globally available scanners. In contrast, a project token runs against scanners defined in that project.

Add your API token to the following code sample.

python

from calypsoai import CalypsoAI

# Define the URL and token for CalypsoAI
CALYPSOAI_URL = "https://www.us1.calypsoai.app"
CALYPSOAI_TOKEN = "ADD-YOUR-TOKEN-HERE"

# Initialize the CalypsoAI client
cai = CalypsoAI(url=CALYPSOAI_URL, token=CALYPSOAI_TOKEN)

# Send a scan request
prompt = cai.scans.scan("What is your name?")
print(prompt.model_dump_json(indent=2))

Run the script.
The script sends a scan request to the AI Security API.

Review the response.

The following response shows the parameters relevant to this request.

json

{
  "id": "01985bd2-bb2c-702d-9b9c-30e8ec065504",
  "input": "What is your name?",
  "result": {
    "outcome": "cleared",
    "scannerResults": [
      {
        "outcome": "passed",
        "scanDirection": "request",
        "scannerId": "01983d0c-f1cc-700a-ab56-6600efc7dfb9",
        "scannerVersionMeta": {
          "name": "v_1",
        },
      }
    ]
  },
  "type": "scan",
  "userId": "machine=0198560b-1ca8-7052-bde5-82898e17c4cf",
}

Key response parameters:

id: The unique identifier for the scan request.
input: The text that was scanned.
result.outcome: The result of the scan. In this example, the scan request was not flagged by any scanners.
result.scannerResults: A list of every scanner that ran during the scan.
result.scannerResults.outcome: The outcome of each individual scanner.
result.scannerResults.scanDirection: The scanning direction of each individual scanner.
result.scannerResults.scannerVersionMeta.name: The name of the scanner version used for each scanner.
type: The scan type. In this example, the type is a scan request.
userId: The ID of the user or machine that ran the scan.

Select to view the full response.

json

{
  "externalMetadata": null,
  "id": "01985bd2-bb2c-702d-9b9c-30e8ec065504",
  "input": "What is your name?",
  "preserve": false,
  "projectId": "01951ee7-d3b7-70bd-9c11-12f73f967057",
  "receivedAt": "2025-07-30T14:53:13.900184Z",
  "result": {
    "outcome": "cleared",
    "scannerResults": [
      {
        "completedDate": "2025-07-30T14:53:14.066272Z",
        "customConfig": false,
        "data": {
          "type": "custom"
        },
        "outcome": "passed",
        "scanDirection": "request",
        "scannerId": "01983d0c-f1cc-700a-ab56-6600efc7dfb9",
        "scannerVersionMeta": {
          "createdAt": "2025-07-24T15:34:10.947982Z",
          "createdBy": null,
          "description": "",
          "id": "01983d12-1103-70ef-be4d-bb6e0eb4ddff",
          "name": "v_1",
          "published": true
        },
        "startedDate": "2025-07-30T14:53:13.903866Z"
      }
    ]
  },
  "type": "scan",
  "userId": "machine=0198560b-1ca8-7052-bde5-82898e17c4cf",
  "endpointId": "01951ee7-d3b7-70bd-9c11-12f73f967057"
}

Send a prompt to the default provider

Send a prompt to the default LLM provider configured for the API token you provide. AI Guardrails scanners validate each prompt before forwarding it and can block flagged prompts and responses.

Add your API token to the following code sample.

python

from calypsoai import CalypsoAI

# Define the URL and token for CalypsoAI
CALYPSOAI_URL = "https://www.us1.calypsoai.app"
CALYPSOAI_TOKEN = "ADD-YOUR-TOKEN-HERE"

# Initialize the CalypsoAI client
cai = CalypsoAI(url=CALYPSOAI_URL, token=CALYPSOAI_TOKEN)

# Send a prompt request
prompt = cai.prompts.send("What is your name?")
print(prompt.model_dump_json(indent=2))

Run the script.
The script sends a prompt to the default LLM provider. AI Guardrails scanners verify the prompt before forwarding it to the provider.

Review the response.

The following response sample shows the main parameters relevant to this request.

json

{
  "id": "01985bd0-6e4b-70a3-94f6-7ac8f72706ad",
  "input": "What is your name?",
  "result": {
    "outcome": "cleared",
    "response": "I am called Assistant. How can I help you today?",
    "scannerResults": [
      {
        "outcome": "passed",
        "scanDirection": "response",
        "scannerId": "01983d0c-f1cc-700a-ab56-6600efc7dfb9",
        "scannerVersionMeta": {
          "name": "v_1",
        }
      }
    ]
  },
  "type": "prompt",
  "userId": "machine=0198560b-1ca8-7052-bde5-82898e17c4cf"
}

Key response parameters:

id: The unique identifier for the prompt scan request.
input: The text that was scanned.
result.outcome: The overall result of the scan. In this example, the prompt was not flagged by any scanners.
result.scannerResults: A list of every scanner that ran during the scan.
result.scannerResults.outcome: The outcome of each individual scanner.
result.scannerResults.scanDirection: The scanning direction of each individual scanner. If a scanner works in both directions, request and response results appear as separate items.
result.scannerResults.scannerVersionMeta.name: The name of the scanner version used for each scanner.
type: The scan type. In this example, the type is a prompt.
userId: The ID of the user or machine that ran the scan.

Select to view the full response.

json

{
  "externalMetadata": null,
  "fromTemplate": false,
  "id": "01985bd0-6e4b-70a3-94f6-7ac8f72706ad",
  "input": "What is your name?",
  "memory": null,
  "orgId": null,
  "parentId": null,
  "preserve": false,
  "projectId": "01951ee7-d3b7-70bd-9c11-12f73f967057",
  "provider": "01953db0-fb71-7035-af13-ef2e37591557",
  "receivedAt": "2025-07-30T14:50:43.147654Z",
  "result": {
    "analysis": null,
    "files": null,
    "outcome": "cleared",
    "providerResult": {
      "data": "I am called Assistant. How can I help you today?",
      "input": null,
      "receivedDate": "2025-07-30T14:50:44.227745Z",
      "sentDate": "2025-07-30T14:50:43.318925Z",
      "statusCode": 200
    },
    "response": "I am called Assistant. How can I help you today?",
    "scannerResults": [
      {
        "completedDate": "2025-07-30T14:50:44.342269Z",
        "customConfig": false,
        "data": {
          "type": "custom"
        },
        "outcome": "passed",
        "scanDirection": "response",
        "scannerId": "01983d0c-f1cc-700a-ab56-6600efc7dfb9",
        "scannerVersionMeta": {
          "createdAt": "2025-07-24T15:34:10.947982Z",
          "createdBy": null,
          "description": "",
          "id": "01983d12-1103-70ef-be4d-bb6e0eb4ddff",
          "name": "v_1",
          "published": true
         },
         "startedDate": "2025-07-30T14:50:44.227764Z"
      }
    ]
  },
  "type": "prompt",
  "userId": "machine=0198560b-1ca8-7052-bde5-82898e17c4cf",
  "endpointId": "01951ee7-d3b7-70bd-9c11-12f73f967057"
}

Create a project

Create a project to organize scanner configurations and manage access to specific models for selected groups of users. Use projects to create different scanner configurations and control which users can access which LLM providers.

Edit the following code sample.

python

from calypsoai import CalypsoAI
from calypsoai.datatypes import ProjectType

# Define the URL and token for CalypsoAI
CALYPSOAI_URL = "https://www.us1.calypsoai.app"
CALYPSOAI_TOKEN = "ADD-YOUR-TOKEN-HERE"

# Initialize the CalypsoAI client
cai = CalypsoAI(url=CALYPSOAI_URL, token=CALYPSOAI_TOKEN)

# Get all provider names
provider_names = [provider for provider in cai.providers.getAllByName()]

# Get the first provider
provider = cai.providers.get(provider_names[0])

# Create a new project
project = cai.projects.create(
    name="ADD-YOUR-PROJECT-NAME-HERE",
    projectType=ProjectType.APP,
    admins=['ADD-USER-ID-HERE'],
    providers=[provider.id],
    friendlyId="ADD-FRIENDLY-ID-HERE"
)

# Print the response
print(project.model_dump_json(indent=2))

Update the required parameters:

Add your API token.
In cai.projects.create, set the following parameters:

Parameter	Description
`name`	Provide a name for the project.
`projectType`	Specify the project type. Available values are `app`, `chat`, and `bot`.
`admins`	Provide a list of user IDs for project administrators. Administrators manage projects by adding providers, configuring scanners, and creating tokens.
`providers`	Provide a list of provider IDs that you want to access in the project.
`friendlyId`	Optional. Provide a custom ID to make the project easier to identify.

Optional parameters

You can also set the following optional parameters:

Parameter	Description
`scanners`	The list of scanners to add to the project.
`members`	The list of user IDs for project members. Project members can access the project but can't change the project configuration.

Run the script.
The script creates a new project with the specified configuration.

Review the response.

The following response sample shows the main parameters relevant to this request.

json

{
  "config": {
    "packages": [],
    "providers": [
      {
        "enabled": true,
        "id": "providerId",
        "name": "provider"
      }
    ],
    "scanners": [
      {
        "blocking": true,
        "enabled": true,
        "id": "scannerId"
      }
    ]
  },
  "friendlyId": "ADD-FRIENDLY-ID-HERE",
  "id": "projectId",
  "name": "ADD-YOUR-PROJECT-NAME-HERE",
  "type": "app"
}

Key response parameters:

config.packages: The scanner packages added to the project.
config.providers: The providers added to the project.
config.scanners: The scanners added to the project.
id: The unique identifier for the project.
name: The project name.
type: The project type.

Select to view the full response.

json

{
    "adminCount": 1,
    "adminRoleId": "userId",
    "chatbotId": null,
    "config": {
      "packages": [],
      "providerRouting": null,
      "providers": [
        {
          "default": true,
          "enabled": true,
          "id": "providerId",
          "name": "provider",
          "type": "groq"
        }
      ],
      "scanners": [
        {
          "blocking": true,
          "enabled": true,
          "flagMessage": null,
          "force": false,
          "id": "scannerId"
        }
      ]
    },
    "createdAt": "2025-04-17T11:02:49.730112Z",
    "friendlyId": "ADD-FRIENDLY-ID-HERE",
    "id": "projectId",
    "memberCount": 1,
    "memberRoleId": "roleId",
    "name": "ADD-YOUR-PROJECT-NAME-HERE",
    "orgId": null,
    "type": "app"
}

Add a scanner to a project

Add a scanner to the project you created. Scanners can have multiple published versions with different configurations. By default, AI Guardrails sets the most recent version as active.

Edit the following code sample.

python

from calypsoai import CalypsoAI
from calypsoai.datatypes import ProjectConfigScanner, UUID

# Define the URL and token for CalypsoAI
CALYPSOAI_URL = "https://www.us1.calypsoai.app"
CALYPSOAI_TOKEN = "ADD-YOUR-TOKEN-HERE"

# Initialize the CalypsoAI client
cai = CalypsoAI(url=CALYPSOAI_URL, token=CALYPSOAI_TOKEN)

# Get all scanners
scanners = [scanner for scanner in cai.scanners.iterate()]

# Update the project with the first scanner
cai.projects.update(
    project="ADD-YOUR-PROJECT-ID-HERE",
    scanners=[ProjectConfigScanner(id=scanners[0].id, version="ADD-YOUR-VERSION-ID-HERE", enabled=True)]
)

Update the required parameters:
- Add your API token.
- In cai.projects.update.project, provide the ID of the project you created.
- In cai.projects.update.scanners, set the following:
Parameter Description
version Provide the scanner version ID.
enabled Make sure this is set to true.
Run the script.
The script adds the scanner to the project. If the request is successful, you receive the None response.

Parameter	Description
`version`	Provide the scanner version ID.
`enabled`	Make sure this is set to `true`.

Next steps

Now that you have completed this guide, try the following tasks to continue working with AI Guardrails:

Create a provider: Add additional LLM providers to your AI Security account.
Send a prompt to a specific provider: Route prompts to a specific LLM provider instead of using the default.
Send a prompt to a specific project: Send prompts by using project-specific scanner configurations.
Create a custom scanner: Build custom scanners tailored to your specific use cases.

Anthropic

Admin

Agent-Sessions

Audit

Auth

Branding

Campaign-Runs

Campaign-Schedules

Campaigns

Chats

Datasets

Files

Generations

License

Org

Project

Projects

Prompts

Providers

Refusal-Catalogs

Scanner-Packages

Scanners

Scans

Secrets

Tokens

Users

Google

Openai

CAI deployment application

Operator

Get started with AI Guardrails

Background

Overview

Before you begin

Send a scan request

Send a prompt to the default provider

Create a project

Add a scanner to a project

Next steps

See also

Get started with AI Guardrails ​

Background ​

Overview ​

Before you begin ​

Send a scan request ​

Send a prompt to the default provider ​

Create a project ​

Add a scanner to a project ​

Next steps ​

See also ​

Get started with AI Guardrails

Background

Overview

Before you begin

Send a scan request

Send a prompt to the default provider

Create a project

Add a scanner to a project

Next steps

See also