> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchagents.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs moved from docs.flintai.dev to docs.switchagents.ai. Use docs.switchagents.ai for every link and request.
> To search these docs from an AI tool, connect the MCP server at https://docs.switchagents.ai/mcp. The page index is at https://docs.switchagents.ai/llms.txt.

# Configuration

> Configure gateway URL, API keys, and environment variables

The Switch Trust 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 Switch Trust 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:

```python theme={null}
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:

```bash theme={null}
pip install "flintai-sdk-py[dotenv]"
```

```bash title=".env" theme={null}
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:

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

## Gateway URL

The gateway URL is your Switch Trust guardrails proxy endpoint. Find it in [Switch Trust](https://app.flintai.dev):

1. Navigate to **Agents** and select your agent
2. Open the **Sessions** tab
3. The gateway URL is shown in the code snippet

<Note>
  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.
</Note>

### 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`:

```bash theme={null}
# 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

### Switch Trust API key

Create and manage API keys in [Switch Trust](https://app.flintai.dev): navigate to **Settings**, then select **API Keys**.

<Warning>
  Copy your API key immediately when created — it is only shown once.
</Warning>

Pass the key directly or set the `FLINTAI_API_KEY` environment variable:

```python theme={null}
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)

```python theme={null}
# 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](/switch-trust/guardrails/policies) to enforce. Policies apply input/output detectors that can block, redact, or alert on unsafe content.

```python theme={null}
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`:

```python theme={null}
client = flintai.wrap(client, require_guardrails=False)
```

<Note>
  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.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Usage" icon="code" href="/switch-trust/sdk/python/usage">
    Wrapping patterns, advanced usage, and best practices
  </Card>

  <Card title="Integrations" icon="plug" href="/switch-trust/sdk/python/integrations">
    Provider-specific setup for OpenAI, Anthropic, Google GenAI, LangChain, and ADK
  </Card>
</CardGroup>