mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Copilot
7e98b0cd29
* Initial plan * Update HostedAgents samples to Azure.AI.AgentServer.AgentFramework 1.0.0-beta.9 and MEAI 10.3.0 Co-authored-by: rogerbarreto <19890735+rogerbarreto@users.noreply.github.com> * Fix HostedAgents samples for Microsoft.Agents.AI 1.0.0-rc2 API changes - Rename CreateAIAgent -> AsAIAgent (AgentThreadAndHITL, AgentWithHostedMCP, AgentWithTextSearchRag) - Rename AsAgent -> AsAIAgent (AgentsInWorkflows) - Replace AIContextProviderFactory with AIContextProviders and simplified TextSearchProvider ctor (AgentWithTextSearchRag) - Update Microsoft.Agents.AI.OpenAI to 1.0.0-rc2 (AgentThreadAndHITL, AgentWithTextSearchRag, AgentWithTools) - Update Microsoft.Agents.AI.Workflows to 1.0.0-rc2 (AgentsInWorkflows) - Add Microsoft.Agents.AI 1.0.0-rc2 reference (AgentWithHostedMCP) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update HostedAgents samples for beta.9 API changes and add missing projects to slnx - Use DefaultAzureCredential consistently across all samples - Add AgentThreadAndHITL, AgentWithLocalTools, AgentWithTools to slnx - Apply dotnet format Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Remove unnecessary Microsoft.Agents.AI.* package references (transitive from AgentFramework) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add DefaultAzureCredential production warning comments to all HostedAgents samples Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update HostedAgents READMEs to reflect DefaultAzureCredential usage Replace AzureCliCredential references with DefaultAzureCredential in all HostedAgents README files to match the actual sample code. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Replace Microsoft.Extensions.AI.OpenAI with Microsoft.Agents.AI.OpenAI and remove AsIChatClient() Swap package references from Microsoft.Extensions.AI.OpenAI to Microsoft.Agents.AI.OpenAI across all 6 HostedAgents samples. This enables using the AsAIAgent() extension directly on ChatClient/ResponsesClient (from OpenAI.Chat/OpenAI.Responses namespaces), removing the intermediate AsIChatClient() call in 3 samples where it was unnecessary. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Use explicit types and AsAIAgent() extensions across all HostedAgents samples Replace var with explicit types for clarity in all 6 samples. Replace new ChatClientAgent() constructor calls with chatClient.AsAIAgent() extension method in AgentWithLocalTools and AgentsInWorkflows. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: rogerbarreto <19890735+rogerbarreto@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
128 lines
6.3 KiB
Markdown
128 lines
6.3 KiB
Markdown
# Hosted Agent Samples
|
|
|
|
These samples demonstrate how to build and host AI agents using the [Azure AI AgentServer SDK](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/ai.agentserver.agentframework-readme). Each sample can be run locally and deployed to Microsoft Foundry as a hosted agent.
|
|
|
|
## Samples
|
|
|
|
| Sample | Description |
|
|
|--------|-------------|
|
|
| [`AgentWithTools`](./AgentWithTools/) | Foundry tools (MCP + code interpreter) via `UseFoundryTools` |
|
|
| [`AgentWithLocalTools`](./AgentWithLocalTools/) | Local C# function tool execution (Seattle hotel search) |
|
|
| [`AgentThreadAndHITL`](./AgentThreadAndHITL/) | Human-in-the-loop with `ApprovalRequiredAIFunction` and thread persistence |
|
|
| [`AgentWithHostedMCP`](./AgentWithHostedMCP/) | Hosted MCP server tool (Microsoft Learn search) |
|
|
| [`AgentWithTextSearchRag`](./AgentWithTextSearchRag/) | RAG with `TextSearchProvider` (Contoso Outdoors) |
|
|
| [`AgentsInWorkflows`](./AgentsInWorkflows/) | Sequential workflow pipeline (translation chain) |
|
|
| [`FoundryMultiAgent`](./FoundryMultiAgent/) | Multi-agent Writer-Reviewer workflow using `AIProjectClient.CreateAIAgentAsync()` from [Microsoft.Agents.AI.AzureAI](https://www.nuget.org/packages/Microsoft.Agents.AI.AzureAI/) |
|
|
| [`FoundrySingleAgent`](./FoundrySingleAgent/) | Single agent with local C# tool execution (hotel search) using `AIProjectClient.CreateAIAgentAsync()` from [Microsoft.Agents.AI.AzureAI](https://www.nuget.org/packages/Microsoft.Agents.AI.AzureAI/) |
|
|
|
|
## Common Prerequisites
|
|
|
|
Before running any sample, ensure you have:
|
|
|
|
1. **.NET 10 SDK** or later — [Download](https://dotnet.microsoft.com/download/dotnet/10.0)
|
|
2. **Azure CLI** installed — [Install guide](https://learn.microsoft.com/cli/azure/install-azure-cli)
|
|
3. **Azure OpenAI** or **Azure AI Foundry project** with a chat model deployed (e.g., `gpt-4o-mini`)
|
|
|
|
### Authenticate with Azure CLI
|
|
|
|
All samples use `DefaultAzureCredential` for authentication, which automatically probes multiple credential sources (environment variables, managed identity, Azure CLI, etc.). For local development, the simplest approach is to authenticate via Azure CLI:
|
|
|
|
```powershell
|
|
az login
|
|
az account show # Verify the correct subscription
|
|
```
|
|
|
|
### Common Environment Variables
|
|
|
|
Most samples require one or more of these environment variables:
|
|
|
|
| Variable | Used By | Description |
|
|
|----------|---------|-------------|
|
|
| `AZURE_OPENAI_ENDPOINT` | Most samples | Your Azure OpenAI resource endpoint URL |
|
|
| `AZURE_OPENAI_DEPLOYMENT_NAME` | Most samples | Chat model deployment name (defaults to `gpt-4o-mini`) |
|
|
| `AZURE_AI_PROJECT_ENDPOINT` | AgentWithTools, AgentWithLocalTools, FoundryMultiAgent, FoundrySingleAgent | Azure AI Foundry project endpoint |
|
|
| `MCP_TOOL_CONNECTION_ID` | AgentWithTools | Foundry MCP tool connection name |
|
|
| `MODEL_DEPLOYMENT_NAME` | AgentWithLocalTools, FoundryMultiAgent, FoundrySingleAgent | Chat model deployment name (defaults to `gpt-4o-mini`) |
|
|
|
|
See each sample's README for the specific variables required.
|
|
|
|
## Azure AI Foundry Setup (for samples that use Foundry)
|
|
|
|
Some samples (`AgentWithTools`, `AgentWithLocalTools`) connect to an Azure AI Foundry project. If you're using these samples, you'll need additional setup.
|
|
|
|
### Azure AI Developer Role
|
|
|
|
The `UseFoundryTools` extension requires the **Azure AI Developer** role on the Cognitive Services resource. Even if you created the project, you may not have this role by default.
|
|
|
|
```powershell
|
|
az role assignment create `
|
|
--role "Azure AI Developer" `
|
|
--assignee "your-email@microsoft.com" `
|
|
--scope "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.CognitiveServices/accounts/{account-name}"
|
|
```
|
|
|
|
> **Note**: You need **Owner** or **User Access Administrator** permissions on the resource to assign roles. If you don't have this, you may need to request JIT (Just-In-Time) elevated access via [Azure PIM](https://portal.azure.com/#view/Microsoft_Azure_PIMCommon/ActivationMenuBlade/~/aadmigratedresource).
|
|
|
|
For more details on permissions, see [Azure AI Foundry Permissions](https://aka.ms/FoundryPermissions).
|
|
|
|
### Creating an MCP Tool Connection
|
|
|
|
The `AgentWithTools` sample requires an MCP tool connection configured in your Foundry project:
|
|
|
|
1. Go to the [Azure AI Foundry portal](https://ai.azure.com)
|
|
2. Navigate to your project
|
|
3. Go to **Connected resources** → **+ New connection** → **Model Context Protocol tool**
|
|
4. Fill in:
|
|
- **Name**: `SampleMCPTool` (or any name you prefer)
|
|
- **Remote MCP Server endpoint**: `https://learn.microsoft.com/api/mcp`
|
|
- **Authentication**: `Unauthenticated`
|
|
5. Click **Connect**
|
|
|
|
The connection **name** (e.g., `SampleMCPTool`) is used as the `MCP_TOOL_CONNECTION_ID` environment variable.
|
|
|
|
> **Important**: Use only the connection **name**, not the full ARM resource ID.
|
|
|
|
## Running a Sample
|
|
|
|
Each sample runs as a standalone hosted agent on `http://localhost:8088/`:
|
|
|
|
```powershell
|
|
cd <sample-directory>
|
|
dotnet run
|
|
```
|
|
|
|
### Interacting with the Agent
|
|
|
|
Each sample includes a `run-requests.http` file for testing with the [VS Code REST Client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) extension, or you can use PowerShell:
|
|
|
|
```powershell
|
|
$body = @{ input = "Your question here" } | ConvertTo-Json
|
|
Invoke-RestMethod -Uri "http://localhost:8088/responses" -Method Post -Body $body -ContentType "application/json"
|
|
```
|
|
|
|
## Deploying to Microsoft Foundry
|
|
|
|
Each sample includes a `Dockerfile` and `agent.yaml` for deployment. To deploy your agent to Microsoft Foundry, follow the [hosted agents deployment guide](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents).
|
|
|
|
## Troubleshooting
|
|
|
|
### `PermissionDenied` — lacks `agents/write` data action
|
|
|
|
Assign the **Azure AI Developer** role to your user. See [Azure AI Developer Role](#azure-ai-developer-role) above.
|
|
|
|
### `Project connection ... was not found`
|
|
|
|
Make sure `MCP_TOOL_CONNECTION_ID` contains only the connection **name** (e.g., `SampleMCPTool`), not the full ARM resource ID path.
|
|
|
|
### `AZURE_AI_PROJECT_ENDPOINT must be set`
|
|
|
|
The `UseFoundryTools` extension requires `AZURE_AI_PROJECT_ENDPOINT`. Set it to your Foundry project endpoint (e.g., `https://your-resource.services.ai.azure.com/api/projects/your-project`).
|
|
|
|
### Multi-framework error when running `dotnet run`
|
|
|
|
If you see "Your project targets multiple frameworks", specify the framework:
|
|
|
|
```powershell
|
|
dotnet run --framework net10.0
|
|
```
|