Merge pull request #959 from MicrosoftDocs/foundry-updates-0005

Apply Azure.AI.Projects 2.0 GA renames and fix C# code inaccuracies

Author: rogerbarreto

agent-framework/agents/index.md

@@ -97,7 +97,7 @@ When using Foundry, Azure OpenAI, OpenAI services, or Anthropic services, you ha
 | [Foundry Models](/azure/ai-foundry/concepts/foundry-models-overview) | Azure OpenAI SDK <sup>2</sup> | [Azure.AI.OpenAI](https://www.nuget.org/packages/Azure.AI.OpenAI) | https://ai-foundry-&lt;resource&gt;.services.ai.azure.com/ |
 | [Foundry Models](/azure/ai-foundry/concepts/foundry-models-overview) | OpenAI SDK <sup>3</sup> | [OpenAI](https://www.nuget.org/packages/OpenAI) | https://ai-foundry-&lt;resource&gt;.services.ai.azure.com/openai/v1/ |
 | [Foundry Models](/azure/ai-foundry/concepts/foundry-models-overview) | Azure AI Inference SDK <sup>2</sup> | [Azure.AI.Inference](https://www.nuget.org/packages/Azure.AI.Inference) | https://ai-foundry-&lt;resource&gt;.services.ai.azure.com/models |
-| [Foundry Agents](/azure/ai-foundry/agents/overview) | Azure AI Persistent Agents SDK | [Azure.AI.Agents.Persistent](https://www.nuget.org/packages/Azure.AI.Agents.Persistent) | https://ai-foundry-&lt;resource&gt;.services.ai.azure.com/api/projects/ai-project-&lt;project&gt; |
+| [Foundry Agents](/azure/ai-foundry/agents/overview) | Azure AI Projects SDK + Microsoft Agents AI Foundry | [Azure.AI.Projects](https://www.nuget.org/packages/Azure.AI.Projects) / [Microsoft.Agents.AI.Foundry](https://www.nuget.org/packages/Microsoft.Agents.AI.Foundry) | https://ai-foundry-&lt;resource&gt;.services.ai.azure.com/api/projects/ai-project-&lt;project&gt; |
 | [Azure OpenAI](/azure/ai-foundry/openai/overview) <sup>1</sup> | Azure OpenAI SDK <sup>2</sup> | [Azure.AI.OpenAI](https://www.nuget.org/packages/Azure.AI.OpenAI) | https://&lt;resource&gt;.openai.azure.com/ |
 | [Azure OpenAI](/azure/ai-foundry/openai/overview) <sup>1</sup> | OpenAI SDK | [OpenAI](https://www.nuget.org/packages/OpenAI) | https://&lt;resource&gt;.openai.azure.com/openai/v1/ |
 | OpenAI | OpenAI SDK | [OpenAI](https://www.nuget.org/packages/OpenAI) | No url required |
@@ -158,13 +158,13 @@ AIAgent agent = new AIProjectClient(
          name: "Joker");
 ```
 
-### Using the Azure AI Persistent Agents SDK
+### Using the Azure AI Projects SDK with Foundry Agents
 
-This SDK is only supported with the Agent Service. See the table above for the correct URL to use.
+This SDK is used for both Responses API based agents and versioned Foundry Agents. See the table above for the correct URL to use.
 
 ```csharp
-var persistentAgentsClient = new PersistentAgentsClient(serviceUrl, new DefaultAzureCredential());
-AIAgent agent = await persistentAgentsClient.CreateAIAgentAsync(
+var aiProjectClient = new AIProjectClient(new Uri(serviceUrl), new DefaultAzureCredential());
+AIAgent agent = aiProjectClient.AsAIAgent(
     model: deploymentName,
     instructions: "You are good at telling jokes.",
     name: "Joker");

agent-framework/agents/providers/microsoft-foundry.md

@@ -31,7 +31,7 @@ The Microsoft Foundry integration exposes two distinct usage patterns:
 | Type | Produced type | Description | Use when |
 |---|---|---|---|
 | **Responses Agent** | `ChatClientAgent` | Your app programmatically provides a model, instructions, and tools at runtime via `AIProjectClient.AsAIAgent(...)`. No server-side agent resource is created. | You own the agent definition and want a simple, flexible setup. This is the pattern used in most samples. |
-| **Foundry Agent** (versioned) | `FoundryAgent` | Server-managed — agent definitions are created and versioned either through the Foundry portal or programmatically via `AIProjectClient.Agents`. Pass an `AgentVersion` or `AgentRecord` or `AgentReference` to `AIProjectClient.AsAIAgent(...)`. | You need strict, versioned agent definitions managed in the Foundry portal, through service APIs |
+| **Foundry Agent** (versioned) | `FoundryAgent` | Server-managed — agent definitions are created and versioned either through the Foundry portal or programmatically via `AIProjectClient.AgentAdministrationClient`. Pass a `ProjectsAgentVersion` or `ProjectsAgentRecord` or `AgentReference` to `AIProjectClient.AsAIAgent(...)`. | You need strict, versioned agent definitions managed in the Foundry portal, through service APIs |
 
 ## Responses Agent (direct inference)
 
@@ -60,7 +60,7 @@ This path is code-first and does not create a server-managed agent resource.
 
 ## Foundry Agent (versioned)
 
-Use the native `AIProjectClient.Agents` APIs from the AI Projects SDK to retrieve versioned agent resources, then wrap them with `AsAIAgent`. Agents can be created and configured directly in the Foundry portal or programmatically via `AIProjectClient.Agents`.
+Use the native `AIProjectClient.AgentAdministrationClient` APIs from the AI Projects SDK to retrieve versioned agent resources, then wrap them with `AsAIAgent`. Agents can be created and configured directly in the Foundry portal or programmatically via `AIProjectClient.AgentAdministrationClient`.
 
 ```csharp
 using Azure.AI.Projects;
@@ -74,7 +74,7 @@ var aiProjectClient = new AIProjectClient(
     new DefaultAzureCredential());
 
 // Retrieve an existing agent by name (uses the latest version automatically)
-AgentRecord jokerRecord = await aiProjectClient.Agents.GetAgentAsync("Joker");
+ProjectsAgentRecord jokerRecord = await aiProjectClient.AgentAdministrationClient.GetAgentAsync("Joker");
 FoundryAgent agent = aiProjectClient.AsAIAgent(jokerRecord);
 
 Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

agent-framework/agents/tools/hosted-mcp-tools.md

@@ -66,24 +66,27 @@ mcpTool.AllowedTools.Add("microsoft_docs_search");
 - **serverUrl**: The URL of the hosted MCP server
 - **AllowedTools**: Specifies which tools from the MCP server the agent can use
 
-#### 4. Persistent Agent Creation
+#### 4. Agent Creation
 
-The agent is created server-side using the Foundry Persistent Agents SDK:
+The agent is created server-side using the Azure AI Projects SDK:
 
 ```csharp
-var persistentAgentsClient = new PersistentAgentsClient(endpoint, new DefaultAzureCredential());
+var aiProjectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());
 
-var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(
-    model: model,
-    name: AgentName,
-    instructions: AgentInstructions,
-    tools: [mcpTool]);
+var agentVersion = await aiProjectClient.AgentAdministrationClient.CreateAgentVersionAsync(
+    AgentName,
+    new ProjectsAgentVersionCreationOptions(
+        new DeclarativeAgentDefinition(model)
+        {
+            Instructions = AgentInstructions,
+            Tools = { mcpTool }
+        }));
 ```
 
 > [!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.
 
-This creates a persistent agent that:
+This creates a versioned agent that:
 - Lives on the Foundry service
 - Has access to the specified MCP tools
 - Can maintain conversation state across multiple interactions
@@ -93,7 +96,7 @@ This creates a persistent agent that:
 The created agent is retrieved as an `AIAgent` instance:
 
 ```csharp
-AIAgent agent = await persistentAgentsClient.GetAIAgentAsync(agentMetadata.Value.Id);
+AIAgent agent = aiProjectClient.AsAIAgent(agentVersion);
 ```
 
 #### 6. Tool Resource Configuration
@@ -141,7 +144,7 @@ Console.WriteLine(response);
 The sample demonstrates proper resource cleanup:
 
 ```csharp
-await persistentAgentsClient.Administration.DeleteAgentAsync(agent.Id);
+await aiProjectClient.AgentAdministrationClient.DeleteAgentAsync(agent.Id);
 ```
 
 > [!TIP]

agent-framework/migration-guide/from-semantic-kernel/index.md

@@ -77,14 +77,15 @@ Agent creation in Agent Framework is made simpler with extensions provided by al
 
 ```csharp
 AIAgent openAIAgent = chatClient.AsAIAgent(instructions: ParrotInstructions);
-AIAgent azureFoundryAgent = await persistentAgentsClient.CreateAIAgentAsync(instructions: ParrotInstructions);
+AIAgent azureFoundryAgent = aiProjectClient.AsAIAgent(model: deploymentName, instructions: ParrotInstructions);
 AIAgent openAIAssistantAgent = await assistantClient.CreateAIAgentAsync(instructions: ParrotInstructions);
 ```
 
-Additionally, for hosted agent providers you can also use the `GetAIAgent` method to retrieve an agent from an existing hosted agent.
+Additionally, for hosted agent providers you can also use the `AsAIAgent` method to retrieve an agent from an existing hosted agent record.
 
 ```csharp
-AIAgent azureFoundryAgent = await persistentAgentsClient.GetAIAgentAsync(agentId);
+ProjectsAgentRecord agentRecord = await aiProjectClient.AgentAdministrationClient.GetAgentAsync(agentName);
+AIAgent azureFoundryAgent = aiProjectClient.AsAIAgent(agentRecord);
 ```
 
 ## 3. Agent Thread/Session Creation

agent-framework/workflows/agents-in-workflows.md

@@ -64,7 +64,7 @@ You'll create a workflow that:
 First, install the required packages for your .NET project:
 
 ```dotnetcli
-dotnet add package Azure.AI.Agents.Persistent --prerelease
+dotnet add package Azure.AI.Projects --prerelease
 dotnet add package Azure.Identity
 dotnet add package Microsoft.Agents.AI.Foundry --prerelease
 dotnet add package Microsoft.Agents.AI.Workflows --prerelease
@@ -75,21 +75,23 @@ dotnet add package Microsoft.Agents.AI.Workflows --prerelease
 Configure the Azure Foundry client with environment variables and authentication:
 
 ```csharp
-using Azure.AI.Agents.Persistent;
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
 using Azure.Identity;
 using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry;
 using Microsoft.Agents.AI.Workflows;
 using Microsoft.Extensions.AI;
 
 public static class Program
 {
     private static async Task Main()
     {
-        // Set up the Azure OpenAI client
+        // Set up the Azure AI Project client
         var endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
             ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
         var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-        var persistentAgentsClient = new PersistentAgentsClient(endpoint, new AzureCliCredential());
+        var aiProjectClient = new AIProjectClient(new Uri(endpoint), new AzureCliCredential());
 ```
 
 ## Step 3: Create Agent Factory Method
@@ -101,20 +103,24 @@ Implement a helper method to create Azure Foundry agents with specific instructi
     /// Creates a translation agent for the specified target language.
     /// </summary>
     /// <param name="targetLanguage">The target language for translation</param>
-    /// <param name="persistentAgentsClient">The PersistentAgentsClient to create the agent</param>
+    /// <param name="aiProjectClient">The AIProjectClient to create the agent</param>
     /// <param name="model">The model to use for the agent</param>
     /// <returns>A ChatClientAgent configured for the specified language</returns>
     private static async Task<ChatClientAgent> GetTranslationAgentAsync(
         string targetLanguage,
-        PersistentAgentsClient persistentAgentsClient,
+        AIProjectClient aiProjectClient,
         string model)
     {
-        var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(
-            model: model,
-            name: $"{targetLanguage} Translator",
-            instructions: $"You are a translation assistant that translates the provided text to {targetLanguage}.");
-
-        return await persistentAgentsClient.GetAIAgentAsync(agentMetadata.Value.Id);
+        string agentName = $"{targetLanguage} Translator";
+        var version = await aiProjectClient.AgentAdministrationClient.CreateAgentVersionAsync(
+            agentName,
+            new ProjectsAgentVersionCreationOptions(
+                new DeclarativeAgentDefinition(model)
+                {
+                    Instructions = $"You are a translation assistant that translates the provided text to {targetLanguage}."
+                }));
+
+        return aiProjectClient.AsAIAgent(version);
     }
 }
 ```
@@ -125,9 +131,9 @@ Create three translation agents using the helper method:
 
 ```csharp
         // Create agents
-        AIAgent frenchAgent = await GetTranslationAgentAsync("French", persistentAgentsClient, deploymentName);
-        AIAgent spanishAgent = await GetTranslationAgentAsync("Spanish", persistentAgentsClient, deploymentName);
-        AIAgent englishAgent = await GetTranslationAgentAsync("English", persistentAgentsClient, deploymentName);
+        AIAgent frenchAgent = await GetTranslationAgentAsync("French", aiProjectClient, deploymentName);
+        AIAgent spanishAgent = await GetTranslationAgentAsync("Spanish", aiProjectClient, deploymentName);
+        AIAgent englishAgent = await GetTranslationAgentAsync("English", aiProjectClient, deploymentName);
 ```
 
 ## Step 5: Build the Workflow
@@ -169,16 +175,16 @@ Properly clean up the Azure Foundry agents after use:
 
 ```csharp
         // Cleanup the agents created for the sample.
-        await persistentAgentsClient.Administration.DeleteAgentAsync(frenchAgent.Id);
-        await persistentAgentsClient.Administration.DeleteAgentAsync(spanishAgent.Id);
-        await persistentAgentsClient.Administration.DeleteAgentAsync(englishAgent.Id);
+        await aiProjectClient.AgentAdministrationClient.DeleteAgentAsync(frenchAgent.Id);
+        await aiProjectClient.AgentAdministrationClient.DeleteAgentAsync(spanishAgent.Id);
+        await aiProjectClient.AgentAdministrationClient.DeleteAgentAsync(englishAgent.Id);
     }
 ```
 
 ## How It Works
 
-1. **Azure Foundry Client Setup**: Uses `PersistentAgentsClient` with Azure CLI credentials for authentication
-2. **Agent Creation**: Creates persistent agents on Azure Foundry with specific instructions for translation
+1. **Azure Foundry Client Setup**: Uses `AIProjectClient` with Azure CLI credentials for authentication
+2. **Agent Creation**: Creates versioned agents on Azure Foundry with specific instructions for translation
 3. **Sequential Processing**: French agent translates input first, then Spanish agent, then English agent
 4. **Turn Token Pattern**: Agents cache messages and only process when they receive a `TurnToken`
 5. **Streaming Updates**: `AgentResponseUpdateEvent` provides real-time token updates as agents generate responses
@@ -187,7 +193,7 @@ Properly clean up the Azure Foundry agents after use:
 ## Key Concepts
 
 - **Azure Foundry Agent Service**: Cloud-based AI agents with advanced reasoning capabilities
-- **PersistentAgentsClient**: Client for creating and managing agents on Azure Foundry
+- **AIProjectClient**: Client for creating and managing agents on Azure Foundry
 - **WorkflowEvent**: Output events (`type="output"`) contain agent output data (`AgentResponseUpdate` for streaming, `AgentResponse` for non-streaming)
 - **TurnToken**: Signal that triggers agent processing after message caching
 - **Sequential Workflow**: Agents connected in a pipeline where output flows from one to the next

agent-framework/workflows/declarative.md

@@ -1326,7 +1326,7 @@ AIProjectClient aiProjectClient = new(foundryEndpoint, new DefaultAzureCredentia
 
 await aiProjectClient.CreateAgentAsync(
     agentName: "ResearcherAgent",
-    agentDefinition: new PromptAgentDefinition(modelName)
+    agentDefinition: new DeclarativeAgentDefinition(modelName)
     {
         Instructions = "You are a research specialist..."
     },