(You’ll find a working demo in C# /.NET at the end)

The problem

In a normal CRUD app, one model does two jobs: it enforces business rules on writes
and gets reshaped for every screen on reads. That’s fine until the jobs fight —
your entity bloats, your queries grow joins, and you can’t make reads faster without
risking writes.

CQRS (Command Query Responsibility Segregation) splits them in two:

The write side owns correctness. The read side owns speed. Domain events
keep them in sync. Reads never touch the write model's joins — they hit pre-shaped
views, so they're trivial and scale on their own.

Two things people get wrong: CQRS is not two databases (that's an option, not
the definition), and adding a message bus is not CQRS. The defining move is
separate read and write models.

The choice that defines everything: when does the read side catch up?

This is where it gets interesting. You decide when the projection runs.

Synchronous — run it inline, before the write returns. Reads are always fresh:

Asynchronous — drop the event on a queue and return instantly; a background
worker projects it later. Fast writes, but the read side serves stale data
until it catches up:

That red window is eventual consistency — the cost of CQRS at scale.

Here's what GET /tickets returns over time after closing a ticket at t=0:

The trade-off, in one table

So when do you actually use CQRS?

Use it when reads and writes genuinely diverge: different shapes, wildly
different load (reads ≫ writes), or a complex domain where query concerns pollute
your business rules. Think product catalogs, social feeds, dashboards, ledgers.

Skip it for simple symmetric CRUD — it’s pure overhead. And if you can’t
tolerate stale reads and can’t design the UX around them, stay synchronous or
stay CRUD.

The mature move isn’t “use CQRS.” It’s knowing that the write side is your truth,
the read side is a rebuildable cache, and choosing how fresh that cache must be —
on purpose.

Demo: https://github.com/kaldren/SystemDesignLab/tree/main/01-CQRS

This repository follows an AI-first approach and is designed to evolve into a platform for learning, experimentation, and technical content creation. The goal is to leverage AI to streamline the development of Proof of Concepts (POCs) while automatically generating supporting artifacts such as documentation, architectural notes, and blog content.

If you prefer video - here’s a quick walkthrough:

Here’s the architecture:

We have 2 executors - one that takes input, and one that aggregates the output, and 3 agents - one that translates text, one that summarizes it, and one that extracts keywords. We are using Microsoft Foundry for LLMs and Aspire Dashboard for local telemetry.

Here’s the code:

// Program.cs

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.Logging;
using OpenTelemetry;
using OpenTelemetry.Logs;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using System.Diagnostics;

/// <summary>
/// Demonstrates a fan-out workflow where a single text document is dispatched
/// in parallel to three specialist agents.
/// </summary>
public static class Program
{
    private const string SourceName = "Workflows.DocumentFanOut";
    private static readonly ActivitySource s_activitySource = new(SourceName);

    private static async Task Main()
    {
        var endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
            ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");

        var deploymentName =
            Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME")
            ?? "gpt-4o-mini";

        var resourceBuilder = ResourceBuilder
            .CreateDefault()
            .AddService(
                serviceName: "DocumentFanOut",
                serviceVersion: "1.0.0");

        using var tracerProvider = Sdk.CreateTracerProviderBuilder()
            .SetResourceBuilder(resourceBuilder)
            .AddSource(SourceName)
            .AddOtlpExporter()
            .Build();

        using var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .SetMinimumLevel(LogLevel.Trace)
                .AddConsole()
                .AddOpenTelemetry(logging =>
                {
                    logging.SetResourceBuilder(resourceBuilder);
                    logging.IncludeFormattedMessage = true;
                    logging.IncludeScopes = true;
                    logging.ParseStateValues = true;

                    logging.AddOtlpExporter();
                });
        });

        var logger = loggerFactory.CreateLogger(SourceName);

#pragma warning disable OPENAI001
        var chatClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
            .GetProjectOpenAIClient()
            .GetProjectResponsesClient()
            .AsIChatClient(deploymentName)
            .AsBuilder()
            .UseOpenTelemetry(
                sourceName: SourceName,
                configure: cfg => cfg.EnableSensitiveData = true)
            .Build();
#pragma warning restore OPENAI001

        using var activity = s_activitySource.StartActivity("main");

        logger.LogInformation(
            "Application started. TraceId: {TraceId}",
            activity?.TraceId);

        var translator = new ChatClientAgent(
            chatClient,
            name: "Translator",
            instructions: "You are a professional translator. Translate the user's document into Spanish. Output only the translated text, no commentary."
        ).BindAsExecutor(new AIAgentHostOptions { ForwardIncomingMessages = false });

        var summarizer = new ChatClientAgent(
            chatClient,
            name: "Summarizer",
            instructions: "You are a concise summarizer. Produce exactly 3 bullet points that capture the key ideas of the document."
        ).BindAsExecutor(new AIAgentHostOptions { ForwardIncomingMessages = false });

        var keywordExtractor = new ChatClientAgent(
            chatClient,
            name: "KeywordExtractor",
            instructions: "You are a keyword-extraction specialist. Return the top 5 most important keywords from the document as a numbered list."
        ).BindAsExecutor(new AIAgentHostOptions { ForwardIncomingMessages = false });

        var documentInput = new DocumentInputExecutor();
        var aggregator = new ResultsAggregatorExecutor();

        var workflow = new WorkflowBuilder(documentInput)
            .AddFanOutEdge(documentInput, [translator, summarizer, keywordExtractor])
            .AddFanInBarrierEdge([translator, summarizer, keywordExtractor], aggregator)
            .WithOutputFrom(aggregator)
            .WithOpenTelemetry(
                configure: cfg => cfg.EnableSensitiveData = true,
                activitySource: s_activitySource)
            .Build();

        const string document = """
            Photosynthesis is the process by which green plants, algae, and some bacteria
            convert light energy into chemical energy stored in glucose. Using sunlight,
            water absorbed from the soil, and carbon dioxide from the air, plants produce
            oxygen as a byproduct. This process occurs primarily in the chloroplasts, where
            the pigment chlorophyll captures light. Photosynthesis is fundamental to life
            on Earth, forming the base of nearly all food chains and maintaining atmospheric
            oxygen levels.
            """;

        Console.WriteLine("=== Input document ===");
        Console.WriteLine(document);
        Console.WriteLine(new string('=', 60));

        logger.LogInformation("Starting fan-out workflow");

        await using StreamingRun run =
            await InProcessExecution.RunStreamingAsync(workflow, input: document);

        await foreach (WorkflowEvent evt in run.WatchStreamAsync())
        {
            switch (evt)
            {
                case WorkflowOutputEvent output:
                    logger.LogInformation(
                        "Workflow completed. Results:{NewLine}{Output}",
                        Environment.NewLine,
                        output.Data);
                    break;

                case WorkflowErrorEvent error:
                    logger.LogError(error.Exception, "Workflow error");
                    break;

                case ExecutorFailedEvent failed:
                    logger.LogError(
                        "Executor '{ExecutorId}' failed: {Data}",
                        failed.ExecutorId,
                        failed.Data);
                    break;
            }
        }

        logger.LogInformation("Application finished");
    }
}

Executors are the fundamental building blocks that process messages in a workflow. They are autonomous processing units that receive typed messages, perform operations, and can produce output messages or events.

// Executors.cs

using System.Text;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;

/// <summary>
/// Receives the raw document string and broadcasts it as a <see cref=”ChatMessage”/>
/// followed by a <see cref=”TurnToken”/> to all downstream agents simultaneously.
/// </summary>
[SendsMessage(typeof(ChatMessage))]
[SendsMessage(typeof(TurnToken))]
internal sealed class DocumentInputExecutor() : Executor<string>(”DocumentInput”)
{
    public override async ValueTask HandleAsync(
        string document,
        IWorkflowContext context,
        CancellationToken cancellationToken = default)
    {
        // Broadcast the document to all fan-out targets.
        await context.SendMessageAsync(new ChatMessage(ChatRole.User, document), cancellationToken: cancellationToken);
        // TurnToken kicks off each receiving agent’s inference turn.
        await context.SendMessageAsync(new TurnToken(emitEvents: false), cancellationToken: cancellationToken);
    }
}

/// <summary>
/// Collects the <see cref=”ChatMessage”/> lists produced by each agent after the
/// fan-in barrier fires, then emits a single formatted string as the workflow output.
/// </summary>
[YieldsOutput(typeof(string))]
internal sealed class ResultsAggregatorExecutor() : Executor<List<ChatMessage>>(”ResultsAggregator”)
{
    private readonly List<ChatMessage> _buffer = [];

    /// <summary>
    /// Each call receives all messages produced by one agent during its turn.
    /// </summary>
    public override ValueTask HandleAsync(
        List<ChatMessage> messages,
        IWorkflowContext context,
        CancellationToken cancellationToken = default)
    {
        _buffer.AddRange(messages);
        return default;
    }

    /// <summary>
    /// Called once all agent replies for this super-step have been delivered.
    /// Formats and yields the combined output.
    /// </summary>
    protected override ValueTask OnMessageDeliveryFinishedAsync(
        IWorkflowContext context,
        CancellationToken cancellationToken = default)
    {
        var sb = new StringBuilder();

        foreach (var msg in _buffer)
        {
            sb.AppendLine($”--- {msg.AuthorName} ---”);
            sb.AppendLine(msg.Text);
            sb.AppendLine();
        }

        _buffer.Clear();

        return context.YieldOutputAsync(sb.ToString(), cancellationToken);
    }
}

Here’s the console output from Aspire:

Here are the traces:

That’s it! For more - read the docs and start experimenting!

Prerequisites:

• Azure Resource Group

• Microsoft Foundry Resource & Project

• Create model for the inference (I used gpt-4o)

• Configure environment variables

• Application Insights Resource

NuGet Packages:

• Azure.AI.Projects.Agents (2.1.0-beta.2)

• Azure.Identity (latest stable)

• Microsoft.Agents.AI.Foundry (1.6.2-preview.260521.1)

• Azure.AI.OpenAI (2.1.0)
  

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI.Foundry;
using OpenAI.Responses;

var endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
var model = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";

const string AgentName = "MicrosoftLearnAgent";
const string AgentInstructions = "You answer questions by searching the Microsoft Learn content only through MCP. If you can't find an answer - just say so! Don't ever use your general knowledge!";

#pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
var mcpTool = ResponseTool.CreateMcpTool(
    serverLabel: "microsoft_learn",
    serverUri: new Uri("https://learn.microsoft.com/api/mcp"),
    toolCallApprovalPolicy: new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.NeverRequireApproval));
#pragma warning restore OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.


var aiProjectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());

var connectionString = aiProjectClient.Telemetry.GetApplicationInsightsConnectionString();
Environment.SetEnvironmentVariable("APPLICATIONINSIGHTS_CONNECTION_STRING", connectionString);

var agentVersion = await aiProjectClient.AgentAdministrationClient.CreateAgentVersionAsync(
    AgentName,
    new ProjectsAgentVersionCreationOptions(
        new DeclarativeAgentDefinition(model)
        {
            Instructions = AgentInstructions,
            Tools = { mcpTool }
        }));

#pragma warning disable OPENAI001
FoundryAgent agent = aiProjectClient.AsAIAgent(agentVersion);
#pragma warning restore OPENAI001

Console.WriteLine(await agent.RunAsync("What are Local MCP Tools"));

… and here’s the telemetry inside AppInsights. As you can see it is executing the mcp tool.

That’s it! Short and sweet!

The question is how well you capture and use that information.

What if every call could be turned into structured data and used by agentic AI systems where agents actively handle tasks, fix issues, and support decision-making?

There are many ways to do it, but here’s a simple architecture on Azure:

𝗜𝗻𝗴𝗲𝘀𝘁𝗶𝗼𝗻 & 𝗣𝗿𝗼𝗰𝗲𝘀𝘀𝗶𝗻𝗴

Audio → Blob → Event Grid → Queue → Worker

𝗨𝗻𝗱𝗲𝗿𝘀𝘁𝗮𝗻𝗱𝗶𝗻𝗴

- Content Understanding (turns audio into structured data)

𝗗𝗮𝘁𝗮 & 𝗥𝗲𝘁𝗿𝗶𝗲𝘃𝗮𝗹

- PostgreSQL (chat history, other structured data)

- Azure AI Search (RAG)

𝗔𝗜

- Microsoft Foundry + LangGraph (multi-agent orchestration)

𝗨𝗜 / 𝗔𝗣𝗜

- Container Apps (exposes the system to users / clients)

Nothing fancy individually, but together, it turns raw calls into something agents can query, analyze, and act on in real workflows.

Full walkthrough + POC app:

Lately, a big part of my job has been figuring out how to leverage AI’s benefits without compromising the overall solution architecture and turning the system into unreliable, hard to maintain mess. Many teams are being pushed to deliver faster using AI, often under tighter deadlines. If this isn’t handled carefully, it can quickly lead to architectural erosion, growing complexity, and systems that you want to stay away from.

Teams are already feeling the impact. When guardrails are missing, structure erodes and boundaries blur. We’re even seeing large systems struggle under constant rushed changes with AI. Frequent Windows update issues are a reminder of how fragile complex software (especially written with AI) can become when complexity grows faster than control.

The challenge isn’t speed versus quality. It’s learning how to move fast without weakening the architecture that keeps the system stable.

In today’s post, I’m focusing specifically on greenfield projects. I’m going to walk through a few practical steps you can follow to ensure AI accelerates your development without slowly destroying your solution and making it unmaintainable.

I will cover brownfield systems separately, because the strategy there is different and deserves its own discussion.

Build Good Architecture from the Start (Greenfield)

If you’re working on a greenfield project, you have a rare advantage as you control the foundation. There’s no legacy, no accidental complexity, no historical shortcuts. That also means the responsibility is entirely yours.

Start with clear understanding of functional and non-functional requirements. Design system boundaries intentionally. Define coding standards, layering rules, and architectural principles before the first large batch of AI-generated code enters the repository.

AI can help you build and move faster but only when you have stable foundations.

In greenfield projects, the discipline you apply at the beginning determines maintainability years later.

We’ve Got the Architecture… Now It’s Time to Protect It

Designing a solid architecture is only the first step. Once development begins and AI starts generating code at scale, protection becomes critical.

Architecture should not live only in your head or in a diagram. It needs to be documented, enforced, and protected with automated checks, review processes, and clear boundaries.

Now let’s see some basic steps that will help us protect the solution from architectural erosion.

Use GitHub Copilot to Protect the Architecture

AI should not only generate code. It should help enforce the architecture you designed. Instead of treating AI as a shortcut to write tons of code, treat it as an extension of your governance model as well.

If you give AI clear rules, boundaries, and responsibilities, it can become part of your quality control system rather than a source of entropy.

A recent 2025 study (https://arxiv.org/pdf/2507.11538) showed that as the number of instructions increases, AI models start missing requirements and skipping constraints. In other words, the more rules you throw at them, the more likely they are to ignore some of them. You should always keep this in mind.

This has direct implications for how we document architecture and even how we use the tools that I am about to show you in a second.

If your repository contains hundreds of loosely structured rules, long narrative explanations, and scattered constraints, the model will not reliably follow all of them. Overloading it with instructions reduces compliance.

That is why architectural guidance for AI must be:

• Short

• Explicit

• Structured

• Prioritized

Concise, well-organized rules outperform long, dense documents. If we want AI to protect the architecture, we must write instructions that it can realistically follow.

Now let’s look at some easy-to-follow steps that will help us protect the architectural integrity of our solution.

Custom Instructions

Start with a copilot-instructions.md file. This document defines your project’s coding standards and architectural rules in a concise format.

Include things like:

• Folder structure expectations

• Layering rules

• Dependency constraints

• Naming conventions

• Required patterns

When Copilot reads this before generating code, it aligns with your architecture instead of inventing its own structure.

Keep it short. If it’s too long, it won’t be followed consistently.

Here’s an example of such a document.

# Project: Protect Arch Demo

This project follows **Clean Architecture** principles. All contributions — human or AI — must respect the layered dependency rules.

## Architecture Layers (innermost → outermost)

1. **Domain** (`src/Domain`) — Entities and repository interfaces. Zero dependencies on other project layers.
2. **Application** (`src/Application`) — Use cases / business logic. Depends only on Domain.
3. **Infrastructure** (`src/Infrastructure`) — Data access, external services. Depends on Domain and Application.
4. **Api** (`src/Api`) — HTTP layer, DI composition root. Depends on Application and Infrastructure.

## Dependency Rules — NEVER violate these

| Layer          | May reference               | Must NEVER reference             |
| -------------- | --------------------------- | -------------------------------- |
| Domain         | (nothing)                   | Application, Infrastructure, Api |
| Application    | Domain                      | Infrastructure, Api              |
| Infrastructure | Domain, Application         | Api                              |
| Api            | Application, Infrastructure | —                                |

## Coding Guidelines

- Use **C# 12** with file-scoped namespaces.
- Keep Domain entities as plain POCOs — no framework dependencies.
- Repository **interfaces** live in `Domain/Interfaces`; **implementations** live in `Infrastructure/Repositories`.
- Use cases live in `Application/UseCases` and accept interfaces via constructor injection.
- The Api project is the only place that configures DI and middleware — never register services elsewhere.
- All new code must pass the architecture tests in `tests/ArchitectureTests` (run with `dotnet test`).

Agent Skills

Agent Skills let you package reusable capabilities, like instructions, scripts, templates, and supporting resources that Copilot can load when needed. Only the skill’s name and description are available by default. The full instructions and resources are loaded on demand, when the task matches the skill’s purpose.

This is critical for two reasons:

1. It keeps context clean and lightweight.

2. It prevents instruction overload, which reduces model reliability.

A skill can encapsulate workflows such as:

• Architecture validation

• Test generation

• Refactoring checks

• Security review

• Deployment validation

Unlike custom instructions, which are always applied and define your structural rules, Agent Skills are task-specific. They activate only when relevant.

Here’s an example of a skill for clean architecture review:

---
name: clean-architecture-review
description: 'Reviews .NET code for Clean Architecture dependency violations. Use when reviewing code changes, pull requests, or validating that new code respects layer boundaries in a Clean Architecture project.'
---

# Clean Architecture Review

You are a specialist in Clean Architecture for .NET projects. When this skill is activated, perform a thorough review of the code for dependency rule violations.

## Architecture Layers

The project uses four layers (innermost → outermost):

1. **Domain** (`src/Domain`) — Entities, value objects, repository interfaces. **Zero** dependencies on other layers.
2. **Application** (`src/Application`) — Use cases and business logic. Depends only on Domain.
3. **Infrastructure** (`src/Infrastructure`) — Data access, external services. Depends on Domain and Application.
4. **Api** (`src/Api`) — HTTP endpoints, DI composition root. Depends on Application and Infrastructure.

## Review Checklist

For each source file, check the following:

### 1. Layer Identification

Determine which layer a file belongs to based on its path prefix:

- `src/Domain/` → Domain
- `src/Application/` → Application
- `src/Infrastructure/` → Infrastructure
- `src/Api/` → Api

### 2. Forbidden Dependencies

Check all `using` directives and type references:

| Layer          | Forbidden Dependencies           |
| -------------- | -------------------------------- |
| Domain         | Application, Infrastructure, Api |
| Application    | Infrastructure, Api              |
| Infrastructure | Api                              |
| Api            | (no restrictions)                |

### 3. Structural Rules

- Interfaces in `Domain/Interfaces/` must **only** be interfaces
- Repository implementations must live in `Infrastructure/Repositories/`
- Use cases must live in `Application/UseCases/`
- DI registration must only happen in `src/Api/Program.cs`

## How to Run Verification

Use the [architecture test script](./run-arch-tests.ps1) to execute automated verification:

```powershell
.\run-arch-tests.ps1
```

Or run directly:

```
dotnet test tests/ArchitectureTests --verbosity normal
```

## Output Format

Report findings as:

```
✅ PASS — No architecture violations found
```

or

```
❌ VIOLATION in [file path]
   Layer: [layer name]
   References: [forbidden namespace]
   Rule: [which rule is broken]
   Fix: [how to fix it]
```

Custom Agents

Custom agents let you define AI roles with clear responsibilities.

Instead of one generic assistant, you can create:

• A Developer Agent

• An Architecture Review Agent

• A Testing Agent

• A Documentation Agent

You can generate code with one agent and hand it off to another for validation.

That handoff mirrors real engineering teams. Responsibilities are separated. Validation is intentional. AI becomes structured, not improvisational.

Here’s an example of an Architecture Guardian agent:

---
name: arch-guardian
description: 'Architecture Guardian — reviews code for Clean Architecture violations'
tools:
  - search
  - read/readFile
---

# Architecture Guardian

You are the **Architecture Guardian** for this project. Your sole purpose is to protect the Clean Architecture boundaries.

## Your Personality

You are a vigilant castle guard. The architecture is your castle, and each layer is a wall. You never let a dependency sneak through the wrong gate.

## What You Do

When asked to review code or validate the architecture:

1. **Identify the layer** each file belongs to based on its path:
   - `src/Domain/` → Domain layer
   - `src/Application/` → Application layer
   - `src/Infrastructure/` → Infrastructure layer
   - `src/Api/` → Api layer

2. **Check `using` statements and references** for forbidden dependencies:
   - Domain → must NOT reference Application, Infrastructure, or Api
   - Application → must NOT reference Infrastructure or Api
   - Infrastructure → must NOT reference Api

3. **Check structural rules**:
   - Interfaces in `Domain/Interfaces/` must be interfaces (not classes)
   - Repository implementations must live in `Infrastructure/Repositories/`
   - Use cases must live in `Application/UseCases/`
   - DI registration must only happen in `src/Api/`

4. **Run the architecture tests** to confirm:

   ```
   dotnet test tests/ArchitectureTests --verbosity normal
   ```

5. **Report findings** clearly — list each violation with the file, line, and which rule was broken.

## Important

- NEVER suggest code that violates these rules.
- If asked to write code, always place it in the correct layer.
- If you find violations, provide corrected code that moves the logic to the proper layer.

Hooks (Preview)

Hooks allow you to execute custom logic automatically when specific events occur during AI-assisted workflows. This feature is currently in preview, but it introduces an important architectural capability.

Instead of relying only on instructions, you can attach enforcement mechanisms to lifecycle events inside the development flow.

Hooks can trigger scripts or commands at defined moments — for example before or after AI generates code.

You can use hooks to:

• Validate that required architectural patterns are present after generation

• Run boundary-check scripts when a new file is created

• Enforce dependency direction rules automatically

• Trigger linting or architectural validation commands

• Block unsafe patterns before changes are finalized

Hooks turn architecture from documentation into execution.

Instead of trusting that AI follows your rules, you verify compliance programmatically.

Even though the feature is still in preview, it represents a major step toward embedding architectural governance directly into AI-assisted development workflows.

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "bash .github/hooks/scripts/arch-test.sh",
        "windows": "powershell -ExecutionPolicy Bypass -File .github/hooks/scripts/arch-test.ps1",
        "timeout": 60
      }
    ]
  }
}

#!/usr/bin/env pwsh
# PostToolUse hook — runs architecture tests after Copilot edits files
# Only triggers when the tool is "editFiles" (i.e. Copilot wrote code)

$input_json = [Console]::In.ReadToEnd() | ConvertFrom-Json

$tool = $input_json.tool_name

# Only run after file-editing tools
if ($tool -notin @("editFiles", "create_file", "replace_string_in_file", "write_to_file", "insert_edit")) {
    # Not a file edit — skip silently
    @{ continue = $true } | ConvertTo-Json
    exit 0
}

# Run architecture tests
$testResult = dotnet test tests/ArchitectureTests --no-restore --verbosity quiet 2>&1

if ($LASTEXITCODE -ne 0) {
    $output = @{
        continue           = $true
        hookSpecificOutput = @{
            hookEventName     = "PostToolUse"
            additionalContext = "ARCHITECTURE VIOLATION DETECTED! The architecture tests failed after your edit. Please review and fix the dependency rule violation. Test output: $($testResult -join "`n")"
        }
    }
    $output | ConvertTo-Json -Depth 3
    exit 0
}

@{ continue = $true } | ConvertTo-Json
exit 0

GitHub Copilot Code Review Agent

Generating code is only half of the equation. The real protection happens during review.

GitHub Copilot’s code review agent brings AI into the pull request workflow. Instead of using AI only at the moment of creation, you can use it as an automated reviewer that analyzes changes before they reach your main branch.

From an architectural perspective, this is critical.

The review agent can:

• Detect violations of architectural boundaries

• Flag missing required patterns

• Identify risky dependency changes

• Suggest improvements aligned with project conventions

• Surface potential security or maintainability issues

This transforms AI from a code accelerator into a quality gate participant.

When combined with branch protection rules and required status checks, the Copilot review agent becomes part of your governance layer. Every pull request passes through automated architectural scrutiny before human approval.

This mirrors how mature engineering organizations operate:

• Developer writes code

• Automated systems validate it

• Reviewers enforce standards

• Only then does it reach production

In a greenfield project, integrating AI into the review stage is one of the most effective ways to prevent architectural erosion while still benefiting from rapid generation.

AI-Governed Systems in 2026 and Onward

This is what a modern solution should start to look like.

Not just src and tests, but explicit architectural guardrails built into the repository itself. Dedicated folders for agents, skills, hooks, prompts, and enforcement scripts. Architecture is not something we design at the beginning and then forget — it needs mechanisms that continuously enforce boundaries as the system evolves. And what better way to achieve that than a well-structured AI governance process with a human in the loop?

Final Thoughts

None of the steps discussed here are complex or exotic. They are practical, easy to follow, and accessible to any team starting a greenfield project.

• Define your architecture clearly in the beginning.

• Document it concisely.

• Use custom instructions to encode your standards.

• Leverage Agent Skills and Custom Agents to structure AI behavior.

• Add hooks to automatically validate architectural rules when different AI agent events occur.

• Enforce everything through pull requests, automated tests, and quality gates.

If a team wants to move fast with AI while still building a system that remains understandable, maintainable, and scalable years from now, these steps are a great starting point.

DNS Lookup

Domain names exist so humans can remember websites more easily. It’s much easier to remember chat.com than 104.18.41.60, right? But since every computer on the internet communicates using IP addresses, we need a way to translate a domain name into an IP address. That’s where DNS comes in.

Your browser first asks a simple question:
“What’s the IP address of chat.com?”

It checks caches (browser, OS, router, ISP).

If there’s no cached answer, it queries DNS by traversing the DNS hierarchy: first the root servers, then the top-level domain servers (.com), and finally the authoritative name server, which contains the IP address for chat.com.

This IP is Anycast, meaning the same IP is advertised from many locations globally.

What is Anycast?

Anycast is a network addressing and routing method in which incoming requests can be routed to multiple different locations, or “nodes.” With Anycast, the same IP address is advertised from servers in multiple geographic locations. This approach is commonly used by CDNs, such as Cloudflare, and provides benefits related to security, reliability, and performance.

For example, a hacker performing a DDoS attack would require significantly more resources to have a meaningful impact, because the traffic is distributed across many servers and locations rather than concentrated on a single endpoint (Unicast).

And of course, another benefit of CDNs in general is also enabled by Anycast. You are routed as close as possible to resources such as images, videos, and text. Basically, Anycast routes your traffic (via BGP, as explained later) to the nearest server that can handle your request. So, if you open chat.com, you will hit a server that is closest to you and therefore experience lower latency and overall good performance. For example, if you are in France, your request will not be routed to the US, but rather to a nearby location, such as Paris.

So, at the end of the DNS lookup process, we get an IP address such as 104.18.41.60, which belongs to Cloudflare, and not directly to OpenAI (ChatGPT).

Border Gateway Protocol (BGP)

BGP is the routing protocol of the internet. A hero almost no one talks about, yet it is the protocol that keeps the internet reliable by selecting paths between networks based on routing policies. To better understand how this works, let’s briefly talk about autonomous systems.

Autonomous systems

The internet is a network of hundreds of thousands of smaller networks called autonomous systems (ASes), each operated by a single organization (e.g., Cloudflare) and consisting of its own set of routers.

Basically, what BGP does is select a route from source to destination based on routing policies between autonomous systems, rather than simply choosing the path with the fewest hops. In practice, these policies can include factors such as business relationships, costs, and traffic agreements between ASes. But at a high level, the idea is simple: BGP determines how traffic moves between networks on the internet.

TCP

Once we have the source IP, destination IP, and port (443 in our case, because that’s what TLS uses), we are ready to start a TCP connection. This is handled underneath by the operating system (OS). The OS creates a TCP connection by adding the required headers—such as source IP, destination IP, and ports—and sending the packets over the network.

The process is a three-step procedure (commonly called the three-way handshake), where the client and the server acknowledge each other and establish an ongoing connection between them.

TLS

Since we don’t want our chat messages to be visible to third parties, we establish an encrypted channel over TCP. This is done using TLS, which relies on symmetric encryption algorithms such as AES to encrypt all data exchanged between the client and the server, including the chat messages. This works by negotiating a symmetric session key that is then used by both parties for encryption and decryption.

HTTP

Now that we have a secure (TLS) and ongoing (TCP) session, we are ready to start communicating with ChatGPT. To do that, we rely on the HTTP protocol. Since we want to load the ChatGPT page in our browser, we first send an HTTP GET request to chat.com.

All of this communication is encrypted using the negotiated symmetric key, and the request is sent not directly to ChatGPT’s infrastructure, but to Cloudflare, because Cloudflare sits in front of ChatGPT to protect its infrastructure, provide CDN capabilities, and handle traffic at the edge for the duration of the session. Remember, you never communicate directly with ChatGPT’s web servers.

Once the request is received and validated, it is forwarded to one of ChatGPT’s many web servers, which processes it. The web server then returns the website resources—such as HTML, CSS, JavaScript, and images—to Cloudflare’s servers, which in turn send the response back to your browser.

Browser

When the browser receives the response from Cloudflare, it parses the HTML, CSS, and JavaScript files and builds the DOM. The final step is rendering the page, where the browser renders the visual elements—that’s how you see ChatGPT in your browser.

Thank you

Now you know what happens when you open ChatGPT in your browser and all the steps that take place in milliseconds, almost like magic. If you found this post useful, please subscribe and share it with others.

THE BASICS…

Let’s start with the basics. A typical architecture usually has a Client for the user interface (UI), a Server for the business logic, and a Database to store state.

This is an architecture we still see today, and it was predominant in the early days of the internet. However, it has a major flaw — it lacks mechanisms that improve security and availability.

Since there’s nothing in front of your web server to protect it, your web server is publicly visible and an easy target for all kinds of attacks, most notably distributed denial-of-service (DDoS) attacks.

Another major issue is the lack of availability. What happens, for example, if your single web server goes down? Your clients won’t be happy, and your business might be at risk.

Of course, whether the lack of availability mechanisms is an issue or not depends entirely on the type of application you have. If this is just a simple web app containing your CV, for example, then this is okay. If this is banking software or a medical system, it is not.

Security, on the other hand, should never be a compromise when your system is exposed to the internet. Yes, a hacked banking system is far more damaging than someone hacking your CV website, but even a personal attack can affect you, your finances, and your reputation.

Let’s now fix these issues.

MEET THE REVERSE PROXY

There’s one service that helps mitigate the flaws of the architecture described above. Some call it a reverse proxy, others a load balancer or gateway. And while they are not always the same thing, they usually solve overlapping problems.

That’s it. One service that will improve your security tremendously and help you reach higher availability. But wait a minute, we now have two web servers, instead of one. Yes, that’s because we do want to utilize the load balancing feature of our reverse proxy.

Now, unlike in the first example above, if and when your server goes down, for example Server A, all the traffic will be automatically redirected to Server B. And just like that your business will no longer suffer and thus you’ve improved your overall availability.

And now you have protection from attacks, load balancing, caching, and TLS/SSL termination—features that usually come built in with these services in the cloud.

Internet Routing

And finally, I’m going to spend just a short amount of time on internet routing and try to answer the question of how a request reaches your load balancer in the first place.

Many people think it’s all thanks to the Domain Name System (DNS), and while the DNS is extremely important part, there’s another protocol, without which the internet simply won’t work and that’s the Border Gateway Protocol which basically finds the best route for your request based on latency, cost, geographic location, and others.

What we call “the internet” is a network of many large networks connected together, called autonomous systems. An autonomous system (AS) is a large network—or a group of networks—operated under a single routing policy, and every device connected to the internet ultimately connects through one of these systems.

Each autonomous system uses BGP to announce which IP address ranges it is responsible for and which other autonomous systems it connects to. BGP routers collect this information from ASes around the world and build routing tables that determine how traffic should flow from one AS to another. When a packet arrives, a router consults its routing table to decide which AS the packet should be forwarded to next.

Because there are so many autonomous systems globally, BGP routers constantly update their routing tables. As networks go offline, new networks come online, or ASes change the IP ranges they advertise, these changes are propagated via BGP so routers can continuously adjust their routing decisions.

I simplified the diagram above, but if you’ve read this far, I hope you now have a better idea of what happens when you visit a website—or your own app—and how and why it all happens so fast. I’m definitely going to make a video and a blog post on BGP and how it works, and I’ll write about it here as well, so I’ll keep you posted.

Thank you for reading this.

Each one of the microservice has its own SQL database (except for Cart, which uses Redis), all of which containerized. The idea of my experiment was to see how easy it really makes the life of a developer that’s been assigned to work on a distributed system with lots of moving parts.

Here’s what the solution structure looks like.

And here’s the architecture diagram that represents the action flow.

The flow starts with the user paying for the items they have in their shopping cart (Redis). Once the payment goes through, a call to Order microservice creates a new order with all the required information. Once the new order is created in the database the service pushes a new OrderCreated event to notify the whole system. Now, this is just a quick and dirty. In a real scenario we should consider something like The Saga Pattern to ensure that we don’t leave our system in a corrupt state (e.g., the insert in the order database failed, but we pushed an event for the new order)

To implement the event-based communication flow I used a library called NServiceBus. It is a paid solution, but available for free as long as your solution is not reaching a production environment (e.g., free for Dev, Test, QA, UAT).

Now, what exactly is Aspire?

Think of Aspire as a production-ready platform (from Microsoft) that allows you to build, test, deploy, debug, and run distributed applications. It provides built-in tooling for local development, containerization, orchestration, and observability, making it much easier to work with distributed systems.

Aspire really makes things so much easier. For example, see how easily I’ve added RabbitMQ as a messaging broker to my solution.

// RabbitMQ
var messaging = builder
    .AddRabbitMQ("messaging")
    .WithManagementPlugin(15672)
    .WithLifetime(ContainerLifetime.Persistent);

Here’s my SQL database.

// SQL Server
var sql = builder
    .AddSqlServer("sql")
    .WithLifetime(ContainerLifetime.Persistent);

And that’s my Redis cache.

// Redis
var cartcache = builder.AddRedis("cartcache")
    .WithLifetime(ContainerLifetime.Persistent);

And this is how I’m creating the Orders microservice, its own SQL database, and then injecting the RabbitMQ messaging that we declared above to be used in it for event-based communication.

// Catalog
var catalogDb = sql.AddDatabase("CatalogDb", "eCommerceDemo.Catalog");
var catalog = builder.AddProject<Projects.eCommerceDemo_Catalog>("catalog")
    .WithReference(catalogDb)
    .WaitFor(catalogDb)
    .WithReference(messaging)
    .WaitFor(messaging);

Tell me that isn’t easy!

If you’re curious about how this looks in action you should check my latest video where I give a detailed walkthrough. You’ll see how a single order creation triggers other services and we’ll even send an email.

If your app only needs server-to-browser notifications, then you really don’t need the heavy SignalR and all the packages, rules and protocols it comes with. You need Server-Sent events, and in .NET 10 they are extremely easy to implement.

In today’s blog post I’m going to show you how you can get started.

Today’s demo shows how to build real-time UI updates in .NET 10 without SignalR, using plain Server-Sent Events. An Azure Function simulates a weather sensor writing data to the database, while a Minimal API streams the updates live to a Blazor WASM frontend.

The solution consists of three projects:

• Blazor WASM (for UI)

• .NET 10 Web API (for SSE)

• .NET 10 Function App (for updating SQL database with fictious weather data)

• SQL Database (for storing sensor / weather data)

Required packages (for database manipulation):

• Microsoft.EntityFrameworkCore

• Microsoft.EntityFrameworkCore.SqlServer

I’m only going to share core code snippets here. See the full solution on GitHub here.

Database

Our database has only one table called WeatherForecasts with basic structure (Id for PK, CapturedAt, TemperatureC and Summary)

Function App (SSE.WeatherSensor)

Our Function App runs every 10 seconds and inserts weather data into the database, simulating a live sensor.

Here’s what the table looks like after it’s populated with weather data generated by the Function App.

API (SSE.API)

This is the API endpoint that implements SSE. It polls the database every 5 seconds and streams the latest weather data to connected clients (our Blazor WASM).

app.MapGet("api/weatherforecast", (HttpContext context, SSEDbContext dbContext) =>
{

    async IAsyncEnumerable<WeatherForecast> GetWeatherForecastStream([EnumeratorCancellation] CancellationToken cancellationToken)
    {
        while (!cancellationToken.IsCancellationRequested)
        {
            var latestForecast = await dbContext.WeatherForecasts
                .OrderByDescending(wf => wf.CapturedAt)
                .FirstOrDefaultAsync(cancellationToken);

            if (latestForecast != null)
            {
                yield return latestForecast;
            }

            await Task.Delay(5000, cancellationToken);
        }
    }

    if (context.Request.Headers["Accept"] == "text/event-stream")
    {
        return Results.ServerSentEvents(GetWeatherForecastStream(context.RequestAborted));
    }
    else
    {
        return Results.BadRequest("Unsupported Accept header. Use 'text/event-stream'.");
    }
});

UI (SSE.Web)

This is our client app that subscribes to the SSE endpoint and renders the live weather updates in real time.

@page "/weather"
@using System.Net.ServerSentEvents
@using System.Text.Json
@using Microsoft.AspNetCore.Components.WebAssembly.Http
@inject HttpClient Http

<h3>Live Weather Sensor Feed</h3>

@if (forecast == null && string.IsNullOrEmpty(errorMessage))
{
    <p><em>Waiting for sensor data...</em></p>
}
else {
    <table class="table">
        <thead>
            <tr>
                <th>Time (Local)</th>
                <th>Temp (C)</th>
                <th>Summary</th>
            </tr>
        </thead>
        <tbody>

            <tr style="border: 2px solid black;">
                <td>@forecast.CapturedAt.ToLocalTime().ToString("HH:mm:ss")</td>
                <td>@forecast.TemperatureC°C</td>
                <td>@forecast.Summary</td>
            </tr>
        </tbody>
    </table>
}


@if (!string.IsNullOrEmpty(errorMessage))
{
    <div class="alert alert-danger">@errorMessage</div>
}

@code {
    private WeatherForecast forecast;
    private string? errorMessage;

    public class WeatherForecast
    {
        public int Id { get; set; }
        public DateTimeOffset CapturedAt { get; set; }
        public int TemperatureC { get; set; }
        public string? Summary { get; set; }
    }

    protected override async Task OnInitializedAsync()
    {
        try
        {
            using var request = new HttpRequestMessage(HttpMethod.Get, "https://localhost:7194/api/weatherforecast");
            request.Headers.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("text/event-stream"));

            using var response = await Http.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);
            using var stream = await response.Content.ReadAsStreamAsync();

            var options = new JsonSerializerOptions { PropertyNameCaseInsensitive = true };
            var parser = SseParser.Create(stream, (type, data) =>
                JsonSerializer.Deserialize<WeatherForecast>(data, options));

            await foreach (var item in parser.EnumerateAsync())
            {
                if (item.Data is not null)
                {
                    forecast = item.Data;

                    await InvokeAsync(StateHasChanged);
                }
            }
        }
        catch (Exception ex)
        {
            errorMessage = $"Connection lost: {ex.Message}";
            await InvokeAsync(StateHasChanged);
        }
    }
}

Demo

Here’s the whole solution in action.

TL;DR: If your use case is server-to-browser real-time updates only, you probably don’t need SignalR — SSE is simpler, cheaper, and easier to maintain. Make sure to consider it for your next project.

What is a Modular Monolith?

A Modular Monolith is a software architecture that runs as a single process, just like a traditional monolith. The difference is that instead of one large, tangled codebase, the application is explicitly split into well-defined modules.

Each module represents a separate domain and owns its own logic. The boundaries are clear, enforced in code, and intentional — not just folders pretending to be architecture, but separate class libraries.

What is a Module?

A module is a self-contained logical unit that represents a specific business capability (for example, Payments or Reviews). Its sole purpose is to model that specific business domain — exactly how you would design a microservice.

Each module behaves like a separate application focused on a single business use case. It has its own API layer and its own data store (a separate schema or even a separate database). In other words, it’s an independent application that happens to live inside the monolith, and it communicates with other modules only through its public API.

And this is the key point: even though all modules run inside a single process, they are designed so that, if needed, they can later be extracted into independent microservices with minimal friction.

Here’s how a typical module looks like.

Each module exposes its own public API, and that is the only way other modules are allowed to access its logic. This is extremely important because it enforces loose coupling, making modules easier to extract later — which is at the core of the Modular Monolith’s benefits.

In addition, every module owns its own data store — either a separate schema within a shared database or a completely separate database. Data ownership is strict and enforced at the module boundary.

In short, think of each module as an independent API that just happens to live inside the same application.

Why use Modular Monolith?

A Modular Monolith is powerful because it lets you start simple, while still enforcing clear boundaries that allow the system to scale later if — and only if — it actually becomes necessary.

You get the simplicity of a monolith today, but by designing proper modules, you’re deliberately preparing for a future where parts of the system may need to be distributed into microservices. If that time comes, the transition is far less painful than trying to break apart a traditional, tightly coupled monolith.

Yes, you can start directly with a microservices architecture. But in most cases, that’s a bad idea, even when you’re convinced you’ll eventually need it (this is exactly what Monolith First by Martin Fowler argues).

By building a Modular Monolith, you get several concrete benefits that help you ship faster and at lower cost — which, in today’s enterprise world, is non-negotiable (everyone wants it yesterday):

• Easy to start with — it’s still a monolith

• Simple CI/CD — a single deployable unit

• Clear boundaries — making future migration to microservices significantly easier

• Easier to scale when needed — both technically and organizationally

• Better maintainability and team ownership — teams work on modules without stepping on each other

Real Estate Platform

Let’s take a fictional real estate platform as an example — a place where people list their homes for others to buy. In this scenario, a Modular Monolith solution could look like this.

At this point, it’s important to understand what this diagram does not represent.

This is not a microservices architecture. All modules run inside a single process, are deployed together, and share the same runtime. There is no network communication between them, no service discovery, no distributed tracing, and no operational overhead.

Yet, from a design perspective, each module behaves as if it were a microservice.

Each module:

• Owns its business logic

• Exposes a public API

• Owns its data

• Has no direct access to other modules’ internals or databases

This is what gives the Modular Monolith its power: strong boundaries without distribution.

Module-to-Module Communication

So how do modules talk to each other? Let’s take Listings and Reviews as an example.

Imagine we’re building a page that needs to display a specific listing (for example, a house on XYZ Street) along with all the reviews people have left for it.

The Listings module should not reach directly into the Reviews database, and the Reviews module should not query Listings data directly. Instead, communication happens strictly through each module’s public API.

The application first calls the Listings module to fetch the listing data by listingId. Then, using the same identifier, it calls the Reviews module through its public API to retrieve all reviews associated with that listing.

Both modules:

• Access only their own database

• Expose explicit read models through their APIs

• Remain completely unaware of each other’s internal implementation

Even though these calls happen inside the same process, they are treated exactly like service-to-service calls. No shared repositories. No cross-module ORM access.

This discipline is what keeps the system modular.

If, at some point, the Reviews module needs to be extracted into a separate microservice, this flow remains largely unchanged — the in-process API call simply becomes a network call. The contract stays the same.

This is the core idea behind Modular Monolith communication: design for distribution, without paying the distribution cost upfront.

Modular Monolith Solution

To make this concrete, here’s how this looks in a real codebase.

The solution is structured around a Modules folders, where each module represents a distinct business capability — Accounts, Listings, Reviews, and so on.

Each module is fully self-contained and separate class library that follows the same internal structure built around Clean Architecture:

• API — the module’s public surface, exposed to other modules

• Application — use cases, orchestration, and business workflows

• Domain — core business logic and domain models

• Infrastructure — data access, external integrations, persistence

This is not accidental. Every module is treated as a mini application with clear ownership and explicit boundaries.

The Shared projects contain only truly cross-cutting concerns — things like the database abstraction, shared kernel primitives, or mediator implementation (a custom one I built since MediatR is now commercial). There is no shared business logic between modules.

At the top level, there’s a single API host that wires everything together and a single Web UI consuming the system — reinforcing the fact that this is still a single deployable unit, running in a single process.

This structure enforces discipline:

• Modules don’t reach into each other’s internals

• Data access stays inside module boundaries

• Communication happens only through public APIs

And most importantly, if one of these modules ever needs to become a standalone microservice, most of the work is already done — the boundaries, contracts, and responsibilities are already in place.

That’s the real power of a Modular Monolith: microservice-level design, without microservice-level complexity.

Lastly, let’s take a deeper look at one of the modules — the Listings module.

At first glance, you’ll notice that the module follows the same internal structure as the others: API, Application, Domain, and Infrastructure. This is intentional and consistent across all modules, reinforcing clear boundaries and ownership.

API

The API project is the module’s public entry point. It exposes endpoints (for example, ListingsEndpoints.cs) and defines how the outside world — including other modules — can interact with Listings. Nothing outside the module talks directly to its internals.

Application

The Application layer contains the use cases and orchestration logic. This is where the module’s behavior lives — not in controllers, not in infrastructure.

The important part here is the Features folder.

Each feature (like CreateListing, GetListingById, or GetUserListings) is implemented as a vertical slice — meaning everything related to that use case lives together. This follows Jimmy Bogard’s Vertical Slice Architecture.

Instead of grouping code by technical concerns (controllers, services, handlers), we group it by business intent.

Each feature typically contains:

• The request/command

• The handler

• Validation

• Any feature-specific logic

This makes features easy to understand, easy to modify, and easy to delete.

Domain

The Domain project contains the core business logic:

• Entities

• Value Objects

• Domain Events

This layer is pure business logic. It has no dependencies on infrastructure, frameworks, or external concerns. It represents the heart of the Listings domain.

Infrastructure

The Infrastructure project handles everything related to persistence and external systems — for example, database access and ORM configuration. This is the only place where the module touches technical details like EF Core.

Why this works so well

This combination — Modular Monolith + Clean boundaries + Vertical Slice Architecture — gives you:

• Strong separation between business domains

• Highly focused, readable features

• Minimal coupling between modules

• A structure that scales without becoming unmanageable

Each module is cohesive. Each feature is explicit. And the entire system remains a single, simple deployable unit.

Final Words

I hope this post helps you appreciate the Modular Monolith approach — and gives you a clear idea of how to build one.

I strongly believe you should always start small and avoid overengineering. Every large company started small, and they only scaled when it became necessary. Don’t start with expensive decisions. Build iteratively.

Don’t begin with the idea of building the next Netflix. Start with a basic streaming app, then add one feature, then another — but keep it simple. Once you see real demand, then you can justify adding complexity. Not before.

This is exactly why Modular Monolith fits my mindset so well. It keeps you on the right track: a single-process application, built with clear module boundaries around real business capabilities. And if your product succeeds and you truly need to scale out, you can evolve the right modules into microservices with far less pain.

And now we have Microsoft Agent Framework, which, according to Microsoft is… the best agentic framework that combines the strengths of Semantic Kernel and AutoGen.

I’ve heard that before. But as techies and architects, we need to be aware of what’s coming so we can prepare and make informed decisions about solutions at work.

In my newest YouTube video, I show a quick demo where we use the Microsoft Agent Framework and the A2A protocol to enable communication between agents, using tools to persist state in Cosmos DB.

Who knows if this is really the path forward for Microsoft? At the very least, it’s fun—and since it’s Sunday, why not give it a try?

It’s a lightweight local web app that looks like ChatGPT, but instead of relying on a single model, it lets multiple LLMs answer your question, critique each other, and then produce a final, consolidated result.

Here’s the core idea, quoting the repo:

Instead of asking a question to your favorite LLM provider (OpenAI GPT-5.1, Google Gemini, Anthropic Claude, xAI Grok, etc.), you can group them into your “LLM Council”.

Your query is sent to all of them through OpenRouter, they each give an answer, they review and rank each other’s work, and finally a Chairman LLM produces the final response.

And honestly — it’s brilliant.

Why This Is Cool

When you ask a single LLM a question, you’re trusting one model’s reasoning, training data, biases, and blind spots.

With LLM Council, a few things change:

• Multiple models answer the same question independently.

• They then evaluate each other’s responses.

• The system picks a “Chairman LLM” (you choose which) to read all answers and critiques, and then write a final, improved response.

It’s like having a panel of experts debate the prompt before speaking to you.

Why This is Cool?

LLMs behave differently:

• Some are great with code (Claude).

• Some are great coders and overall thinkers (GPT-5.1).

• Some are creative and fast (Gemini).

• Some are cheap and fast (Mixtral, Qwen, etc.).

Instead of guessing which one is best for each prompt, LLM Council lets them collaborate.

As models become more specialized, this “debate → critique → consolidate” pattern becomes extremely powerful.

It’s basically a tiny research lab running on your laptop.

Trying It Out

The repo is simple to clone and run. Basically, you just follow the README and you’re done. You’ll need an OpenRouter API key — everything else works out of the box.

Demo

Running It on Windows

If you’re on Windows, there’s one extra step: the repo uses a start.sh shell script.
Windows doesn’t run .sh files natively, so you need a shell environment.

I used Git Bash (included with Git for Windows) to run the script:

Mac and Linux users don’t need this — both platforms support shell scripts out of the box.

Here’s a quick demo of how this works with a prompt “How to become a great solution architect? I want to be able to build systems like Netflix and Uber.”

That’s why in today’s post, I’ll walk you through how I managed to make it work and, hopefully, help you apply it in your own projects.

The API

First, here’s how my API looks. It receives the file from Copilot Studio, performs basic validation, and uploads it to a storage account.

    [HttpPost(”upload”)]
    public async Task<IActionResult> Upload([FromBody] UploadFileRequest request)
    {
        if (string.IsNullOrWhiteSpace(request.ContentBytes))
            return BadRequest(”contentBytes is missing”);

        if (string.IsNullOrWhiteSpace(request.Name))
            return BadRequest(”name is missing”);

        // Handle possible data:image/png;base64,...
        var base64 = request.ContentBytes.Contains(’,’)
            ? request.ContentBytes.Split(’,’).Last()
            : request.ContentBytes;

        byte[] fileBytes;

        try
        {
            fileBytes = Convert.FromBase64String(base64);
        }
        catch
        {
            return BadRequest(”Invalid base64 content”);
        }

        var container = _blobServiceClient.GetBlobContainerClient(”uploadedfiles”);
        await container.CreateIfNotExistsAsync();

        var blob = container.GetBlobClient(request.Name);

        using var stream = new MemoryStream(fileBytes);
        await blob.UploadAsync(stream, overwrite: true);

        return Ok(new
        {
            FileName = request.Name,
            Size = fileBytes.Length,
            Status = “Uploaded”
        });
    }
}

Here’s my UploadFileRequest request model. This is the format I am sending from Copilot Studio, so it needs strictly match it.

public class UploadFileRequest
{
    public string ContentBytes { get; set; } = string.Empty;
    public string Name { get; set; } = string.Empty;
}

Copilot Studio Flow

Next, I created a flow for the whole file upload process. The flow expects a file, then it runs an HTTP post against my API, attaching the file content and the file name.

contentBytes: triggerBody()?[’file’][’content’]

To add it, use the F(x) icon on the right.

Then add it here and save it.

Do the same for the name below.

name: triggerBody()?[’file’]?[’name’]

In the end, I added a condition that checks the response from the file upload. If it returns 200, it uses the Respond to agent action to confirm the file was uploaded successfully. Otherwise, it uses the same action to indicate that the upload failed.

Agent

Now that we have the flow created, we need to create an agent. I named mine File Upload Agent.

Topic

The last step is to create a topic that gets triggered any time a person mentions that they want to upload a file.

Name it File Upload

Below is the topic setup. It defines what this topic is about — in our case, file uploads — and what will trigger it.
When the user asks for a file to be uploaded, the agent responds with a question prompting them to attach the file in the chat.
In the next step, we call the flow created earlier. As input, we set File content (Record) to First(System.Activity.Attachments), which grabs the first attached file. If you want to process all files, simply remove First.
For the output, we assign the response to a variable called OutputMsg and display it inside a Message element.

And that’s it. If you follow the same approach, you’ll be able to upload files from Copilot Studio (directly in the agent chat) to your own API.

While researching how to do this, I couldn’t find a single resource or piece of documentation on it, so I hope this helps others as well.

Azure Cosmos DB is a fully managed Platform as a Service (PaaS) and serves as Microsoft’s flagship distributed database solution.

How you design the partitioning strategy for your Cosmos DB is undoubtedly one of the most critical architectural decisions you’ll make when building a solution on Microsoft Azure’s highly scalable, globally distributed NoSQL database.

Request Units (RUs)

Each operation you perform in Cosmos DB — whether it’s a read, write, update, or query — consumes a certain number of Request Units (RUs).

RUs represent a normalized measure of system resources such as CPU, memory, and IOPS (input/output operations per second) required to perform a given operation. This abstraction makes performance predictable — instead of worrying about the underlying infrastructure, you only manage RUs.

The amount of RUs consumed depends on several factors:

• Item size – larger JSON documents consume more RUs.

• Operation type – writes and queries typically cost more than point reads.

• Query complexity – filters, cross-partition queries, and sorting increase RU consumption.

• Indexing – since Cosmos DB automatically indexes all properties by default, write operations cost more if you have large or deeply nested documents.

You provision throughput in RUs per second (e.g., 400 RU/s), which defines how much performance capacity your container or database can handle. If your workload exceeds that capacity, Cosmos DB starts to throttle requests, returning a 429 (Request Rate Too Large) response until throughput is available again.

You can monitor RU consumption using the Azure Portal, SDK, or query metrics to identify and optimize expensive operations.

Basic Database Structure

In the Azure Cosmos DB NoSQL API, the data model consists of three main components — database, container(s), and item(s) — as illustrated in the diagram below.

• A database is the top-level logical namespace that groups one or more containers.

• A container is the fundamental unit of scalability and throughput. It holds a collection of JSON documents (items) and defines the partition key used to distribute data across partitions.

• An item is a single JSON document stored within a container. Each item must include an id property and a value for the partition key.

What is Partitioning?

Partitioning literally means dividing into parts. In Azure Cosmos DB, partitioning is a core mechanism that enables your application to scale efficiently and maintain consistent performance at any size.

Whenever you create a container, you must define a partition key — a property within your JSON documents that determines how data is distributed across partitions. The partition key choice directly affects scalability, query performance, and cost efficiency.

Each partition key value creates a virtual bucket called a logical partition, which contains all items that share the same partition key value. Choosing the right partition key is critical to achieving balanced data distribution. Ideally, the partition key should contain a value that never changes and one that has high cardinality — meaning it should have many unique values to evenly distribute data and requests across multiple logical partitions.

Otherwise, you may end up with what’s known as a hot partition — a single logical partition that stores a disproportionately large share of your data or handles most of the requests. This can lead to uneven throughput consumption, throttling, and degraded performance as that single partition becomes a bottleneck for your workload.

A logical partition resides within a physical partition. Depending on your data volume and throughput, a container can span multiple physical partitions. Each physical partition hosts one or more logical partitions, and Azure Cosmos DB automatically manages this distribution behind the scenes to maintain performance and scalability.

Now, let’s dive a bit deeper into partitioning strategy and discuss how to choose an effective partition key.

Partitioning Strategy

Let’s imagine we’re building a simple e-commerce website, similar to Amazon, where we have products, categories, and reviews. When users visit the site, they see a list of categories, select one, and then browse the products that belong to it.

For the sake of simplicity, we won’t attempt to replicate Amazon’s full complexity here — instead, we’ll focus on a simplified example that helps illustrate the fundamentals of partitioning in Azure Cosmos DB.

So, based on the structure we just defined, we’ll have three containers — one for products, one for categories, and one for reviews.

Now comes the interesting (and often challenging) part: choosing the right partition key for each container. The partition key determines how data is distributed and accessed, so picking the right one is essential for achieving scalability, balanced throughput, and optimal query performance.

Application accessing patterns

Whenever you choose a partition key, your starting point should always be how your application accesses the data. The way users query and interact with your data model should guide your partitioning strategy.

For our fictitious e-commerce app, when a user visits the website, they first see a list of categories and select one. After choosing a category, they’re shown a list of products that belong to it. From there, they can click on a specific product to view its details, add it to the cart, or purchase it.

Now, based on this, let’s choose the right partition key for each container, starting with the simplest one - categories.

categories

This one is easy. Since we don’t have that many categories (tens and not thousands) we’ll use the id as a partition key for it. What this means is that for each category we’ll have a single logical partition.

products

You might be tempted to use the product’s ID as the partition key here as well — it offers high cardinality and would evenly distribute data across partitions. While that’s not necessarily wrong, remember that our partitioning strategy is driven by how the application accesses data, not just by distribution.

In our e-commerce example, users typically browse products by category, not by individual product ID. That’s why a better choice for the Products container is CategoryID as the partition key — it aligns with the most common access pattern (fetching all products within a category) while still providing good distribution and query performance.

This approach keeps queries efficient, since the data you need (all products in a given category) is co-located within the same logical partition. As a result, Cosmos DB doesn’t have to perform a cross-partition query, which improves latency, throughput efficiency (RUs), and overall performance.

reviews

This one should be straightforward. In any e-commerce platform, reviews naturally belong to the product they describe — users leave feedback directly under the product page for others to see.

To maintain high cardinality and maximize query efficiency, we’ll use the ProductID as the partition key for the Reviews container. This way, all reviews for a given product are stored within the same logical partition, allowing the application to retrieve them with a single, efficient query — no cross-partition scans, no unnecessary RU consumption, and minimal latency.

For example, whenever you’re fetching a product’s reviews, you’ll run a query like this:

SELECT * 
FROM r 
WHERE r.ProductId = "123"

This query retrieves all reviews for the product with ID 123. Since all reviews for a given product reside in the same logical partition, Cosmos DB executes this as a single-partition query, ensuring low latency and efficient RU consumption.

Thanks

That’s a quick overview of the Cosmos DB partitioning fundamentals and the practical approach I personally use when designing data models. These are the core concepts that, once mastered, make it much easier to build scalable, high-performing solutions in Azure.

YouTube

Here’s a 10-minute video where I explain all this + a code demo.

If you want to really go deep into this topic, here’s links that I recommend:

• Partitioning and horizontal scaling - Azure Cosmos DB | Microsoft Learn

• Model and Partition Data using a Real-World Example - Azure Cosmos DB for NoSQL | Microsoft Learn

Most of the tutorials out there concentrate on building and deploying public containers that can be accessed from everyone over the internet. This approach, however, is not ideal and is rarely used in real production environments.

That’s why today I will show you how you can deploy two containers, one accessible from the internet (the web app UI) and another one that’s only accessible by the first container (the backend).

Keep in mind that this is not a full-blown tutorial. You should clone the repo and study it on your own. You can find the source code of my demo here: kaldren/acr-private-demo

What is Azure Container Apps

Azure Container Apps is a serverless platform for deploying and running containers. It is built on top of Kubernetes, and it abstracts away most of its complexity for you. Basically, things like scaling, container orchestration, configuration and server updates are all done for you by Azure.

Bicep

For this demo I’ve decided to use Bicep to deploy my infrastructure. You can check the source code for a more detailed walkthrough.

Container Communication in Azure Container Apps

There are a few ways for containers to talk to each other in ACA.

• Default fully qualified domain name (FQDN)

• A custom domain name

• The container app name, for instance http://<APP_NAME> for internal requests

• A Dapr URL

Today I will show you how the third option above, connecting via the app name for internal requests.

Let’s take a look at the bicep files now.

Repo Walkthrough

Azure Container Registry

First, to be able to deploy containers in Azure via ACA you need to have Azure Container Registry (ACR). This service can build and store your container images. Once the image is in the ACR your Container App can pull from it and use the image to build and deploy a container instance.

@description(’Name of the Container Registry’)
param containerRegistryName string

resource containerRegistry ‘Microsoft.ContainerRegistry/registries@2025-05-01-preview’ = {
  name: containerRegistryName
  location: resourceGroup().location
  identity: {
    type: ‘SystemAssigned’
  }
  sku: {
    name: ‘Basic’
  }
  properties: {
    adminUserEnabled: true
  }
}

output containerRegistry object = {
  name: containerRegistry.name
  endpoint: containerRegistry.properties.loginServer
}

Managed Identity

Once we deploy the ACR we need to create another resource - a Managed identity. We will then assign the role AcrPull to it for the ACR that we created above. This will allow it to pull container images from the registry. We will then assign this identity to our container apps which would allow them to pull the images from the registry themselves.

param containerRegistryName string

resource managedIdentity ‘Microsoft.ManagedIdentity/userAssignedIdentities@2025-01-31-preview’ = {
  location: resourceGroup().location
  name: ‘mi-containerapp’
}

// Set ArcPull role assignment for the managed identity on the ACR
resource acrPull ‘Microsoft.Authorization/roleAssignments@2022-04-01’ = {
  name: guid(managedIdentity.id, ‘AcrPull’)
  scope: containerRegistry
  properties: {
    roleDefinitionId: subscriptionResourceId(
      ‘Microsoft.Authorization/roleDefinitions’,
      ‘7f951dda-4ed3-4680-a7ca-43fe172d538d’ // AcrPull role ID
    )
    principalId: managedIdentity.properties.principalId
    principalType: ‘ServicePrincipal’
  }
}

output managedIdentityId string = managedIdentity.id

resource containerRegistry ‘Microsoft.ContainerRegistry/registries@2025-05-01-preview’ existing = {
  name: containerRegistryName
}

Azure Container Apps

We will deploy two containers - one for the frontend and one for the backend.

param location string = resourceGroup().location
param containerAppEnvironmentName string
param containerAppName string
param containerRegistryName string
param imageName string
param imageTag string

resource containerAppEnvironment ‘Microsoft.App/managedEnvironments@2025-02-02-preview’ = {
  name: containerAppEnvironmentName
  location: location
  properties: {}
}

resource containerApp ‘Microsoft.App/containerApps@2022-03-01’ ={
  name: containerAppName
  location: location
  identity: {
    type: ‘SystemAssigned, UserAssigned’
    userAssignedIdentities: {
      ‘${managedIdentity.id}’: {}
    }
  }
  properties:{
    managedEnvironmentId: containerAppEnvironment.id
    configuration: {
      ingress: {
        targetPort: 9696
        external: true
      }
      registries: [
        {
          server: ‘${containerRegistry.name}.azurecr.io’
          identity: managedIdentity.id
        }
      ]
    }
    template: {
      containers: [
        {
          image: ‘${containerRegistry.name}.azurecr.io/${imageName}:${imageTag}’
          name: imageName
        }
      ]
    }
  }
}

resource containerRegistry ‘Microsoft.ContainerRegistry/registries@2025-05-01-preview’ existing = {
  name: containerRegistryName
}

resource managedIdentity ‘Microsoft.ManagedIdentity/userAssignedIdentities@2025-01-31-preview’ existing = {
  name: ‘mi-containerapp’
}

The most important sections (in bold) to note are:

• identity section: Here we assign the managed identity created above to the app

• registry section: We use the identity to authenticate with the ACR

• ingress section: We allow incoming external requests (from the internet) because the web app needs to be accessible from everyone

Here’s the deployed frontend container app.

Now, let’s take a look at the backend container app.

param location string = resourceGroup().location
param containerAppEnvironmentName string
param containerAppName string
param containerRegistryName string
param imageName string
param imageTag string

resource containerAppEnvironment ‘Microsoft.App/managedEnvironments@2025-02-02-preview’ = {
  name: containerAppEnvironmentName
  location: location
  properties: {}
}

resource containerApp ‘Microsoft.App/containerApps@2022-03-01’ ={
  name: containerAppName
  location: location
  identity: {
    type: ‘SystemAssigned, UserAssigned’
    userAssignedIdentities: {
      ‘${managedIdentity.id}’: {}
    }
  }
  properties:{
    managedEnvironmentId: containerAppEnvironment.id
    configuration: {
      ingress: {
        targetPort: 8686
        external: false
      }
      registries: [
        {
          server: ‘${containerRegistry.name}.azurecr.io’
          identity: managedIdentity.id
        }
      ]
    }
    template: {
      containers: [
        {
          image: ‘${containerRegistry.name}.azurecr.io/${imageName}:${imageTag}’
          name: imageName
        }
      ]
    }
  }
}

resource containerRegistry ‘Microsoft.ContainerRegistry/registries@2025-05-01-preview’ existing = {
  name: containerRegistryName
}

resource managedIdentity ‘Microsoft.ManagedIdentity/userAssignedIdentities@2025-01-31-preview’ existing = {
  name: ‘mi-containerapp’
}

The only difference here is the external ingress is set to false. That’s because we don’t want this container to be accessible from the internet but only from the network inside the Azure Container App Environment.

Here’s how the backend container app looks like.

main.bicep

Here we add all bicep files as modules. For example:

module acr ‘modules/container-registry.bicep’ = {
  name: ‘acr-${randomSuffix}’
  params: {
    containerRegistryName: containerRegistryName
  }
  dependsOn: [
    rg
  ]
  scope: resourceGroup(resourceGroupName)
}

(Check the repo for the full file content)

deploy.sh

I’ve written a shell script that does the deployment for me. Here’s part of it.

# az login -- Might need to login first. Uncomment if needed.

az deployment sub create \
  --name rgDeployment \
  --location eastus \
  --parameters params/main.dev.bicepparam deployContainerApp=false

# # Login to ACR
ACR_LOGIN_SERVER=$(az acr show -n $ACR_NAME --query loginServer -o tsv)
az acr build --registry $ACR_NAME \
  --image $BACKEND_IMAGE:$BACKEND_TAG \
  --file ../backend/Dockerfile ../backend

ACR_LOGIN_SERVER=$(az acr show -n $ACR_NAME --query loginServer -o tsv)
az acr build --registry $ACR_NAME \
  --image $FRONTEND_IMAGE:$FRONTEND_TAG \
  --file ../frontend/Dockerfile ../frontend

az deployment sub create \
  --name rgDeployment \
  --location eastus \
  --parameters params/main.dev.bicepparam deployContainerApp=true

What this does is it is first deploying the ACR and managed identity resources without the container apps (see the deployContainerApp is set to false). That’s because I want to build and deploy the images for the frontend and backend first, so they are available for when we start deploying the container apps.

Dockerfile

Nothing fancy here. We just set the version to Python 3.13, install requirements.txt and run the apps on ports 8686 and 9696.

FROM python:3.13
WORKDIR /app
ENV HELLO_MESSAGE=”Hello from the backend!”
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8686
CMD [”uvicorn”, “main:app”, “--host”, “0.0.0.0”, “--port”, “8686”]

FROM python:3.13
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 9696
# Run streamlit app on container’s port 9696
CMD [”streamlit”, “run”, “main.py”, “--server.port=9696”, “--server.address=0.0.0.0”]

compose.yaml

This one I used for local development and testing.

Talking Containers

Let’s take a quick look at the frontend code to see how, once we deploy the infrastructure, we are able to connect to the backend container via the private network and not the public internet.

import streamlit as st
import requests

st.title(”Container Demo UI”)
st.text(”This text will change if the backend is called successfully.”)

API_URL = “http://app-backend-dev”

def call_hi_get():
    try:
        response = requests.get(f”{API_URL}/hi”)
        if response.status_code == 200:
            st.text(response.json().get(”message”, “No message in response”))
    except requests.RequestException as e:
        st.text(f”Error reaching backend: {e}”)
    
if st.button(”Call /hi endpoint!”):
    response = call_hi_get()

Here we’re using the app name, which in this case is app-backend-dev. We’re not using any FQDNs or FQDNs with internal in their url (e.g. https://app-frontend-dev.internal.alabala-xxx.eastus.azurecontainerapps.io) - I’ve seen this approach presented by folks, but I really, really hate it, because it is ugly and it requires you to figure out the actual FQDN first.

This approach is much cleaner - it relies on the service discovery system of ACA, which is much cleaner solution. We don’t have to care what the FQDN is.

Azure

Here’s our infrastructure in Azure.

If you want to learn more, then clone the repo, take a look and try it on your own.

Thanks.

What is MCP?

MCP stands for Model Context Protocol, and it is an open-source standard for connecting your AI applications to external systems.

Those systems can live on your own machine, like your filesystem, or be deployed thousands of kilometers away in some distant server, like the Azure MCP server.

In a nutshell, MCP allows you to easily integrate your AI application with other sources, like data stores, APIs, and etc.,

How MCP works?

MCP uses the client-server architecture that we are all familiar with. There are three main actors involved in the whole process:

1. MCP Host

   An AI application, powered by language model that supports MCP. Examples of such applications are Claude Desktop, Claude Code, GitHub Copilot.

   Keep in mind that for this to work the language model needs to support tool calling and not every model supports this. Also, I’m saying language model and not large language model (LLM), because nothing stops a small language model (SLM) from being able to use MCP, if the model supports it.

2. MCP Client

   An MCP Host creates a client, which then connects to an MCP Server. Each MCP Server has its own dedicated client.

3. MCP Server

   This is what provides the extended functionalities to your AI application. This is basically what we called “external system” earlier. Think of it as an API that your AI-powered application can call. And like we said, it can live on the same machine as your AI application or anywhere on the internet.

The following is a basic diagram of the whole process.

One thing to note is the two-way connection between the MCP Client and the MCP Server. That’s because the protocol allows for both the client AND the server to send messages to each other.

Features of MCP

So, what does MCP gives us? There are a few options available.

1. Tools

   These are functions provided by the MCP server that an LLM can call. You can think of them like API endpoints if you want. These functions could be calling a database, another API or executing any kind of business logic or integration. Tools are without question the most powerful feature of MCP.

2. Resources

   Read-only data sources that supply contextual information, such as file contents, database schemas, or API documentation.

3. Prompts

   Pre-built templates for guiding the model in using specific tools and resources.

These are all features that the MCP Server provides. There are also features that the MCP Client provides and that’s why the connection above is bidirectional. However, these are not that interesting for our understanding of MCP and for this demo, so if you want to learn more, please read the docs, which are really good.

Now, let’s build our remote MCP server.

requirements.txt

fastmcp

We’re going to be using FastMCP to build our server.

main.py

from fastmcp import FastMCP

mcp = FastMCP("Demo MCP")

@mcp.tool
def call_the_ceo() -> str:
    return "Calling the CEO... DONE!"

@mcp.tool
def send_email(to: str, subject: str, body: str) -> str:
    return f"Email sent to {to} with subject '{subject}' and body '{body}'"

@mcp.tool
def weather_info(location: str) -> str:
    return f"The weather in {location} is sunny with a high of 999°F."

if __name__ == "__main__":
    mcp.run()

We defined 3 tools. One that calls the CEO, another one that sends email and third one for weather info.

Dockerfile

# Use official Python image
FROM python:3.12-slim

# Set working directory
WORKDIR /app

# Copy requirements and source code
COPY requirements.txt ./
COPY main.py ./

# Install dependencies
RUN pip install --no-cache-dir -r requirements.txt

# Expose port
EXPOSE 8000

# Set entrypoint
CMD ["fastmcp", "run", "./main.py:mcp", "--transport", "http", "--host", "0.0.0.0", "--port", "8000"]

Since we’re going to use containers, we need Dockerfile. We’re first going to run this locally using Docker Desktop and test it with a tool called MCP Inspector. Then we will push this to Azure Container Registry and then run it on Container Apps.

Make sure you install the packages inside virtual environment and then run it.

uv venv
uv pip install -r .\requirements.txt
.venv\Scripts\activate

Now, let’s build our image.

docker build -t mcp-server-demo .

Run the image

docker run --name mcp-server-demo --rm -p 8000:8000 `
   -e HOST=0.0.0.0 -e PORT=8000 `
   mcp-server-demo

Now, let’s run the MCP Inspector. Inside the project folder, run the following.

npx @modelcontextprotocol/inspector fastmcp run .\main.py

Click Connect and if all done correctly, you should see the following.

Click on Tools and you should see all the tools that we have exposed. You can test each one of them if you want by providing the required parameters and clicking on Run Tool.

That’s great, we’ve tested the MCP server, and we saw it working locally. Now, let’s deploy this to Container Apps and use it remotely.

Deploy to Container Apps (Steps):

1. Create resource group in Azure

2. Create Azure Container Registry

3. Log into your container registry using azure cli

   az acr login --name [YOUR AZURE CONTAINER REGISTRY NAME]

4. Tag your container image

   docker tag mcp-server-demo [YOUR CONTAINER REGISTRY NAME].azurecr.io/mcp-server-demo:latest

5. Push to Azure Container Registry

   docker push [YOUR CONTAINER REGISTRY NAME].azurecr.io/mcp-server-demo:latest

6. Create Container App and in the set-up steps add the image you just pushed. Also, don’t forget to enable external traffic (Ingress option).

7. Once deployed, copy your container app’s URL

   

8. Open Claude Desktop (assuming you have it installed)

9. On the left screen at the bottom click on your user and then to Settings

   

10. Click on Developer and then on Edit Config

11. Open claude_desktop_config.json if it didn’t open automatically

12. Add the following snipper and replace [YOUR CONTAINER APP URL] with your actual container app url you copied earlier.

    {
      "mcpServers": {
        "custom-mcp": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "[YOUR CONTAINER APP URL]"
          ]
        }
      }
    }
    

13. Install custom-mcp package (the one we used above)

    npm i -g mcp-remote

14. Open Claude Desktop

Now, if you’ve followed along (and if I didn’t miss any step) you shouldn’t see any errors. Also, you should see the remote MCP server by clicking on the bar icon. Make sure it is enabled.

Now, let’s test this with the following prompt.

call the ceo

If everything was done correctly, you should see something similar to the following.

Choose either Allow always as we trust our own MCP server.

Here’s the result:

As you can see this actually worked. Now, let’s ask about the weather.

We can see that it says it’s 999F, which is exactly what we put in our code above. It works!

Now, let’s send an email, but let’s see how the LLM can provide a better user experience on its own, without us explicitly programming it to do so.

Here, if I wanted to send email directly, I would’ve provided the parameters. But instead, I said that I want to send an email and the LLM knows what parameters the tool needs in order for the email to be sent - email address, subject and body. And it asks me for that. Smart, and cool!

Now, let’s send the email.

Honestly, I’m too tired to fix any grammar mistakes at this point and am not going to use AI to do that either. I hope you found this quick demo useful!

Until next time!

Today, I’ll show you a quick way to experiment with it. For more details, check the official documentation.

Prerequisites

To follow along, make sure you have the following installed:

• Python

• Claude Desktop

• uv

Step 1: Set up the project

Windows

# Create a new directory for our project
uv init fakedb
cd fakedb

# Create virtual environment and activate it
uv venv
.venv\Scripts\activate

# Install dependencies
uv add mcp[cli]

# Create our server file
code fakedb.py

macOS

# Create a new directory for our project
uv init fakedb
cd fakedb

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install dependencies
uv add "mcp[cli]"

# Create our server file
touch fakedb.py

Step 2: Build a simple MCP server

Let’s add an endpoint to our MCP server that retrieves user information by user ID.

fakedb.py

This script creates a simple MCP server named fakedb with one tool, get_user_info. The tool takes a user ID, looks it up in a hardcoded dictionary (fake_db), and returns the matching user’s name and age. You could make this more interesting by integrating a real database and performing an actual query, but for simplicity, we’re keeping it in-memory here.

from typing import Any
from mcp.server.fastmcp import FastMCP

# Initialize FastMCP server
mcp = FastMCP("fakedb")

@mcp.tool()
def get_user_info(user_id: str) -> dict[str, Any] | None:
    """Get user information from the database.

    Args:
        user_id: The ID of the user to retrieve.
    """

    # Here we're simulating a real database lookup 
    # (you can try with a real one to make it more interesting)
    fake_db = {
        "1234": {"name": "Alice", "age": 30},
        "5678": {"name": "Bob", "age": 25},
    }
    return fake_db.get(user_id)

if __name__ == "__main__":
    # Initialize and run the server
    mcp.run(transport='stdio')

Step 3: Connect to Claude Desktop

Windows

Open:

%APPDATA%\Claude\claude_desktop_config.json

macOS

Open:

~/Library/Application Support/Claude/claude_desktop_config.json

Replace the file contents with:

{
  "mcpServers": {
    "userDatabase": {
      "command": "uv",
      "args": [
        "--directory",
        "<<FULL PATH TO YOUR PROJECT DIRECTORY>>",
        "run",
        "fakedb.py"
      ]
    }
  }
}

This configuration creates a new MCP server connection called userDatabase. The command and args simply run your MCP server.

Restart Claude Desktop, and you should see your new MCP server with one endpoint, called get_user_info.

Step 4: Test it in Claude

Now, if you ask Claude for user information (for example, “Give me all you have about user with id 1234 in tabular format”), the LLM will:

1. Detect the get_user_info tool.

2. Call it with the provided user_id.

3. Return the result in a neat, tabular format, exactly how we defined it.

You can see from the image above the prompt, the tool that was used and the output.

So this is it! A quick and neat way to test what MCP is and how it works without writing lots of complex code.

Thanks for reading!

Here’s a quick overview of how you can make it happen.

To keep things simple, I’ve used TigerCloud to spin up a PostgreSQL instance in the cloud.

Now, back to code.

general.txt

For the purpose of this demo, I’ve used Python’s Q&A section in their documentation that you can see here: General Python FAQ — Python 3.13.5 documentation

You can either copy the text from that page, or click Download to download the whole docs, then go to faq folder and take the general.txt from there and put it in your solution.

requirements.txt

Here are all the packages I needed:

openai
pandas
numpy
psycopg2-binary
pgvector
dotenv

.env

For the demo I had to get my OpenAI key as well as the connection string from TigerCloud:

OPENAI_API_KEY=<YOUR OPENAI API KEY HERE>
TIMESCALE_CONNECTION_STRING=<YOUR TIMESCALE CONNECTION STRING HERE>

utils.py

import numpy as np
import openai
from pgvector.psycopg2 import register_vector

# Function to process input with retrieval of most similar documents from the database
def process_input_with_retrieval(user_input, conn):
    delimiter = "```"

    #Step 1: Get documents related to the user input from database
    related_docs = get_top3_similar_docs(get_embeddings(user_input), conn)

    # Step 2: Get completion from OpenAI API
    # Set system message to help set appropriate tone and context for model
    system_message = f"""
    You are a friendly chatbot. \
    You can answer questions about Python, the programming language. \
    You respond in a concise, technically credible tone. Always use ONLY the data from the context and DO NOT PROVIDE any additional information. If you can't find the answer in the context, say "I don't know". Even if you find something that you think is not correct, but if it is in the context - say it.
    """

    # Prepare messages to pass to model
    # We use a delimiter to help the model understand the where the user_input starts and ends
    messages = [
        {"role": "system", "content": system_message},
        {"role": "user", "content": f"{delimiter}{user_input}{delimiter}"},
        {"role": "assistant", "content": f"Relevant Python information: \n {related_docs[0][0]} \n {related_docs[1][0]} {related_docs[2][0]}"}   
    ]

    final_response = get_completion_from_messages(messages)
    return final_response

# Helper function: get text completion from OpenAI API
def get_completion_from_messages(messages, model="gpt-4o", temperature=0, max_tokens=1000):
    openai_client = openai.OpenAI()
    response = openai_client.chat.completions.create(
        model=model,
        messages=messages,
        temperature=temperature, 
        max_tokens=max_tokens, 
    )
    return response.choices[0].message.content

# Helper function: Get top 3 most similar documents from the database
def get_top3_similar_docs(query_embedding, conn):
    embedding_array = np.array(query_embedding)
    # Register pgvector extension
    register_vector(conn)
    cur = conn.cursor()
    # Get the top 3 most similar documents using the KNN <=> operator
    cur.execute("SELECT content FROM embeddings ORDER BY embedding <=> %s LIMIT 3", (embedding_array,))
    top3_docs = cur.fetchall()
    return top3_docs

# Load text file content (duh!)
def load_text_file(file_path):
    with open(file_path, 'r', encoding='utf-8') as file:
        return file.read()

# Function to chunk text into smaller pieces
def chunk_text(text, num_chunks):
    """
    Split text into a specified number of chunks.
    
    Args:
        text (str): The text to be chunked
        num_chunks (int): Number of chunks to create
        
    Returns:
        list: List of text chunks
    """
    if num_chunks <= 0:
        raise ValueError("Number of chunks must be greater than 0")
    
    if not text:
        return [""] * num_chunks
    
    text_length = len(text)
    chunk_size = text_length // num_chunks
    remainder = text_length % num_chunks
    
    chunks = []
    start = 0
    
    for i in range(num_chunks):
        # Add one extra character to the first 'remainder' chunks
        current_chunk_size = chunk_size + (1 if i < remainder else 0)
        end = start + current_chunk_size
        chunks.append(text[start:end])
        start = end
    
    return chunks

# Function to get embeddings for a given text using OpenAI API
def get_embeddings(text):
    openai_client = openai.OpenAI()
    response = openai_client.embeddings.create(
        model="text-embedding-3-small",
        input = text.replace("\n"," ")
    )
    return response.data[0].embedding

main.py

from dotenv import load_dotenv, find_dotenv
import os
import openai
import pandas as pd
import numpy as np
import psycopg2
from utils import chunk_text, get_embeddings, load_text_file, process_input_with_retrieval
from psycopg2.extras import execute_values
from pgvector.psycopg2 import register_vector
_ = load_dotenv(find_dotenv()) 
openai.api_key  = os.environ['OPENAI_API_KEY'] 

new_list = []
text = load_text_file('general.txt')

# You can change the number of chunks here based on your needs and the size of the text
chunks = chunk_text(text, 5)

for i in range(len(chunks)):
    embedding = get_embeddings(chunks[i])
    new_list.append([chunks[i], embedding])

df = pd.DataFrame(new_list, columns=['content', 'embedding'])

print(f"Created DataFrame with {len(df)} rows")

connection_string  = os.environ['TIMESCALE_CONNECTION_STRING']

# Connect to PostgreSQL database in Timescale using connection string
conn = psycopg2.connect(connection_string)
cur = conn.cursor()

#install pgvector
cur.execute("CREATE EXTENSION IF NOT EXISTS vector;")
conn.commit()

#install pgvectorscale
cur.execute("CREATE EXTENSION IF NOT EXISTS vectorscale CASCADE;")
conn.commit()

# Create table to store embeddings and metadata
table_create_command = """
-- Remove table embeddings if it exists
DROP TABLE IF EXISTS embeddings;
CREATE TABLE embeddings (
            id bigserial primary key, 
            content text,
            embedding vector(1536)
            );
            """

cur.execute(table_create_command)
cur.close()
conn.commit()


#Batch insert embeddings and metadata from dataframe into PostgreSQL database
register_vector(conn)
cur = conn.cursor()

# Prepare the list of tuples to insert
data_list = [(row['content'], np.array(row['embedding'])) for index, row in df.iterrows()]

# Use execute_values to perform batch insertion
execute_values(cur, "INSERT INTO embeddings (content, embedding) VALUES %s", data_list)

# Commit after we insert all embeddings
conn.commit()

# Create an index on the data for faster retrieval
cur.execute('CREATE INDEX embedding_idx ON embeddings USING diskann (embedding);')
conn.commit()

input = 'Is Python portable?'

response = process_input_with_retrieval(input, conn)
print(input)
print(response)

Here’s the outcome

You can play around with this by changing the input, the data, etc.

All in all, it works great. And the fact that you are using one of the most widely used relational databases as your vector store for RAG is super convenient.

Thanks:

• PostgreSQL as a Vector Database: A Pgvector Tutorial | TigerData

This blog post is meant to give you a high-level overview of how I approached it, not a full step-by-step tutorial.

You can watch the video at the end to see the app in action.

The Onboarding App

I built a simple onboarding web app for, you guessed it, onboarding new employees in a company.

The app takes three inputs: the employee’s full name, email, and department. Behind the scenes, it creates three agents:

• department_rag_agent uses Azure AI Search to perform a vector-based RAG (see RAG and generative AI - Azure AI Search) search and find relevant onboarding information for the specified department (for example, Software Engineering).

• discord_agent is responsible for sending a welcome message on Discord, which includes the employee’s details and any department-specific information returned by the RAG agent.

• onboarding_agent acts as the orchestrator. It first invokes the RAG agent to gather relevant information, then passes the results to the Discord agent to send the final message.

The entire process is coordinated automatically once the onboarding form is submitted.

Here’s the end result message in Discord:

Project Structure Overview

This project showcases a multi-agent onboarding flow using Azure AI Foundry Agent Service. The main folders are:

• src/api/ – Contains the FastAPI backend with agent logic, tools, and utilities.

• func-api/ – An Azure Function App that exposes an endpoint for sending Discord messages. This is needed because connected agents do not support local function calls (see How to use connected agents - Azure AI Foundry | Microsoft Learn).

• web/ – A React.js frontend that serves as the UI for triggering the onboarding flow.

Environment Setup

• Azure Function App (for webhook to Discord)

• Azure AI Search (for RAG)

• Azure OpenAI (for embedding model)

• Azure AI Foundry project (for LLM)

To run the app locally or deploy it yourself, you’ll need a .env file with the following variables:

# Azure AI Foundry
PROJECT_ENDPOINT=   # Your Azure AI Foundry project endpoint
MODEL_DEPLOYMENT_NAME=   # The model deployment name used for your agents (e.g., gpt-4o-mini)

# Azure AI Search
AZURE_SEARCH_ENDPOINT=   # Endpoint of your Azure AI Search resource
AZURE_SEARCH_API_KEY=    # API key for your Azure AI Search instance
AZURE_SEARCH_INDEX_NAME= # Name of the index used for department RAG search

Also, you need to make sure you connect your Azure AI Search resource with your AI Foundry (see How to add a new connection in Azure AI Foundry portal - Azure AI Foundry | Microsoft Learn)

Final Thoughts

This was a fun Sunday experiment that gave me a hands-on introduction to Azure AI Foundry Agent Service (seriously, Microsoft, please give it a shorter and cooler name). With multi-agent coordination, Azure AI Search, and Discord integration via Azure Functions and an OpenAPI spec, I built a simple but practical onboarding automation flow that helped me understand what this framework is currently capable of.

Keep in mind that this framework is still new and actively evolving, so things may change quickly.

Here’s a demo of the app as well as quick walkthrough of the solution

Resources

• Github Repo

• What is Azure AI Foundry Agent Service?