Usage

The Flint AI Python SDK provides two integration paths: flintai.wrap() for standard LLM clients, and framework-specific plugins for agent frameworks like Google ADK and LangChain.

Basic wrapping

Call flintai.wrap() on your existing LLM client. The SDK auto-detects the provider, rewrites the client’s base URL to route through the guardrails proxy, and injects authentication headers. The same client instance is returned — mutated in place.

import openai
import flintai

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

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)

Set FLINTAI_GATEWAY_URL and FLINTAI_API_KEY as environment variables, then call flintai.wrap(client) without parameters. See Configuration for details.

`wrap()` parameters

Parameter	Type	Default	Description
`client`	any	—	The LLM client to wrap (positional, required)
`gateway_url`	`str`	`None`	Guardrails proxy URL. Falls back to `FLINTAI_GATEWAY_URL`.
`api_key`	`str`	`None`	Flint AI API key. Falls back to `FLINTAI_API_KEY`.
`llm_api_key`	`str`	`None`	Upstream LLM provider API key, forwarded as `X-LLM-API-Key`. Falls back to `FLINTAI_LLM_API_KEY`.
`policy_id`	`str`	`None`	Guardrails policy ID. Falls back to `FLINTAI_POLICY_ID`.
`require_guardrails`	`bool`	`True`	Raise `FlintAIGuardrailsError` if guardrails can’t be applied.
`forward_llm_key`	`bool`	`False`	Auto-extract the provider key from `client.api_key` and forward it.

Explicit initialization

For more control, use flintai.init() to initialize the SDK separately from wrapping. This is useful when registering plugins or when you want to configure guardrails once and wrap multiple clients.

import flintai

flintai.init(
    gateway_url="https://app.flintai.dev",
    api_key="your-flintai-api-key",
)

# Wrap clients without repeating credentials
client1 = flintai.wrap(openai_client)
client2 = flintai.wrap(anthropic_client)

init() accepts the same guardrails parameters as wrap(), plus:

Parameter	Type	Default	Description
`provider`	`str`	`None`	Explicitly set the provider (`"openai"`, `"anthropic"`, `"google"`). Auto-detected if not set.

Shutdown

Call flintai.shutdown() to clean up resources and restore wrapped clients to their original configuration. The SDK registers an atexit handler automatically, so explicit shutdown is optional in most cases.

flintai.shutdown()

Google ADK

ADK agents lazily create their GenAI client at runtime, so flintai.wrap() cannot be used. Use ADKGuardrailsPlugin instead:

from flintai.plugins.adk import ADKGuardrailsPlugin
from google.adk.agents import LlmAgent

plugin = ADKGuardrailsPlugin(
    gateway_url="https://app.flintai.dev",
    api_key="your-flintai-api-key",
    llm_api_key="your-gemini-api-key",
)

agent = LlmAgent(
    name="my_agent",
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant.",
    tools=[...],
    generate_content_config=plugin.content_config,
    before_model_callback=plugin.before_model_callback,
    on_model_error_callback=plugin.on_model_error,
)

Set FLINTAI_GATEWAY_URL, FLINTAI_API_KEY, and FLINTAI_LLM_API_KEY as environment variables (or in a .env file), then create the plugin with no arguments: ADKGuardrailsPlugin().

The plugin provides three components to pass to the ADK Agent:

content_config — Configures HTTP options to route requests through the guardrails proxy
before_model_callback — Injects agent identity (X-Agent-Id, X-Agent-Name from the callback context or AGENT_NAME env var) and session ID (X-Agent-Session-Id) headers on each LLM call
on_model_error — Converts guardrails blocks (detected via the GUARDRAIL_BLOCKED error code) into an LlmResponse so the agent can handle them gracefully instead of crashing

The before_model_callback fails closed by default. If guardrails routing was never applied (the request has no http_options), it raises FlintAIGuardrailsError. Pass require_guardrails=False to the plugin for best-effort behavior.

LangChain middleware

For LangChain agents, use LangChainGuardrailsMiddleware to intercept model calls and inject guardrails routing:

from flintai.plugins.langchain import LangChainGuardrailsMiddleware
from langchain.agents import create_agent

middleware = LangChainGuardrailsMiddleware(
    gateway_url="https://app.flintai.dev",
    api_key="your-flintai-api-key",
)

agent = create_agent(
    model="openai:gpt-4o",
    tools=[...],
    middleware=[middleware],
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Hello!"}]},
    config={"configurable": {"thread_id": "session-456"}},
)

Set FLINTAI_GATEWAY_URL and FLINTAI_API_KEY as environment variables, then create the middleware with no arguments: LangChainGuardrailsMiddleware().

The middleware automatically:

Detects the underlying SDK client (OpenAI, Anthropic, or Google GenAI) from the LangChain chat model
Applies guardrails routing on the first model call
Extracts thread_id from the LangChain runtime config and attaches it as X-Agent-Session-Id

Error handling

The SDK raises FlintAIGuardrailsError when guardrails can’t be applied and require_guardrails is True (the default). Common scenarios:

Missing gateway_url or api_key (and no environment variables set)
Unrecognized client type passed to wrap()
Async client passed to wrap() (not supported)
ADK agent passed to wrap() instead of using ADKGuardrailsPlugin

from flintai import FlintAIGuardrailsError

try:
    client = flintai.wrap(client)
except FlintAIGuardrailsError as e:
    print(f"Guardrails not applied: {e}")

Thread safety

flintai.init(), flintai.wrap(), and flintai.shutdown() are not thread-safe. Call them from the main thread during application startup.
Once initialized, wrapped clients are thread-safe — the underlying SDK clients handle their own concurrency.
Double-wrapping is safe — the SDK detects already-wrapped clients and skips them with a warning.

Async clients

Async clients (AsyncOpenAI, AsyncAnthropic) are not supported. Use sync clients only. Passing an async client to wrap() raises a TypeError.

Best practices

Use environment variables for credentials instead of hardcoding them. See Configuration.
Pin your provider SDK versions to the tested ranges to avoid breakage from private API changes. See Integrations for version compatibility.
Wrap once per client during startup. The SDK mutates the client in place, so wrapping the same client multiple times is a no-op (with a warning).
Use require_guardrails=False only in development. In production, fail-closed behavior ensures traffic is never sent without guardrails.

Overview

Getting Started

Python SDK

Rules Reference

Resources

Basic wrapping

`wrap()` parameters

Explicit initialization

Shutdown

Google ADK

LangChain middleware

Error handling

Thread safety

Async clients

Best practices

Next steps

Integrations

Configuration

​Basic wrapping

​wrap() parameters

​Explicit initialization

​Shutdown

​Google ADK

​LangChain middleware

​Error handling

​Thread safety

​Async clients

​Best practices

​Next steps

Integrations

Configuration

Basic wrapping

`wrap()` parameters

Explicit initialization

Shutdown

Google ADK

LangChain middleware

Error handling

Thread safety

Async clients

Best practices

Next steps