Clarify sample maturity tiers and add durable-state reference samples by andrewmatkin · Pull Request #641 · microsoft/Agents

andrewmatkin · 2026-06-30T18:26:19Z

Summary

Adds sample maturity-tier guidance and a reusable README template so quickstarts, scenario starters, and production references are clearly distinguished.
Adds Azure Blob Storage persistent-state starter samples for .NET, Node.js, and Python.
Adds a .NET Tier 3 production-reference support triage sample with managed identity, Key Vault, Blob Storage, health checks, telemetry, Bicep infrastructure, tests, deployment guidance, and runbook.

Closes #640

Validation

dotnet build samples\dotnet\persistent-state\PersistentState.csproj
dotnet build samples\dotnet\production-reference\ProductionReference.csproj
dotnet test samples\dotnet\production-reference\tests\ProductionReference.Tests.csproj
[x]
pm run --prefix samples\nodejs\persistent-state build
Python compile check for samples\python\persistent-state\src
[x]
pm run lint -- --quiet
[x]
pm run validate-plugin
�z bicep build --file samples\dotnet\production-reference\infra\main.bicep
Markdown link/fence validation

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

- New Tier 2 sample: samples/dotnet/persistent-state - PersistentState.csproj references Microsoft.Agents.Storage.Blobs 1.5.* - Program.cs reads AZURE_BLOB_STORAGE_CONNECTION_STRING (fail-fast) and AZURE_BLOB_STORAGE_CONTAINER_NAME (default: agents-persistent-state), registers BlobsStorage as IStorage singleton - MyAgent.cs uses turnState.Conversation.GetValue/SetValue to maintain a per-conversation message counter across restarts - AspNetExtensions.cs, appsettings.json, launchSettings.json copied from QuickStart to preserve local auth and launch behavior - README follows SAMPLE_README_TEMPLATE.md; covers local connection string setup, Azurite emulation, container naming rules, verify steps, and managed identity / workload identity as the cloud deployment path - Project added to samples/dotnet/Samples.sln Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

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

- nodejs/persistent-state: fix broken Next starter link from ../multiagent/README.md to ../multi-turn-prompt/README.md - python/persistent-state: fix broken Next starter link from ../multi-turn-prompt/README.md (path does not exist) to ../semantic-kernel-multiturn/README.md - nodejs/README.md: move Persistent State row before Copilot SDK Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

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

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

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

# Conflicts: # samples/dotnet/README.md # samples/dotnet/Samples.sln # samples/nodejs/README.md

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

andrewmatkin · 2026-07-01T17:09:03Z

andrewmatkin please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.
@microsoft-github-policy-service agree [company="{your company}"]
Options:

(default - no company specified) I have sole ownership of intellectual property rights to my Submissions and I am not making Submissions in the course of work for my employer.
@microsoft-github-policy-service agree
(when company given) I am making Submissions in the course of work for my employer (or my employer has intellectual property rights in my Submissions by contract or applicable law). I have permission from my employer to make Submissions and enter into this Agreement on behalf of my employer. By signing below, the defined term “You” includes me and my employer.
@microsoft-github-policy-service agree company="Microsoft"
Contributor License Agreement

@microsoft-github-policy-service agree company="Microsoft"

tracyboehrer (tracyboehrer) · 2026-08-13T21:00:21Z

Any reason that using state couldn't be incorporated into another example? For example, quickstart?

tracyboehrer (tracyboehrer) · 2026-08-13T21:04:38Z

Why do we need a Blobs specific storage options in the production-reference? As opposed to: https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/storage?tabs=csharp

tracyboehrer (tracyboehrer) · 2026-08-14T19:45:41Z

I'm generally OK with the idea of a sample that shows a complete production bot.

It should be coupled with a doc, which would include things like "how to secure your agent" (there is a dotnet version in PR), include the existing doc on registering persistent storage, etc...

Then preferably a Claude/Copilot skill to aid in adding production features to an agent (see #653)

andrewmatkin and others added 30 commits June 5, 2026 10:27

Ignore local worktree directory

5e9cd4d

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

Document sample maturity taxonomy

ca01061

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

Polish .NET persistent state starter

b8e9623

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

Clean .NET sample solution entry

536c1b7

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

Add JavaScript persistent state starter

0bc1820

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

Fix Node.js version prerequisite and managed identity URL in README

f7de4c8

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

Fix JavaScript persistent state scripts

31f977b

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

Add Python persistent state starter

c8059a9

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

Align Python persistent state setup

8e62c5c

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

Add persistent state samples to catalogs

7fdb58b

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

Point persistent state docs to advanced next samples

e63ed75

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

Align .NET persistent state next sample

f07c8bc

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

Address persistent state review feedback

5353e6f

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

Align Python persistent state verification text

5f29bac

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

Add .NET production reference skeleton

ca17306

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

Remove production reference solution BOM

7e1b168

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

Remove production reference solution leading blank

e7a8f61

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

Normalize production reference JSON encoding

0f5904d

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

Add production reference storage configuration

6b7b41e

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

Add support triage agent behavior

e6e4f9a

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

Fix dialog to not mutate input state; add immutability + whitespace t…

2ee7455

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

Exclude nested tests from production reference app globs

71b4d44

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

Add production reference health and telemetry

e7c1a23

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

Keep production reference test config out of publish output

7230496

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

Add production reference Azure infrastructure

8fab403

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

Remove generated production reference ARM artifact

40244b2

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

Document .NET production reference sample

bb64d81

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

Correct production reference operations docs

f144606

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

andrewmatkin and others added 4 commits June 26, 2026 14:09

Address production reference final review feedback

e2b7961

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

Stabilize production reference telemetry tests

6f62b46

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

Merge remote-tracking branch 'origin/main' into sample-taxonomy-strategy

240d686

# Conflicts: # samples/dotnet/README.md # samples/dotnet/Samples.sln # samples/nodejs/README.md

Fix sample catalog links after main merge

bb88468

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

github-actions Bot added Samples Changes to Samples From Fork labels Jun 30, 2026

andrewmatkin mentioned this pull request Jun 30, 2026

Clarify sample maturity tiers and add durable-state reference samples #640

Open

Merge branch 'main' into sample-taxonomy-strategy

9e422b1

MattB (MattB-msft) requested review from Axel Suárez (axelsrz), Cecilia Avila (ceciliaavila), Rodrigo Brandão (rodrigobr-msft), Joel Mut (sw-joelmut) and tracyboehrer (tracyboehrer) August 13, 2026 15:27

Navigation Menu

Uh oh!

Clarify sample maturity tiers and add durable-state reference samples - #641

Clarify sample maturity tiers and add durable-state reference samples#641
andrewmatkin wants to merge 35 commits into
microsoft:mainfrom
andrewmatkin:sample-taxonomy-strategy

andrewmatkin commented Jun 30, 2026

Uh oh!

andrewmatkin commented Jul 1, 2026

Uh oh!

tracyboehrer (tracyboehrer) commented Aug 13, 2026

Uh oh!

tracyboehrer (tracyboehrer) commented Aug 13, 2026

Uh oh!

tracyboehrer (tracyboehrer) commented Aug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants