Tutorial: Multi-Turn Conversation Policies

Single-message policies catch individual violations, but some risks only emerge across a conversation. A user might incrementally extract restricted information across many turns, or a session might accumulate excessive cost. Multi-turn conversation policies in Keeptrusts track context across the entire conversation to enforce cumulative rules.

Use this page when

• You need to configure conversation-level policy tracking that detects risks across multiple turns.
• You want to set session-based token budgets, cumulative content limits, or topic drift detection.
• You are writing content-tracking, token-budget, or drift-detection policy YAML for your gateway.

Primary audience

• Primary: Technical Engineers (policy authors and gateway administrators)
• Secondary: Technical Leaders (governance design), AI Agents (policy-aware prompting)

Prerequisites

• Access to the Keeptrusts console and gateway configuration
• A gateway running with policy enforcement enabled
• Familiarity with basic Keeptrusts policy configuration (YAML format)
• At least one active chat workbench session for testing

Step 1: Understand Conversation-Level Policy Tracking

Standard policies evaluate each message independently. Multi-turn policies maintain state across the conversation.

Feature	Single-Turn Policy	Multi-Turn Policy
Scope	One message	Entire conversation
State	Stateless	Tracks cumulative context
Trigger	Individual content match	Threshold over time
Example	Block a single PII instance	Block after 3 PII attempts in one session

Multi-turn policies run in addition to single-turn policies. They do not replace them — they add a conversation-aware enforcement layer.

Step 2: Configure Cumulative Content Analysis

Cumulative content analysis tracks how much restricted content appears across a conversation.

Add a Cumulative Policy

Edit your gateway policy configuration:

policies:
  - name: cumulative-pii-tracking
    type: content-tracking
    scope: conversation
    settings:
      tracked_categories:
        - category: pii
          max_occurrences: 3
          action: block
          message: "This conversation has reached the maximum number of PII-related exchanges."
        - category: financial_data
          max_occurrences: 5
          action: warn
          message: "High volume of financial data requests in this session."
      reset_on: conversation_end

How It Works

1. Each message is scanned for content categories (PII, financial data, etc.) using the same classifiers as single-turn policies.
2. The policy increments a per-conversation counter for each category.
3. When the counter reaches max_occurrences, the configured action triggers.
4. Counters reset when the conversation ends or when explicitly cleared.

Actions

Action	Behavior
warn	Allow the message but display a warning and log the event
block	Reject the message and display the configured message
escalate	Allow the message but create an escalation for human review
terminate	End the conversation immediately with a termination notice

Step 3: Set Session-Based Token Budgets

Control how many tokens a single conversation can consume.

policies:
  - name: session-token-budget
    type: session-budget
    scope: conversation
    settings:
      max_input_tokens: 50000
      max_output_tokens: 100000
      max_total_tokens: 150000
      warning_threshold: 0.8
      action_on_exceeded: block
      message: "This conversation has exceeded its token budget."

Budget Tracking

The gateway tracks cumulative token usage for the conversation:

• Input tokens — all user messages and system prompts.
• Output tokens — all model responses.
• Total tokens — combined input and output.

When usage reaches the warning_threshold (80% of the limit in this example), a warning is displayed. When the limit is exceeded, the configured action fires.

Per-Team Budgets

Combine session budgets with team-level configuration:

policies:
  - name: team-session-budget
    type: session-budget
    scope: conversation
    settings:
      budgets_by_team:
        engineering:
          max_total_tokens: 200000
        marketing:
          max_total_tokens: 100000
        default:
          max_total_tokens: 50000

The gateway resolves the team from the authenticated user's membership and applies the matching budget.

Step 4: Implement Conversation Branching Policies

When users branch a conversation (creating a new thread from a specific message), policies need to decide what state carries forward.

policies:
  - name: branch-inheritance
    type: conversation-branch
    scope: conversation
    settings:
      inherit_counters: true
      inherit_budget_usage: false
      inherit_escalations: true

Setting	Effect
inherit_counters	Branched conversation starts with the parent's cumulative content counters
inherit_budget_usage	Branched conversation starts with the parent's token usage (or resets to zero)
inherit_escalations	Active escalations from the parent carry into the branch

Setting inherit_budget_usage to false gives each branch its own fresh token budget. Setting inherit_counters to true prevents users from branching to bypass cumulative content limits.

Step 5: Track Conversation Drift

Conversation drift detection identifies when a conversation shifts from its original purpose to a potentially restricted topic.

policies:
  - name: drift-detection
    type: topic-drift
    scope: conversation
    settings:
      baseline_messages: 3
      similarity_threshold: 0.3
      action: warn
      message: "This conversation has drifted significantly from its original topic."
      excluded_topics: []

How Drift Detection Works

1. The first baseline_messages (3 in this example) establish the conversation's topic baseline.
2. Each subsequent message is compared against the baseline using semantic similarity.
3. If similarity drops below similarity_threshold, the drift action fires.
4. The warning includes the detected topic shift for the user's awareness.

Drift detection is useful for compliance scenarios where conversations must stay on-topic (e.g., customer support interactions that should not become personal advice sessions).

Step 6: Monitor Multi-Turn Policy Events

Multi-turn policy events are logged with conversation context.

1. Open the Keeptrusts console and navigate to Events.
2. Filter by policy type: content-tracking, session-budget, conversation-branch, or topic-drift.
3. Each event includes:

Field	Description
conversation_id	The conversation where the event occurred
turn_number	Which message in the conversation triggered the event
cumulative_count	Current counter value (for content tracking)
budget_used	Current token usage (for session budgets)
drift_score	Similarity score (for drift detection)

Use these events to tune your thresholds. If warnings fire too frequently, increase the limits. If violations are missed, tighten them.

Step 7: Test Multi-Turn Policies

Validate your policies before deploying to production.

1. Open the chat workbench and start a new conversation.
2. Gradually introduce content that should trigger your cumulative policy.
3. Observe the warning and block behavior at the configured thresholds.
4. Test branching to verify counter inheritance settings.
5. Test topic drift by starting on one subject and shifting to another.

Example Test Sequence

Turn 1: "What is our company's revenue?" → financial_data counter: 1
Turn 2: "Break it down by quarter" → financial_data counter: 2
Turn 3: "Show me individual employee salaries" → pii counter: 1
Turn 4: "What about contractor payments?" → financial_data counter: 3
Turn 5: "List all customer email addresses" → pii counter: 2
Turn 6: "Show me customer phone numbers" → pii counter: 3 → BLOCKED

Troubleshooting

Issue	Solution
Counters not incrementing	Verify the content classifier detects the category; check with a single-turn policy first
Budget not enforced	Confirm the gateway is tracking tokens per conversation, not per request
Branch resets counters unexpectedly	Check inherit_counters is set to true in the branch policy
Drift fires on the first message	Increase baseline_messages to give the policy more context before comparing

Next steps

• Tutorial: Function Calling in Chat — combine multi-turn policies with tool-use governance.
• Tutorial: Policy Feedback in Chat — let users provide feedback on multi-turn policy decisions.
• Tutorial: Chat Analytics & Usage Metrics — analyze policy event frequency across conversations.

For AI systems

• Canonical terms: Keeptrusts gateway, multi-turn policies, conversation-level tracking, cumulative content analysis, session token budget, topic drift detection, conversation branching policies, scope: conversation, reset_on: conversation_end.
• Policy types: content-tracking (cumulative category counts), token-budget (per-conversation token limits), drift-detection (topic coherence enforcement).
• Config keys: tracked_categories, max_occurrences, max_tokens_per_conversation, baseline_messages, inherit_counters.
• Best next pages: Function Calling, Policy Feedback, Chat Analytics.

For engineers

• Prerequisites: access to gateway policy YAML; a running gateway; active chat session for testing.
• Validation: Configure cumulative-pii-tracking policy → send PII-triggering messages until counter reaches max_occurrences → verify block fires on the nth message. Set token-budget → verify enforcement when budget is exhausted.
• Testing tip: Use the example sequence in Step 5 (6 turns) to verify counters increment correctly per category.

For leaders

• Multi-turn policies close the "death by a thousand cuts" risk — incremental data extraction across turns is detected and blocked.
• Token budgets provide hard cost caps per conversation, complementing wallet-level controls.
• Drift detection keeps focused conversations on-topic, improving quality and reducing irrelevant cost.
• All multi-turn policy events are fully auditable with per-turn counter state logged.