Clarify notebook walkthrough steps

Author: nagkumar91

lab/5-Observability/1-OpenAIAgents/weekend_planner.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "# Weekend Planner with OpenAI Agents Telemetry\n",
     "\n",
-    "Capture GenAI-compliant spans while orchestrating an OpenAI Agents workflow. This notebook mirrors the sample script but keeps everything inline so you can tweak the code and immediately inspect telemetry." 
+    "Capture GenAI-compliant spans while orchestrating an OpenAI Agents workflow. This notebook mirrors the sample script but keeps everything inline so you can tweak the code and immediately inspect telemetry."
    ]
   },
   {
@@ -23,7 +23,15 @@
     "pip install azure-monitor-opentelemetry-exporter\n",
     "```\n",
     "\n",
-    "Set environment variables for your model provider (`API_HOST=github` by default) and, if needed, `APPLICATION_INSIGHTS_CONNECTION_STRING`." 
+    "Set environment variables for your model provider (`API_HOST=github` by default) and, if needed, `APPLICATION_INSIGHTS_CONNECTION_STRING`."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Step 1: Import dependencies and configure logging\n",
+    "Load the OpenAI Agents SDK, OpenTelemetry helpers, and supporting utilities. This cell also reads your `.env` file and enables rich logging so you can watch the agent run.\n"
    ]
   },
   {
@@ -67,6 +75,14 @@
     "LOGGER.setLevel(logging.INFO)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Step 2: Define helpers for capture configuration\n",
+    "These utilities resolve the API host, set the GenAI capture environment variables, and prepare the tracer provider used throughout the notebook.\n"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -160,6 +176,14 @@
     "    trace.set_tracer_provider(provider)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Step 3: Initialise OpenTelemetry instrumentation\n",
+    "Run this cell after updating your environment variables to wire up the tracer provider and the OpenAI Agents instrumentor.\n"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -176,6 +200,14 @@
     "print(\"Instrumentation ready for provider:\", API_CONFIG.provider)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Step 4: Register agent tools and construct the agent\n",
+    "With instrumentation active, declare the reusable tools and build the Weekend Planner agent that the notebook will invoke.\n"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -225,8 +257,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Run the agent\n",
-    "Execute the final cell to orchestrate a single planning session. Spans will be emitted to the configured exporter (console or Azure Monitor)." 
+    "### Step 5: Run the agent\n",
+    "Execute the final cell to orchestrate a single planning session. Watch the console (or Application Insights) for `create_agent`, `invoke_agent`, and `execute_tool` spans emitted by the instrumentation.\n"
    ]
   },
   {
@@ -273,4 +305,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

lab/5-Observability/2-LangChain/weekend_planner.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "# LangChain Weekend Planner with Azure AI Telemetry\n",
     "\n",
-    "Instrument a LangChain v1 agent so each invocation emits GenAI-compliant spans via `langchain-azure-ai`." 
+    "Instrument a LangChain v1 agent so each invocation emits GenAI-compliant spans via `langchain-azure-ai`."
    ]
   },
   {
@@ -21,7 +21,15 @@
     "pip install azure-identity  # required when API_HOST=azure\n",
     "```\n",
     "\n",
-    "Configure environment variables for your model provider (GitHub Models by default) and optionally `APPLICATION_INSIGHTS_CONNECTION_STRING` to export to Azure Monitor." 
+    "Configure environment variables for your model provider (GitHub Models by default) and optionally `APPLICATION_INSIGHTS_CONNECTION_STRING` to export to Azure Monitor."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Step 1: Import dependencies and tracer helpers\n",
+    "Load LangChain, the Azure tracer callback, and supporting utilities while configuring logging and environment handling.\n"
    ]
   },
   {
@@ -54,6 +62,14 @@
     "LOGGER.setLevel(logging.INFO)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Step 2: Configure the chat model and tracer\n",
+    "This cell selects GitHub Models or Azure OpenAI based on environment variables and prepares the Azure OpenTelemetry tracer.\n"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -95,6 +111,14 @@
     "print(\"Model configured:\", MODEL.model_name if hasattr(MODEL, \"model_name\") else \"custom\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Step 3: Define tools and initialise the agent\n",
+    "Create the weather, activities, and date tools, then assemble the agent so each invocation can emit GenAI spans.\n"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -147,8 +171,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Invoke the agent\n",
-    "Use the LangChain tracer callback to record `invoke_agent` and tool spans for each request." 
+    "### Step 4: Invoke the agent\n",
+    "Call the agent with the Azure tracer in the config to emit `invoke_agent` and tool spans. Inspect the notebook output and your telemetry backend before iterating further.\n"
    ]
   },
   {
@@ -179,4 +203,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

lab/5-Observability/3-LangGraph/music_router.ipynb

@@ -24,6 +24,14 @@
     "Set `API_HOST` to `github` (default) or `azure`, provide the corresponding credentials, and optionally `APPLICATION_INSIGHTS_CONNECTION_STRING` for Azure Monitor export."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Step 1: Import LangGraph, LangChain, and telemetry helpers\n",
+    "Bring in the required libraries and load environment variables for your chosen provider.\n"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -48,6 +56,14 @@
     "load_dotenv(override=True)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Step 2: Configure the chat model and tracer\n",
+    "Initialise the chat client (GitHub Models or Azure OpenAI) and the Azure AI tracer so spans are emitted for every model call.\n"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -89,6 +105,14 @@
     "print(\"Model ready:\", MODEL.model_name if hasattr(MODEL, \"model_name\") else \"custom\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Step 3: Declare tools and bind them to the model\n",
+    "Define the music playback tools and bind them to the chat model so LangGraph can leverage them during execution.\n"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -114,6 +138,14 @@
     "MODEL_WITH_TOOLS = MODEL.bind_tools(TOOLS, parallel_tool_calls=False)\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Step 4: Build the LangGraph workflow\n",
+    "Create the agent and tool nodes, wire up conditional edges, and compile the workflow with an in-memory checkpointer.\n"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -148,8 +180,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Stream an interaction\n",
-    "Runs the graph with telemetry enabled. Each step sends spans through the Azure tracer."
+    "### Step 5: Stream an interaction\n",
+    "Execute the graph with the tracer callback to observe emitted spans for the model and tool steps in real time.\n"
    ]
   },
   {