agent/agent-framework
2
0
Fork 0
mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add proposed stucture for samples and user documentation (#484)

Browse Source
This commit is contained in:
westey
2025-08-25 18:11:09 +01:00
committed by GitHub
Unverified
parent 5284b611c2
commit 435fd14da5
14 changed files with 330 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dotnet/agent-framework-dotnet.slnx
+6
View File
@@ -9,6 +9,7 @@
<Project Path="demos/MinimalConsole/MinimalConsole.csproj" />
</Folder>
<Folder Name="/Samples/">
<File Path="samples/README.md" />
<Project Path="samples/GettingStarted/GettingStarted.csproj" />
</Folder>
<Folder Name="/Samples/AgentWebChat/">
@@ -17,6 +18,11 @@
<Project Path="samples/AgentWebChat/AgentWebChat.ServiceDefaults/AgentWebChat.ServiceDefaults.csproj" />
<Project Path="samples/AgentWebChat/AgentWebChat.Web/AgentWebChat.Web.csproj" />
</Folder>
<Folder Name="/Samples/GettingStartedSteps/">
<File Path="samples/GettingStartedSteps/README.md" />
<Project Path="samples/GettingStartedSteps/Step01_ChatClientAgent_Running/Step01_ChatClientAgent_Running.csproj" />
<Project Path="samples/GettingStartedSteps/Step02_ChatClientAgent_Multiturn/Step02_ChatClientAgent_Multiturn.csproj" />
</Folder>
<Folder Name="/Solution Items/">
<File Path=".editorconfig" />
<File Path=".gitignore" />
dotnet/samples/Directory.Build.props
+9
View File
@@ -7,6 +7,15 @@
<IsAotCompatible>false</IsAotCompatible>
<ProjectsTargetFrameworks>net472;net9.0</ProjectsTargetFrameworks>
<UserSecretsId>5ee045b0-aea3-4f08-8d31-32d1a6f8fed0</UserSecretsId>
<NoWarn>$(NoWarn);CA1707</NoWarn>
</PropertyGroup>
<ItemGroup>
<Using Include="SampleHelpers.SampleEnvironment" Alias="Environment" />
</ItemGroup>
<ItemGroup>
<Compile Include="$(MSBuildThisFileDirectory)\..\src\Shared\Demos\*.cs" LinkBase="" Visible="false" />
</ItemGroup>
</Project>
dotnet/samples/GettingStartedSteps/README.md
+68
View File
@@ -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.
dotnet/samples/GettingStartedSteps/Step01_ChatClientAgent_Running/Program.cs
+32
View File
@@ -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);
}
dotnet/samples/GettingStartedSteps/Step01_ChatClientAgent_Running/Step01_ChatClientAgent_Running.csproj
+23
View File
@@ -0,0 +1,23 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net9.0</TargetFramework>
<LangVersion>12</LangVersion>
<Nullable>enable</Nullable>
<ImplicitUsings>disable</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Azure.AI.OpenAI" />
<PackageReference Include="Azure.Identity" />
<PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\..\..\src\Microsoft.Extensions.AI.Agents.OpenAI\Microsoft.Extensions.AI.Agents.OpenAI.csproj" />
<ProjectReference Include="..\..\..\src\Microsoft.Extensions.AI.Agents\Microsoft.Extensions.AI.Agents.csproj" />
</ItemGroup>
</Project>
dotnet/samples/GettingStartedSteps/Step02_ChatClientAgent_Multiturn/Program.cs
+39
View File
@@ -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);
}
dotnet/samples/GettingStartedSteps/Step02_ChatClientAgent_Multiturn/Step02_ChatClientAgent_Multiturn.csproj
+23
View File
@@ -0,0 +1,23 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net9.0</TargetFramework>
<LangVersion>12</LangVersion>
<Nullable>enable</Nullable>
<ImplicitUsings>disable</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Azure.AI.OpenAI" />
<PackageReference Include="Azure.Identity" />
<PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\..\..\src\Microsoft.Extensions.AI.Agents.OpenAI\Microsoft.Extensions.AI.Agents.OpenAI.csproj" />
<ProjectReference Include="..\..\..\src\Microsoft.Extensions.AI.Agents\Microsoft.Extensions.AI.Agents.csproj" />
</ItemGroup>
</Project>
dotnet/samples/README.md
+24
View File
@@ -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.
dotnet/src/Shared/Demos/SampleEnvironment.cs
+5 -5
View File
@@ -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();
user-documentation/dotnet/README.md
+14
View File
@@ -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)
user-documentation/dotnet/getting-started/README.md
+39
View File
@@ -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/).
user-documentation/dotnet/user-guide/README.md
+4
View File
@@ -0,0 +1,4 @@
# Microsoft Agent Framework for .NET Concepts
- [Agent Types](./agent-types.md)
- [Multi-turn conversations and Threading](./multi-turn-conversations.md)
user-documentation/dotnet/user-guide/agent-types.md
+41
View File
@@ -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.
user-documentation/dotnet/user-guide/multi-turn-conversations.md
+3
View File
@@ -0,0 +1,3 @@
# Microsoft Agent Framework for .NET Multi-Turn Conversations and Threading
To be added.