.NET: Bring Hosted-Toolbox sample to parity with sibling hosting samples

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AgentSkills/README.md

@@ -42,7 +42,7 @@ The agent is hosted using the [Agent Framework](https://github.com/microsoft/age
 
 ## Prerequisites
 
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
 - Azure CLI logged in (`az login`)
 
 ### Required RBAC

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-AzureSearchRag/README.md

@@ -7,7 +7,7 @@ This sample is the Azure AI Search counterpart to `Hosted-TextRag`. Where `Hoste
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
 - An Azure AI Search service ([create one](https://learn.microsoft.com/azure/search/search-create-service-portal))
 - **A pre-provisioned search index** with the schema and content described in the next section
 - Azure CLI logged in (`az login`)

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/README.md

@@ -5,7 +5,7 @@ A simple general-purpose AI assistant hosted as a Foundry Hosted Agent using the
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
 - Azure CLI logged in (`az login`)
 
 ## Configuration
@@ -16,7 +16,7 @@ Copy the template and fill in your project endpoint:
 cp .env.example .env
 ```
 
-Edit `.env` and set your Azure AI Foundry project endpoint:
+Edit `.env` and set your Foundry project endpoint:
 
 ```env
 FOUNDRY_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/Program.cs

@@ -20,7 +20,7 @@
 // indirect prompt injection in an uploaded file.
 //
 // Required environment variables:
-//   FOUNDRY_PROJECT_ENDPOINT         - Azure AI Foundry project endpoint
+//   FOUNDRY_PROJECT_ENDPOINT         - Foundry project endpoint
 //   FOUNDRY_MODEL    - Model deployment name (default: gpt-4o)
 //
 // Optional:

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Files/README.md

@@ -43,7 +43,7 @@ The end-to-end alpha-SDK round trip (client uploads via `AgentSessionFiles.Uploa
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
 - Azure CLI logged in (`az login`)
 
 ## Configuration

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-FoundryAgent/README.md

@@ -7,7 +7,7 @@ This is the **Foundry hosting** pattern — the agent's behavior is configured i
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a **registered agent** (created via Foundry UI, CLI, or API)
+- A Foundry project with a **registered agent** (created via Foundry UI, CLI, or API)
 - Azure CLI logged in (`az login`)
 
 ## Configuration
@@ -18,7 +18,7 @@ Copy the template and fill in your project endpoint:
 cp .env.example .env
 ```
 
-Edit `.env` and set your Azure AI Foundry project endpoint:
+Edit `.env` and set your Foundry project endpoint:
 
 ```env
 FOUNDRY_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalCodeAct/README.md

@@ -21,7 +21,7 @@ sample for the `agent-framework-local-codeact` package.
 - Python 3 available on `PATH` (used by `LocalCodeActProvider` to execute the
   embedded runner and validator). Override with the `LOCAL_CODEACT_PYTHON`
   environment variable if you need a specific interpreter path.
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
 - Azure CLI logged in (`az login`)
 
 ## Configuration
@@ -32,7 +32,7 @@ Copy the template and fill in your project endpoint:
 cp .env.example .env
 ```
 
-Edit `.env` and set your Azure AI Foundry project endpoint:
+Edit `.env` and set your Foundry project endpoint:
 
 ```env
 FOUNDRY_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-LocalTools/README.md

@@ -7,7 +7,7 @@ The agent specializes in finding hotels in Seattle, with a `GetAvailableHotels`
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
 - Azure CLI logged in (`az login`)
 
 ## Configuration
@@ -18,7 +18,7 @@ Copy the template and fill in your project endpoint:
 cp .env.example .env
 ```
 
-Edit `.env` and set your Azure AI Foundry project endpoint:
+Edit `.env` and set your Foundry project endpoint:
 
 ```env
 FOUNDRY_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-McpTools/README.md

@@ -19,7 +19,7 @@ A hosted agent demonstrating **two layers of MCP (Model Context Protocol) tool i
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
 - Azure CLI logged in (`az login`)
 
 ## Configuration

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-MemoryAgent/README.md

@@ -17,7 +17,7 @@ This sample exists to demonstrate two things together:
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with at least one chat model deployment and one embedding model deployment
+- A Foundry project with at least one chat model deployment and one embedding model deployment
 - Azure CLI logged in (`az login`)
 
 ## Configuration

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Observability/README.md

@@ -27,7 +27,7 @@ Foundry injects `APPLICATIONINSIGHTS_CONNECTION_STRING` when the agent runs in t
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
 - Azure CLI logged in (`az login`)
 
 ## Configuration
@@ -36,7 +36,7 @@ Foundry injects `APPLICATIONINSIGHTS_CONNECTION_STRING` when the agent runs in t
 cp .env.example .env
 ```
 
-Edit `.env` and set your Azure AI Foundry project endpoint:
+Edit `.env` and set your Foundry project endpoint:
 
 ```env
 FOUNDRY_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-TextRag/README.md

@@ -7,7 +7,7 @@ This sample demonstrates how to add knowledge grounding to a hosted agent withou
 ## Prerequisites
 
 - [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure AI Foundry project with a deployed model (e.g., `gpt-4o`)
+- A Foundry project with a deployed model (e.g., `gpt-4o`)
 - Azure CLI logged in (`az login`)
 
 ## Configuration
@@ -18,7 +18,7 @@ Copy the template and fill in your project endpoint:
 cp .env.example .env
 ```
 
-Edit `.env` and set your Azure AI Foundry project endpoint:
+Edit `.env` and set your Foundry project endpoint:
 
 ```env
 FOUNDRY_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox-AuthPaths/.env.example

@@ -1,4 +1,4 @@
-# Azure AI Foundry project endpoint (auto-injected in hosted containers).
+# Foundry project endpoint (auto-injected in hosted containers).
 AZURE_AI_PROJECT_ENDPOINT=https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>
 
 # Model deployment name. Must exist in the Foundry project above.

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox-AuthPaths/Program.cs

@@ -11,7 +11,7 @@
 //
 // Required environment variables:
 //   AZURE_AI_PROJECT_ENDPOINT (local-dev) OR FOUNDRY_PROJECT_ENDPOINT (hosted runtime)
-//                                     - Azure AI Foundry project endpoint. The Foundry hosted
+//                                     - Foundry project endpoint. The Foundry hosted
 //                                       runtime auto-injects FOUNDRY_PROJECT_ENDPOINT; locally
 //                                       set AZURE_AI_PROJECT_ENDPOINT (the AF-repo convention).
 //   TOOLBOX_NAME                      - Name of the Foundry Toolbox to load

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/.env.example

@@ -0,0 +1,16 @@
+# Foundry project endpoint (auto-injected in hosted containers).
+AZURE_AI_PROJECT_ENDPOINT=https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>
+
+# Model deployment name. Must exist in the Foundry project above.
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+
+# Name of the Foundry Toolbox you provisioned in the portal (see README.md).
+TOOLBOX_NAME=my-toolset
+
+# Agent name advertised over the wire. Must be unique if running side-by-side with
+# other Hosted-* samples (e.g. Hosted-Toolbox-AuthPaths), otherwise the REPL client
+# cannot disambiguate which agent to chat with.
+AGENT_NAME=hosted-toolbox-agent
+
+# Application Insights connection string (auto-injected in hosted containers; optional locally).
+# APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=...

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/Dockerfile

@@ -0,0 +1,17 @@
+# Use the official .NET 10.0 ASP.NET runtime as a parent image
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
+WORKDIR /app
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY . .
+RUN dotnet restore
+RUN dotnet publish -c Release -o /app/publish
+
+# Final stage
+FROM base AS final
+WORKDIR /app
+COPY --from=build /app/publish .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedToolbox.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/Dockerfile.contributor

@@ -0,0 +1,21 @@
+# Dockerfile for contributors building from the agent-framework repository source.
+#
+# This project uses ProjectReference to the local source, which means a standard
+# multi-stage Docker build cannot resolve dependencies outside this folder.
+# Pre-publish the app targeting the container runtime and copy the output:
+#
+#   dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+#   docker build -f Dockerfile.contributor -t hosted-toolbox .
+#   docker run --rm -p 8088:8088 \
+#     -e AGENT_NAME=hosted-toolbox-agent \
+#     -e AZURE_BEARER_TOKEN=$AZURE_BEARER_TOKEN \
+#     --env-file .env hosted-toolbox
+#
+# For end-users consuming the NuGet package (not ProjectReference), use the standard
+# Dockerfile which performs a full dotnet restore + publish inside the container.
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
+WORKDIR /app
+COPY out/ .
+EXPOSE 8088
+ENV ASPNETCORE_URLS=http://+:8088
+ENTRYPOINT ["dotnet", "HostedToolbox.dll"]

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/Program.cs

@@ -7,20 +7,19 @@
 //
 // Required environment variables:
 //   FOUNDRY_PROJECT_ENDPOINT (hosted runtime) OR AZURE_AI_PROJECT_ENDPOINT (local-dev)
-//                                     - Azure AI Foundry project endpoint. The Foundry hosted
+//                                     - Foundry project endpoint. The Foundry hosted
 //                                       runtime auto-injects FOUNDRY_PROJECT_ENDPOINT; locally
 //                                       set AZURE_AI_PROJECT_ENDPOINT.
-//   FOUNDRY_MODEL                     - Model deployment name (default: gpt-4o)
 //
 // Optional:
-//   FOUNDRY_TOOLBOX_NAME              - Name of the toolbox to load (default: my-toolset)
-//   FOUNDRY_AGENT_TOOLSET_ENDPOINT    - Foundry Toolsets proxy base URL
-//                                       (injected automatically by Foundry platform at runtime)
-//   FOUNDRY_AGENT_NAME                - Client name reported to MCP server (auto-injected in hosted runtime)
-//   FOUNDRY_AGENT_VERSION             - Client version reported to MCP server (auto-injected in hosted runtime)
-//   FOUNDRY_AGENT_TOOLSET_FEATURES    - Additional Foundry-Features header flags (the mandatory
-//                                       Toolboxes=V1Preview flag is always sent; this env var
-//                                       appends additional flags if present).
+//   FOUNDRY_MODEL (or AZURE_AI_MODEL_DEPLOYMENT_NAME)
+//                                     - Model deployment name (default: gpt-4o)
+//   TOOLBOX_NAME                      - Name of the toolbox to load (default: my-toolset).
+//                                       NOTE: All FOUNDRY_* and AGENT_* env-var prefixes (other
+//                                       than the platform-injected ones above) are reserved by the
+//                                       Foundry container platform and rejected at agent-create.
+//                                       Use TOOLBOX_NAME, not FOUNDRY_TOOLBOX_NAME, for the
+//                                       sample-owned toolbox name so it survives deployment.
 //
 // The Foundry.Hosting package builds the toolbox proxy URL from FOUNDRY_PROJECT_ENDPOINT
 // per tools-integration-spec.md §2–§3.
@@ -43,8 +42,7 @@
         "nor AZURE_AI_PROJECT_ENDPOINT (local-dev convention) is set.");
 string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
     ?? Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
-string toolboxName = Environment.GetEnvironmentVariable("FOUNDRY_TOOLBOX_NAME")
-    ?? Environment.GetEnvironmentVariable("TOOLBOX_NAME") ?? "my-toolset";
+string toolboxName = Environment.GetEnvironmentVariable("TOOLBOX_NAME") ?? "my-toolset";
 
 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
 // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid

dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/README.md

@@ -1,27 +1,111 @@
 # Hosted-Toolbox
 
-A hosted Foundry agent that loads tools from a Foundry Toolbox via the AF Foundry hosting bridge.
+A hosted Foundry agent that loads tools from a single Foundry Toolbox via the AF Foundry hosting bridge.
 
-The agent declares one `FoundryAITool.CreateHostedMcpToolbox(name)` marker; `AddFoundryToolboxes(name)` registers a `FoundryToolboxService` that resolves the marker into the individual MCP tools the toolbox bundles, connecting to the Foundry Toolboxes MCP proxy at startup and discovering tools via `tools/list`.
+`AddFoundryToolboxes(name)` registers a `FoundryToolboxService` that connects to the Foundry Toolboxes MCP proxy at startup, discovers the toolbox's bundled tools via `tools/list`, and makes them available to the agent on every request. The agent code does nothing per request; the toolbox is baked in on the server.
+
+This is the minimal toolbox intro. For a richer walkthrough where a single toolbox bundles three MCP tools each authenticated differently, see [`Hosted-Toolbox-AuthPaths/`](../Hosted-Toolbox-AuthPaths/).
 
 ## Prerequisites
 
-- A Microsoft Foundry project with a Toolbox configured.
-- Azure CLI logged in (`az login`).
-- Set environment variables:
-  - `AZURE_AI_PROJECT_ENDPOINT` (local-dev) or `FOUNDRY_PROJECT_ENDPOINT` (auto-injected in hosted containers)
-  - `AZURE_AI_MODEL_DEPLOYMENT_NAME` (default `gpt-4o`)
-  - `TOOLBOX_NAME` (default `my-toolbox`)
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+- A Foundry project with a deployed model (e.g., `gpt-4o`) and a Toolbox configured
+- Azure CLI logged in (`az login`)
+
+## Configuration
+
+Copy the template and fill in your values:
+
+```powershell
+Copy-Item .env.example .env
+```
+
+Edit `.env`:
+
+```env
+AZURE_AI_PROJECT_ENDPOINT=https://<your-account>.services.ai.azure.com/api/projects/<your-project>
+AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
+TOOLBOX_NAME=my-toolset
+```
+
+Configuration notes:
+
+- `AZURE_AI_PROJECT_ENDPOINT` (local-dev) or `FOUNDRY_PROJECT_ENDPOINT` (auto-injected in hosted containers).
+- `AZURE_AI_MODEL_DEPLOYMENT_NAME` (default `gpt-4o`).
+- `TOOLBOX_NAME` (default `my-toolset`). Use `TOOLBOX_NAME`, not `FOUNDRY_TOOLBOX_NAME`: all `FOUNDRY_*` env-var names are reserved by the Foundry platform and rejected at agent-create, so a `FOUNDRY_*`-named value would not survive deployment.
 
 The `Foundry.Hosting` package builds the toolbox proxy URL from `FOUNDRY_PROJECT_ENDPOINT` as `{FOUNDRY_PROJECT_ENDPOINT}/toolboxes/{TOOLBOX_NAME}/mcp?api-version=v1` per [`tools-integration-spec.md`](https://github.com/microsoft/AgentSchema/blob/main/specs/agents/hosted_agents/container-spec/docs/tools-integration-spec.md) §2–§3.
 
-## Run
+## Running directly (contributors)
 
 ```powershell
+cd dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox
 dotnet run --tl:off
 ```
 
+### Test it
+
+Using the Azure Developer CLI:
+
+```powershell
+azd ai agent invoke --local "What tools do you have available, and what can they do?"
+```
+
+## Running with Docker
+
+### 1. Publish for the container runtime
+
+```powershell
+dotnet publish -c Debug -f net10.0 -r linux-musl-x64 --self-contained false -o out
+```
+
+### 2. Build and run
+
+```powershell
+docker build -f Dockerfile.contributor -t hosted-toolbox .
+
+$env:AZURE_BEARER_TOKEN = (az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
+
+docker run --rm -p 8088:8088 `
+  -e AGENT_NAME=hosted-toolbox-agent `
+  -e AZURE_BEARER_TOKEN=$env:AZURE_BEARER_TOKEN `
+  --env-file .env `
+  hosted-toolbox
+```
+
+## Deploying to Foundry (azd spec)
+
+This sample includes an `azd` manifest (`agent.manifest.yaml`) and hosted agent spec (`agent.yaml`) for deployment to Foundry.
+
+Initialize an `azd` project from this sample's manifest:
+
+```powershell
+mkdir hosted-toolbox; cd hosted-toolbox
+azd ai agent init -m https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-Toolbox/agent.manifest.yaml
+```
+
+Then deploy:
+
+```powershell
+azd deploy
+```
+
+If you need to override defaults, set deployment-time environment variables in the `azd` environment before deploying:
+
+```powershell
+azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME gpt-4o
+azd env set TOOLBOX_NAME my-toolset
+```
+
+For end-to-end hosted agent deployment guidance, see the [official deployment guide](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent).
+
+---
+
+## NuGet package users
+
+Use the standard `Dockerfile` instead of `Dockerfile.contributor`. See the commented section in `HostedToolbox.csproj` for the `PackageReference` alternative.
+
 ## Related samples
 
-- [`Hosted-Toolbox-AuthPaths/`](../Hosted-Toolbox-AuthPaths/) — extends this pattern with a three-tool toolbox demonstrating different MCP-tool authentication paths (key, Entra agent identity, inline `Authorization`), driven by the shared `Using-Samples/SimpleAgent/` REPL.
+- [`Hosted-Toolbox-AuthPaths/`](../Hosted-Toolbox-AuthPaths/) — same hosting bones as this sample, but the toolbox bundles three MCP tools each authenticated differently (key, Entra agent identity, inline `Authorization`), driven by the shared `Using-Samples/SimpleAgent/` REPL.
 - [`Hosted-McpTools/`](../Hosted-McpTools/) — contrasts client-side `McpClient` vs server-side `HostedMcpServerTool` for non-toolbox MCP servers.