Automated sync from private repo (2026-07-10)

samples/csharp/hosted-agents/AGENTS.md

@@ -0,0 +1,51 @@
+# Coding Agent Instructions — C# hosted-agent samples
+
+Conventions for AI agents creating or editing samples under
+`samples/csharp/hosted-agents/`. Agents read the nearest `AGENTS.md` up the
+tree, so this applies to C# hosted-agent samples. Treat these as shared
+conventions and a starting point — adapt to what each sample actually needs.
+
+## README conventions
+
+Most samples follow the shared template,
+[`README-template.md`](./README-template.md): a good default is to copy it and
+fill in the `{{placeholders}}`. It keeps a familiar section flow:
+
+1. What this sample demonstrates
+2. How it works — plus any sample-specific background (e.g. "Environment
+   variables", "Architecture", "Features")
+3. Prerequisites — what the *sample* needs: a Foundry project + model deployment,
+   the **.NET 10 SDK**, and (only if applicable) RBAC roles, extra Azure
+   resources, and environment variables / secrets
+4. Option 1: Azure Developer CLI (`azd`) — init → provision → run → invoke →
+   deploy → invoke-deployed
+5. Option 2: VS Code (Foundry Toolkit) — the one-click **F5** run-and-debug flow
+   (Agent Inspector opens automatically) and/or a manual run (`dotnet restore` →
+   configure env → `az login` → `dotnet run`) → open the Agent Inspector → deploy
+6. Any sample-specific deep-dive sections (customization, advanced demos, reference)
+7. Troubleshooting
+8. Next steps
+
+## Conventions worth keeping
+
+- Prefer the current CLI commands (the template reflects these; avoid older
+  forms such as `azd ext install azure.ai.agents`).
+- Prefer self-contained READMEs over deferring run/deploy steps to a parent
+  README or hiding steps inside collapsible `<details>` blocks.
+
+## When a sample legitimately differs
+
+Not every sample fits the two-option shape, and that's fine — adapt rather than
+force it:
+
+- **Command-line-only samples** (e.g. VoiceLive, WebSocket, some A2A samples) may
+  have no VS Code / Agent Inspector path. Document the flow they actually support
+  (curl / `azd` / a browser client) and omit Option 2 when it doesn't apply.
+- **Deploy-first samples** (e.g. A2A) may lead with deployment instead of a local
+  run. Keep the section order sensible for the scenario.
+
+Use the template for structure and shared vocabulary, and keep whatever
+sample-specific sections a reader needs.
+
+> The per-sample `AGENTS.md` (hosted-agent overview, `azd` lifecycle, Microsoft
+> Foundry Skill) still applies; this file only adds README conventions.

samples/csharp/hosted-agents/README-template.md

@@ -0,0 +1,151 @@
+<!--
+README template for a .NET (C#) hosted-agent sample.
+
+How to use:
+  1. Copy this file into your sample folder as README.md.
+  2. Replace every {{placeholder}}.
+  3. Delete any section that does not apply, but keep the section order.
+  4. Delete this comment block.
+-->
+
+# What this sample demonstrates
+
+{{One or two sentences: what the agent does and which framework it uses.}}
+
+## How it works
+
+{{Short description of how the agent is wired.}} See `Program.cs` for the implementation.
+
+<!--
+Sample-specific *background* subsections (e.g. "Environment variables", "Architecture",
+"Features") belong here, right after "How it works" and before "Prerequisites" — they give
+context a reader needs before running. Keep run/deploy steps out of them; those live in the
+Options below. Deep-dive/customization/reference sections go *after* the two options.
+-->
+
+## Prerequisites
+
+What the **sample itself** needs, independent of how you run it. The tooling for each run
+path (`azd` or the VS Code Foundry Toolkit) is listed under its option below.
+
+1. An existing Foundry project with a deployed model (or create them during setup in Option 1).
+2. **[.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)** or later.
+3. **Roles (RBAC):** {{Azure roles the identity running the sample needs on the Foundry project or other resources, e.g. `Azure AI User`. Delete if project access is sufficient.}}
+4. **Additional Azure resources:** {{Extra resources the sample depends on — a toolbox, connection, storage account, etc. If declared in the sample's `azure.yaml`, `azd provision` (Option 1) creates them; otherwise create them before running (Foundry portal, SDK, or `azd ai`). Delete if none.}}
+5. **Environment variables / secrets:** {{Required env vars or secrets, e.g. `GITHUB_PAT`, and how to obtain them. Delete if none.}}
+
+## Option 1: Azure Developer CLI (`azd`)
+
+### Prerequisites
+
+1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd)
+2. Install the Foundry extension:
+
+   ```bash
+   azd ext install microsoft.foundry
+   ```
+
+3. Authenticate:
+
+   ```bash
+   azd auth login
+   ```
+
+### Initialize the agent project
+
+No cloning required. Create a new folder and initialize from the manifest:
+
+```bash
+mkdir my-agent && cd my-agent
+azd ai agent init -m {{URL to your sample's azure.yaml on GitHub}}
+```
+
+Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one.
+
+### Provision Azure resources (if needed)
+
+If you don't already have a Foundry project and model deployment:
+
+```bash
+azd provision
+```
+
+### Run the agent locally
+
+```bash
+azd ai agent run
+```
+
+The agent host will start on `http://localhost:8088`.
+
+### Invoke the local agent
+
+In a separate terminal, from the project directory:
+
+```bash
+azd ai agent invoke --local "{{prompt}}"
+```
+
+### Deploy to Foundry
+
+Once tested locally, deploy to Microsoft Foundry:
+
+```bash
+azd deploy
+```
+
+For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent).
+
+### Invoke the deployed agent
+
+```bash
+azd ai agent invoke "{{prompt}}"
+```
+
+## Option 2: VS Code (Foundry Toolkit)
+
+### Prerequisites
+
+1. **VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed.
+2. [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension.
+3. Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain is ready.
+
+### Run and debug the agent
+
+Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector.
+
+### Or run manually, then open the Inspector
+
+1. Set the required environment variables and sign in to Azure with the Azure CLI (`az login`).
+2. Start the agent: `dotnet run` (listens on `http://localhost:8088`).
+3. Command Palette (`Ctrl+Shift+P`) → **Foundry Toolkit: Open Agent Inspector**, then send a message to test.
+
+### Deploy to Foundry
+
+1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings.
+2. If prompted, complete **Foundry Project Setup** to select subscription and project.
+3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name.
+4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**.
+5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab.
+
+<!--
+Sample-specific deep-dive sections go here, AFTER the two options, so the run/deploy
+lifecycle stays consistent across samples. Give each its own `##` heading. Common kinds:
+  - Customization  — swapping a dependency/endpoint (e.g. "Targeting a different MCP server",
+                     "Using your own Foundry model", "Adding skills").
+  - Advanced demos — behavior worth showing after deploy (e.g. "Uploading files to a hosted
+                     session", "Testing session multiplexing after deployment").
+  - Reference      — protocol/wire format, event shapes, or project structure.
+Delete this comment and add the real sections your sample needs.
+-->
+
+## Troubleshooting
+
+> Delete if not needed. List errors specific to this sample and their fixes.
+
+{{Symptom → cause → fix.}}
+
+## Next steps
+
+- [Quickstart: Create a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent)
+- {{Links to related samples.}}

samples/csharp/hosted-agents/README.md

@@ -252,7 +252,7 @@ Or, if you've already cloned this repository:
 ## Repo structure
 
 ```
-samples/dotnet/hosted-agents/
+samples/csharp/hosted-agents/
 ├── agent-framework/
 │   ├── hello-world/                   ← Start here (Agent Framework)
 │   ├── simple-agent/

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

@@ -141,22 +141,22 @@ Or in PowerShell:
 <details>
 <summary><h3>Using the Foundry Toolkit VS Code Extension</h3></summary>
 
-The [Foundry Toolkit VS Code extension](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?view=foundry&pivots=vscode) has a built-in sample gallery. You can open this sample directly from the extension without cloning the repository, it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience.
-
-The extension also adds an **Agent Inspector** UI for chatting with a hosted agent that is already running locally, plus a guided **Deploy Hosted Agent** command (see [Deploying the Agent to Foundry](#deploying-the-agent-to-foundry) below).
+The [Foundry Toolkit VS Code extension](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio) has a built-in sample gallery. You can open a sample directly from the extension without cloning the repository — it scaffolds the project into a new workspace, generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically, and configures a one-click **F5** debug experience. It also adds an **Agent Inspector** UI for chatting with a running agent and a guided **Deploy Hosted Agent** command (see [Deploying the Agent to Foundry](#deploying-the-agent-to-foundry) below).
 
 #### Prerequisites
 
-1. **Foundry Toolkit VS Code Extension** — [install from the VS Code marketplace](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent?pivots=vscode) and sign in to Azure.
-2. The agent is already running locally — start it with [`azd ai agent run`](#using-azd) or [`dotnet run`](#using-dotnet-run) first.
+1. **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio)** extension installed and signed in to Azure.
+2. **[C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit)** extension. Run Command Palette (`Ctrl+Shift+P`) → **C#: Check Workspace Requirements** to confirm the toolchain.
+
+#### Run and debug the agent
 
-#### Open the Agent Inspector
+Press **F5** to start the agent. The agent starts and the **Agent Inspector** opens automatically. Chat with the agent in the Inspector.
 
-With the agent running on `http://localhost:8088/`:
+#### Or run manually, then open the Inspector
 
-1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**.
-2. The Inspector auto-connects to the running agent.
-3. Send messages from the Inspector to chat with the agent and watch the streamed responses.
+1. Start the agent with [`azd ai agent run`](#using-azd) or [`dotnet run`](#using-dotnet-run) — it listens on `http://localhost:8088/`.
+2. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**.
+3. The Inspector auto-connects to the running agent. Send messages to chat and watch the streamed responses.
 
 </details>