mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Remove the private preview docuemntation (#968)
Co-authored-by: Mark Wallace <markwallace@microsoft.com>
This commit is contained in:
Mark Wallace
committed by
GitHub
Unverified
GitHub
parent
ff7d301389
commit
d6f2c6b3e5
@@ -1,14 +0,0 @@
|
||||
# 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)
|
||||
@@ -1,102 +0,0 @@
|
||||
# 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.Agents.AI;
|
||||
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/).
|
||||
|
||||
## (Optional) Installing Packages
|
||||
|
||||
Packages will be published to [NuGet](https://www.nuget.org/) when the Agent Framework public preview is released.
|
||||
In the meantime nightly builds of the Agent Framework are available [here](https://github.com/orgs/microsoft/packages?repo_name=agent-framework).
|
||||
|
||||
To download nightly builds follow the following steps:
|
||||
|
||||
1. You will need a GitHub account to complete these steps.
|
||||
1. Create a GitHub Personal Access Token with the `read:packages` scope using these [instructions](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic).
|
||||
1. If your account is part of the Microsoft organization then you must authorize the `Microsoft` organization as a single sign-on organization.
|
||||
1. Click the "Configure SSO" next to the Personal Access Token you just created and then authorize `Microsoft`.
|
||||
1. Use the following command to add the Microsoft GitHub Packages source to your NuGet configuration:
|
||||
|
||||
```powershell
|
||||
dotnet nuget add source --username GITHUBUSERNAME --password GITHUBPERSONALACCESSTOKEN --store-password-in-clear-text --name GitHubMicrosoft "https://nuget.pkg.github.com/microsoft/index.json"
|
||||
```
|
||||
|
||||
1. Or you can manually create a `NuGet.Config` file.
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<configuration>
|
||||
<packageSources>
|
||||
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
|
||||
<add key="github" value="https://nuget.pkg.github.com/microsoft/index.json" />
|
||||
</packageSources>
|
||||
|
||||
<packageSourceMapping>
|
||||
<packageSource key="nuget.org">
|
||||
<package pattern="*" />
|
||||
</packageSource>
|
||||
<packageSource key="github">
|
||||
<package pattern="*nightly"/>
|
||||
</packageSource>
|
||||
</packageSourceMapping>
|
||||
|
||||
<packageSourceCredentials>
|
||||
<github>
|
||||
<add key="Username" value="<Your GitHub Id>" />
|
||||
<add key="ClearTextPassword" value="<Your Personal Access Token>" />
|
||||
</github>
|
||||
</packageSourceCredentials>
|
||||
</configuration>
|
||||
```
|
||||
|
||||
* If you place this file in your project folder make sure to have Git (or whatever source control you use) ignore it.
|
||||
* For more information on where to store this file go [here](https://learn.microsoft.com/en-us/nuget/reference/nuget-config-file).
|
||||
1. You can now add packages from the nightly build to your project.
|
||||
* E.g. use this command `dotnet add package Microsoft.Agents.AI --version 0.0.1-nightly-250731.6-alpha`
|
||||
1. And the latest package release can be referenced in the project like this:
|
||||
* `<PackageReference Include="Microsoft.Agents.AI" Version="*-*" />`
|
||||
|
||||
For more information see: <https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry>
|
||||
|
||||
::: zone-end
|
||||
::: zone pivot="programming-language-python"
|
||||
|
||||
## Coming Soon
|
||||
|
||||
::: zone-end
|
||||
@@ -1,4 +0,0 @@
|
||||
# Microsoft Agent Framework for .NET Concepts
|
||||
|
||||
- [Agent Types](./agent-types.md)
|
||||
- [Multi-turn conversations and Threading](./multi-turn-conversations.md)
|
||||
@@ -1,200 +0,0 @@
|
||||
# Microsoft Agent Framework Agent Types
|
||||
|
||||
::: zone pivot="programming-language-csharp"
|
||||
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 `AgentProtocol` 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 `AgentProtocol` subclasses for common service hosted agent protocols,
|
||||
such as A2A.
|
||||
|
||||
## Pre-built agents
|
||||
|
||||
To be added.
|
||||
::: zone-end
|
||||
::: zone pivot="programming-language-python"
|
||||
|
||||
The Microsoft Agent Framework provides support for several types of agents to accommodate different use cases and requirements.
|
||||
|
||||
All agents implement a common protocol, `AgentProtocol`, 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 chat client 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
|
||||
1. Streaming responses
|
||||
|
||||
To create one of these agents, simply construct a `ChatAgent` using the chat client implementation of your choice.
|
||||
|
||||
```python
|
||||
from agent_framework import ChatAgent
|
||||
from agent_framework.foundry import FoundryChatClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
ChatAgent(
|
||||
chat_client=FoundryChatClient(async_credential=credential),
|
||||
instructions="You are a helpful assistant"
|
||||
) as agent
|
||||
):
|
||||
response = await agent.run("Hello!")
|
||||
```
|
||||
|
||||
Alternatively, you can use the convenience method on the chat client:
|
||||
|
||||
```python
|
||||
from agent_framework.foundry import FoundryChatClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
|
||||
async with AzureCliCredential() as credential:
|
||||
agent = FoundryChatClient(async_credential=credential).create_agent(
|
||||
instructions="You are a helpful assistant"
|
||||
)
|
||||
```
|
||||
|
||||
For detailed examples, see:
|
||||
- [Basic Foundry agent](../../../python/samples/getting_started/agents/foundry/foundry_basic.py)
|
||||
- [Foundry with explicit settings](../../../python/samples/getting_started/agents/foundry/foundry_with_explicit_settings.py)
|
||||
- [Using existing Foundry agent](../../../python/samples/getting_started/agents/foundry/foundry_with_existing_agent.py)
|
||||
|
||||
### Function Tools
|
||||
|
||||
You can provide function tools to agents for enhanced capabilities:
|
||||
|
||||
```python
|
||||
from typing import Annotated
|
||||
from pydantic import Field
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
|
||||
def get_weather(location: Annotated[str, Field(description="The location to get the weather for.")]) -> str:
|
||||
"""Get the weather for a given location."""
|
||||
return f"The weather in {location} is sunny with a high of 25°C."
|
||||
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
FoundryChatClient(async_credential=credential).create_agent(
|
||||
instructions="You are a helpful weather assistant.",
|
||||
tools=get_weather
|
||||
) as agent
|
||||
):
|
||||
response = await agent.run("What's the weather in Seattle?")
|
||||
```
|
||||
|
||||
For complete examples with function tools, see:
|
||||
- [Foundry with function tools](../../../python/samples/getting_started/agents/foundry/foundry_with_function_tools.py)
|
||||
|
||||
### Streaming Responses
|
||||
|
||||
Agents support both regular and streaming responses:
|
||||
|
||||
```python
|
||||
# Regular response (wait for complete result)
|
||||
response = await agent.run("What's the weather like in Seattle?")
|
||||
print(response.text)
|
||||
|
||||
# Streaming response (get results as they are generated)
|
||||
async for chunk in agent.run_stream("What's the weather like in Portland?"):
|
||||
if chunk.text:
|
||||
print(chunk.text, end="", flush=True)
|
||||
```
|
||||
|
||||
For streaming examples, see:
|
||||
- [Foundry streaming examples](../../../python/samples/getting_started/agents/foundry/foundry_basic.py)
|
||||
|
||||
### Code Interpreter Tools
|
||||
|
||||
Foundry agents support hosted code interpreter tools for executing Python code:
|
||||
|
||||
```python
|
||||
from agent_framework import ChatAgent, HostedCodeInterpreterTool
|
||||
from agent_framework.foundry import FoundryChatClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
ChatAgent(
|
||||
chat_client=FoundryChatClient(async_credential=credential),
|
||||
instructions="You are a helpful assistant that can execute Python code.",
|
||||
tools=HostedCodeInterpreterTool()
|
||||
) as agent
|
||||
):
|
||||
response = await agent.run("Calculate the factorial of 100 using Python")
|
||||
```
|
||||
|
||||
For code interpreter examples, see:
|
||||
- [Foundry with code interpreter](../../../python/samples/getting_started/agents/foundry/foundry_with_code_interpreter.py)
|
||||
|
||||
## Custom agents
|
||||
|
||||
It is also possible to create fully custom agents that are not just wrappers around a chat client.
|
||||
Agent Framework provides the `AgentProtocol` protocol and `BaseAgent` base class, which when implemented/subclassed allows for complete control over the agent's behavior and capabilities.
|
||||
|
||||
```python
|
||||
from agent_framework import BaseAgent, AgentRunResponse, AgentRunResponseUpdate, AgentThread, ChatMessage
|
||||
from collections.abc import AsyncIterable
|
||||
|
||||
class CustomAgent(BaseAgent):
|
||||
async def run(
|
||||
self,
|
||||
messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
|
||||
*,
|
||||
thread: AgentThread | None = None,
|
||||
**kwargs: Any,
|
||||
) -> AgentRunResponse:
|
||||
# Custom agent implementation
|
||||
pass
|
||||
|
||||
def run_stream(
|
||||
self,
|
||||
messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
|
||||
*,
|
||||
thread: AgentThread | None = None,
|
||||
**kwargs: Any,
|
||||
) -> AsyncIterable[AgentRunResponseUpdate]:
|
||||
# Custom streaming implementation
|
||||
pass
|
||||
```
|
||||
|
||||
::: zone-end
|
||||
@@ -1,84 +0,0 @@
|
||||
# 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 |
|
||||
@@ -1,70 +0,0 @@
|
||||
$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
|
||||
}
|
||||
}
|
||||
@@ -1,15 +0,0 @@
|
||||
# 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)
|
||||
|
||||
@@ -1,95 +0,0 @@
|
||||
# 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.
|
||||
|
||||
## 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.Agents.AI;
|
||||
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/).
|
||||
|
||||
## (Optional) Installing Packages
|
||||
|
||||
Packages will be published to [NuGet](https://www.nuget.org/) when the Agent Framework public preview is released.
|
||||
In the meantime nightly builds of the Agent Framework are available [here](https://github.com/orgs/microsoft/packages?repo_name=agent-framework).
|
||||
|
||||
To download nightly builds follow the following steps:
|
||||
|
||||
1. You will need a GitHub account to complete these steps.
|
||||
1. Create a GitHub Personal Access Token with the `read:packages` scope using these [instructions](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic).
|
||||
1. If your account is part of the Microsoft organization then you must authorize the `Microsoft` organization as a single sign-on organization.
|
||||
1. Click the "Configure SSO" next to the Personal Access Token you just created and then authorize `Microsoft`.
|
||||
1. Use the following command to add the Microsoft GitHub Packages source to your NuGet configuration:
|
||||
|
||||
```powershell
|
||||
dotnet nuget add source --username GITHUBUSERNAME --password GITHUBPERSONALACCESSTOKEN --store-password-in-clear-text --name GitHubMicrosoft "https://nuget.pkg.github.com/microsoft/index.json"
|
||||
```
|
||||
|
||||
1. Or you can manually create a `NuGet.Config` file.
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<configuration>
|
||||
<packageSources>
|
||||
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
|
||||
<add key="github" value="https://nuget.pkg.github.com/microsoft/index.json" />
|
||||
</packageSources>
|
||||
|
||||
<packageSourceMapping>
|
||||
<packageSource key="nuget.org">
|
||||
<package pattern="*" />
|
||||
</packageSource>
|
||||
<packageSource key="github">
|
||||
<package pattern="*nightly"/>
|
||||
</packageSource>
|
||||
</packageSourceMapping>
|
||||
|
||||
<packageSourceCredentials>
|
||||
<github>
|
||||
<add key="Username" value="<Your GitHub Id>" />
|
||||
<add key="ClearTextPassword" value="<Your Personal Access Token>" />
|
||||
</github>
|
||||
</packageSourceCredentials>
|
||||
</configuration>
|
||||
```
|
||||
|
||||
* If you place this file in your project folder make sure to have Git (or whatever source control you use) ignore it.
|
||||
* For more information on where to store this file go [here](https://learn.microsoft.com/en-us/nuget/reference/nuget-config-file).
|
||||
1. You can now add packages from the nightly build to your project.
|
||||
* E.g. use this command `dotnet add package Microsoft.Extensions.AI.Agents --version 0.0.1-nightly-250731.6-alpha`
|
||||
1. And the latest package release can be referenced in the project like this:
|
||||
* `<PackageReference Include="Microsoft.Extensions.AI.Agents" Version="*-*" />`
|
||||
|
||||
For more information see: <https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry>
|
||||
|
||||
|
||||
@@ -1,5 +0,0 @@
|
||||
# Microsoft Agent Framework for .NET Concepts
|
||||
|
||||
- [Agent Types](./agent-types.md)
|
||||
- [Multi-turn conversations and Threading](./multi-turn-conversations.md)
|
||||
|
||||
@@ -1,45 +0,0 @@
|
||||
# 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.
|
||||
|
||||
@@ -1,75 +0,0 @@
|
||||
# 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 |
|
||||
|
||||
@@ -1,15 +0,0 @@
|
||||
# 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)
|
||||
|
||||
@@ -1,50 +0,0 @@
|
||||
# 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 AI Foundry.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you begin, ensure you have the following:
|
||||
|
||||
- [Python 3.9 or later](https://www.python.org/downloads/)
|
||||
- An [Azure AI Foundry](https://learn.microsoft.com/azure/ai-foundry/) project 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 AI Foundry project. 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 AI Foundry as the backend. It will create a basic agent using `ChatAgent` with `FoundryChatClient` and custom instructions.
|
||||
|
||||
Make sure to set the following environment variables:
|
||||
- `FOUNDRY_PROJECT_ENDPOINT`: Your Azure AI Foundry project endpoint
|
||||
- `FOUNDRY_MODEL_DEPLOYMENT_NAME`: The name of your model deployment
|
||||
|
||||
For detailed information about different ways to run examples and configure environment variables, see [Running Examples Guide](running_examples.md).
|
||||
|
||||
### Sample Code
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
from agent_framework import ChatAgent
|
||||
from agent_framework.foundry import FoundryChatClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
|
||||
async def main():
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
ChatAgent(
|
||||
chat_client=FoundryChatClient(async_credential=credential),
|
||||
instructions="You are good at telling jokes."
|
||||
) as agent,
|
||||
):
|
||||
result = await agent.run("Tell me a joke about a pirate.")
|
||||
print(result.text)
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
## More Examples
|
||||
|
||||
For more detailed examples and advanced scenarios, see the [Foundry Agent Examples](../../python/samples/getting_started/agents/foundry/README.md).
|
||||
@@ -1,107 +0,0 @@
|
||||
# Try the Python agent-framework from the repository
|
||||
|
||||
This page shows how an external Python application (not working inside this repo) can install and use the Python packages provided by this repository directly from the `main` branch on GitHub, in lieu of waiting for a PyPI release.
|
||||
|
||||
Globally, these are the steps:
|
||||
- Create a requirements.txt and constraints.txt (or a pyproject.toml) or a uv pyproject.toml
|
||||
- Create and activate a virtual environment
|
||||
- Install the main package with extras from the repo using pip or uv
|
||||
- Verify the installation
|
||||
|
||||
## Quick summary
|
||||
- Minimum Python: >= 3.10 (project requires-python = ">=3.10").
|
||||
- GitHub repository: https://github.com/microsoft/agent-framework.
|
||||
- Package subdirectories used by pip:
|
||||
- Main package: `python/packages/main`
|
||||
- Azure: `python/packages/azure`
|
||||
- Foundry: `python/packages/foundry`
|
||||
- Workflow: `python/packages/workflow`
|
||||
|
||||
Why use the repo URL?
|
||||
- Installing from the GitHub repo lets you try the current `main` branch without waiting for a PyPI release, once we start releasing our packages on PyPI we will remove this guide.
|
||||
|
||||
Important note about extras and sub-packages
|
||||
- The `agent-framework` package defines optional extras (for example `azure`, `foundry`, `workflow`) which declare dependency names like `agent-framework-azure`.
|
||||
- Installing `agent-framework[azure]` from the repo will instruct pip to request the distribution `agent-framework-azure`. This package is also not published on PyPI (or an index pip knows about), pip may fail to resolve the extra automatically, so you need to explicitly tell pip where to find that package.
|
||||
|
||||
To do this with pip, you can use a `--constraint` file that pins the subpackages to the repo URL while installing the main package with extras, see the quick start example below.
|
||||
|
||||
# Quick start — install the main package from GitHub in a new virtual environment
|
||||
|
||||
### Approach 1) using requirements.txt + constraints.txt
|
||||
|
||||
Create and activate a virtual environment:
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
```
|
||||
|
||||
For example, when you want to use Agent Framework with Azure OpenAI clients, use a requirements.txt like this:
|
||||
|
||||
```
|
||||
agent-framework[azure] @ git+https://github.com/microsoft/agent-framework.git@main#subdirectory=python/packages/main
|
||||
```
|
||||
|
||||
with constraints for the extras, in constraints.txt:
|
||||
|
||||
```
|
||||
agent-framework-azure @ git+https://github.com/microsoft/agent-framework.git@main#subdirectory=python/packages/azure
|
||||
agent-framework-foundry @ git+https://github.com/microsoft/agent-framework.git@main#subdirectory=python/packages/foundry
|
||||
agent-framework-workflow @ git+https://github.com/microsoft/agent-framework.git@main#subdirectory=python/packages/workflow
|
||||
```
|
||||
|
||||
Then install with:
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt --constraint constraints.txt
|
||||
```
|
||||
|
||||
### Approach 2) or using [`uv`](https://docs.astral.sh/uv/getting-started/installation/) with `pyproject.toml`
|
||||
|
||||
First create a pyproject.toml with the dependency and source mappings, for example:
|
||||
```toml
|
||||
[project]
|
||||
name = "my-app"
|
||||
requires-python = ">=3.10"
|
||||
dependencies = [
|
||||
"agent-framework[azure]", # or [azure,workflow]
|
||||
]
|
||||
[tool.uv]
|
||||
prerelease = "if-necessary-or-explicit"
|
||||
[tool.uv.sources]
|
||||
"agent-framework" = { git = "https://github.com/microsoft/agent-framework.git", branch = "main", subdirectory = "python/packages/main" }
|
||||
"agent-framework-azure" = { git = "https://github.com/microsoft/agent-framework.git", branch = "main", subdirectory = "python/packages/azure" }
|
||||
"agent-framework-foundry" = { git = "https://github.com/microsoft/agent-framework.git", branch = "main", subdirectory = "python/packages/foundry" }
|
||||
"agent-framework-workflow" = { git = "https://github.com/microsoft/agent-framework.git", branch = "main", subdirectory = "python/packages/workflow" }
|
||||
```
|
||||
Then create a virtual environment:
|
||||
```bash
|
||||
uv venv
|
||||
```
|
||||
|
||||
Then install with:
|
||||
|
||||
```bash
|
||||
uv sync
|
||||
```
|
||||
|
||||
## Quick verification
|
||||
|
||||
To verify the installation, you can run a Python shell (from your virtual environment) and try to import the main package and any extras you installed, for example (and you can uncomment the extras you installed):
|
||||
|
||||
```python
|
||||
from agent_framework import __version__ as af_version
|
||||
# from agent_framework.azure import __version__ as af_azure_version
|
||||
# from agent_framework.foundry import __version__ as af_foundry_version
|
||||
# from agent_framework.workflow import __version__ as af_workflow_version
|
||||
print(f"Main package: {af_version}")
|
||||
# print(f"Azure extra: {af_azure_version}")
|
||||
# print(f"Foundry extra: {af_foundry_version}")
|
||||
# print(f"Workflow extra: {af_workflow_version}")
|
||||
```
|
||||
This should print the version of the main package, for example:
|
||||
```
|
||||
Main package: 0.1.0b1
|
||||
```
|
||||
|
||||
Next, you can review the get started guides in [user-guide](../user-guide/README.md) to try out the functionality of the agent framework.
|
||||
@@ -1,59 +0,0 @@
|
||||
# Running Agent Framework Python Examples
|
||||
|
||||
This guide explains different ways to run the Agent Framework examples and how to properly configure environment variables for each approach.
|
||||
|
||||
## Different Approaches to Running Examples
|
||||
|
||||
There are several ways to run the examples, each requiring different environment variable configurations:
|
||||
|
||||
### 1. Running within IDE (VS Code with F5)
|
||||
|
||||
If you clone the repository and run examples within an IDE like VS Code using F5:
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone https://github.com/microsoft/agent-framework.git
|
||||
cd agent-framework/python
|
||||
```
|
||||
|
||||
2. Configure environment variables in the `agent-framework/python` folder by creating a `.env` file (use [.env.example](../../python/.env.example) as example):
|
||||
```
|
||||
FOUNDRY_PROJECT_ENDPOINT=your_project_endpoint
|
||||
FOUNDRY_MODEL_DEPLOYMENT_NAME=your_model_deployment_name
|
||||
```
|
||||
|
||||
3. Open the project in VS Code, choose an example and press F5 to run it.
|
||||
|
||||
### 2. Running with Terminal Command
|
||||
|
||||
If you clone the repository and run samples with `python sample.py` terminal command:
|
||||
|
||||
1. Clone the repository and navigate to the specific sample folder:
|
||||
```bash
|
||||
git clone https://github.com/microsoft/agent-framework.git
|
||||
cd agent-framework/python/samples/getting_started/agents/foundry
|
||||
```
|
||||
|
||||
2. Configure environment variables in the sample folder by creating a `.env` file where the sample is located:
|
||||
```
|
||||
FOUNDRY_PROJECT_ENDPOINT=your_project_endpoint
|
||||
FOUNDRY_MODEL_DEPLOYMENT_NAME=your_model_deployment_name
|
||||
```
|
||||
|
||||
3. Run the sample:
|
||||
```bash
|
||||
python sample.py
|
||||
```
|
||||
|
||||
### 3. Copy-Paste Code in Local Project
|
||||
|
||||
If you copy and paste code samples into your own local project setup:
|
||||
|
||||
1. Install the required dependencies in your local environment:
|
||||
```bash
|
||||
pip install agent-framework
|
||||
```
|
||||
|
||||
2. Set up environment variables based on your local project configuration (e.g., `.env` file in your project root, system environment variables, or your preferred configuration method).
|
||||
|
||||
3. Make sure the environment variables are accessible from where your Python script runs.
|
||||
@@ -1,5 +0,0 @@
|
||||
# Microsoft Agent Framework for Python Concepts
|
||||
|
||||
- [Agent Types](./agent-types.md)
|
||||
- [Multi-turn conversations and Threading](./multi-turn-conversations.md)
|
||||
|
||||
@@ -1,199 +0,0 @@
|
||||
# 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 implement a common protocol, `AgentProtocol`, 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 chat client 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
|
||||
1. Streaming responses
|
||||
|
||||
To create one of these agents, simply construct a `ChatAgent` using the chat client implementation of your choice.
|
||||
|
||||
```python
|
||||
from agent_framework import ChatAgent
|
||||
from agent_framework.foundry import FoundryChatClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
ChatAgent(
|
||||
chat_client=FoundryChatClient(async_credential=credential),
|
||||
instructions="You are a helpful assistant"
|
||||
) as agent
|
||||
):
|
||||
response = await agent.run("Hello!")
|
||||
```
|
||||
|
||||
Alternatively, you can use the convenience method on the chat client:
|
||||
|
||||
```python
|
||||
from agent_framework.foundry import FoundryChatClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
|
||||
async with AzureCliCredential() as credential:
|
||||
agent = FoundryChatClient(async_credential=credential).create_agent(
|
||||
instructions="You are a helpful assistant"
|
||||
)
|
||||
```
|
||||
|
||||
For detailed examples, see:
|
||||
- [Basic Foundry agent](../../../python/samples/getting_started/agents/foundry/foundry_basic.py)
|
||||
- [Foundry with explicit settings](../../../python/samples/getting_started/agents/foundry/foundry_with_explicit_settings.py)
|
||||
- [Using existing Foundry agent](../../../python/samples/getting_started/agents/foundry/foundry_with_existing_agent.py)
|
||||
|
||||
### Function Tools
|
||||
|
||||
You can provide function tools to agents for enhanced capabilities:
|
||||
|
||||
```python
|
||||
from typing import Annotated
|
||||
from pydantic import Field
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
|
||||
def get_weather(location: Annotated[str, Field(description="The location to get the weather for.")]) -> str:
|
||||
"""Get the weather for a given location."""
|
||||
return f"The weather in {location} is sunny with a high of 25°C."
|
||||
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
FoundryChatClient(async_credential=credential).create_agent(
|
||||
instructions="You are a helpful weather assistant.",
|
||||
tools=get_weather
|
||||
) as agent
|
||||
):
|
||||
response = await agent.run("What's the weather in Seattle?")
|
||||
```
|
||||
|
||||
For complete examples with function tools, see:
|
||||
- [Foundry with function tools](../../../python/samples/getting_started/agents/foundry/foundry_with_function_tools.py)
|
||||
|
||||
### Streaming Responses
|
||||
|
||||
Agents support both regular and streaming responses:
|
||||
|
||||
```python
|
||||
# Regular response (wait for complete result)
|
||||
response = await agent.run("What's the weather like in Seattle?")
|
||||
print(response.text)
|
||||
|
||||
# Streaming response (get results as they are generated)
|
||||
async for chunk in agent.run_stream("What's the weather like in Portland?"):
|
||||
if chunk.text:
|
||||
print(chunk.text, end="", flush=True)
|
||||
```
|
||||
|
||||
For streaming examples, see:
|
||||
- [Foundry streaming examples](../../../python/samples/getting_started/agents/foundry/foundry_basic.py)
|
||||
|
||||
### Code Interpreter Tools
|
||||
|
||||
Foundry agents support hosted code interpreter tools for executing Python code:
|
||||
|
||||
```python
|
||||
from agent_framework import ChatAgent, HostedCodeInterpreterTool
|
||||
from agent_framework.foundry import FoundryChatClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
ChatAgent(
|
||||
chat_client=FoundryChatClient(async_credential=credential),
|
||||
instructions="You are a helpful assistant that can execute Python code.",
|
||||
tools=HostedCodeInterpreterTool()
|
||||
) as agent
|
||||
):
|
||||
response = await agent.run("Calculate the factorial of 100 using Python")
|
||||
```
|
||||
|
||||
For code interpreter examples, see:
|
||||
- [Foundry with code interpreter](../../../python/samples/getting_started/agents/foundry/foundry_with_code_interpreter.py)
|
||||
|
||||
### Model Context Protocol (MCP) Tools
|
||||
|
||||
Foundry agents support Model Context Protocol (MCP) tools for connecting to external services and data sources.
|
||||
|
||||
Learn more about MCP tools in the [Azure AI Foundry documentation](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/model-context-protocol).
|
||||
|
||||
```python
|
||||
from agent_framework import ChatAgent, MCPStreamableHTTPTool
|
||||
from agent_framework.foundry import FoundryChatClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
|
||||
# Tools can be defined at agent creation
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
FoundryChatClient(async_credential=credential).create_agent(
|
||||
name="DocsAgent",
|
||||
instructions="You are a helpful assistant that can help with microsoft documentation questions.",
|
||||
tools=MCPStreamableHTTPTool(
|
||||
name="Microsoft Learn MCP",
|
||||
url="https://learn.microsoft.com/api/mcp",
|
||||
),
|
||||
) as agent
|
||||
):
|
||||
response = await agent.run("How to create an Azure storage account using az cli?")
|
||||
```
|
||||
|
||||
You can also provide MCP tools when running the agent:
|
||||
|
||||
```python
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
MCPStreamableHTTPTool(
|
||||
name="Microsoft Learn MCP",
|
||||
url="https://learn.microsoft.com/api/mcp",
|
||||
) as mcp_server,
|
||||
ChatAgent(
|
||||
chat_client=FoundryChatClient(async_credential=credential),
|
||||
name="DocsAgent",
|
||||
instructions="You are a helpful assistant that can help with microsoft documentation questions.",
|
||||
) as agent,
|
||||
):
|
||||
response = await agent.run("What is Microsoft Semantic Kernel?", tools=mcp_server)
|
||||
```
|
||||
|
||||
For complete MCP examples, see:
|
||||
- [Foundry with MCP tools](../../../python/samples/getting_started/agents/foundry/foundry_with_local_mcp.py)
|
||||
|
||||
## Custom agents
|
||||
|
||||
It is also possible to create fully custom agents that are not just wrappers around a chat client.
|
||||
Agent Framework provides the `AgentProtocol` protocol and `BaseAgent` base class, which when implemented/subclassed allows for complete control over the agent's behavior and capabilities.
|
||||
|
||||
```python
|
||||
from agent_framework import BaseAgent, AgentRunResponse, AgentRunResponseUpdate, AgentThread, ChatMessage
|
||||
from collections.abc import AsyncIterable
|
||||
|
||||
class CustomAgent(BaseAgent):
|
||||
async def run(
|
||||
self,
|
||||
messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
|
||||
*,
|
||||
thread: AgentThread | None = None,
|
||||
**kwargs: Any,
|
||||
) -> AgentRunResponse:
|
||||
# Custom agent implementation
|
||||
pass
|
||||
|
||||
def run_stream(
|
||||
self,
|
||||
messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
|
||||
*,
|
||||
thread: AgentThread | None = None,
|
||||
**kwargs: Any,
|
||||
) -> AsyncIterable[AgentRunResponseUpdate]:
|
||||
# Custom streaming implementation
|
||||
pass
|
||||
```
|
||||
@@ -1,140 +0,0 @@
|
||||
# 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 `ChatAgent` based on a Foundry agent, the conversation history is persisted in the service. While when using a `ChatAgent` based on chat completion with gpt-4, 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 `get_new_thread()` 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.
|
||||
|
||||
```python
|
||||
# Create a new thread.
|
||||
thread = agent.get_new_thread()
|
||||
# Run the agent with the thread.
|
||||
response = await agent.run("Hello, how are you?", thread=thread)
|
||||
|
||||
# Run an agent with a temporary thread.
|
||||
response = await agent.run("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.
|
||||
|
||||
```python
|
||||
# Create a new thread.
|
||||
thread = agent.get_new_thread()
|
||||
# Run the agent with the thread.
|
||||
response = await agent.run("Hello, how are you?", thread=thread)
|
||||
|
||||
# Serialize the thread for storage.
|
||||
serialized_thread = await thread.serialize()
|
||||
# Deserialize the thread state after loading from storage.
|
||||
resumed_thread = await agent.deserialize_thread(serialized_thread)
|
||||
|
||||
# Run the agent with the resumed thread.
|
||||
response = await agent.run("Hello, how are you?", thread=resumed_thread)
|
||||
```
|
||||
|
||||
### Custom Message Stores
|
||||
|
||||
For in-memory threads, you can provide a custom message store implementation to control how messages are stored and retrieved:
|
||||
|
||||
```python
|
||||
from agent_framework import AgentThread, ChatMessageList, ChatAgent
|
||||
from agent_framework.foundry import FoundryChatClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
|
||||
# Using the default in-memory message store
|
||||
thread = AgentThread(message_store=ChatMessageList())
|
||||
|
||||
# Or let the agent create one automatically
|
||||
thread = agent.get_new_thread()
|
||||
|
||||
# You can also provide a custom message store factory when creating the agent
|
||||
def custom_message_store_factory():
|
||||
return ChatMessageList() # or your custom implementation
|
||||
|
||||
async with AzureCliCredential() as credential:
|
||||
agent = ChatAgent(
|
||||
chat_client=FoundryChatClient(async_credential=credential),
|
||||
instructions="You are a helpful assistant",
|
||||
chat_message_store_factory=custom_message_store_factory
|
||||
)
|
||||
```
|
||||
|
||||
## 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 `ChatAgent` with the responses service, `AgentThread` instances created by this agent, will not work with a `ChatAgent` 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.
|
||||
|
||||
## Practical Multi-Turn Example
|
||||
|
||||
Here's a complete example showing how to maintain context across multiple interactions:
|
||||
|
||||
```python
|
||||
from agent_framework import ChatAgent, AgentThread
|
||||
from agent_framework.foundry import FoundryChatClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
|
||||
async def foundry_multi_turn_example():
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
ChatAgent(
|
||||
chat_client=FoundryChatClient(async_credential=credential),
|
||||
instructions="You are a helpful assistant"
|
||||
) as agent
|
||||
):
|
||||
# Create a thread for persistent conversation
|
||||
thread = agent.get_new_thread()
|
||||
|
||||
# First interaction
|
||||
response1 = await agent.run("My name is Alice", thread=thread)
|
||||
print(f"Agent: {response1.text}")
|
||||
|
||||
# Second interaction - agent remembers the name
|
||||
response2 = await agent.run("What's my name?", thread=thread)
|
||||
print(f"Agent: {response2.text}") # Should mention "Alice"
|
||||
|
||||
# Serialize thread for storage
|
||||
serialized = await thread.serialize()
|
||||
|
||||
# Later, deserialize and continue conversation
|
||||
new_thread = await agent.deserialize_thread(serialized)
|
||||
response3 = await agent.run("What did we talk about?", thread=new_thread)
|
||||
print(f"Agent: {response3.text}") # Should remember previous context
|
||||
```
|
||||
|
||||
For complete threading examples, see:
|
||||
- [Foundry with threads](../../../python/samples/getting_started/agents/foundry/foundry_with_thread.py)
|
||||
- [Custom message store](../../../python/samples/getting_started/threads/custom_chat_message_store_thread.py)
|
||||
- [Suspend and resume threads](../../../python/samples/getting_started/threads/suspend_resume_thread.py)
|
||||
|
||||
## 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 |
|
||||
Reference in New Issue
Block a user