{ "cells": [ { "cell_type": "markdown", "metadata": { }, "source": [ "*Module 10 Self-Driven Lab*\r\n", "\r\n", "# Compliance \u0026 Escalation: Policy, Pricing, and the Human Handoff\r\n", "\r\n", "**Objective:** master ZDR auditing, US-only inference configuration, deterministic escalation policy, and structured handoff protocols.\r\n", "\r\n", "## Challenge Outline\r\n", "\r\n", "Build a complete notebook that demonstrates the following outcomes:\r\n", "\r\n", "- **ZDR audit:** evaluate the Module 12 capstone architecture. Identify every component that breaks ZDR, such as Message Batches, Files API, Code Execution, or MCP Connector, and propose a synchronous-only alternative for a regulated client.\r\n", "- **Regional configuration:** set up a Messages API request with `inference_geo: \"us\"`. Calculate the total token cost of a 1,000-token input/output turn using the 1.1x multiplier.\r\n", "- **Escalation logic:** add a policy-silent trigger to the system prompt. Test it by asking for a competitor price match and verify the agent escalates rather than inventing a discount.\r\n", "- **Handoff payload:** implement the `escalate_to_human` tool using `strict: true`. Ensure it captures `customer_id`, `root_cause`, `actions_attempted`, and `recommended_next_step`.\r\n", "- **Schema hardening:** review tool definitions for PHI. Rename properties that contain sensitive identifiers to generic versions to prevent schema-caching risks.\r\n", "\r\n", "Your solution should include enough code, output, or written observations to prove each outcome worked. Keep the notebook focused on final behavior and evidence rather than a guided walkthrough.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Student Workspace\n", "\n", "Use the sections below to build your solution. Each section maps to one required outcome from the challenge outline.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 1: ZDR audit\n", "\n", "evaluate the Module 12 capstone architecture. Identify every component that breaks ZDR, such as Message Batches, Files API, Code Execution, or MCP Connector, and propose a synchronous-only alternative for a regulated client.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 1: ZDR audit\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 2: Regional configuration\n", "\n", "set up a Messages API request with `inference_geo: \"us\"`. Calculate the total token cost of a 1,000-token input/output turn using the 1.1x multiplier.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 2: Regional configuration\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 3: Escalation logic\n", "\n", "add a policy-silent trigger to the system prompt. Test it by asking for a competitor price match and verify the agent escalates rather than inventing a discount.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 3: Escalation logic\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 4: Handoff payload\n", "\n", "implement the `escalate_to_human` tool using `strict: true`. Ensure it captures `customer_id`, `root_cause`, `actions_attempted`, and `recommended_next_step`.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 4: Handoff payload\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 5: Schema hardening\n", "\n", "review tool definitions for PHI. Rename properties that contain sensitive identifiers to generic versions to prevent schema-caching risks.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 5: Schema hardening\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Verification Notes\n", "\n", "Summarize the evidence that each part worked. Capture API signals, validation outcomes, errors, recovery behavior, cost observations, or comparisons required by this lab.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Verification notes\n", "# Record the evidence that proves each lab outcome worked.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "---\n", "\n", "## Answer Key\n", "\n", "The cells below contain the completed reference implementation/content for this module. Use this section only after attempting the self-driven lab." ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "# Compliance \u0026 Escalation: Policy, Pricing, and the Human Handoff\n", "\n", "This module establishes the guardrails of the system: how architects manage data-protection requirements, regional inference constraints, pricing implications, and the exact moment control must transition from an autonomous agent to a human operator.\n", "\n", "## 1. Zero Data Retention (ZDR) \u0026 Compliance Matrix\n", "\n", "Compliance is determined per feature. Architects must know which capabilities keep a workload ZDR-compliant and which break it.\n", "\n", "### 1a. ZDR-Eligible Features\n", "\n", "- Adaptive Thinking\n", "- Citations\n", "- Structured Outputs\n", "- Standard Web Search/Fetch\n", "- Compaction\n", "\n", "### 1b. Non-Eligible Features\n", "\n", "- Message Batches, because batch inputs and outputs are stored for 29 days.\n", "- Files API\n", "- Code Execution\n", "- MCP Connector\n", "\n", "### 1c. HIPAA \u0026 Schema Caching\n", "\n", "PHI must never appear in JSON schema definitions, tool names, property names, or property descriptions because schemas are cached separately from message content. Field names should be generic.\n", "\n", "Use `record_id`, not `patient_ssn`.\n", "\n", "Use `member_identifier`, not `diagnosis_for_jane_doe`.\n", "\n", "## 2. Regional Logic \u0026 The 1.1x Multiplier\n", "\n", "Data residency requirements affect both compute location and billing.\n", "\n", "### 2a. The Multiplier\n", "\n", "Setting `inference_geo: \"us\"` restricts compute to US-based infrastructure but incurs a **1.1x pricing multiplier** on all token categories for models starting with Claude Opus 4.6.\n", "\n", "### 2b. Capacity Impact\n", "\n", "The multiplier also applies to Priority Tier burndown. Each token processed draws down **1.1 tokens** from committed capacity.\n", "\n", "### 2c. Optimization Strategy\n", "\n", "For cost-sensitive high-volume tasks, use Haiku 4.5, which is currently unaffected by this multiplier, and reserve Opus for strategic reasoning turns.\n", "\n", "## 3. Explicit Escalation: Triggers as Policy\n", "\n", "Escalation should be driven by written policy, not model vibes or sentiment alone.\n", "\n", "### 3a. Hard Triggers\n", "\n", "- **Customer requests:** any explicit request for a human must be honored immediately without re-routing or attempting further autonomous resolution.\n", "- **Policy gaps or silence:** if a request touches an area where the provided policy is ambiguous or silent, such as a refund-window exception or competitor price match, the agent must escalate rather than improvising a new policy.\n", "- **High-stakes actions:** use the PreToolUse hooks from Module 9 to catch and escalate irreversible actions before they execute.\n", "\n", "```text\n", "Escalate immediately when:\n", "- The customer asks for a human, manager, representative, or supervisor.\n", "- The policy does not explicitly cover the requested exception.\n", "- The requested action is irreversible, regulated, or above the configured approval threshold.\n", "```\n", "\n", "## 4. The Structured Handoff Protocol\n", "\n", "A blind handoff frustrates users. A structured payload ensures the human operator can resolve the issue quickly.\n", "\n", "The final act of the agent is to call an `escalate_to_human` tool with a strict schema.\n", "\n", "```json\n", "{\n", " \"name\": \"escalate_to_human\",\n", " \"description\": \"Transfer control to a human operator with enough context to resolve the issue without repeating failed steps.\",\n", " \"strict\": true,\n", " \"input_schema\": {\n", " \"type\": \"object\",\n", " \"properties\": {\n", " \"customer_id\": { \"type\": \"string\" },\n", " \"root_cause\": { \"type\": \"string\" },\n", " \"actions_attempted\": {\n", " \"type\": \"array\",\n", " \"items\": { \"type\": \"string\" }\n", " },\n", " \"recommended_next_step\": { \"type\": \"string\" }\n", " },\n", " \"required\": [\n", " \"customer_id\",\n", " \"root_cause\",\n", " \"actions_attempted\",\n", " \"recommended_next_step\"\n", " ],\n", " \"additionalProperties\": false\n", " }\n", "}\n", "```\n", "\n", "## Lab Exercise: Designing the Compliance Guardrail\n", "\n", "**Objective:** master ZDR auditing, US-only inference configuration, deterministic escalation policy, and structured handoff protocols.\n", "\n", "1. **ZDR audit:** evaluate the Module 12 capstone architecture. Identify every component that breaks ZDR, such as Message Batches, Files API, Code Execution, or MCP Connector, and propose a synchronous-only alternative for a regulated client.\n", "2. **Regional configuration:** set up a Messages API request with `inference_geo: \"us\"`. Calculate the total token cost of a 1,000-token input/output turn using the 1.1x multiplier.\n", "3. **Escalation logic:** add a policy-silent trigger to the system prompt. Test it by asking for a competitor price match and verify the agent escalates rather than inventing a discount.\n", "4. **Handoff payload:** implement the `escalate_to_human` tool using `strict: true`. Ensure it captures `customer_id`, `root_cause`, `actions_attempted`, and `recommended_next_step`.\n", "5. **Schema hardening:** review tool definitions for PHI. Rename properties that contain sensitive identifiers to generic versions to prevent schema-caching risks.\n", "\n", "\u003e **Exam tip:** ZDR, data residency, HIPAA schema safety, and escalation are separate decisions. A workflow can satisfy one and fail another." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.11.0" } }, "nbformat": 4, "nbformat_minor": 5 }