csharp hosted local tools example for AgentFramework (#520)

* Sample for local tool calls in agent

* Remove image since it is not relevant.

* Updating sample to use hotels instead of date and time for local tool calls

* -Align PROJECT_ENDPOINT and MODEL_DEPLOYMENT_NAME with azd conventions for agents
and add VS Code launch.json for easier local debugging

* Updating model to use chat reference from resources

* Adding AgentWithLocalTools csharp sample

* Updating default model

* Moving to AgentFramework folder

Author: eamonoreilly

samples/csharp/hosted-agents/AgentFramework/AgentWithLocalTools/.dockerignore

@@ -0,0 +1,29 @@
+# Build outputs
+bin/
+obj/
+out/
+
+# Environment files with secrets
+.env
+.env.*
+*.local
+appsettings.*.json
+!appsettings.json
+
+# IDE and editor files
+.vs/
+.vscode/
+*.user
+*.suo
+*.sln.docstates
+
+# Git
+.git/
+.gitignore
+
+# Documentation and samples (not needed in container)
+*.md
+*.http
+
+# Test results
+TestResults/

samples/csharp/hosted-agents/AgentFramework/AgentWithLocalTools/AgentWithLocalTools.csproj

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk">
+    <PropertyGroup>
+        <OutputType>Exe</OutputType>
+        <TargetFramework>net10.0</TargetFramework>
+        <Nullable>enable</Nullable>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <EnablePreviewFeatures>true</EnablePreviewFeatures>
+    </PropertyGroup>
+    
+    <ItemGroup>
+        <PackageReference Include="Azure.AI.AgentServer.AgentFramework" Version="1.0.0-beta.6" />
+        <PackageReference Include="Azure.AI.Projects" Version="1.2.0-beta.5" />
+        <PackageReference Include="Azure.AI.OpenAI" Version="2.8.0-beta.1" />
+        <PackageReference Include="Azure.Identity" Version="1.17.1" />
+        <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="10.2.0-preview.1.26063.2" />
+    </ItemGroup>
+</Project>

samples/csharp/hosted-agents/AgentFramework/AgentWithLocalTools/Dockerfile

@@ -0,0 +1,20 @@
+# Build the application
+FROM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build
+WORKDIR /src
+
+# Copy files from the current directory on the host to the working directory in the container
+COPY . .
+
+RUN dotnet restore
+RUN dotnet build -c Release --no-restore
+RUN dotnet publish -c Release --no-build -o /app
+
+# Run the application
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
+WORKDIR /app
+
+# Copy everything needed to run the app from the "build" stage.
+COPY --from=build /app .
+
+EXPOSE 8088
+ENTRYPOINT ["dotnet", "AgentWithLocalTools.dll"]

samples/csharp/hosted-agents/AgentFramework/AgentWithLocalTools/Program.cs

@@ -0,0 +1,136 @@
+// Seattle Hotel Agent - A simple agent with a tool to find hotels in Seattle.
+// Uses Microsoft Agent Framework with Azure AI Foundry.
+// Ready for deployment to Foundry Hosted Agent service.
+
+using System.ComponentModel;
+using System.Globalization;
+using System.Text;
+using System.ClientModel.Primitives;
+using Azure.AI.AgentServer.AgentFramework.Extensions;
+using Azure.AI.OpenAI;
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+// Get configuration from environment variables
+var endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME") ?? "gpt-4.1-mini";
+Console.WriteLine($"Project Endpoint: {endpoint}");
+Console.WriteLine($"Model Deployment: {deploymentName}");
+// Simulated hotel data for Seattle
+var seattleHotels = new[]
+{
+    new Hotel("Contoso Suites", 189, 4.5, "Downtown"),
+    new Hotel("Fabrikam Residences", 159, 4.2, "Pike Place Market"),
+    new Hotel("Alpine Ski House", 249, 4.7, "Seattle Center"),
+    new Hotel("Margie's Travel Lodge", 219, 4.4, "Waterfront"),
+    new Hotel("Northwind Inn", 139, 4.0, "Capitol Hill"),
+    new Hotel("Relecloud Hotel", 99, 3.8, "University District"),
+};
+
+[Description("Get available hotels in Seattle for the specified dates. This simulates a call to a hotel availability API.")]
+string GetAvailableHotels(
+    [Description("Check-in date in YYYY-MM-DD format")] string checkInDate,
+    [Description("Check-out date in YYYY-MM-DD format")] string checkOutDate,
+    [Description("Maximum price per night in USD (optional, defaults to 500)")] int maxPrice = 500)
+{
+    try
+    {
+        // Parse dates
+        if (!DateTime.TryParseExact(checkInDate, "yyyy-MM-dd", CultureInfo.InvariantCulture, DateTimeStyles.None, out var checkIn))
+        {
+            return $"Error parsing check-in date. Please use YYYY-MM-DD format.";
+        }
+
+        if (!DateTime.TryParseExact(checkOutDate, "yyyy-MM-dd", CultureInfo.InvariantCulture, DateTimeStyles.None, out var checkOut))
+        {
+            return $"Error parsing check-out date. Please use YYYY-MM-DD format.";
+        }
+
+        // Validate dates
+        if (checkOut <= checkIn)
+        {
+            return "Error: Check-out date must be after check-in date.";
+        }
+
+        var nights = (checkOut - checkIn).Days;
+
+        // Filter hotels by price
+        var availableHotels = seattleHotels.Where(h => h.PricePerNight <= maxPrice).ToList();
+
+        if (availableHotels.Count == 0)
+        {
+            return $"No hotels found in Seattle within your budget of ${maxPrice}/night.";
+        }
+
+        // Build response
+        var result = new StringBuilder();
+        result.AppendLine($"Available hotels in Seattle from {checkInDate} to {checkOutDate} ({nights} nights):");
+        result.AppendLine();
+
+        foreach (var hotel in availableHotels)
+        {
+            var totalCost = hotel.PricePerNight * nights;
+            result.AppendLine($"**{hotel.Name}**");
+            result.AppendLine($"   Location: {hotel.Location}");
+            result.AppendLine($"   Rating: {hotel.Rating}/5");
+            result.AppendLine($"   ${hotel.PricePerNight}/night (Total: ${totalCost})");
+            result.AppendLine();
+        }
+
+        return result.ToString();
+    }
+    catch (Exception ex)
+    {
+        return $"Error processing request. Details: {ex.Message}";
+    }
+}
+
+// Create chat client using AIProjectClient to get the OpenAI connection from the project
+var credential = new DefaultAzureCredential();
+AIProjectClient projectClient = new AIProjectClient(new Uri(endpoint), credential);
+
+// Get the OpenAI connection from the project
+ClientConnection connection = projectClient.GetConnection(typeof(AzureOpenAIClient).FullName!);
+
+if (!connection.TryGetLocatorAsUri(out Uri? openAiEndpoint) || openAiEndpoint is null)
+{
+    throw new InvalidOperationException("Failed to get OpenAI endpoint from project connection.");
+}
+openAiEndpoint = new Uri($"https://{openAiEndpoint.Host}");
+Console.WriteLine($"OpenAI Endpoint: {openAiEndpoint}");
+
+var chatClient = new AzureOpenAIClient(openAiEndpoint, credential)
+    .GetChatClient(deploymentName)
+    .AsIChatClient()
+    .AsBuilder()
+    .UseOpenTelemetry(sourceName: "Agents", configure: cfg => cfg.EnableSensitiveData = false)
+    .Build();
+
+var agent = new ChatClientAgent(chatClient,
+    name: "SeattleHotelAgent",
+    instructions: """
+        You are a helpful travel assistant specializing in finding hotels in Seattle, Washington.
+
+        When a user asks about hotels in Seattle:
+        1. Ask for their check-in and check-out dates if not provided
+        2. Ask about their budget preferences if not mentioned
+        3. Use the GetAvailableHotels tool to find available options
+        4. Present the results in a friendly, informative way
+        5. Offer to help with additional questions about the hotels or Seattle
+
+        Be conversational and helpful. If users ask about things outside of Seattle hotels,
+        politely let them know you specialize in Seattle hotel recommendations.
+        """,
+    tools: [AIFunctionFactory.Create(GetAvailableHotels)])
+    .AsBuilder()
+    .UseOpenTelemetry(sourceName: "Agents", configure: cfg => cfg.EnableSensitiveData = false)
+    .Build();
+
+Console.WriteLine("Seattle Hotel Agent Server running on http://localhost:8088");
+await agent.RunAIAgentAsync(telemetrySourceName: "Agents");
+
+// Hotel record for simulated data
+record Hotel(string Name, int PricePerNight, double Rating, string Location);

samples/csharp/hosted-agents/AgentFramework/AgentWithLocalTools/README.md

@@ -0,0 +1,132 @@
+**IMPORTANT!** All samples and other resources made available in this GitHub repository ("samples") are designed to assist in accelerating development of agents, solutions, and agent workflows for various scenarios. Review all provided resources and carefully test output behavior in the context of your use case. AI responses may be inaccurate and AI actions should be monitored with human oversight. Learn more in the transparency documents for [Agent Service](https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/agents/transparency-note) and [Agent Framework](https://github.com/microsoft/agent-framework/blob/main/TRANSPARENCY_FAQ.md).
+
+Agents, solutions, or other output you create may be subject to legal and regulatory requirements, may require licenses, or may not be suitable for all industries, scenarios, or use cases. By using any sample, you are acknowledging that any output created using those samples are solely your responsibility, and that you will comply with all applicable laws, regulations, and relevant safety standards, terms of service, and codes of conduct.
+
+Third-party samples contained in this folder are subject to their own designated terms, and they have not been tested or verified by Microsoft or its affiliates.
+
+Microsoft has no responsibility to you or others with respect to any of these samples or any resulting output.
+
+# What this sample demonstrates
+
+This sample demonstrates a **key advantage of code-based hosted agents**:
+
+- **Local C# tool execution** - Run custom C# methods as agent tools
+
+Code-based agents can execute **any C# code** you write. This sample includes a Seattle Hotel Agent with a `GetAvailableHotels` tool that searches for available hotels based on check-in/check-out dates and budget preferences.
+
+The agent is hosted using the [Azure AI AgentServer SDK](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/ai.agentserver.agentframework-readme) and can be deployed to Microsoft Foundry using the Azure Developer CLI.
+
+## How It Works
+
+### Local Tools Integration
+
+In [Program.cs](Program.cs), the agent uses a local C# method (`GetAvailableHotels`) that simulates a hotel availability API. This demonstrates how code-based agents can execute custom server-side logic that prompt agents cannot access.
+
+The tool accepts:
+- **checkInDate** - Check-in date in YYYY-MM-DD format
+- **checkOutDate** - Check-out date in YYYY-MM-DD format  
+- **maxPrice** - Maximum price per night in USD (optional, defaults to $500)
+
+### Agent Hosting
+
+The agent is hosted using the [Azure AI AgentServer SDK](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/ai.agentserver.agentframework-readme),
+which provisions a REST API endpoint compatible with the OpenAI Responses protocol.
+
+### Agent Deployment
+
+The hosted agent can be deployed to Microsoft Foundry using the Azure Developer CLI [ai agent](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents?view=foundry&tabs=cli#create-a-hosted-agent) extension.
+
+## Running the Agent Locally
+
+### Prerequisites
+
+Before running this sample, ensure you have:
+
+1. **Azure AI Foundry Project**
+   - Project created in [Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-foundry?view=foundry#microsoft-foundry-portals)
+   - Chat model deployed (e.g., `gpt-4o` or `gpt-4.1`)
+   - Note your project endpoint URL and model deployment name
+
+2. **Azure CLI**
+   - Installed and authenticated
+   - Run `az login` and verify with `az account show`
+
+3. **.NET 10.0 SDK or later**
+   - Verify your version: `dotnet --version`
+   - Download from [https://dotnet.microsoft.com/download](https://dotnet.microsoft.com/download)
+
+### Environment Variables
+
+Set the following environment variables (matching `agent.yaml`):
+
+- `AZURE_AI_PROJECT_ENDPOINT` - Your Azure AI Foundry project endpoint URL (required)
+- `MODEL_DEPLOYMENT_NAME` - The deployment name for your chat model (defaults to `gpt-4.1-mini`)
+
+**PowerShell:**
+
+```powershell
+# Replace with your actual values
+$env:AZURE_AI_PROJECT_ENDPOINT="https://<your-resource>.services.ai.azure.com/api/projects/<your-project>"
+$env:MODEL_DEPLOYMENT_NAME="gpt-4.1-mini"
+```
+
+**Bash:**
+
+```bash
+export AZURE_AI_PROJECT_ENDPOINT="https://<your-resource>.services.ai.azure.com/api/projects/<your-project>"
+export MODEL_DEPLOYMENT_NAME="gpt-4.1-mini"
+```
+
+### Running the Sample
+
+To run the agent, execute the following command in your terminal:
+
+```bash
+dotnet run
+```
+
+This will start the hosted agent locally on `http://localhost:8088/`.
+
+### Interacting with the Agent
+
+**PowerShell (Windows):**
+```powershell
+$body = @{
+    input = "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under $200 per night"
+    stream = $false
+} | ConvertTo-Json
+
+Invoke-RestMethod -Uri http://localhost:8088/responses -Method Post -Body $body -ContentType "application/json"
+```
+
+**Bash/curl (Linux/macOS):**
+```bash
+curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
+   -d '{"input": "Find me hotels in Seattle for March 20-23, 2025 under $200 per night","stream":false}'
+```
+
+You can also use the `run-requests.http` file in this directory with the VS Code REST Client extension.
+
+The agent will use the `GetAvailableHotels` tool to search for available hotels matching your criteria.
+
+### Deploying the Agent to Microsoft Foundry
+
+To deploy your agent to Microsoft Foundry, follow the comprehensive deployment guide at https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents?view=foundry&tabs=cli
+
+## Troubleshooting
+
+### Images built on Apple Silicon or other ARM64 machines do not work on our service
+
+We **recommend using `azd` cloud build**, which always builds images with the correct architecture.
+
+If you choose to **build locally**, and your machine is **not `linux/amd64`** (for example, an Apple Silicon Mac), the image will **not be compatible with our service**, causing runtime failures.
+
+**Fix for local builds**
+
+Use this command to build the image locally:
+
+```shell
+docker build --platform=linux/amd64 -t image .
+```
+
+This forces the image to be built for the required `amd64` architecture.

samples/csharp/hosted-agents/AgentFramework/AgentWithLocalTools/agent.yaml

@@ -0,0 +1,32 @@
+# Unique identifier/name for this agent
+name: seattle-hotel-agent
+# Brief description of what this agent does
+description: >
+  A travel assistant agent that helps users find hotels in Seattle.
+  Demonstrates local C# tool execution - a key advantage of code-based 
+  hosted agents over prompt agents.
+metadata:
+  # Categorization tags for organizing and discovering agents
+  authors:
+    - Microsoft
+  tags:
+    - Azure AI AgentServer
+    - Microsoft Agent Framework
+    - Local Tools
+    - Travel Assistant
+    - Hotel Search
+template:
+  name: seattle-hotel-agent
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: v1
+  environment_variables:
+    - name: AZURE_AI_PROJECT_ENDPOINT
+      value: ${AZURE_AI_PROJECT_ENDPOINT}
+    - name: MODEL_DEPLOYMENT_NAME
+      value: "{{chat}}"
+resources:
+  - kind: model
+    id: gpt-4.1-mini
+    name: chat