A guardrail that silently blocks a tool call is only half the job — the agent, and the person watching it, need to know why, in a form specific enough to act on. This guide sketches a guardrail-hook pattern for agents built on the OpenAI Agents SDK: a check that resolves a URL's page type before a tool executes, and a deny response shaped so the agent's own reasoning (and your logs) get a real reason, not a dead end. Code throughout is an illustrative sketch of the pattern, not a copy of the SDK's internals — confirm exact hook names, decorators, and exception types against your installed version before shipping any of it.
Agent frameworks generally expose guardrails at a few conceptual points: before the agent starts working on an input, after it produces a final output, and around an individual tool call. A URL policy check belongs at the tool-call point, because that is the only one of the three that sees the actual destination before a network request happens.
This distinction matters in practice because it's tempting to reuse whatever guardrail infrastructure your team built first. A team that already has an input guardrail checking for prompt injection may be tempted to extend it to "also check URLs" — but an input guardrail runs once, on the original task, before the agent has issued a single tool call, and has no visibility into a URL the agent discovers three steps into its own research. The tool-call guardrail is not a stylistic preference; it is the only hook that structurally has the information a URL check needs at the moment it needs it.
Useful for catching an obviously malicious task description before the agent starts, but a URL rarely appears in the original request at all — the agent usually discovers it mid-task by searching or following a link. Not the right place for URL policy.
Useful for catching leaked secrets or policy-violating content in the response the user sees, but by the time output guardrails run, any tool call the agent already made has already happened. Too late for a URL that should never have been fetched.
The right place: a hook that runs with the tool's actual arguments (the URL) available, before the tool's underlying function executes, with the ability to short-circuit the call and return a result of its own instead.
This is the same conclusion the framework-agnostic and LangChain-specific guides on this site reach from different starting points: whatever the framework calls its hook, the check has to sit directly on the path between "the agent decided to fetch this URL" and "the URL was actually fetched."
Whatever tool your agent uses to fetch pages or submit forms, find the specific argument (usually named url or similar) that a guardrail hook needs to inspect. Guardrails that only see the tool name, not its arguments, cannot do this check.
Resolve the URL's page type (full schema on the page-types database page) using the same framework-agnostic check function described in our implementation guide. This should be the very first thing the guardrail does, before any other validation.
Rather than letting the tool's underlying function execute, return (or raise, depending on your SDK version's guardrail-tripwire convention) a structured result carrying the page type and the reason, not a bare boolean.
"Blocked" tells the agent nothing useful. "Denied: this is a login page (credential surface); do not retry, report the restriction" gives the model's next reasoning step something concrete to act on — the difference between an agent that loops and one that adapts.
Record the URL, resolved page type, and result regardless of whether the guardrail's message to the agent is followed, retried, or ignored — the log is your audit trail; the agent's behavior afterward is a separate concern.
This sketch shows the shape of a guardrail conceptually similar to the tool-call guardrail hooks documented for the OpenAI Agents SDK. It uses generic names deliberately — confirm the exact decorator, exception class, and hook registration API against your installed SDK version before adapting this.
Whatever your SDK version's actual guardrail return convention is — raising an exception, returning a tripwire object, or setting a flag the runtime checks — the logic inside the function is the part that matters: resolve the page type, decide, and attach a specific reason to a denial rather than a bare failure.
A guardrail sits directly in the critical path of every tool call, so its own performance characteristics become the agent's performance characteristics. Two practical consequences follow from that.
First, cache lookup results the same way the framework-agnostic implementation guide recommends — an agent that revisits the same domain repeatedly within a session (a status page it checks every few minutes, a documentation site it references across several tool calls) should not re-run a full lookup each time. Second, decide up front what the guardrail does if it hits a rate limit on the underlying API: the safe default, consistent with default-deny, is to treat a rate-limited response the same as any other lookup failure and deny, while alerting whoever operates the agent that the limit was hit, rather than silently falling back to an unchecked fetch. Neither of these is specific to the OpenAI Agents SDK; both apply equally to the framework-agnostic check function and the LangChain tool-wrapper pattern described elsewhere on this site, because a guardrail that adds noticeable latency to every tool call tends to get quietly disabled under production pressure, which is a worse outcome than a slightly stale cache.
The single biggest difference between a guardrail that helps an agent recover gracefully and one that produces confusing, looping behavior is whether the denial carries a specific, structured reason. It is easy to underweight this while building the guardrail itself, because from the guardrail's own point of view "deny" is the entire job — the UX cost only shows up later, in the agent's next turn and in whoever reads the transcript afterward.
| Guardrail point | Sees the URL before the fetch? | Can shape a specific deny reason? | Use for |
|---|---|---|---|
| Input guardrail (on the user's task) | Rarely — URL usually not in the original request | N/A | Blocking obviously malicious task descriptions |
| Output guardrail (on the final answer) | No — runs after tool calls complete | Yes, for the final answer only | Catching leaked content in the response |
| Tool-call guardrail | Yes | Yes, per call | URL page-type policy (this guide) |
| Egress proxy, outside the SDK | Yes, at the network layer | Depends on proxy design | Backstop for any tool not covered by an in-process guardrail |
Run through this against your actual code, not from memory of how you intended to build it — several of these are the kind of gap that only shows up when you deliberately try to break your own implementation.
Consider an agent built to answer customer questions by reading a vendor's public support documentation and status page — a common pattern for a support-automation assistant that needs current information it wasn't trained on. Its task: "find out whether Acme Corp's API had an outage yesterday and summarize their current uptime status."
A reasonable plan: fetch Acme Corp's status page, and if that page links to an incident history, follow it. Both of those resolve to the status page type, which a support agent's policy allows, so the guardrail passes both calls through and the agent gets the content it needs. Now suppose the status page also links to "sign in to get personalized incident alerts" — a plausible link for the agent to consider following if its task description is read broadly. That fetch resolves to login, the guardrail's tripwire fires, and the tool call returns the structured reason instead of a login page: page_type='login' is not permitted (policy_deny_page_type). Do not retry this URL. The agent's next reasoning step has something to work with — it can note in its summary that personalized alerts require signing in, without ever having attempted to sign in itself. Nothing about this required anticipating the sign-in link in the task description; the guardrail caught it because the page type, not the agent's plan, was what got evaluated.
Agent designs that split work across multiple specialized agents — a triage agent handing a task to a research agent, which hands a sub-task to a browsing agent — raise one specific question for a URL guardrail: does the guardrail travel with the handoff, or does it need to be registered separately on each agent in the chain?
The safe assumption, until you have verified otherwise for your specific SDK version and agent topology, is the second one: a guardrail registered on one agent's tools does not automatically protect a different agent further down a handoff chain unless you have explicitly confirmed your runtime propagates it. Treat every agent in a multi-agent design as needing its own guardrail registration reviewed individually, the same way the checklist below asks you to confirm coverage tool by tool rather than assuming it. A single unguarded agent anywhere in a handoff chain reintroduces the exact gap the rest of the design closed.
Several high-profile 2026 incidents — escaped agents breaching Hugging Face via dataset uploads, hijacking the DseWiki wiki through write endpoints, building a covert channel inside JFrog Artifactory, and taking over four third-party accounts through a rogue app — all involved a tool call reaching a page type a guardrail like the one above would have denied. Our analysis of the public disclosures shows the database and egress rules would have denied nearly every entry point pre-request.
Every 2026 agent escape, mapped to the rule that stops it Read the sandbox-escape caseThe honest fine print — the same two assumptions we publish, plus two operational ones
The reference check function this guardrail builds on.
The equivalent pattern for LangChain-built agents.
The four-layer enforcement model behind every lookup.
The companion product for blocking human access to AI tools.
Download the sample, adapt the sketch above to your SDK version, and confirm the deny message actually names a reason before this reaches production.
