AG-UI .NET SDK — Feature Workflow (Orchestrator)
This is the hub skill. Given a request to build or change a feature in the AG-UI
.NET SDK (sdks/dotnet/), it lays out the correct end-to-end order and routes the
depth of each step to a focused sibling skill. It does not duplicate their content.
The SDK has a multi-artifact definition of done. An agent working ad hoc forgets
artifacts — most often cross-language parity, docs, AGENTS.md/docs/architecture.md sync,
and PublicAPI.Unshipped.txt. Use this skill to avoid that.
Package map
sdks/dotnet/src/:
| Package |
Responsibility |
AGUI.Abstractions |
Wire types: events, messages, tools, capabilities, AGUIJsonSerializerContext |
AGUI.Formatting |
JSON formatter + SSE encode/decode |
AGUI.Protobuf |
Protobuf encoding of the protocol |
AGUI.Client |
AGUIChatClient (IChatClient) + transport negotiation |
AGUI.Server |
Hosting-agnostic agent-side conversion (ChatResponseUpdate → events) |
ASP.NET hosting glue lives in samples/AGUI.Samples.Shared (not a src/ package).
sdks/dotnet/AGENTS.md and docs/architecture.md are the canonical description of
the layout and conventions (kept current via agui-dotnet-agents-sync); AGUI.slnx
is the ground truth if you need to re-derive the package list.
Build & test commands
# from sdks/dotnet/
dotnet build sdks/dotnet/AGUI.slnx # whole solution
dotnet test tests/AGUI.Abstractions.UnitTests/ # per-project, fast feedback
Directory.Build.props treats warnings as errors, and PublicApiAnalyzers is on
for every src/ project with a PublicAPI.Shipped.txt. The build fails if you skip
the AOT serialization wiring or forget PublicAPI.Unshipped.txt — these are not
optional polish steps, they are enforced.
Definition of done (feature checklist)
Ordered workflow → route each step
Do the steps in this order. Skip a step only if it genuinely doesn't apply
(e.g. a non-wire-affecting internal refactor skips cross-language parity).
Understand the wire contract. Read the TypeScript (and Python) reference for
the type/behavior so the .NET shape matches the spec. Porting an existing feature
from another SDK? → agui-cross-sdk-parity.
Implement the type/behavior in the right package.
- New/changed wire type (event, message, tool, capability) →
agui-dotnet-wire-types
(covers the AGUI.Abstractions recipe: class in Events/, AGUIEventTypes
constant, converter case, AOT registration, PublicAPI.Unshipped.txt).
- New/changed transport or encoding (SSE, protobuf, formatter) →
agui-dotnet-transport (AGUI.Formatting, AGUI.Protobuf).
Wire AOT serialization. Every protocol type goes through
AGUIJsonSerializerContext — no reflection. agui-dotnet-wire-types has the
per-type recipe; the build enforces it.
Update client/server mapping. Server-side ChatResponseUpdate → event lives in
AGUI.Server; client-side event → ChatResponseUpdate lives in AGUI.Client
(EventStreamConverter, builders). Update both directions if the wire shape changed.
Unit tests (round-trip + behavior) → agui-dotnet-unit-tests.
Integration tests (HTTP + SSE pipeline, WebApplicationFactory,
AGUIChatClient) → agui-dotnet-integration-tests. Required when the change
crosses the transport boundary.
Cross-language parity tests (if wire-affecting) →
agui-dotnet-cross-language-tests (tests/AGUI.CrossLanguage.IntegrationTests,
CrossLanguage.TestServer, CrossLanguage.Vitest). This is the step agents most
often forget — .NET must agree with TS/Python on the bytes.
Update PublicAPI.Unshipped.txt for every changed public member, in each
affected src/ project. The PublicAPI analyzer fails the build otherwise.
Docs (user-facing change) → agui-dotnet-sdk-docs (docs.ag-ui.com).
Sync AGENTS.md / docs/architecture.md if you changed structure, recipes, or
commands → agui-dotnet-agents-sync. Fix stale package references while here.
Build + test green. dotnet build sdks/dotnet/AGUI.slnx, then the relevant
dotnet test <project> (unit + integration + cross-language as applicable).
Validate & review. Run/inspect in the dojo → agui-dojo; manual UI/docs
checks → agui-playwright-validate; review the change → agui-dotnet-code-review.
Routing table (quick reference)
| Step / need |
Sibling skill |
| Add/modify a wire type |
agui-dotnet-wire-types |
| Add/modify transport or encoding |
agui-dotnet-transport |
| Port a feature from TS/Python |
agui-cross-sdk-parity |
| Write unit tests |
agui-dotnet-unit-tests |
| Write integration tests |
agui-dotnet-integration-tests |
| Write cross-language tests |
agui-dotnet-cross-language-tests |
| Add a GettingStarted sample Step (Server/Client pair) |
agui-dotnet-sample-step |
| Update SDK docs site |
agui-dotnet-sdk-docs |
| Keep AGENTS.md / docs/architecture.md current |
agui-dotnet-agents-sync |
| Run/validate in the dojo |
agui-dojo |
| Manual UI/docs validation |
agui-playwright-validate |
| Review the change |
agui-dotnet-code-review |
The depth of each step lives in the sibling skill it routes to; fall back to the
recipes in AGENTS.md and the deep content in docs/architecture.md for anything a
sibling doesn't cover.
❌ Anti-patterns
- Don't stop at "it compiles and unit tests pass." Wire-affecting changes are not
done until cross-language parity tests and docs are updated.
- Don't put protocol or server code in a sample. It belongs in
src/; the server is
AGUI.Server, hosting glue is in samples/AGUI.Samples.Shared, and no src/ project
references ASP.NET.
- Don't skip
PublicAPI.Unshipped.txt or AOT registration "to fix later" — the
warnings-as-errors build will block you immediately.
- Don't do the deep work here. This skill routes; the depth lives in the sibling
skills. Open the relevant one before implementing a step.
Source: ag-ui-protocol/ag-ui → .github/skills/agui-dotnet-feature-workflow/SKILL.md
1---
2name: agui-dotnet-feature-workflow
3description: "> Orchestrator/hub for implementing a feature or change in the AG-UI .NET SDK (sdks/dotnet). USE FOR: \"what's the workflow\", \"what order do I do things in\", \"how do I implement a feature in the .NET SDK\", starting any non-trivial AG-UI .NET SDK change, planning the end-to-end steps and definition-of-done (code + AOT serialization + client/server mapping + unit/integration/cross-language tests + docs + PublicAPI + AGENTS.md sync). DO NOT USE FOR: the deep how-to of a single step — this skill ROUTES to focused siblings: adding wire types (agui-dotnet-wire-types), transport/encoding (agui-dotnet-transport), unit tests (agui-dotnet-unit-tests), integration tests (agui-dotnet-integration-tests), cross-language tests (agui-dotnet-cross-language-tests), porting from TS/Python (agui-cross-sdk-parity), adding a GettingStarted sample Step (agui-dotnet-sample-step), SDK docs..."
4category: ai-agents-and-harness
5source_repo: ag-ui-protocol/ag-ui
6source_path: ".github/skills/agui-dotnet-feature-workflow/SKILL.md"
7source_url: https://github.com/ag-ui-protocol/ag-ui/blob/HEAD/.github/skills/agui-dotnet-feature-workflow/SKILL.md
8metadata:
9 source: https://skillmd.com/skills/ag-ui-protocol/agui-dotnet-feature-workflow
10---
11
12# AG-UI .NET SDK — Feature Workflow (Orchestrator)
13
14This is the **hub** skill. Given a request to build or change a feature in the AG-UI
15.NET SDK (`sdks/dotnet/`), it lays out the correct end-to-end order and **routes the
16depth of each step to a focused sibling skill**. It does not duplicate their content.
17
18The SDK has a multi-artifact **definition of done**. An agent working ad hoc forgets
19artifacts — most often cross-language parity, docs, `AGENTS.md`/`docs/architecture.md` sync,
20and `PublicAPI.Unshipped.txt`. Use this skill to avoid that.
21
22## Package map
23
24`sdks/dotnet/src/`:
25
26| Package | Responsibility |
27|---|---|
28| `AGUI.Abstractions` | Wire types: events, messages, tools, capabilities, `AGUIJsonSerializerContext` |
29| `AGUI.Formatting` | JSON formatter + SSE encode/decode |
30| `AGUI.Protobuf` | Protobuf encoding of the protocol |
31| `AGUI.Client` | `AGUIChatClient` (`IChatClient`) + transport negotiation |
32| `AGUI.Server` | Hosting-agnostic agent-side conversion (`ChatResponseUpdate` → events) |
33
34ASP.NET hosting glue lives in `samples/AGUI.Samples.Shared` (not a `src/` package).
35`sdks/dotnet/AGENTS.md` and `docs/architecture.md` are the canonical description of
36the layout and conventions (kept current via `agui-dotnet-agents-sync`); `AGUI.slnx`
37is the ground truth if you need to re-derive the package list.
38
39## Build & test commands
40
41```bash
42# from sdks/dotnet/
43dotnet build sdks/dotnet/AGUI.slnx # whole solution
44dotnet test tests/AGUI.Abstractions.UnitTests/ # per-project, fast feedback
45```
46
47`Directory.Build.props` **treats warnings as errors**, and `PublicApiAnalyzers` is on
48for every `src/` project with a `PublicAPI.Shipped.txt`. **The build fails if you skip
49the AOT serialization wiring or forget `PublicAPI.Unshipped.txt`** — these are not
50optional polish steps, they are enforced.
51
52## Definition of done (feature checklist)
53
54- [ ] Wire contract understood (matched against TS/Python reference if wire-affecting)
55- [ ] Type/behavior implemented in the **right package** (see map)
56- [ ] AOT serialization wired (`[JsonSerializable]` in `AGUIJsonSerializerContext`, converter case, `[JsonPropertyName]`)
57- [ ] Client/server mapping updated (`AGUI.Client` event→update and/or `AGUI.Server` update→event)
58- [ ] Unit tests (serialization round-trip + behavior)
59- [ ] Integration tests (full pipeline) if it crosses the HTTP/SSE boundary
60- [ ] Cross-language parity tests if wire-affecting
61- [ ] `PublicAPI.Unshipped.txt` updated for every changed public member
62- [ ] Docs updated (docs.ag-ui.com / SDK docs) if user-facing
63- [ ] `AGENTS.md` / `docs/architecture.md` synced if structure/recipe changed
64- [ ] `dotnet build sdks/dotnet/AGUI.slnx` and relevant `dotnet test` projects green
65
66## Ordered workflow → route each step
67
68Do the steps **in this order**. Skip a step only if it genuinely doesn't apply
69(e.g. a non-wire-affecting internal refactor skips cross-language parity).
70
711. **Understand the wire contract.** Read the TypeScript (and Python) reference for
72 the type/behavior so the .NET shape matches the spec. Porting an existing feature
73 from another SDK? → **`agui-cross-sdk-parity`**.
74
752. **Implement the type/behavior in the right package.**
76 - New/changed wire type (event, message, tool, capability) → **`agui-dotnet-wire-types`**
77 (covers the `AGUI.Abstractions` recipe: class in `Events/`, `AGUIEventTypes`
78 constant, converter case, AOT registration, `PublicAPI.Unshipped.txt`).
79 - New/changed transport or encoding (SSE, protobuf, formatter) →
80 **`agui-dotnet-transport`** (`AGUI.Formatting`, `AGUI.Protobuf`).
81
823. **Wire AOT serialization.** Every protocol type goes through
83 `AGUIJsonSerializerContext` — no reflection. `agui-dotnet-wire-types` has the
84 per-type recipe; the build enforces it.
85
864. **Update client/server mapping.** Server-side `ChatResponseUpdate` → event lives in
87 `AGUI.Server`; client-side event → `ChatResponseUpdate` lives in `AGUI.Client`
88 (`EventStreamConverter`, builders). Update both directions if the wire shape changed.
89
905. **Unit tests** (round-trip + behavior) → **`agui-dotnet-unit-tests`**.
91
926. **Integration tests** (HTTP + SSE pipeline, `WebApplicationFactory`,
93 `AGUIChatClient`) → **`agui-dotnet-integration-tests`**. Required when the change
94 crosses the transport boundary.
95
967. **Cross-language parity tests** (if wire-affecting) →
97 **`agui-dotnet-cross-language-tests`** (`tests/AGUI.CrossLanguage.IntegrationTests`,
98 `CrossLanguage.TestServer`, `CrossLanguage.Vitest`). This is the step agents most
99 often forget — .NET must agree with TS/Python on the bytes.
100
1018. **Update `PublicAPI.Unshipped.txt`** for every changed public member, in each
102 affected `src/` project. The PublicAPI analyzer fails the build otherwise.
103
1049. **Docs** (user-facing change) → **`agui-dotnet-sdk-docs`** (docs.ag-ui.com).
105
10610. **Sync `AGENTS.md` / `docs/architecture.md`** if you changed structure, recipes, or
107 commands → **`agui-dotnet-agents-sync`**. Fix stale package references while here.
108
10911. **Build + test green.** `dotnet build sdks/dotnet/AGUI.slnx`, then the relevant
110 `dotnet test <project>` (unit + integration + cross-language as applicable).
111
11212. **Validate & review.** Run/inspect in the dojo → **`agui-dojo`**; manual UI/docs
113 checks → **`agui-playwright-validate`**; review the change → **`agui-dotnet-code-review`**.
114
115## Routing table (quick reference)
116
117| Step / need | Sibling skill |
118|---|---|
119| Add/modify a wire type | `agui-dotnet-wire-types` |
120| Add/modify transport or encoding | `agui-dotnet-transport` |
121| Port a feature from TS/Python | `agui-cross-sdk-parity` |
122| Write unit tests | `agui-dotnet-unit-tests` |
123| Write integration tests | `agui-dotnet-integration-tests` |
124| Write cross-language tests | `agui-dotnet-cross-language-tests` |
125| Add a GettingStarted sample Step (Server/Client pair) | `agui-dotnet-sample-step` |
126| Update SDK docs site | `agui-dotnet-sdk-docs` |
127| Keep AGENTS.md / docs/architecture.md current | `agui-dotnet-agents-sync` |
128| Run/validate in the dojo | `agui-dojo` |
129| Manual UI/docs validation | `agui-playwright-validate` |
130| Review the change | `agui-dotnet-code-review` |
131
132> The depth of each step lives in the sibling skill it routes to; fall back to the
133> recipes in `AGENTS.md` and the deep content in `docs/architecture.md` for anything a
134> sibling doesn't cover.
135
136## ❌ Anti-patterns
137
1381. **Don't stop at "it compiles and unit tests pass."** Wire-affecting changes are not
139 done until cross-language parity tests and docs are updated.
1402. **Don't put protocol or server code in a sample.** It belongs in `src/`; the server is
141 `AGUI.Server`, hosting glue is in `samples/AGUI.Samples.Shared`, and no `src/` project
142 references ASP.NET.
1433. **Don't skip `PublicAPI.Unshipped.txt` or AOT registration** "to fix later" — the
144 warnings-as-errors build will block you immediately.
1454. **Don't do the deep work here.** This skill routes; the depth lives in the sibling
146 skills. Open the relevant one before implementing a step.
147
148---
149
150**Source:** [`ag-ui-protocol/ag-ui`](https://github.com/ag-ui-protocol/ag-ui) → `.github/skills/agui-dotnet-feature-workflow/SKILL.md`