Blog · · 9 min read

AI agent handoff input filter: redact tool payloads before nesting history so specialists never see private product data

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:

  1. Declare destination visibility. FAQ, refund, and billing specialists do not share one allowlist for tools, fields, and message classes.
  2. Redact typed tools and load-bearing payloads first. Clean input_history, pre_handoff_items, and new_items before any nest or summarize step (OpenAI handoff filters).
  3. Then nest or summarize. Prefer nest_handoff_history(remove_all_tools(...)), or sanitize the returned input_history after nesting while keeping original new_items for session storage (#4614; OpenAI Handoffs).
  4. Never treat input_items-only filtering as enough. Nested history is built from the three source fields, not from an input_items override alone (OpenAI Handoffs).
  5. Split durable session from model-visible input. Audit what the specialist provider request contained; keep the unredacted causality under ordinary product access controls.
  6. 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_tools strips typed tool items: function calls, outputs, search, MCP-related records, and similar structures (OpenAI handoff filters).
  • nest_handoff_history compacts 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:

ProjectionContentsConsumer
Model-visibleDestination allowlist only; tools redacted or summarized without private payloadsSpecialist provider request
Durable sessionFull typed tool causality under product ACLsAudit, 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:

DestinationMay seeMust not see
FAQUser utterance, public article IDs, sanitized ticket subjectPayment tokens, raw CRM dumps, internal admin notes
RefundOrder ID, refund eligibility fields, prior refund decisionsUnrelated account exports, sibling ticket bodies
BillingInvoice IDs, balance summariesFull 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

FailureResponse
Filter throws mid-handoffDo not transfer; keep the run on the source agent or safe queue
Nested summary still contains a planted markerBlock the specialist call; alert; treat as a release blocker
Destination missing from allowlist matrixFail closed; do not inherit the triage transcript
Durable store write fails after model-visible projectionPrefer not completing the handoff over losing audit causality
Specialist needs a field you redactedReturn 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:

  1. 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).
  2. 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).
  3. input_items-only trap. Apply a filter that cleans only input_items and assert your wrapper still refuses to nest dirty source fields (OpenAI Handoffs).
  4. Destination matrix. Same triage transcript to FAQ and refund yields different model-visible field sets.
  5. Durable retention. Authorized audit read still returns the original tool causality after a redacted specialist transfer.
  6. 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

  1. Treating remove_all_tools as a complete privacy control. It removes typed items; nesting can re-encode the same payloads as summary text (#4614).
  2. Compressing before redacting. Competitor guidance to remove then compress is directionally right; reversing the order recreates the leak (PraisonAI Handoff Filters).
  3. One filter for every destination. Global strip either over-shares to FAQ or under-shares to refund.
  4. Deleting durable history to "be safe." You need audit causality; project a second view instead.
  5. Checking only UI transcripts. Verify the provider request the specialist model actually receives.
  6. 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.

Be first in line.

Join the waitlist and we'll email you the moment it's ready. No sales call.

Try the demo →
or talk to us