AGENTS.md

Agent Instructions — openai-agents-hook

OpenAI Agents SDK guardrail integration for PII redaction.

Package Layout

src/privacy_filter_openai/
├── __init__.py      # Exports PiiInputGuardrail, PiiOutputGuardrail
└── guardrails.py    # Guardrail implementations

Development Commands

# IMPORTANT: privacy-filter must be installed first (editable or from wheel)
cd ../privacy-filter
uv pip install -e .

# Then work on openai-agents-hook
cd ../openai-agents-hook
uv sync

# Build wheel
uv build

Key Implementation Details

Dependency Chain

• pyproject.toml depends on "privacy-filter" (local package)
• Optional extra: openai → installs openai-agents (the Agents SDK)
• Must install privacy-filter first before this package will work

Guardrail Interface

From agents SDK:

class Guardrail:
    async def __call__(
        self,
        context: RunContextWrapper,
        agent: Agent,
        input_content: str,  # or output_content
    ) -> GuardrailFunctionOutput:
        ...

@dataclass
class GuardrailFunctionOutput:
    output: str
    triggered: bool

Our Implementation

class PiiInputGuardrail:
    """Redacts PII from user messages before agent processing."""
    async def __call__(context, agent, input_content) -> GuardrailFunctionOutput

class PiiOutputGuardrail:
    """Restores PII from placeholders in agent responses."""
    async def __call__(context, agent, output_content) -> GuardrailFunctionOutput

State Sharing Between Guardrails

The tricky part: input and output guardrails are separate instances, but they need to share the PiiStore (placeholder mappings).

Solution: Use a module-level dict keyed by context id:

_PIISTORE_CONTEXT: dict[int, PiiStore] = {}

# Input guardrail stores:
_PIISTORE_CONTEXT[id(context)] = store

# Output guardrail retrieves and clears:
store = _PIISTORE_CONTEXT.pop(id(context), None)

This assumes input guardrail runs before output guardrail for the same context.

Publishing

This is a separate package (openai-agents-privacy-filter) that depends on privacy-filter.

Important publishing order:

1. privacy-filter must be on PyPI first
2. Wait a few minutes for PyPI index propagation
3. Then build/publish openai-agents-privacy-filter

# 1. Ensure privacy-filter is published to PyPI
cd ../privacy-filter
uv build
uv publish dist/*

# 2. Wait for PyPI, then build/publish openai-agents-hook
cd ../openai-agents-hook
uv build
uv publish dist/*

Note: This package fails to build if privacy-filter is not on PyPI.

Dependencies

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

OpenAI Agents SDK Reference

• Docs: https://openai.github.io/openai-agents-python/
• Guardrails: https://openai.github.io/openai-agents-python/guardrails/