Configuration

The Flint AI Python SDK needs two pieces of information to route traffic through the guardrails proxy: a gateway URL and an API key. You can provide these as function parameters, environment variables, or in a .env file.

Environment variables

Set these variables in your shell or deployment environment to avoid hard coding credentials:

Variable	Required	Description
`FLINTAI_GATEWAY_URL`	Yes	Guardrails proxy URL
`FLINTAI_API_KEY`	Yes	Your Flint AI API key
`FLINTAI_LLM_API_KEY`	No	Your upstream LLM provider API key, forwarded to the gateway as `X-LLM-API-Key`. Pass explicitly for Google GenAI (can’t be auto-extracted); omit to let the proxy use its own upstream credentials.
`FLINTAI_POLICY_ID`	No	Guardrails policy ID to enforce on requests
`FLINTAI_ALLOWED_GATEWAY_HOSTS`	No	Comma-separated allowlist of permitted gateway hostnames. Defaults to `app.flintai.dev`. Set to `*` to allow any host.
`AGENT_ID`	No	Agent identifier attached to guardrails requests
`AGENT_NAME`	No	Agent name attached to guardrails requests

When environment variables are set, you can call wrap() without passing credentials:

import openai
import flintai

client = openai.OpenAI()
client = flintai.wrap(client)

`.env` file support

Install the [dotenv] extra to load variables from a .env file automatically:

pip install "flintai-sdk-py[dotenv]"

.env

FLINTAI_GATEWAY_URL=https://app.flintai.dev
FLINTAI_API_KEY=your-flintai-api-key
FLINTAI_LLM_API_KEY=your-llm-api-key

The SDK reads .env from the current working directory on first use.

Precedence

When the same setting is provided in multiple places, the SDK uses this order:

Explicit parameters passed to wrap() or init()
Environment variables (FLINTAI_*)
.env file (if [dotenv] is installed)

Gateway URL

The gateway URL is your Flint AI guardrails proxy endpoint. Find it in Flint AI Platform:

Navigate to Agents and select your agent
Open the Sessions tab
The gateway URL is shown in the code snippet

The gateway URL must use https://. Plaintext http:// is only allowed for localhost, 127.0.0.1, and ::1 (local development). The SDK warns when using HTTP, even on loopback.

Gateway host allowlist

By default, the SDK only allows connections to app.flintai.dev. This prevents credentials from being accidentally sent to an unintended endpoint. To use a self-hosted gateway, set FLINTAI_ALLOWED_GATEWAY_HOSTS:

# Single host
export FLINTAI_ALLOWED_GATEWAY_HOSTS=gateway.yourcompany.com

# Multiple hosts
export FLINTAI_ALLOWED_GATEWAY_HOSTS=gateway.yourcompany.com,gateway-staging.yourcompany.com

# Allow any host (use with caution)
export FLINTAI_ALLOWED_GATEWAY_HOSTS=*

Loopback hosts are always allowed regardless of this setting.

API keys

Flint AI API key

Create and manage API keys in Flint AI Platform: navigate to Settings, then select API Keys.

Copy your API key immediately when created — it is only shown once.

Pass the key directly or set the FLINTAI_API_KEY environment variable:

import flintai

# Pass directly
client = flintai.wrap(client, api_key="your-flintai-api-key", gateway_url="https://app.flintai.dev")

# Or use environment variable
# export FLINTAI_API_KEY=your-flintai-api-key
client = flintai.wrap(client, gateway_url="https://app.flintai.dev")

LLM provider API key

By default, the gateway supplies its own upstream credentials — you don’t need to forward your provider key. If you need to use your own provider credentials, you have two options:

llm_api_key — Explicitly pass the key. Required for Google GenAI if you want to forward your key (since its client doesn’t expose api_key as an attribute). Omit to let the proxy use its own upstream credentials.
forward_llm_key=True — Auto-extract the key from client.api_key and forward it (wrap() only)

# Explicit key (required for Google GenAI)
client = flintai.wrap(client, llm_api_key="your-gemini-api-key", ...)

# Auto-extract from client (OpenAI, Anthropic)
client = flintai.wrap(client, forward_llm_key=True, ...)

Policy ID

A policy ID tells the gateway which guardrails policy to enforce. Policies apply input/output detectors that can block, redact, or alert on unsafe content.

client = flintai.wrap(
    client,
    gateway_url="https://app.flintai.dev",
    api_key="your-flintai-api-key",
    policy_id="your-policy-id",
)

You can also set this via the FLINTAI_POLICY_ID environment variable.

Fail-closed behavior

The SDK defaults to require_guardrails=True. If guardrails configuration is missing or can’t be applied — for example, missing credentials or an unrecognized client type — the SDK raises FlintAIGuardrailsError instead of sending traffic unguarded. To allow operation without guardrails (for example, in local development), pass require_guardrails=False:

client = flintai.wrap(client, require_guardrails=False)

With require_guardrails=False, the SDK logs a warning when guardrails are not configured but still wraps the client and allows it to make calls directly to the provider.

Overview

Getting Started

Python SDK

Rules Reference

Resources

Environment variables

`.env` file support

Precedence

Gateway URL

Gateway host allowlist

API keys

Flint AI API key

LLM provider API key

Policy ID

Fail-closed behavior

Next steps

Usage

Integrations

​Environment variables

​.env file support

​Precedence

​Gateway URL

​Gateway host allowlist

​API keys

​Flint AI API key

​LLM provider API key

​Policy ID

​Fail-closed behavior

​Next steps

Usage

Integrations

Environment variables

`.env` file support

Precedence

Gateway URL

Gateway host allowlist

API keys

Flint AI API key

LLM provider API key

Policy ID

Fail-closed behavior

Next steps