Blog · · 9 min read
AI agent handoff input filter: redact tool payloads before nesting history so specialists never see private product data

Your triage agent looked up a ticket, saw a payment method fragment in a tool result, then handed the run to an FAQ specialist. You wired remove_all_tools so the specialist would not see raw tool calls. The typed items disappeared. The nested history summary still contained the tool name, call ID, arguments, and the payment fragment as ordinary assistant text. A dashboard that only counts typed tool items will report success while the specialist model request still carries private product data. That is the practical failure behind an AI agent handoff input filter in a product multi-agent flow: presentation can reintroduce what type-aware filters already removed (OpenAI Agents SDK: Handoffs; openai-agents-python#4614).
Direct answer: redact, then nest, then prove
Ship one product-owned contract before you trust triage to specialist transfers with real CRM or support tools:
- Declare destination visibility. FAQ, refund, and billing specialists do not share one allowlist for tools, fields, and message classes.
- Redact typed tools and load-bearing payloads first. Clean
input_history,pre_handoff_items, andnew_itemsbefore any nest or summarize step (OpenAI handoff filters). - Then nest or summarize. Prefer
nest_handoff_history(remove_all_tools(...)), or sanitize the returnedinput_historyafter nesting while keeping originalnew_itemsfor session storage (#4614; OpenAI Handoffs). - Never treat
input_items-only filtering as enough. Nested history is built from the three source fields, not from aninput_itemsoverride alone (OpenAI Handoffs). - Split durable session from model-visible input. Audit what the specialist provider request contained; keep the unredacted causality under ordinary product access controls.
- Fixture the leak path. Plant a unique private marker in a tool result and assert it is absent from the specialist model request after handoff.
HandoffProjectionContract {
destination: faq | refund | billing | ...
allowlist: tools, fields, message_classes
project(data):
cleaned = redact_typed_tools_and_payloads(
data.input_history,
data.pre_handoff_items,
data.new_items,
allowlist[destination]
)
visible = nest_or_summarize(cleaned) # never nest dirty sources
durable = data.new_items # unredacted for authorized audit
audit_hash = hash(visible.model_input)
assert marker_absent(visible, planted_private_marker)
return ModelVisible(visible), Durable(durable), Audit(audit_hash)
}
Why typed-tool filters still leak
Handoffs reuse conversation history so the next agent can continue the job. OpenAI's Agents SDK models that transfer as a tool call and, by default, lets the receiving agent see the prior transcript unless you change it with an input_filter or nested-history settings (OpenAI Handoffs).
Two helpers look like a complete privacy answer:
remove_all_toolsstrips typed tool items: function calls, outputs, search, MCP-related records, and similar structures (OpenAI handoff filters).nest_handoff_historycompacts summarizable history into assistant summary segments for the next agent (OpenAI handoff filters).
Composition order and presentation decide whether the filter holds. Nesting summarizes without redacting sensitive data. Tool arguments and outputs from the source fields can remain inside the generated assistant summary even after structured tool items are no longer forwarded separately (OpenAI Handoffs; nest_handoff_history).
Issue #4614 makes the failure concrete. Composing remove_all_tools(nest_handoff_history(...)) removes typed tool records, yet the target agent can still see the tool name, call ID, arguments, and private output marker inside the SDK-generated summary. The maintainer confirmed the observation: once nesting serializes typed records into ordinary assistant text, a later type-aware filter has nothing left to remove. The safe order is nest_handoff_history(remove_all_tools(data)), or an equivalent sanitize-before-present path (#4614).
Competitor docs already recommend remove-then-compress chains and privacy-aware custom filters (PraisonAI Handoff Filters). Follow that order, then add what product SaaS still needs: destination allowlists, a durable-versus-model-visible split, and a leak fixture against nested summary text.
Filtering only input_items is a false green
Filtering only input_items while leaving input_history, pre_handoff_items, and new_items dirty still leaks private tool payloads into nested summaries. OpenAI's handoffs guide states the helper builds nested history from those three fields and ignores an existing input_items override, so excluding content only from input_items can leave tool payloads in the generated summary (OpenAI Handoffs; nest_handoff_history).
Product teams often discover this after a dashboard shows "tools removed" while a specialist model request still contains ticket bodies. Inspect the specialist provider payload for privacy proof; the absence of typed tool item types is not enough. If you must preserve original new_items for session history, sanitize the returned input_history after nesting rather than pretending an input_items override cleaned the nest (OpenAI Handoffs).
Keep durable causality; project a redacted specialist view
Durable session history should keep the unredacted tool causality for audit while the specialist model request receives a separately projected, redacted view. Support, trust, and incident review still need to answer which tool ran, with which arguments, and what it returned. The FAQ specialist model does not.
Implement two projections from one handoff event:
| Projection | Contents | Consumer |
|---|---|---|
| Model-visible | Destination allowlist only; tools redacted or summarized without private payloads | Specialist provider request |
| Durable session | Full typed tool causality under product ACLs | Audit, resume, dispute, SOC review |
OpenAI's input_items field exists so you can filter model input while keeping new_items intact for session history (OpenAI Handoffs). Use that split deliberately. Log a hash or redacted fingerprint of the model-visible payload at handoff time so an incident can prove what the specialist saw without dumping another copy of the secrets into logs.
Do not solve privacy by deleting durable history. That trades a model leak for an unrecoverable support case.
Destination allowlists beat a global strip
A global remove_all_tools policy is not a destination allowlist: FAQ, refund, and billing specialists need different visibility contracts for the same triage transcript. Refund may need order identifiers and payment-state summaries. FAQ usually needs the user question and public knowledge links, not payment method fragments. Billing may need invoice line items the FAQ agent must never receive.
Build a matrix before you ship multi-agent routing:
| Destination | May see | Must not see |
|---|---|---|
| FAQ | User utterance, public article IDs, sanitized ticket subject | Payment tokens, raw CRM dumps, internal admin notes |
| Refund | Order ID, refund eligibility fields, prior refund decisions | Unrelated account exports, sibling ticket bodies |
| Billing | Invoice IDs, balance summaries | Full card PANs, session cookies, other tenants' rows |
PraisonAI's privacy-aware custom filter example shows keyword redaction before compress (PraisonAI Handoff Filters). Extend that idea from string scrubbing to product-owned field classes tied to destination. A regex for emails is useful. An allowlist of schema fields per specialist is what stops systematic over-share.
Keep this separate from delegated authority work elsewhere in the stack. Authority envelopes decide what a child may do. Handoff projection decides what it may see. You need both.
Implement the AI agent handoff input filter in an existing product
1. Inventory handoff edges
List every in-product transfer: triage to FAQ, triage to refund, supervisor takeover, language specialist, and any agent-as-tool nested specialist. For each edge, name the destination, the tools the source may have called, and the minimum fields the destination needs to finish the job.
2. Sanitize source fields before presentation
# Recommendation: product-owned wrapper, not a drop-in for every SDK version.
def project_for_destination(data, destination, allowlist):
cleaned = redact_tools_and_fields(
input_history=data.input_history,
pre_handoff_items=data.pre_handoff_items,
new_items=data.new_items,
allowlist=allowlist[destination],
)
# Safe composition: redact typed payloads before nest/summarize presentation.
nested = nest_handoff_history(cleaned)
model_visible = nested.input_history
durable = data.new_items # keep original causality for authorized audit
return model_visible, durable
Follow the documented contract: sanitize all three source fields before calling nest, or sanitize the returned history while preserving original new_items for session storage (nest_handoff_history; OpenAI Handoffs).
3. Wire the filter on the handoff object
Attach the destination-specific filter on the handoff itself so a global run filter cannot accidentally widen visibility for one specialist. OpenAI documents per-handoff input_filter precedence over a run-level filter (OpenAI Handoffs).
4. Redact nested summary text, not only typed items
After nesting, scan model-visible assistant summary text for destination-denied field classes and private markers. Type-aware removal is required, and once presentation has flattened tools into prose you still need a text-level check (#4614).
5. Fail closed on unknown destinations
If routing picks a specialist without a visibility policy, do not default to full history. Refuse the handoff or fall back to a minimal brief: user goal, ticket ID, and public knowledge links.
Handle failure and recovery
| Failure | Response |
|---|---|
| Filter throws mid-handoff | Do not transfer; keep the run on the source agent or safe queue |
| Nested summary still contains a planted marker | Block the specialist call; alert; treat as a release blocker |
| Destination missing from allowlist matrix | Fail closed; do not inherit the triage transcript |
| Durable store write fails after model-visible projection | Prefer not completing the handoff over losing audit causality |
| Specialist needs a field you redacted | Return a structured "missing field" handoff error so triage fetches a minimal allowlisted brief, rather than widening the whole transcript |
Server-managed conversation IDs that cannot apply handoff input filters need a separate run with explicitly selected input; do not reuse the original conversation identity when the receiving agent must not inherit that history (OpenAI Handoffs).
Verify the solution
Run these checks in CI against a staging agent runtime:
- Marker absence. Plant
PRIVATE_TOOL_OUTPUT_<uuid>only in a tool result. After handoff, assert the specialist provider request body does not contain the marker (#4614). - Unsafe order regression. Reproduce
remove_all_tools(nest_handoff_history(...))as a negative test that must fail your product wrapper, and assert the safe order passes (#4614). input_items-only trap. Apply a filter that cleans onlyinput_itemsand assert your wrapper still refuses to nest dirty source fields (OpenAI Handoffs).- Destination matrix. Same triage transcript to FAQ and refund yields different model-visible field sets.
- Durable retention. Authorized audit read still returns the original tool causality after a redacted specialist transfer.
- Typed item absence. Model-visible history contains no destination-denied tool item types after projection (OpenAI handoff filters).
Operational checklist before enabling a new specialist:
- Visibility matrix row reviewed by security and the owning product surface
- Filter attached on the handoff edge, not only documented in a wiki
- Leak fixture green in CI
- Audit hash logged on every handoff
- On-call runbook for "marker detected in specialist request"
Common mistakes
- Treating
remove_all_toolsas a complete privacy control. It removes typed items; nesting can re-encode the same payloads as summary text (#4614). - Compressing before redacting. Competitor guidance to remove then compress is directionally right; reversing the order recreates the leak (PraisonAI Handoff Filters).
- One filter for every destination. Global strip either over-shares to FAQ or under-shares to refund.
- Deleting durable history to "be safe." You need audit causality; project a second view instead.
- Checking only UI transcripts. Verify the provider request the specialist model actually receives.
- Treating authority envelopes as sufficient. Child credentials can be correct while the child still sees private tool outputs it should not.
What to do next
Pick your highest-traffic triage to specialist edge. Write the destination allowlist for that edge, wrap handoff projection so redaction always runs before nest or summarize, and add the planted-marker CI fixture before you enable another specialist. If you are evaluating platforms for product-agent workflows, ask whether handoffs expose a first-class model-visible versus durable split and whether you can prove private tool markers never cross. Make Your Agent targets product surfaces where those boundaries decide whether specialist routing is safe to ship.