update agent sample

Author: mattgotteiner

agentic-retrieval-pipeline-example/agent-example.ipynb

@@ -116,15 +116,16 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 1,
    "id": "e42b4a10",
    "metadata": {},
    "outputs": [],
    "source": [
-    "from dotenv import load_dotenv\n",
+    "import os\n",
+    "\n",
     "from azure.identity import DefaultAzureCredential\n",
     "from azure.mgmt.core.tools import parse_resource_id\n",
-    "import os\n",
+    "from dotenv import load_dotenv\n",
     "\n",
     "load_dotenv(override=True) # take environment variables from .env.\n",
     "\n",
@@ -164,7 +165,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 2,
    "id": "91fd6810",
    "metadata": {},
    "outputs": [
@@ -177,8 +178,13 @@
     }
    ],
    "source": [
-    "from azure.search.documents.indexes.models import SearchIndex, SearchField, VectorSearch, VectorSearchProfile, HnswAlgorithmConfiguration, AzureOpenAIVectorizer, AzureOpenAIVectorizerParameters, SemanticSearch, SemanticConfiguration, SemanticPrioritizedFields, SemanticField\n",
     "from azure.search.documents.indexes import SearchIndexClient\n",
+    "from azure.search.documents.indexes.models import (\n",
+    "    AzureOpenAIVectorizer, AzureOpenAIVectorizerParameters,\n",
+    "    HnswAlgorithmConfiguration, SearchField, SearchIndex,\n",
+    "    SemanticConfiguration, SemanticField, SemanticPrioritizedFields,\n",
+    "    SemanticSearch, VectorSearch, VectorSearchProfile\n",
+    ")\n",
     "\n",
     "index = SearchIndex(\n",
     "    name=index_name,\n",
@@ -234,7 +240,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 3,
    "id": "f98f31e7",
    "metadata": {},
    "outputs": [
@@ -284,8 +290,11 @@
     }
    ],
    "source": [
-    "from azure.search.documents.indexes.models import SearchIndexKnowledgeSource, SearchIndexKnowledgeSourceParameters, SearchIndexFieldReference\n",
     "from azure.search.documents.indexes import SearchIndexClient\n",
+    "from azure.search.documents.indexes.models import (\n",
+    "    SearchIndexFieldReference, SearchIndexKnowledgeSource,\n",
+    "    SearchIndexKnowledgeSourceParameters\n",
+    ")\n",
     "\n",
     "ks = SearchIndexKnowledgeSource(\n",
     "    name=knowledge_source_name,\n",
@@ -310,7 +319,7 @@
     "\n",
     "This step creates a knowledge base, which acts as a wrapper for your knowledge source and LLM deployment.\n",
     "\n",
-    "`EXTRACTIVE_DATA` is the default modality and returns content from your knowledge sources without generative alteration. This is recommended for interaction with Foundry Agent Service"
+    "`EXTRACTIVE_DATA` is the default modality and returns content from your knowledge sources without answer generation. This is recommended for interaction with Foundry Agent Service."
    ]
   },
   {
@@ -328,8 +337,11 @@
     }
    ],
    "source": [
-    "from azure.search.documents.indexes.models import KnowledgeBase, KnowledgeSourceReference, AzureOpenAIVectorizerParameters, KnowledgeRetrievalOutputMode, KnowledgeRetrievalMinimalReasoningEffort\n",
     "from azure.search.documents.indexes import SearchIndexClient\n",
+    "from azure.search.documents.indexes.models import (\n",
+    "    KnowledgeBase, KnowledgeRetrievalMinimalReasoningEffort,\n",
+    "    KnowledgeRetrievalOutputMode, KnowledgeSourceReference\n",
+    ")\n",
     "\n",
     "knowledge_base = KnowledgeBase(\n",
     "    name=base_name,\n",
@@ -357,7 +369,9 @@
    "source": [
     "## Create an agent\n",
     "\n",
-    "In Foundry Agent Service, an agent is a smart micro-service that can do RAG. The purpose of this agent is to decide when to send a query to the agentic retrieval pipeline."
+    "In Foundry Agent Service, an agent is an smart micro-service that can use an LLM with tools. The purpose of this agent is to use retrieval tools from the knowledge base to do RAG.\n",
+    "\n",
+    "Your Foundry project may have no agents at this stage, but if you've already run this notebook, you will see the agent listed here."
    ]
   },
   {
@@ -399,8 +413,6 @@
     }
    ],
    "source": [
-    "from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient\n",
-    "from azure.mgmt.cognitiveservices.models import ConnectionPropertiesV2BasicResource, CustomKeysConnectionProperties, CustomKeys\n",
     "import requests\n",
     "from azure.identity import get_bearer_token_provider\n",
     "\n",
@@ -429,9 +441,27 @@
     "print(f\"Connection '{project_connection_name}' created or updated successfully.\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "6631324e",
+   "metadata": {},
+   "source": [
+    "## Optimize agent instructions for knowledge retrieval\n",
+    "\n",
+    "To maximize the accuracy of knowledge base invocations and ensure proper citation formatting, use optimized agent instructions. Based on our experiments, we recommend the following instruction template as a starting point:\n",
+    "\n",
+    "```\n",
+    "You are a helpful assistant that must use the knowledge base to answer all the questions from user. You must never answer from your own knowledge under any circumstances.\n",
+    "Every answer must always provide annotations for using the MCP knowledge base tool and render them as: `【message_idx:search_idx†source_name】`\n",
+    "If you cannot find the answer in the provided knowledge base you must respond with \"I don't know\".\n",
+    "```\n",
+    "\n",
+    "The specified citation format ensures the agent includes provenance information in responses, making it clear which knowledge sources were used."
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": null,
    "id": "aa363122",
    "metadata": {},
    "outputs": [
@@ -447,9 +477,9 @@
     "from azure.ai.projects.models import PromptAgentDefinition, MCPTool\n",
     "\n",
     "instructions = \"\"\"\n",
-    "A Q&A agent that can answer questions about the Earth at night.\n",
-    "Always provide references to the ID of the data source used to answer the question.\n",
-    "If you do not have the answer, respond with \"I don't know\".\n",
+    "You are a helpful assistant that must use the knowledge base to answer all the questions from user. You must never answer from your own knowledge under any circumstances.\n",
+    "Every answer must always provide annotations for using the MCP knowledge base tool and render them as: `【message_idx:search_idx†source_name】`\n",
+    "If you cannot find the answer in the provided knowledge base you must respond with \"I don't know\".\n",
     "\"\"\"\n",
     "mcp_kb_tool = MCPTool(\n",
     "    server_label=\"knowledge-base\",\n",
@@ -476,7 +506,9 @@
    "id": "16a2d5ed",
    "metadata": {},
    "source": [
-    "## Start a chat with the agent"
+    "## Start a chat with the agent\n",
+    "\n",
+    "Set the `tool_choice` parameter to \"required\" to ensure the knowledge base tool is consistently used"
    ]
   },
   {
@@ -489,21 +521,36 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Response: The larger December brightening observed in suburban belts compared to urban cores, despite higher absolute light levels downtown, is primarily because suburban areas have more yard space and a prevalence of single-family homes where holiday light displays are more common and prominent. Urban cores do experience brightening during the holidays, but suburban areas show greater increases in lighting intensity due to more extensive holiday light decorations in residential yards and neighborhoods [source 4:4, page 176].\n",
+      "Response: Here are evidence-based explanations to your questions:\n",
+      "\n",
+      "---\n",
+      "\n",
+      "**1. Why do suburban belts display larger December brightening than urban cores, even though absolute light levels are higher downtown?**\n",
+      "\n",
+      "- Suburban belts show a *larger percentage increase* in night brightness during December compared to urban cores, largely because suburban residential areas feature more single-family homes and larger yards, which are typically decorated with holiday lights. These areas start from a lower baseline (less bright overall at night compared to dense urban centers), so the relative change (brightening) is much more noticeable.\n",
+      "\n",
+      "- In contrast, the downtown core is already very bright at night due to dense commercial lighting and streetlights. While it also sees a December increase (often 20–30% brighter), the *absolute* change is less striking because it begins at a much higher base of illumination.\n",
       "\n",
-      "Regarding the sharp visibility of Phoenix's nighttime street grid from space, the Phoenix metropolitan area is laid out along a regular grid of city blocks and streets, which is clearly visible at night due to street lighting. The sharp street grid pattern is emphasized by the extensive street lighting that traces the grid, and the presence of brightly lit transportation corridors (like Grand Avenue) and nodes such as shopping centers and gas stations at street intersections. Additionally, Phoenix's urban spread includes many suburban municipalities linked by well-illuminated surface streets and freeways, enhancing the visibility of the grid pattern from space [source 4:0 and 4:1, pages 104-105].\n",
+      "- This pattern is observed across U.S. cities, with the phenomenon driven by widespread cultural practices and the suburban landscape’s suitability for holiday lighting displays. The effect is visible in satellite data and was quantified at 20–50% brighter in December, especially in suburbs and city outskirts.\n",
       "\n",
-      "In contrast, large stretches of interstate highways between Midwestern cities are comparatively dim at night because these transportation corridors often do not have extensive street-level lighting along the highways themselves, as lighting is typically limited to city areas and major intersections. While the interstates are well-traveled, fewer lights are installed directly on these long stretches of highway, making them less visible from space in nighttime imagery [source 4:3, page 124].\n",
+      "---\n",
       "\n",
-      "Summary:\n",
-      "- Suburban December brightening larger due to more holiday yard lighting in single-family homes and yards.\n",
-      "- Phoenix’s nighttime grid visibility is due to its regular urban street grid with comprehensive street lighting and connected suburban municipalities with illuminated streets.\n",
-      "- Midwest interstate highways are dimmer because highways themselves are less illuminated between cities.\n",
+      "**2. Why is the Phoenix nighttime street grid so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?**\n",
       "\n",
-      "References:  \n",
-      "- Source 4:4 (page 176) for December brightening in suburban vs urban areas.  \n",
-      "- Sources 4:0 and 4:1 (pages 104-105) for Phoenix nighttime grid visibility.  \n",
-      "- Source 4:3 (page 124) for dimmer interstate stretches between Midwestern cities.\n"
+      "- Phoenix’s sharply visible nighttime street grid from space is a result of its urban layout: the city (like many western U.S. cities) was developed using a regular grid system, with extensive and uniform street lighting and strong urban sprawl. The grid pattern, and the dense network of intersecting surface streets, is brightly illuminated, particularly at intersections, commercial areas, and major thoroughfares.\n",
+      "\n",
+      "- The interstate highways between midwestern cities, though significant in length and crucial to national infrastructure, traverse sparsely populated rural areas. These stretches typically have very little artificial lighting (due to low traffic volumes at night and cost considerations), making them much less visible in nighttime satellite imagery. Only nodes (cities and towns) along the route show as bright \"pearls\" in the darkness, while the \"strings\" (highways) connecting them remain faint or invisible.\n",
+      "\n",
+      "- In summary:\n",
+      "  - Urban areas like Phoenix stand out with strong, connected patterns of light due to dense development and extensive lighting.\n",
+      "  - Rural interstates are sparsely lit, and only their endpoints—cities and large towns—generate notable light visible from space.\n",
+      "\n",
+      "---\n",
+      "\n",
+      "**References**:\n",
+      "- [Holiday Lights increase most dramatically in suburbs, not downtowns: earth_at_night_508_page_176_verbalized, page 160](4:5)\n",
+      "- [Lighting paths and urban grids are visible from space, while rural highways remain dim: earth_at_night_508_page_124_verbalized, page 108](4:3)\n",
+      "- [Phoenix’s grid and surrounding urban structure: earth_at_night_508_page_104_verbalized, page 88](4:1)\n"
      ]
     }
    ],
@@ -516,6 +563,7 @@
     "# Send initial request that will trigger the MCP tool\n",
     "response = openai_client.responses.create(\n",
     "    conversation=conversation.id,\n",
+    "    tool_choice=\"required\",\n",
     "    input=\"\"\"\n",
     "        Why do suburban belts display larger December brightening than urban cores even though absolute light levels are higher downtown?\n",
     "        Why is the Phoenix nighttime street grid is so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?\n",
@@ -526,6 +574,26 @@
     "print(f\"Response: {response.output_text}\")\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "39c02785",
+   "metadata": {},
+   "source": [
+    "## Inspect the response\n",
+    "\n",
+    "The underlying response from the agent contains metadata about what queries the agent sent to the knowledge base and what citations were found"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b845d2ae",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "response.to_dict()"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "3b328340",
@@ -538,7 +606,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 11,
    "id": "3711252f",
    "metadata": {},
    "outputs": [
@@ -615,15 +683,15 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 12,
    "id": "409befbb",
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "AI agent 'earth-knowledge-agent' version '4' deleted successfully\n"
+      "AI agent 'earth-knowledge-agent' version '7' deleted successfully\n"
      ]
     }
    ],
@@ -642,7 +710,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 13,
    "id": "d67f8609",
    "metadata": {},
    "outputs": [
@@ -669,7 +737,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": 14,
    "id": "e35a6eb0",
    "metadata": {},
    "outputs": [
@@ -696,7 +764,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": 15,
    "id": "d9895f27",
    "metadata": {},
    "outputs": [
@@ -716,7 +784,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": ".venv (3.12.10)",
+   "display_name": ".venv",
    "language": "python",
    "name": "python3"
   },

agentic-retrieval-pipeline-example/requirements.txt

@@ -4,4 +4,5 @@ azure-identity
 ipykernel
 dotenv
 azure-search-documents==11.7.0b2
-requests
+requests
+openai

agentic-retrieval-pipeline-example/sample.env

@@ -1,6 +1,7 @@
 PROJECT_ENDPOINT=https://your-foundry-resource.services.ai.azure.com/api/projects/your-foundry-project
+AGENT_MODEL=gpt-4.1-mini
 PROJECT_RESOURCE_ID=/subscriptions/your-subscription-id/resourceGroups/your-resource-group/providers/Microsoft.CognitiveServices/accounts/your-account/projects/your-project
 AZURE_OPENAI_ENDPOINT=https://your-openai-service.openai.azure.com
 AZURE_OPENAI_GPT_DEPLOYMENT=gpt-5-mini
 AZURE_SEARCH_ENDPOINT=https://your-search-service.search.windows.net
-AZURE_SEARCH_INDEX_NAME=earth_at_night
+AZURE_SEARCH_INDEX_NAME=earth-at-night