mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Roger Barreto
9a47620f64
* Bump HostedAgents samples to AgentFramework beta.11 and pass credential to UseFoundryTools Update all 8 HostedAgents samples: - Azure.AI.AgentServer.AgentFramework -> 1.0.0-beta.11 - Microsoft.Agents.AI.OpenAI -> 1.0.0-rc4 - Microsoft.Agents.AI/AzureAI/Workflows -> 1.0.0-rc4 - Azure.AI.Projects -> 2.0.0-beta.1 - Fix Workflow.AsAgent() -> AsAIAgent() in FoundryMultiAgent - Pass credential to UseFoundryTools in AgentWithTools (resolves #56802) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Remove AgentWithTools sample (UseFoundryTools no longer supported) Remove the AgentWithTools hosted agent sample as the UseFoundryTools backend is no longer supported. Updated HostedAgents README and solution file to remove all references. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix AgentWithHostedMCP: downgrade Azure.AI.OpenAI to 2.8.0-beta.1 for rc4 compatibility Azure.AI.OpenAI 2.9.0-beta.1 has breaking changes (GetResponsesClient no longer accepts deployment name, ResponsesClient.Model removed) that are incompatible with Microsoft.Agents.AI.OpenAI rc4. Pin to 2.8.0-beta.1 and use GetResponsesClient(deploymentName).AsAIAgent() pattern. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
101 lines
5.1 KiB
Markdown
101 lines
5.1 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 |
|
|
|--------|-------------|
|
|
| [`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` | AgentWithLocalTools, FoundryMultiAgent, FoundrySingleAgent | Azure AI Foundry project endpoint |
|
|
| `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 (`AgentWithLocalTools`, `FoundrySingleAgent`, `FoundryMultiAgent`) connect to an Azure AI Foundry project. If you're using these samples, you'll need additional setup.
|
|
|
|
### Azure AI Developer Role
|
|
|
|
Some Foundry operations require 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).
|
|
|
|
## 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.
|
|
|
|
### Multi-framework error when running `dotnet run`
|
|
|
|
If you see "Your project targets multiple frameworks", specify the framework:
|
|
|
|
```powershell
|
|
dotnet run --framework net10.0
|
|
```
|