AG-UI .NET — Add a GettingStarted Sample Step

The samples/GettingStarted/Step01..StepNN pairs are the primary consumer-facing deliverable: each Step is a self-contained Server + Client that demonstrates one feature, written to look like the code we want users to write. Adding a Step is a recurring, multi-artifact task. This skill covers the sample anatomy and wiring; it routes the integration-test mechanics to agui-dotnet-integration-tests and the doc sync to agui-dotnet-agents-sync.

Run all commands from sdks/dotnet/. Confirm the next free number and the current naming by listing samples/GettingStarted/Step* first — never assume the range.

Anatomy of a Step

A Step is a folder samples/GettingStarted/StepNN_<Name>/ with two projects:

• StepNN_<Name>.Server — an ASP.NET host (Microsoft.NET.Sdk.Web, net10.0). Program.cs calls builder.Services.AddAGUI(), registers an IChatClient, and ends with app.MapAGUI("/"). The IChatClient is the whole point: the SDK turns any IChatClient into an AG-UI endpoint, so the sample logic is just MEAI.

  • References src/AGUI.Abstractions + samples/AGUI.Samples.Shared (the ASP.NET glue). It does not reference an src/ server package directly.
  • InternalsVisibleTo the integration-test project so its replay test can reach the server's Program and any FakeChatClient.
  • Provide a deterministic FakeChatClient fallback (fixed clocks, canned tool results) used when no real LLM is configured. Replayable determinism is what lets the integration test record once and replay forever.

• StepNN_<Name>.Client — a console app (Microsoft.NET.Sdk, OutputType Exe, net10.0). Program.cs builds the client and hands it to a shared SampleClient:

  using HttpClient httpClient = new() { BaseAddress = new Uri(baseUrl) };
  var aguiClient = new AGUIChatClient(new(httpClient, baseUrl));
  await SampleClient.RunAsync(aguiClient, Console.Out);

  • References only src/AGUI.Client. (AGUIChatClient is constructed from AGUIChatClientOptions — see agui-dotnet-transport for the protobuf opt-in via AGUIEventStreamHandler.)

Mirror the closest existing Step rather than inventing structure: the feature determines which one (tools → Step02/03, interrupts → Step09/10, state → Step05, parallel calls → Step12). Keep the file-name/type-name/namespace consistent (StepNN_<Name>.Server etc.).

Wiring (the parts agents forget)

1. Solution. Add both .csproj paths to AGUI.slnx under the /samples/GettingStarted/ folder, in Step order.
2. Integration-test references. Add a ProjectReference to both the Server and Client projects in tests/AGUI.Hosting.AspNetCore.IntegrationTests/*.csproj (it references every Step pair so its replay tests can host them).
3. Replay test. Add Samples/GettingStarted/StepNN_<Name>Test.cs deriving from IntegrationTestBase<StepNN_<Name>.Server.Program>, then record its baseline. The recording/Verify/8-capture-point mechanics belong to agui-dotnet-integration-tests — use that skill; don't reinvent them here. Fixtures land under Samples/GettingStarted/fixtures/StepNN_<Name>/ and baselines under baselines/StepNN_<Name>/.
4. Doc tables. Add the Step to the Step tables in sdks/dotnet/AGENTS.md and sdks/dotnet/docs/architecture.md (and the PR review guide's Step table if present) via agui-dotnet-agents-sync.

GettingStarted Steps are standalone console samples, not dojo scenarios. The dojo is a separate host (samples/AGUIClientServer/AGUIDojoServer) — only touch it via agui-dojo if the feature also needs a dojo demo.

Verify

dotnet build samples/GettingStarted/StepNN_<Name>/StepNN_<Name>.Server/StepNN_<Name>.Server.csproj
dotnet build samples/GettingStarted/StepNN_<Name>/StepNN_<Name>.Client/StepNN_<Name>.Client.csproj
dotnet test tests/AGUI.Hosting.AspNetCore.IntegrationTests/ --filter StepNN_<Name>

Run the pair end to end (server in one shell, client in another) to confirm it reads like the code a user would write — the bar for a sample is exemplary, not merely passing.

❌ Anti-patterns

1. Non-deterministic sample behavior. A wall-clock, RNG, or live network call in the FakeChatClient path breaks record/replay. Use fixed values.
2. Protocol or hosting code in the sample. A Step composes existing SDK APIs; if it needs a new event/encoding, that lands in src/ first (agui-dotnet-wire-types / agui-dotnet-transport), and the sample only consumes it.
3. Half-wired Step. Forgetting AGUI.slnx, the integration-test ProjectReference, or the doc Step tables leaves a sample that builds locally but isn't covered, shipped in the solution, or documented.
4. Diverging from the sibling Steps. Copy the closest Step's shape (naming, csproj refs, Program.cs skeleton, InternalsVisibleTo) instead of a new layout.

References

• Replay/Verify test mechanics: agui-dotnet-integration-tests.
• Step tables / structure sync: agui-dotnet-agents-sync.
• Protobuf opt-in or a new encoding the Step demos: agui-dotnet-transport.
• End-to-end workflow context: agui-dotnet-feature-workflow.