Skip to Content
ZeroLeaksDocs
Shield SDKProvider wrappers

OpenAI Agents SDK

Check a run's input, final output, tool calls, and tool results with Shield guardrails for the OpenAI Agents SDK.

@zeroleaks/shield/openai-agents provides five guardrails for the OpenAI Agents SDK (@openai/agents). Register them in the SDK's guardrail slots on an agent, a Runner, a function tool, or an MCP server.

Guardrails can stop a run or a tool call, but they can't change text. Nothing is redacted and instructions are not hardened. Content with a finding either trips the guardrail or passes through unchanged.

Usage

import {
  Agent,
  InputGuardrailTripwireTriggered,
  OutputGuardrailTripwireTriggered,
  run,
  tool,
} from "@openai/agents";
import { z } from "zod";
import {
  shieldInputGuardrail,
  shieldOutputGuardrail,
  shieldToolInputGuardrail,
  shieldToolOutputGuardrail,
} from "@zeroleaks/shield/openai-agents";

const readInbox = tool({
  name: "read_inbox",
  description: "Read new email.",
  parameters: z.object({}),
  execute: async () => fetchInbox(),
  outputGuardrails: [shieldToolOutputGuardrail()],
});

const sendEmail = tool({
  name: "send_email",
  description: "Send an email.",
  parameters: z.object({ to: z.string(), body: z.string() }),
  execute: async ({ to, body }) => send(to, body),
  inputGuardrails: [shieldToolInputGuardrail()],
});

const agent = new Agent({
  name: "Support",
  instructions: "You are a support agent for Acme. Never share internal ticket notes.",
  tools: [readInbox, sendEmail],
  inputGuardrails: [shieldInputGuardrail()],
  outputGuardrails: [shieldOutputGuardrail()],
});

try {
  const result = await run(agent, userInput);
  return result.finalOutput;
} catch (error) {
  if (
    error instanceof InputGuardrailTripwireTriggered ||
    error instanceof OutputGuardrailTripwireTriggered
  ) {
    console.warn(error.result.guardrail.name, error.result.output.outputInfo);
    return "Sorry, I can't help with that.";
  }
  throw error;
}

To guard every tool exposed by an MCP server, pass the tool guardrails to the server (Agents SDK 0.17.1 or later):

import { MCPServerStreamableHttp } from "@openai/agents";

const server = new MCPServerStreamableHttp({
  url: serverUrl,
  toolInputGuardrails: [shieldToolInputGuardrail()],
  toolOutputGuardrails: [shieldToolOutputGuardrail()],
});

To guard every agent a Runner runs, pass the input and output guardrails to it instead: new Runner({ inputGuardrails: [shieldInputGuardrail()], outputGuardrails: [shieldOutputGuardrail()] }).

What Shield checks

GuardrailWhat it checksOn a finding
shieldInputGuardrail()The run's input, for injectionrun() rejects with InputGuardrailTripwireTriggered
shieldOutputGuardrail()The final output, for prompt leaks, credentials, exfiltration links, and canariesrun() rejects with OutputGuardrailTripwireTriggered
shieldToolOutputGuardrail()What the tool returned, for injection, before the model reads itThe model gets a rejection message instead of the output, and the run continues
shieldToolInputGuardrail()The call's arguments, before the tool runs, for credentials, exfiltration links, canaries, and system prompt textThe tool doesn't run, and the model gets a rejection message
shieldToolPolicyGuardrail()The call, before the tool runs, against a tool policyThe tool doesn't run, and the model gets the policy's reason

The output and tool input guardrails check for a leak of systemPrompt if you pass it, else of the agent's instructions when they are a string. With instructions given as a function, or a stored prompt, pass systemPrompt, or the prompt leak check is skipped.

outputInfo never contains the text. The SDK includes it in the error message, so the message is safe to log. The error's result.agentOutput contains the SDK's unredacted copy of the output that tripped the guardrail. Do not log that field.

Tool policy guardrail

shieldToolPolicyGuardrail({ policy }) runs policy.checkAsync() on each call before the tool runs. A policy from createToolPolicy() remembers what a session has read, so give each run its own. Pass a function of the context you pass to run(), and give the same function to shieldToolOutputGuardrail({ policy }), which records each output:

import { createToolPolicy, type ToolPolicy } from "@zeroleaks/shield";
import {
  shieldToolOutputGuardrail,
  shieldToolPolicyGuardrail,
} from "@zeroleaks/shield/openai-agents";

type Session = { policy: ToolPolicy };
const policyGuardrail = shieldToolPolicyGuardrail<Session>({ policy: (context) => context.policy });
const outputGuardrail = shieldToolOutputGuardrail<Session>({ policy: (context) => context.policy });

const sendEmail = tool({
  name: "send_email",
  description: "Send an email.",
  parameters: z.object({ to: z.string(), body: z.string() }),
  execute: async ({ to, body }) => send(to, body),
  inputGuardrails: [policyGuardrail],
  outputGuardrails: [outputGuardrail],
});

await run(agent, userInput, {
  context: { policy: createToolPolicy({ rules: { send_email: { labels: ["sink"] } } }) },
});

Place this guardrail last in inputGuardrails, after shieldToolInputGuardrail(), so calls rejected by another guardrail are not counted. To use one policy throughout a conversation, store it in the context object passed to every run().

Options

Each guardrail takes part of the shared options, plus the options in the second table:

GuardrailsShared options
Input, tool outputdetect, scanToolResults, onDetection, onInjectionDetected
Output, tool inputsystemPrompt, sanitize, output, onLeakDetected, onOutputFindings
Tool policyNone
OptionGuardrailsTypeDefaultDescription
nameallstring"shield_input", "shield_output", "shield_tool_input", "shield_tool_output", "shield_tool_policy"The name the SDK shows in errors, results, and traces
runInParallelinputbooleanfalsetrue runs the guardrail alongside the first model call. That reduces latency, but a blocked input can reach the model or a tool.
canaryoutput, tool inputstringnoneA canary token you planted in the instructions. It must be a string: these guardrails can't plant one.
throwOnLeakoutput, tool inputbooleantrueTrip on a prompt leak or a canary. The shared option defaults to false.
blockOnOutputFindingsoutput, tool inputbooleantrueTrip on a high or critical output finding. The shared option defaults to false.
behaviortool input, tool output, tool policy"rejectContent" | "throwException""rejectContent"Give the model rejectionMessage in place of the output, or fail the run
rejectionMessagetool input, tool output, tool policystringsee Default rejection messagesWhat the model gets in place of the tool's output
policytool policy (required), tool outputToolPolicy | (context) => ToolPolicynoneThe tool policy, or a function that returns it from the context passed to run()

Streaming

With stream: true, run() resolves with the stream. An input guardrail's error comes from result.completed and the stream. The output guardrail's error is thrown from your for await loop and result.completed after the last chunk.

Limitations

  • Output is never redacted, and instructions are not hardened.
  • With stream: true, the output guardrail runs after the text was streamed and can't take it back.
  • The tool has already run when the tool output guardrail checks its output.
  • Input guardrails run once per run, on the input to the first agent, not on later turns or after a handoff.
  • Output guardrails run only for the agent that produced the final output, plus those of the Runner.
  • For a tool with an outputSchema, a rejection message fails the SDK's schema check and run() rejects with ToolCallError.
  • Hosted tools (web search, file search, code interpreter, hosted MCP) run on OpenAI's side and take no tool guardrails.
  • The tools an MCP server lists are not checked for tool poisoning. Run scanTools() on what server.listTools() returns.
  • With previousResponseId or conversationId, the input guardrail only sees the new input.
  • System and assistant messages, images, files, audio, screenshots, and reasoning are not read.
  • The arguments of calls to tools without shieldToolInputGuardrail() are not checked.
  • Only high and critical findings trip the tool input guardrail. A bare URL that carries data is most often medium.
  • With parallel tool calls, the policy can refuse a sink call the model chose before it saw a result from the same turn.
  • Realtime agents (@openai/agents/realtime) are not covered. They have guardrails of their own.

See Limitations for what no integration scans.

On this page