diff --git a/skills/dotnet-microsoft-agent-framework/SKILL.md b/skills/dotnet-microsoft-agent-framework/SKILL.md index 36dc8f9..0738850 100644 --- a/skills/dotnet-microsoft-agent-framework/SKILL.md +++ b/skills/dotnet-microsoft-agent-framework/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-microsoft-agent-framework -version: "1.4.0" +version: "1.5.0" category: "AI" description: "Build .NET AI agents and multi-agent workflows with Microsoft Agent Framework using the right agent type, threads, tools, workflows, hosting protocols, and enterprise guardrails." compatibility: "Requires preview-era Microsoft Agent Framework packages and a .NET application that truly needs agentic or workflow orchestration." diff --git a/skills/dotnet-microsoft-agent-framework/references/official-docs-index.md b/skills/dotnet-microsoft-agent-framework/references/official-docs-index.md index ce1bab8..7a44467 100644 --- a/skills/dotnet-microsoft-agent-framework/references/official-docs-index.md +++ b/skills/dotnet-microsoft-agent-framework/references/official-docs-index.md @@ -6,7 +6,7 @@ The local snapshot lives under `references/official-docs/`. ## Scope -- Mirrored authored docs: `102` markdown pages across overview, tutorials, user guide, integrations, migration, and support +- Mirrored authored docs: `100` markdown pages across overview, tutorials, user guide, integrations, migration, and support - Live-only Learn pages added into the mirror: `support/faq.md`, `support/troubleshooting.md`, and `support/upgrade/index.md` - Generated API references are not mirrored page-by-page; use the live `.NET` API landing page when exact symbols matter - Intentional exclusions: media files, TOC scaffolding, breadcrumb files, DocFX support files, and Python-only upgrade pages are not mirrored into the skill @@ -103,9 +103,7 @@ The local snapshot lives under `references/official-docs/`. - [`official-docs/user-guide/agents/agent-types/a2a-agent.md`](official-docs/user-guide/agents/agent-types/a2a-agent.md) - [`official-docs/user-guide/agents/agent-types/anthropic-agent.md`](official-docs/user-guide/agents/agent-types/anthropic-agent.md) -- [`official-docs/user-guide/agents/agent-types/azure-ai-foundry-agent.md`](official-docs/user-guide/agents/agent-types/azure-ai-foundry-agent.md) -- [`official-docs/user-guide/agents/agent-types/azure-ai-foundry-models-chat-completion-agent.md`](official-docs/user-guide/agents/agent-types/azure-ai-foundry-models-chat-completion-agent.md) -- [`official-docs/user-guide/agents/agent-types/azure-ai-foundry-models-responses-agent.md`](official-docs/user-guide/agents/agent-types/azure-ai-foundry-models-responses-agent.md) +- [`official-docs/user-guide/agents/agent-types/microsoft-foundry-agents.md`](official-docs/user-guide/agents/agent-types/microsoft-foundry-agents.md) — Consolidated "Microsoft Foundry Agents" page covering persistent Azure AI Foundry Agents, Foundry Models Chat Completions, and Foundry Models Responses (all three upstream URLs now resolve to this single page) - [`official-docs/user-guide/agents/agent-types/azure-openai-chat-completion-agent.md`](official-docs/user-guide/agents/agent-types/azure-openai-chat-completion-agent.md) - [`official-docs/user-guide/agents/agent-types/azure-openai-responses-agent.md`](official-docs/user-guide/agents/agent-types/azure-openai-responses-agent.md) - [`official-docs/user-guide/agents/agent-types/chat-client-agent.md`](official-docs/user-guide/agents/agent-types/chat-client-agent.md) diff --git a/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/anthropic-agent.md b/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/anthropic-agent.md index cbebf87..181f3c0 100644 --- a/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/anthropic-agent.md +++ b/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/anthropic-agent.md @@ -430,4 +430,4 @@ See the [Agent getting started tutorials](../../../tutorials/overview.md) for mo ## Next steps > [!div class="nextstepaction"] -> [Azure AI Agents](./azure-ai-foundry-agent.md) +> [Microsoft Foundry Agents](./microsoft-foundry-agents.md) diff --git a/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/azure-ai-foundry-agent.md b/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/azure-ai-foundry-agent.md deleted file mode 100644 index 15f809f..0000000 --- a/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/azure-ai-foundry-agent.md +++ /dev/null @@ -1,347 +0,0 @@ ---- -title: Azure AI Foundry Agents -description: Learn how to use Microsoft Agent Framework with Azure AI Foundry Agents service. -zone_pivot_groups: programming-languages -author: westey-m -ms.topic: tutorial -ms.author: westey -ms.date: 09/15/2025 -ms.service: agent-framework ---- - -# Azure AI Foundry Agents - -Microsoft Agent Framework supports creating agents that use the [Azure AI Foundry Agents](/azure/ai-foundry/agents/overview) service. You can create persistent service-based agent instances with service-managed conversation threads. - -::: zone pivot="programming-language-csharp" - -## Getting Started - -Add the required NuGet packages to your project. - -```dotnetcli -dotnet add package Azure.Identity -dotnet add package Microsoft.Agents.AI.AzureAI.Persistent --prerelease -``` - -## Create Azure AI Foundry Agents - -As a first step you need to create a client to connect to the Azure AI Foundry Agents service. - -```csharp -using System; -using Azure.AI.Agents.Persistent; -using Azure.Identity; -using Microsoft.Agents.AI; - -var persistentAgentsClient = new PersistentAgentsClient( - "https://.services.ai.azure.com/api/projects/", - new AzureCliCredential()); -``` - -To use the Azure AI Foundry Agents service, you need create an agent resource in the service. -This can be done using either the Azure.AI.Agents.Persistent SDK or using Microsoft Agent Framework helpers. - -### Using the Persistent SDK - -Create a persistent agent and retrieve it as an `AIAgent` using the `PersistentAgentsClient`. - -```csharp -// Create a persistent agent -var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync( - model: "gpt-4o-mini", - name: "Joker", - instructions: "You are good at telling jokes."); - -// Retrieve the agent that was just created as an AIAgent using its ID -AIAgent agent1 = await persistentAgentsClient.GetAIAgentAsync(agentMetadata.Value.Id); - -// Invoke the agent and output the text result. -Console.WriteLine(await agent1.RunAsync("Tell me a joke about a pirate.")); -``` - -### Using Agent Framework helpers - -You can also create and return an `AIAgent` in one step: - -```csharp -AIAgent agent2 = await persistentAgentsClient.CreateAIAgentAsync( - model: "gpt-4o-mini", - name: "Joker", - instructions: "You are good at telling jokes."); -``` - -## Reusing Azure AI Foundry Agents - -You can reuse existing Azure AI Foundry Agents by retrieving them using their IDs. - -```csharp -AIAgent agent3 = await persistentAgentsClient.GetAIAgentAsync(""); -``` - -## Using the agent - -The agent is a standard `AIAgent` and supports all standard `AIAgent` operations. - -For more information on how to run and interact with agents, see the [Agent getting started tutorials](../../../tutorials/overview.md). - -::: zone-end -::: zone pivot="programming-language-python" - -## Configuration - -### Environment Variables - -Before using Azure AI Foundry Agents, you need to set up these environment variables: - -```bash -export AZURE_AI_PROJECT_ENDPOINT="https://.services.ai.azure.com/api/projects/" -export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini" -``` - -Alternatively, you can provide these values directly in your code. - -### Installation - -Add the Agent Framework Azure AI package to your project: - -```bash -pip install agent-framework-azure-ai --pre -``` - -## Getting Started - -### Authentication - -Azure AI Foundry Agents use Azure credentials for authentication. The simplest approach is to use `AzureCliCredential` after running `az login`: - -```python -from azure.identity.aio import AzureCliCredential - -async with AzureCliCredential() as credential: - # Use credential with Azure AI agent client -``` - -## Create Azure AI Foundry Agents - -### Basic Agent Creation - -The simplest way to create an agent is using the `AzureAIAgentClient` with environment variables: - -```python -import asyncio -from agent_framework.azure import AzureAIAgentClient -from azure.identity.aio import AzureCliCredential - -async def main(): - async with ( - AzureCliCredential() as credential, - AzureAIAgentClient(async_credential=credential).as_agent( - name="HelperAgent", - instructions="You are a helpful assistant." - ) as agent, - ): - result = await agent.run("Hello!") - print(result.text) - -asyncio.run(main()) -``` - -### Explicit Configuration - -You can also provide configuration explicitly instead of using environment variables: - -```python -import asyncio -from agent_framework.azure import AzureAIAgentClient -from azure.identity.aio import AzureCliCredential - -async def main(): - async with ( - AzureCliCredential() as credential, - AzureAIAgentClient( - project_endpoint="https://.services.ai.azure.com/api/projects/", - model_deployment_name="gpt-4o-mini", - async_credential=credential, - agent_name="HelperAgent" - ).as_agent( - instructions="You are a helpful assistant." - ) as agent, - ): - result = await agent.run("Hello!") - print(result.text) - -asyncio.run(main()) -``` - -## Using Existing Azure AI Foundry Agents - -### Using an Existing Agent by ID - -If you have an existing agent in Azure AI Foundry, you can use it by providing its ID: - -```python -import asyncio -from agent_framework import ChatAgent -from agent_framework.azure import AzureAIAgentClient -from azure.identity.aio import AzureCliCredential - -async def main(): - async with ( - AzureCliCredential() as credential, - ChatAgent( - chat_client=AzureAIAgentClient( - async_credential=credential, - agent_id="" - ), - instructions="You are a helpful assistant." - ) as agent, - ): - result = await agent.run("Hello!") - print(result.text) - -asyncio.run(main()) -``` - -### Create and Manage Persistent Agents - -For more control over agent lifecycle, you can create persistent agents using the Azure AI Projects client: - -```python -import asyncio -import os -from agent_framework import ChatAgent -from agent_framework.azure import AzureAIAgentClient -from azure.ai.projects.aio import AIProjectClient -from azure.identity.aio import AzureCliCredential - -async def main(): - async with ( - AzureCliCredential() as credential, - AIProjectClient( - endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - credential=credential - ) as project_client, - ): - # Create a persistent agent - created_agent = await project_client.agents.create_agent( - model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - name="PersistentAgent", - instructions="You are a helpful assistant." - ) - - try: - # Use the agent - async with ChatAgent( - chat_client=AzureAIAgentClient( - project_client=project_client, - agent_id=created_agent.id - ), - instructions="You are a helpful assistant." - ) as agent: - result = await agent.run("Hello!") - print(result.text) - finally: - # Clean up the agent - await project_client.agents.delete_agent(created_agent.id) - -asyncio.run(main()) -``` - -## Agent Features - -### Function Tools - -You can provide custom function tools to Azure AI Foundry agents: - -```python -import asyncio -from typing import Annotated -from agent_framework.azure import AzureAIAgentClient -from azure.identity.aio import AzureCliCredential -from pydantic import Field - -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 def main(): - async with ( - AzureCliCredential() as credential, - AzureAIAgentClient(async_credential=credential).as_agent( - name="WeatherAgent", - instructions="You are a helpful weather assistant.", - tools=get_weather - ) as agent, - ): - result = await agent.run("What's the weather like in Seattle?") - print(result.text) - -asyncio.run(main()) -``` - -### Code Interpreter - -Azure AI Foundry agents support code execution through the hosted code interpreter: - -```python -import asyncio -from agent_framework import HostedCodeInterpreterTool -from agent_framework.azure import AzureAIAgentClient -from azure.identity.aio import AzureCliCredential - -async def main(): - async with ( - AzureCliCredential() as credential, - AzureAIAgentClient(async_credential=credential).as_agent( - name="CodingAgent", - instructions="You are a helpful assistant that can write and execute Python code.", - tools=HostedCodeInterpreterTool() - ) as agent, - ): - result = await agent.run("Calculate the factorial of 20 using Python code.") - print(result.text) - -asyncio.run(main()) -``` - -### Streaming Responses - -Get responses as they are generated using streaming: - -```python -import asyncio -from agent_framework.azure import AzureAIAgentClient -from azure.identity.aio import AzureCliCredential - -async def main(): - async with ( - AzureCliCredential() as credential, - AzureAIAgentClient(async_credential=credential).as_agent( - name="StreamingAgent", - instructions="You are a helpful assistant." - ) as agent, - ): - print("Agent: ", end="", flush=True) - async for chunk in agent.run_stream("Tell me a short story"): - if chunk.text: - print(chunk.text, end="", flush=True) - print() - -asyncio.run(main()) -``` - -## Using the Agent - -The agent is a standard `BaseAgent` and supports all standard agent operations. - -For more information on how to run and interact with agents, see the [Agent getting started tutorials](../../../tutorials/overview.md). - -::: zone-end - -## Next steps - -> [!div class="nextstepaction"] -> [Azure AI Foundry Models based Agents](./azure-ai-foundry-models-chat-completion-agent.md) diff --git a/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/azure-ai-foundry-models-chat-completion-agent.md b/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/azure-ai-foundry-models-chat-completion-agent.md deleted file mode 100644 index d81431d..0000000 --- a/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/azure-ai-foundry-models-chat-completion-agent.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Azure AI Foundry Models ChatCompletion Agents -description: Learn how to use the Microsoft Agent Framework with Azure AI Foundry Models service via OpenAI ChatCompletion API. -zone_pivot_groups: programming-languages -author: westey-m -ms.topic: tutorial -ms.author: westey -ms.date: 10/07/2025 -ms.service: agent-framework ---- - -# Azure AI Foundry Models Agents - -The Microsoft Agent Framework supports creating agents using models deployed with Azure AI Foundry Models via an OpenAI Chat Completion compatible API, and therefore the OpenAI client libraries can be used to access Foundry models. - -[Azure AI Foundry supports deploying](/azure/ai-foundry/foundry-models/how-to/create-model-deployments?pivots=ai-foundry-portal) a wide range of models, including open source models. - -> [!NOTE] -> The capabilities of these models may limit the functionality of the agents. For example, many open source models do not support function calling and therefore any agent based on such models will not be able to use function tools. - -::: zone pivot="programming-language-csharp" - -## Getting Started - -Add the required NuGet packages to your project. - -```powershell -dotnet add package Azure.Identity -dotnet add package Microsoft.Agents.AI.OpenAI --prerelease -``` - -## Creating an OpenAI ChatCompletion Agent with Foundry Models - -As a first step you need to create a client to connect to the OpenAI service. - -Since the code is not using the default OpenAI service, the URI of the OpenAI compatible Foundry service, needs to be provided via `OpenAIClientOptions`. - -```csharp -using System; -using System.ClientModel.Primitives; -using Azure.Identity; -using Microsoft.Agents.AI; -using OpenAI; - -var clientOptions = new OpenAIClientOptions() { Endpoint = new Uri("https://.services.ai.azure.com/openai/v1/") }; - -#pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. -OpenAIClient client = new OpenAIClient(new BearerTokenPolicy(new AzureCliCredential(), "https://ai.azure.com/.default"), clientOptions); -#pragma warning restore OPENAI001 -// You can optionally authenticate with an API key -// OpenAIClient client = new OpenAIClient(new ApiKeyCredential(""), clientOptions); -``` - -A client for chat completions can then be created using the model deployment name. - -```csharp -var chatCompletionClient = client.GetChatClient("gpt-4o-mini"); -``` - -Finally, the agent can be created using the `AsAIAgent` extension method on the `ChatCompletionClient`. - -```csharp -AIAgent agent = chatCompletionClient.AsAIAgent( - instructions: "You are good at telling jokes.", - name: "Joker"); - -// Invoke the agent and output the text result. -Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.")); -``` - -## Using the Agent - -The agent is a standard `AIAgent` and supports all standard `AIAgent` operations. - -See the [Agent getting started tutorials](../../../tutorials/overview.md) for more information on how to run and interact with agents. - -::: zone-end -::: zone pivot="programming-language-python" - -More docs coming soon. - -::: zone-end - -## Next steps - -> [!div class="nextstepaction"] -> [Azure OpenAI ChatCompletion Agents](./azure-ai-foundry-models-responses-agent.md) diff --git a/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/azure-ai-foundry-models-responses-agent.md b/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/azure-ai-foundry-models-responses-agent.md deleted file mode 100644 index e8634ad..0000000 --- a/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/azure-ai-foundry-models-responses-agent.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Azure AI Foundry Models Responses Agents -description: Learn how to use the Microsoft Agent Framework with Azure AI Foundry Models service via OpenAI Responses API. -zone_pivot_groups: programming-languages -author: jozkee -ms.topic: tutorial -ms.author: dacantu -ms.date: 10/22/2025 -ms.service: agent-framework ---- - -# Azure AI Foundry Models Responses Agents - -The Microsoft Agent Framework supports creating agents using models deployed with Azure AI Foundry Models via an OpenAI Responses compatible API, and therefore the OpenAI client libraries can be used to access Foundry models. - -::: zone pivot="programming-language-csharp" - -## Getting Started - -Add the required NuGet packages to your project. - -```powershell -dotnet add package Azure.Identity -dotnet add package Microsoft.Agents.AI.OpenAI --prerelease -``` - -## Creating an OpenAI Responses Agent with Foundry Models - -As a first step you need to create a client to connect to the OpenAI service. - -Since the code is not using the default OpenAI service, the URI of the OpenAI compatible Foundry service, needs to be provided via `OpenAIClientOptions`. - -```csharp -using System; -using System.ClientModel.Primitives; -using Azure.Identity; -using Microsoft.Agents.AI; -using OpenAI; - -var clientOptions = new OpenAIClientOptions() { Endpoint = new Uri("https://.services.ai.azure.com/openai/v1/") }; - -#pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. -OpenAIClient client = new OpenAIClient(new BearerTokenPolicy(new AzureCliCredential(), "https://ai.azure.com/.default"), clientOptions); -#pragma warning restore OPENAI001 -// You can optionally authenticate with an API key -// OpenAIClient client = new OpenAIClient(new ApiKeyCredential(""), clientOptions); -``` - -A client for responses can then be created using the model deployment name. - -```csharp -#pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. -var responseClient = client.GetOpenAIResponseClient("gpt-4o-mini"); -#pragma warning restore OPENAI001 -``` - -Finally, the agent can be created using the `AsAIAgent` extension method on the `ResponseClient`. - -```csharp -AIAgent agent = responseClient.AsAIAgent( - instructions: "You are good at telling jokes.", - name: "Joker"); - -// Invoke the agent and output the text result. -Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.")); -``` - -## Using the Agent - -The agent is a standard `AIAgent` and supports all standard `AIAgent` operations. - -See the [Agent getting started tutorials](../../../tutorials/overview.md) for more information on how to run and interact with agents. - -::: zone-end -::: zone pivot="programming-language-python" - -More docs coming soon. - -::: zone-end - -## Next steps - -> [!div class="nextstepaction"] -> [Azure OpenAI Responses Agents](./azure-openai-responses-agent.md) diff --git a/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/index.md b/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/index.md index 7f375a9..e2ea4de 100644 --- a/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/index.md +++ b/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/index.md @@ -46,9 +46,7 @@ To make creating these agents even easier, Agent Framework provides helpers for | Underlying inference service | Description | Service chat history storage support | Custom chat history storage support | |------------------------------|-------------|--------------------------------------|-------------------------------------| -|[Azure AI Foundry Agent](./azure-ai-foundry-agent.md)|An agent that uses the Azure AI Foundry Agents Service as its backend.|Yes|No| -|[Azure AI Foundry Models ChatCompletion](./azure-ai-foundry-models-chat-completion-agent.md)|An agent that uses any of the models deployed in the Azure AI Foundry Service as its backend via ChatCompletion.|No|Yes| -|[Azure AI Foundry Models Responses](./azure-ai-foundry-models-responses-agent.md)|An agent that uses any of the models deployed in the Azure AI Foundry Service as its backend via Responses.|No|Yes| +|[Microsoft Foundry Agents](./microsoft-foundry-agents.md)|Persistent Azure AI Foundry Agents (service-managed threads) and Foundry Models via Chat Completions or Responses API.|Persistent agents: Yes; Models: No|Persistent agents: No; Models: Yes| |[Azure OpenAI ChatCompletion](./azure-openai-chat-completion-agent.md)|An agent that uses the Azure OpenAI ChatCompletion service.|No|Yes| |[Azure OpenAI Responses](./azure-openai-responses-agent.md)|An agent that uses the Azure OpenAI Responses service.|Yes|Yes| |[OpenAI ChatCompletion](./openai-chat-completion-agent.md)|An agent that uses the OpenAI ChatCompletion service.|No|Yes| @@ -203,7 +201,7 @@ For detailed examples, see the agent-specific documentation sections below. |Underlying Inference Service|Description|Service Chat History storage supported|Custom Chat History storage supported| |---|---|---|---| -|[Azure AI Agent](./azure-ai-foundry-agent.md)|An agent that uses the Azure AI Agents Service as its backend.|Yes|No| +|[Microsoft Foundry Agents](./microsoft-foundry-agents.md)|An agent that uses the Azure AI Foundry Agents Service (persistent) or Foundry Models (Chat Completions/Responses) as its backend.|Persistent: Yes; Models: No|Persistent: No; Models: Yes| |[Azure OpenAI Chat Completion](./azure-openai-chat-completion-agent.md)|An agent that uses the Azure OpenAI Chat Completion service.|No|Yes| |[Azure OpenAI Responses](./azure-openai-responses-agent.md)|An agent that uses the Azure OpenAI Responses service.|Yes|Yes| |[OpenAI Chat Completion](./openai-chat-completion-agent.md)|An agent that uses the OpenAI Chat Completion service.|No|Yes| diff --git a/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/microsoft-foundry-agents.md b/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/microsoft-foundry-agents.md new file mode 100644 index 0000000..fac031c --- /dev/null +++ b/skills/dotnet-microsoft-agent-framework/references/official-docs/user-guide/agents/agent-types/microsoft-foundry-agents.md @@ -0,0 +1,282 @@ +--- +title: Microsoft Foundry Agents +description: Learn how to use Microsoft Agent Framework with Azure AI Foundry — persistent service agents, Chat Completions models, and Responses models. +zone_pivot_groups: programming-languages +ms.topic: concept +ms.date: 03/17/2026 +ms.service: agent-framework +--- + +# Microsoft Foundry Agents + +Microsoft Agent Framework supports three ways to work with Azure AI Foundry: + +| Mode | API | History | NuGet | +| --- | --- | --- | --- | +| **Persistent (service-managed) agents** | Azure AI Foundry Agents SDK | Service-owned threads | `Microsoft.Agents.AI.AzureAI.Persistent` | +| **Foundry Models — Chat Completions** | OpenAI Chat Completions | Local or custom store | `Microsoft.Agents.AI.OpenAI` | +| **Foundry Models — Responses** | OpenAI Responses | Local or custom store | `Microsoft.Agents.AI.OpenAI` | + +Choose the persistent agent path when you need service-managed threads, managed tools (code interpreter, file search, web search), or operational agent lifecycle managed by the platform. + +Choose the Foundry Models path (Chat Completions or Responses) when you want to bring your own state, keep portability, and use the broadest range of open-source and partner models from the Foundry model catalog through an OpenAI-compatible API. + +::: zone pivot="programming-language-csharp" + +## Persistent Azure AI Foundry Agents + +### Getting Started + +Add the required NuGet packages. + +```dotnetcli +dotnet add package Azure.Identity +dotnet add package Microsoft.Agents.AI.AzureAI.Persistent --prerelease +``` + +### Create and Run a Persistent Agent + +```csharp +using System; +using Azure.AI.Agents.Persistent; +using Azure.Identity; +using Microsoft.Agents.AI; + +var persistentAgentsClient = new PersistentAgentsClient( + "https://.services.ai.azure.com/api/projects/", + new AzureCliCredential()); + +// Create a persistent agent resource +var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync( + model: "gpt-4o-mini", + name: "Joker", + instructions: "You are good at telling jokes."); + +// Retrieve it as an AIAgent +AIAgent agent = await persistentAgentsClient.GetAIAgentAsync(agentMetadata.Value.Id); + +Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.")); +``` + +### Using Agent Framework Helpers + +You can create and return an `AIAgent` in one step: + +```csharp +AIAgent agent = await persistentAgentsClient.CreateAIAgentAsync( + model: "gpt-4o-mini", + name: "Joker", + instructions: "You are good at telling jokes."); +``` + +### Reusing Existing Foundry Agents + +Retrieve an existing agent by its ID: + +```csharp +AIAgent agent = await persistentAgentsClient.GetAIAgentAsync(""); +``` + +## Foundry Models — Chat Completions + +### Getting Started + +Add the required NuGet packages. + +```powershell +dotnet add package Azure.Identity +dotnet add package Microsoft.Agents.AI.OpenAI --prerelease +``` + +### Create an OpenAI Chat Completion Agent with Foundry Models + +```csharp +using System; +using System.ClientModel.Primitives; +using Azure.Identity; +using Microsoft.Agents.AI; +using OpenAI; + +var clientOptions = new OpenAIClientOptions() +{ + Endpoint = new Uri("https://.services.ai.azure.com/openai/v1/") +}; + +#pragma warning disable OPENAI001 +OpenAIClient client = new OpenAIClient( + new BearerTokenPolicy(new AzureCliCredential(), "https://ai.azure.com/.default"), + clientOptions); +#pragma warning restore OPENAI001 +// Or: new OpenAIClient(new ApiKeyCredential(""), clientOptions); + +var chatCompletionClient = client.GetChatClient("gpt-4o-mini"); + +AIAgent agent = chatCompletionClient.AsAIAgent( + instructions: "You are good at telling jokes.", + name: "Joker"); + +Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.")); +``` + +## Foundry Models — Responses + +### Create an OpenAI Responses Agent with Foundry Models + +Use the same client setup as above, then use the Responses client: + +```csharp +#pragma warning disable OPENAI001 +var responseClient = client.GetOpenAIResponseClient("gpt-4o-mini"); +#pragma warning restore OPENAI001 + +AIAgent agent = responseClient.AsAIAgent( + instructions: "You are good at telling jokes.", + name: "Joker"); + +Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.")); +``` + +::: zone-end +::: zone pivot="programming-language-python" + +## Persistent Azure AI Foundry Agents (Python) + +### Environment Variables + +```bash +export AZURE_AI_PROJECT_ENDPOINT="https://.services.ai.azure.com/api/projects/" +export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini" +``` + +### Installation + +```bash +pip install agent-framework-azure-ai --pre +``` + +### Basic Agent Creation + +```python +import asyncio +from agent_framework.azure import AzureAIAgentClient +from azure.identity.aio import AzureCliCredential + +async def main(): + async with ( + AzureCliCredential() as credential, + AzureAIAgentClient(async_credential=credential).as_agent( + name="HelperAgent", + instructions="You are a helpful assistant." + ) as agent, + ): + result = await agent.run("Hello!") + print(result.text) + +asyncio.run(main()) +``` + +### Function Tools + +```python +import asyncio +from typing import Annotated +from agent_framework.azure import AzureAIAgentClient +from azure.identity.aio import AzureCliCredential +from pydantic import Field + +def get_weather( + location: Annotated[str, Field(description="The location to get weather for.")], +) -> str: + """Get the weather for a given location.""" + return f"The weather in {location} is sunny." + +async def main(): + async with ( + AzureCliCredential() as credential, + AzureAIAgentClient(async_credential=credential).as_agent( + name="WeatherAgent", + instructions="You are a weather assistant.", + tools=get_weather + ) as agent, + ): + result = await agent.run("What's the weather in Seattle?") + print(result.text) + +asyncio.run(main()) +``` + +### Streaming Responses + +```python +import asyncio +from agent_framework.azure import AzureAIAgentClient +from azure.identity.aio import AzureCliCredential + +async def main(): + async with ( + AzureCliCredential() as credential, + AzureAIAgentClient(async_credential=credential).as_agent( + name="StreamingAgent", + instructions="You are a helpful assistant." + ) as agent, + ): + print("Agent: ", end="", flush=True) + async for chunk in agent.run_stream("Tell me a short story"): + if chunk.text: + print(chunk.text, end="", flush=True) + print() + +asyncio.run(main()) +``` + +### Foundry Models (Python) + +For Foundry Models via Chat Completions or Responses from Python, use the `AzureAIAgentClient` with the appropriate Foundry Models endpoint instead of the Foundry Agents project endpoint. + +```python +import asyncio +from agent_framework.azure import AzureAIAgentClient +from azure.identity.aio import AzureCliCredential + +async def main(): + async with ( + AzureCliCredential() as credential, + AzureAIAgentClient( + project_endpoint="https://.services.ai.azure.com/openai/v1/", + model_deployment_name="gpt-4o-mini", + async_credential=credential + ).as_agent( + name="Joker", + instructions="You are good at telling jokes." + ) as agent, + ): + result = await agent.run("Tell me a joke about a pirate.") + print(result.text) + +asyncio.run(main()) +``` + +::: zone-end + +## Key Differences + +| Concern | Persistent Agent | Foundry Models (CC/Responses) | +| --- | --- | --- | +| Thread storage | Service-owned | Local or custom store | +| Hosted tools | Yes (code interpreter, file search) | No (function tools only) | +| Agent lifecycle | Managed by Azure AI Foundry | In-process | +| Portability | Lower | Higher | +| Best for | Managed resources, file access, code exec | Broadest model range, own state | + +## Using Any Agent + +Every agent created through these paths is a standard `AIAgent` and supports all standard `AIAgent` operations including multi-turn conversations, function tools, middleware, and streaming. + +See the [Agent getting started tutorials](../../../tutorials/overview.md) for more information. + +## Source + +Consolidated from upstream "Microsoft Foundry Agents | Microsoft Learn": +- `https://learn.microsoft.com/agent-framework/user-guide/agents/agent-types/azure-ai-foundry-agent` +- `https://learn.microsoft.com/agent-framework/user-guide/agents/agent-types/azure-ai-foundry-models-chat-completion-agent` +- `https://learn.microsoft.com/agent-framework/user-guide/agents/agent-types/azure-ai-foundry-models-responses-agent` diff --git a/skills/dotnet-microsoft-agent-framework/references/providers.md b/skills/dotnet-microsoft-agent-framework/references/providers.md index c8960fa..fb98b08 100644 --- a/skills/dotnet-microsoft-agent-framework/references/providers.md +++ b/skills/dotnet-microsoft-agent-framework/references/providers.md @@ -147,4 +147,4 @@ Before you commit to a local or custom model path, verify: - `references/official-docs/user-guide/agents/agent-types/azure-openai-responses-agent.md` - `references/official-docs/user-guide/agents/agent-types/openai-chat-completion-agent.md` - `references/official-docs/user-guide/agents/agent-types/openai-responses-agent.md` -- `references/official-docs/user-guide/agents/agent-types/azure-ai-foundry-agent.md` +- `references/official-docs/user-guide/agents/agent-types/microsoft-foundry-agents.md`