fix: recommend AIProjectClient instead of PersistentAgentsClient

Author: XiaofuHuang

tools/Azure.Mcp.Tools.AzureAIBestPractices/src/Resources/ai-background-knowledge.txt

@@ -18,7 +18,8 @@ Use this hierarchy to analyze and select AI models
   - **Multi-LLM Support**: Works with OpenAI, Azure OpenAI, Azure AI Foundry, and other providers
 
 **Agent Types:**
-  - **[RECOMMENDED] Azure AI Foundry Agent (`PersistentAgentsClient`)**: Service-managed persistent agents with conversation threads - best for production applications requiring conversation continuity
+  - **[RECOMMENDED] Azure AI Foundry Agent (`AIProjectClient`)**: Latest unified client for Azure AI Foundry agents with conversation threads - best for production applications requiring conversation continuity and modern agent features
+  - **[LEGACY] Azure AI Foundry Agent (`PersistentAgentsClient`)**: Older client for service-managed persistent agents - superseded by `AIProjectClient`
   - **OpenAI ChatCompletion / Responses / Assistants Agent (`OpenAIClient`)**: Stateless or service-managed agents using OpenAI service
   - **Azure AI Foundry Models ChatCompletion / Responses Agent (`OpenAIClient` / `AzureOpenAIClient`)**: For testing Foundry-deployed models (stateless)
   - **Azure OpenAI ChatCompletion / Responses (`AzureOpenAIClient`)**: Stateless agents using Azure OpenAI ChatCompletion / Responses service  

tools/Azure.Mcp.Tools.AzureAIBestPractices/src/Resources/ai-best-practices-core.txt

@@ -65,18 +65,9 @@ Always search / fetch / query for sufficient knowledge (quickstarts, tutorials,
 ### 1. Search for Implementation Knowledge
 After completing the required model selection process above, gather SDK and implementation information.
 #### Step 1: Fetch common quickstart pages
-  Use the Microsoft Document **fetch** operation to retrieve these pages directly for complete, unabridged content. These are the most commonly needed references and should be fetched for EVERY implementation:
-  - [Default] Azure AI Foundry Quickstart: `https://learn.microsoft.com/agent-framework/user-guide/agents/agent-types/azure-ai-foundry-agent`
-
-#### Step 2 (Optional): Search for specific agent type documentation
-  **ONLY if user explicitly requests a NON-Azure AI Foundry service provider:**
-  - **Default for Azure AI Foundry**: ALWAYS use Azure AI Foundry Agent (`PersistentAgentsClient`) - skip this step
-  - **DO NOT use this step for demos, prototypes, or "local testing"** - still use `PersistentAgentsClient`
-  - **ONLY search other agent types if user explicitly says**: "use OpenAI service", "use Azure OpenAI service", etc.
-    - Example: User says "use OpenAI service" → Search "Agent Framework OpenAI ChatCompletion Agents"
-    - Example: User says "use Azure OpenAI" → Search "Agent Framework Azure OpenAI ChatCompletion Agents"
-
-#### Step 3: Search for feature guidelines
+  Use the **fetch** operation to retrieve GitHub pages directly for complete, unabridged content. These are the most commonly needed references and should be fetched for EVERY implementation:
+  - [Default] Microsoft Agent Framework Quickstart: `https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureAIProject/Program.cs`
+#### Step 2: Search for feature guidelines
 **Stage 1 - Identify Core Capabilities:**
 Break down the user's requirement into individual capabilities
 - Example: "Build a weather agent for user to query weather" → ["function calling"]
@@ -142,20 +133,20 @@ User Requirements Analysis:
 
 ### 2. Explain SDK selection
 **Recommended SDK:** Microsoft Agent Framework
-**Recommended Agent Type:** Azure AI Foundry Agents with PersistentAgentsClient
+**Recommended Agent Type:** Azure AI Foundry Agents with AIProjectClient
 **Default Programming Language:** .NET
 
 ** Agent Type Selection Rules **
-- **ALWAYS use `PersistentAgentsClient` for Azure AI Foundry** 
-- **DO NOT use `AzureOpenAIClient`** for Azure AI Foundry models, even for demos, prototypes, or local testing
-- `PersistentAgentsClient` provides service-managed persistence, conversation threads, and full agent capabilities
+- **ALWAYS use `AIProjectClient` for Azure AI Foundry** 
+- **DO NOT use `AzureOpenAIClient` or `PersistentAgentsClient`** for Azure AI Foundry models, even for demos, prototypes, or local testing
+- `AIProjectClient` provides service-managed persistence, conversation threads, and full agent capabilities
 - Only use other agent types (OpenAI ChatCompletion, Azure OpenAI, etc.) if the user **explicitly requests a different service provider**
 
 **Output format:**
 ```
 SDK Selection: Microsoft Agent Framework
 
-Agent Type: Azure AI Foundry Agents (PersistentAgentsClient)
+Agent Type: Azure AI Foundry Agents (AIProjectClient)
 
 Programming Language: [.NET (default) OR Python (if user specified)]
 
@@ -210,6 +201,7 @@ Create a step-by-step plan / todo list covering project initialization, installa
    - If build fails: Analyze build errors → Fix code issues → Rebuild
    - Repeat fix-rebuild cycle until build succeeds with zero errors
 
+Creating the plan is NOT the end - it's the beginning. Continue to implement the code.
 
 ## Code - Implementation Guidelines
 **Note**: Continue using Microsoft Document Search throughout implementation for any unknowns.
@@ -233,11 +225,15 @@ DO REMIND USER THE `--pre` OR `--prerelease` FLAG IS REQUIRED IN GENERATED DOC.
 
 #### .NET
 Agent type-specific installation packages:
-- **Azure AI Foundry Agent (RECOMMENDED)** - `PersistentAgentsClient`:
+- **Azure AI Foundry Agent (RECOMMENDED)** - `AIProjectClient`:
   ```bash
   dotnet add package Azure.Identity
   dotnet add package Microsoft.Agents.AI.AzureAI --prerelease
   ```
+  
+  Do NOT add `Azure.AI.Projects` separately - it's already included in `Microsoft.Agents.AI.AzureAI`. 
+  Adding `Azure.AI.Projects` manually may introduce version mismatches and build errors
+
 - **Workflows and Orchestration** - For multi-agent systems and workflow features, also add:
   ```bash
   dotnet add package Microsoft.Agents.AI.Workflows --prerelease

tools/Azure.Mcp.Tools.AzureAIBestPractices/src/Resources/ai-error-patterns.txt

@@ -74,79 +74,112 @@ var data = await context.ReadStateAsync<string>(key: stateId, scopeName: "MyScop
 
 ### Agent Type 
 #### Agent Type Selection
-**IMPORTANT**: When using Azure AI Foundry, always use `PersistentAgentsClient` to create agents - NOT `AzureOpenAIClient`.
+
+**For .NET:**
+**IMPORTANT**: When using Azure AI Foundry, always use `AIProjectClient` to create agents - NOT `AzureOpenAIClient`.
 - ❌ Do NOT use `AzureOpenAIClient` for Azure AI Foundry models - that's only for testing and lacks conversation persistence
-- ✅ DO use `PersistentAgentsClient` - it provides full agent capabilities with service-managed state
+- ✅ DO use `AIProjectClient` - it provides full agent capabilities with service-managed state and is the latest recommended approach
+- ⚠️ `PersistentAgentsClient` is legacy - use `AIProjectClient` instead
 
-Code samples may show `AzureOpenAIClient` for simplicity or backward compatibility, but production implementations should use `PersistentAgentsClient` for Azure AI Foundry.
+Code samples may show `AzureOpenAIClient` for simplicity or backward compatibility, but production implementations should use `AIProjectClient` for Azure AI Foundry.
 
-#### Key Difference: When to Pass ChatOptions
-The main difference between `PersistentAgentsClient` and `AzureOpenAIClient` is **when** you configure ChatOptions (Tools, ResponseFormat, etc. ):
-- **PersistentAgentsClient**: Pass ChatOptions when **retrieving** the agent via `GetAIAgentAsync()`
-- **AzureOpenAIClient**: Pass options when **creating** the agent via `CreateAIAgent()`
+#### Key Differences: AIProjectClient vs AzureOpenAIClient
 
-Note: Only add ChatOptions properties (Tools, ResponseFormat, etc.) when user requirements explicitly need them. Do NOT add them by default.
+**1. Creation Pattern:**
+- `AIProjectClient` uses `await aiProjectClient.CreateAIAgentAsync(...)` - creates agents on the server
+- `AzureOpenAIClient` uses `.GetChatClient(deploymentName).CreateAIAgent(...)` - creates local agents
 
-#### ✅ CORRECT - PersistentAgentsClient Pattern
-Pass all ChatOptions properties (tools, ResponseFormat, etc.) to `GetAIAgentAsync()`:
+#### ✅ CORRECT - AIProjectClient Pattern (Recommended)
 
 ```csharp
-using Azure.AI.Agents.Persistent;
+using System.ComponentModel;
+using System.Text.Json.Serialization;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
-using System.ComponentModel;
-using System.Text.Json.Serialization;
 
-// Define function tool
-[Description("Get weather for a location")]
-static string GetWeather([Description("Location")] string location)
-    => $"Weather in {location}: 25°C, sunny";
+string endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+
+[Description("Get the weather for a given location.")]
+static string GetWeather([Description("The location to get the weather for.")] string location)
+    => $"The weather in {location} is cloudy with a high of 15°C.";
+
+const string AssistantInstructions = "You are a helpful assistant that can get weather information.";
+const string AssistantName = "WeatherAssistant";
+
+// Get a client to create/retrieve/delete server side agents with Azure Foundry Agents.
+AIProjectClient aiProjectClient = new(new Uri(endpoint), new AzureCliCredential());
+
+// Define the agent with function tools.
+AITool tool = AIFunctionFactory.Create(GetWeather);
+
+// Create AIAgent directly - Simple agent with tools for basic scenarios
+AIAgent agent = await aiProjectClient.CreateAIAgentAsync(
+    name: AssistantName,
+    model: deploymentName,
+    instructions: AssistantInstructions,
+    tools: [tool]);
+
+// Create ChatClientAgent - Advanced agent with structured output support via ResponseFormat
+// Use this when you need structured JSON responses with schema validation
+ChatClientAgent agent1 = await aiProjectClient.CreateAIAgentAsync(
+    model: deploymentName,
+    new ChatClientAgentOptions(name: AssistantName, instructions: AssistantInstructions, tools: [tool])
+    {
+        ChatOptions = new()
+        {
+            ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<WeatherResponse>()
+        }
+    });
+
+// Non-streaming agent interaction with function tools.
+Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?"));
+
+// Streaming agent interaction with function tools.
+await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync("What is the weather like in Amsterdam?"))
+{
+    Console.WriteLine(update);
+}
+
+// Cleanup by agent name removes the agent version created.
+await aiProjectClient.Agents.DeleteAgentAsync(agent.Name);
+
 
-// Define response schema
+// Define structured output schema for weather response
+[Description("Weather information for a location")]
 public class WeatherResponse
 {
     [JsonPropertyName("location")]
     public string Location { get; set; } = string.Empty;
 
     [JsonPropertyName("temperature")]
-    public double Temperature { get; set; }
-}
+    public string Temperature { get; set; } = string.Empty;
 
-var client = new PersistentAgentsClient(
-    "https://<resource>.services.ai.azure.com/api/projects/<project>",
-    new AzureCliCredential());
+    [JsonPropertyName("condition")]
+    public string Condition { get; set; } = string.Empty;
+}
+```
 
-// Step 1: Create agent (only model, name, instructions)
-var agentMetadata = await client.Administration.CreateAgentAsync(
-    model: "gpt-4o-mini", // Just for example
-    name: "WeatherAgent",
-    instructions: "Provide weather information");
+#### ❌ INCORRECT - AzureOpenAIClient Patterns to Avoid
 
-// Step 2: Get agent with ChatOptions (tools, ResponseFormat, etc.)
-AIAgent agent = await client.GetAIAgentAsync(
-    agentId: agentMetadata.Value.Id,
-    new ChatOptions
-    {
-        Tools = [AIFunctionFactory.Create(GetWeather)],  // ✅ Tools passed here
-        ResponseFormat = ChatResponseFormat.ForJsonSchema<WeatherResponse>(  // ✅ ResponseFormat passed here
-            schemaName: "WeatherResponse",
-            schemaDescription: "Weather data")
-    });
+**Don't use explicit thread management with AzureOpenAIClient:**
+```csharp
 
-var response = await agent.RunAsync("What's the weather in Seattle?");
+// Create AIAgent with AzureOpenAIClient
+AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential()) // ❌ WRONG: Use AIProjectClient instead
+    .GetChatClient(deploymentName)
+    .CreateAIAgent(instructions: "You are a helpful assistant");
 ```
 
-#### ❌ INCORRECT - Don't Use AzureOpenAIClient Pattern with PersistentAgentsClient
+#### ❌ INCORRECT - Don't Use Legacy PersistentAgentsClient Pattern
 
 ```csharp
-var client = new PersistentAgentsClient(
+using Azure.AI.Agents.Persistent;  // ❌ WRONG: Use Azure.AI.Projects instead
+
+var client = new PersistentAgentsClient(  // ❌ WRONG: Use AIProjectClient instead
     "https://<resource>.services.ai.azure.com/api/projects/<project>",
     new AzureCliCredential());
-
-// ❌ WRONG PATTERN: Trying to pass tools at agent creation
-AIAgent agent = await client.Administration.CreateAgentAsync(
-        model: "gpt-4o-mini",
-        tools: [AIFunctionFactory.Create(GetWeather)]  // ❌ Wrong: Can't pass tools here
-    );
 ```
+