Add C# toolbox-auth-paths hosted-agent sample (#402)

* Add C# toolbox auth-paths hosted-agent sample and wire cloud E2E

Add samples/csharp/hosted-agents/agent-framework/toolbox-auth-paths, an
Agent Framework hosted agent that loads a multi-tool Foundry Toolbox
demonstrating the authentication paths a toolbox MCP tool can use to
reach its upstream server: key-based (CustomKeys connection) and public
no-auth. Foundry resolves each tool credential server-side, so the agent
code carries no auth logic.

Wire the sample into hosted-agents-cloud-e2e.yml as a self-provisioning
cell. A guarded self_provision flag (set only for this sample) forces a
single matrix cell instead of the toolbox cartesian product, runs azd
provision so the connection and toolbox are created from the manifest
resources, sources the provisioning PAT from the GH_PAT secret, and
fails fast when no real PAT is configured. Teardown stays gated on
SKIP_PROVISION to match the shared project status quo.

Add the CI invoke payload under internal/tools/samples-hosted-agents and
list the sample in the agent-framework README sample index.

* Drop self-provision CI path and remove no-auth toolbox entry

Revert hosted-agents-cloud-e2e.yml to origin/main: the self_provision
flag was a net-new strategy with no precedent in CI. Toolbox samples run
with SKIP_PROVISION=true and consume a toolbox pre-registered in the
TOOLBOX_ENDPOINT repo variable (like langgraph-toolbox), so no PAT is
provisioned in CI.

Remove the public no-auth path from toolbox-auth-paths: an auth sample
should only demonstrate authenticated paths. Toolbox now exposes only the
key-based CustomKeys GitHub tool; Entra agent identity stays documented.

Rework the sample README to be developer-runnable (azd provision or manual
toolbox creation in your own project) and document the out-of-band CI
registration without naming individuals. Interacting section now uses
azd ai agent invoke --local. Trim payloads to the github prompts.

* Remove redundant test-payload.txt from toolbox-auth-paths sample

CI reads invoke prompts from internal/tools/samples-hosted-agents, and
the build context strips test-payload.txt, so the sample-dir copy is
unused. Drop it and fix the dangling README link.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Rename github_pat secret parameter to gh_pat in toolbox-auth-paths

GitHub forbids creating secrets/variables whose names start with the
GITHUB_ prefix (case-insensitive), and azd resolves a manifest secret
parameter from an env var of the same name. The github_pat parameter
therefore could not be wired in the e2e Foundry project.

Rename the parameter (and its {{ }} placeholder) to gh_pat, matching the
existing GH_PAT secret already used by the cloud-e2e workflow. The
scaffold step now exports both github_pat (other toolbox samples) and
gh_pat. Docs updated; token-format mentions (github_pat_...) left intact.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix gh_pat secret resolution in cloud-e2e scaffold (uppercase env var)

azd ai agent init --no-prompt resolves a manifest secret parameter from an
env var named after the parameter UPPERCASED (gh_pat -> GH_PAT). The scaffold
step set a lowercase gh_pat env var, so azd could not find it and failed with
'unable to prompt for secret parameter gh_pat in no-prompt mode'.

Set GH_PAT (uppercase) instead and correct the explanatory comment. The
manifest parameter stays lowercase gh_pat; azd uppercases it to find GH_PAT.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Use map form for gh_pat secret parameter so azd resolves it

azd ai agent init --no-prompt only binds a manifest secret parameter to an
env var when parameters use the map form (parameters: <name>:). The
toolbox-auth-paths manifest used the array form (parameters: properties:
- name:), where 'secret' is not a schema field, so azd recognized the
parameter name but never looked up its env var — failing with 'unable to
prompt for secret parameter gh_pat in no-prompt mode' regardless of the env
var set.

Switch to the map form (matching the browser-automation/langgraph-toolbox
samples). Also export a lowercase gh_pat env var alongside GH_PAT so azd
resolves the value whether it uppercases the parameter name or not.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Drop lowercase gh_pat env var (case-collides with GH_PAT)

GitHub rejects a workflow whose env block defines names differing only by
case (GH_PAT vs gh_pat) -> 'workflow file issue', no jobs run. Keep only the
uppercase GH_PAT, which is what azd resolves the gh_pat secret parameter from
(azd uppercases the parameter name).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Exclude toolbox-auth-paths x code-interpreter combo (known SDK bug)

The csharp code-interpreter combo triggers an 'invalid_payload' on
/tools/0/container (container serialized as null) — a known .NET Agent
Framework SDK bug in Microsoft.Agents.AI.Foundry.Hosting that cannot be
fixed from this repo. The matrix already excludes this combo for the
sibling foundry-toolbox-server-side sample; add the new toolbox-auth-paths
sample to the same exclusion so the matrix doesn't gate on the known defect.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Rework toolbox-auth-paths to AddFoundryToolboxes (latest Hosting SDK)

The sample pinned Microsoft.Agents.AI.Foundry.Hosting 1.3.0-preview and used
GetToolboxToolsAsync() to pass the toolbox's tools to the agent as server-side
MCP tools. Those tools default to AlwaysRequire approval, so the model's tool
call returned an unhandled approval request and the hosted handler dropped it —
the agent responded with an empty output (silent), even though CI marked it
'completed'.

Bump to the latest 1.9.0-preview and adopt the AddFoundryToolboxes pattern
(matching the AF repo Hosted-Toolbox sample). The hosting layer now connects to
the toolbox MCP proxy at startup and exposes its tools as host-executed
functions — no server-side approval gate — so the agent actually calls the tool
and returns a real answer.

Verified locally against a Foundry project: POST /responses now returns
function_call + function_call_output + a text message (was output: []).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Derive toolset endpoint from project endpoint when not injected

The previous run revealed the CI hosted container does NOT inject
FOUNDRY_AGENT_TOOLSET_ENDPOINT, so AddFoundryToolboxes disabled toolbox
support and the agent answered from the model alone (a hallucinated, toolless
response that still passed CI). Derive FOUNDRY_AGENT_TOOLSET_ENDPOINT from
FOUNDRY_PROJECT_ENDPOINT (<project>/toolboxes) when the platform doesn't set
it, so the toolbox actually loads.

Verified locally: with only FOUNDRY_PROJECT_ENDPOINT set, the host derives the
toolset endpoint, discovers the toolbox tools, and POST /responses returns
function_call + function_call_output + a text message.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Work around toolbox token audience mismatch (cognitiveservices vs ai.azure.com)

CI showed the toolbox failing to connect with 401 'audience is incorrect
(https://ai.azure.com)'. The Hosting SDK's toolbox token handler requests a
https://cognitiveservices.azure.com token, but the Foundry toolbox MCP proxy
(both the test project and the CI project) requires https://ai.azure.com — so
the toolbox silently failed to load and the agent answered from the model alone.

Register a TokenCredential for the toolbox connection that maps the
cognitiveservices.azure.com audience to ai.azure.com. Verified locally against a
Foundry project: the toolbox now discovers its tools and POST /responses returns
function_call + function_call_output + a text message grounded in the tool.

This is a workaround for an SDK audience bug; the proper fix belongs in
Microsoft.Agents.AI.Foundry.Hosting.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Bump MAF Hosting to 1.10.0 and drop toolbox audience workaround

Microsoft.Agents.AI.Foundry.Hosting 1.10.0-preview.260610.1 requests the
correct https://ai.azure.com token audience for the Foundry toolbox MCP
proxy, so the FoundryToolsetCredential audience-rewrite workaround is no
longer needed. Removed the credential, its DI registration, and the now
unused Azure.Core using.

Verified locally against tao-foundry-prj: the toolbox discovers 51 tools
and the agent answers a GitHub search prompt end-to-end (function_call +
function_call_output + message), with no workaround.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 2 people

samples/csharp/hosted-agents/agent-framework/README.md

@@ -15,8 +15,15 @@ This directory contains samples that demonstrate how to use the [Agent Framework
 | 5 | [text-search-rag](text-search-rag/) | A support agent with RAG capabilities using `TextSearchProvider`. |
 | 6 | [workflows](workflows/) | A multi-agent translation pipeline using `WorkflowBuilder`. |
 | 7 | [foundry-toolbox-server-side](foundry-toolbox-server-side/) | An agent that loads a Foundry Toolbox with `GetToolboxToolsAsync()` and passes its tools as server-side tools — Foundry executes them on the agent's behalf. |
-| 8 | [a2a/01-delegation](a2a/01-delegation/) | Two hosted agents — a math-expert executor exposed over A2A and a concierge caller that delegates to it through a Foundry Toolbox A2A connection. |
-| 9 | [foundry-toolbox-mcp-skills](foundry-toolbox-mcp-skills/) | An agent that discovers MCP-based skills from a Foundry Toolbox and exposes them to the agent via `AgentSkillsProvider` with progressive disclosure. |
+| 8 | [toolbox-auth-paths](toolbox-auth-paths/) | A multi-tool Foundry Toolbox demonstrating the authentication paths an MCP tool can use (key-based `CustomKeys`, public no-auth, and optional Entra agent identity) — all resolved server-side. |
+| 9 | [azure-search-rag](azure-search-rag/) | A support agent with RAG grounded in an Azure AI Search keyword index via `TextSearchProvider` over `Azure.Search.Documents`. |
+| 10 | [foundry-memory-rag](foundry-memory-rag/) | A personal-coach agent with persistent per-user memory that survives across requests and sessions using `FoundryMemoryProvider`. |
+| 11 | [file-tools](file-tools/) | An agent that answers questions over both image-baked bundled files and per-session uploaded files through scoped, security-hardened tools. |
+| 12 | [agent-skills](agent-skills/) | An agent that loads its behavioral guidelines from Foundry Skills (`SKILL.md`) at startup, so updates ship without code changes. |
+| 13 | [observability](observability/) | An instrumented agent demonstrating OpenTelemetry tracing, metrics, and logging for a hosted agent. |
+| 14 | [teams-activity](teams-activity/) | A hosted agent that can be deployed to Foundry and published to Teams, handling messages with file attachments and Teams/calendar questions. |
+| 15 | [a2a/01-delegation](a2a/01-delegation/) | Two hosted agents — a math-expert executor exposed over A2A and a concierge caller that delegates to it through a Foundry Toolbox A2A connection. |
+| 16 | [foundry-toolbox-mcp-skills](foundry-toolbox-mcp-skills/) | An agent that discovers MCP-based skills from a Foundry Toolbox and exposes them to the agent via `AgentSkillsProvider` with progressive disclosure. |
 
 ### Invocations API
 

samples/csharp/hosted-agents/agent-framework/toolbox-auth-paths/.dockerignore

@@ -0,0 +1,9 @@
+**/bin
+**/obj
+**/.vs
+**/.vscode
+**/.idea
+**/*.user
+**/.env
+**/.env.*
+!**/.env.example

samples/csharp/hosted-agents/agent-framework/toolbox-auth-paths/.env.example

@@ -0,0 +1,19 @@
+# Foundry project endpoint — auto-injected in hosted containers.
+# Only set manually if running without `azd ai agent run`.
+# FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
+
+# Model deployment name — must match a deployment in your Foundry project.
+AZURE_AI_MODEL_DEPLOYMENT_NAME=
+
+# Toolbox name — must match a toolbox in your Foundry project.
+# When deploying with `azd provision`, the toolbox is created automatically
+# from the resources declared in agent.manifest.yaml.
+TOOLBOX_NAME=auth-paths-tools
+
+# Note: the GitHub PAT for the key-based auth path is NOT a container env var.
+# It is declared as the `gh_pat` secret parameter in agent.manifest.yaml and
+# prompted by `azd ai agent init`; azd stores it in the Foundry connection only.
+
+# Application Insights — auto-injected in hosted containers.
+# Set for local telemetry (optional but recommended).
+# APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=...

samples/csharp/hosted-agents/agent-framework/toolbox-auth-paths/Dockerfile

@@ -0,0 +1,12 @@
+FROM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build
+WORKDIR /src
+COPY . .
+RUN dotnet restore
+RUN dotnet build -c Release --no-restore
+RUN dotnet publish -c Release --no-build -o /app
+
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
+WORKDIR /app
+COPY --from=build /app .
+EXPOSE 8088
+ENTRYPOINT ["dotnet", "toolbox-auth-paths.dll"]

samples/csharp/hosted-agents/agent-framework/toolbox-auth-paths/Program.cs

@@ -0,0 +1,88 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+/*
+ * Foundry Toolbox — Auth Paths — Agent Framework Responses agent for C#
+ *
+ * Hosted agent that loads a Foundry Toolbox via AddFoundryToolboxes. The hosting
+ * layer connects to the Foundry Toolboxes MCP proxy at startup, discovers the
+ * toolbox's tools, and makes them available to the agent. The toolbox's MCP tools
+ * authenticate to their upstream servers using different paths:
+ *
+ *   1. Key-based — a CustomKeys project connection injects a Bearer token (GitHub MCP).
+ *
+ * (Path 2 — Microsoft Entra agent identity — is documented in README.md as an optional
+ * additive toolbox entry, because it requires a post-deploy RBAC grant on the agent's
+ * managed identity before the toolbox can enumerate it.)
+ *
+ * The agent process carries NO auth logic. Foundry's toolbox proxy resolves each tool's
+ * credential when it proxies the MCP call, so this code is identical regardless of which
+ * auth path a given tool uses — the difference lives entirely in agent.manifest.yaml.
+ *
+ * Required environment variables:
+ *   FOUNDRY_PROJECT_ENDPOINT        — Foundry project endpoint (auto-injected in hosted containers)
+ *   AZURE_AI_MODEL_DEPLOYMENT_NAME  — Model deployment name (declared in agent.manifest.yaml)
+ *   TOOLBOX_NAME                    — Name of the Foundry Toolbox to load
+ *   FOUNDRY_AGENT_TOOLSET_ENDPOINT  — Toolbox MCP proxy base URL (auto-injected in hosted containers;
+ *                                     set locally to "<project-endpoint>/toolboxes")
+ */
+
+#pragma warning disable OPENAI001 // Foundry hosting APIs are experimental
+
+using Azure.AI.AgentServer.Core;
+using Azure.AI.Projects;
+using Azure.Identity;
+using DotNetEnv;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.Extensions.DependencyInjection;
+
+// Load .env file if present (for local development)
+Env.TraversePath().Load();
+
+var projectEndpoint = new Uri(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT environment variable is not set."));
+
+var deployment = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME")
+    ?? throw new InvalidOperationException("AZURE_AI_MODEL_DEPLOYMENT_NAME environment variable is not set.");
+
+var toolboxName = Environment.GetEnvironmentVariable("TOOLBOX_NAME")
+    ?? throw new InvalidOperationException("TOOLBOX_NAME environment variable is not set.");
+
+// The agent is backed by the project's Responses API. It carries no tools directly —
+// the toolbox's tools are registered below via AddFoundryToolboxes and injected by the
+// hosting layer at request time as host-executed MCP tools.
+var projectClient = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
+
+// Hosted containers inject FOUNDRY_AGENT_TOOLSET_ENDPOINT (the toolbox MCP proxy base).
+// When it is absent (local dev, or environments that don't inject it), derive it from the
+// project endpoint so AddFoundryToolboxes can still reach the toolbox proxy.
+if (string.IsNullOrEmpty(Environment.GetEnvironmentVariable("FOUNDRY_AGENT_TOOLSET_ENDPOINT")))
+{
+    Environment.SetEnvironmentVariable(
+        "FOUNDRY_AGENT_TOOLSET_ENDPOINT",
+        $"{projectEndpoint.ToString().TrimEnd('/')}/toolboxes");
+}
+
+AIAgent agent = projectClient
+    .AsAIAgent(
+        model: deployment,
+        instructions: "You are a developer assistant with access to Foundry toolbox tools that reach "
+                    + "external services over authenticated paths. Use the GitHub tools to "
+                    + "search issues and pull requests. Be concise and cite the tool you used.",
+        name: "toolbox-auth-paths",
+        description: "Agent with an authenticated Foundry Toolbox using server-side tools.");
+
+var builder = AgentHost.CreateBuilder(args);
+
+builder.Services.AddFoundryResponses(agent);
+
+// Register the Foundry Toolbox. The hosting layer connects to the toolbox MCP proxy at
+// startup (FOUNDRY_AGENT_TOOLSET_ENDPOINT, auto-injected by the platform), discovers the
+// toolbox's tools, and injects them into the agent. The platform proxy resolves each
+// tool's connection credential, so the agent runs under its own identity.
+builder.Services.AddFoundryToolboxes(options => options.ApiVersion = "v1", toolboxName);
+
+builder.RegisterProtocol("responses", endpoints => endpoints.MapFoundryResponses());
+
+var app = builder.Build();
+app.Run();

samples/csharp/hosted-agents/agent-framework/toolbox-auth-paths/README.md

@@ -0,0 +1,114 @@
+# Foundry Toolbox — Auth Paths
+
+A Foundry Toolbox that demonstrates the **authentication paths** a toolbox MCP tool can use to reach its upstream server. Like [`foundry-toolbox-server-side`](../foundry-toolbox-server-side/), the agent loads the toolbox with `GetToolboxToolsAsync()` and passes the tools to `AsAIAgent(..., tools: ...)` as **server-side tools** — Foundry executes them on the agent's behalf.
+
+The key idea: **the agent code carries no auth logic**. Foundry resolves each tool's credential server-side when it proxies the MCP call, so `Program.cs` is identical regardless of which path a tool uses. The difference lives entirely in [`agent.manifest.yaml`](agent.manifest.yaml).
+
+## Auth path matrix
+
+| # | Path | `authType` | Where the secret lives | Wired by default? |
+|---|------|-----------|------------------------|-------------------|
+| 1 | Key-based | `CustomKeys` | `gh_pat` secret parameter → Foundry connection secret store, injected as `Authorization: Bearer …` | ✅ Yes (GitHub MCP) |
+| 2 | Microsoft Entra agent identity | `AgenticIdentity` | No secret — the agent's managed identity gets an Entra token for the target `audience` | ➕ Optional (see below) |
+
+> A third variant — embedding an `Authorization` header **inline** in the manifest — is an anti-pattern: the token is committed in plain text. Always prefer a `CustomKeys` connection (path 1) so the secret stays in the Foundry connection store.
+
+## How auth is exercised
+
+There is nothing auth-specific to run. Each prompt drives a GitHub tool, which drives the key-based path end to end:
+
+- A GitHub answer means the **CustomKeys** PAT (path 1) resolved correctly.
+
+A `401`/`403` from a tool means that path's credential did not resolve. Send any prompt that triggers a GitHub tool (e.g. *"What tools do you have available?"*) to exercise the path.
+
+## All-or-nothing enumeration
+
+`GetToolboxToolsAsync()` fetches **all** tool definitions at startup. If any configured source is misconfigured (bad PAT, missing RBAC, unreachable server), the fetch fails and the host does not start. When adding a new auth path, **validate one source at a time** — comment out the others in the manifest until each one enumerates cleanly.
+
+## Adding auth path 2 — Microsoft Entra agent identity
+
+Path 2 is documented rather than wired by default because it needs a post-deploy RBAC grant before the toolbox can enumerate it. To add it:
+
+1. Add a parameter and an `AgenticIdentity` connection, and reference it from a third toolbox tool, in [`agent.manifest.yaml`](agent.manifest.yaml):
+
+   ```yaml
+   parameters:
+     properties:
+       - name: entra_audience
+         secret: false
+         description: Entra ID token audience for the target MCP server (e.g. https://cognitiveservices.azure.com).
+       - name: entra_mcp_target
+         secret: false
+         description: URL of the Entra-protected MCP server that accepts agent-identity tokens.
+   resources:
+     - kind: connection
+       name: entra-agent-conn
+       category: RemoteTool
+       authType: AgenticIdentity
+       audience: "{{ entra_audience }}"
+       target: "{{ entra_mcp_target }}"
+     - kind: toolbox
+       name: auth-paths-tools
+       tools:
+         # … existing github entry …
+         - type: mcp
+           server_label: entra
+           project_connection_id: entra-agent-conn
+   ```
+
+2. **Grant RBAC on the target before the first invoke.** After deploy, the agent gets a managed identity (its principal id changes each time the agent is recreated). Assign that identity the role the target MCP server requires (for an Azure Cognitive Services target: **Cognitive Services User** at the resource scope). Until this lands, the path-2 source fails to enumerate and bricks the whole toolbox.
+
+## Provisioning the toolbox in your environment
+
+The agent reads its toolbox from your Foundry project at startup, so the `auth-paths-tools` toolbox (and the `github-mcp-conn` connection that backs the key-based path) must exist in the project before you run. You have two ways to create them.
+
+### Option 1 — `azd provision` (recommended)
+
+`azd provision` reads [`agent.manifest.yaml`](agent.manifest.yaml) and creates the connection and toolbox for you:
+
+```bash
+azd ai agent init          # prompts once for the gh_pat secret parameter
+azd provision              # creates github-mcp-conn (CustomKeys) + auth-paths-tools toolbox
+```
+
+The `gh_pat` value is stored only in the Foundry connection secret store. It is never written to disk or passed to the container as an env var. Use a GitHub PAT (classic `ghp_...` or fine-grained `github_pat_...`) scoped to read the repositories your prompts ask about. Public-repo read is enough for the sample prompts.
+
+### Option 2 — create the toolbox yourself
+
+Create the same two resources in the [Foundry portal](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/toolbox) or in code with the [Foundry Toolbox CRUD sample](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/samples/hosted_agents/sample_toolboxes_crud.py):
+
+1. A `CustomKeys` connection named `github-mcp-conn`, target `https://api.githubcopilot.com/mcp`, key `Authorization` = `Bearer <your-pat>`.
+2. A toolbox named `auth-paths-tools` with one MCP tool: `github` (referencing `github-mcp-conn`).
+
+Once the toolbox exists, set `TOOLBOX_NAME=auth-paths-tools` (already the manifest default) and run the agent.
+
+## Continuous integration
+
+The `hosted-agents-cloud-e2e` workflow treats this as a **toolbox sample** (its directory name contains `toolbox`) and runs with `SKIP_PROVISION=true`, so it does **not** run `azd provision` and never receives a PAT. Instead it consumes a toolbox that already exists in a shared Foundry project, the same way [`langgraph-toolbox`](../../../python/hosted-agents/bring-your-own/responses/langgraph-toolbox/) does. To enable it there, register an `auth-paths-tools` toolbox in that project (Option 2 above) and add one `label=url|query` line to the `TOOLBOX_ENDPOINT` repository variable:
+
+```
+auth-paths=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/auth-paths-tools/mcp?api-version=v1|<query that exercises the github tool>
+```
+
+The workflow derives `TOOLBOX_NAME` from the URL slug (`.../toolboxes/auth-paths-tools/mcp`) and drives the toolbox with that query. Until the toolbox is registered, add a `.ci-skip` file in this directory to keep the sample out of the gated set.
+
+## Running the Agent Host
+
+Follow the instructions in the [Running the Agent Host Locally](../README.md#running-the-agent-host-locally) section of the parent README to run the agent host.
+
+## Interacting with the agent
+
+With the agent host running locally on `http://localhost:8088/`, use `azd ai agent invoke --local` to send a prompt:
+
+```bash
+azd ai agent invoke --local "What tools do you have available?"
+azd ai agent invoke --local "Search the microsoft/agent-framework repo for open issues that mention hosted agents."
+```
+
+A GitHub answer means the key-based **CustomKeys** path (path 1) resolved its PAT correctly. A `401`/`403` means the connection credential did not resolve.
+
+> You can also invoke with `curl` (`Invoke-WebRequest` in PowerShell) against `http://localhost:8088/responses`, or use the **Agent Inspector** in the Foundry Toolkit VS Code extension. See the [parent README](../README.md) for details.
+
+## Deploying the Agent to Foundry
+
+To deploy the agent to Foundry, follow the instructions in the [Deploying the Agent to Foundry](../README.md#deploying-the-agent-to-foundry) section of the parent README.

samples/csharp/hosted-agents/agent-framework/toolbox-auth-paths/agent.manifest.yaml

@@ -0,0 +1,60 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/AgentManifest.yaml
+name: toolbox-auth-paths-dotnet-agent-framework
+displayName: "Foundry Toolbox — Auth Paths (.NET, Agent Framework)"
+description: >
+  Agent Framework agent that loads a Foundry Toolbox demonstrating the
+  authentication paths a toolbox MCP tool can use to reach its upstream server:
+  key-based (CustomKeys connection) by default, with Microsoft Entra agent
+  identity documented in the README as an optional additive toolbox entry. The
+  Foundry platform resolves each tool's credential server-side when it proxies
+  the MCP call, so the agent code carries no auth logic.
+metadata:
+  tags:
+    - AI Agent Hosting
+    - Responses Protocol
+    - Agent Framework
+    - Toolbox
+    - MCP
+    - Authentication
+    - .NET
+template:
+  name: toolbox-auth-paths-dotnet-agent-framework
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  environment_variables:
+    # FOUNDRY_PROJECT_ENDPOINT and APPLICATIONINSIGHTS_CONNECTION_STRING
+    # are injected by the platform (hosted) and translated by azd (local)
+    # — do NOT declare them here.
+    - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
+      value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
+    - name: TOOLBOX_NAME
+      value: "auth-paths-tools"
+parameters:
+  gh_pat:
+    secret: true
+    description: GitHub Personal Access Token for the key-based (CustomKeys) auth path (classic ghp_... or fine-grained github_pat_...).
+resources:
+  - kind: model
+    id: gpt-4.1
+    name: AZURE_AI_MODEL_DEPLOYMENT_NAME
+  # Auth path 1 — key-based (CustomKeys). Foundry injects the PAT as a Bearer token when it
+  # proxies the GitHub MCP call. The token lives only in this connection's secret store and
+  # is never exposed to the agent container.
+  - kind: connection
+    name: github-mcp-conn
+    category: RemoteTool
+    authType: CustomKeys
+    target: https://api.githubcopilot.com/mcp
+    credentials:
+      type: CustomKeys
+      keys:
+        Authorization: "Bearer {{ gh_pat }}"
+  - kind: toolbox
+    name: auth-paths-tools
+    tools:
+      # Auth path 1 — key-based via the CustomKeys connection above.
+      - type: mcp
+        server_label: github
+        project_connection_id: github-mcp-conn

samples/csharp/hosted-agents/agent-framework/toolbox-auth-paths/agent.yaml

@@ -0,0 +1,14 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
+kind: hosted
+name: toolbox-auth-paths-dotnet-agent-framework
+protocols:
+  - protocol: responses
+    version: 1.0.0
+resources:
+  cpu: "0.25"
+  memory: 0.5Gi
+environment_variables:
+  - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
+    value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
+  - name: TOOLBOX_NAME
+    value: ${TOOLBOX_NAME}

samples/csharp/hosted-agents/agent-framework/toolbox-auth-paths/toolbox-auth-paths.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <RootNamespace>ToolboxAuthPaths</RootNamespace>
+    <AssemblyName>toolbox-auth-paths</AssemblyName>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <NoWarn>$(NoWarn);NU1903;NU1605</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <!-- Agent Framework hosting — provides AgentHost, AddFoundryResponses, MapFoundryResponses,
+         and AddFoundryToolboxes for registering Foundry Toolboxes as host-side MCP tools. -->
+    <PackageReference Include="Microsoft.Agents.AI.Foundry.Hosting" Version="1.10.0-preview.260610.1" />
+    <!-- .env file support for local development. -->
+    <PackageReference Include="DotNetEnv" Version="3.1.1" />
+  </ItemGroup>
+
+</Project>