mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Add a script to produce docs by language, and add multi-turn-conversation docs (#510)
* Add a script to produce docs by language, and add multi-turn-conversation docs. * Fix typo. * Remove java pivots, move source templates and update comments. * Add links to docs from root readme
This commit is contained in:
westey
committed by
GitHub
Unverified
GitHub
parent
529341f58b
commit
802c8e6238
@@ -28,6 +28,8 @@ Below are the basics for each language implementation. For more details on pytho
|
||||
|
||||
## Agent Framework Documentation
|
||||
|
||||
- [Python documentation](./user-documentation-python/README.md)
|
||||
- [DotNet documentation](./user-documentation-dotnet/README.md)
|
||||
- [Agent Framework Repository](https://github.com/microsoft/agent-framework)
|
||||
- [Design Documents](./docs/design)
|
||||
- [Architectural Decision Records](./docs/decisions)
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
# Microsoft Agent Framework
|
||||
|
||||
## Overview
|
||||
|
||||
The Microsoft Agent Framework 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 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)
|
||||
@@ -0,0 +1,48 @@
|
||||
# Microsoft Agent Framework Getting Started
|
||||
|
||||
This guide will help you get up and running quickly with a basic agent using the Agent Framework and Azure OpenAI.
|
||||
|
||||
::: zone pivot="programming-language-csharp"
|
||||
|
||||
## 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/).
|
||||
|
||||
::: zone-end
|
||||
::: zone pivot="programming-language-python"
|
||||
|
||||
## Coming Soon
|
||||
|
||||
::: zone-end
|
||||
@@ -0,0 +1,49 @@
|
||||
# Microsoft Agent Framework Agent Types
|
||||
|
||||
The Microsoft Agent Framework 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 agents based on inference services
|
||||
|
||||
The agent framework makes it easy to create simple agents based on many different inference services.
|
||||
Any inference service that provides a ChatClient implementation can be used to build these agents.
|
||||
|
||||
These agents support a wide range of functionality out of the box:
|
||||
|
||||
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 ChatClient implementation of your choice.
|
||||
|
||||
::: zone pivot="programming-language-csharp"
|
||||
|
||||
```csharp
|
||||
using Microsoft.Extensions.AI;
|
||||
|
||||
var agent = new ChatClientAgent(chatClient, instructions: "You are a helpful assistant");
|
||||
```
|
||||
|
||||
For examples on how to construct `ChatClientAgents` with various `IChatClient` implementations, see the [Agent setup samples](../../../dotnet/samples/AgentSetup).
|
||||
|
||||
::: zone-end
|
||||
::: zone pivot="programming-language-python"
|
||||
::: zone-end
|
||||
|
||||
## Complex custom agents
|
||||
|
||||
It is also possible to create fully custom agents, that are not just wrappers around a ChatClient.
|
||||
The agent framework provides the `AIAgent` base type, which when subclassed allows for complete control over the agent's behavior and capabilities.
|
||||
|
||||
## Remote agents
|
||||
|
||||
The agent framework provides out of the box `AIAgent` subclasses for common service hosted agent protocols,
|
||||
such as A2A.
|
||||
|
||||
## Pre-built agents
|
||||
|
||||
To be added.
|
||||
@@ -0,0 +1,84 @@
|
||||
# Microsoft Agent Framework Multi-Turn Conversations and Threading
|
||||
|
||||
The Microsoft Agent Framework provides built-in support for managing multi-turn conversations with AI agents. This includes maintaining context across multiple interactions. Different agent types and underlying services that are used to build agents may support different threading types, and the agent framework abstracts these differences away, providing a consistent interface for developers.
|
||||
|
||||
For example, when using a ChatClientAgent based on a foundry agent, the conversation history is persisted in the service. While, when using a ChatClientAgent based on chat completion with gpt-4.1 the conversation history is in-memory and managed by the agent.
|
||||
|
||||
The differences between the underlying threading models are abstracted away via the `AgentThread` type.
|
||||
|
||||
## AgentThread lifecycle
|
||||
|
||||
### AgentThread Creation
|
||||
|
||||
`AgentThread` instances can be created in two ways:
|
||||
|
||||
1. By calling `GetNewThread` on the agent.
|
||||
1. By running the agent and not providing an `AgentThread`. In this case the agent will create a throwaway `AgentThread` with an underlying thread which will only be used for the duration of the run.
|
||||
|
||||
Some underlying threads may be persistently created in an underlying service, where the service requires this, e.g. Foundry Agents or OpenAI Responses. Any cleanup or deletion of these threads is the responsibility of the user.
|
||||
|
||||
::: zone pivot="programming-language-csharp"
|
||||
|
||||
```csharp
|
||||
// Create a new thread.
|
||||
AgentThread thread = agent.GetNewThread();
|
||||
// Run the agent with the thread.
|
||||
var response = await agent.RunAsync("Hello, how are you?", thread);
|
||||
|
||||
// Run an agent with a temporary thread.
|
||||
response = await agent.RunAsync("Hello, how are you?");
|
||||
```
|
||||
|
||||
::: zone-end
|
||||
::: zone pivot="programming-language-python"
|
||||
::: zone-end
|
||||
|
||||
### AgentThread Storage
|
||||
|
||||
`AgentThread` instances can be serialized and stored for later use. This allows for the preservation of conversation context across different sessions or service calls.
|
||||
|
||||
For cases where the conversation history is stored in a service, the serialized `AgentThread` will contain an
|
||||
id of the thread in the service.
|
||||
For cases where the conversation history is managed in-memory, the serialized `AgentThread` will contain the messages
|
||||
themselves.
|
||||
|
||||
::: zone pivot="programming-language-csharp"
|
||||
|
||||
```csharp
|
||||
// Create a new thread.
|
||||
AgentThread thread = agent.GetNewThread();
|
||||
// Run the agent with the thread.
|
||||
var response = await agent.RunAsync("Hello, how are you?", thread);
|
||||
|
||||
// Serialize the thread for storage.
|
||||
JsonElement serializedThread = await thread.SerializeAsync();
|
||||
// Deserialize the thread state after loading from storage.
|
||||
AgentThread resumedThread = await agent.DeserializeThreadAsync(serializedThread);
|
||||
|
||||
// Run the agent with the resumed thread.
|
||||
var response = await agent.RunAsync("Hello, how are you?", resumedThread);
|
||||
```
|
||||
|
||||
::: zone-end
|
||||
::: zone pivot="programming-language-python"
|
||||
::: zone-end
|
||||
|
||||
## Agent/AgentThread relationship
|
||||
|
||||
`AIAgent` instances are stateless and the same agent instance can be used with multiple `AgentThread` instances.
|
||||
|
||||
Not all agents support all thread types though. For example if you are using a `ChatClientAgent` with the responses service, `AgentThread` instances created by this agent, will not work with a `ChatClientAgent` using the Foundry Agent service.
|
||||
This is because these services both support saving the conversation history in the service, and the `AgentThread`
|
||||
only has a reference to this service managed thread.
|
||||
|
||||
It is therefore considered unsafe to use an `AgentThread` instance that was created by one agent with a different agent instance, unless you are aware of the underlying threading model and its implications.
|
||||
|
||||
## Threading support by service / protocol
|
||||
|
||||
| Service | Threading Support |
|
||||
|---------|--------------------|
|
||||
| Foundry Agents | Service managed persistent threads |
|
||||
| OpenAI Responses | Service managed persistent threads OR in-memory threads |
|
||||
| OpenAI ChatCompletion | In-memory threads |
|
||||
| OpenAI Assistants | Service managed threads |
|
||||
| A2A | Service managed threads |
|
||||
@@ -0,0 +1,70 @@
|
||||
$scriptDirectory = $PSScriptRoot
|
||||
$workspaceDirectory = Join-Path $scriptDirectory "../"
|
||||
$workspaceRoot = Resolve-Path "$workspaceDirectory"
|
||||
$userDocRoot = Join-Path $workspaceRoot "docs/docs-templates"
|
||||
$dotnetOutputRoot = Join-Path $workspaceRoot "user-documentation-dotnet"
|
||||
$pythonOutputRoot = Join-Path $workspaceRoot "user-documentation-python"
|
||||
|
||||
Write-Host "Templates Root: " $userDocRoot
|
||||
Write-Host "Dotnet Output Root: " $dotnetOutputRoot
|
||||
Write-Host "Python Output Root: " $pythonOutputRoot
|
||||
|
||||
# Delete all files in the ./user-documentation-dotnet directory.
|
||||
Get-ChildItem -Path $dotnetOutputRoot -Recurse | Remove-Item -Force -Recurse
|
||||
# Delete all files in the ./user-documentation-python directory.
|
||||
Get-ChildItem -Path $pythonOutputRoot -Recurse | Remove-Item -Force -Recurse
|
||||
|
||||
# Copy all files from ./user-documentation to ./user-documentation-dotnet and ./user-documentation-python
|
||||
Get-ChildItem -Path $userDocRoot -Recurse | ForEach-Object {
|
||||
if (-not $_.PSIsContainer) {
|
||||
$relativePath = $_.FullName.Substring($userDocRoot.Length + 1)
|
||||
$dotnetDestination = Join-Path $dotnetOutputRoot $relativePath
|
||||
$pythonDestination = Join-Path $pythonOutputRoot $relativePath
|
||||
|
||||
# Create output folder if needed
|
||||
$destinationDir = Split-Path $dotnetDestination -Parent
|
||||
if (-not (Test-Path $destinationDir)) {
|
||||
New-Item -ItemType Directory -Path $destinationDir -Force | Out-Null
|
||||
}
|
||||
|
||||
$destinationDir = Split-Path $pythonDestination -Parent
|
||||
if (-not (Test-Path $destinationDir)) {
|
||||
New-Item -ItemType Directory -Path $destinationDir -Force | Out-Null
|
||||
}
|
||||
|
||||
Write-Host "Copying $($_.FullName) to $dotnetDestination"
|
||||
Write-Host "Copying $($_.FullName) to $pythonDestination"
|
||||
|
||||
# Copy the file
|
||||
Copy-Item -Path $_.FullName -Destination $dotnetDestination -Force
|
||||
Copy-Item -Path $_.FullName -Destination $pythonDestination -Force
|
||||
|
||||
# Read the contents of the copied file
|
||||
$content = Get-Content -Path $dotnetDestination -Raw
|
||||
# Remove the python sections
|
||||
$pattern = '(?s)(::: zone pivot="programming-language-python"\s*).*?(::: zone-end)\r?\n'
|
||||
$content = [regex]::Replace($content, $pattern, '')
|
||||
# Remove the csharp markers
|
||||
$pattern = '(?s)(::: zone pivot="programming-language-csharp"\s\r?\n*)'
|
||||
$content = [regex]::Replace($content, $pattern, '')
|
||||
# Remove the csharp markers
|
||||
$pattern = '(?s)(::: zone-end)\r?\n'
|
||||
$content = [regex]::Replace($content, $pattern, '')
|
||||
# Write the modified contents back
|
||||
Set-Content -Path $dotnetDestination -Value $content
|
||||
|
||||
# Read the contents of the copied file
|
||||
$content = Get-Content -Path $pythonDestination -Raw
|
||||
# Remove the csharp sections
|
||||
$pattern = '(?s)(::: zone pivot="programming-language-csharp"\s*).*?(::: zone-end)\r?\n'
|
||||
$content = [regex]::Replace($content, $pattern, '')
|
||||
# Remove the csharp markers
|
||||
$pattern = '(?s)(::: zone pivot="programming-language-python"\s\r?\n*)'
|
||||
$content = [regex]::Replace($content, $pattern, '')
|
||||
# Remove the python markers
|
||||
$pattern = '(?s)(::: zone-end)\r?\n'
|
||||
$content = [regex]::Replace($content, $pattern, '')
|
||||
# Write the modified contents back
|
||||
Set-Content -Path $pythonDestination -Value $content
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
# Microsoft Agent Framework
|
||||
|
||||
## Overview
|
||||
|
||||
The Microsoft Agent Framework 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 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)
|
||||
|
||||
+3
-1
@@ -1,4 +1,4 @@
|
||||
# Microsoft Agent Framework for .NET Getting Started
|
||||
# Microsoft Agent Framework Getting Started
|
||||
|
||||
This guide will help you get up and running quickly with a basic agent using the Agent Framework and Azure OpenAI.
|
||||
|
||||
@@ -37,3 +37,5 @@ 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/).
|
||||
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
# Microsoft Agent Framework for .NET Concepts
|
||||
|
||||
- [Agent Types](./agent-types.md)
|
||||
- [Multi-turn conversations and Threading](./multi-turn-conversations.md)
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
# Microsoft Agent Framework Agent Types
|
||||
|
||||
The Microsoft Agent Framework 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 agents based on inference services
|
||||
|
||||
The agent framework makes it easy to create simple agents based on many different inference services.
|
||||
Any inference service that provides a ChatClient implementation can be used to build these agents.
|
||||
|
||||
These agents support a wide range of functionality out of the box:
|
||||
|
||||
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 ChatClient implementation of your choice.
|
||||
|
||||
```csharp
|
||||
using Microsoft.Extensions.AI;
|
||||
|
||||
var agent = new ChatClientAgent(chatClient, instructions: "You are a helpful assistant");
|
||||
```
|
||||
|
||||
For examples on how to construct `ChatClientAgents` with various `IChatClient` implementations, see the [Agent setup samples](../../../dotnet/samples/AgentSetup).
|
||||
|
||||
|
||||
## Complex custom agents
|
||||
|
||||
It is also possible to create fully custom agents, that are not just wrappers around a ChatClient.
|
||||
The agent framework provides the `AIAgent` base type, which when subclassed allows for complete control over the agent's behavior and capabilities.
|
||||
|
||||
## Remote agents
|
||||
|
||||
The agent framework provides out of the box `AIAgent` subclasses for common service hosted agent protocols,
|
||||
such as A2A.
|
||||
|
||||
## Pre-built agents
|
||||
|
||||
To be added.
|
||||
|
||||
@@ -0,0 +1,75 @@
|
||||
# Microsoft Agent Framework Multi-Turn Conversations and Threading
|
||||
|
||||
The Microsoft Agent Framework provides built-in support for managing multi-turn conversations with AI agents. This includes maintaining context across multiple interactions. Different agent types and underlying services that are used to build agents may support different threading types, and the agent framework abstracts these differences away, providing a consistent interface for developers.
|
||||
|
||||
For example, when using a ChatClientAgent based on a foundry agent, the conversation history is persisted in the service. While, when using a ChatClientAgent based on chat completion with gpt-4.1 the conversation history is in-memory and managed by the agent.
|
||||
|
||||
The differences between the underlying threading models are abstracted away via the `AgentThread` type.
|
||||
|
||||
## AgentThread lifecycle
|
||||
|
||||
### AgentThread Creation
|
||||
|
||||
`AgentThread` instances can be created in two ways:
|
||||
|
||||
1. By calling `GetNewThread` on the agent.
|
||||
1. By running the agent and not providing an `AgentThread`. In this case the agent will create a throwaway `AgentThread` with an underlying thread which will only be used for the duration of the run.
|
||||
|
||||
Some underlying threads may be persistently created in an underlying service, where the service requires this, e.g. Foundry Agents or OpenAI Responses. Any cleanup or deletion of these threads is the responsibility of the user.
|
||||
|
||||
```csharp
|
||||
// Create a new thread.
|
||||
AgentThread thread = agent.GetNewThread();
|
||||
// Run the agent with the thread.
|
||||
var response = await agent.RunAsync("Hello, how are you?", thread);
|
||||
|
||||
// Run an agent with a temporary thread.
|
||||
response = await agent.RunAsync("Hello, how are you?");
|
||||
```
|
||||
|
||||
|
||||
### AgentThread Storage
|
||||
|
||||
`AgentThread` instances can be serialized and stored for later use. This allows for the preservation of conversation context across different sessions or service calls.
|
||||
|
||||
For cases where the conversation history is stored in a service, the serialized `AgentThread` will contain an
|
||||
id of the thread in the service.
|
||||
For cases where the conversation history is managed in-memory, the serialized `AgentThread` will contain the messages
|
||||
themselves.
|
||||
|
||||
```csharp
|
||||
// Create a new thread.
|
||||
AgentThread thread = agent.GetNewThread();
|
||||
// Run the agent with the thread.
|
||||
var response = await agent.RunAsync("Hello, how are you?", thread);
|
||||
|
||||
// Serialize the thread for storage.
|
||||
JsonElement serializedThread = await thread.SerializeAsync();
|
||||
// Deserialize the thread state after loading from storage.
|
||||
AgentThread resumedThread = await agent.DeserializeThreadAsync(serializedThread);
|
||||
|
||||
// Run the agent with the resumed thread.
|
||||
var response = await agent.RunAsync("Hello, how are you?", resumedThread);
|
||||
```
|
||||
|
||||
|
||||
## Agent/AgentThread relationship
|
||||
|
||||
`AIAgent` instances are stateless and the same agent instance can be used with multiple `AgentThread` instances.
|
||||
|
||||
Not all agents support all thread types though. For example if you are using a `ChatClientAgent` with the responses service, `AgentThread` instances created by this agent, will not work with a `ChatClientAgent` using the Foundry Agent service.
|
||||
This is because these services both support saving the conversation history in the service, and the `AgentThread`
|
||||
only has a reference to this service managed thread.
|
||||
|
||||
It is therefore considered unsafe to use an `AgentThread` instance that was created by one agent with a different agent instance, unless you are aware of the underlying threading model and its implications.
|
||||
|
||||
## Threading support by service / protocol
|
||||
|
||||
| Service | Threading Support |
|
||||
|---------|--------------------|
|
||||
| Foundry Agents | Service managed persistent threads |
|
||||
| OpenAI Responses | Service managed persistent threads OR in-memory threads |
|
||||
| OpenAI ChatCompletion | In-memory threads |
|
||||
| OpenAI Assistants | Service managed threads |
|
||||
| A2A | Service managed threads |
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
# Microsoft Agent Framework
|
||||
|
||||
## Overview
|
||||
|
||||
The Microsoft Agent Framework 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 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)
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
# Microsoft Agent Framework Getting Started
|
||||
|
||||
This guide will help you get up and running quickly with a basic agent using the Agent Framework and Azure OpenAI.
|
||||
|
||||
## Coming Soon
|
||||
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
# Microsoft Agent Framework for .NET Concepts
|
||||
|
||||
- [Agent Types](./agent-types.md)
|
||||
- [Multi-turn conversations and Threading](./multi-turn-conversations.md)
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
# Microsoft Agent Framework Agent Types
|
||||
|
||||
The Microsoft Agent Framework 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 agents based on inference services
|
||||
|
||||
The agent framework makes it easy to create simple agents based on many different inference services.
|
||||
Any inference service that provides a ChatClient implementation can be used to build these agents.
|
||||
|
||||
These agents support a wide range of functionality out of the box:
|
||||
|
||||
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 ChatClient implementation of your choice.
|
||||
|
||||
|
||||
## Complex custom agents
|
||||
|
||||
It is also possible to create fully custom agents, that are not just wrappers around a ChatClient.
|
||||
The agent framework provides the `AIAgent` base type, which when subclassed allows for complete control over the agent's behavior and capabilities.
|
||||
|
||||
## Remote agents
|
||||
|
||||
The agent framework provides out of the box `AIAgent` subclasses for common service hosted agent protocols,
|
||||
such as A2A.
|
||||
|
||||
## Pre-built agents
|
||||
|
||||
To be added.
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
# Microsoft Agent Framework Multi-Turn Conversations and Threading
|
||||
|
||||
The Microsoft Agent Framework provides built-in support for managing multi-turn conversations with AI agents. This includes maintaining context across multiple interactions. Different agent types and underlying services that are used to build agents may support different threading types, and the agent framework abstracts these differences away, providing a consistent interface for developers.
|
||||
|
||||
For example, when using a ChatClientAgent based on a foundry agent, the conversation history is persisted in the service. While, when using a ChatClientAgent based on chat completion with gpt-4.1 the conversation history is in-memory and managed by the agent.
|
||||
|
||||
The differences between the underlying threading models are abstracted away via the `AgentThread` type.
|
||||
|
||||
## AgentThread lifecycle
|
||||
|
||||
### AgentThread Creation
|
||||
|
||||
`AgentThread` instances can be created in two ways:
|
||||
|
||||
1. By calling `GetNewThread` on the agent.
|
||||
1. By running the agent and not providing an `AgentThread`. In this case the agent will create a throwaway `AgentThread` with an underlying thread which will only be used for the duration of the run.
|
||||
|
||||
Some underlying threads may be persistently created in an underlying service, where the service requires this, e.g. Foundry Agents or OpenAI Responses. Any cleanup or deletion of these threads is the responsibility of the user.
|
||||
|
||||
|
||||
### AgentThread Storage
|
||||
|
||||
`AgentThread` instances can be serialized and stored for later use. This allows for the preservation of conversation context across different sessions or service calls.
|
||||
|
||||
For cases where the conversation history is stored in a service, the serialized `AgentThread` will contain an
|
||||
id of the thread in the service.
|
||||
For cases where the conversation history is managed in-memory, the serialized `AgentThread` will contain the messages
|
||||
themselves.
|
||||
|
||||
|
||||
## Agent/AgentThread relationship
|
||||
|
||||
`AIAgent` instances are stateless and the same agent instance can be used with multiple `AgentThread` instances.
|
||||
|
||||
Not all agents support all thread types though. For example if you are using a `ChatClientAgent` with the responses service, `AgentThread` instances created by this agent, will not work with a `ChatClientAgent` using the Foundry Agent service.
|
||||
This is because these services both support saving the conversation history in the service, and the `AgentThread`
|
||||
only has a reference to this service managed thread.
|
||||
|
||||
It is therefore considered unsafe to use an `AgentThread` instance that was created by one agent with a different agent instance, unless you are aware of the underlying threading model and its implications.
|
||||
|
||||
## Threading support by service / protocol
|
||||
|
||||
| Service | Threading Support |
|
||||
|---------|--------------------|
|
||||
| Foundry Agents | Service managed persistent threads |
|
||||
| OpenAI Responses | Service managed persistent threads OR in-memory threads |
|
||||
| OpenAI ChatCompletion | In-memory threads |
|
||||
| OpenAI Assistants | Service managed threads |
|
||||
| A2A | Service managed threads |
|
||||
|
||||
@@ -1,14 +0,0 @@
|
||||
# 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)
|
||||
@@ -1,41 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,3 +0,0 @@
|
||||
# Microsoft Agent Framework for .NET Multi-Turn Conversations and Threading
|
||||
|
||||
To be added.
|
||||
Reference in New Issue
Block a user