openai-agents-tonic-textual 0.1.0

Tonic Textual PII redaction tools and guardrails for the OpenAI Agents SDK

OpenAI Agents SDK: Tonic Textual

PII detection and redaction tools and guardrails for the OpenAI Agents SDK, powered by Tonic Textual.

Tonic Textual is a transformer-based PII engine supporting 46+ entity types across 50+ languages. This package provides:

• Function tools that let agents actively redact PII from text, JSON, HTML, and binary files
• An input guardrail that blocks user messages containing PII before they reach the LLM
• An output guardrail that catches PII in agent responses before they reach the user

Installation

pip install openai-agents-tonic-textual

Authentication

All functions read from the TONIC_TEXTUAL_API_KEY environment variable by default:

export TONIC_TEXTUAL_API_KEY="your-textual-api-key"

You can also pass api_key= explicitly to any function if you prefer.

Quick Start

Tools (agent actively calls redaction)

from agents import Agent, Runner
from openai_agents_tonic_textual import textual_tools

agent = Agent(
    name="PII Redactor",
    instructions="Use the available tools to redact PII from any input.",
    tools=textual_tools(),
)

result = Runner.run_sync(agent, "Redact: John Smith lives at 123 Main St")
print(result.final_output)

Input Guardrail (block PII before it reaches the LLM)

from agents import Agent, Runner, InputGuardrailTripwireTriggered
from openai_agents_tonic_textual import textual_input_guardrail

agent = Agent(
    name="Safe Assistant",
    instructions="You are a helpful assistant.",
    input_guardrails=[textual_input_guardrail()],
)

try:
    result = Runner.run_sync(agent, "My SSN is 123-45-6789")
except InputGuardrailTripwireTriggered as e:
    info = e.guardrail_result.output.output_info
    print(f"PII detected! Redacted: {info['redacted_text']}")

Output Guardrail (catch PII in agent responses)

from agents import Agent, Runner, OutputGuardrailTripwireTriggered
from openai_agents_tonic_textual import textual_output_guardrail

agent = Agent(
    name="Safe Assistant",
    instructions="You are a helpful assistant.",
    output_guardrails=[textual_output_guardrail()],
)

try:
    result = Runner.run_sync(agent, "Tell me about John Smith")
except OutputGuardrailTripwireTriggered as e:
    info = e.guardrail_result.output.output_info
    print(f"PII in output! Redacted: {info['redacted_text']}")

Both Guardrails

from openai_agents_tonic_textual import textual_input_guardrail, textual_output_guardrail

agent = Agent(
    name="Fully guarded assistant",
    instructions="You are a helpful assistant.",
    input_guardrails=[textual_input_guardrail()],
    output_guardrails=[textual_output_guardrail()],
)

Available Tools

Tool	Description
redact_text	Redact PII from plain text
redact_json	Redact PII from JSON strings, preserving structure
redact_html	Redact PII from HTML content, preserving markup
redact_file	Redact PII from binary files (PDF, JPG, PNG, CSV, TSV)
extract_entities	Extract PII entities as a JSON array (detection only, no modification)
list_pii_types	List all 46+ PII entity types Tonic Textual can detect

Configuration

PII Handling Modes

tools = textual_tools(
    generator_default="Synthesis",  # "Off", "Redaction", or "Synthesis"
    generator_config={
        "NAME_GIVEN": "Synthesis",
        "EMAIL_ADDRESS": "Redaction",
        "PHONE_NUMBER": "Off",
    },
)

Mode	Behavior
Off	PII is detected but left unchanged
Redaction	PII is replaced with entity type labels (e.g., [NAME_GIVEN])
Synthesis	PII is replaced with realistic synthetic values

Self-Hosted Deployments

tools = textual_tools(base_url="https://textual.your-company.com")

Guardrail Entity Filtering

Only trigger guardrails for specific PII types:

# Works the same for both input and output guardrails
input_guard = textual_input_guardrail(
    entities=["US_SSN", "CREDIT_CARD"],  # Only block SSNs and credit cards
)

output_guard = textual_output_guardrail(
    entities=["US_SSN", "CREDIT_CARD"],
)

Self-Correcting Error Messages

The tools include built-in format detection. If an agent sends JSON to redact_text, the tool returns an error message naming the correct tool (redact_json). This enables agents to self-correct without human intervention.