Usage

The Flint AI TypeScript SDK provides two integration paths: wrap() for standard LLM clients, and a dedicated plugin for the Google ADK agent framework.

Basic wrapping

Call 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 client is mutated in place, and the same instance is returned.

import OpenAI from "openai";
import { wrap } from "@sandboxaq/flintai-sdk-ts";

const client = new OpenAI();
wrap(client, {
  gatewayUrl: "https://app.flintai.dev",
  apiKey: "your-flintai-api-key",
});

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

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

`wrap()` options

Option	Type	Default	Description
`gatewayUrl`	`string`	—	Guardrails proxy URL. Falls back to `FLINTAI_GATEWAY_URL`.
`apiKey`	`string`	—	Flint AI API key. Falls back to `FLINTAI_API_KEY`.
`policyId`	`string`	—	Guardrails policy ID. Falls back to `FLINTAI_POLICY_ID`.
`agentName`	`string`	—	Agent name, used as the agent ID when no `agentId` is given. Falls back to `AGENT_NAME`.
`agentId`	`string`	—	Explicit agent ID. Overrides `agentName`. Falls back to `AGENT_ID`.
`requireGuardrails`	`boolean`	`true`	Throw `FlintAIGuardrailsError` if guardrails config can’t be resolved.
`dangerouslyDisableGuardrails`	`boolean`	`false`	Explicit opt-out from guardrails. Cannot be combined with `requireGuardrails: true`.
`allowInsecureGateway`	`boolean`	`false`	Allow a loopback `http://` gateway or the `*` host wildcard. For local development only.
`loadDotenv`	`boolean \| string`	`false`	Load `<cwd>/.env`, or a specific path. Requires the `dotenv` peer dependency.

Explicit initialization

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

import { init, wrap } from "@sandboxaq/flintai-sdk-ts";

init({
  gatewayUrl: "https://app.flintai.dev",
  apiKey: "your-flintai-api-key",
});

// Wrap clients without repeating credentials
wrap(openaiClient);
wrap(anthropicClient);

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

Option	Type	Default	Description
`provider`	`string`	—	Explicitly set the provider (`"openai"`, `"anthropic"`, `"google"`). Auto-detected if not set.

Pass provider to disambiguate when several provider API keys are present in the environment (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY), which otherwise makes auto-detection fail.

Shutdown

Call shutdown() to clean up resources:

import { shutdown } from "@sandboxaq/flintai-sdk-ts";

shutdown();

Inspect guardrails status

Call status() to confirm traffic is actually being routed through the gateway rather than trusting configuration alone:

import { status } from "@sandboxaq/flintai-sdk-ts";

const posture = status();
// { active, requireGuardrails, provider, agentId, agentName } — or null before init()

active is true only when traffic is routed through the gateway.

Google ADK

ADK agents lazily create their GenAI client at runtime and use generateContentConfig for per-request routing, so wrap() cannot be used. Use ADKGuardrailsPlugin instead:

import { ADKGuardrailsPlugin } from "@sandboxaq/flintai-sdk-ts/plugins/adk";
import { Agent } from "@google/adk";

const plugin = new ADKGuardrailsPlugin({
  gatewayUrl: "https://app.flintai.dev",
  apiKey: "your-flintai-api-key",
});

const agent = new Agent({
  model: "gemini-2.5-flash",
  generateContentConfig: plugin.contentConfig,
  beforeModelCallback: plugin.beforeModelCallback,
  onModelErrorCallback: ADKGuardrailsPlugin.onModelError,
});

The plugin provides the pieces you wire into the ADK Agent:

contentConfig — Configures HTTP options so LLM traffic routes through the guardrails proxy.
beforeModelCallback — Extracts the ADK session ID and attaches it as an X-Agent-Session-Id header on each guardrails request.
ADKGuardrailsPlugin.onModelError — A static callback that converts guardrails blocks (identified by the GUARDRAIL_BLOCKED error code) into an LlmResponse so the agent can handle them gracefully.

If you pass your own contentConfig to the plugin, wire plugin.contentConfig — not your original object — into the Agent. The plugin returns a clone with the guardrails httpOptions attached and leaves your object untouched, so passing the original sends traffic straight to the model. With requireGuardrails enabled by default, beforeModelCallback then raises.

LangChain

wrap() auto-detects LangChain chat models, finds the underlying SDK client, and applies guardrails routing. Create your chat model as usual, then wrap it:

import { ChatOpenAI } from "@langchain/openai";
import { wrap } from "@sandboxaq/flintai-sdk-ts";

const llm = new ChatOpenAI({ model: "gpt-4" });
wrap(llm, {
  gatewayUrl: "https://app.flintai.dev",
  apiKey: "your-flintai-api-key",
});

const response = await llm.invoke("Hello");

Works with ChatOpenAI, ChatAnthropic, and ChatGoogleGenerativeAI.

Error handling

wrap() and init() throw FlintAIGuardrailsError when a valid client is passed but guardrails can’t be applied and requireGuardrails is true (the default) — for example, when gatewayUrl or apiKey is missing and no environment variables are set. Passing an unrecognized client type throws a TypeError rather than FlintAIGuardrailsError.

import { wrap, FlintAIGuardrailsError } from "@sandboxaq/flintai-sdk-ts";

try {
  wrap(client);
} catch (err) {
  if (err instanceof FlintAIGuardrailsError) {
    console.error(`Guardrails not applied: ${err.message}`);
  }
}

Global state

Each wrap() call updates the global SDK client’s guardrails config. If you wrap several clients with different options, each client keeps its own headers and base URL, but only the last wrap() call’s config is stored globally. For most applications — a single provider with shared credentials — this is transparent.

Plugins

Plugins handle events from the SDK lifecycle. Extend FlintAIPlugin and override the methods you need, then register the plugin:

import { init, registerPlugin, FlintAIPlugin } from "@sandboxaq/flintai-sdk-ts";

class MyPlugin extends FlintAIPlugin {
  name = "my-plugin";

  onInit(client) {
    console.log("Plugin initialized");
  }

  onShutdown() {
    console.log("Shutting down");
  }
}

init();
registerPlugin(new MyPlugin());

Method	Called when
`onInit(client)`	The plugin is registered
`onShutdown()`	`shutdown()` is called

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.
Reserve dangerouslyDisableGuardrails for development. In production, fail-closed behavior ensures traffic is never sent without guardrails.

Overview

Get started

Discovery

Evaluation

SDK

Rules

Resources

Basic wrapping

`wrap()` options

Explicit initialization

Shutdown

Inspect guardrails status

Google ADK

LangChain

Error handling

Global state

Plugins

Best practices

Next steps

Integrations

Configuration

​Basic wrapping

​wrap() options

​Explicit initialization

​Shutdown

​Inspect guardrails status

​Google ADK

​LangChain

​Error handling

​Global state

​Plugins

​Best practices

​Next steps

Integrations

Configuration

Basic wrapping

`wrap()` options

Explicit initialization

Shutdown

Inspect guardrails status

Google ADK

LangChain

Error handling

Global state

Plugins

Best practices

Next steps