Skip to main content
The Switch Trust Python SDK needs a gateway URL and a Switch Trust API key to route traffic through the guardrails proxy. You can provide them as function parameters, environment variables, or in a .env file. Your LLM client keeps using its own provider key.

Environment variables

Set these variables in your shell or deployment environment to avoid hard coding credentials: When environment variables are set, you can call wrap() without passing credentials:

.env file support

To read settings from a .env file, install the [dotenv] extra:
Then pass load_dotenv=True to read .env from the current working directory, or pass a path to read a specific file:
.env

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 (SWITCH_TRUST_*), including any loaded from a .env file with load_dotenv
  3. The key on the client (client.api_key), for the LLM provider key only, in wrap() with forward_llm_key=True

Gateway URL

The gateway URL is your Switch Trust guardrails proxy endpoint. Find it in Switch Trust:
  1. Navigate to Agents and select your agent
  2. Open the Sessions tab
  3. The gateway URL is shown in the code snippet
The gateway URL must use https://, except for a loopback gateway (localhost, 127.0.0.1, or ::1) during local development, which can also use plaintext http://. Any loopback gateway, over https:// or http://, needs allow_insecure_gateway=True passed to init() or wrap(). The SDK warns when using HTTP, even on loopback.

Gateway host allowlist

By default, the SDK only allows connections to api.switchagents.ai, api.flintai.dev, and app.flintai.dev. This prevents credentials from being accidentally sent to an unintended endpoint. To use a self-hosted gateway, set SWITCH_TRUST_ALLOWED_GATEWAY_HOSTS:
To allow a loopback gateway or the * wildcard, pass allow_insecure_gateway=True in code. The environment and a .env file can’t turn either on. Without it, the SDK raises an error when it reads the configuration.

API keys

Switch Trust API key

Create and manage API keys in Switch Trust: navigate to Settings, then select API keys. Give the key the Ingest only role, or Editor or higher. The gateway refuses a Viewer key.
Copy your API key immediately when created — it is only shown once.
Pass the key directly or set the SWITCH_TRUST_API_KEY environment variable:

LLM provider API key

Your client’s own provider key reaches the provider through the gateway, as it would without the SDK. The gateway holds no provider credentials of its own, so each request uses a key you supply. To send a different key from the one your client has, forward one. A forwarded key replaces the client’s. Use one of these:
  • llm_api_key: Pass the key. Use this to forward a key for Google GenAI, whose client doesn’t expose api_key as an attribute.
  • forward_llm_key=True: Take the key from client.api_key and forward it. wrap() only.
  • SWITCH_TRUST_LLM_API_KEY: Set the environment variable.

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.
You can also set this via the SWITCH_TRUST_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 because of missing credentials or an unrecognized client type, the SDK raises SwitchTrustGuardrailsError instead of sending traffic unguarded. To allow operation without guardrails (for example, in local development), pass 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.

Next steps

Usage

Wrapping patterns, advanced usage, and best practices

Integrations

Provider-specific setup for OpenAI, Anthropic, Google GenAI, LangChain, and ADK