microsoft · andrewmatkin · Jun 5, 2026 · Jun 5, 2026 · Jun 9, 2026 · Jun 10, 2026
diff --git a/.gitignore b/.gitignore
@@ -61,6 +61,7 @@ BenchmarkDotNet.Artifacts/
 project.lock.json
 project.fragment.lock.json
 artifacts/
+.worktrees/
 
 # ASP.NET Scaffolding
 ScaffoldingReadMe.txt
@@ -397,4 +398,3 @@ static/
 devTools/
 node_modules/
 *.tsbuildinfo
-
diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@ Use the Agents SDK to:
 
 ## Get Started
 
-You can get started right here by scolling up and clicking the 'samples' folder in this repo, selecting your language and reviewing the samples list before picking which one you want to start with (QuickStart is recommended for fundamentals).
+You can get started right here by opening the [samples catalog](samples/README.md), selecting your language, and reviewing each sample's maturity tier before picking where to start. The QuickStart samples are recommended for fundamentals.
 
 Microsoft 365 Copilot is one of many channels supported by this SDK, and a *Microsoft 365 Copilot subscription is *not* required* to get started with or use this SDK unless your working specifically with that channel (or others, that require a subscription/service to use their client).
 

diff --git a/samples/README.md b/samples/README.md
@@ -1,9 +1,62 @@
-# Microsoft 365 Agents SDK Samples list
+# Microsoft 365 Agents SDK Samples
 
-This table contains links to the samples available for each language.
+This catalog helps you choose a sample by language, scenario, and expected maturity. Most samples in this repository are starter samples: they are intentionally small, focused examples for learning one SDK concept or integration path. They are not production reference implementations unless explicitly labeled that way.
 
-|Language | README |
-|---------|-------------|
-|.Net|[dotnet](dotnet/README.md)|
-|JavaScript|[nodejs](nodejs/README.md)|
-|Python|[python](python/README.md)|
+## Sample maturity tiers
+
+| Tier | Use when you want to | What to expect |
+|------|----------------------|----------------|
+| **Tier 1: QuickStart** | Learn the SDK messaging loop and get a minimal agent running quickly. | Minimal code, local setup instructions, and explicit development-time shortcuts. |
+| **Tier 2: Scenario starter** | Start from a realistic feature or integration scenario. | A focused sample for auth, telemetry, cards, streaming, Copilot Studio, tool orchestration, or another SDK capability. |
+| **Tier 3: Production reference** | Understand a deployable architecture pattern. | Durable state, managed identity or secret management, health checks, observability, tests, infrastructure as code, deployment guidance, and a runbook. |
+
+## Choose a sample
+
+| Language | Sample list | Best first sample |
+|----------|-------------|-------------------|
+| .NET | [dotnet](dotnet/README.md) | [QuickStart](dotnet/quickstart/README.md) |
+| JavaScript | [nodejs](nodejs/README.md) | [QuickStart](nodejs/quickstart/README.md) |
+| Python | [python](python/README.md) | [Quickstart](python/quickstart/README.md) |
+
+## Starter sample contract
+
+Every starter sample should make its scope clear:
+
+- State the maturity tier, language, scenario, supported channels, and approximate setup time.
+- Name intentional shortcuts, such as in-memory state, local-only secrets, disabled token validation, or omitted retry policies.
+- Explain what the sample does and does not demonstrate.
+- Link to the next sample or documentation a developer should use when moving toward production.
+- Include a lightweight smoke test or manual verification step that confirms the agent starts and responds.
+
+Use [SAMPLE_README_TEMPLATE.md](SAMPLE_README_TEMPLATE.md) when adding or refreshing sample documentation.
+
+## Current production reference coverage
+
+The repository includes one Tier 3 production reference sample:
+
+- **.NET support triage agent** ([dotnet/production-reference](dotnet/production-reference/README.md)) — a deployable, stateful support triage agent with managed identity, durable Blob Storage state, health checks, OpenTelemetry, Bicep infrastructure, xUnit tests, and a runbook.
+
+
+Before labeling a sample as Tier 3, it should include or link to:
+
+| Capability | Expected production-reference coverage |
+|------------|----------------------------------------|
+| Identity and secrets | Microsoft Entra configuration, managed identity where possible, Key Vault or equivalent secret storage, and no checked-in secrets. |
+| State and storage | Durable conversation or user state with local development and cloud deployment configuration. |
+| Observability | Structured logs, traces, metrics, correlation IDs, and a documented telemetry backend. |
+| Reliability | Error handling, retry/throttling guidance, and health/readiness endpoints. |
+| Deployment | Infrastructure as code, CI/CD guidance, rollback notes, and environment-specific configuration. |
+| Testing | Unit tests, integration or smoke tests, and clear local validation commands. |
+| Operations | Troubleshooting notes, a short runbook, and known limitations. |
+
+## Starter gaps to prioritize
+
+The current catalog has strong coverage for quickstarts, authentication, OpenTelemetry, streaming, Copilot Studio integration, orchestration scenarios, and **persistent state** ([.NET](dotnet/persistent-state/README.md), [JavaScript](nodejs/persistent-state/README.md), [Python](python/persistent-state/README.md)). The next starter samples that would most improve the path from "hello world" to production are:
+
+| Gap | Why it matters |
+|-----|----------------|
+| Configuration and secret management starter | Shows local development settings separately from cloud-hosted secret storage. |
+| Error handling, retry, and throttling starter | Shows realistic handling for downstream API failures and rate limits. |
+| Health and readiness starter | Shows the endpoints and checks needed by hosting platforms and deployment pipelines. |
+| Evaluation and regression testing starter | Shows how to validate prompts, tools, and agent behavior before deployment. |
+| Cross-language parity set | Keeps the core QuickStart, auth, telemetry, and storage paths consistent across .NET, JavaScript, and Python. |
diff --git a/samples/SAMPLE_README_TEMPLATE.md b/samples/SAMPLE_README_TEMPLATE.md
@@ -0,0 +1,72 @@
+# Sample README Template
+
+Use this template when adding a new Microsoft 365 Agents SDK sample or refreshing an existing sample README. Keep starter samples focused and explicit about what is intentionally omitted.
+
+````markdown
+# <Sample name>
+
+> **Sample tier:** Tier 1: QuickStart | Tier 2: Scenario starter | Tier 3: Production reference
+> **Language:** .NET | JavaScript | Python
+> **Scenario:** <one-line scenario>
+> **Estimated setup time:** <for example, 10 minutes>
+> **Supported channels:** <Agents Playground, Web Chat, Teams, Microsoft 365 Copilot, custom app, etc.>
+
+## What this sample demonstrates
+
+- <Capability or concept this sample teaches>
+- <Integration, channel, or SDK behavior shown by the sample>
+
+## What this sample does not demonstrate
+
+- <Production capability intentionally omitted, such as durable state>
+- <Security, deployment, testing, or operations concern outside the sample scope>
+
+## Prerequisites
+
+- <Runtime and version>
+- <Required tools>
+- <Required cloud resources, if any>
+
+## Configure the sample
+
+1. <Configuration step>
+1. <Configuration step>
+
+## Run locally
+
+```bash
+<command>
+```
+
+## Verify the sample
+
+1. <Start the agent or test client>
+1. <Send a message or trigger the scenario>
+1. Confirm: `<expected observable result>`
+
+## Intentional shortcuts
+
+| Shortcut | Why it is acceptable in this sample | Production alternative |
+|----------|-------------------------------------|------------------------|
+| <Example: local `.env` secret> | <Keeps local setup simple> | <Use Key Vault or equivalent secret storage> |
+
+## Next steps
+
+- <Link to the next starter sample>
+- <Link to relevant Microsoft Learn documentation>
+- <Link to production guidance or checklist>
+````
+
+## Tier 3 production-reference additions
+
+If the sample is labeled Tier 3, also include:
+
+- Architecture diagram or deployment topology.
+- Durable state and storage configuration.
+- Managed identity or equivalent non-local secret flow.
+- Health/readiness endpoints.
+- OpenTelemetry or equivalent structured observability.
+- Unit, integration, and smoke test commands.
+- Infrastructure-as-code deployment instructions.
+- Rollback and troubleshooting notes.
+- Known limits and support boundaries.
diff --git a/samples/dotnet/README.md b/samples/dotnet/README.md
@@ -1,19 +1,24 @@
 # Microsoft 365 .NET Agents SDK Samples list
 
-|Name|Description|README|
-|----|----|----|
-|QuickStart/Empty Agent|Simplest agent|[quickstart](quickstart/README.md)|
-|AutoSignIn|Simple OAuth agent using Graph|[auto-signin](auto-signin/README.md)|
-|OBOAuthorization|OBO to Copilot Studio Agent |[obo-authorization](obo-authorization/README.md)|
-|Semantic Kernel | WeatherAgent which demonstrates a multi-turn AI interaction |[semantic-kernel-multiturn](semantic-kernel-multiturn/README.md)|
-|Streaming Agent |Streams OpenAI responses|[azure-ai-streaming](azure-ai-streaming/README.md)|
-|Copilot Studio Client|Console app to consume a Copilot Studio Agent|[copilotstudio-client](copilotstudio-client/README.md)|
-|Copilot Studio Skill |Call the echo bot from a Copilot Studio skill |[copilotstudio-skill](copilotstudio-skill/README.md)|
-|RetrievalAgent Sample with Semantic Kernel|A simple Retrieval Agent that is hosted on an Asp.net core web service. |[RetrievalAgent](retrieval-agent/README.md)|
-|MultiAgent|Demonstrates multiple AgentApplication in the same host|[MultiAgent](multiagent/README.md)|
-|GenesysHandoff|Demonstrates how a Microsoft Copilot Studio Agent (bot) can seamlessly **hand off a conversation to a live agent** in **Genesys Cloud**.|[GenesysHandoff](genesys-handoff/README.md)|
-|Proactive|Demonstrates the basics of a proactive conversation using in-code and Http triggers.|[Proactive](proactive/README.md)|
-|OpenTelemetry Agent|Configures OTel tracing, metrics, and logging with OTLP export|[otel](otel/README.md)|
-|Agent Framework|Weather agent built with Microsoft Agent Framework SDK|[Agent Framework](Agent%20Framework/README.md)|
-|Copilot SDK|Dungeon Scribe RPG agent powered by the GitHub Copilot SDK|[copilot-sdk](copilot-sdk/README.md)|
-|Named Pipe Agent|Pipe-only echo agent for the DirectLine App Service extension (DirectLineFlex)|[named-pipe-agent](named-pipe-agent/README.md)|
+These samples are Tier 1 or Tier 2 starter samples unless a README explicitly labels the sample as a production reference. See the [sample maturity tiers](../README.md#sample-maturity-tiers) before copying a sample into an application.
+
+|Name|Tier|Description|README|
+|----|----|----|----|
+|QuickStart/Empty Agent|Tier 1: QuickStart|Simplest agent|[quickstart](quickstart/README.md)|
+|AutoSignIn|Tier 2: Scenario starter|Simple OAuth agent using Graph|[auto-signin](auto-signin/README.md)|
+|OBOAuthorization|Tier 2: Scenario starter|OBO to Copilot Studio Agent |[obo-authorization](obo-authorization/README.md)|
+|Semantic Kernel | Tier 2: Scenario starter | WeatherAgent which demonstrates a multi-turn AI interaction |[semantic-kernel-multiturn](semantic-kernel-multiturn/README.md)|
+|Streaming Agent |Tier 2: Scenario starter|Streams OpenAI responses|[azure-ai-streaming](azure-ai-streaming/README.md)|
+|Copilot Studio Client|Tier 2: Scenario starter|Console app to consume a Copilot Studio Agent|[copilotstudio-client](copilotstudio-client/README.md)|
+|Copilot Studio Skill |Tier 2: Scenario starter|Call the echo bot from a Copilot Studio skill |[copilotstudio-skill](copilotstudio-skill/README.md)|
+|RetrievalBot Sample with Semantic Kernel|Tier 2: Scenario starter|A simple Retrieval Agent that is hosted on an Asp.net core web service. |[RetrievalBot](retrieval-agent/README.md)|
+|MultiAgent|Tier 2: Scenario starter|Demonstrates multiple AgentApplication in the same host|[MultiAgent](multiagent/README.md)|
+|GenesysHandoff|Tier 2: Scenario starter|Demonstrates how a Microsoft Copilot Studio Agent (bot) can seamlessly **hand off a conversation to a live agent** in **Genesys Cloud**.|[GenesysHandoff](genesys-handoff/README.md)|
+|Proactive|Tier 2: Scenario starter|Demonstrates the basics of a proactive conversation using in-code and Http triggers.|[Proactive](proactive/README.md)|
+|OpenTelemetry Agent|Tier 2: Scenario starter|Configures OTel tracing, metrics, and logging with OTLP export|[otel](otel/README.md)|
+|Agent Framework|Tier 2: Scenario starter|Weather agent built with Microsoft Agent Framework SDK|[Agent Framework](Agent%20Framework/README.md)|
+|Copilot SDK|Tier 2: Scenario starter|Dungeon Scribe RPG agent powered by the GitHub Copilot SDK|[copilot-sdk](copilot-sdk/README.md)|
+|Named Pipe Agent|Tier 2: Scenario starter|Pipe-only echo agent for the DirectLine App Service extension (DirectLineFlex)|[named-pipe-agent](named-pipe-agent/README.md)|
+|Persistent State|Tier 2: Scenario starter|Durable conversation state backed by Azure Blob Storage|[persistent-state](persistent-state/README.md)|
+|Production Reference|Tier 3: Production reference|Deployable support triage agent with managed identity, durable state, health checks, telemetry, Bicep, tests, and runbook|[production-reference](production-reference/README.md)|
+
diff --git a/samples/dotnet/Samples.sln b/samples/dotnet/Samples.sln
@@ -37,6 +37,12 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CopilotSdk", "copilot-sdk\C
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SlackAgent", "slackagent\SlackAgent.csproj", "{74277777-C4F9-2F3E-162A-02D8A8E4B702}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "PersistentState", "persistent-state\PersistentState.csproj", "{C40EE44E-A349-4B48-9556-AEA743E23092}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ProductionReference", "production-reference\ProductionReference.csproj", "{462C6644-9FCC-486B-B4E6-FED3BBF17346}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ProductionReference.Tests", "production-reference\tests\ProductionReference.Tests.csproj", "{EA9858E1-A852-4C13-B00A-351B26EF89B9}"
+EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NamedPipeAgent", "named-pipe-agent\NamedPipeAgent.csproj", "{C26BC6C8-72FF-435F-82B3-1782CA505EDF}"
 EndProject
 Global
@@ -105,9 +111,21 @@ Global
 		{74277777-C4F9-2F3E-162A-02D8A8E4B702}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{74277777-C4F9-2F3E-162A-02D8A8E4B702}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{74277777-C4F9-2F3E-162A-02D8A8E4B702}.Release|Any CPU.Build.0 = Release|Any CPU
-		{C26BC6C8-72FF-435F-82B3-1782CA505EDF}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{C26BC6C8-72FF-435F-82B3-1782CA505EDF}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{C26BC6C8-72FF-435F-82B3-1782CA505EDF}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{C40EE44E-A349-4B48-9556-AEA743E23092}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{C40EE44E-A349-4B48-9556-AEA743E23092}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{C40EE44E-A349-4B48-9556-AEA743E23092}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{C40EE44E-A349-4B48-9556-AEA743E23092}.Release|Any CPU.Build.0 = Release|Any CPU
+		{462C6644-9FCC-486B-B4E6-FED3BBF17346}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{462C6644-9FCC-486B-B4E6-FED3BBF17346}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{462C6644-9FCC-486B-B4E6-FED3BBF17346}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{462C6644-9FCC-486B-B4E6-FED3BBF17346}.Release|Any CPU.Build.0 = Release|Any CPU
+		{EA9858E1-A852-4C13-B00A-351B26EF89B9}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{EA9858E1-A852-4C13-B00A-351B26EF89B9}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{EA9858E1-A852-4C13-B00A-351B26EF89B9}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{EA9858E1-A852-4C13-B00A-351B26EF89B9}.Release|Any CPU.Build.0 = Release|Any CPU
+		{C26BC6C8-72FF-435F-82B3-1782CA505EDF}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{C26BC6C8-72FF-435F-82B3-1782CA505EDF}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{C26BC6C8-72FF-435F-82B3-1782CA505EDF}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{C26BC6C8-72FF-435F-82B3-1782CA505EDF}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
@@ -117,3 +135,4 @@ Global
 		SolutionGuid = {12345678-1234-5678-9012-123456789012}
 	EndGlobalSection
 EndGlobal
+