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
| Guardrail | What it checks | On a finding |
|---|---|---|
shieldInputGuardrail() | The run's input, for injection | run() rejects with InputGuardrailTripwireTriggered |
shieldOutputGuardrail() | The final output, for prompt leaks, credentials, exfiltration links, and canaries | run() rejects with OutputGuardrailTripwireTriggered |
shieldToolOutputGuardrail() | What the tool returned, for injection, before the model reads it | The 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 text | The tool doesn't run, and the model gets a rejection message |
shieldToolPolicyGuardrail() | The call, before the tool runs, against a tool policy | The 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:
| Guardrails | Shared options |
|---|---|
| Input, tool output | detect, scanToolResults, onDetection, onInjectionDetected |
| Output, tool input | systemPrompt, sanitize, output, onLeakDetected, onOutputFindings |
| Tool policy | None |
| Option | Guardrails | Type | Default | Description |
|---|---|---|---|---|
name | all | string | "shield_input", "shield_output", "shield_tool_input", "shield_tool_output", "shield_tool_policy" | The name the SDK shows in errors, results, and traces |
runInParallel | input | boolean | false | true runs the guardrail alongside the first model call. That reduces latency, but a blocked input can reach the model or a tool. |
canary | output, tool input | string | none | A canary token you planted in the instructions. It must be a string: these guardrails can't plant one. |
throwOnLeak | output, tool input | boolean | true | Trip on a prompt leak or a canary. The shared option defaults to false. |
blockOnOutputFindings | output, tool input | boolean | true | Trip on a high or critical output finding. The shared option defaults to false. |
behavior | tool input, tool output, tool policy | "rejectContent" | "throwException" | "rejectContent" | Give the model rejectionMessage in place of the output, or fail the run |
rejectionMessage | tool input, tool output, tool policy | string | see Default rejection messages | What the model gets in place of the tool's output |
policy | tool policy (required), tool output | ToolPolicy | (context) => ToolPolicy | none | The 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 andrun()rejects withToolCallError. - 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 whatserver.listTools()returns. - With
previousResponseIdorconversationId, 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.