{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Module 1 — Foundations of Claude Orchestration\n",
    "\n",
    "Two ways to interact with Claude: the **Messages API** for direct, granular control and **Managed Agents** for reusable, versioned configurations. The agentic loop pattern (`stop_reason`) governs every multi-turn workflow.\n",
    "\n",
    "> **Prerequisite:** finish `Module0_Complete.ipynb` first so VS Code, `.venv`, and `ANTHROPIC_API_KEY` are wired up."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup\n",
    "\n",
    "Load the key from `.env` and instantiate one client for the rest of the notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import anthropic\n",
    "from dotenv import load_dotenv\n",
    "\n",
    "load_dotenv()\n",
    "client = anthropic.Anthropic()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Messages API — local message history\n",
    "\n",
    "The Claude API is **stateless**. To build a conversation, maintain a local `messages` list and re-send the full history with every request. The cell below opens the conversation, appends the assistant's reply, then queues a follow-up turn."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "messages = [\n    {\"role\": \"user\", \"content\": \"Analyze the target audience for an AI consulting firm.\"}\n]\n\n# Adaptive thinking is required for Opus 4.7 (replaces budget_tokens)\nresponse = client.messages.create(\n    model=\"claude-opus-4-7\",\n    max_tokens=4096,\n    thinking={\"type\": \"adaptive\"},\n    inference_geo=\"us\",       # 1.1x pricing, ZDR-eligible\n    messages=messages,\n)\n\nmessages.append({\"role\": \"assistant\", \"content\": response.content})\nmessages.append({\"role\": \"user\", \"content\": \"Now, generate three LinkedIn post ideas for this audience.\"})\n\nprint(\"stop_reason:\", response.stop_reason)\nprint(\"messages so far:\", len(messages))"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Managed Agent — reusable configuration\n",
    "\n",
    "A Managed Agent bundles model, persona, and tools into a single ID with a version, so every caller hits the same configuration without re-specifying it. Use this pattern for production workflows where you want the persona and tool list to be reviewable and reusable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "agent = client.beta.agents.create(\n",
    "    name=\"Marketing Strategist\",\n",
    "    model=\"claude-opus-4-7\",\n",
    "    description=\"Specializes in high-value lead generation and content strategy.\",\n",
    "    system=\"You are an expert Marketing Strategist. Use thinking to ensure your plans are data-driven.\",\n",
    "    tools=[\n",
    "        {\n",
    "            \"type\": \"agent_toolset_20260401\",\n",
    "            \"configs\": [\n",
    "                {\"name\": \"web_search\", \"enabled\": True, \"permission_policy\": {\"type\": \"always_allow\"}},\n",
    "                {\"name\": \"web_fetch\",  \"enabled\": True, \"permission_policy\": {\"type\": \"always_allow\"}},\n",
    "            ],\n",
    "        }\n",
    "    ],\n",
    ")\n",
    "\n",
    "print(f\"Agent Created: {agent.id} (Version: {agent.version})\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. The agentic loop — `stop_reason`\n",
    "\n",
    "Always drive your loop from the structured `stop_reason`, never from natural-language hints in the assistant's text. The two values that matter most:\n",
    "\n",
    "- `tool_use` → execute the tool and send the result back; loop continues.\n",
    "- `end_turn` → task complete; exit the loop."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if response.stop_reason == \"tool_use\":\n",
    "    print(\"Continue: dispatch tool, append tool_result, re-call client.messages.create.\")\n",
    "elif response.stop_reason == \"end_turn\":\n",
    "    print(\"Done: Claude finished naturally.\")\n",
    "else:\n",
    "    print(f\"Unexpected stop_reason: {response.stop_reason}\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}