.NET: Foundry V2 - Update Sample and Docs for clear distinction between Classic/New Foundry Agents. (#2459)

* Address potential confusion around agent version vs API version

* Address potential confusion around agent version vs API version

* Add extra documentation for clarity

* Remove V2 remainers

* Apply suggestions from code review

Co-authored-by: Copilot <[email protected]>
Co-authored-by: westey <[email protected]>

* Apply suggestions from code review

Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: Copilot <[email protected]>
Co-authored-by: westey <[email protected]>

Author: 3 people

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureAIAgentsPersistent/README.md

@@ -1,3 +1,13 @@
+# Classic Foundry Agents 
+
+This sample demonstrates how to create an agent using the classic Foundry Agents experience.
+
+# Classic vs New Foundry Agents
+
+Below is a comparison between the classic and new Foundry Agents approaches:
+
+[Migration Guide](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/migrate?view=foundry)
+
 # Prerequisites
 
 Before you begin, ensure you have the following prerequisites:

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureAIProject/Program.cs

@@ -10,35 +10,34 @@
 var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
-const string JokerInstructions = "You are good at telling jokes.";
 const string JokerName = "JokerAgent";
 
 // Get a client to create/retrieve/delete server side agents with Azure Foundry Agents.
 var aiProjectClient = new AIProjectClient(new Uri(endpoint), new AzureCliCredential());
 
 // Define the agent you want to create. (Prompt Agent in this case)
-var agentVersionCreationOptions = new AgentVersionCreationOptions(new PromptAgentDefinition(model: deploymentName) { Instructions = JokerInstructions });
+var agentVersionCreationOptions = new AgentVersionCreationOptions(new PromptAgentDefinition(model: deploymentName) { Instructions = "You are good at telling jokes." });
 // Azure.AI.Agents SDK creates and manages agent by name and versions.
 // You can create a server side agent version with the Azure.AI.Agents SDK client below.
-var agentVersion = aiProjectClient.Agents.CreateAgentVersion(agentName: JokerName, options: agentVersionCreationOptions);
+var createdAgentVersion = aiProjectClient.Agents.CreateAgentVersion(agentName: JokerName, options: agentVersionCreationOptions);
 
 // Note:
 //      agentVersion.Id = "<agentName>:<versionNumber>",
 //      agentVersion.Version = <versionNumber>,
 //      agentVersion.Name = <agentName>
 
-// You can retrieve an AIAgent for a already created server side agent version.
-AIAgent jokerAgentV1 = aiProjectClient.GetAIAgent(agentVersion);
+// You can retrieve an AIAgent for an already created server side agent version.
+AIAgent existingJokerAgent = aiProjectClient.GetAIAgent(createdAgentVersion);
 
-// You can also create another AIAgent version (V2) by providing the same name with a different definition.
-AIAgent jokerAgentV2 = aiProjectClient.CreateAIAgent(name: JokerName, model: deploymentName, instructions: JokerInstructions + "V2");
+// You can also create another AIAgent version by providing the same name with a different definition.
+AIAgent newJokerAgent = aiProjectClient.CreateAIAgent(name: JokerName, model: deploymentName, instructions: "You are extremely hilarious at telling jokes.");
 
 // You can also get the AIAgent latest version just providing its name.
 AIAgent jokerAgentLatest = aiProjectClient.GetAIAgent(name: JokerName);
-var latestVersion = jokerAgentLatest.GetService<AgentVersion>()!;
+var latestAgentVersion = jokerAgentLatest.GetService<AgentVersion>()!;
 
 // The AIAgent version can be accessed via the GetService method.
-Console.WriteLine($"Latest agent version id: {latestVersion.Id}");
+Console.WriteLine($"Latest agent version id: {latestAgentVersion.Id}");
 
 // Once you have the AIAgent, you can invoke it like any other AIAgent.
 AgentThread thread = jokerAgentLatest.GetNewThread();
@@ -47,5 +46,5 @@
 // This will use the same thread to continue the conversation.
 Console.WriteLine(await jokerAgentLatest.RunAsync("Now tell me a joke about a cat and a dog using last joke as the anchor.", thread));
 
-// Cleanup by agent name removes both agent versions created (jokerAgentV1 + jokerAgentV2).
-aiProjectClient.Agents.DeleteAgent(jokerAgentV1.Name);
+// Cleanup by agent name removes both agent versions created.
+aiProjectClient.Agents.DeleteAgent(existingJokerAgent.Name);

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureAIProject/README.md

@@ -1,3 +1,13 @@
+# New Foundry Agents 
+
+This sample demonstrates how to create an agent using the new Foundry Agents experience. 
+
+# Classic vs New Foundry Agents
+
+Below is a comparison between the classic and new Foundry Agents approaches:
+
+[Migration Guide](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/migrate?view=foundry)
+
 # Prerequisites
 
 Before you begin, ensure you have the following prerequisites:

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step01.1_Basics/Program.cs

@@ -11,40 +11,38 @@
 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";
 
-const string JokerInstructionsV1 = "You are good at telling jokes.";
-const string JokerInstructionsV2 = "You are extremely hilarious at telling jokes.";
 const string JokerName = "JokerAgent";
 
 // 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 you want to create. (Prompt Agent in this case)
-AgentVersionCreationOptions options = new(new PromptAgentDefinition(model: deploymentName) { Instructions = JokerInstructionsV1 });
+AgentVersionCreationOptions options = new(new PromptAgentDefinition(model: deploymentName) { Instructions = "You are good at telling jokes." });
 
 // Azure.AI.Agents SDK creates and manages agent by name and versions.
 // You can create a server side agent version with the Azure.AI.Agents SDK client below.
-AgentVersion agentVersion = aiProjectClient.Agents.CreateAgentVersion(agentName: JokerName, options);
+AgentVersion createdAgentVersion = aiProjectClient.Agents.CreateAgentVersion(agentName: JokerName, options);
 
 // Note:
 //      agentVersion.Id = "<agentName>:<versionNumber>",
 //      agentVersion.Version = <versionNumber>,
 //      agentVersion.Name = <agentName>
 
 // You can retrieve an AIAgent for an already created server side agent version.
-AIAgent jokerAgentV1 = aiProjectClient.GetAIAgent(agentVersion);
+AIAgent existingJokerAgent = aiProjectClient.GetAIAgent(createdAgentVersion);
 
-// You can also create another AIAgent version (V2) by providing the same name with a different definition/instruction.
-AIAgent jokerAgentV2 = aiProjectClient.CreateAIAgent(name: JokerName, model: deploymentName, instructions: JokerInstructionsV2);
+// You can also create another AIAgent version by providing the same name with a different definition/instruction.
+AIAgent newJokerAgent = aiProjectClient.CreateAIAgent(name: JokerName, model: deploymentName, instructions: "You are extremely hilarious at telling jokes.");
 
 // You can also get the AIAgent latest version by just providing its name.
 AIAgent jokerAgentLatest = aiProjectClient.GetAIAgent(name: JokerName);
-AgentVersion latestVersion = jokerAgentLatest.GetService<AgentVersion>()!;
+AgentVersion latestAgentVersion = jokerAgentLatest.GetService<AgentVersion>()!;
 
 // The AIAgent version can be accessed via the GetService method.
-Console.WriteLine($"Latest agent version id: {latestVersion.Id}");
+Console.WriteLine($"Latest agent version id: {latestAgentVersion.Id}");
 
 // Once you have the AIAgent, you can invoke it like any other AIAgent.
 Console.WriteLine(await jokerAgentLatest.RunAsync("Tell me a joke about a pirate."));
 
-// Cleanup by agent name removes both agent versions created (jokerAgentV1 + jokerAgentV2).
-await aiProjectClient.Agents.DeleteAgentAsync(jokerAgentV1.Name);
+// Cleanup by agent name removes both agent versions created.
+await aiProjectClient.Agents.DeleteAgentAsync(existingJokerAgent.Name);

dotnet/samples/GettingStarted/FoundryAgents/README.md

@@ -6,6 +6,15 @@ of Azure Foundry Agents and can be used with Azure Foundry as the AI provider.
 These samples showcase how to work with agents managed through Azure Foundry, including agent creation,
 versioning, multi-turn conversations, and advanced features like code interpretation and computer use.
 
+## Classic vs New Foundry Agents
+
+> [!NOTE]
+> Recently, Azure Foundry introduced a new and improved experience for creating and managing AI agents, which is the target of these samples.
+
+For more information about the previous classic agents and for what's new in Foundry Agents, see the [Foundry Agents migration documentation](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/migrate?view=foundry).
+
+For a sample demonstrating how to use classic Foundry Agents, see the following: [Agent with Azure AI Persistent](../AgentProviders/Agent_With_AzureAIAgentsPersistent/README.md).
+
 ## Getting started with Foundry Agents prerequisites
 
 Before you begin, ensure you have the following prerequisites: