From 435fd14da5b42a25a4fe31f1e36a76d13036197d Mon Sep 17 00:00:00 2001
From: westey <164392973+westey-m@users.noreply.github.com>
Date: Mon, 25 Aug 2025 18:11:09 +0100
Subject: [PATCH] Add proposed stucture for samples and user documentation
(#484)
---
dotnet/agent-framework-dotnet.slnx | 6 ++
dotnet/samples/Directory.Build.props | 9 +++
dotnet/samples/GettingStartedSteps/README.md | 68 +++++++++++++++++++
.../Step01_ChatClientAgent_Running/Program.cs | 32 +++++++++
.../Step01_ChatClientAgent_Running.csproj | 23 +++++++
.../Program.cs | 39 +++++++++++
.../Step02_ChatClientAgent_Multiturn.csproj | 23 +++++++
dotnet/samples/README.md | 24 +++++++
dotnet/src/Shared/Demos/SampleEnvironment.cs | 10 +--
user-documentation/dotnet/README.md | 14 ++++
.../dotnet/getting-started/README.md | 39 +++++++++++
.../dotnet/user-guide/README.md | 4 ++
.../dotnet/user-guide/agent-types.md | 41 +++++++++++
.../user-guide/multi-turn-conversations.md | 3 +
14 files changed, 330 insertions(+), 5 deletions(-)
create mode 100644 dotnet/samples/GettingStartedSteps/README.md
create mode 100644 dotnet/samples/GettingStartedSteps/Step01_ChatClientAgent_Running/Program.cs
create mode 100644 dotnet/samples/GettingStartedSteps/Step01_ChatClientAgent_Running/Step01_ChatClientAgent_Running.csproj
create mode 100644 dotnet/samples/GettingStartedSteps/Step02_ChatClientAgent_Multiturn/Program.cs
create mode 100644 dotnet/samples/GettingStartedSteps/Step02_ChatClientAgent_Multiturn/Step02_ChatClientAgent_Multiturn.csproj
create mode 100644 dotnet/samples/README.md
create mode 100644 user-documentation/dotnet/README.md
create mode 100644 user-documentation/dotnet/getting-started/README.md
create mode 100644 user-documentation/dotnet/user-guide/README.md
create mode 100644 user-documentation/dotnet/user-guide/agent-types.md
create mode 100644 user-documentation/dotnet/user-guide/multi-turn-conversations.md
diff --git a/dotnet/agent-framework-dotnet.slnx b/dotnet/agent-framework-dotnet.slnx
index 40dcd00c01..136c1a168d 100644
--- a/dotnet/agent-framework-dotnet.slnx
+++ b/dotnet/agent-framework-dotnet.slnx
@@ -9,6 +9,7 @@
+
@@ -17,6 +18,11 @@
+
+
+
+
+
diff --git a/dotnet/samples/Directory.Build.props b/dotnet/samples/Directory.Build.props
index cf76e03054..564527ad9d 100644
--- a/dotnet/samples/Directory.Build.props
+++ b/dotnet/samples/Directory.Build.props
@@ -7,6 +7,15 @@
false
net472;net9.0
5ee045b0-aea3-4f08-8d31-32d1a6f8fed0
+ $(NoWarn);CA1707
+
+
+
+
+
+
+
+
diff --git a/dotnet/samples/GettingStartedSteps/README.md b/dotnet/samples/GettingStartedSteps/README.md
new file mode 100644
index 0000000000..4b204637f4
--- /dev/null
+++ b/dotnet/samples/GettingStartedSteps/README.md
@@ -0,0 +1,68 @@
+# Getting started steps
+
+The getting started steps samples demonstrate the fundamental concepts and functionalities
+of the agent framework and can be used with any agent type.
+
+While the functionality can be used with any agent type, these samples use Azure OpenAI as the AI provider
+and use ChatCompletion as the type of service.
+
+For other samples that demonstrate how to create and configure each type of agent that come with the agent framework,
+see the [Agent setup](../AgentSetup/README.md) samples.
+
+## Getting started steps prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 8.0 SDK or later
+- Azure OpenAI service endpoint and deployment configured
+- Azure CLI installed and authenticated (for Azure credential authentication)
+
+**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure OpenAI resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
+
+## Samples
+
+|Sample|Description|
+|---|---|
+|[Running a simple agent](./Step01_ChatClientAgent_Running/)|This sample demonstrates how to create and run a basic agent with instructions|
+|[Multi-turn conversation with a simple agent](./Step02_ChatClientAgent_MultiTurn/)|This sample demonstrates how to implement a multi-turn conversation with a simple agent|
+
+## Running the samples from the console
+
+To run the samples, navigate to the desired sample directory, e.g.
+
+```powershell
+cd Step01_ChatClientAgent_Running
+```
+
+Set the following environment variables:
+
+```powershell
+$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" # Replace with your Azure OpenAI resource endpoint
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini" # Optional, defaults to gpt-4o-mini
+```
+
+If the variables are not set, you will be prompted for the values when running the samples.
+
+Execute the following command to build the sample:
+
+```powershell
+dotnet build
+```
+
+Execute the following command to run the sample:
+
+```powershell
+dotnet run --no-build
+```
+
+Or just build and run in one step:
+
+```powershell
+dotnet run
+```
+
+## Running the samples from Visual Studio
+
+Open the solution in Visual Studio and set the desired sample project as the startup project. Then, run the project using the built-in debugger or by pressing `F5`.
+
+You will be prompted for any required environment variables if they are not already set.
diff --git a/dotnet/samples/GettingStartedSteps/Step01_ChatClientAgent_Running/Program.cs b/dotnet/samples/GettingStartedSteps/Step01_ChatClientAgent_Running/Program.cs
new file mode 100644
index 0000000000..c2af5c010e
--- /dev/null
+++ b/dotnet/samples/GettingStartedSteps/Step01_ChatClientAgent_Running/Program.cs
@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to create and use a simple AI agent with Azure OpenAI as the backend.
+
+using System;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Extensions.AI.Agents;
+using OpenAI;
+
+var azureOpenAIEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var azureOpenAIDeploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+
+const string JokerName = "Joker";
+const string JokerInstructions = "You are good at telling jokes.";
+
+AIAgent agent = new AzureOpenAIClient(
+ new Uri(azureOpenAIEndpoint),
+ new AzureCliCredential())
+ .GetChatClient(azureOpenAIDeploymentName)
+ .CreateAIAgent(JokerInstructions, JokerName);
+
+// Invoke the agent and output the text result.
+Console.WriteLine("--- Run the agent ---\n");
+Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
+
+// Invoke the agent with streaming support.
+Console.WriteLine("\n--- Run the agent with streaming ---\n");
+await foreach (var update in agent.RunStreamingAsync("Tell me a joke about a pirate."))
+{
+ Console.Write(update);
+}
diff --git a/dotnet/samples/GettingStartedSteps/Step01_ChatClientAgent_Running/Step01_ChatClientAgent_Running.csproj b/dotnet/samples/GettingStartedSteps/Step01_ChatClientAgent_Running/Step01_ChatClientAgent_Running.csproj
new file mode 100644
index 0000000000..15185f869a
--- /dev/null
+++ b/dotnet/samples/GettingStartedSteps/Step01_ChatClientAgent_Running/Step01_ChatClientAgent_Running.csproj
@@ -0,0 +1,23 @@
+
+
+
+ Exe
+ net9.0
+ 12
+
+ enable
+ disable
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/dotnet/samples/GettingStartedSteps/Step02_ChatClientAgent_Multiturn/Program.cs b/dotnet/samples/GettingStartedSteps/Step02_ChatClientAgent_Multiturn/Program.cs
new file mode 100644
index 0000000000..6b2d0d902a
--- /dev/null
+++ b/dotnet/samples/GettingStartedSteps/Step02_ChatClientAgent_Multiturn/Program.cs
@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to create and use a simple AI agent with a multi-turn conversation.
+
+using System;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Extensions.AI.Agents;
+using OpenAI;
+
+var azureOpenAIEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var azureOpenAIDeploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+
+const string JokerName = "Joker";
+const string JokerInstructions = "You are good at telling jokes.";
+
+AIAgent agent = new AzureOpenAIClient(
+ new Uri(azureOpenAIEndpoint),
+ new AzureCliCredential())
+ .GetChatClient(azureOpenAIDeploymentName)
+ .CreateAIAgent(JokerInstructions, JokerName);
+
+// Invoke the agent with a multi-turn conversation, where the context is preserved in the thread object.
+Console.WriteLine("\n--- Run with a thread (context preserved) ---\n");
+AgentThread thread = agent.GetNewThread();
+Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", thread));
+Console.WriteLine(await agent.RunAsync("Now add some emojis to the joke and tell it in the voice of a pirate's parrot.", thread));
+
+// Invoke the agent with a multi-turn conversation and streaming, where the context is preserved in the thread object.
+Console.WriteLine("\n--- Run with a thread and streaming (context preserved) ---\n");
+thread = agent.GetNewThread();
+await foreach (var update in agent.RunStreamingAsync("Tell me a joke about a pirate.", thread))
+{
+ Console.WriteLine(update);
+}
+await foreach (var update in agent.RunStreamingAsync("Now add some emojis to the joke and tell it in the voice of a pirate's parrot.", thread))
+{
+ Console.WriteLine(update);
+}
diff --git a/dotnet/samples/GettingStartedSteps/Step02_ChatClientAgent_Multiturn/Step02_ChatClientAgent_Multiturn.csproj b/dotnet/samples/GettingStartedSteps/Step02_ChatClientAgent_Multiturn/Step02_ChatClientAgent_Multiturn.csproj
new file mode 100644
index 0000000000..15185f869a
--- /dev/null
+++ b/dotnet/samples/GettingStartedSteps/Step02_ChatClientAgent_Multiturn/Step02_ChatClientAgent_Multiturn.csproj
@@ -0,0 +1,23 @@
+
+
+
+ Exe
+ net9.0
+ 12
+
+ enable
+ disable
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/dotnet/samples/README.md b/dotnet/samples/README.md
new file mode 100644
index 0000000000..0d9d0340b5
--- /dev/null
+++ b/dotnet/samples/README.md
@@ -0,0 +1,24 @@
+# Agent Framework Samples
+
+The agent framework samples are designed to help you get started with building AI-powered agents
+from various providers.
+
+The Agent Framework supports building agents using various infererence and inference-style services.
+All these are supported using the single `ChatClientAgent` class.
+
+The Agent Framework also supports creating proxy agents, that allow accessing remote agents as if they
+were local agents. These are supported using various `AIAgent` subclasses.
+
+## Sample Categories
+
+The samples are subdivided into the following categories:
+
+- [Getting Started Steps](./GettingStartedSteps/README.md): Basic steps to get started with the agent framework.
+ These samples demonstrate the fundamental concepts and functionalities of the agent framework when using the
+ `ChatClientAgent` and can be used with any underlying service that the `ChatClientAgent` supports.
+- [Agent setup](./AgentSetup/README.md): Samples that demonstrate how to create and configure each type of agent that come with the agent framework.
+- [Agent specific features](./AgentSpecificFeatures/README.md): Samples that showcase features specific to each type of agent.
+
+## Prerequisites
+
+For prerequisites see each set of samples for their specific requirements.
diff --git a/dotnet/src/Shared/Demos/SampleEnvironment.cs b/dotnet/src/Shared/Demos/SampleEnvironment.cs
index 80668651ce..37ae808f05 100644
--- a/dotnet/src/Shared/Demos/SampleEnvironment.cs
+++ b/dotnet/src/Shared/Demos/SampleEnvironment.cs
@@ -11,12 +11,15 @@ namespace SampleHelpers;
internal static class SampleEnvironment
{
public static string? GetEnvironmentVariable(string key)
+ => SampleEnvironment.GetEnvironmentVariable(key, EnvironmentVariableTarget.Process);
+
+ public static string? GetEnvironmentVariable(string key, EnvironmentVariableTarget target)
{
// Allows for opting into showing all setting values in the console output, so that it is easy to troubleshoot sample setup issues.
- var showAllSampleValues = SystemEnvironment.GetEnvironmentVariable("AF_SHOW_ALL_DEMO_SETTING_VALUES");
+ var showAllSampleValues = SystemEnvironment.GetEnvironmentVariable("AF_SHOW_ALL_DEMO_SETTING_VALUES", target);
var shouldShowValue = showAllSampleValues?.ToUpperInvariant() == "Y";
- var value = SystemEnvironment.GetEnvironmentVariable(key);
+ var value = SystemEnvironment.GetEnvironmentVariable(key, target);
if (string.IsNullOrWhiteSpace(value))
{
var color = Console.ForegroundColor;
@@ -66,9 +69,6 @@ internal static class SampleEnvironment
// Methods that directly call System.Environment
- public static string? GetEnvironmentVariable(string variable, EnvironmentVariableTarget target)
- => System.Environment.GetEnvironmentVariable(variable, target);
-
public static IDictionary GetEnvironmentVariables()
=> System.Environment.GetEnvironmentVariables();
diff --git a/user-documentation/dotnet/README.md b/user-documentation/dotnet/README.md
new file mode 100644
index 0000000000..91db21c48a
--- /dev/null
+++ b/user-documentation/dotnet/README.md
@@ -0,0 +1,14 @@
+# Microsoft Agent Framework for .NET
+
+## Overview
+
+The Microsoft Agent Framework for .NET provides a set of tools and libraries to help developers create intelligent agents that can interact with users in natural language as well as orchestrate those agents together to perform complex tasks.
+
+The framework, in conjunction with its python counterpart, is the successor of the Semantic Kernel and AutoGen agent frameworks.
+
+## See also
+
+- [Getting Started](./getting-started/)
+- [Migration Guide](./migration-guide/)
+- [User Guide](./user-guide/)
+- [Samples](../../dotnet/samples)
diff --git a/user-documentation/dotnet/getting-started/README.md b/user-documentation/dotnet/getting-started/README.md
new file mode 100644
index 0000000000..8314cae27a
--- /dev/null
+++ b/user-documentation/dotnet/getting-started/README.md
@@ -0,0 +1,39 @@
+# Microsoft Agent Framework for .NET Getting Started
+
+This guide will help you get up and running quickly with a basic agent using the Agent Framework and Azure OpenAI.
+
+## Prerequisites
+
+Before you begin, ensure you have the following:
+
+- [.NET 8.0 SDK or later](https://dotnet.microsoft.com/download)
+- An [Azure OpenAI](https://learn.microsoft.com/azure/ai-services/openai/) resource with a deployed model (e.g., `gpt-4o-mini`)
+- [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed and authenticated (`az login`)
+
+**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure OpenAI resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
+
+## Running a Basic Agent Sample
+
+This sample demonstrates how to create and use a simple AI agent with Azure OpenAI as the backend. It will create a basic agent using `AzureOpenAIClient` with `gpt-4o-mini` and custom instructions.
+
+Make sure to replace `https://your-resource.openai.azure.com/` with the endpoint of your Azure OpenAI resource.
+
+### Sample Code
+
+```csharp
+using System;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Extensions.AI.Agents;
+using OpenAI;
+
+AIAgent agent = new AzureOpenAIClient(
+ new Uri("https://your-resource.openai.azure.com/"),
+ new AzureCliCredential())
+ .GetChatClient("gpt-4o-mini")
+ .CreateAIAgent(instructions: "You are good at telling jokes.");
+
+Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
+```
+
+For more details and more advanced scenarios, see [Getting Started Steps](../../../dotnet/samples/GettingStartedSteps/).
diff --git a/user-documentation/dotnet/user-guide/README.md b/user-documentation/dotnet/user-guide/README.md
new file mode 100644
index 0000000000..26adcc089d
--- /dev/null
+++ b/user-documentation/dotnet/user-guide/README.md
@@ -0,0 +1,4 @@
+# Microsoft Agent Framework for .NET Concepts
+
+- [Agent Types](./agent-types.md)
+- [Multi-turn conversations and Threading](./multi-turn-conversations.md)
diff --git a/user-documentation/dotnet/user-guide/agent-types.md b/user-documentation/dotnet/user-guide/agent-types.md
new file mode 100644
index 0000000000..a0ff932f08
--- /dev/null
+++ b/user-documentation/dotnet/user-guide/agent-types.md
@@ -0,0 +1,41 @@
+# Microsoft Agent Framework for .NET Agent Types
+
+The Microsoft Agent Framework for .NET provides support for several types of agents to accommodate different use cases and requirements.
+
+All agents are derived from a common base class, `AIAgent`, which provides a consistent interface for all agent types. This allows for building common, agent agnostic, higher level functionality such as multi-agent orchestrations.
+
+Let's dive into each agent type in more detail.
+
+## Simple custom agents based on inference services
+
+The agent framework makes it easy to create simple custom agents based on many different inference services.
+Any inference service that provides a `Microsoft.Extensions.AI.IChatClient` implementation can be used to build these agents.
+
+These agents support a wide range of functionality:
+
+1. Function calling
+1. Multi-turn conversations with local chat history management or service provided chat history management
+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 `IChatClient` implementation of your choice:
+
+```csharp
+using Microsoft.Extensions.AI;
+
+var agent = new ChatClientAgent(chatClient, instructions: "You are a helpful asssistant");
+```
+
+For examples on how to construct `ChatClientAgents` with various `IChatClient` implementations, see the [Agent setup samples](../../../dotnet/samples/AgentSetup).
+
+## Complex custom agents
+
+To be added.
+
+## Remote agents
+
+To be added.
+
+## Pre-built agents
+
+To be added.
diff --git a/user-documentation/dotnet/user-guide/multi-turn-conversations.md b/user-documentation/dotnet/user-guide/multi-turn-conversations.md
new file mode 100644
index 0000000000..72f2798bb6
--- /dev/null
+++ b/user-documentation/dotnet/user-guide/multi-turn-conversations.md
@@ -0,0 +1,3 @@
+# Microsoft Agent Framework for .NET Multi-Turn Conversations and Threading
+
+To be added.