Class●Since v1.0

PIIMiddleware

Detect and handle Personally Identifiable Information (PII) in conversations.

This middleware detects common PII types and applies configurable strategies to handle them. It can detect emails, credit cards, IP addresses, MAC addresses, and URLs in both user input and agent output.

Built-in PII types:

email: Email addresses
credit_card: Credit card numbers (validated with Luhn algorithm)
ip: IP addresses (validated with stdlib)
mac_address: MAC addresses
url: URLs (both http/https and bare URLs)

Strategies:

block: Raise an exception when PII is detected
redact: Replace PII with [REDACTED_TYPE] placeholders
mask: Partially mask PII (e.g., ****-****-****-1234 for credit card)
hash: Replace PII with deterministic hash (e.g., <email_hash:a1b2c3d4>)

Strategy Selection Guide:

Strategy	Preserves Identity?	Best For
`block`	N/A	Avoid PII completely
`redact`	No	General compliance, log sanitization
`mask`	No	Human readability, customer service UIs
`hash`	Yes (pseudonymous)	Analytics, debugging

PIIMiddleware(
  self,
  pii_type: Literal['email', 'credit_card', 'ip', 'mac_address', 'url'] | str,
  *,
  strategy: Literal['block', 'redact', 'mask', 'hash'] = 'redact',
  detector: Callable[[str], list[PIIMatch]] | str | None = None,
  apply_to_input: bool = True,
  apply_to_output: bool = False,
  apply_to_tool_results: bool = False
)

Bases

AgentMiddleware[AgentState[ResponseT], ContextT, ResponseT]

Example:

from langchain.agents.middleware import PIIMiddleware
from langchain.agents import create_agent

# Redact all emails in user input
agent = create_agent(
    "openai:gpt-5",
    middleware=[
        PIIMiddleware("email", strategy="redact"),
    ],
)

# Use different strategies for different PII types
agent = create_agent(
    "openai:gpt-4o",
    middleware=[
        PIIMiddleware("credit_card", strategy="mask"),
        PIIMiddleware("url", strategy="redact"),
        PIIMiddleware("ip", strategy="hash"),
    ],
)

# Custom PII type with regex
agent = create_agent(
    "openai:gpt-5",
    middleware=[
        PIIMiddleware("api_key", detector=r"sk-[a-zA-Z0-9]{32}", strategy="block"),
    ],
)

Parameters

Name	Type	Description
`pii_type`*	`Literal['email', 'credit_card', 'ip', 'mac_address', 'url'] \| str`	Type of PII to detect. Can be a built-in type (`email`, `credit_card`, `ip`, `mac_address`, `url`) or a custom type name.
`strategy`	`Literal['block', 'redact', 'mask', 'hash']`	Default:`'redact'` How to handle detected PII. Options: `block`: Raise `PIIDetectionError` when PII is detected `redact`: Replace with `[REDACTED_TYPE]` placeholders `mask`: Partially mask PII (show last few characters) `hash`: Replace with deterministic hash (format: `<type_hash:digest>`)
`detector`	`Callable[[str], list[PIIMatch]] \| str \| None`	Default:`None` Custom detector function or regex pattern. If `Callable`: Function that takes content string and returns list of `PIIMatch` objects If `str`: Regex pattern to match PII If `None`: Uses built-in detector for the `pii_type`
`apply_to_input`	`bool`	Default:`True` Whether to check user messages before model call.
`apply_to_output`	`bool`	Default:`False` Whether to check AI messages after model call.
`apply_to_tool_results`	`bool`	Default:`False` Whether to check tool result messages after tool execution.

Constructors

constructor

__init__

Name	Type
pii_type	Literal['email', 'credit_card', 'ip', 'mac_address', 'url'] \| str
strategy	Literal['block', 'redact', 'mask', 'hash']
detector	Callable[[str], list[PIIMatch]] \| str \| None
apply_to_input	bool
apply_to_output	bool
apply_to_tool_results	bool