Skip to content

Quickstart: TypeScript

Get started with Guardrails TypeScript in minutes. Guardrails provides drop-in replacements for OpenAI clients that automatically validate inputs and outputs using configurable safety checks.

Install

npm install @openai/guardrails

Set API Key

export OPENAI_API_KEY=sk-...

Create Pipeline Configuration

The fastest way is using the Guardrails Wizard - a no-code tool for creating configurations.

Or define manually:

{
    "version": 1,
    "input": {
        "version": 1,
        "guardrails": [
            {"name": "URL Filter", "config": {}},
            {"name": "Moderation", "config": {"categories": ["hate", "violence"]}}
        ]
    },
    "output": {
        "version": 1,
        "guardrails": [
            {"name": "Contains PII", "config": {"entities": ["EMAIL_ADDRESS", "PHONE_NUMBER"]}}
        ]
    }
}

Pipeline Stages

Guardrails use a pipeline configuration with 1 to 3 stages:

  • Preflight - Runs before the LLM call (e.g., mask PII, moderation)
  • Input - Runs in parallel with the LLM call (e.g., jailbreak detection)
  • Output - Runs over the LLM generated content (e.g., fact checking, compliance)

Not all stages are required - you can use just input, just output, or any combination.

Use as Drop-in Replacement

Replace your OpenAI client with the Guardrails version (GuardrailsOpenAI):

We support chat.completions.create and responses.create.

import { GuardrailsOpenAI } from '@openai/guardrails';

async function main() {
    // Use GuardrailsOpenAI instead of OpenAI
    const client = await GuardrailsOpenAI.create('./guardrails_config.json');

    try {
        const response = await client.responses.create({
            model: "gpt-5",
            input: "Hello world"
        });

        // Access OpenAI response directly
        console.log(response.output_text);

    } catch (error) {
        if (error.constructor.name === 'GuardrailTripwireTriggered') {
            console.log(`Guardrail triggered: ${error.guardrailResult.info}`);
        }
    }
}

main();

That's it! Your existing OpenAI code now includes automatic guardrail validation based on your pipeline configuration. The response object works exactly like the original OpenAI response with additional guardrail_results property.

Multi-Turn Conversations

When maintaining conversation history across multiple turns, only append messages after guardrails pass. This prevents blocked input messages from polluting your conversation context.

import { GuardrailsOpenAI, GuardrailTripwireTriggered } from '@openai/guardrails';

const client = await GuardrailsOpenAI.create('./guardrails_config.json');
const messages: Array<{ role: 'user' | 'assistant'; content: string }> = [];

while (true) {
  const userInput = await readUserInput(); // replace with your input routine

  try {
    // ✅ Pass user input inline (don't mutate messages first)
    const response = await client.chat.completions.create({
      model: 'gpt-4o',
      messages: [...messages, { role: 'user', content: userInput }],
    });

    const responseContent = response.choices[0].message?.content ?? '';
    console.log(`Assistant: ${responseContent}`);

    // ✅ Only append AFTER guardrails pass
    messages.push({ role: 'user', content: userInput });
    messages.push({ role: 'assistant', content: responseContent });
  } catch (error) {
    if (error instanceof GuardrailTripwireTriggered) {
      // ❌ Guardrail blocked - message NOT added to history
      console.log('Message blocked by guardrails');
      continue;
    }
    throw error;
  }
}

Why this matters: If you append the user message before the guardrail check, blocked messages remain in your conversation history and get sent on every subsequent turn, even though they violated your safety policies.

Guardrail Execution Error Handling

Guardrails supports two error handling modes for guardrail execution failures:

Fail-Safe Mode (Default)

If a guardrail fails to execute (e.g., invalid model name), the system continues passing back tripwire_triggered=False:

// Default: raiseGuardrailErrors=false
const client = await GuardrailsOpenAI.create(config);
// Continues execution even if guardrails have any errors

Fail-Secure Mode

Enable strict mode to raise exceptions on guardrail execution failures:

// Strict mode: raiseGuardrailErrors=true
const client = await GuardrailsOpenAI.create(
    config,
    undefined,
    true  // raiseGuardrailErrors = true
);
// Raises exceptions if guardrails fail to execute properly

Note: This only affects guardrail execution errors. Safety violations (tripwires) are handled separately - see Tripwires for details.

Agents SDK Integration

For OpenAI Agents SDK users, we provide GuardrailAgent as a drop-in replacement:

import { GuardrailAgent } from '@openai/guardrails';
import { Runner } from '@openai/agents';

// Create agent with guardrails automatically configured
const agent = await GuardrailAgent.create(
    './guardrails_config.json',
    "Customer support agent",
    "You are a customer support agent. You help customers with their questions."
);

// Use exactly like a regular Agent
const result = await Runner.run(agent, "Hello, can you help me?");

GuardrailAgent automatically wires up your pipeline configuration to the agent's input and output guardrails, so you can focus on building your agent logic.

Azure OpenAI

Use the Azure-specific client:

import { GuardrailsAzureOpenAI } from '@openai/guardrails';

const client = await GuardrailsAzureOpenAI.create(
    './guardrails_config.json',
    {
        azure_endpoint: "https://your-resource.openai.azure.com/",
        api_key: "your-azure-key",
        api_version: "2025-01-01-preview"
    }
);

Third-Party Models

Works with any OpenAI-compatible API:

import { GuardrailsOpenAI } from '@openai/guardrails';

// Local Ollama model
const client = await GuardrailsOpenAI.create(
    './guardrails_config.json',
    {
        baseURL: "http://127.0.0.1:11434/v1/",
        apiKey: "ollama"
    }
);

Token Usage Tracking

LLM-based guardrails (Jailbreak, custom prompt checks, etc.) consume tokens. Keep track of those costs with the totalGuardrailTokenUsage helper:

import { GuardrailsOpenAI, totalGuardrailTokenUsage } from '@openai/guardrails';

const client = await GuardrailsOpenAI.create(CONFIG);
const response = await client.guardrails.responses.create({
  model: 'gpt-4.1-mini',
  input: 'Hello!',
});

const tokens = totalGuardrailTokenUsage(response);
console.log(`Guardrail tokens used: ${tokens.total_tokens}`);
// => Guardrail tokens used: 425

The helper returns:

{
  prompt_tokens: 300,       // Sum of prompt tokens across all LLM guardrails
  completion_tokens: 125,   // Sum of completion tokens
  total_tokens: 425,        // Total guardrail tokens
}

Works With GuardrailsOpenAI Clients

totalGuardrailTokenUsage works across all client types and endpoints:

  • OpenAI - sync and async clients
  • Azure OpenAI - sync and async clients
  • Third-party providers - any OpenAI-compatible API wrapper
  • Endpoints - both responses and chat.completions
  • Streaming - capture from the final chunk
// OpenAI client responses
const response = await client.guardrails.responses.create(...);
const tokens = totalGuardrailTokenUsage(response);

// Streaming – use the final chunk
let lastChunk: unknown;
for await (const chunk of stream) {
  lastChunk = chunk;
}
const streamingTokens = lastChunk ? totalGuardrailTokenUsage(lastChunk) : null;

Note: The JavaScript Agents SDK (@openai/agents) does not currently populate guardrail results in the RunResult object, so totalGuardrailTokenUsage() will return empty results for Agents SDK runs.

Per-Guardrail Usage

Each guardrail result includes its own token_usage entry:

const response = await client.guardrails.responses.create(...);
for (const gr of response.guardrail_results.allResults) {
  const usage = gr.info.token_usage;
  if (usage) {
    console.log(`${gr.info.guardrail_name}: ${usage.total_tokens} tokens`);
  }
}

Non-LLM guardrails (PII, Moderation, URL Filter, etc.) do not consume tokens, so token_usage will be omitted.

Next Steps