openai-agents-privacy-filter

PII redaction guardrails for the OpenAI Agents SDK. Automatically redact personally identifiable information from agent inputs and restore original values in outputs.

Features

• Input guardrail — Redact PII from user messages before the agent processes them
• Output guardrail — Restore original values from placeholders in agent responses
• Local processing — Uses the openai/privacy-filter HuggingFace model (no API calls)
• Configurable — Adjust confidence thresholds and filter by entity type

Installation

pip install openai-agents-privacy-filter

Requires:

• Python 3.11+
• openai-agents (for guardrail interface)

Quick Start

from privacy_filter_openai import PiiInputGuardrail, PiiOutputGuardrail
from agents import Agent, Runner

# Create guardrails
input_guardrail = PiiInputGuardrail(min_score=0.8)
output_guardrail = PiiOutputGuardrail()

# Create agent with PII guardrails
agent = Agent(
    name="PII-Safe Agent",
    instructions="You are a helpful assistant.",
    input_guardrails=[input_guardrail],
    output_guardrails=[output_guardrail],
)

# Run — PII is automatically redacted before LLM and restored after
result = await Runner.run(agent, "My email is alice@example.com")
print(result.final_output)  # "Your email is alice@example.com" (not [EMAIL_1])

How It Works

Input Guardrail

• Runs before the agent sees the user input
• Detects PII using the privacy-filter model
• Replaces PII with placeholders like [EMAIL_1], [PERSON_2]
• Stores mappings for later restoration

Output Guardrail

• Runs after the agent generates a response
• Restores original values from placeholders
• Returns the unredacted content to the user

Configuration

from privacy_filter_openai import PiiInputGuardrail, PiiOutputGuardrail

input_guardrail = PiiInputGuardrail(
    min_score=0.8,           # Minimum confidence threshold (0.0-1.0)
    entity_types=None,       # Filter to specific entities (None = all)
    cache_dir=None,          # Custom HuggingFace cache directory
)

output_guardrail = PiiOutputGuardrail()

Supported Entity Types

Complete Example

import asyncio
from agents import Agent, Runner
from privacy_filter_openai import PiiInputGuardrail, PiiOutputGuardrail

async def main():
    input_guardrail = PiiInputGuardrail(min_score=0.9)
    output_guardrail = PiiOutputGuardrail()

    agent = Agent(
        name="Assistant",
        instructions="Help the user with their questions.",
        input_guardrails=[input_guardrail],
        output_guardrails=[output_guardrail],
    )

    result = await Runner.run(
        agent,
        "My name is John Doe and my phone is 555-0123"
    )
    print(result.final_output)
    # Output references "John Doe" and "555-0123", not placeholders

if __name__ == "__main__":
    asyncio.run(main())

GuardrailResult Behavior

• Input guardrail: Returns GuardrailResult(output=redacted_text, triggered=True) — the agent sees redacted text
• Output guardrail: Returns GuardrailResult(output=unredacted_text, triggered=True) — user sees original values

Dependencies

• privacy-filter — Core PII detection library
• openai-agents (optional extra) — OpenAI Agents SDK

Related

• Core library: privacy-filter
• NanoBot integration: nanobot-privacy-filter-hook
• OpenAI Agents docs: https://openai.github.io/openai-agents-python/

License

MIT