diff --git a/fern/security-and-privacy/PCI.mdx b/fern/security-and-privacy/PCI.mdx index 3a6ab8726..4aed23785 100644 --- a/fern/security-and-privacy/PCI.mdx +++ b/fern/security-and-privacy/PCI.mdx @@ -161,7 +161,7 @@ Here's a complete squad configuration that demonstrates this approach: "assistantName": "Assistant 3", "description": "Transfer the caller to the payment confirmation assistant.", "contextEngineeringPlan": { - "type": "none" + "type": "previousAssistantMessages" }, "variableExtractionPlan": { "schema": { @@ -227,6 +227,97 @@ The key component is the `artifactPlan` in Assistant 2: This ensures that sensitive payment information is never recorded, logged, or transcribed, while still allowing you to maintain call quality data for the non-sensitive portions of the conversation. +## Handoff Context Configuration + +When using squads or the handoff tool, you can control what conversation context is forwarded to the next assistant using `contextEngineeringPlan`. This is particularly important for PCI-compliant flows where an assistant handles sensitive data such as payment card numbers. + +By default, handoffs use `contextEngineeringPlan` type `all`, which transfers the entire conversation history -- including tool call results. For assistants that process sensitive data, you should choose a more restrictive context type to ensure that tool call results (which may contain card numbers or other sensitive values) are not forwarded. + + +If a sensitive assistant uses the default `contextEngineeringPlan` (type `all`), the full conversation context -- including tool call results -- will be forwarded to the next assistant. Always set an appropriate context engineering plan on handoff destinations from assistants that handle sensitive data. + + +### Recommended context types + +The following table describes the `contextEngineeringPlan` types relevant to PCI and other sensitive data flows: + +| Type | Behavior | PCI Recommendation | +|------|----------|-------------| +| `previousAssistantMessages` | Forwards only the conversation history from **before** the current assistant's session. Excludes the current assistant's own messages and tool calls entirely. | **Recommended.** Preserves useful pre-payment context while fully excluding the sensitive assistant's data. | +| `none` | Starts the next assistant with a blank conversation. No prior context is forwarded. | **Safe.** Maximum isolation. Use when the next assistant does not need any prior context. | + + +For a full reference on all context engineering plan types, see the [Handoff Tool - Context Engineering](/squads/handoff#context-engineering) documentation. + + +### Configuring the context engineering plan + +Set the `contextEngineeringPlan` on the handoff destination from your sensitive assistant. Here is an example using `previousAssistantMessages`: + +```json +"assistantDestinations": [ + { + "type": "assistant", + "assistantName": "Confirmation Assistant", + "description": "Transfer to the confirmation assistant after payment collection.", + "contextEngineeringPlan": { + "type": "previousAssistantMessages" + } + } +] +``` + +Or equivalently, when using the handoff tool: + +```json +{ + "type": "handoff", + "destinations": [ + { + "type": "assistant", + "assistantName": "Confirmation Assistant", + "description": "Transfer to the confirmation assistant after payment collection.", + "contextEngineeringPlan": { + "type": "previousAssistantMessages" + } + } + ] +} +``` + +### Using variable extraction for safe data passing + +If the next assistant needs specific data from the sensitive session (such as the last four digits of a card number for confirmation), use `variableExtractionPlan` instead of relying on full context forwarding. This extracts only the structured fields you define: + +```json +"assistantDestinations": [ + { + "type": "assistant", + "assistantName": "Confirmation Assistant", + "contextEngineeringPlan": { + "type": "previousAssistantMessages" + }, + "variableExtractionPlan": { + "schema": { + "type": "object", + "properties": { + "lastFourDigits": { + "type": "string", + "description": "Last four digits of the card number" + } + } + } + } + } +] +``` + +The extracted variables are available in the next assistant's system prompt using Liquid template syntax (e.g., `{{lastFourDigits}}`). This is the pattern used in the [Payment Collection Squad Example](#payment-collection-squad-example) above. + + +Combining `contextEngineeringPlan` with `variableExtractionPlan` gives you the best of both worlds: sensitive tool call data is excluded from the forwarded context, while the specific data points the next assistant needs are passed through as named variables. + + ## Can PCI be used alongside HIPAA? Yes, you can enable both HIPAA and PCI compliance for an assistant. In this case, the restrictions from both compliances will apply, meaning that no recordings or transcripts will be stored or transmitted, even if you have specified cloud storage endpoints or webhooks for storing transcripts. diff --git a/fern/squads/handoff.mdx b/fern/squads/handoff.mdx index fcc763470..9213807c9 100644 --- a/fern/squads/handoff.mdx +++ b/fern/squads/handoff.mdx @@ -437,6 +437,24 @@ Transfers only user and assistant messages, filtering out system messages, tool Use `userAndAssistantMessages` when the destination assistant does not need to see tool call history or system prompts from the previous assistant. This produces a cleaner context and reduces token usage. +### Previous assistant messages + +Transfers only the conversation history from **before** the current assistant's session. This excludes the current assistant's own messages, tool calls, and tool results entirely, forwarding only the context that existed when the current assistant first received the call. + +```json +{ + "contextEngineeringPlan": { + "type": "previousAssistantMessages" + } +} +``` + +This mode is particularly useful when the current assistant handles sensitive data (such as payment card numbers in a PCI-compliant flow). By excluding the current assistant's session from the forwarded context, you prevent sensitive tool call results from reaching the next assistant. + + +Use `previousAssistantMessages` when handing off from a sensitive assistant (e.g., one collecting payment data) to a non-sensitive assistant. It preserves useful conversation context from earlier in the call while ensuring the sensitive assistant's tool call data is not forwarded. See the [PCI Compliance - Handoff Context Configuration](/security-and-privacy/pci#handoff-context-configuration) guide for a complete walkthrough. + + ### No context Starts the next assistant with a blank conversation: