updates

Author: mattgotteiner

Quickstart-Agentic-Retrieval/quickstart.ipynb

@@ -235,16 +235,15 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 7,
    "id": "918ded26",
    "metadata": {},
    "outputs": [],
    "source": [
     "from azure.search.documents.agent import KnowledgeAgentRetrievalClient\n",
     "from azure.search.documents.agent.models import KnowledgeAgentRetrievalRequest, KnowledgeAgentMessage, KnowledgeAgentMessageTextContent, KnowledgeAgentIndexParams\n",
-    "import azure.search.documents._utils\n",
     "\n",
-    "agent_client = KnowledgeAgentRetrievalClient(endpoint=endpoint, agent_name=agent_name, authentication_policy=azure.search.documents._utils.get_authentication_policy(credential))\n",
+    "agent_client = KnowledgeAgentRetrievalClient(endpoint=endpoint, agent_name=agent_name, credential=credential)\n",
     "\n",
     "messages.append({\n",
     "    \"role\": \"user\",\n",
@@ -276,7 +275,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 8,
    "id": "d4d78fbe",
    "metadata": {},
    "outputs": [
@@ -334,7 +333,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 9,
    "id": "7fccf4b0",
    "metadata": {},
    "outputs": [
@@ -348,7 +347,7 @@
       "    \"id\": 0,\n",
       "    \"type\": \"ModelQueryPlanning\",\n",
       "    \"input_tokens\": 1407,\n",
-      "    \"output_tokens\": 318\n",
+      "    \"output_tokens\": 311\n",
       "  },\n",
       "  {\n",
       "    \"id\": 1,\n",
@@ -357,8 +356,8 @@
       "    \"query\": {\n",
       "      \"search\": \"suburban belts December brightening urban cores light levels\"\n",
       "    },\n",
-      "    \"query_time\": \"2025-05-02T04:50:56.846Z\",\n",
-      "    \"elapsed_ms\": 611\n",
+      "    \"query_time\": \"2025-05-06T15:43:41.162Z\",\n",
+      "    \"elapsed_ms\": 714\n",
       "  },\n",
       "  {\n",
       "    \"id\": 2,\n",
@@ -367,9 +366,9 @@
       "    \"query\": {\n",
       "      \"search\": \"Phoenix nighttime street grid visibility from space\"\n",
       "    },\n",
-      "    \"query_time\": \"2025-05-02T04:50:57.331Z\",\n",
+      "    \"query_time\": \"2025-05-06T15:43:41.683Z\",\n",
       "    \"count\": 2,\n",
-      "    \"elapsed_ms\": 485\n",
+      "    \"elapsed_ms\": 520\n",
       "  }\n",
       "]\n",
       "Results\n",
@@ -408,7 +407,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 10,
    "id": "da260539",
    "metadata": {},
    "outputs": [],
@@ -434,25 +433,24 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 11,
    "id": "b2dea5c2",
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Suburban belts display larger December brightening than urban cores because seasonal lighting, such\n",
-      "as holiday decorations, tends to be more prevalent in residential areas where individual homes often\n",
-      "contribute significantly to increased brightness. In contrast, urban cores, while having higher\n",
-      "absolute light levels, don't experience as much variability due to the consistent presence of\n",
-      "streetlights, commercial lighting, and less individual contribution to seasonal displays [ref_id:0].\n",
-      "The Phoenix nighttime street grid is sharply visible from space because it is laid out in a regular\n",
-      "grid of city blocks and streets, typical of western U.S. cities. This lighting pattern is evident\n",
-      "from the low-Earth-orbit vantage point and highlights the extensive spread of urbanization. In\n",
-      "contrast, large stretches of interstate between midwestern cities remain comparatively dim as these\n",
-      "areas primarily consist of long, undeveloped stretches without urban lighting patterns, typical of\n",
-      "agricultural or undeveloped land [ref_id:1].\n"
+      "Suburban belts tend to display larger December brightening compared to urban cores even though the\n",
+      "absolute light levels are higher downtown because suburban areas often have more residential\n",
+      "Christmas lighting during the holiday season. In contrast, urban cores have more constant commercial\n",
+      "lighting throughout the year, which changes less dramatically in December [Source 0].  The Phoenix\n",
+      "nighttime street grid is sharply visible from space because the city's urban layout follows a\n",
+      "regular grid pattern typical of many Western U.S. cities. This grid pattern, along with the street\n",
+      "lighting, becomes distinctly visible from space. In contrast, large stretches of interstate between\n",
+      "Midwestern cities are dimmer due to lower population density and reduced road lighting, as they pass\n",
+      "through more rural areas without the extensive grid-like street lighting found in metropolitan areas\n",
+      "like Phoenix [Source 1].\n"
      ]
     }
    ],
@@ -476,25 +474,24 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 12,
    "id": "9126b4ce",
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Suburban belts display larger December brightening compared to urban cores even though absolute\n",
-      "light levels are higher downtown due to the widespread use of decorative lighting during the holiday\n",
-      "season. Suburban areas tend to have more residential properties where festive lighting is commonly\n",
-      "used, contributing to this phenomenon. Additionally, suburban development often spreads outward,\n",
-      "leading to a more extensive area where lighting may be present compared to the concentrated urban\n",
-      "cores {ref_id: 0}.  Regarding Phoenix's sharply visible nighttime street grid from space, Phoenix\n",
-      "and many cities in the western United States feature a regular grid layout of city blocks and\n",
-      "streets. This grid is particularly evident at night because street lighting creates a clear and\n",
-      "sharp pattern visible from space. In contrast, the interstate between midwestern cities may appear\n",
-      "dimmer because these areas generally have less consistent lighting and lower population density,\n",
-      "causing stretches of roadway to be less illuminated {ref_id: 1}.\n"
+      "Suburban areas often display larger December brightening compared to urban cores because of\n",
+      "widespread decorative lighting practices during the holiday season in residential neighborhoods,\n",
+      "whereas urban cores, despite having higher absolute light levels, may not experience as pronounced\n",
+      "increases due to the density and type of lighting already present there [ref_id: 1].  The reason the\n",
+      "Phoenix nighttime street grid is so sharply visible from space is due to its regular grid layout of\n",
+      "city blocks and streets, which highlight street lighting patterns. This structure, common to many\n",
+      "central and western U.S. cities, facilitates easy visibility from space, making individual lights\n",
+      "and intersections conspicuous. This contrasts with large stretches of interstate between midwestern\n",
+      "cities, which often remain dim due to fewer intersections or less dense lighting along rural or\n",
+      "undeveloped areas [ref_id: 0].\n"
      ]
     }
    ],
@@ -518,7 +515,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 13,
    "id": "7034e480",
    "metadata": {},
    "outputs": [],
@@ -550,7 +547,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": 14,
    "id": "35a1bfcb",
    "metadata": {},
    "outputs": [
@@ -693,7 +690,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": 15,
    "id": "6f74c2c3",
    "metadata": {},
    "outputs": [
@@ -707,7 +704,7 @@
       "    \"id\": 0,\n",
       "    \"type\": \"ModelQueryPlanning\",\n",
       "    \"input_tokens\": 2283,\n",
-      "    \"output_tokens\": 110\n",
+      "    \"output_tokens\": 207\n",
       "  },\n",
       "  {\n",
       "    \"id\": 1,\n",
@@ -716,9 +713,19 @@
       "    \"query\": {\n",
       "      \"search\": \"how to locate lava flows at night\"\n",
       "    },\n",
-      "    \"query_time\": \"2025-05-02T04:51:05.929Z\",\n",
+      "    \"query_time\": \"2025-05-06T15:44:00.218Z\",\n",
       "    \"count\": 6,\n",
-      "    \"elapsed_ms\": 346\n",
+      "    \"elapsed_ms\": 497\n",
+      "  },\n",
+      "  {\n",
+      "    \"id\": 2,\n",
+      "    \"type\": \"AzureSearchQuery\",\n",
+      "    \"target_index\": \"earth_at_night\",\n",
+      "    \"query\": {\n",
+      "      \"search\": \"best practices for observing lava at night\"\n",
+      "    },\n",
+      "    \"query_time\": \"2025-05-06T15:44:00.571Z\",\n",
+      "    \"elapsed_ms\": 352\n",
       "  }\n",
       "]\n",
       "Results\n",

Quickstart-Agentic-Retrieval/requirements.txt

@@ -1,7 +1,9 @@
-azure-search-documents==11.6.0b11
 azure-identity
 openai
 aiohttp
 ipykernel
 dotenv
-requests
+requests
+
+--extra-index-url https://pkgs.dev.azure.com/azure-sdk/public/_packaging/azure-sdk-for-python/pypi/simple/
+azure-search-documents==11.6.0a20250505003

agent-example/agent-example.ipynb

@@ -159,35 +159,37 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": null,
    "id": "fbe31e32",
    "metadata": {},
    "outputs": [],
    "source": [
-    "import requests\n",
     "\n",
-    "create_agent_request = {\n",
-    "    \"name\": agent_name,\n",
-    "    \"targetIndexes\": [ { \"indexName\": index_name } ],\n",
-    "    \"models\": [\n",
-    "          {\n",
-    "            \"kind\": \"azureOpenAI\",\n",
-    "            \"azureOpenAIParameters\": {\n",
-    "                \"resourceUri\": azure_openai_endpoint,\n",
-    "                \"apiKey\": None,\n",
-    "                \"deploymentId\": azure_openai_gpt_model,\n",
-    "                \"modelName\": azure_openai_gpt_model\n",
-    "            }\n",
-    "        }\n",
-    "    ]\n",
-    "}\n",
+    "from azure.search.documents.indexes.models import KnowledgeAgent, KnowledgeAgentAzureOpenAIModel, KnowledgeAgentTargetIndex, KnowledgeAgentRequestLimits, AzureOpenAIVectorizerParameters\n",
+    "from azure.search.documents.indexes import SearchIndexClient\n",
     "\n",
-    "response = requests.put(\n",
-    "    url=f\"{endpoint}/agents/{agent_name}?api-version={api_version}\",\n",
-    "    headers={ \"Authorization\": f\"Bearer {token_provider()}\" },\n",
-    "    json=create_agent_request\n",
+    "agent = KnowledgeAgent(\n",
+    "    name=agent_name,\n",
+    "    models=[\n",
+    "        KnowledgeAgentAzureOpenAIModel(\n",
+    "            azure_open_ai_parameters=AzureOpenAIVectorizerParameters(\n",
+    "                resource_url=azure_openai_endpoint,\n",
+    "                deployment_name=azure_openai_gpt_deployment,\n",
+    "                model_name=azure_openai_gpt_model\n",
+    "            )\n",
+    "        )\n",
+    "    ],\n",
+    "    target_indexes=[\n",
+    "        KnowledgeAgentTargetIndex(\n",
+    "            index_name=index_name,\n",
+    "            default_reranker_threshold=2.5\n",
+    "        )\n",
+    "    ],\n",
     ")\n",
-    "response.raise_for_status()\n"
+    "\n",
+    "index_client = SearchIndexClient(endpoint=endpoint, credential=credential)\n",
+    "index_client.create_or_update_agent(agent)\n",
+    "print(f\"Knowledge agent '{agent_name}' created or updated successfully\")"
    ]
   },
   {
@@ -254,13 +256,18 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": null,
    "id": "de2ee775",
    "metadata": {},
    "outputs": [],
    "source": [
     "from azure.ai.projects.models import FunctionTool, ToolSet, ListSortOrder\n",
     "\n",
+    "from azure.search.documents.agent import KnowledgeAgentRetrievalClient\n",
+    "from azure.search.documents.agent.models import KnowledgeAgentRetrievalRequest, KnowledgeAgentMessage, KnowledgeAgentMessageTextContent, KnowledgeAgentIndexParams\n",
+    "\n",
+    "agent_client = KnowledgeAgentRetrievalClient(endpoint=endpoint, agent_name=agent_name, credential=credential)\n",
+    "\n",
     "thread = project_client.agents.create_thread()\n",
     "retrieval_results = {}\n",
     "\n",
@@ -274,36 +281,26 @@
     "    messages = project_client.agents.list_messages(thread.id, limit=5, order=ListSortOrder.DESCENDING)\n",
     "    # Reverse the order so the most recent message is last\n",
     "    messages.data.reverse()\n",
-    "    retrieval_request = {\n",
-    "        \"messages\" : [ { \"role\": msg.role, \"content\": [ { \"text\": msg_content.text.value, \"type\": msg_content.type } for msg_content in msg.content ] } for msg in messages.data ],\n",
-    "        \"targetIndexParams\" :  [\n",
-    "            { \n",
-    "                \"indexName\" : index_name,\n",
-    "                \"rerankerThreshold\": 2.5\n",
-    "            } \n",
-    "        ]\n",
-    "    }\n",
-    "    response = requests.post(\n",
-    "        url=f\"{endpoint}/agents/{agent_name}/retrieve?api-version={api_version}\",\n",
-    "        headers={ \"Authorization\": f\"Bearer {token_provider()}\" },\n",
-    "        json=retrieval_request\n",
+    "    retrieval_result = agent_client.knowledge_retrieval.retrieve(\n",
+    "        retrieval_request=KnowledgeAgentRetrievalRequest(\n",
+    "            messages=[KnowledgeAgentMessage(role=msg[\"role\"], content=[KnowledgeAgentMessageTextContent(text=msg.content[0].text)]) for msg in messages.data],\n",
+    "            target_index_params=[KnowledgeAgentIndexParams(index_name=index_name, reranker_threshold=2.5)]\n",
+    "        )\n",
     "    )\n",
-    "    response.raise_for_status()\n",
-    "    result = response.json()\n",
     "\n",
     "    # Associate the retrieval results with the last message in the conversation\n",
     "    last_message = messages.data[-1]\n",
-    "    retrieval_results[last_message.id] = result\n",
+    "    retrieval_results[last_message.id] = retrieval_result\n",
     "\n",
     "    # Return the grounding response to the agent\n",
-    "    return result[\"response\"][0][\"content\"][0][\"text\"]\n",
+    "    return retrieval_result.response[0].content[0].text\n",
     "\n",
     "# Link to AI Agent Service function calling tutorial\n",
     "user_functions = { agentic_retrieval }\n",
     "functions = FunctionTool(user_functions)\n",
     "toolset = ToolSet()\n",
     "toolset.add(functions)\n",
-    "project_client.agents.enable_auto_function_calls(toolset=toolset)"
+    "project_client.agents.enable_auto_function_calls(toolset=toolset)\n"
    ]
   },
   {
@@ -384,7 +381,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": null,
    "id": "7b90fefa",
    "metadata": {},
    "outputs": [
@@ -456,14 +453,15 @@
     }
    ],
    "source": [
-    "retrieval_results = retrieval_results.get(message.id)\n",
-    "if retrieval_results is None:\n",
+    "\n",
+    "retrieval_result = retrieval_results.get(message.id)\n",
+    "if retrieval_result is None:\n",
     "    raise RuntimeError(f\"No retrieval results found for message {message.id}\")\n",
     "\n",
     "print(\"Retrieval activity\")\n",
-    "print(json.dumps(retrieval_results[\"activity\"], indent=2))\n",
+    "print(json.dumps([activity.as_dict() for activity in retrieval_result.activity], indent=2))\n",
     "print(\"Retrieval results\")\n",
-    "print(json.dumps(retrieval_results[\"references\"], indent=2))"
+    "print(json.dumps([reference.as_dict() for reference in retrieval_result.references], indent=2))\n"
    ]
   },
   {

agent-example/requirements.txt

@@ -1,7 +1,8 @@
-azure-search-documents==11.6.0b11
 azure-ai-projects
 azure-identity
 aiohttp
 ipykernel
 dotenv
-requests
+
+--extra-index-url https://pkgs.dev.azure.com/azure-sdk/public/_packaging/azure-sdk-for-python/pypi/simple/
+azure-search-documents==11.6.0a20250505003