Create and publish documentation site for 0.4 dotnet (#5275)

<img width="1840" alt="Screenshot 2025-01-30 at 6 26 02 PM"
src="https://github.com/user-attachments/assets/5b4c9ebf-0880-4b2e-aa1f-f2b956922b49"
/>

.github/workflows/docs.yml

@@ -185,12 +185,64 @@ jobs:
           path: "website/artifact"
           name: "02-docs"
 
+  build-04-dotnet:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          lfs: true
+      - name: Setup .NET 8.0
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '8.0.x'
+          global-json-file: dotnet/global.json
+      - run: dotnet tool update -g docfx
+      - run: |
+          mkdir -p ./build/dotnet/dev/
+          docfx build docfx.json --output ./build/dotnet/dev/
+        working-directory: ./docs/dotnet
+      - name: insert clarity snippet to *.html
+        working-directory: ./docs/dotnet/build/dotnet/dev/
+        shell: python
+        run: |
+          import os
+          clarity_script = """
+          <script type="text/javascript">
+              (function(c,l,a,r,i,t,y){
+                  c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
+                  t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
+                  y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
+              })(window, document, "clarity", "script", "lnxpe6skj1");
+          </script>
+          """
+
+          site_folder = '.'
+
+          for root, dirs, files in os.walk(site_folder):
+              for file in files:
+                  if file.endswith('.html'):
+                      html_path = os.path.join(root, file)
+
+                      # insert the script into the html's head section
+                      with open(html_path, 'r') as file:
+                          html = file.read()
+                          html = html.replace('</head>', clarity_script + '</head>')
+
+                      with open(html_path, 'w') as file:
+                          file.write(html)
+
+                      print(f'Clarity script inserted into {html_path}')
+      - uses: actions/upload-artifact@v4
+        with:
+          path: "./docs/dotnet/build"
+          name: "dotnet-dev-docs"
+
   deploy:
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
-    needs: [build-02, build-04, gen-redirects, gen-component-schema]
+    needs: [build-02, build-04, build-04-dotnet, gen-redirects, gen-component-schema]
     if: ${{ needs.build-02.result == 'success' && needs.build-04.result == 'success' && needs.gen-redirects.result == 'success' && github.ref == 'refs/heads/main' }}
     steps:
       - uses: actions/download-artifact@v4

docs/dotnet/.gitignore

@@ -0,0 +1,12 @@
+###############
+#    folder   #
+###############
+/**/DROP/
+/**/TEMP/
+/**/packages/
+/**/bin/
+/**/obj/
+
+# build artifacts for web
+_site/
+api/

docs/dotnet/README.md

@@ -0,0 +1,13 @@
+## How to build and run the website
+
+### Prerequisites
+- dotnet 7.0 or later
+
+### Build
+Firstly, go to autogen/dotnet folder and run the following command to build the website:
+```bash
+dotnet tool restore
+dotnet tool run docfx website/docfx.json --serve
+```
+
+After the command is executed, you can open your browser and navigate to `http://localhost:8080` to view the website.

docs/dotnet/core/differences-from-python.md

@@ -0,0 +1,8 @@
+# Differences from Python
+
+## Publishing to a topic that an agent is also subscribed to
+
+> [!NOTE]
+> TLDR; Default behavior is identical.
+
+When an agent publishes a message to a topic to which it also listens, the message will not be received by the agent that sent it. This is also the behavior in the Python runtime. However to support previous usage, in @Microsoft.AutoGen.Core.InProcessRuntime, you can set the @Microsoft.AutoGen.Core.InProcessRuntime.DeliverToSelf property to true in the TopicSubscription attribute to allow an agent to receive messages it sends.

docs/dotnet/core/index.md

@@ -0,0 +1,7 @@
+# AutoGen Core
+
+AutoGen Core for .NET follows the same concepts and conventions of its Python counterpart. In fact, in order to understand the concepts in the .NET version, we recommend reading the Python documentation first. Unless otherwise stated, the concepts in the Python version map to .NET.
+
+Any important differences between the language versions are documented in the [Differences from Python](./differences-from-python.md) section. For things that only affect a given language, such as dependency injection or host builder patterns, these will not be specified in the differences document.
+
+For .NET we are starting with the core functionality and will be expanding support progressively. So far the core abstractions of Agent and Runtime are available. The InProcessRuntime is the only runtime available at this time. We will be expanding to cross language support in upcoming releases.

docs/dotnet/core/installation.md

@@ -0,0 +1,22 @@
+# Installation
+
+Install via `.NET cli`
+
+```sh
+dotnet add package Microsoft.AutoGen.Contracts --version 0.4.0-dev.1
+dotnet add package Microsoft.AutoGen.Core --version 0.4.0-dev.1
+```
+
+Or, install via `Package Manager`
+
+```pwsh
+PM> NuGet\Install-Package Microsoft.AutoGen.Contracts -Version 0.4.0-dev.1
+PM> NuGet\Install-Package Microsoft.AutoGen.Core -Version 0.4.0-dev.1
+```
+
+Or, add via `<PackageReference>`
+
+```xml
+<PackageReference Include="Microsoft.AutoGen.Contracts" Version="0.4.0-dev.1" />
+<PackageReference Include="Microsoft.AutoGen.Core" Version="0.4.0-dev.1" />
+```

docs/dotnet/core/protobuf-message-types.md

@@ -0,0 +1,58 @@
+# Using Protocol Buffers to Define Message Types
+
+For a message to be sent using a runtime other than the @Microsoft.AutoGen.Core.InProcessRuntime, it must be defined as a Protocol Buffers message. This is because the message is serialized and deserialized using Protocol Buffers. This requirement may be relaxed in future by allowing for converters, custom serialization, or other mechanisms.
+
+## How to include Protocol Buffers in a .NET project
+
+The .proto file which defines the message types must be included in the project, which will automatically generate the C# classes for the messages.
+
+1. Include `Grpc.Tools` package in your `.csproj` file:
+
+```xml
+  <PackageReference Include="Grpc.Tools" PrivateAssets="All" />
+```
+
+2. Create an include a `.proto` file in the project:
+
+```xml
+<ItemGroup>
+  <Protobuf Include="messages.proto" GrpcServices="Client;Server" Link="messages.proto" />
+</ItemGroup>
+```
+
+3. define your messages as specified in the [Protocol Buffers Language Guide](https://protobuf.dev/programming-guides/proto3/)
+
+```proto
+syntax = "proto3";
+
+package HelloAgents;
+
+option csharp_namespace = "MyAgentsProtocol";
+
+message TextMessage {
+    string Source = 1;
+    string Content = 2;
+}
+```
+
+4. Code against the generated class for handling, sending and publishing messages:
+
+```csharp
+using Microsoft.AutoGen.Contracts;
+using Microsoft.AutoGen.Core;
+using MyAgentsProtocol;
+
+[TypeSubscription("default")]
+public class Checker(
+    AgentId id,
+    IAgentRuntime runtime,
+    ) :
+        BaseAgent(id, runtime, "MyAgent", null),
+        IHandle<TextMessage>
+{
+    public async ValueTask HandleAsync(TextMessage item, MessageContext messageContext)
+    {
+        Console.WriteLine($"Received message from {item.Source}: {item.Content}");
+    }
+}
+```

docs/dotnet/core/toc.yml

@@ -0,0 +1,10 @@
+- name: Overview
+  href: index.md
+- name: Installation
+  href: installation.md
+- name: Tutorial
+  href: tutorial.md
+- name: Differences from Python
+  href: differences-from-python.md
+- name: Protobuf message types
+  href: protobuf-message-types.md

docs/dotnet/core/tutorial.md

@@ -0,0 +1,165 @@
+# Tutorial
+
+> [!TIP]
+> If you'd prefer to just see the code the entire sample is available as a [project here](https://github.com/microsoft/autogen/tree/main/dotnet/samples/GettingStarted).
+
+In this tutorial we are going to define two agents, `Modifier` and `Checker`, that will count down from 10 to 1. The `Modifier` agent will modify the count and the `Checker` agent will check the count and stop the application when the count reaches 1.
+
+## Defining the message types
+
+The first thing we need to do is to define the messages that will be passed between the agents, we're simply going to define them as classes.
+
+We're going to use `CountMessage` to pass the current count and `CountUpdate` to pass the updated count.
+
+[!code-csharp[](../../../dotnet/samples/GettingStarted/CountMessage.cs#snippet_CountMessage)]
+[!code-csharp[](../../../dotnet/samples/GettingStarted/CountUpdate.cs#snippet_CountUpdate)]
+
+By separating out the message types into strongly typed classes, we can build a workflow where agents react to certain types and produce certain types.
+
+## Creating the agents
+
+### Inherit from `BaseAgent`
+
+In AutoGen an agent is a class that can receive and send messages. The agent defines its own logic of what to do with the messages it receives. To define an agent, create a class that inherits from @Microsoft.AutoGen.Core.BaseAgent, like so:
+
+```csharp
+using Microsoft.AutoGen.Contracts;
+using Microsoft.AutoGen.Core;
+
+public class Modifier(
+    AgentId id,
+    IAgentRuntime runtime,
+    ) :
+        BaseAgent(id, runtime, "MyAgent", null),
+{
+}
+```
+
+We will see how to pass arguments to an agent when it is constructed, but for now you just need to know that @Microsoft.AutoGen.Contracts.AgentId and @Microsoft.AutoGen.Core.IAgentRuntime will always be passed to the constructor, and those should be forwarded to the base class constructor. The other two arguments are a description of the agent and an optional logger.
+
+Learn more about what an Agent ID is [here](https://microsoft.github.io/autogen/stable/user-guide/core-user-guide/core-concepts/agent-identity-and-lifecycle.html#agent-id).
+
+### Create a handler
+
+Now, we want `Modifier` to receive `CountMessage` and produce `CountUpdate` after it modifies the count. To do this, we need to implement the `IHandle<CountMessage>` interface:
+
+```csharp
+public class Modifier(
+    // ...
+    ) :
+        BaseAgent(...),
+        IHandle<CountMessage>
+{
+
+    public async ValueTask HandleAsync(CountMessage item, MessageContext messageContext)
+    {
+        // ...
+    }
+}
+```
+
+### Add a subscription
+
+We've defined a function that will be called when a `CountMessage` is delivered to this agent, but there is still one step before the message will actually be delivered to the agent. The agent must subscribe to the topic to the message is published to. We can do this by adding the `TypeSubscription` attribute to the class:
+
+```csharp
+[TypeSubscription("default")]
+public class Modifier(
+    // ...
+```
+
+Learn more about topics and subscriptions [here](https://microsoft.github.io/autogen/stable/user-guide/core-user-guide/core-concepts/topic-and-subscription.html).
+
+### Publish a message
+
+Now that we have a handler for `CountMessage`, and we have the subscription in place we can publish a result out of the handler.
+
+```csharp
+public async ValueTask HandleAsync(CountMessage item, MessageContext messageContext)
+{
+    int newValue = item.Content - 1;
+    Console.WriteLine($"\nModifier:\nModified {item.Content} to {newValue}");
+
+    CountUpdate updateMessage = new CountUpdate { NewCount = newValue };
+    await this.PublishMessageAsync(updateMessage, topic: new TopicId("default"));
+}
+```
+
+You'll notice that when we publish the message, we specify the topic to publish to. We're using a topic called `default` in this case, which is the same topic which we subscribed to. We could have used a different topic, but in this case we're keeping it simple.
+
+### Passing arguments to the agent
+
+Let's extend our agent to make what we do to the count configurable. We'll do this by passing a function to the agent that will be used to modify the count.
+
+```csharp
+using ModifyF = System.Func<int, int>;
+
+// ...
+
+[TypeSubscription("default")]
+public class Modifier(
+    AgentId id,
+    IAgentRuntime runtime,
+    ModifyF modifyFunc // <-- Add this
+    ) :
+        BaseAgent(...),
+        IHandle<CountMessage>
+{
+
+    public async ValueTask HandleAsync(CountMessage item, MessageContext messageContext)
+    {
+        int newValue = modifyFunc(item.Content); // <-- use it here
+
+        // ...
+    }
+}
+
+```
+
+### Final Modifier implementation
+
+Here is the final implementation of the Modifier agent:
+
+[!code-csharp[](../../../dotnet/samples/GettingStarted/Modifier.cs#snippet_Modifier)]
+
+### Checker
+
+We'll also define a Checker agent that will check the count and stop the application when the count reaches 1. Additionally, we'll use dependency injection to get a reference to the `IHostApplicationLifetime` service, which we can use to stop the application.
+
+[!code-csharp[](../../../dotnet/samples/GettingStarted/Checker.cs#snippet_Checker)]
+
+## Putting it all together
+
+Now that we have our agents defined, we can put them together in a simple application that will count down from 10 to 1.
+
+After includes, the first thing to do is to define the two functions for modifying and checking for completion.
+
+[!code-csharp[](../../../dotnet/samples/GettingStarted/Program.cs#snippet_Program_funcs)]
+
+Then, we create a builder and do the following things:
+
+- Specify that we are using the in process runtime
+- Register our functions as services
+- Register the agent classes we defined earlier
+- Finally, build and start our app
+
+[!code-csharp[](../../../dotnet/samples/GettingStarted/Program.cs#snippet_Program_builder)]
+
+The app is now running, but we need to kick off the process with a message. We do this by publishing a `CountMessage` with an initial value of 10.
+Importantly we publish this to the "default" topic which is what our agents are subscribed to. Finally, we wait for the application to stop.
+
+[!code-csharp[](../../../dotnet/samples/GettingStarted/Program.cs#snippet_Program_publish)]
+
+That's it! You should see the count down from 10 to 1 in the console.
+
+Here's the full code for the `Program` class:
+
+[!code-csharp[](../../../dotnet/samples/GettingStarted/Program.cs#snippet_Program)]
+
+## Things to try
+
+Here are some ideas to try with this sample:
+
+- Change the initial count
+- Create a new modifier function that counts up instead. (Don't forget to change the checker too!)
+- Create an agent that outputs to the console instead of the modifier or checker agent doing it themselves (hint: use a new message type)

docs/dotnet/docfx.json

@@ -0,0 +1,78 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "files": [
+            "Contracts/Microsoft.AutoGen.Contracts.csproj",
+            "Core/Microsoft.AutoGen.Core.csproj"
+          ],
+          "src": "../../dotnet/src/Microsoft.Autogen/"
+        }
+      ],
+      "dest": "api",
+      "includePrivateMembers": false,
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false,
+      "noRestore": false,
+      "namespaceLayout": "flattened",
+      "memberLayout": "samePage",
+      "allowCompilationErrors": false
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": [
+          "api/**.yml",
+          "api/index.md"
+        ]
+      },
+      {
+        "files": [
+          "core/**.md",
+          "core/**/toc.yml",
+          "articles/**.md",
+          "articles/**/toc.yml",
+          "tutorial/**.md",
+          "tutorial/**/toc.yml",
+          "release_note/**.md",
+          "release_note/**/toc.yml",
+          "toc.yml",
+          "*.md"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**"
+        ]
+      }
+    ],
+    "output": "_site",
+    "globalMetadataFiles": [],
+    "fileMetadataFiles": [],
+    "template": [
+      "default",
+      "modern",
+      "template"
+    ],
+    "globalMetadata": {
+      "_appTitle": "AutoGen .NET",
+      "_appName": "AutoGen .NET",
+      "_appLogoPath": "images/logo.svg",
+      "_appFooter": "AutoGen",
+      "_appFaviconPath": "images/favicon.ico",
+      "_gitContribute": {
+        "repo": "https://github.com/microsoft/autogen.git"
+      }
+    },
+    "postProcessors": [
+      "ExtractSearchIndex"
+    ],
+    "_enableSearch": true,
+    "keepFileLink": false,
+    "disableGitFeatures": false
+  }
+}

docs/dotnet/images/logo.svg

@@ -0,0 +1,4 @@
+<svg width="96" height="85" viewBox="0 0 96 85" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="96" height="85" rx="6" fill="#2D2D2F"/>
+<path d="M32.6484 28.7109L23.3672 57H15.8906L28.5703 22.875H33.3281L32.6484 28.7109ZM40.3594 57L31.0547 28.7109L30.3047 22.875H35.1094L47.8594 57H40.3594ZM39.9375 44.2969V49.8047H21.9141V44.2969H39.9375ZM77.6484 39.1641V52.6875C77.1172 53.3281 76.2969 54.0234 75.1875 54.7734C74.0781 55.5078 72.6484 56.1406 70.8984 56.6719C69.1484 57.2031 67.0312 57.4688 64.5469 57.4688C62.3438 57.4688 60.3359 57.1094 58.5234 56.3906C56.7109 55.6562 55.1484 54.5859 53.8359 53.1797C52.5391 51.7734 51.5391 50.0547 50.8359 48.0234C50.1328 45.9766 49.7812 43.6406 49.7812 41.0156V38.8828C49.7812 36.2578 50.1172 33.9219 50.7891 31.875C51.4766 29.8281 52.4531 28.1016 53.7188 26.6953C54.9844 25.2891 56.4922 24.2188 58.2422 23.4844C59.9922 22.75 61.9375 22.3828 64.0781 22.3828C67.0469 22.3828 69.4844 22.8672 71.3906 23.8359C73.2969 24.7891 74.75 26.1172 75.75 27.8203C76.7656 29.5078 77.3906 31.4453 77.625 33.6328H70.8047C70.6328 32.4766 70.3047 31.4688 69.8203 30.6094C69.3359 29.75 68.6406 29.0781 67.7344 28.5938C66.8438 28.1094 65.6875 27.8672 64.2656 27.8672C63.0938 27.8672 62.0469 28.1094 61.125 28.5938C60.2188 29.0625 59.4531 29.7578 58.8281 30.6797C58.2031 31.6016 57.7266 32.7422 57.3984 34.1016C57.0703 35.4609 56.9062 37.0391 56.9062 38.8359V41.0156C56.9062 42.7969 57.0781 44.375 57.4219 45.75C57.7656 47.1094 58.2734 48.2578 58.9453 49.1953C59.6328 50.1172 60.4766 50.8125 61.4766 51.2812C62.4766 51.75 63.6406 51.9844 64.9688 51.9844C66.0781 51.9844 67 51.8906 67.7344 51.7031C68.4844 51.5156 69.0859 51.2891 69.5391 51.0234C70.0078 50.7422 70.3672 50.4766 70.6172 50.2266V44.1797H64.1953V39.1641H77.6484Z" fill="white"/>
+</svg>

docs/dotnet/index.md

@@ -0,0 +1,40 @@
+---
+_disableAffix: true
+---
+<style>
+    .center {
+        text-align: center;
+    }
+
+    .subheader {
+        font-size: 1.5em;
+    }
+</style>
+
+<div class="center">
+    <h1>AutoGen .NET</h1>
+    <p class="subheader">
+    A <i>.NET</i> framework for building AI agents and applications
+    </p>
+</div>
+
+<div class="row">
+  <div class="col-sm-6">
+    <div class="card">
+      <div class="card-body">
+        <h5 class="card-title">Core</h5>
+        <p class="card-text">An event-driven programming framework for building scalable multi-agent AI systems.</p>
+        <a href="core/index.md" class="btn btn-primary">Get started</a>
+      </div>
+    </div>
+  </div>
+  <div class="col-sm-6">
+    <div class="card">
+      <div class="card-body">
+        <h5 class="card-title">AgentChat</h5>
+        <p class="card-text">A programming framework for building conversational single and multi-agent applications. Built on Core.</p>
+        <a href="#" class="btn btn-primary disabled">Coming soon</a>
+      </div>
+    </div>
+  </div>
+</div>

docs/dotnet/template/public/main.css

@@ -0,0 +1,4 @@
+.navbar-brand img {
+    height: 50px;
+    margin-right: 0.5rem;
+}

docs/dotnet/template/public/main.js

@@ -0,0 +1,9 @@
+export default {
+    iconLinks: [
+      {
+        icon: 'github',
+        href: 'https://github.com/microsoft/autogen',
+        title: 'GitHub'
+      }
+    ]
+  }

docs/dotnet/toc.yml

@@ -0,0 +1,8 @@
+- name: Core
+  href: core/
+
+- name: API Reference
+  href: api/
+
+- name: Python⤴
+  href: https://microsoft.github.io/autogen/

docs/dotnet/user-guide/core-user-guide/defining-message-types.md

@@ -1,30 +0,0 @@
-# Defining Message Types
-
-Messages are currently required to be Protocol Buffers. To define them, it is necessary to include the Protocol Buffers compiler, through the `Grpc.Tools` package. In your `.csproj` file, add/edit:
-
-```xml
-    <PackageReference Include="Grpc.Tools" PrivateAssets="All" />
-```
-
-Then create an include a `.proto` file in the project:
-
-```xml
-<ItemGroup>
-  <Protobuf Include="messages.proto" GrpcServices="Client;Server" Link="messages.proto" />
-</ItemGroup>
-```
-
-Then define your messages as specified in the [Protocol Buffers Language Guide](https://protobuf.dev/programming-guides/proto3/)
-
-```proto
-syntax = "proto3";
-
-package HelloAgents;
-
-option csharp_namespace = "AgentsProtocol";
-
-message TextMessage {
-    string Source = 1;
-    string Content = 2;
-}
-```

docs/dotnet/user-guide/core-user-guide/differences-python.md

@@ -1,46 +0,0 @@
-# Differences from Python
-
-## Agents Self-Interact
-
-When an agent sends a message of a type to which it also listens:
-
-```csharp
-[TopicSubscription("default")]
-public class MyAgent(
-    IAgentWorker worker,
-    [FromKeyedServices("EventTypes")] EventTypes typeRegistry
-    ) :
-      Agent(worker, typeRegistry),
-      IHandle<Message>
-{
-  async Task SomeInternalFunctionAsync()
-  {
-    Message m;
-
-    // ...
-
-    await this.PublishMessageAsync(m);
-  }
-
-  public async Task Handle(Message message)
-  {
-    // will receive messages sent by SomeInternalFunctionAsync()
-  }
-}
-```
-
-Tracked by [#4998](https://github.com/microsoft/autogen/issues/4998)
-
-## 'Local' Runtime is Multithreaded
-
-Unlike the `single_threaded_runtime`, the InProcess (`local: true`) runtime for .NET is multi-threaded, so messages will process in arbitrary order across agents. This means that an agent may process messages sent after the termination request has been made unless checking for termination using the `IHostApplicationLifecycle` service.
-
-## No equivalent to 'stop_when_idle()'
-
-Agents need to request termination explicitly, as there is no meaningful 'idle' state.
-
-## All message types need to be Protocol Buffers
-
-See (linkto: defining-message-types.md) for instructions on defining messages
-
-Tracked by [#4695](https://github.com/microsoft/autogen/issues/4695)

docs/dotnet/user-guide/core-user-guide/getting-started.md

@@ -1,143 +0,0 @@
-# Quick Start
-
-Before diving into the core APIs, let’s start with a simple example of two agents that count down from 10 to 1.
-
-We first define the agent classes and their respective procedures for handling messages. We create two agent classes: `Modifier` and `Checker`. The `Modifier` agent modifies a number that is given and the `Check` agent checks the value against a condition. We also define a pair of
-messages in a .proto file which will be generated into the message types that will be passed
-between the agents.
-
-```proto
-syntax = "proto3";
-
-package HelloAgents;
-
-option csharp_namespace = "Microsoft.Autogen.Samples.CountAgent.Protocol";
-
-message CountMessage {
-    int32 Content = 1;
-}
-
-message CountUpdate {
-    int32 NewCount = 1;
-}
-```
-
-We create two messages to ensure we have tick-tock behaviour between the agents; if we used a single type, then both agents would receive the other agents' message as well as self-sent messages. (Note: this is a behaviour difference from Python; Issue#4998)
-
-In the project file, we add
-
-```xml
-<ItemGroup>
-  <PackageReference Include="Grpc.Tools" PrivateAssets="All" />
-</ItemGroup>
-
-<ItemGroup>
-  <Protobuf Include="messages.proto" GrpcServices="Client;Server" Link="messages.proto" />
-</ItemGroup>
-```
-
-This will ensure the message classes are available for our agents to send/receive.
-
-Now we will define the agents:
-
-```csharp
-[TopicSubscription("default")]
-public class Modifier(
-    IAgentWorker worker,
-    [FromKeyedServices("EventTypes")] EventTypes typeRegistry,
-    ModifyF modifyFunc
-    ) :
-        Agent(worker, typeRegistry),
-        IHandle<CountMessage>
-{
-    public async Task Handle(CountMessage item)
-    {
-        // handling code
-    }
-}
-```
-
-The `TopicSubscription` attribute defines the set of topics the agents will listen to. Topics (see here) are useful for separaating different logical chains of agent communications.
-
-The first two parameters to the constructor, `IAgentWorker` and `EventTypes` are automatically made available through dependency injection to the workers. (We do not allow direct construction of workers in Autogen.Core: see here for FAQ), and need to be passed on to the base class.
-
-Other parameters are also made available through dependency injection (see here).
-
-Agents register for messages by implementing the `IHandle<MessageType>` interface:
-
-```csharp
-    public async Task Handle(CountMessage item)
-    {
-            int newValue = modifyFunc(item.Content);
-            Console.WriteLine($"{SEPARATOR_LINE}\nModifier:\nModified {item.Content} to {newValue}");
-
-            CountUpdate updateMessage = new CountUpdate { NewCount = newValue };
-
-            await this.PublishMessageAsync(updateMessage);
-    }
-```
-
-The `Modifier` agent receives a `CountMessage` indicating the current count, modifies it using the injected `ModifyF modifyFunc`, and publishes the `CountUpdate` message.
-
-The `Checker` agent is defines similarly:
-
-```csharp
-[TopicSubscription("default")]
-public class Checker(
-    IAgentWorker worker,
-    [FromKeyedServices("EventTypes")] EventTypes typeRegistry,
-    IHostApplicationLifetime hostApplicationLifetime,
-    TerminationF runUntilFunc
-    ) :
-        Agent(worker, typeRegistry),
-        IHandle<CountUpdate>
-{
-  public Task Handle(CountUpdate item)
-  {
-    if (!runUntilFunc(item.NewCount))
-    {
-        Console.WriteLine($"{SEPARATOR_LINE}\nChecker:\n{item.NewCount} passed the check, continue.");
-        await this.PublishMessageAsync(new CountMessage { Content = item.NewCount });
-    }
-    else
-    {
-        Console.WriteLine($"{SEPARATOR_LINE}\nChecker:\n{item.NewCount} failed the check, stopping.");
-        hostApplicationLifetime.StopApplication();
-    }
-  }
-}
-```
-
-The `Checker` continues the count when `runUntilFunc` has not triggered by publishing a new `CountMessage` with the updated count; if termination is desired, it will request it by calling `hostApplicationLifetime.StopApplication()`.
-
-You might have already noticed, the agents’ logic, whether it is using model or code executor, is completely decoupled from how messages are delivered. This is the core idea: the framework provides a communication infrastructure, and the agents are responsible for their own logic. We call the communication infrastructure an Agent Runtime.
-
-Agent runtime is a key concept of this framework. Besides delivering messages, it also manages agents’ lifecycle. So the creation of agents are handled by the runtime.
-
-The following code shows how to register and run the agents using the local (InProcess) runtime:
-
-```csharp
-// Define the counting logic
-using ModifyF = System.Func<int, int>;
-using TerminationF = System.Func<int, bool>;
-
-ModifyF modifyFunc = (int x) => x - 1;
-TerminationF runUntilFunc = (int x) =>
-{
-    return x <= 1;
-};
-
-// Register the services
-WebApplicationBuilder? builder = WebApplication.CreateBuilder(args);
-builder.Services.AddSingleton(modifyFunc);
-builder.Services.AddSingleton(runUntilFunc);
-
-// Send the initial count to the agents app, running on the `local` runtime, and pass through the registered services via the application `builder`
-var app = await AgentsApp.PublishMessageAsync("default", new CountMessage
-{
-    Content = 10
-}, local: true, builder: builder).ConfigureAwait(false);
-
-// Run until application shutdown
-await app.WaitForShutdownAsync();
-```

docs/dotnet/user-guide/core-user-guide/installation.md

@@ -1,33 +0,0 @@
-# Installation
-
-## Add via `<ProjectReference>`
-
-```
-  <ProjectReference Include="<path>/<to>/Contracts/Microsoft.AutoGen.Contracts.csproj" />
-  <ProjectReference Include="<path>/<to>/Core/Microsoft.AutoGen.Core.csproj" />
-```
-
-<!-- (TODO: Move to bottom) -->
-
-## These will only work after we release the package:
-
-## Install via `.NET cli`
-
-```
-> dotnet add package Microsoft.AutoGen.Contracts --version 0.4.0
-> dotnet add package Microsoft.AutoGen.Core --version 0.4.0
-```
-
-## Install via `Package Manager`
-
-```
-PM> NuGet\Install-Package Microsoft.AutoGen.Contracts -Version 0.4.0
-PM> NuGet\Install-Package Microsoft.AutoGen.Core -Version 0.4.0
-```
-
-## Add via `<PackageReference>`
-
-```
-  <PackageReference Include="Microsoft.AutoGen.Contracts" Version="0.2.1" />
-  <PackageReference Include="Microsoft.AutoGen.Core" Version="0.2.1" />
-```

dotnet/samples/GettingStarted/Checker.cs

@@ -1,12 +1,13 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Checker.cs
 
+#region snippet_Checker
 using Microsoft.AutoGen.Contracts;
 using Microsoft.AutoGen.Core;
 using Microsoft.Extensions.Hosting;
 using TerminationF = System.Func<int, bool>;
 
-namespace Samples;
+namespace GettingStartedSample;
 
 [TypeSubscription("default")]
 public class Checker(
@@ -32,3 +33,4 @@ public class Checker(
         }
     }
 }
+#endregion snippet_Checker

dotnet/samples/GettingStarted/CountMessage.cs

@@ -1,9 +1,11 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // CountMessage.cs
 
-namespace Samples;
+#region snippet_CountMessage
+namespace GettingStartedSample;
 
 public class CountMessage
 {
     public int Content { get; set; }
 }
+#endregion

dotnet/samples/GettingStarted/CountUpdate.cs

@@ -1,9 +1,11 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // CountUpdate.cs
 
-namespace Samples;
+#region snippet_CountUpdate
+namespace GettingStartedSample;
 
 public class CountUpdate
 {
     public int NewCount { get; set; }
 }
+#endregion

dotnet/samples/GettingStarted/Modifier.cs

@@ -1,12 +1,12 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Modifier.cs
-
+#region snippet_Modifier
 using Microsoft.AutoGen.Contracts;
 using Microsoft.AutoGen.Core;
 
 using ModifyF = System.Func<int, int>;
 
-namespace Samples;
+namespace GettingStartedSample;
 
 [TypeSubscription("default")]
 public class Modifier(
@@ -27,3 +27,4 @@ public class Modifier(
         await this.PublishMessageAsync(updateMessage, topic: new TopicId("default"));
     }
 }
+#endregion snippet_Modifier

dotnet/samples/GettingStarted/Program.cs

@@ -1,10 +1,11 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Program.cs
-
+#region snippet_Program
+#region snippet_Program_funcs
+using GettingStartedSample;
 using Microsoft.AutoGen.Contracts;
 using Microsoft.AutoGen.Core;
 using Microsoft.Extensions.DependencyInjection.Extensions;
-using Samples;
 using ModifyF = System.Func<int, int>;
 using TerminationF = System.Func<int, bool>;
 
@@ -13,7 +14,9 @@ TerminationF runUntilFunc = (int x) =>
 {
     return x <= 1;
 };
+#endregion snippet_Program_funcs
 
+#region snippet_Program_builder
 AgentsAppBuilder appBuilder = new AgentsAppBuilder();
 appBuilder.UseInProcessRuntime();
 
@@ -25,7 +28,9 @@ appBuilder.AddAgent<Modifier>("Modifier");
 
 var app = await appBuilder.BuildAsync();
 await app.StartAsync();
+#endregion snippet_Program_builder
 
+#region snippet_Program_publish
 // Send the initial count to the agents app, running on the `local` runtime, and pass through the registered services via the application `builder`
 await app.PublishMessageAsync(new CountMessage
 {
@@ -34,3 +39,5 @@ await app.PublishMessageAsync(new CountMessage
 
 // Run until application shutdown
 await app.WaitForShutdownAsync();
+#endregion snippet_Program_publish
+#endregion snippet_Program