Merge latest changes to live (#956)

* docs: remove comma splice in tool-approval.md

* docs: Remove duplicate codeblock in tool-approval.md

* docs: Remove duplicate code block

* fix header language

* docs: Link to topic-specific .NET sample project

* docs: move full sample link to tip

* Add fixes for overview page (#949)

* Add fixes for overview page

* Add missing import statements for python sample code

* Add C# runtime-context samples and migrate middleware docs to AIProjectClient

- Add full C# zone pivot to runtime-context.md with 4 code samples covering
  AgentRunOptions.AdditionalProperties, FunctionInvocationContext,
  AgentSession.StateBag, and cross-middleware state sharing
- Migrate all 9 middleware docs from Azure.AI.OpenAI (AzureOpenAIClient) to
  Azure.AI.Projects (AIProjectClient) with DefaultAzureCredential
- Use .GetResponsesClient().AsIChatClient() for standalone IChatClient examples
- Add DefaultAzureCredential production warning to all middleware docs

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: correct critical provider documentation issues

- copilot-studio.md: Replace non-existent CopilotStudioChatClient with
  CopilotStudioAgent, rewrite C# sample, add Python section
- index.md: Fix comparison table (OpenAI/Anthropic/GitHub Copilot MCP,
  Anthropic Code Interpreter), add Foundry Local row, add Copilot Studio
  to Python list, note both AIAgent/.NET and BaseAgent/Python base classes
- github-copilot.md: Fix PermissionRequest import path, rename thread
  variable to session for consistency
- foundry-local.md: Fix next step link to point forward to Anthropic
- microsoft-foundry.md: Fix next step link to point to Foundry Local

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: replace geopolitical term in copilot-studio example

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix doc inaccuracies in various places (#954)

* Fixes for RAG docs (#952)

* Adds sample documentation for two separate Neo4j context providers fo… (#361)

* Python: Adds sample documentation for two separate Neo4j context providers for retrieval and memory

* adding pypi links

* Move Neo4j integration docs from inline sections to dedicated integration pages

* Add GraphRAG section and address PR review comments

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fixing dotnet docs

* fixing dotnet docs

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

* Fix for csharp declarative agent docs (#955)

---------

Co-authored-by: Learn Build Service GitHub App <Learn Build Service LearnBuild@microsoft.com>
Co-authored-by: Jacob Alber <jaalber@microsoft.com>
Co-authored-by: Jacob Alber <jacob.alber@microsoft.com>
Co-authored-by: Roger Barreto <19890735+rogerbarreto@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Giles Odigwe <gilesodigwe@microsoft.com>
Co-authored-by: Tao Chen <taochen@microsoft.com>
Co-authored-by: Giles Odigwe <79032838+giles17@users.noreply.github.com>
Co-authored-by: Ryan Knight <ryan@grandcloud.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Co-authored-by: Dmytro Struk <13853051+dmytrostruk@users.noreply.github.com>
Co-authored-by: Ben Thomas <ben.thomas@microsoft.com>
Co-authored-by: Chris <66376200+crickman@users.noreply.github.com>
Co-authored-by: SergeyMenshykh <68852919+SergeyMenshykh@users.noreply.github.com>
Co-authored-by: Peter Ibekwe <109177538+peibekwe@users.noreply.github.com>

Author: 16 people

agent-framework/TOC.yml

@@ -178,6 +178,10 @@ items:
     href: integrations/purview.md
   - name: M365
     href: integrations/m365.md
+  - name: Neo4j GraphRAG Provider
+    href: integrations/neo4j-graphrag.md
+  - name: Neo4j Memory Provider
+    href: integrations/neo4j-memory.md
   - name: A2A Protocol
     href: integrations/a2a.md
   - name: AG-UI Protocol

agent-framework/agents/declarative.md

@@ -18,25 +18,53 @@ Declarative agents allow you to define agent configuration using YAML or JSON fi
 The following example shows how to create a declarative agent from a YAML configuration:
 
 ```csharp
-using System;
-using System.IO;
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
-// Load agent configuration from a YAML file
-var yamlContent = File.ReadAllText("agent-config.yaml");
-
-// Create the agent from the YAML definition
-AIAgent agent = AgentFactory.CreateFromYaml(
-    yamlContent,
-    new AzureOpenAIClient(
-        new Uri("https://<myresource>.openai.azure.com"),
-        new AzureCliCredential()));
-
-// Run the declarative agent
-Console.WriteLine(await agent.RunAsync("Why is the sky blue?"));
+// Create the chat client
+IChatClient chatClient = new AzureOpenAIClient(
+    new Uri("https://<myresource>.openai.azure.com"),
+    new DefaultAzureCredential())
+     .GetChatClient("gpt-4o-mini")
+     .AsIChatClient();
+
+// Define the agent using a YAML definition.
+var yamlDefinition =
+    """
+    kind: Prompt
+    name: Assistant
+    description: Helpful assistant
+    instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format.
+    model:
+        options:
+            temperature: 0.9
+            topP: 0.95
+    outputSchema:
+        properties:
+            language:
+                type: string
+                required: true
+                description: The language of the answer.
+            answer:
+                type: string
+                required: true
+                description: The answer text.
+    """;
+
+// Create the agent from the YAML definition.
+var agentFactory = new ChatClientPromptAgentFactory(chatClient);
+var agent = await agentFactory.CreateFromYamlAsync(yamlDefinition);
+
+// Invoke the agent and output the text result.
+Console.WriteLine(await agent!.RunAsync("Tell me a joke about a pirate in English."));
+
+// Invoke the agent with streaming support.
+await foreach (var update in agent!.RunStreamingAsync("Tell me a joke about a pirate in French."))
+{
+    Console.WriteLine(update);
+}
 ```
 
 :::zone-end

agent-framework/agents/index.md

@@ -18,6 +18,7 @@ The Microsoft Agent Framework provides support for several types of agents to ac
 ::: zone pivot="programming-language-csharp"
 All agents are derived from a common base class, `AIAgent`, which provides a consistent interface for all agent types. This allows for building common, agent agnostic, higher level functionality such as multi-agent orchestrations.
 ::: zone-end
+
 ::: zone pivot="programming-language-python"
 All agents are derived from a common base class, `Agent`, which provides a consistent interface for all agent types. This allows for building common, agent agnostic, higher level functionality such as multi-agent orchestrations.
 ::: zone-end
@@ -28,7 +29,7 @@ All agents in the Microsoft Agent Framework execute using a structured runtime m
 
 ![AI Agent Diagram](../media/agent.svg)
 
-> [!IMPORTANT]
+> [!WARNING]
 > If you use Microsoft Agent Framework to build applications that operate with third-party servers or agents, you do so at your own risk. We recommend reviewing all data being shared with third-party servers or agents and being cognizant of third-party practices for retention and location of data. It is your responsibility to manage whether your data will flow outside of your organization's Azure compliance and geographic boundaries and any related implications.
 
 ::: zone pivot="programming-language-csharp"
@@ -66,7 +67,6 @@ To make creating these agents even easier, Agent Framework provides helpers for
 |[Anthropic](./providers/anthropic.md)|An agent that uses a Claude model via the Anthropic Service as its backend.|No|Yes|
 |[OpenAI ChatCompletion](./providers/openai.md)|An agent that uses the OpenAI ChatCompletion service.|No|Yes|
 |[OpenAI Responses](./providers/openai.md)|An agent that uses the OpenAI Responses service.|Yes|Yes|
-|[OpenAI Assistants](./providers/openai.md)|An agent that uses the OpenAI Assistants service.|Yes|No|
 |[Any other `IChatClient`](./providers/custom.md)|You can also use any other [`Microsoft.Extensions.AI.IChatClient`](/dotnet/ai/microsoft-extensions-ai#the-ichatclient-interface) implementation to create an agent.|Varies|Varies|
 
 ## Complex custom agents
@@ -261,7 +261,6 @@ For detailed examples, see the agent-specific documentation sections below.
 |[Azure OpenAI Assistants](./providers/azure-openai.md)|An agent that uses the Azure OpenAI Assistants service.|Yes|
 |[OpenAI Chat Completion](./providers/openai.md)|An agent that uses the OpenAI Chat Completion service.|No|
 |[OpenAI Responses](./providers/openai.md)|An agent that uses the OpenAI Responses service.|Yes|
-|[OpenAI Assistants](./providers/openai.md)|An agent that uses the OpenAI Assistants service.|Yes|
 |[Anthropic Claude](./providers/anthropic.md)|An agent that uses Anthropic Claude models.|No|
 |[Amazon Bedrock](https://github.com/microsoft/agent-framework/tree/main/python/packages/bedrock)|An agent that uses Amazon Bedrock models through the Agent Framework Bedrock chat client.|No|
 |[GitHub Copilot](./providers/github-copilot.md)|An agent that uses the GitHub Copilot SDK backend.|No|

agent-framework/agents/middleware/agent-vs-run-scope.md

@@ -33,7 +33,7 @@ using System.Linq;
 using System.Runtime.CompilerServices;
 using System.Threading;
 using System.Threading.Tasks;
-using Azure.AI.OpenAI;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
@@ -65,11 +65,12 @@ async IAsyncEnumerable<AgentResponseUpdate> SecurityStreamingMiddleware(
     }
 }
 
-AIAgent baseAgent = new AzureOpenAIClient(
-    new Uri("https://<myresource>.openai.azure.com"),
-    new AzureCliCredential())
-        .GetChatClient("gpt-4o-mini")
-        .AsAIAgent(instructions: "You are a helpful assistant.");
+AIAgent baseAgent = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
+    new DefaultAzureCredential())
+        .AsAIAgent(
+            model: "gpt-4o-mini",
+            instructions: "You are a helpful assistant.");
 
 // Register middleware at the agent level
 var agentWithMiddleware = baseAgent
@@ -80,6 +81,9 @@ var agentWithMiddleware = baseAgent
 Console.WriteLine(await agentWithMiddleware.RunAsync("What's the weather in Paris?"));
 ```
 
+> [!WARNING]
+> `DefaultAzureCredential` is convenient for development but requires careful consideration in production. In production, consider using a specific credential (e.g., `ManagedIdentityCredential`) to avoid latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+
 ### Run-level middleware
 
 Run-level middleware uses the same builder pattern, applied inline for a specific invocation:

agent-framework/agents/middleware/chat-middleware.md

@@ -23,7 +23,7 @@ using System.Collections.Generic;
 using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
-using Azure.AI.OpenAI;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
@@ -48,18 +48,23 @@ async Task<ChatResponse> LoggingChatMiddleware(
 }
 
 // Register IChatClient middleware using the client factory
-var agent = new AzureOpenAIClient(
-    new Uri("https://<myresource>.openai.azure.com"),
-    new AzureCliCredential())
-        .GetChatClient("gpt-4o-mini")
-        .AsAIAgent("You are a helpful assistant.", clientFactory: (chatClient) => chatClient
-            .AsBuilder()
-                .Use(getResponseFunc: LoggingChatMiddleware, getStreamingResponseFunc: null)
-            .Build());
+var agent = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
+    new DefaultAzureCredential())
+        .AsAIAgent(
+            model: "gpt-4o-mini",
+            instructions: "You are a helpful assistant.",
+            clientFactory: (chatClient) => chatClient
+                .AsBuilder()
+                    .Use(getResponseFunc: LoggingChatMiddleware, getStreamingResponseFunc: null)
+                .Build());
 
 Console.WriteLine(await agent.RunAsync("Hello, how are you?"));
 ```
 
+> [!WARNING]
+> `DefaultAzureCredential` is convenient for development but requires careful consideration in production. In production, consider using a specific credential (e.g., `ManagedIdentityCredential`) to avoid latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+
 > [!NOTE]
 > For more information about `IChatClient` middleware, see [Custom IChatClient middleware](/dotnet/ai/microsoft-extensions-ai#custom-ichatclient-middleware).
 

agent-framework/agents/middleware/defining-middleware.md

@@ -26,25 +26,27 @@ First, create a basic agent with a function tool.
 ```csharp
 using System;
 using System.ComponentModel;
-using Azure.AI.OpenAI;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
-using OpenAI;
 
 [Description("The current datetime offset.")]
 static string GetDateTime()
     => DateTimeOffset.Now.ToString();
 
-AIAgent baseAgent = new AzureOpenAIClient(
-    new Uri("https://<myresource>.openai.azure.com"),
-    new AzureCliCredential())
-        .GetChatClient("gpt-4o-mini")
+AIAgent baseAgent = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
+    new DefaultAzureCredential())
         .AsAIAgent(
+            model: "gpt-4o-mini",
             instructions: "You are an AI assistant that helps people find information.",
             tools: [AIFunctionFactory.Create(GetDateTime, name: nameof(GetDateTime))]);
 ```
 
+> [!WARNING]
+> `DefaultAzureCredential` is convenient for development but requires careful consideration in production. In production, consider using a specific credential (e.g., `ManagedIdentityCredential`) to avoid latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+
 ## Step 2: Create Your Agent Run Middleware
 
 Next, create a function that will get invoked for each agent run.
@@ -178,9 +180,12 @@ To add middleware to your <xref:Microsoft.Extensions.AI.IChatClient>, you can us
 After adding the middleware, you can use the `IChatClient` with your agent as usual.
 
 ```csharp
-var chatClient = new AzureOpenAIClient(new Uri("https://<myresource>.openai.azure.com"), new AzureCliCredential())
-    .GetChatClient("gpt-4o-mini")
-    .AsIChatClient();
+var chatClient = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
+    new DefaultAzureCredential())
+        .GetProjectOpenAIClient()
+        .GetResponsesClient()
+        .AsIChatClient("gpt-4o-mini");
 
 var middlewareEnabledChatClient = chatClient
     .AsBuilder()
@@ -194,12 +199,16 @@ var agent = new ChatClientAgent(middlewareEnabledChatClient, instructions: "You
  an agent via one of the helper methods on SDK clients.
 
 ```csharp
-var agent = new AzureOpenAIClient(new Uri("https://<myresource>.openai.azure.com"), new AzureCliCredential())
-    .GetChatClient("gpt-4o-mini")
-    .AsAIAgent("You are a helpful assistant.", clientFactory: (chatClient) => chatClient
-        .AsBuilder()
-            .Use(getResponseFunc: CustomChatClientMiddleware, getStreamingResponseFunc: null)
-        .Build());
+var agent = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
+    new DefaultAzureCredential())
+        .AsAIAgent(
+            model: "gpt-4o-mini",
+            instructions: "You are a helpful assistant.",
+            clientFactory: (chatClient) => chatClient
+                .AsBuilder()
+                    .Use(getResponseFunc: CustomChatClientMiddleware, getStreamingResponseFunc: null)
+                .Build());
 ```
 
 ::: zone-end

agent-framework/agents/middleware/exception-handling.md

@@ -22,7 +22,7 @@ using System;
 using System.Collections.Generic;
 using System.Threading;
 using System.Threading.Tasks;
-using Azure.AI.OpenAI;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
@@ -54,11 +54,12 @@ async Task<AgentResponse> ExceptionHandlingMiddleware(
     }
 }
 
-AIAgent agent = new AzureOpenAIClient(
-    new Uri("https://<myresource>.openai.azure.com"),
-    new AzureCliCredential())
-        .GetChatClient("gpt-4o-mini")
-        .AsAIAgent(instructions: "You are a helpful assistant.");
+AIAgent agent = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
+    new DefaultAzureCredential())
+        .AsAIAgent(
+            model: "gpt-4o-mini",
+            instructions: "You are a helpful assistant.");
 
 var safeAgent = agent
     .AsBuilder()
@@ -68,6 +69,9 @@ var safeAgent = agent
 Console.WriteLine(await safeAgent.RunAsync("Get user statistics"));
 ```
 
+> [!WARNING]
+> `DefaultAzureCredential` is convenient for development but requires careful consideration in production. In production, consider using a specific credential (e.g., `ManagedIdentityCredential`) to avoid latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+
 :::zone-end
 
 :::zone pivot="programming-language-python"

agent-framework/agents/middleware/index.md

@@ -43,9 +43,12 @@ var middlewareEnabledAgent = originalAgent
 `IChatClient` middleware can be registered on an `IChatClient` before it is used with a `ChatClientAgent`, by using the chat client builder pattern.
 
 ```csharp
-var chatClient = new AzureOpenAIClient(new Uri("https://<myresource>.openai.azure.com"), new DefaultAzureCredential())
-    .GetChatClient(deploymentName)
-    .AsIChatClient();
+var chatClient = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
+    new DefaultAzureCredential())
+        .GetProjectOpenAIClient()
+        .GetResponsesClient()
+        .AsIChatClient(deploymentName);
 
 var middlewareEnabledChatClient = chatClient
     .AsBuilder()
@@ -62,12 +65,16 @@ var agent = new ChatClientAgent(middlewareEnabledChatClient, instructions: "You
  an agent via one of the helper methods on SDK clients.
 
 ```csharp
-var agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
-    .GetChatClient(deploymentName)
-    .AsAIAgent("You are a helpful assistant.", clientFactory: (chatClient) => chatClient
-        .AsBuilder()
-            .Use(getResponseFunc: CustomChatClientMiddleware, getStreamingResponseFunc: null)
-        .Build());
+var agent = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
+    new DefaultAzureCredential())
+        .AsAIAgent(
+            model: deploymentName,
+            instructions: "You are a helpful assistant.",
+            clientFactory: (chatClient) => chatClient
+                .AsBuilder()
+                    .Use(getResponseFunc: CustomChatClientMiddleware, getStreamingResponseFunc: null)
+                .Build());
 ```
 
 ## Agent Run Middleware

agent-framework/agents/middleware/result-overrides.md

@@ -23,7 +23,7 @@ using System.Collections.Generic;
 using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
-using Azure.AI.OpenAI;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
@@ -52,11 +52,12 @@ async Task<AgentResponse> ResultOverrideMiddleware(
     return new AgentResponse(modifiedMessages);
 }
 
-AIAgent agent = new AzureOpenAIClient(
-    new Uri("https://<myresource>.openai.azure.com"),
-    new AzureCliCredential())
-        .GetChatClient("gpt-4o-mini")
-        .AsAIAgent(instructions: "You are a helpful weather assistant.");
+AIAgent agent = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
+    new DefaultAzureCredential())
+        .AsAIAgent(
+            model: "gpt-4o-mini",
+            instructions: "You are a helpful weather assistant.");
 
 var agentWithOverride = agent
     .AsBuilder()
@@ -66,6 +67,9 @@ var agentWithOverride = agent
 Console.WriteLine(await agentWithOverride.RunAsync("What's the weather in Seattle?"));
 ```
 
+> [!WARNING]
+> `DefaultAzureCredential` is convenient for development but requires careful consideration in production. In production, consider using a specific credential (e.g., `ManagedIdentityCredential`) to avoid latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+
 :::zone-end
 
 :::zone pivot="programming-language-python"