Protecting Agents with Input Guardrails

Introduction & Context

In the previous lessons, you learned how to securely handle sensitive data using context objects and how to monitor agent workflows with event handlers. Now, you're ready to tackle the next critical layer of agent security: input guardrails . While context management protects your internal data and event handlers give you visibility into agent behavior, input guardrails protect your agents from potentially harmful, inappropriate, or malicious user inputs before they even begin processing. Imagine real-world scenarios where your agents might face problematic inputs: a travel assistant could receive requests for illegal activities, a customer service bot might be asked to perform tasks outside its scope, or a content creation agent could be prompted to generate inappropriate material. Without proper input validation, your agents could waste resources, violate company policies, or even expose security vulnerabilities. The most common and critical use of guardrails is at the input stage — validating user requests before your agent begins processing. Input guardrails serve as your first line of defense, ensuring that only safe, appropriate, and policy-compliant inputs are allowed to reach your agents.

Guardrails vs. Event Handlers

As you build more capable and autonomous OpenAI agents, security becomes a multi-layered challenge. Guardrails are a foundational security mechanism designed to protect your agents from a wide range of problematic scenarios — whether that’s malicious user input, requests that violate business policies, or attempts to push your agent outside its intended scope. It's important to distinguish between event handlers and guardrails : Event Handlers are general-purpose lifecycle callbacks that give you visibility and control over agent execution. They're designed for monitoring, logging, dynamic context injection, and observability across your entire workflow. Event handlers can run at various points during agent execution and are primarily focused on understanding and controlling what happens during the agent’s processing. Guardrails are specialized validation functions dedicated to keeping agents safe. They evaluate inputs (or outputs) to ensure requests comply with your rules before the agent starts working or before a response is returned to the user. Both are essential, but they serve different purposes. Event handlers enhance visibility and coordination, while guardrails directly protect against unsafe or policy-violating behavior.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

JavaScript

const myGuardrail = {
  name: 'My Guardrail',
  async execute({ input, context }) {
    // Perform input validation (e.g., check for prohibited keywords, malformed input, or policy violations)
    const validationFailed = /* your validation logic here */ false;

    if (validationFailed) {
      return {
        outputInfo: 'Input failed validation: details about the specific policy violation.',
        tripwireTriggered: true
      };
    }

    return {
      outputInfo: 'Input passed all validation checks.',
      tripwireTriggered: false
    };
  }
};

const myGuardrail = {
  name: 'My Guardrail',
  async execute({ input, context }) {
    // Perform input validation (e.g., check for prohibited keywords, malformed input, or policy violations)
    const validationFailed = /* your validation logic here */ false;

    if (validationFailed) {
      return {
        outputInfo: 'Input failed validation: details about the specific policy violation.',
        tripwireTriggered: true
      };
    }

    return {
      outputInfo: 'Input passed all validation checks.',
      tripwireTriggered: false
    };
  }
};

JavaScript

const simpleContentFilter = {
  name: 'Simple Content Filter',
  async execute({ input }) {
    // List of prohibited terms for requests
    const prohibitedTerms = ['gambling', 'nightclub', 'alcohol'];

    // Convert input to lowercase string
    const inputText = String(input).toLowerCase();

    // Check for prohibited terms
    for (const term of prohibitedTerms) {
      if (inputText.includes(term)) {
        return {
          outputInfo: `Blocked: inappropriate travel request containing '${term}'`,
          tripwireTriggered: true
        };
      }
    }

    return {
      outputInfo: 'Travel request approved',
      tripwireTriggered: false
    };
  }
};

const simpleContentFilter = {
  name: 'Simple Content Filter',
  async execute({ input }) {
    // List of prohibited terms for requests
    const prohibitedTerms = ['gambling', 'nightclub', 'alcohol'];

    // Convert input to lowercase string
    const inputText = String(input).toLowerCase();

    // Check for prohibited terms
    for (const term of prohibitedTerms) {
      if (inputText.includes(term)) {
        return {
          outputInfo: `Blocked: inappropriate travel request containing '${term}'`,
          tripwireTriggered: true
        };
      }
    }

    return {
      outputInfo: 'Travel request approved',
      tripwireTriggered: false
    };
  }
};

JavaScript

import { Agent } from '@openai/agents';

const travelGenie = new Agent({
  name: 'Travel Genie',
  instructions: 'You are a helpful travel assistant.',
  inputGuardrails: [simpleContentFilter],
  model: 'gpt-4.1'
});

import { Agent } from '@openai/agents';

const travelGenie = new Agent({
  name: 'Travel Genie',
  instructions: 'You are a helpful travel assistant.',
  inputGuardrails: [simpleContentFilter],
  model: 'gpt-4.1'
});

JavaScript

import { run, InputGuardrailTripwireTriggered } from '@openai/agents';

try {
  const result = await run(
    travelGenie,
    'Where can I gamble in Europe?'
  );
  console.log(result.finalOutput);
} catch (err) {
  if (err instanceof InputGuardrailTripwireTriggered) {
    console.log('Content guardrail tripped: Request blocked');
  } else {
    throw err;
  }
}

import { run, InputGuardrailTripwireTriggered } from '@openai/agents';

try {
  const result = await run(
    travelGenie,
    'Where can I gamble in Europe?'
  );
  console.log(result.finalOutput);
} catch (err) {
  if (err instanceof InputGuardrailTripwireTriggered) {
    console.log('Content guardrail tripped: Request blocked');
  } else {
    throw err;
  }
}

text

Content guardrail tripped: Request blocked

Content guardrail tripped: Request blocked

JavaScript

import { z } from 'zod';

const ContentCheckOutput = z.object({
  containsProhibitedContent: z.boolean(),
  reasoning: z.string()
});

import { z } from 'zod';

const ContentCheckOutput = z.object({
  containsProhibitedContent: z.boolean(),
  reasoning: z.string()
});

JavaScript

import { Agent } from '@openai/agents';

const guardrailAgent = new Agent({
  name: 'Content Guardrail',
  instructions:
    'Analyze the user\'s input to determine if it requests information ' +
    'about gambling venues, nightclubs, alcohol-related activities, or similar topics.',
  outputType: ContentCheckOutput,
  model: 'gpt-4.1'
});

import { Agent } from '@openai/agents';

const guardrailAgent = new Agent({
  name: 'Content Guardrail',
  instructions:
    'Analyze the user\'s input to determine if it requests information ' +
    'about gambling venues, nightclubs, alcohol-related activities, or similar topics.',
  outputType: ContentCheckOutput,
  model: 'gpt-4.1'
});

JavaScript

import { run } from '@openai/agents';

const contentGuardrail = {
  name: 'Content Guardrail',
  async execute({ input, context }) {
    // Run the guardrail agent to analyze the input
    const result = await run(guardrailAgent, input, { context: context.context });

    // Print the guardrail agent's response for visibility
    console.log('Guardrail Agent response:\n' + JSON.stringify(result.finalOutput) + '\n');

    // Return the validation decision
    return {
      outputInfo: result.finalOutput?.reasoning,
      tripwireTriggered: result.finalOutput?.containsProhibitedContent ?? false
    };
  }
};

import { run } from '@openai/agents';

const contentGuardrail = {
  name: 'Content Guardrail',
  async execute({ input, context }) {
    // Run the guardrail agent to analyze the input
    const result = await run(guardrailAgent, input, { context: context.context });

    // Print the guardrail agent's response for visibility
    console.log('Guardrail Agent response:\n' + JSON.stringify(result.finalOutput) + '\n');

    // Return the validation decision
    return {
      outputInfo: result.finalOutput?.reasoning,
      tripwireTriggered: result.finalOutput?.containsProhibitedContent ?? false
    };
  }
};

JavaScript

const travelGenie = new Agent({
  name: 'Travel Genie',
  instructions:
    'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +
    'Recommend exciting destinations and offer helpful travel tips.',
  inputGuardrails: [contentGuardrail],
  model: 'gpt-4.1'
});

const travelGenie = new Agent({
  name: 'Travel Genie',
  instructions:
    'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +
    'Recommend exciting destinations and offer helpful travel tips.',
  inputGuardrails: [contentGuardrail],
  model: 'gpt-4.1'
});

JavaScript

import { run, InputGuardrailTripwireTriggered } from '@openai/agents';

try {
  const result = await run(
    travelGenie,
    'Can you recommend the best nightclubs in Europe?'
  );
  console.log('Travel Genie response:\n' + result.finalOutput + '\n');
} catch (err) {
  if (err instanceof InputGuardrailTripwireTriggered) {
    console.log('!!! Content guardrail tripped: Request blocked.\n');
  } else {
    throw err;
  }
}

import { run, InputGuardrailTripwireTriggered } from '@openai/agents';

try {
  const result = await run(
    travelGenie,
    'Can you recommend the best nightclubs in Europe?'
  );
  console.log('Travel Genie response:\n' + result.finalOutput + '\n');
} catch (err) {
  if (err instanceof InputGuardrailTripwireTriggered) {
    console.log('!!! Content guardrail tripped: Request blocked.\n');
  } else {
    throw err;
  }
}

text

Guardrail Agent response:
{"containsProhibitedContent":true,"reasoning":"The user is asking about nightclubs, which are areas known for adult content. This type of request should be blocked as it relates to prohibited content."}

!!! Content guardrail tripped: Request blocked.

Guardrail Agent response:
{"containsProhibitedContent":true,"reasoning":"The user is asking about nightclubs, which are areas known for adult content. This type of request should be blocked as it relates to prohibited content."}

!!! Content guardrail tripped: Request blocked.

JavaScript

const travelGenie = new Agent({
  name: 'Travel Genie',
  instructions:
    'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +
    'Recommend exciting destinations and offer helpful travel tips.',
  inputGuardrails: [simpleContentFilter, contentGuardrail],
  model: 'gpt-4.1'
});

const travelGenie = new Agent({
  name: 'Travel Genie',
  instructions:
    'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +
    'Recommend exciting destinations and offer helpful travel tips.',
  inputGuardrails: [simpleContentFilter, contentGuardrail],
  model: 'gpt-4.1'
});

JavaScript

const myGuardrail = {
  name: 'My Guardrail',
  async execute({ input, context }) {
    // Perform input validation (e.g., check for prohibited keywords, malformed input, or policy violations)
    const validationFailed = /* your validation logic here */ false;

    if (validationFailed) {
      return {
        outputInfo: 'Input failed validation: details about the specific policy violation.',
        tripwireTriggered: true
      };
    }

    return {
      outputInfo: 'Input passed all validation checks.',
      tripwireTriggered: false
    };
  }
};

JavaScript

const simpleContentFilter = {
  name: 'Simple Content Filter',
  async execute({ input }) {
    // List of prohibited terms for requests
    const prohibitedTerms = ['gambling', 'nightclub', 'alcohol'];

    // Convert input to lowercase string
    const inputText = String(input).toLowerCase();

    // Check for prohibited terms
    for (const term of prohibitedTerms) {
      if (inputText.includes(term)) {
        return {
          outputInfo: `Blocked: inappropriate travel request containing '${term}'`,
          tripwireTriggered: true
        };
      }
    }

    return {
      outputInfo: 'Travel request approved',
      tripwireTriggered: false
    };
  }
};

JavaScript

import { Agent } from '@openai/agents';

const travelGenie = new Agent({
  name: 'Travel Genie',
  instructions: 'You are a helpful travel assistant.',
  inputGuardrails: [simpleContentFilter],
  model: 'gpt-4.1'
});

JavaScript

import { run, InputGuardrailTripwireTriggered } from '@openai/agents';

try {
  const result = await run(
    travelGenie,
    'Where can I gamble in Europe?'
  );
  console.log(result.finalOutput);
} catch (err) {
  if (err instanceof InputGuardrailTripwireTriggered) {
    console.log('Content guardrail tripped: Request blocked');
  } else {
    throw err;
  }
}

text

Content guardrail tripped: Request blocked

JavaScript

import { z } from 'zod';

const ContentCheckOutput = z.object({
  containsProhibitedContent: z.boolean(),
  reasoning: z.string()
});

JavaScript

import { Agent } from '@openai/agents';

const guardrailAgent = new Agent({
  name: 'Content Guardrail',
  instructions:
    'Analyze the user\'s input to determine if it requests information ' +
    'about gambling venues, nightclubs, alcohol-related activities, or similar topics.',
  outputType: ContentCheckOutput,
  model: 'gpt-4.1'
});

JavaScript

import { run } from '@openai/agents';

const contentGuardrail = {
  name: 'Content Guardrail',
  async execute({ input, context }) {
    // Run the guardrail agent to analyze the input
    const result = await run(guardrailAgent, input, { context: context.context });

    // Print the guardrail agent's response for visibility
    console.log('Guardrail Agent response:\n' + JSON.stringify(result.finalOutput) + '\n');

    // Return the validation decision
    return {
      outputInfo: result.finalOutput?.reasoning,
      tripwireTriggered: result.finalOutput?.containsProhibitedContent ?? false
    };
  }
};

JavaScript

const travelGenie = new Agent({
  name: 'Travel Genie',
  instructions:
    'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +
    'Recommend exciting destinations and offer helpful travel tips.',
  inputGuardrails: [contentGuardrail],
  model: 'gpt-4.1'
});

JavaScript

import { run, InputGuardrailTripwireTriggered } from '@openai/agents';

try {
  const result = await run(
    travelGenie,
    'Can you recommend the best nightclubs in Europe?'
  );
  console.log('Travel Genie response:\n' + result.finalOutput + '\n');
} catch (err) {
  if (err instanceof InputGuardrailTripwireTriggered) {
    console.log('!!! Content guardrail tripped: Request blocked.\n');
  } else {
    throw err;
  }
}

text

Guardrail Agent response:
{"containsProhibitedContent":true,"reasoning":"The user is asking about nightclubs, which are areas known for adult content. This type of request should be blocked as it relates to prohibited content."}

!!! Content guardrail tripped: Request blocked.

JavaScript

const travelGenie = new Agent({
  name: 'Travel Genie',
  instructions:
    'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +
    'Recommend exciting destinations and offer helpful travel tips.',
  inputGuardrails: [simpleContentFilter, contentGuardrail],
  model: 'gpt-4.1'
});

Introduction & Context

Guardrails vs. Event Handlers

Join the 1M+ learners on CodeSignal

How Input Guardrails Work

Simple Rule-Based Input Validation

Attaching Guardrails to Agents

Testing Guardrail Behavior with Blocked Inputs

Understanding Concurrent Execution with Guardrails

Creating LLM-Based Content Validation

Implementing LLM-Based Guardrail Functions

Testing LLM-Based Validation

Combining Multiple Guardrails

Summary & Preparing for Practice