{ "cells": [ { "cell_type": "markdown", "metadata": { }, "source": [ "# Module 11 Self-Driven Lab\n", "\n", "Use this notebook as your workspace for **Enterprise Prospecting \u0026 Outreach Orchestrator**. The answer-key notebook sits next to this file. Work through each checkpoint before comparing against the completed version.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "# Final Project — Enterprise Prospecting \u0026 Outreach Orchestrator\n", "\n", "Capstone that ties Modules 1–10 into one production system:\n", "\n", "- **Phase 1** — Coordinator Agent with adaptive thinking, US data residency, and `effort=\"xhigh\"`.\n", "- **Phase 2** — Knowledge mapping with the MCP Connector and `.mcp.json` env-var substitution.\n", "- **Phase 3** — Hub-and-spoke subagent research with structured error responses.\n", "- **Phase 4** — Synthesis with the Advisor tool, Message Batches at 50% off, 300k extended output, structured extraction.\n", "- **Phase 5** — Reliability via PreToolUse hooks, server-side compaction, and the case-facts pattern.\n", "- **Phase 6** — Repository governance with path-scoped rules and a forked-context audit skill.\n", "\n", "**How to use this notebook**\n", "\n", "1. Run **Setup**.\n", "2. Work through **Code Starters** — fill in the `TODO` bodies yourself.\n", "3. Compare to the **Answer Key** sections that follow.\n", "\n", "\u003e Some calls in this notebook hit beta endpoints (`mcp-client-2025-11-20`, `compact-2026-01-12`, `output-300k-2026-03-24`, `advisor-tool-2026-03-01`). Make sure your account has access before running a cell against the live API." ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Setup" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Setup cell. Run this before the exercise cells below.\n", "import os\n", "import time\n", "import json\n", "\n", "import anthropic\n", "from dotenv import load_dotenv\n", "\n", "load_dotenv()\n", "client = anthropic.Anthropic()" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "---\n", "\n", "# Code Starters\n", "\n", "Skeletons for the four core building blocks of the orchestrator. Fill in each `TODO` before peeking at the answer key. Each starter cell raises `NotImplementedError` so it\u0027s obvious which pieces are still stubs." ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Checkpoint 1\n", "\n", "Implement this step yourself. Use the preceding explanation and the module page as your guide, then compare your approach with the answer key after you have a working version.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# TODO: Implement checkpoint 1 for Module 11.\n", "# Keep the cell focused, run it, inspect the output, then move to the next checkpoint.\n", "\n", "raise NotImplementedError(\u0027Complete checkpoint 1\u0027)\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Setup cell. Run this before the exercise cells below.\n", "# PHASES 2 \u0026 3: Hub-and-Spoke Orchestration with MCP\n", "def run_research_session(agent_id, prospect_query):\n", " \"\"\"Open a stateful session and dispatch a coordinator turn that spawns\n", " parallel research subagents in a single message.\n", "\n", " Required:\n", " - client.beta.sessions.create with mcp_servers describing the CRM endpoint\n", " - authorization_token sourced from os.environ[\"CRM_TOKEN\"]\n", " - one client.beta.sessions.events.send with a user.message that instructs\n", " the coordinator to call the Task tool 3+ times in parallel\n", " \"\"\"\n", " raise NotImplementedError(\"TODO: implement run_research_session\")" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Checkpoint 2\n", "\n", "Implement this step yourself. Use the preceding explanation and the module page as your guide, then compare your approach with the answer key after you have a working version.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# TODO: Implement checkpoint 2 for Module 11.\n", "# Keep the cell focused, run it, inspect the output, then move to the next checkpoint.\n", "\n", "raise NotImplementedError(\u0027Complete checkpoint 2\u0027)\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Checkpoint 3\n", "\n", "Implement this step yourself. Use the preceding explanation and the module page as your guide, then compare your approach with the answer key after you have a working version.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# TODO: Implement checkpoint 3 for Module 11.\n", "# Keep the cell focused, run it, inspect the output, then move to the next checkpoint.\n", "\n", "raise NotImplementedError(\u0027Complete checkpoint 3\u0027)\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "---\n", "\n", "# Answer Key\n", "\n", "Reference implementation. Each section corresponds to one phase of the project." ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Phase 1 — Agent Definition \u0026 Data Governance\n", "\n", "The Managed Agent bundles the static config (model, system, tools). The dynamic per-call parameters — adaptive thinking, US data residency, `effort=\"xhigh\"` — are set when you invoke the agent later, not at agent creation." ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Checkpoint 4\n", "\n", "Implement this step yourself. Use the preceding explanation and the module page as your guide, then compare your approach with the answer key after you have a working version.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# TODO: Implement checkpoint 4 for Module 11.\n", "# Keep the cell focused, run it, inspect the output, then move to the next checkpoint.\n", "\n", "raise NotImplementedError(\u0027Complete checkpoint 4\u0027)\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Phase 2 — Knowledge Mapping with MCP \u0026 Resources\n", "\n", "Scaffold the `.mcp.json` for local development and write a runtime-loadable env-var substitutor. **Never commit the rendered file** — commit only the template, then materialize at deploy time." ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Setup cell. Run this before the exercise cells below.\n", "from pathlib import Path\n", "\n", "mcp_template = \u0027\u0027\u0027{\n", " \"mcpServers\": {\n", " \"crm\": {\n", " \"command\": \"node\",\n", " \"args\": [\"./mcp-servers/crm-server.js\"],\n", " \"env\": {\n", " \"CRM_TOKEN\": \"${CRM_TOKEN}\",\n", " \"CRM_BASE_URL\": \"${CRM_BASE_URL}\"\n", " }\n", " }\n", " }\n", "}\n", "\u0027\u0027\u0027\n", "\n", "Path(\"module11_demo\").mkdir(exist_ok=True)\n", "Path(\"module11_demo/.mcp.json.example\").write_text(mcp_template, encoding=\"utf-8\")\n", "print(\"wrote module11_demo/.mcp.json.example — commit this; never the resolved file\")" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Phase 3 — Multi-Agent Research Workflow\n", "\n", "Open a stateful session, attach the CRM via MCP, and instruct the Coordinator to spawn three Task subagents in a single turn. Subagents run with **isolated context** — pass them only what they need.\n", "\n", "Then define the structured-error contract every subagent tool must follow." ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Setup cell. Run this before the exercise cells below.\n", "session = client.beta.sessions.create(\n", " agent_id=coordinator_agent.id,\n", " mcp_servers=[\n", " {\n", " \"name\": \"crm-server\",\n", " \"type\": \"url\",\n", " \"url\": \"https://mcp.your-enterprise.com/crm\",\n", " \"authorization_token\": os.environ.get(\"CRM_TOKEN\", \"DEMO_NOT_SET\"),\n", " }\n", " ],\n", ")\n", "\n", "client.beta.sessions.events.send(\n", " session_id=session.id,\n", " event={\n", " \"type\": \"user.message\",\n", " \"content\": [{\n", " \"type\": \"text\",\n", " \"text\": (\n", " \"Research AI adoption in Fintech and Healthcare simultaneously. \"\n", " \"Spawn three Task subagents in parallel: web_research, \"\n", " \"financial_analysis, competitor_tracking. Pass each only the \"\n", " \"prospect summary they need. Reconcile their outputs into a \"\n", " \"single brief and update the case_facts block before responding.\"\n", " ),\n", " }],\n", " },\n", ")\n", "\n", "print(\"session id:\", session.id)" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Checkpoint 5\n", "\n", "Implement this step yourself. Use the preceding explanation and the module page as your guide, then compare your approach with the answer key after you have a working version.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# TODO: Implement checkpoint 5 for Module 11.\n", "# Keep the cell focused, run it, inspect the output, then move to the next checkpoint.\n", "\n", "raise NotImplementedError(\u0027Complete checkpoint 5\u0027)\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Phase 4 — Synthesis \u0026 Scaled Outreach\n", "\n", "Pair the Sonnet 4.6 executor with the Opus 4.7 advisor inside one batch request. Use `output-300k-2026-03-24` for book-length intelligence reports, and constrain the final output to a JSON schema with nullable fields so missing data comes back as `null` instead of an invented placeholder." ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Checkpoint 6\n", "\n", "Implement this step yourself. Use the preceding explanation and the module page as your guide, then compare your approach with the answer key after you have a working version.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# TODO: Implement checkpoint 6 for Module 11.\n", "# Keep the cell focused, run it, inspect the output, then move to the next checkpoint.\n", "\n", "raise NotImplementedError(\u0027Complete checkpoint 6\u0027)\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Checkpoint 7\n", "\n", "Implement this step yourself. Use the preceding explanation and the module page as your guide, then compare your approach with the answer key after you have a working version.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# TODO: Implement checkpoint 7 for Module 11.\n", "# Keep the cell focused, run it, inspect the output, then move to the next checkpoint.\n", "\n", "raise NotImplementedError(\u0027Complete checkpoint 7\u0027)\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Phase 5 — Production Reliability \u0026 Context Hygiene\n", "\n", "Server-side compaction at 50k tokens, with explicit instructions to preserve case facts verbatim. Place a `cache_control` breakpoint at the end of the system prompt so the prompt cache survives compaction.\n", "\n", "After the call, re-count tokens to verify the effective context size shrank as expected." ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Checkpoint 8\n", "\n", "Implement this step yourself. Use the preceding explanation and the module page as your guide, then compare your approach with the answer key after you have a working version.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# TODO: Implement checkpoint 8 for Module 11.\n", "# Keep the cell focused, run it, inspect the output, then move to the next checkpoint.\n", "\n", "raise NotImplementedError(\u0027Complete checkpoint 8\u0027)\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Checkpoint 9\n", "\n", "Implement this step yourself. Use the preceding explanation and the module page as your guide, then compare your approach with the answer key after you have a working version.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# TODO: Implement checkpoint 9 for Module 11.\n", "# Keep the cell focused, run it, inspect the output, then move to the next checkpoint.\n", "\n", "raise NotImplementedError(\u0027Complete checkpoint 9\u0027)\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Deterministic safety: PreToolUse hook\n", "\n", "Block any `process_outreach` call until the prospect\u0027s `risk_score` has been verified. This is config the Claude Code harness reads, not a runtime API call." ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Checkpoint 10\n", "\n", "Implement this step yourself. Use the preceding explanation and the module page as your guide, then compare your approach with the answer key after you have a working version.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# TODO: Implement checkpoint 10 for Module 11.\n", "# Keep the cell focused, run it, inspect the output, then move to the next checkpoint.\n", "\n", "raise NotImplementedError(\u0027Complete checkpoint 10\u0027)\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Phase 6 — Claude Code \u0026 Repository Governance\n", "\n", "Two artifacts go into the repo so every developer (and Claude itself) follows the same standards: a path-scoped rule for outreach files, and a forked-context audit skill." ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Checkpoint 11\n", "\n", "Implement this step yourself. Use the preceding explanation and the module page as your guide, then compare your approach with the answer key after you have a working version.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# TODO: Implement checkpoint 11 for Module 11.\n", "# Keep the cell focused, run it, inspect the output, then move to the next checkpoint.\n", "\n", "raise NotImplementedError(\u0027Complete checkpoint 11\u0027)\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "---\n", "\n", "## Final Audit Checklist\n", "\n", "- **ZDR check:** adaptive thinking, citations, structured outputs, and standard web search are ZDR-eligible. Message Batches and the MCP Connector are **not** — batch results sit server-side for 29 days.\n", "- **Cost check:** `inference_geo: \"us\"` adds a 1.1× multiplier on Opus 4.6+ (input, output, and cache); same multiplier hits Priority-Tier burndown.\n", "- **Token management:** call `client.messages.count_tokens` on the next outgoing payload after compaction fires to verify the effective context size shrank.\n", "- **Citations vs. structured outputs:** mutually exclusive. Sending both returns a 400.\n", "- **Subagents:** isolated context by default — the Coordinator must explicitly forward only the data each subagent needs." ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Reflection\n", "\n", "Before opening the answer key, write down what worked, what failed, and which API behavior or agent-design rule you would rely on in production.\n" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "name": "python", "version": "3.9" } }, "nbformat": 4, "nbformat_minor": 5 }