recusal-openai-agents
The Recusal gate for the OpenAI Agents SDK: every function tool call an agent proposes is judged by your policy before the tool runs, and a refused call never runs.
This is a separate distribution from recusal. The kernel has zero runtime dependencies
and a frozen compatibility perimeter; this package carries the SDK dependency and its own
version, so an SDK release never forces a release of the kernel.
Status: not yet published to PyPI. Until it is, install it from the repository:
pip install "recusal-openai-agents @ git+https://github.com/philpaz/recusal#subdirectory=adapters/openai-agents"
Requires Python 3.10+ (the SDK's minimum), recusal>=0.14.0 and openai-agents>=0.24.0.
It is tested on every pull request against exactly openai-agents==0.24.0 with
openai==3.34.0, and weekly against the newest releases.
Use
from agents import Agent, function_tool
from recusal import Finding
from recusal_openai_agents import gated_agent
@function_tool
def run_sql(sql: str) -> str: ...
def policy(tool_name, tool_input):
sql = tool_input.get("sql", "")
if tool_name == "run_sql" and sql.lstrip().upper().startswith("DELETE"):
return [Finding.fail("no_deletes", severity="CRITICAL", message="DELETE is not allowed")]
return []
agent = gated_agent(Agent(name="assistant", tools=[run_sql]), policy)
gated_agent returns a copy of the agent with a Recusal tool input guardrail on every
function tool. A refused call's output is Recusal's reason, which the model reads on its
next turn. The tool does not run. A policy that raises refuses the call (fail closed).
Runner.run, Runner.run_streamed and a human approval (needs_approval) all pass
through the guardrail, which runs when the tool is about to execute, after any approval.
The gate judges the arguments as the SDK prepares them from the tool's schema, defaults included, and refuses a tool whose schema transforms its input after validation, since what would execute could not be judged.
Build the agent completely, then gate it. A tool appended to the gated agent's list
afterwards is not gated. gate_tools(tools, policy) gates a list of tools directly.
Put every decision on the record
from recusal.audit import AuditLog
from recusal_openai_agents import audited_agent
log = AuditLog(path="decisions.jsonl")
agent = audited_agent(Agent(name="assistant", tools=[run_sql]), policy, log)
audited_tools(tools, policy, log) is the list form. Each call a guardrail sees, allowed
or refused, is one hash-chained entry labeled openai_agents.tool_input_guardrail with
the SDK's tool call id and a SHA-256 fingerprint of the arguments (never the arguments).
If the log cannot be written the call is refused. Check the log with
recusal audit verify decisions.jsonl.
The audited forms are the plain ones with a recording passed in, so there is one decision path.
What the gate refuses, and what it does not see
gated_agent raises at construction for an agent that can run something the guardrail
never sees. The rule is default-deny:
- Any tool that is not a
FunctionTool: hosted tools that run on OpenAI's servers (web search, file search, code interpreter, image generation, hosted MCP, tool search) and local ones the SDK executes itself (shell, apply patch, computer, custom). A tool type added in a later SDK release is refused too. - MCP servers attached with
mcp_servers=, and handoffs to other agents. - A sub-agent behind
agent.as_tool(...)whose own tools are not gated. Gate the sub-agent first,gated_agent(sub, policy).as_tool(...), and the parent accepts it. Agentsubclasses such asSandboxAgent, which add tools of their own at run time.
Not on the audit log: a call the SDK rejects before the guardrail runs. A tool the agent
does not have raises ModelBehaviorError in the SDK, and nothing runs.
Compatibility
This package is outside the kernel's frozen perimeter (STABILITY.md, Integrations). Its
public names are the ones in recusal_openai_agents.__all__. When an SDK release changes
what the guardrail is handed, this package gets a release and the kernel does not.
A runnable offline demonstration, with the SDK's scripted model and no API key, is
examples/openai_agents_gate.py
and
examples/openai_agents_audit.py.
Metadata
Release files for recusal-openai-agents 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| recusal_openai_agents-0.1.0.tar.gz | 15.9 kB | With provenance | Details for recusal_openai_agents-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| recusal_openai_agents-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for recusal_openai_agents-0.1.0-py3-none-any.whl |
Total release size: 31.6 kB
Release files / recusal_openai_agents-0.1.0.tar.gz
| Download URL | recusal_openai_agents-0.1.0.tar.gz |
|---|---|
| Size | 15.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f3d2efbc6666bafb6ef29cf25f84dce5f88663d37199b473470cb148f120a68d
|
|
BLAKE2b-256 checksum How to use checksums |
53920407fae9cbd79f46238de2367bc953e3d3d44a57325b149d6cd04a1ef8a4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logRelease files / recusal_openai_agents-0.1.0-py3-none-any.whl
| Download URL | recusal_openai_agents-0.1.0-py3-none-any.whl |
|---|---|
| Size | 15.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b9cb390b7a4850e86176442df2908015352f2f86088deb9375d2fb73ee2b9d76
|
|
BLAKE2b-256 checksum How to use checksums |
ffeecd86dd127d3bc75286f856b445f7f7a438a62ce036fcab4911382af1965c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logSecurity for recusal-openai-agents 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for recusal_openai_agents-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.