Merge pull request #957 from MicrosoftDocs/foundry-updates-0002

Migrate C# samples to AIProjectClient and update Microsoft Foundry provider docs

Author: rogerbarreto

agent-framework/agents/agent-pipeline.md

@@ -157,9 +157,10 @@ The chat client layer handles the actual communication with the LLM service.
 `ChatClientAgent` uses an `IChatClient` instance, which can be decorated with additional middleware:
 
 ```csharp
-var chatClient = new AzureOpenAIClient(endpoint, credential)
-    .GetChatClient(deploymentName)
-    .AsIChatClient()
+var chatClient = new AIProjectClient(endpoint, credential)
+    .GetProjectOpenAIClient()
+    .GetProjectResponsesClient()
+    .AsIChatClient(deploymentName)
     .AsBuilder()
     .Use(CustomChatClientMiddleware)
     .Build();
@@ -170,9 +171,10 @@ var agent = new ChatClientAgent(chatClient, instructions: "You are helpful.");
 You can also use `AIContextProvider` as chat client middleware to enrich messages, tools, and instructions at the client level. This must be used within the context of a running `AIAgent`:
 
 ```csharp
-var chatClient = new AzureOpenAIClient(endpoint, credential)
-    .GetChatClient(deploymentName)
-    .AsIChatClient()
+var chatClient = new AIProjectClient(endpoint, credential)
+    .GetProjectOpenAIClient()
+    .GetProjectResponsesClient()
+    .AsIChatClient(deploymentName)
     .AsBuilder()
     .UseAIContextProviders(new MyContextProvider())
     .Build();

agent-framework/agents/background-responses.md

@@ -55,11 +55,10 @@ Some agents may not allow explicit control over background responses. These agen
 For non-streaming scenarios, when you initially run an agent, it may or may not return a continuation token. If no continuation token is returned, it means the operation has completed. If a continuation token is returned, it indicates that the agent has initiated a background response that is still processing and will require polling to retrieve the final result:
 
 ```csharp
-AIAgent agent = new AzureOpenAIClient(
-    new Uri("https://<myresource>.openai.azure.com"),
+AIAgent agent = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
     new DefaultAzureCredential())
-    .GetResponsesClient("<deployment-name>")
-    .AsAIAgent();
+    .AsAIAgent(model: "<deployment-name>", instructions: "You are a helpful assistant.");
 
 AgentRunOptions options = new()
 {
@@ -100,11 +99,10 @@ Console.WriteLine(response.Text);
 In streaming scenarios, background responses work much like regular streaming responses - the agent streams all updates back to consumers in real-time. However, the key difference is that if the original stream gets interrupted, agents support stream resumption through continuation tokens. Each update includes a continuation token that captures the current state, allowing the stream to be resumed from exactly where it left off by passing this token to subsequent streaming API calls:
 
 ```csharp
-AIAgent agent = new AzureOpenAIClient(
-    new Uri("https://<myresource>.openai.azure.com"),
+AIAgent agent = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
     new DefaultAzureCredential())
-    .GetResponsesClient("<deployment-name>")
-    .AsAIAgent();
+    .AsAIAgent(model: "<deployment-name>", instructions: "You are a helpful assistant.");
 
 AgentRunOptions options = new()
 {

agent-framework/agents/declarative.md

@@ -18,17 +18,17 @@ 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 Azure.AI.OpenAI;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
 
 // Create the chat client
-IChatClient chatClient = new AzureOpenAIClient(
-    new Uri("https://<myresource>.openai.azure.com"),
+IChatClient chatClient = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
     new DefaultAzureCredential())
-     .GetChatClient("gpt-4o-mini")
-     .AsIChatClient();
+        .GetProjectOpenAIClient()
+        .GetProjectResponsesClient()
+        .AsIChatClient("gpt-4o-mini");
 
 // Define the agent using a YAML definition.
 var yamlDefinition =
@@ -67,6 +67,9 @@ await foreach (var update in agent!.RunStreamingAsync("Tell me a joke about a pi
 }
 ```
 
+> [!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/index.md

@@ -139,22 +139,23 @@ Once you have created the OpenAIClient, you can get a sub client for the specifi
 
 ```csharp
 AIAgent agent = client
-    .GetChatClient(model)
-    .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
+    .AsAIAgent(model: model, instructions: "You are good at telling jokes.", name: "Joker");
 ```
 
-### Using the Azure OpenAI SDK
+### Using the Azure AI Projects SDK
 
-This SDK can be used to connect to both Azure OpenAI and Foundry Models services.
-Either way, you will need to supply the correct service URL when creating the `AzureOpenAIClient`.
+This SDK can be used to connect to Foundry services.
+You will need to supply the correct project endpoint URL when creating the `AIProjectClient`.
 See the table above for the correct URL to use.
 
 ```csharp
-AIAgent agent = new AzureOpenAIClient(
+AIAgent agent = new AIProjectClient(
     new Uri(serviceUrl),
     new DefaultAzureCredential())
-     .GetChatClient(deploymentName)
-     .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
+     .AsAIAgent(
+         model: deploymentName,
+         instructions: "You are good at telling jokes.",
+         name: "Joker");
 ```
 
 ### Using the Azure AI Persistent Agents SDK

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

@@ -184,7 +184,7 @@ var chatClient = new AIProjectClient(
     new Uri("<your-foundry-project-endpoint>"),
     new DefaultAzureCredential())
         .GetProjectOpenAIClient()
-        .GetResponsesClient()
+        .GetProjectResponsesClient()
         .AsIChatClient("gpt-4o-mini");
 
 var middlewareEnabledChatClient = chatClient

agent-framework/agents/middleware/index.md

@@ -47,7 +47,7 @@ var chatClient = new AIProjectClient(
     new Uri("<your-foundry-project-endpoint>"),
     new DefaultAzureCredential())
         .GetProjectOpenAIClient()
-        .GetResponsesClient()
+        .GetProjectResponsesClient()
         .AsIChatClient(deploymentName);
 
 var middlewareEnabledChatClient = chatClient

agent-framework/agents/multimodal.md

@@ -22,11 +22,11 @@ You can send images to an agent by creating a `ChatMessage` that includes both t
 First, create an `AIAgent` that is able to analyze images.
 
 ```csharp
-AIAgent agent = new AzureOpenAIClient(
-    new Uri("https://<myresource>.openai.azure.com"),
+AIAgent agent = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
     new DefaultAzureCredential())
-    .GetChatClient("gpt-4o")
     .AsAIAgent(
+        model: "gpt-4o",
         name: "VisionAgent",
         instructions: "You are a helpful agent that can analyze images");
 ```

agent-framework/agents/observability.md

@@ -26,10 +26,11 @@ Agent Framework integrates with [OpenTelemetry](https://opentelemetry.io/), and
 To enable observability for your chat client, you need to build the chat client as follows:
 
 ```csharp
-// Using the Azure OpenAI client as an example
-var instrumentedChatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
-    .GetChatClient(deploymentName)
-    .AsIChatClient() // Converts a native OpenAI SDK ChatClient into a Microsoft.Extensions.AI.IChatClient
+// Using the AIProjectClient as an example
+var instrumentedChatClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .GetProjectOpenAIClient()
+    .GetProjectResponsesClient()
+    .AsIChatClient(deploymentName) // Converts into a Microsoft.Extensions.AI.IChatClient
     .AsBuilder()
     .UseOpenTelemetry(sourceName: SourceName, configure: (cfg) => cfg.EnableSensitiveData = true)    // Enable OpenTelemetry instrumentation with sensitive data
     .Build();

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

@@ -21,74 +21,78 @@ Add the required NuGet packages to your project.
 
 ```dotnetcli
 dotnet add package Azure.Identity
-dotnet add package Microsoft.Agents.AI.AzureAI.Persistent --prerelease
+dotnet add package Microsoft.Agents.AI.Foundry --prerelease
 ```
 
-## Create Foundry Agents
+## Two agent types
 
-As a first step you need to create a client to connect to the Agent Service.
+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 |
+
+## Responses Agent (direct inference)
+
+Use `AsAIAgent` on `AIProjectClient` directly with a model and instructions. This is the recommended starting point for most scenarios.
 
 ```csharp
-using System;
-using Azure.AI.Agents.Persistent;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 
-var persistentAgentsClient = new PersistentAgentsClient(
-    "https://<myresource>.services.ai.azure.com/api/projects/<myproject>",
-    new DefaultAzureCredential());
+AIAgent agent = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
+    new DefaultAzureCredential())
+        .AsAIAgent(
+            model: "gpt-4o-mini",
+            name: "Joker",
+            instructions: "You are good at telling jokes.");
+
+Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
 ```
 
 > [!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.
 
-To use the Agent Service, you need create an agent resource in the service.
-This can be done using either the Azure.AI.Agents.Persistent SDK or using Microsoft Agent Framework helpers.
+This path is code-first and does not create a server-managed agent resource.
 
-### Using the Persistent SDK
+## Foundry Agent (versioned)
 
-Create a persistent agent and retrieve it as an `AIAgent` using the `PersistentAgentsClient`.
+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`.
 
 ```csharp
-// Create a persistent agent
-var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(
-    model: "gpt-4o-mini",
-    name: "Joker",
-    instructions: "You are good at telling jokes.");
-
-// Retrieve the agent that was just created as an AIAgent using its ID
-AIAgent agent1 = await persistentAgentsClient.GetAIAgentAsync(agentMetadata.Value.Id);
-
-// Invoke the agent and output the text result.
-Console.WriteLine(await agent1.RunAsync("Tell me a joke about a pirate."));
-```
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry;
 
-### Using Agent Framework helpers
+var aiProjectClient = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
+    new DefaultAzureCredential());
 
-You can also create and return an `AIAgent` in one step:
+// Retrieve an existing agent by name (uses the latest version automatically)
+AgentRecord jokerRecord = await aiProjectClient.Agents.GetAgentAsync("Joker");
+FoundryAgent agent = aiProjectClient.AsAIAgent(jokerRecord);
 
-```csharp
-AIAgent agent2 = await persistentAgentsClient.CreateAIAgentAsync(
-    model: "gpt-4o-mini",
-    name: "Joker",
-    instructions: "You are good at telling jokes.");
+Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
 ```
 
-## Reusing Foundry Agents
+> [!IMPORTANT]
+> Foundry Agents tools and instructions are strict to the ones it was created with, attempting to modify tooling or instructions at runtime is not supported.
+
+## Using the agent
 
-You can reuse existing Foundry Agents by retrieving them using their IDs.
+Both `ChatClientAgent` (Responses) and `FoundryAgent` (versioned) are standard `AIAgent` instances and support all standard operations including sessions, tools, middleware, and streaming.
 
 ```csharp
-AIAgent agent3 = await persistentAgentsClient.GetAIAgentAsync("<agent-id>");
+AgentSession session = await agent.CreateSessionAsync();
+Console.WriteLine(await agent.RunAsync("Tell me a joke.", session));
+Console.WriteLine(await agent.RunAsync("Now make it funnier.", session));
 ```
 
-> [!TIP]
-> See the [.NET samples](https://github.com/microsoft/agent-framework/tree/main/dotnet/samples) for complete runnable examples.
-
-## Using the agent
-
-The agent is a standard `AIAgent` and supports all standard `AIAgent` operations.
-
 For more information on how to run and interact with agents, see the [Agent getting started tutorials](../../get-started/your-first-agent.md).
 
 ::: zone-end

agent-framework/agents/skills.md

@@ -86,7 +86,7 @@ The Agent Framework includes a skills provider that discovers skills from filesy
 Create a `FileAgentSkillsProvider` pointing to a directory containing your skills, and add it to the agent's context providers:
 
 ```csharp
-using Azure.AI.OpenAI;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
 
@@ -95,20 +95,23 @@ var skillsProvider = new FileAgentSkillsProvider(
     skillPath: Path.Combine(AppContext.BaseDirectory, "skills"));
 
 // Create an agent with the skills provider
-AIAgent agent = new AzureOpenAIClient(
+AIAgent agent = new AIProjectClient(
     new Uri(endpoint), new DefaultAzureCredential())
-    .GetResponsesClient(deploymentName)
     .AsAIAgent(new ChatClientAgentOptions
     {
         Name = "SkillsAgent",
         ChatOptions = new()
         {
+            ModelId = deploymentName,
             Instructions = "You are a helpful assistant.",
         },
         AIContextProviders = [skillsProvider],
     });
 ```
 
+> [!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.
+
 ### Invoking the agent
 
 Once configured, the agent automatically discovers available skills and uses them when a task matches: