Merge pull request #738 from jozkee/docs_agent_types

Suggestions for user-guide/agents/agent-types C# sections

Author: TaoChenOSU

agent-framework/user-guide/agents/agent-types/TOC.yml

@@ -2,8 +2,10 @@
   href: index.md
 - name: Azure AI Foundry Agents
   href: azure-ai-foundry-agent.md
-- name: Azure AI Foundry Models Agents
-  href: azure-ai-foundry-models.md
+- name: Azure AI Foundry Models Agents via ChatCompletion
+  href: azure-ai-foundry-models-chat-completion-agent.md
+- name: Azure AI Foundry Models Agents via Responses
+  href: azure-ai-foundry-models-responses-agent.md
 - name: Azure OpenAI ChatCompletion Agents
   href: azure-openai-chat-completion-agent.md
 - name: Azure OpenAI Responses Agents

agent-framework/user-guide/agents/agent-types/azure-ai-foundry-agent.md

@@ -11,13 +11,13 @@ ms.service: agent-framework
 
 # Azure AI Foundry Agents
 
-The Microsoft Agent Framework supports creating agents that use the [Azure AI Foundry Agents](/azure/ai-foundry/agents/overview) service.
+The Microsoft Agent Framework supports creating agents that use the [Azure AI Foundry Agents](/azure/ai-foundry/agents/overview) service, you can create persistent service-based agent instances with service-managed conversation threads.
 
 ::: zone pivot="programming-language-csharp"
 
 ## Getting Started
 
-Add the Agents Azure AI NuGet package to your project.
+Add the required NuGet packages to your project.
 
 ```powershell
 dotnet add package Azure.Identity
@@ -55,6 +55,9 @@ var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync
 
 // 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 the Agent Framework helpers
@@ -341,4 +344,4 @@ See the [Agent getting started tutorials](../../../tutorials/overview.md) for mo
 ## Next steps
 
 > [!div class="nextstepaction"]
-> [Azure AI Foundry Models based Agents](./azure-ai-foundry-models.md)
+> [Azure AI Foundry Models based Agents](./azure-ai-foundry-models-chat-completion-agent.md)

…s/agent-types/azure-ai-foundry-models.md …-foundry-models-chat-completion-agent.mdagent-framework/user-guide/agents/agent-types/azure-ai-foundry-models.md renamed to agent-framework/user-guide/agents/agent-types/azure-ai-foundry-models-chat-completion-agent.md agent-framework/user-guide/agents/agent-types/azure-ai-foundry-models.md renamed to agent-framework/user-guide/agents/agent-types/azure-ai-foundry-models-chat-completion-agent.md

@@ -1,6 +1,6 @@
 ---
-title: Azure AI Foundry Models Agents
-description: Learn how to use the Microsoft Agent Framework with Azure AI Foundry Models service.
+title: Azure AI Foundry Models ChatCompletion Agents
+description: Learn how to use the Microsoft Agent Framework with Azure AI Foundry Models service via OpenAI ChatCompletion API.
 zone_pivot_groups: programming-languages
 author: westey-m
 ms.topic: tutorial
@@ -11,8 +11,9 @@ ms.service: agent-framework
 
 # Azure AI Foundry Models Agents
 
+The Microsoft Agent Framework supports creating agents using models deployed with Azure AI Foundry Models via an OpenAI Chat Completion compatible API, and therefore the OpenAI client libraries can be used to access Foundry models.
+
 [Azure AI Foundry supports deploying](/azure/ai-foundry/foundry-models/how-to/create-model-deployments?pivots=ai-foundry-portal) a wide range of models, including open source models.
-Microsoft Agent Framework can create agents that use these models.
 
 > [!NOTE]
 > The capabilities of these models may limit the functionality of the agents. For example, many open source models do not support function calling and therefore any agent based on such models will not be able to use function tools.
@@ -21,11 +22,10 @@ Microsoft Agent Framework can create agents that use these models.
 
 ## Getting Started
 
-Foundry supports accessing models via an OpenAI Chat Completion compatible API, and therefore the OpenAI client libraries can be used to access Foundry models.
-
 Add the required NuGet packages to your project.
 
 ```powershell
+dotnet add package Azure.Identity
 dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
 ```
 
@@ -37,24 +37,18 @@ Since the code is not using the default OpenAI service, the URI of the OpenAI co
 
 ```csharp
 using System;
+using System.ClientModel.Primitives;
+using Azure.Identity;
 using Microsoft.Agents.AI;
 using OpenAI;
 
-var clientOptions = new OpenAIClientOptions() { Endpoint = new Uri("https://ai-foundry-<your-resource>.services.ai.azure.com/openai/v1/") };
-```
-
-There are different options for constructing the `OpenAIClient` depending on the desired authentication method. Let's look at two common options.
-
-The first option uses an API key.
+var clientOptions = new OpenAIClientOptions() { Endpoint = new Uri("https://<myresource>.services.ai.azure.com/openai/v1/") };
 
-```csharp
-OpenAIClient client = new OpenAIClient(new ApiKeyCredential("<your_api_key>"), clientOptions);
-```
-
-The second option uses token based authentication, and here it is using the Azure CLI credential to get a token.
-
-```csharp
+#pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates.
 OpenAIClient client = new OpenAIClient(new BearerTokenPolicy(new AzureCliCredential(), "https://ai.azure.com/.default"), clientOptions);
+#pragma warning restore OPENAI001
+// You can optionally authenticate with an API key
+// OpenAIClient client = new OpenAIClient(new ApiKeyCredential("<your_api_key>"), clientOptions);
 ```
 
 A client for chat completions can then be created using the model deployment name.
@@ -69,13 +63,16 @@ Finally, the agent can be created using the `CreateAIAgent` extension method on
 AIAgent agent = chatCompletionClient.CreateAIAgent(
     instructions: "You are good at telling jokes.",
     name: "Joker");
+
+// Invoke the agent and output the text result.
+Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
 ```
 
 ## 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](../../../tutorials/overview.md)
+See the [Agent getting started tutorials](../../../tutorials/overview.md) for more information on how to run and interact with agents.
 
 ::: zone-end
 ::: zone pivot="programming-language-python"
@@ -87,4 +84,4 @@ More docs coming soon.
 ## Next steps
 
 > [!div class="nextstepaction"]
-> [Azure OpenAI ChatCompletion Agents](./azure-openai-chat-completion-agent.md)
+> [Azure OpenAI ChatCompletion Agents](./azure-ai-foundry-models-responses-agent.md)

agent-framework/user-guide/agents/agent-types/azure-ai-foundry-models-responses-agent.md

@@ -0,0 +1,84 @@
+---
+title: Azure AI Foundry Models Responses Agents
+description: Learn how to use the Microsoft Agent Framework with Azure AI Foundry Models service via OpenAI Responses API.
+zone_pivot_groups: programming-languages
+author: jozkee
+ms.topic: tutorial
+ms.author: dacantu
+ms.date: 10/22/2025
+ms.service: agent-framework
+---
+
+# Azure AI Foundry Models Responses Agents
+
+The Microsoft Agent Framework supports creating agents using models deployed with Azure AI Foundry Models via an OpenAI Responses compatible API, and therefore the OpenAI client libraries can be used to access Foundry models.
+
+::: zone pivot="programming-language-csharp"
+
+## Getting Started
+
+Add the required NuGet packages to your project.
+
+```powershell
+dotnet add package Azure.Identity
+dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
+```
+
+## Creating an OpenAI Responses Agent with Foundry Models
+
+As a first step you need to create a client to connect to the OpenAI service.
+
+Since the code is not using the default OpenAI service, the URI of the OpenAI compatible Foundry service, needs to be provided via `OpenAIClientOptions`.
+
+```csharp
+using System;
+using System.ClientModel.Primitives;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using OpenAI;
+
+var clientOptions = new OpenAIClientOptions() { Endpoint = new Uri("https://<myresource>.services.ai.azure.com/openai/v1/") };
+
+#pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates.
+OpenAIClient client = new OpenAIClient(new BearerTokenPolicy(new AzureCliCredential(), "https://ai.azure.com/.default"), clientOptions);
+#pragma warning restore OPENAI001
+// You can optionally authenticate with an API key
+// OpenAIClient client = new OpenAIClient(new ApiKeyCredential("<your_api_key>"), clientOptions);
+```
+
+A client for responses can then be created using the model deployment name.
+
+```csharp
+#pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates.
+var responseClient = client.GetOpenAIResponseClient("gpt-4o-mini");
+#pragma warning restore OPENAI001
+```
+
+Finally, the agent can be created using the `CreateAIAgent` extension method on the `ResponseClient`.
+
+```csharp
+AIAgent agent = responseClient.CreateAIAgent(
+    instructions: "You are good at telling jokes.",
+    name: "Joker");
+
+// Invoke the agent and output the text result.
+Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
+```
+
+## Using the Agent
+
+The agent is a standard `AIAgent` and supports all standard `AIAgent` operations.
+
+See the [Agent getting started tutorials](../../../tutorials/overview.md) for more information on how to run and interact with agents.
+
+::: zone-end
+::: zone pivot="programming-language-python"
+
+More docs coming soon.
+
+::: zone-end
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Azure OpenAI Responses Agents](./azure-openai-responses-agent.md)

agent-framework/user-guide/agents/agent-types/azure-openai-chat-completion-agent.md

@@ -20,9 +20,9 @@ The Microsoft Agent Framework supports creating agents that use the [Azure OpenA
 Add the required NuGet packages to your project.
 
 ```powershell
-dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
-dotnet add package Azure.AI.OpenAI
+dotnet add package Azure.AI.OpenAI --prerelease
 dotnet add package Azure.Identity
+dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
 ```
 
 ## Creating an Azure OpenAI ChatCompletion Agent
@@ -99,6 +99,7 @@ Get responses as they are generated using streaming:
 AIAgent agent = chatCompletionClient.CreateAIAgent(
     instructions: "You are good at telling jokes.",
     name: "Joker");
+
 // Invoke the agent with streaming support.
 await foreach (var update in agent.RunStreamingAsync("Tell me a joke about a pirate."))
 {

agent-framework/user-guide/agents/agent-types/azure-openai-responses-agent.md

@@ -11,7 +11,7 @@ ms.service: agent-framework
 
 # Azure OpenAI Responses Agents
 
-The Microsoft Agent Framework supports creating agents that use the [Azure OpenAI responses](/azure/ai-foundry/openai/how-to/responses) service.
+The Microsoft Agent Framework supports creating agents that use the [Azure OpenAI Responses](/azure/ai-foundry/openai/how-to/responses) service.
 
 ::: zone pivot="programming-language-csharp"
 
@@ -20,9 +20,9 @@ The Microsoft Agent Framework supports creating agents that use the [Azure OpenA
 Add the required NuGet packages to your project.
 
 ```powershell
-dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
-dotnet add package Azure.AI.OpenAI
+dotnet add package Azure.AI.OpenAI --prerelease
 dotnet add package Azure.Identity
+dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
 ```
 
 ## Creating an Azure OpenAI Responses Agent
@@ -37,15 +37,17 @@ using Microsoft.Agents.AI;
 using OpenAI;
 
 AzureOpenAIClient client = new AzureOpenAIClient(
-    new Uri("https://<myresource>.openai.azure.com"),
+    new Uri("https://<myresource>.openai.azure.com/openai/v1/"),
     new AzureCliCredential());
 ```
 
 Azure OpenAI supports multiple services that all provide model calling capabilities.
 We need to pick the Responses service to create a Responses based agent.
 
 ```csharp
+#pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates.
 var responseClient = client.GetOpenAIResponseClient("gpt-4o-mini");
+#pragma warning restore OPENAI001
 ```
 
 Finally, create the agent using the `CreateAIAgent` extension method on the `ResponseClient`.
@@ -54,6 +56,9 @@ Finally, create the agent using the `CreateAIAgent` extension method on the `Res
 AIAgent agent = responseClient.CreateAIAgent(
     instructions: "You are good at telling jokes.",
     name: "Joker");
+
+// Invoke the agent and output the text result.
+Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
 ```
 
 ## Using the Agent

agent-framework/user-guide/agents/agent-types/chat-client-agent.md

@@ -53,6 +53,9 @@ AIAgent agent = new ChatClientAgent(
     chatClient,
     instructions: "You are good at telling jokes.",
     name: "Joker");
+
+// Invoke the agent and output the text result.
+Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
 ```
 
 > [!IMPORTANT]

agent-framework/user-guide/agents/agent-types/index.md

@@ -34,7 +34,7 @@ These agents support a wide range of functionality out of the box:
 1. Custom service provided tools (e.g. MCP, Code Execution)
 1. Structured output
 
-To create one of these agents, simply construct a `ChatClientAgent` using the ChatClient implementation of your choice.
+To create one of these agents, simply construct a `ChatClientAgent` using the `IChatClient` implementation of your choice.
 
 ```csharp
 using Microsoft.Agents.AI;
@@ -48,17 +48,18 @@ See the documentation for each service, for more information:
 |Underlying Inference Service|Description|Service Chat History storage supported|Custom Chat History storage supported|
 |---|---|---|---|
 |[Azure AI Foundry Agent](./azure-ai-foundry-agent.md)|An agent that uses the Azure AI Foundry Agents Service as its backend.|Yes|No|
-|[Azure AI Foundry Models](./azure-ai-foundry-models.md)|An agent that uses any of the models deployed in the Azure AI Foundry Service as its backend.|No|Yes|
+|[Azure AI Foundry Models ChatCompletion](./azure-ai-foundry-models-chat-completion-agent.md)|An agent that uses any of the models deployed in the Azure AI Foundry Service as its backend via ChatCompletion.|No|Yes|
+|[Azure AI Foundry Models Responses](./azure-ai-foundry-models-responses-agent.md)|An agent that uses any of the models deployed in the Azure AI Foundry Service as its backend via Responses.|No|Yes|
 |[Azure OpenAI ChatCompletion](./azure-openai-chat-completion-agent.md)|An agent that uses the Azure OpenAI ChatCompletion service.|No|Yes|
 |[Azure OpenAI Responses](./azure-openai-responses-agent.md)|An agent that uses the Azure OpenAI Responses service.|Yes|Yes|
 |[OpenAI ChatCompletion](./openai-chat-completion-agent.md)|An agent that uses the OpenAI ChatCompletion service.|No|Yes|
 |[OpenAI Responses](./openai-responses-agent.md)|An agent that uses the OpenAI Responses service.|Yes|Yes|
 |[OpenAI Assistants](./openai-assistants-agent.md)|An agent that uses the OpenAI Assistants service.|Yes|No|
-|[Any other ChatClient](./chat-client-agent.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|
+|[Any other `IChatClient`](./chat-client-agent.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
 
-It is also possible to create fully custom agents, that are not just wrappers around a ChatClient.
+It is also possible to create fully custom agents, that are not just wrappers around an `IChatClient`.
 The agent framework provides the `AIAgent` base type.
 This base type is the core abstraction for all agents, which when subclassed allows for complete control over the agent's behavior and capabilities.
 

agent-framework/user-guide/agents/agent-types/openai-assistants-agent.md

@@ -39,10 +39,12 @@ OpenAIClient client = new OpenAIClient("<your_api_key>");
 ```
 
 OpenAI supports multiple services that all provide model calling capabilities.
-We need to pick the Assistants service to create an Assistants based agent.
+We will use the Assistants client to create an Assistants based agent.
 
 ```csharp
+#pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates.
 var assistantClient = client.GetAssistantClient();
+#pragma warning restore OPENAI001
 ```
 
 To use the OpenAI Assistants service, you need create an assistant resource in the service.
@@ -60,6 +62,9 @@ var createResult = await assistantClient.CreateAssistantAsync(
 
 // Retrieve the assistant as an AIAgent
 AIAgent agent1 = await assistantClient.GetAIAgentAsync(createResult.Value.Id);
+
+// Invoke the agent and output the text result.
+Console.WriteLine(await agent1.RunAsync("Tell me a joke about a pirate."));
 ```
 
 ### Using the Agent Framework helpers

agent-framework/user-guide/agents/agent-types/openai-chat-completion-agent.md

@@ -48,6 +48,9 @@ Finally, create the agent using the `CreateAIAgent` extension method on the `Cha
 AIAgent agent = chatCompletionClient.CreateAIAgent(
     instructions: "You are good at telling jokes.",
     name: "Joker");
+
+// Invoke the agent and output the text result.
+Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
 ```
 
 ## Using the Agent