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

# Usage

> Wrap LLM clients and route traffic through guardrails

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.

```typescript theme={null}
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" }],
});
```

<Tip>
  Set `FLINTAI_GATEWAY_URL` and `FLINTAI_API_KEY` as environment variables, then call `wrap(client)` without options. See [Configuration](/flintai/platform/sdk/typescript/configuration) for details.
</Tip>

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

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

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

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

```typescript theme={null}
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.

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

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

```typescript theme={null}
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`.

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

```typescript theme={null}
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](/flintai/platform/sdk/typescript/configuration).
* **Pin your provider SDK versions** to the tested ranges to avoid breakage from private API changes. See [Integrations](/flintai/platform/sdk/typescript/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.

## Next steps

<CardGroup cols={2}>
  <Card title="Integrations" icon="plug" href="/flintai/platform/sdk/typescript/integrations">
    Provider-specific setup and version compatibility
  </Card>

  <Card title="Configuration" icon="sliders" href="/flintai/platform/sdk/typescript/configuration">
    Environment variables, credentials, and gateway setup
  </Card>
</CardGroup>