N+1 Blog

Microsoft Agent Framework — Workflows, MCP, A2A & AG-UI

Sat, 07 Mar 2026 00:00:00 +0000

TL;DR

This is Part 2 of the Microsoft Agent Framework series. Part 1 covered the basics — creating agents, tools, multi-turn conversations, and memory. This post goes further: orchestrating agents into workflow graphs, exposing them as MCP servers, enabling agent-to-agent communication via A2A, and streaming to frontends with AG-UI. All samples run as single-file C# scripts with dotnet run.

TL;DR
Introduction — From agents to systems
Workflows — Orchestrating agents as graphs
MCP Integration — Agents as servers and clients
- MCP Server
- MCP Client
A2A — Agent-to-agent communication
- A2A Server
- A2A Client
AG-UI — Exposing agents to web UIs
- AG-UI Server
- AG-UI Client
Key takeaways
Presentation
References

Source code: https://github.com/NikiforovAll/maf-getting-started

Introduction — From agents to systems

Part 1 built individual agents with tools, sessions, and memory. But real systems need more: pipelines that chain agents together, protocols that expose agents to external clients, and standards that let agents discover each other.

MAF addresses this with three integration protocols:

Protocol	Who talks	Transport	Use case
MCP Server	Client → Your Agent	stdio / HTTP	Expose agents as tools
MCP Client	Your Agent → Remote Tools	stdio / HTTP	Consume external tools
A2A	Agent → Agent	HTTP + JSON-RPC	Multi-agent orchestration
AG-UI	User → Agent	HTTP POST + SSE	Serve end users

MCP gives agents tools (both ways), A2A lets agents talk to agents, AG-UI connects agents to end users.

Workflows — Orchestrating agents as graphs

Workflows in MAF are directed graphs — nodes are executors (functions or agents), edges define data flow. Three patterns cover most use cases:

Pattern	Use Case	API
Function Workflow	Pure data transformations, no LLM	`BindAsExecutor()` + `WorkflowBuilder`
Agent Workflow	LLM-powered multi-agent pipelines	`AgentWorkflowBuilder.BuildSequential()`
Composed Workflow	Mix functions + agents in one graph	`WorkflowBuilder` + `AddEdge()`

The building blocks:

Building Block	API	Description
Executor	`Func<T,R>.BindAsExecutor()`	A node in the workflow graph
Edge	`builder.AddEdge(A, B)`	Connects two executors (A → B)
Output	`builder.WithOutputFrom(B)`	Designates the final output node
Run	`InProcessExecution.RunAsync()`	Executes the workflow
StreamingRun	`InProcessExecution.RunStreamingAsync()`	Executes with streaming events
Events	`ExecutorCompletedEvent`, `AgentResponseUpdateEvent`	Emitted per completed node

Function workflow

Bind plain C# functions as workflow executors — no LLM involved, pure data transformations:

#:package Microsoft.Agents.AI.Workflows@1.0.0-rc2

using Microsoft.Agents.AI.Workflows;

Func<string, string> uppercaseFunc = s => s.ToUpperInvariant();
var uppercase = uppercaseFunc.BindAsExecutor("UppercaseExecutor");

Func<string, string> reverseFunc = s => string.Concat(s.Reverse());
var reverse = reverseFunc.BindAsExecutor("ReverseTextExecutor");

WorkflowBuilder builder = new(uppercase);
builder.AddEdge(uppercase, reverse).WithOutputFrom(reverse);
var workflow = builder.Build();

await using Run run = await InProcessExecution.RunAsync(workflow, "Hello, World!");
foreach (WorkflowEvent evt in run.NewEvents)
{
    if (evt is ExecutorCompletedEvent executorComplete)
    {
        Console.WriteLine($"{executorComplete.ExecutorId}: {executorComplete.Data}");
    }
}

graph LR Input["Hello, World!"] --> U[UppercaseExecutor] U --> R[ReverseTextExecutor] R --> Output["!DLROW ,OLLEH"]

Step	Executor	Output
Input	—	`"Hello, World!"`
1	UppercaseExecutor	`"HELLO, WORLD!"`
2	ReverseTextExecutor	`"!DLROW ,OLLEH"`

BindAsExecutor() wraps any Func<TInput, TOutput> into a workflow node. The TOutput of one node must match the TInput of the next — the type system enforces the contract.

Agent workflow

For LLM-powered pipelines, AgentWorkflowBuilder.BuildSequential() chains agents together:

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME");

var chatClient = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsIChatClient();

AIAgent writer = chatClient.AsAIAgent(
    instructions: "You write short creative stories in 2-3 sentences.", name: "Writer"
);

AIAgent critic = chatClient.AsAIAgent(
    instructions: "You review stories and give brief constructive feedback in 1-2 sentences.", name: "Critic"
);

var agentWorkflow = AgentWorkflowBuilder.BuildSequential("story-pipeline", [writer, critic]);

List<ChatMessage> input = [new(ChatRole.User, "Write a story about a robot learning to paint.")];

await using StreamingRun agentRun = await InProcessExecution.RunStreamingAsync(agentWorkflow,input);
await agentRun.TrySendMessageAsync(new TurnToken(emitEvents: true));

string lastExecutorId = string.Empty;
await foreach (WorkflowEvent evt in agentRun.WatchStreamAsync())
{
    if (evt is AgentResponseUpdateEvent e)
    {
        if (e.ExecutorId != lastExecutorId)
        {
            lastExecutorId = e.ExecutorId;
            Console.WriteLine();
            Console.WriteLine($"[{e.ExecutorId}]:");
        }

        Console.Write(e.Update.Text);
    }
    else if (evt is WorkflowOutputEvent output)
    {
        Console.WriteLine();
    }
}

graph LR U[User Prompt] --> W[Writer] W -->|story| C[Critic] C -->|feedback| O[Output]

[Writer]:
A small robot named Pixel discovered an abandoned art studio and began
mixing colors with its mechanical fingers...

[Critic]:
The story has a charming premise. Consider adding sensory details about
how the robot perceives color differently from humans...

Agent workflows use StreamingRun + AgentResponseUpdateEvent — not Run/NewEvents like function workflows. The TrySendMessageAsync(new TurnToken(emitEvents: true)) call kicks off the pipeline and enables event streaming.

Composed workflow

Real pipelines mix deterministic and intelligent steps. Consider PII redaction:

Step	What	Why not just one?
Regex (function)	Mask emails — fast, 100% reliable	LLMs hallucinate, regex doesn't
LLM (agent)	Rewrite text naturally	Regex can't rephrase prose
Regex (function)	Validate no PII leaked	Trust but verify — deterministic check

WorkflowBuilder lets you compose both in a single directed graph. First, define the three executors:

var client = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential());

// Step 1: Function executor — mask emails with regex
Func<string, string> maskEmails = text =>
    Regex.Replace(text, @"[\w.-]+@[\w.-]+\.\w+", "[EMAIL_REDACTED]");
var maskExecutor = maskEmails.BindAsExecutor("MaskEmails");

// Step 2: Agent executor — wrap LLM agent call as a function executor
AIAgent rewriter = client
    .GetChatClient(deploymentName)
    .AsAIAgent(
        instructions: "You receive text with [EMAIL_REDACTED] placeholders. "
            + "Rewrite the text to sound natural while keeping all redactions intact. "
            + "Do not invent or restore any redacted information. "
            + "Return only the rewritten text.",
        name: "Rewriter"
    );
Func<string, ValueTask<string>> rewriteFunc = async text =>
{
    var response = await rewriter.RunAsync(text);
    return response.ToString();
};
var rewriteExecutor = rewriteFunc.BindAsExecutor("Rewriter");

// Step 3: Function executor — validate no emails leaked
Func<string, string> validate = text =>
{
    var leaks = Regex.Matches(text, @"[\w.-]+@[\w.-]+\.\w+");
    return leaks.Count > 0
        ? $"VALIDATION FAILED - {leaks.Count} email(s) leaked"
        : $"CLEAN - no emails detected\n\n{text}";
};
var validateExecutor = validate.BindAsExecutor("ValidateNoLeaks");

Sync Func<T,R> is auto-wrapped to ValueTask by the framework, while async Func<T, ValueTask<R>> is used for agent calls that involve I/O. Both produce the same Executor — the graph doesn’t care.

Then wire the graph and execute:

// Build graph: mask → rewrite → validate
WorkflowBuilder builder = new(maskExecutor);
builder.AddEdge(maskExecutor, rewriteExecutor);
builder.AddEdge(rewriteExecutor, validateExecutor);
builder.WithOutputFrom(validateExecutor);
var workflow = builder.Build();

var input = """
    Hi team, please contact Alice at alice.smith@example.com for the Q3 report.
    Bob (bob.jones@corp.net) will handle the deployment.
    CC: support@acme.io for any issues.
    """;

await using Run run = await InProcessExecution.RunAsync(workflow, input);

foreach (WorkflowEvent evt in run.NewEvents)
{
    if (evt is ExecutorCompletedEvent executorComplete)
    {
        Console.WriteLine($"[{executorComplete.ExecutorId}]:");
        Console.WriteLine(executorComplete.Data);
        Console.WriteLine();
    }
}

graph LR I[Input text with emails] --> M[MaskEmails
Func — regex] M --> R[Rewriter
AIAgent — LLM] R --> V[ValidateNoLeaks
Func — regex] V --> O[Output]

[MaskEmails]:
Hi team, please contact Alice at [EMAIL_REDACTED] for the Q3 report.
Bob ([EMAIL_REDACTED]) will handle the deployment.
CC: [EMAIL_REDACTED] for any issues.

[Rewriter]:
Hi team, please reach out to Alice at [EMAIL_REDACTED] regarding the Q3 report.
Bob ([EMAIL_REDACTED]) will be managing the deployment.
For any issues, CC [EMAIL_REDACTED].

[ValidateNoLeaks]:
CLEAN - no emails detected

MCP Integration — Agents as servers and clients

Model Context Protocol is an open standard for connecting AI models to external tools and data. The integration is two-sided:

Direction	Pattern	API
Agent as MCP Server	Expose your agents as tools for external MCP clients (Claude Code, VS Code, etc.)	`.AsAIFunction()` → `McpServerTool.Create()`
Agent as MCP Client	Your agent discovers and calls tools from remote MCP servers	`McpClient.CreateAsync()` → `ListToolsAsync()`

MCP Server

Two calls turn any agent into an MCP tool: .AsAIFunction() then McpServerTool.Create():

var client = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential());

AIAgent joker = client
    .GetChatClient(deploymentName)
    .AsAIAgent(
        instructions: "You are good at telling jokes.",
        name: "Joker",
        description: "An agent that tells jokes on any topic."
    );

AIAgent weatherAgent = client
    .GetChatClient(deploymentName)
    .AsAIAgent(
        instructions: "You are a helpful weather assistant.",
        name: "WeatherAgent",
        description: "An agent that answers weather questions.",
        tools: [AIFunctionFactory.Create(GetWeather)]
    );

var jokerTool = McpServerTool.Create(joker.AsAIFunction());
var weatherTool = McpServerTool.Create(weatherAgent.AsAIFunction());

var builder = Host.CreateEmptyApplicationBuilder(settings: null);
builder.Services.AddMcpServer().WithStdioServerTransport().WithTools([jokerTool, weatherTool]);

await builder.Build().RunAsync();

[Description("Get the weather for a given location.")]
static string GetWeather([Description("The location to get the weather for.")] string location) =>
    $"The weather in {location} is cloudy with a high of 15°C.";

sequenceDiagram participant C as MCP Client
(Claude Code) participant S as MCP Server
(stdio) participant W as WeatherAgent participant T as GetWeather C->>S: call WeatherAgent tool S->>W: RunAsync(input) W->>T: GetWeather("Amsterdam") T-->>W: "cloudy, 15°C" W-->>S: response S-->>C: result

Drop a .mcp.json in your repo root and Claude Code / VS Code picks it up automatically:

{
  "mcpServers": {
    "maf-agents": {
      "command": "dotnet",
      "args": ["run", "src/06-agent-as-mcp.cs"],
      "env": {
        "AZURE_OPENAI_ENDPOINT": "https://your-resource.cognitiveservices.azure.com/",
        "AZURE_OPENAI_DEPLOYMENT_NAME": "gpt-4o-mini"
      }
    }
  }
}

dotnet run starts the MCP server as a child process. Communication happens over stdio — no ports, no networking.

MCP Client

Agents can also consume MCP tools. Here’s an agent that uses Microsoft Learn’s public MCP server:

var client = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential());

Console.WriteLine("Connecting to Microsoft Learn MCP...");
await using var mcpClient = await McpClient.CreateAsync(
    new HttpClientTransport(
        new()
        {
            Endpoint = new Uri("https://learn.microsoft.com/api/mcp"),
            Name = "Microsoft Learn MCP",
            TransportMode = HttpTransportMode.StreamableHttp,
        }
    ),
    loggerFactory: loggerFactory
);

Console.WriteLine("Listing tools...");
IList<McpClientTool> mcpTools = await mcpClient.ListToolsAsync();
Console.WriteLine($"Discovered {mcpTools.Count} tools:");
foreach (var tool in mcpTools)
    Console.WriteLine($"  - {tool.Name}");

AIAgent agent = client
    .GetChatClient(deploymentName)
    .AsIChatClient()
    .AsBuilder()
    .UseLogging(loggerFactory)
    .Build()
    .AsAIAgent(
        instructions: "You answer questions using Microsoft Learn documentation tools.",
        name: "DocsAgent",
        loggerFactory: loggerFactory,
        tools: [.. mcpTools.Cast<AITool>()]
    );

Console.WriteLine("Running agent...");
Console.WriteLine(await agent.RunAsync("What is Microsoft Agent Framework?"));

HttpClientTransport connects to remote MCP servers (Streamable HTTP), while StdioClientTransport works for local servers. The same ListToolsAsync() API discovers tools in both cases. Discovered McpClientTool instances are cast to AITool and passed directly as agent tools.

A2A — Agent-to-agent communication

Agent-to-Agent Protocol is an open standard for agents to discover and communicate with each other over HTTP.

	MCP	A2A
Who talks	Client → Tool	Agent → Agent
Transport	stdio / HTTP	HTTP + JSON-RPC
Discovery	Config file	`/.well-known/agent-card.json`
Use case	Extend agent capabilities	Multi-agent orchestration

A2A Server

Every A2A agent publishes an AgentCard that clients fetch for discovery:

var client = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential());

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient().AddLogging();
builder.Services.ConfigureHttpJsonOptions(o =>
{
    o.SerializerOptions.TypeInfoResolverChain.Add(
        A2AJsonUtilities.DefaultOptions.TypeInfoResolver!
    );
    o.SerializerOptions.TypeInfoResolverChain.Add(
        A2AJsonUtilities.DefaultOptions.TypeInfoResolver!
    );
});

var app = builder.Build();

AIAgent agent = client
    .GetChatClient(deploymentName)
    .AsIChatClient()
    .AsAIAgent(
        instructions: "You are a helpful assistant.",
        name: "A2AAssistant",
        tools: [AIFunctionFactory.Create(GetWeather)]
    );

AgentCard agentCard = new()
{
    Name = "A2AAssistant",
    Description = "A helpful assistant exposed via A2A protocol.",
    Version = "1.0.0",
    DefaultInputModes = ["text"],
    DefaultOutputModes = ["text"],
    Capabilities = new() { Streaming = false },
    Skills =
    [
        new()
        {
            Id = "general",
            Name = "General Assistant",
            Description = "Answers general questions and checks weather.",
        },
    ],
};

app.MapA2A(
    agent,
    path: "/",
    agentCard: agentCard,
    taskManager => app.MapWellKnownAgentCard(taskManager, "/")
);

await app.RunAsync();

[Description("Get the weather for a given location.")]
static string GetWeather([Description("The location to get the weather for.")] string location) =>
    $"The weather in {location} is cloudy with a high of 15°C.";

MapA2A() exposes the agent over HTTP, and MapWellKnownAgentCard() serves the card at /.well-known/agent-card.json. Clients discover the agent by fetching the card — no config files, no registry needed.

A2A Client

var host = args.Length > 0 ? args[0] : "http://localhost:5000";

A2ACardResolver resolver = new(new Uri(host));

AIAgent agent = await resolver.GetAIAgentAsync();

Console.WriteLine(await agent.RunAsync("What is the weather in Amsterdam?"));

4 lines to discover a remote agent and call it. A2ACardResolver fetches the agent card, constructs an AIAgent proxy, and you use the same RunAsync() interface as local agents.

AG-UI — Exposing agents to web UIs

Agent User Interface Protocol connects agents to frontend UIs via HTTP POST + Server-Sent Events:

	MCP	A2A	AG-UI
Who talks	Client → Tool	Agent → Agent	User → Agent
Transport	stdio / HTTP	HTTP + JSON-RPC	HTTP POST + SSE
Discovery	Config file	Agent card	URL
Use case	Extend capabilities	Multi-agent orchestration	Serve end users

The client sends one HTTP POST, the server streams back typed SSE events:

Phase	What happens	SSE Events
Start	Server begins processing	`RUN_STARTED`
Text response	Tokens stream to UI in real-time	`TEXT_MESSAGE_START` → `TEXT_MESSAGE_CONTENT`* → `TEXT_MESSAGE_END`
Tool call	Agent invokes a function	`TOOL_CALL_START` → `TOOL_CALL_ARGS` → `TOOL_CALL_END`
State update	Shared state syncs to client	`STATE_SNAPSHOT` or `STATE_DELTA`
Finish	Run completes	`RUN_FINISHED`

AG-UI Server

var client = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential());

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient().AddLogging();
builder.Services.AddCors(o =>
    o.AddDefaultPolicy(p => p.AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader())
);
builder.Services.AddAGUI();

WebApplication app = builder.Build();
app.UseCors();

AIAgent agent = client
    .GetChatClient(deploymentName)
    .AsIChatClient()
    .AsAIAgent(
        instructions: "You are a helpful assistant.",
        name: "AGUIAssistant",
        description: "A helpful assistant that can answer questions and check weather.",
        tools: [AIFunctionFactory.Create(GetWeather)]
    );

app.MapAGUI("/", agent);

await app.RunAsync();

[Description("Get the weather for a given location.")]
static string GetWeather([Description("The location to get the weather for.")] string location) =>
    $"The weather in {location} is cloudy with a high of 15°C.";

AddAGUI() registers the AG-UI JSON serialization, MapAGUI("/", agent) exposes the agent as an HTTP+SSE endpoint. Two calls from agent to web-ready endpoint.

AG-UI Client

using HttpClient httpClient = new() { Timeout = TimeSpan.FromSeconds(60) };
AGUIChatClient chatClient = new(httpClient, "http://localhost:5000");

AIAgent agent = chatClient.AsAIAgent(name: "agui-client");

await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(
    [new ChatMessage(ChatRole.User, "What's the weather in Amsterdam?")]))
{
    foreach (AIContent content in update.Contents)
        if (content is TextContent text)
            Console.Write(text.Text);
}

AGUIChatClient wraps HttpClient and speaks the AG-UI protocol. From there it’s the familiar AsAIAgent() + RunStreamingAsync() pattern. The full interactive client adds a Spectre.Console chat loop with session management. For richer frontend experiences, check out CopilotKit or AG-UI Dojo.

Key takeaways

BindAsExecutor() — turn any Func<T,R> into a workflow node
AgentWorkflowBuilder.BuildSequential() — chain agents into pipelines with one call
WorkflowBuilder + AddEdge() — compose function and agent executors in a single graph
McpServerTool.Create(agent.AsAIFunction()) — expose agents as MCP tools in two lines
MapA2A() + AgentCard — agents discover and call each other over HTTP
AddAGUI() + MapAGUI() — expose agents to web UIs via HTTP+SSE in two lines

Presentation

References

Microsoft Agent Framework — Foundations

Mon, 02 Mar 2026 00:00:00 +0000

TL;DR

Microsoft Agent Framework (MAF) merges Semantic Kernel and AutoGen into a single, production-ready agent runtime built on Microsoft.Extensions.AI. This post walks through five progressive samples — creating your first agent, adding tools, composing agents, multi-turn conversations, and persistent memory — all running as single-file C# scripts with dotnet run.

TL;DR
Introduction — What is MAF?
Your first agent
Tools — Giving agents the ability to act
- Function tools
- Agent-as-tool
Multi-turn conversations
Memory and persistence
Key takeaways
What’s next
Presentation
References

Source code: https://github.com/NikiforovAll/maf-getting-started

Introduction — What is MAF?

.NET had two AI agent frameworks from Microsoft: Semantic Kernel for enterprise orchestration and AutoGen for multi-agent research. Two ecosystems, overlapping goals, confusion about which to pick. MAF unifies them into one framework.

Before	After
Semantic Kernel — enterprise AI orchestration	Built on Microsoft.Extensions.AI abstractions
AutoGen — multi-agent research framework	Microsoft.Agents.AI — unified agent runtime
Two ecosystems, overlapping goals	Single API for single & multi-agent scenarios

1️⃣ The architecture is layered:

Layer	Components
Your Application	AIAgent, Tools, Sessions, Workflows
Microsoft.Agents.AI	Unified agent runtime
Microsoft.Extensions.AI	`IChatClient`, `AIFunction`
Providers	Azure OpenAI, OpenAI, Ollama, ...

2️⃣ The core concepts:

Concept	Type	Purpose
AIAgent	`IAIAgent`	Core agent abstraction
Tools	`AIFunction`	Functions the agent can call
Session	`AgentSession`	Conversation state & history
Run	`RunAsync` / `RunStreamingAsync`	Execute agent with input
Workflow	`WorkflowBuilder`	Multi-agent orchestration

Your first agent

All samples use .NET 10’s run-file feature — single .cs files with #:package directives, no .csproj needed:

export AZURE_OPENAI_ENDPOINT="https://your-resource.cognitiveservices.azure.com/"
export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"

dotnet run src/01-hello-agent.cs

Here’s the full agent — 38 lines from zero to running:

#:package Microsoft.Agents.AI.OpenAI@1.0.0-rc2
#:package Azure.AI.OpenAI@2.8.0-beta.1
#:package Azure.Identity@1.18.0

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI.Chat;

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME");

AIAgent agent = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(
        new ChatClientAgentOptions
        {
            Name = "HelloAgent",
            ChatOptions = new ChatOptions
            {
                Instructions = "You are a friendly assistant. Keep your answers brief.",
                Temperature = 0.9f,
            },
        }
    );

// Non-streaming
Console.WriteLine(await agent.RunAsync("Tell me a one-sentence fun fact."));

// Streaming — process tokens as they arrive
await foreach (var update in agent.RunStreamingAsync("Tell me a one-sentence fun fact."))
{
    Console.WriteLine(update);
}

The pipeline is straightforward:

Step	Call	Role
1	`new AzureOpenAIClient(...)`	Azure OpenAI provider
2	`.GetChatClient("gpt-4o-mini")`	`ChatClient` via `IChatClient`
3	`.AsAIAgent(options)`	`AIAgent` from MAF
4	`.RunAsync("prompt")`	Execute and get response

AsAIAgent() is the key extension method. It turns any IChatClient into a full agent. Because it’s built on IChatClient, you can swap the provider (Azure OpenAI, OpenAI, Ollama) without touching agent code.

Tools — Giving agents the ability to act

Function tools

Define a plain C# method with [Description] attributes and register it via AIFunctionFactory.Create():

[Description("Get the weather for a given location.")]
static string GetWeather(
    [Description("The location to get the weather for.")] string location) =>
    $"The weather in {location} is cloudy with a high of 15°C.";

AIAgent weatherAgent = client
    .GetChatClient(deploymentName)
    .AsAIAgent(
        instructions: "You are a helpful weather assistant.",
        name: "WeatherAgent",
        description: "An agent that answers weather questions.",
        tools: [AIFunctionFactory.Create(GetWeather)]
    );

Console.WriteLine(await weatherAgent.RunAsync("What is the weather like in Amsterdam?"));

How tool calling works:

User sends: “What’s the weather in Amsterdam?”
LLM decides to call GetWeather("Amsterdam")
MAF invokes the C# method automatically
Result is fed back to the LLM
LLM generates the final answer using the tool result

The [Description] attributes are sent to the LLM as the tool schema — write clear, specific descriptions because that’s all the model sees when deciding which tool to call.

sequenceDiagram participant U as User participant A as WeatherAgent participant T as GetWeather U->>A: "Weather in Amsterdam?" A->>T: GetWeather("Amsterdam") T-->>A: "cloudy, 15°C" A-->>U: final answer

Agent-as-tool

Any agent can become a tool for another agent via .AsAIFunction():

AIAgent orchestrator = client
    .GetChatClient(deploymentName)
    .AsAIAgent(
        instructions: "You are a helpful assistant. Use the weather agent when asked about weather.",
        tools: [weatherAgent.AsAIFunction()]
    );

Console.WriteLine(await orchestrator.RunAsync("What's the weather in Amsterdam and Paris?"));

The orchestrator delegates to WeatherAgent when it encounters weather questions. The weather agent, in turn, calls its own GetWeather tool for each location.

sequenceDiagram participant U as User participant O as Orchestrator participant W as WeatherAgent participant T as GetWeather U->>O: "Weather in Amsterdam and Paris?" O->>W: AsAIFunction() W->>T: GetWeather("Amsterdam") T-->>W: "cloudy, 15°C" W->>T: GetWeather("Paris") T-->>W: "cloudy, 15°C" W-->>O: combined result O-->>U: final answer

Each agent has its own LLM call — be mindful of latency and cost when nesting agents.

Multi-turn conversations

Without a session, each RunAsync call is stateless — the agent has no memory of prior turns. AgentSession holds the conversation thread:

AIAgent agent = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(
        instructions: """You are a friendly assistant. Keep your answers brief.
            And always remember the information the user shares with you
            during the conversation.
            """,
        name: "ConversationAgent"
    );

AgentSession session = await agent.CreateSessionAsync();

// Turn 1 — introduce context
Console.WriteLine(await agent.RunAsync("My name is Alice and I love hiking.", session));

// Turn 2 — agent remembers from session history
Console.WriteLine(await agent.RunAsync("What do you remember about me?", session));

// Turn 3 — agent uses accumulated context
Console.WriteLine(await agent.RunAsync("Suggest a hiking destination for me.", session));

Under the hood, the session accumulates the full conversation and sends it with each LLM call:

Turn	Input	ChatHistory contents
created	—	`[]` (empty)
1	"My name is Alice..."	`[system, user₁, assistant₁]`
2	"What do you remember?"	`[system, user₁, assistant₁, user₂, assistant₂]`
3	"Suggest a destination"	`[system, user₁, assistant₁, user₂, assistant₂, user₃, assistant₃]`

The default provider is InMemoryChatHistoryProvider — zero config, but lost on process restart.

Memory and persistence

In-memory and serialization

The default InMemoryChatHistoryProvider works for single-process scenarios. For persistence across restarts, MAF provides serialization:

AgentSession session = await agent.CreateSessionAsync();

await agent.RunAsync("My name is Alice", session);

// Serialize session to JSON
var serialized = await agent.SerializeSessionAsync(session);
Console.WriteLine($"Session serialized ({serialized.GetRawText().Length} bytes)");

// Store anywhere — database, file, Redis, blob storage

// Restore session from serialized data
var restoredSession = await agent.DeserializeSessionAsync(serialized);

// Agent remembers everything from the original session
await agent.RunAsync("Do you still remember my name?", restoredSession);
// → "Yes, your name is Alice!"

SerializeSessionAsync / DeserializeSessionAsync give you portable session state. Export to JSON, store it however you want, restore later.

Custom ChatHistoryProvider

For more control, implement ChatHistoryProvider directly. Here’s a simple file-backed provider:

sealed class FileChatHistoryProvider(string filePath) : ChatHistoryProvider
{
    protected override ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(
        InvokingContext context, CancellationToken cancellationToken = default)
    {
        if (!File.Exists(filePath))
            return new(Enumerable.Empty<ChatMessage>());

        var json = File.ReadAllText(filePath);
        var messages = JsonSerializer.Deserialize(json, ChatHistoryJsonContext.Default.ListChatMessage) ?? [];
        return new(messages.AsEnumerable());
    }

    protected override ValueTask StoreChatHistoryAsync(InvokedContext context, CancellationToken cancellationToken = default)
    {
        List<ChatMessage> existing = [];
        if (File.Exists(filePath))
        {
            var json = File.ReadAllText(filePath);
            existing = JsonSerializer.Deserialize(json, ChatHistoryJsonContext.Default.ListChatMessage) ?? [];
        }

        existing.AddRange(context.RequestMessages);
        existing.AddRange(context.ResponseMessages ?? []);

        File.WriteAllText(path: filePath, JsonSerializer.Serialize(existing, ChatHistoryJsonContext.Default.ListChatMessage));
        return default;
    }
}

Wire it up via ChatClientAgentOptions:

AIAgent agent = new AzureOpenAIClient(new Uri(endpoint!), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(new ChatClientAgentOptions
    {
        Name = "PersistentAgent",
        ChatOptions = new ChatOptions
        {
            Instructions = "You are a friendly assistant. Keep your answers brief.",
        },
        ChatHistoryProvider = new FileChatHistoryProvider(filePath),
    });

This survives process restarts — create a new agent with the same file, and it picks up where it left off. The limitation: all sessions share the same file. Concurrent sessions will clobber each other’s history.

Session-aware ChatHistoryProvider

For per-session isolation, use ProviderSessionState<TState>. Each session gets its own file identified by a unique session ID:

sealed class FileChatHistoryProvider : ChatHistoryProvider
{
    private readonly string _directory;
    private readonly ProviderSessionState<SessionState> _sessionState;

    public FileChatHistoryProvider(string directory, string? existingSessionId = null)
    {
        _directory = directory;
        _sessionState = new ProviderSessionState<SessionState>(
            _ => new SessionState(existingSessionId ?? Guid.NewGuid().ToString("N")[..8]),
            nameof(FileChatHistoryProvider));
    }

    public string GetSessionId(AgentSession? session) =>
        _sessionState.GetOrInitializeState(session).SessionId;

    protected override ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(
        InvokingContext context, CancellationToken cancellationToken = default)
    {
        var state = _sessionState.GetOrInitializeState(context.Session);
        var path = Path.Combine(_directory, $"{state.SessionId}.json");
        // ... read from session-specific file
    }

    // ... StoreChatHistoryAsync implementation similar to before, but using session-specific file

    sealed class SessionState(string sessionId)
    {
        public string SessionId { get; } = sessionId;
    }
}

To restore a session after restart, extract the session ID and pass it to a new provider:

var sessionId = historyProvider.GetSessionId(session);
var restoredProvider = new FileChatHistoryProvider(historyDir, sessionId);

AIAgent agent2 = client.GetChatClient(deploymentName)
    .AsAIAgent(new ChatClientAgentOptions
    {
        ChatHistoryProvider = restoredProvider,
    });

AgentSession session2 = await agent2.CreateSessionAsync();
await agent2.RunAsync("Do you remember my name?", session2); // → "Alice"

Key takeaways

AsAIAgent() — one extension method turns any IChatClient into a full agent
[Description] + AIFunctionFactory.Create() — plain C# methods become LLM-callable tools
.AsAIFunction() — any agent can become a tool for another agent
AgentSession — pass to RunAsync to maintain multi-turn conversation history
ChatHistoryProvider — the extension point for production persistence

What’s next

Part 2 covers Workflows, MCP, and AG-UI — orchestrating multi-agent pipelines, exposing agents as MCP servers, and streaming to frontends via the AG-UI protocol.

Presentation

References

Building RAG with .NET AI Building Blocks - Microsoft.Extensions.AI

Sat, 28 Feb 2026 00:00:00 +0000

TL;DR

I built a RAG-based document intelligence assistant in .NET using IChatClient and IEmbeddingGenerator from Microsoft.Extensions.AI, VectorStoreCollection from Microsoft.Extensions.VectorData, Qdrant for vector search, Ollama for local inference, and .NET Aspire to wire it all together. The result is a provider-agnostic RAG app where switching from Ollama to OpenAI means changing one line of DI registration. This post walks through the abstractions, the pipeline, and how Aspire enables LLM-as-Judge evaluation in integration tests.

TL;DR
Introduction
The building blocks
The RAG pipeline
- Ingestion
- Query
Aspire orchestration
RAG evaluation with LLM-as-Judge
Demo
Summary
References

Source code: https://github.com/NikiforovAll/company-intel-dotnet

Introduction

Most AI integrations are tightly coupled to a specific provider. Your code imports the OpenAI SDK, or the Ollama client, or the Azure AI library. Switching providers means rewriting application code, not just configuration.

Microsoft.Extensions.AI (MEAI) gives you IChatClient and IEmbeddingGenerator. You register an implementation at startup. The rest of your code uses the abstraction. Change one line in DI. Your RAG pipeline, your agent, your evaluation tests — none of them care.

Microsoft.Extensions.VectorData does the same for vector stores. Define your data model with attributes, and the framework handles embedding and search.

This post walks through building a complete RAG application using these abstractions, with Aspire for orchestration and LLM-as-Judge for quality evaluation.

The building blocks

.NET has four AI building blocks. This post focuses on the first two.

Block	Package	What it gives you
MEAI	`Microsoft.Extensions.AI`	`IChatClient`, `IEmbeddingGenerator` — provider-agnostic interfaces
VectorData	`Microsoft.Extensions.VectorData`	`VectorStoreCollection`, attribute-driven data models, auto-embedding
Agent Framework	`Microsoft.Agents.AI`	`IAIAgent`, AG-UI protocol for streaming to frontends

IChatClient and IEmbeddingGenerator

Here’s the entire AI registration for the app:

builder.AddOllamaApiClient("ollama-llama3-1").AddChatClient();
builder.AddOllamaApiClient("ollama-all-minilm").AddEmbeddingGenerator();

After this, any service can inject IChatClient or IEmbeddingGenerator<string, Embedding<float>> and use them without knowing what’s behind them.

The chat client usage looks like this:

IChatClient chatClient = sp.GetRequiredService<IChatClient>();
var response = await chatClient.GetResponseAsync(messages);

The same applies to embeddings:

var embedder = sp.GetRequiredService<IEmbeddingGenerator<string, Embedding<float>>>();
var embeddings = await embedder.GenerateAsync(["some text"]);

384-dimensional vectors from all-minilm, but your code doesn’t know or care about dimensions.

DelegatingChatClient: middleware for AI

MEAI borrows the middleware pattern from ASP.NET Core. DelegatingChatClient wraps an IChatClient and intercepts calls. You can add logging, caching, telemetry, retry logic — all as composable layers.

Here’s a real example from the project. OllamaSharp doesn’t set MessageId on streaming updates, but CopilotKit’s Zod schema rejects null values. The fix is a thin wrapper:

internal sealed class EnsureMessageIdChatClient(IChatClient inner) : DelegatingChatClient(inner)
{
    public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
        IEnumerable<ChatMessage> messages,
        ChatOptions? options = null,
        CancellationToken cancellationToken = default)
    {
        string? messageId = null;

        await foreach (var update in base.GetStreamingResponseAsync(
            messages, options, cancellationToken))
        {
            if (update.MessageId is null)
            {
                messageId ??= Guid.NewGuid().ToString("N");
                update.MessageId = messageId;
            }

            yield return update;
        }
    }
}

This is a compatibility shim, but the pattern is general. MEAI ships with built-in delegating clients for logging, OpenTelemetry, caching, and automatic function invocation. You compose them in DI like middleware:

builder.AddOllamaApiClient("ollama-llama3-1")
    .AddChatClient(pipeline => pipeline
        .UseLogging()
        .UseOpenTelemetry()
        .UseFunctionInvocation());

Each .Use*() call wraps the client in another layer. The outermost layer runs first, just like ASP.NET middleware.

VectorData with auto-embedding

This is the data model for chunks stored in Qdrant:

public sealed class DocumentRecord
{
    [VectorStoreKey]
    public Guid Id { get; set; } = Guid.NewGuid();

    [VectorStoreData]
    public string Text { get; set; } = "";

    [VectorStoreData]
    public string FileName { get; set; } = "";

    [VectorStoreData]
    public int ChunkIndex { get; set; }

    [VectorStoreData(IsIndexed = true)]
    public string Source { get; set; } = "";

    [VectorStoreVector(Dimensions: 384)]
    public string Embedding => Text;
}

The interesting part is the last property. [VectorStoreVector(Dimensions: 384)] on a string property means “embed this text automatically when upserting.” The Embedding property points to Text, so VectorData calls your registered IEmbeddingGenerator, gets the 384-dim vector, and stores it in Qdrant. No manual embedding calls anywhere in the ingestion code.

Registration ties it together:

builder.Services.AddSingleton<VectorStoreCollection<Guid, DocumentRecord>>(sp =>
{
    var embeddingGenerator = sp.GetRequiredService<IEmbeddingGenerator<string, Embedding<float>>>();
    var vectorStore = new QdrantVectorStore(
        sp.GetRequiredService<QdrantClient>(),
        ownsClient: false,
        new QdrantVectorStoreOptions { EmbeddingGenerator = embeddingGenerator }
    );
    return vectorStore.GetCollection<Guid, DocumentRecord>(CollectionName);
});

Pass the embedding generator to the vector store options. From that point, every UpsertAsync call automatically embeds text before storage. Every SearchAsync call automatically embeds the query before searching.

The RAG pipeline

Two phases:

Phase 1: INGEST                      Phase 2: QUERY
─────────────────                    ─────────────────
Upload PDF                           "What does the report say about X?"
  → Extract text (PdfPig)              → Embed query (all-minilm)
  → Chunk (recursive, 128 tokens)      → Vector search (Qdrant, top-5)
  → Auto-embed + upsert (Qdrant)       → LLM generates grounded answer

Ingestion

The ingestion service is straightforward:

public async Task<IngestionRecord> IngestPdfAsync(
    Stream pdfStream, string fileName, string source,
    long fileSizeBytes, CancellationToken ct = default)
{
    await collection.EnsureCollectionExistsAsync(ct);

    var extraction = PdfTextExtractor.Extract(pdfStream);
    var chunks = TextChunker.Chunk(extraction.Text);

    var records = chunks
        .Select((chunk, index) => new DocumentRecord
        {
            Text = chunk,
            FileName = fileName,
            ChunkIndex = index,
            Source = source,
        })
        .ToList();

    await collection.UpsertAsync(records, ct);
}

Notice what’s missing: no embedding calls. collection.UpsertAsync handles it because we configured auto-embedding on the DocumentRecord. PdfPig extracts text (pure .NET, no native dependencies), TextChunker splits it into chunks, and the vector store takes care of the rest.

The chunker is a recursive splitter targeting 128 tokens (~512 chars) with 25-token overlap. It tries paragraph boundaries first (\n\n), then lines (\n), then sentences (. ), then words.

Query

The search adapter creates a function that retrieves relevant chunks:

public static Func<string, CancellationToken, Task<IEnumerable<TextSearchResult>>> Create(
    VectorStoreCollection<Guid, DocumentRecord> collection, int top = 5) =>
    async (query, ct) =>
    {
        var results = new List<TextSearchResult>();
        await foreach (var result in collection.SearchAsync(
            query, top: top, cancellationToken: ct))
        {
            var sourceName = FormatSourceName(
                result.Record.FileName, result.Record.Text);
            results.Add(new TextSearchResult
            {
                Text = result.Record.Text,
                SourceName = sourceName,
                SourceLink = result.Record.Source,
            });
        }
        return results;
    };

collection.SearchAsync takes a plain string query. The vector store auto-embeds it, runs similarity search against Qdrant, and returns matching records. Page numbers are extracted from chunk text via regex and formatted into the source name (e.g., “report.pdf (Page 5)”).

The agent then passes these chunks as context to the LLM with instructions to answer only from the provided context and cite sources.

Aspire orchestration

Here’s the AppHost. This defines the entire system:

var builder = DistributedApplication.CreateBuilder(args);

var ollama = builder
    .AddOllama("ollama")
    .WithImageTag("latest")
    .WithDataVolume()
    .WithLifetime(ContainerLifetime.Persistent);

var llama = ollama.AddModel("llama3.1");
var embedModel = ollama.AddModel("all-minilm");

var qdrant = builder
    .AddQdrant("qdrant", apiKey: builder.AddParameter("qdrant-apikey", "localdev"))
    .WithImageTag("latest")
    .WithDataVolume()
    .WithLifetime(ContainerLifetime.Persistent);

var sqlite = builder
    .AddSqlite("ingestion-db", databasePath: sqlitePath, databaseFileName: "ingestion.db")
    .WithSqliteWeb();

var api = builder
    .AddProject<Projects.CompanyIntel_Api>("api")
    .WithReference(llama)
    .WithReference(embedModel)
    .WithReference(qdrant)
    .WithReference(sqlite);

builder
    .AddJavaScriptApp("ui", "../CompanyIntel.UI", "dev")
    .WithPnpm()
    .WithHttpEndpoint(port: 3000, env: "PORT")
    .WithEnvironment("AGENT_URL", api.GetEndpoint("http"))
    .WithOtlpExporter();

await builder.Build().RunAsync();

dotnet aspire run starts Ollama (pulls models if needed), Qdrant, SQLite with a web UI, the ASP.NET Core API, and the Next.js frontend. WithLifetime(ContainerLifetime.Persistent) means Ollama and Qdrant survive between runs. WithReference injects connection strings automatically — the API project never hardcodes a URL.

RAG evaluation with LLM-as-Judge

This is where Aspire really pays off. The evaluation tests spin up the entire stack — Ollama, Qdrant, API — in ephemeral containers, ingest a test PDF, ask questions, and score the answers using LLM-as-Judge.

The test fixture:

public class AspireAppFixture : IAsyncLifetime
{
    public async ValueTask InitializeAsync()
    {
        var appHost = await DistributedApplicationTestingBuilder.CreateAsync<Projects.CompanyIntel_AppHost>();

        _app = await appHost.BuildAsync(cts.Token);
        await _app.StartAsync(cts.Token);
        await _app.ResourceNotifications.WaitForResourceHealthyAsync("api", cts.Token);

        ApiClient = _app.CreateHttpClient("api", "http");
    }
}

The evaluation itself uses Microsoft.Extensions.AI.Evaluation.Quality, which provides four evaluators:

Metric	What it measures
Relevance	Does the answer address the question?
Coherence	Is the answer well-structured and logical?
Groundedness	Is every claim backed by the retrieved context?
Retrieval	Did the search find the right chunks?

Each evaluator uses the same Ollama llama3.1 as a judge and scores on a 1-5 scale:

[Theory]
[MemberData(nameof(EvalScenarios))]
public async Task EvaluateRagResponseQuality(string question)
{
    var chatResponse = await fixture.ApiClient.PostAsJsonAsync("/api/chat", new { message = question });

    var result = await chatResponse.Content.ReadFromJsonAsync<ChatApiResponse>();

    IChatClient judgeChatClient = new OllamaApiClient(fixture.OllamaEndpoint, "llama3.1");
    var chatConfig = new ChatConfiguration(judgeChatClient);

    IEvaluator[] evaluators =
    [
        new RelevanceEvaluator(),
        new CoherenceEvaluator(),
        new GroundednessEvaluator(),
        new RetrievalEvaluator(),
    ];

    foreach (var evaluator in evaluators)
    {
        var evalResult = await evaluator.EvaluateAsync(
            messages, modelResponse, chatConfig, additionalContext, cts.Token);

        foreach (var metricName in evaluator.EvaluationMetricNames)
        {
            var metric = evalResult.Get<NumericMetric>(metricName);
            Assert.True(metric.Value >= 3,
                $"{metricName} score too low: {metric.Value}");
        }
    }
}

Groundedness is the most interesting metric here. It checks whether every claim in the answer can be traced back to the retrieved context. A score below 3 means the model is hallucinating — making claims the documents don’t support.

Demo

The chat tab. Ask a question, get a grounded answer with citations:

The documents tab. Upload PDFs, see ingestion stats (pages, chunks, size):

Summary

The .NET AI building blocks let you write RAG applications without coupling to a specific provider.

What worked well:

VectorData’s auto-embedding removed all manual embedding calls from the codebase. Define [VectorStoreVector] on a string property, and upsert/search just works.
DelegatingChatClient handled a real compatibility issue (missing MessageId in OllamaSharp streaming) without touching the rest of the code.
Aspire’s DistributedApplicationTestingBuilder made RAG evaluation reproducible: ephemeral containers, random ports, clean state per run.
Microsoft.Extensions.AI.Evaluation.Quality gave us four evaluation metrics out of the box, using the same local LLM as judge.

References

Building RAG with .NET Aspire and Python

Sun, 22 Feb 2026 00:00:00 +0000

TL;DR

I built a RAG-based company research assistant where .NET Aspire orchestrates a Python backend (Pydantic AI + FastAPI), a Next.js frontend (CopilotKit), Qdrant for hybrid vector search, and Ollama for local LLM inference. One dotnet run starts everything. This post walks through the architecture, the RAG pipeline, and how Aspire makes polyglot orchestration and observability surprisingly painless.

Source code: https://github.com/NikiforovAll/company_intel

TL;DR
Introduction
Architecture overview
Aspire as the orchestrator
- Connection strings flow to Python
The RAG pipeline
Observability
RAG evaluation with Aspire
Demo
Summary
References

Introduction

Most RAG tutorials show you the happy path: embed some text, throw it into a vector store, query it. Real systems are messier. You need a scraper, a chunking pipeline, embeddings, a vector store with hybrid search, an LLM, a frontend, and something to wire it all together. Each piece has its own runtime, its own configuration, its own way of failing.

I wanted to build a company research assistant, where you ingest data about companies (websites, Wikipedia, news) and then ask questions with grounded, cited answers. The interesting part isn’t any single component. It’s how they fit together.

.NET Aspire turned out to be the right tool for this. Not because it’s .NET (the backend is Python, the frontend is Node.js), but because it handles the boring-but-hard parts: service discovery, connection string injection, health checks, and OpenTelemetry collection. You define the topology once, run it, and everything talks to everything.

Architecture overview

The system has two phases.

Phase 1️⃣: a backoffice agent scrapes company data, chunks it, embeds it (dense + sparse vectors), and stores everything in Qdrant.
Phase 2️⃣: a chat agent takes user questions, runs hybrid retrieval against Qdrant, and generates grounded answers with citations. No internet access required during query time.

Phase 1: INGEST (online)          Phase 2: QUERY (offline)
─────────────────────────         ────────────────────────
User: "ingest Figma"              User: "Who are competitors?"
  → Scrape websites (Crawl4AI)      → Hybrid retrieval (Qdrant)
  → Clean → Chunk → Embed           → RRF fusion (dense + BM25)
  → Store in Qdrant                 → LLM generates grounded answer

The data flow for queries: UI (CopilotKit) → AG-UI protocol → FastAPI → Pydantic AI agent → Ollama (Qwen3 8B). The agent calls a search_knowledge_base tool that embeds the query, runs hybrid search in Qdrant, applies a context budget, and returns chunks to the LLM.

Aspire as the orchestrator

Here’s the entire AppHost/Program.cs. This is the only .NET code in the project, and it defines everything:

var builder = DistributedApplication.CreateBuilder(args);

var ollama = builder
    .AddOllama("ollama")
    .WithImageTag("latest")
    .WithDataVolume()
    .WithLifetime(ContainerLifetime.Persistent);

var qwen3 = ollama.AddModel("qwen3:latest");
var embedModel = ollama.AddModel("snowflake-arctic-embed:33m");

var qdrant = builder
    .AddQdrant("qdrant", apiKey: builder.AddParameter("qdrant-apikey", "localdev"))
    .WithDataVolume()
    .WithLifetime(ContainerLifetime.Persistent);

var agent = builder
    .AddUvicornApp("company-intel-agent", "../agent", "main:app")
    .WithUv()
    .WithHttpHealthCheck("/health")
    .WithReference(qwen3)
    .WithReference(embedModel)
    .WithReference(qdrant)
    .WithOtlpExporter();

var ui = builder
    .AddNpmApp("ui", "../ui", "dev")
    .WithPnpmPackageInstallation()
    .WithHttpEndpoint(port: 3000, env: "PORT")
    .WithEnvironment("AGENT_URL", agent.GetEndpoint("http"))
    .WithOtlpExporter();

await builder.Build().RunAsync();

A few things worth noting:

AddOllama and AddModel pull and run Ollama as a container, then register specific models. The Python agent gets connection strings for both qwen3 (the LLM) and snowflake-arctic-embed (the embedding model) automatically through WithReference. Qdrant is the same story. WithLifetime(ContainerLifetime.Persistent) means Ollama and Qdrant survive between runs, so you don’t re-download models every time.

AddUvicornApp is a community extension that runs a Python FastAPI app via uvicorn, managed by uv for dependency resolution. Aspire treats it like any other resource: health checks, logs, traces, all piped into the dashboard.

AddNpmApp does the same for the Next.js frontend. WithPnpmPackageInstallation runs pnpm install on startup. The AGENT_URL environment variable points the frontend at the Python backend, and Aspire resolves the endpoint dynamically.

Connection strings flow to Python

When Aspire starts the Python agent, it injects environment variables like ConnectionStrings__ollama-qwen3 with the format Endpoint=http://localhost:XXXX;Model=qwen3:latest. The Python side parses these in settings.py

No hardcoded URLs. No .env files to manage. Aspire assigns ports dynamically, and the Python code just reads them. If you add a second Qdrant instance or swap Ollama for a remote endpoint, you change the AppHost, not the Python code.

The RAG pipeline

Ingestion

The ingestion pipeline in pipeline.py is straightforward: load raw documents, chunk them, embed them, upsert to Qdrant.

async def ingest_company(company: str, data_dir: Path) -> IngestionResult:
    with logfire.span("ingest_company {company}", company=company):
        store = get_vectorstore()
        store.delete_company(company)  # idempotent: wipe and re-ingest

        docs = load_raw_documents(company, data_dir)
        chunks = chunk_documents(docs)

        embedder = get_embedder()
        texts = [c.text for c in chunks]
        dense, sparse = await embedder.embed_texts(texts)

        total = store.upsert_chunks(chunks, dense, sparse)
        return IngestionResult(
            company=company,
            documents_loaded=len(docs),
            chunks_produced=len(chunks),
            vectors_stored=total,
        )

The chunking is semantic: split by headings, then paragraphs, then sentences, targeting 256-512 tokens with 50-token overlap. Each chunk gets both a dense vector (from snowflake-arctic-embed-s, 384 dimensions) and a sparse BM25 vector via fastembed.

Hybrid retrieval

The query side uses Qdrant’s prefetch + fusion to combine dense and sparse search:

def search(self, dense_vector, sparse_vector, company=None, limit=SEARCH_FUSION_LIMIT):
    query_filter = None
    if company:
        query_filter = Filter(must=[
            FieldCondition(key="company", match=MatchValue(value=company.strip().lower()))
        ])

    response = self._client.query_points(
        collection_name=COLLECTION_NAME,
        prefetch=[
            Prefetch(
                query=dense_vector,
                using=DENSE_VECTOR_NAME,
                score_threshold=DENSE_SCORE_THRESHOLD,
                limit=SEARCH_DENSE_LIMIT,
            ),
            Prefetch(
                query=SparseVector(indices=sparse_vector.indices, values=sparse_vector.values),
                using=SPARSE_VECTOR_NAME,
                limit=SEARCH_SPARSE_LIMIT,
            ),
        ],
        query=FusionQuery(fusion=Fusion.RRF),
        query_filter=query_filter,
        limit=limit,
        with_payload=True,
    )
    # ... return results

Two prefetch branches run in parallel inside Qdrant: top-10 dense results and top-10 sparse results. Reciprocal Rank Fusion (RRF) merges them into a single ranked list. Dense search catches semantic similarity; sparse search catches exact keyword matches. The combination is more robust than either alone.

The agent then generates an answer with inline citations from the retrieved chunks based on agent’s system prompt.

Streaming to the frontend

The FastAPI backend uses the AG-UI protocol (via pydantic_ai.ui.ag_ui.AGUIAdapter) to stream agent responses as server-sent events. The frontend uses CopilotKit, which connects to the Python backend through an HttpAgent:

@app.post("/")
async def run_agent(request: Request) -> Response:
    with logfire.span("agent request"):
        response = await AGUIAdapter.dispatch_request(request, agent=agent)
        return response

One line dispatches the request. CopilotKit on the React side handles message rendering, tool call visualization, and streaming updates.

Observability

🤔 Getting OpenTelemetry from Python into the Aspire dashboard has a catch: Python’s OTLP exporter defaults to gRPC, but Aspire’s gRPC endpoint requires HTTP/2 with ALPN, which Python’s grpcio doesn’t support. The fix is to use HTTP/protobuf instead:

def _configure_aspire_otlp() -> None:
    http_endpoint = os.environ.get("DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL")
    if http_endpoint:
        os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = http_endpoint
        os.environ["OTEL_EXPORTER_OTLP_PROTOCOL"] = "http/protobuf"

Aspire sets DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL automatically via WithOtlpExporter(). The Python code picks it up and redirects telemetry to the HTTP endpoint.

🤔 Another gotcha: the Aspire dashboard can’t render exponential histograms, so you need explicit bucket histograms. Logfire’s defaults use exponential, so the code overrides them with ExplicitBucketHistogramAggregation.

Once configured, you get distributed traces across the entire request path: HTTP request → agent execution → embedding → Qdrant search → LLM generation. All visible in the Aspire dashboard alongside the .NET services.

Logfire instruments Pydantic AI and HTTPX automatically:

logfire.configure(service_name="company-intel-agent", send_to_logfire=False)
logfire.instrument_pydantic_ai() # adds Semantic Conventions for Generative AI
logfire.instrument_httpx()

This gives you GenAI semantic conventions (token usage per LLM call) and HTTP client spans for free.

Here’s what a distributed trace looks like for a backoffice ingestion request. You can see every span: the agent run, scraping (Wikipedia, website, search), and the final ingestion into Qdrant:

And the metrics view, showing scraper page content size broken down by source type:

RAG evaluation with Aspire

Here’s where Aspire really pays off. The eval test uses DistributedApplicationTestingBuilder to spin up the entire stack, a fresh Qdrant, Ollama, and the Python agent, run ingestion against a golden dataset, then check retrieval quality:

[Fact]
public async Task RetrievalQualityMeetsThresholds()
{
    var appHost = await DistributedApplicationTestingBuilder.CreateAsync<Projects.AppHost>(
        ["UseVolumes=false"],  // fresh Qdrant, no stale data
        (appOptions, _) => appOptions.DisableDashboard = true,
        cts.Token
    );

    await using var app = await appHost.BuildAsync(cts.Token);
    await app.StartAsync(cts.Token);

    await app.ResourceNotifications.WaitForResourceHealthyAsync(
        "company-intel-agent", cts.Token
    );

    using var http = app.CreateHttpClient("company-intel-agent");

    // Start eval, poll until done, assert thresholds
    var startResp = await http.PostAsJsonAsync("/eval/run", new { company = "paypal" }, cts.Token);
    // ... poll status ...

    Assert.True(status.Metrics!.HitRate >= 0.50);
    Assert.True(status.Metrics!.ContextRecall >= 0.50);
}

UseVolumes=false ensures a clean Qdrant on every run. No leftover data from previous tests. Aspire assigns random ports, so there are no conflicts if you run tests in parallel. The test exercises the real ingestion and retrieval pipelines, not a mock.

The eval itself uses substring matching: each query in the golden dataset has expected facts, and the test checks whether retrieved chunks contain those facts. No LLM-as-judge needed for this; deterministic substring matching gives reliable signal in seconds instead of minutes.

🤔 We could use LLM-as-judge for a more semantic evaluation, but that would require a fast local model. Qwen3 8B is good for generation but slow for evaluation, so substring matching was a pragmatic choice here.

Two metrics: Hit Rate (did at least one expected fact get retrieved?) and Context Recall (what fraction of expected facts were found?). Both must exceed 50% or CI fails.

Demo

The chat tab. Ask a question, get a grounded answer with citations from the knowledge base:

Multi-company research with detailed, structured answers:

The backoffice tab. Tell it to gather data for a company, and it scrapes, chunks, embeds, and stores everything in the background:

Summary

The main takeaway: Aspire isn’t just for .NET microservices. It’s a polyglot orchestrator. If your system has containers, Python apps, and Node.js frontends that need to discover each other and report telemetry to the same place, Aspire handles that with less configuration than Docker Compose.

What worked well:

Connection string injection removed all hardcoded URLs from Python code
WithOtlpExporter() gave the Python agent observability for free (once you work around the HTTP/2 issue)
DistributedApplicationTestingBuilder made RAG evaluation reproducible: fresh stack per test, no manual setup

What I’d do differently next time: use a remote LLM for evaluation instead of local Qwen3. Substring matching works, but semantic matching would catch paraphrased facts. That needs a fast model though, not a 8B one running on CPU.

References

Risks of AI-Assisted Development

Sun, 15 Feb 2026 00:00:00 +0000

TL;DR

AI coding tools are powerful but come with real risks: unsolved prompt injection vulnerabilities, subtle bugs that pass review because they “look right,” cognitive shifts from writing to reading code, measurable skill degradation, and unclear ROI. None of these mean you should stop using AI — they mean you should use it with open eyes. Review AI-generated code harder, write code by hand regularly, and make sure fundamentals come before delegation.

TL;DR
Introduction
1️⃣ Security: prompt injection is unsolved
2️⃣ Subtle bugs: the “looks right” problem
3️⃣ Cognitive shift: reading vs. writing code
4️⃣ Skill degradation: knowing when to learn
5️⃣ Cost: the enterprise pricing question
What to do about all this

Introduction

AI coding tools are useful. They’re also new enough that we’re still figuring out what goes wrong when you lean on them too hard. This post covers the real risks — not to scare anyone off, but because using a power tool without understanding its failure modes is how you lose a finger.

AI is a tool. Treat it like one. A table saw doesn’t care about your fingers, and a language model doesn’t care about your codebase.

1️⃣ Security: prompt injection is unsolved

Every AI tool that processes external input is vulnerable to prompt injection. This is not a theoretical concern — it’s a known, actively exploited class of vulnerability with no general solution today.

The core problem: language models can’t reliably distinguish between instructions and data. If your application feeds user input into a prompt, an attacker can hijack the model’s behavior. Filters and guardrails help, but they’re mitigations, not fixes. Researchers keep finding bypasses.

What this means in practice:

Code that calls AI APIs with user-supplied content needs the same scrutiny as code that builds SQL queries from user input
AI-generated code may introduce vulnerabilities the model doesn’t flag — it optimizes for “looks correct,” not “is secure”
Supply chain concerns multiply when AI suggests dependencies it was trained on but hasn’t vetted

Until prompt injection has a real solution (and there’s no timeline for that), treat AI-touching-external-input as a threat surface.

2️⃣ Subtle bugs: the “looks right” problem

AI-generated bugs are different. The code reads clean. Variable names are reasonable. The structure follows conventions. Everything looks right. And buried inside is a logic error that won’t surface until production — a race condition, an off-by-one in business logic, a null check that misses an edge case.

This is genuinely dangerous. Code review relies partly on pattern recognition — reviewers notice when something “feels off.” AI-generated code doesn’t trigger that instinct because it’s optimized for readability, not correctness. The model produces text that looks like working code based on statistical patterns. Sometimes that’s working code. Sometimes it’s convincingly wrong.

The defense is old-fashioned: tests, assertions, thorough reviews, and healthy skepticism. Don’t trust code more because it reads well. Read it harder because it reads well.

3️⃣ Cognitive shift: reading vs. writing code

Writing code and reading code use different parts of your brain. Writing forces you to think through logic step by step — you’re constructing. Reading is pattern matching — you’re recognizing.

Neuroscience calls this the “generation effect” (documented since 1978): you need to do something to truly know it. Flash card experiments showed that generating a word from a partial cue created dramatically better recall than just reading the complete word. Brain scans confirm it — generating thoughts from scratch lights up multiple brain regions simultaneously. Reading or hearing information barely registers by comparison.

When AI writes the code and you review it, you’re always in reading mode. You lose the constructive thinking that comes from writing. Over months and years, that changes how you relate to code. You get better at skimming and approving, worse at building from scratch.

An MIT study put numbers on this. Researchers monitored brain activity (EEG) while students wrote essays under three conditions: unassisted, AI-assisted, and AI-after-outlining. The AI-assisted group showed significantly lower brain activity and neural connectivity while working. And here’s the telling part: 83% of the ChatGPT group couldn’t recall a single sentence from their own essay minutes after finishing. The essays were technically fine — grammatically correct, well-structured — but evaluators consistently called them “hollow” and “soulless.” The students produced text without thinking. It showed.

This isn’t hypothetical. Developers who rely heavily on autocomplete and generation tools report feeling less confident writing code without them. The skill atrophies like any unused muscle.

The risk isn’t that AI makes you a worse developer tomorrow. It’s that two years from now, you can’t write a moderately complex function without reaching for a tool. And when the tool is wrong (see previous section), you can’t tell.

Deliberate practice matters. Write code by hand regularly. Solve problems without AI assistance. Keep the muscle working.

4️⃣ Skill degradation: knowing when to learn

There’s a difference between delegating a task you understand and delegating a task you’ve never learned. AI blurs this line.

If a senior developer uses AI to generate boilerplate they’ve written hundreds of times — fine. They know what correct looks like. They’ll spot problems. But if a junior developer uses AI to skip learning how authentication works, or how database transactions behave, they’re building on a foundation they don’t have.

The evidence from other fields is blunt:

London taxi drivers — who navigate from memory — had physically larger brain regions for spatial reasoning than average. Drivers who switched to GPS experienced measurable gray matter shrinkage in those same regions.
Doctors who used AI diagnostic assistance for just four months showed weakened ability to spot cancer independently afterward.
In a study by Christof Van Nimwegen, participants who solved logic puzzles with software assistance collapsed when the software was taken away — they “aimlessly clicked around” while the unassisted group kept improving.

The pattern repeats: outsource a cognitive function to a tool, and the brain physically downsizes for that function. There’s no reason to think coding is exempt.

The uncomfortable truth: AI makes it easy to produce code you don’t understand. And for a while, that works. You ship features, hit deadlines, look productive. The gap shows up when something breaks in an unfamiliar way, or when you need to design something the model hasn’t seen, or when you’re in a meeting and can’t explain your own system.

Know the difference between “I’m using AI to go faster at something I know” and “I’m using AI to avoid learning something I should know.” The second one has a cost, and you pay it later.

5️⃣ Cost: the enterprise pricing question

AI tooling isn’t cheap. Enterprise tiers, additional API usage for agentic workflows, premium models — the bill adds up. For a team of 100 developers, you’re looking at $25-50K/year just for Copilot licenses, potentially much more with heavy agentic usage.

The ROI question remains genuinely open. Vendors cite productivity studies, but most of those measure speed on isolated tasks, not long-term codebase quality or maintenance costs. Nobody has strong longitudinal data yet.

Meanwhile, pricing models keep changing. What costs $19/month today might cost $39 tomorrow if vendors decide the market will bear it. Or it might get cheaper as competition increases. Nobody knows, and that uncertainty makes long-term budgeting harder than anyone admits.

Organizations should treat AI tool spend like any other infrastructure cost: measure what you can, set budgets, and be honest about what you don’t know yet. “Everyone else is paying for it” is not a strategy.

What to do about all this

None of these risks mean you should avoid AI tools. They mean you should use them with open eyes.

Review AI-generated code with more scrutiny, not less
Maintain security practices around any AI-facing surface
Write code by hand regularly to keep your skills sharp
Make sure junior developers learn fundamentals before leaning on generation
Think first, then delegate — outline your approach before handing work to AI (the MIT study found this group had higher brain connectivity than even the unassisted group)
Track your AI tool costs and measure outcomes honestly
Stay current on prompt injection research — the landscape changes fast

The developers who’ll get the most from AI tools long-term are the ones who understand both the capabilities and the failure modes. Blind trust and blind rejection are equally wasteful.

Observing Claude Code Task Orchestration in Real Time using 'claude-code-kanban'

Sat, 07 Feb 2026 00:00:00 +0000

TL;DR: claude-code-kanban is a real-time Kanban dashboard for Claude Code teams. Tasks flow through Pending → In Progress → Completed in your browser.

One command: npx claude-code-kanban.

Source code: github.com/NikiforovAll/claude-task-viewer

Why I built this

I was running a Claude Code team, a lead agent coordinating three specialists to implement an auth module. Around minute five I realized I had no idea what was happening. One agent was blocked, another had finished, the lead was assigning new work.

Claude Code has a built-in task list, but it’s limited. You see a flat list of tasks in the terminal. No visual grouping by status, no dependency graph, no way to track multiple agents at a glance. When you have four agents working in parallel, that’s not enough.

I wanted to glance at something and immediately know: what’s done, what’s stuck, what’s next. So I built a Kanban board that watches Claude Code’s task files and streams updates to a browser.

What it looks like

Three columns: Pending, In Progress, Completed. Each task card shows its assigned agent (color-coded), a short description, and which tasks it’s waiting on.

The sidebar lists sessions with progress bars. A live feed shows what agents are doing right now. You can filter by project, search by name, or toggle between active and all sessions.

Clicking a task opens the detail panel: full description, dependencies, and a note field. The notes are readable by Claude too, so you can leave instructions mid-session.

What you actually get

The dashboard auto-detects team sessions. Each agent gets a consistent color across the board. You can filter by owner to isolate one agent’s work or see everything at once. Session cards show team member count and names.

Blocked tasks show “Waiting on #X, #Y” labels. If you try to delete a task that blocks others, the dashboard stops you and shows which tasks would break. This is how you find bottlenecks: three tasks all waiting on one means that’s your critical path.

Press P to view the session plan with syntax-highlighted code blocks. Press I for session info: team members, project path, git branch. I check these first when coming back to a session.

The whole thing is keyboard-driven. Arrow keys navigate tasks, Tab switches between sidebar and board, Enter opens details, Esc closes panels. ? shows all shortcuts.

Dark and light themes. The dark one has a “Terminal Luxe” aesthetic. Preference sticks across sessions.

Getting started

npx claude-code-kanban

That’s it. The server starts on port 3456 and opens your browser. Start a Claude Code session with teams and the dashboard picks it up automatically, no configuration needed.

What’s next

The tool is observation-only by design. Claude Code owns the task state and I want to keep that boundary clean. But the observation side has room to grow: timeline views, session comparison, maybe export for sharing with people who aren’t staring at the terminal.

References

LazyClaude 0.12.0: Marketplace Plugin Management

Sun, 21 Dec 2025 00:00:00 +0000

TL;DR

LazyClaude is a keyboard-driven TUI for managing Claude Code customizations (slash commands, subagents, skills, MCPs, hooks). Version 0.12.0 introduces a built-in marketplace browser that lets you discover, preview, and install plugins without leaving the terminal. If you’re new to LazyClaude, check out the original announcement for a full introduction.

Source: github.com/NikiforovAll/lazyclaude

Install: uvx lazyclaude

Why LazyClaude?

Managing Claude Code customizations means navigating multiple configuration directories (~/.claude/, ./.claude/, ~/.claude/plugins/) and understanding what’s defined at each level. LazyClaude gives you a visual, keyboard-driven interface that shows everything in one place.

Key Benefits:

Visual Exploration: See all customizations organized by type (slash commands, subagents, skills, memory files, MCPs, hooks)
Multi-Level Management: Understand and manage configurations across user, project, and plugin levels
Keyboard-Driven Workflow: Navigate with vim-style keys (j/k), no mouse required
Copy/Move Between Levels: Easily share personal configs with your team or customize plugin content
Integrated Marketplace: Discover and install plugins without leaving the terminal (new in 0.12.0!)

Getting Started

Launch with uvx lazyclaude and you’ll see a multi-panel interface inspired by lazygit:

Interface Overview:

Left Sidebar: Panels for each customization type ([1] Slash Commands, [2] Subagents, [3] Skills, [4] Memory, [5] MCPs, [6] Hooks)
Right Pane: Content and metadata view for the selected item
Status Bar: Shows current path and active filter
Footer: Keyboard shortcuts reference

Quick Navigation:

1-6 or Tab - Switch between panels
j/k or arrow keys - Navigate items
[ / ] - Toggle between content and metadata views
? - Show help, q - Quit

Core Workflows

Filtering and Viewing Configurations

LazyClaude helps you understand where customizations are defined. Use filters to narrow your view:

a - Show All levels
u - Show only User level (~/.claude/)
p - Show only Project level (./.claude/)
P - Show only Plugin level (~/.claude/plugins/)
D - Toggle visibility of disabled plugins

This makes it easy to:

See what’s personal vs. shared with your team
Understand what comes from installed plugins
Find where a specific customization is defined

Editing and Managing Configurations

e - Open in your $EDITOR
c - Copy to another level (e.g., copy plugin config to user level to customize)
m - Move to another level
C - Copy file path to clipboard

Common Patterns:

Customize a Plugin:

[P]lugin → navigate → [c]opy → User → [e]dit

Share with Team:

[u]ser → navigate → [c]opy → Project → git commit

What’s New in 0.12.0: Marketplace Browser

Version 0.12.0 adds integrated marketplace support. Press M to open the marketplace browser:

Browse and Install Plugins

Navigate available plugins with vim-style keys (j/k), expand marketplace trees with l, and install plugins with i.

Marketplace Actions:

i - Install plugin (or enable if disabled)
d - Uninstall plugin
e - Open plugin folder in file manager
/ - Search within marketplace

Preview Before Installing

Press p on any plugin to enter preview mode. The marketplace closes and the main interface shows you all the plugin’s contents (slash commands, skills, etc.) in read-only mode. Explore what you’re getting before you install it.

Preview Mode Benefits:

View all customizations included in a plugin
Read content and metadata without installing
Understand plugin structure and capabilities
Navigate as if the plugin were installed (read-only)

Press Esc to exit preview mode and return to the normal view.

Conclusion

LazyClaude 0.12.0 makes managing Claude Code customizations visual, keyboard-driven, and efficient. The new marketplace browser brings plugin discovery and installation directly into the terminal, completing the workflow. Whether you’re exploring your existing setup, customizing plugins, or sharing configurations with your team, LazyClaude provides the tools you need without leaving the command line.

Get Started:

uvx lazyclaude

For complete documentation on all features and workflows, check out the user guide.

LazyClaude: Explore Your Claude Code Setup Without Breaking Flow

Sun, 07 Dec 2025 00:00:00 +0000

TL;DR

Claude Code’s customization system is powerful but scattered across multiple files and configuration levels. LazyClaude is a lazygit-inspired terminal UI that lets you explore all your customizations—slash commands, agents, skills, MCPs, hooks, and memory files—in one place. Filter by level (user/project/plugin), search by name, and navigate with vim-style keybindings.

Source: github.com/NikiforovAll/lazyclaude

Install: uvx lazyclaude

Introduction

Claude Code has a rich customization system. You can define custom slash commands, create specialized agents, configure MCP servers, set up hooks, and write memory files that shape how Claude understands your project. The problem? These customizations live in different places:

~/.claude/ for user-level configuration
.claude/ for project-specific settings
Plugin directories for third-party extensions

When you need to find a specific command or understand what’s available, you’re left running /help, /mcp, /agents, or opening files one by one. Each lookup interrupts your flow.

LazyClaude solves this by providing a dedicated terminal UI where you can browse all your Claude Code customizations without leaving your workflow.

What is LazyClaude?

LazyClaude is a terminal user interface that follows the design philosophy of lazygit: keyboard-driven, panel-based, and focused on getting information quickly.

See README for more details.

Getting Started

Install with uv:

uvx lazyclaude

Conclusion

LazyClaude brings visibility to Claude Code’s configuration system. Instead of hunting through files or interrupting your workflow with help commands, you get a dedicated window showing everything at a glance.

It’s keyboard-first, fast, and stays out of your way—exactly what a developer tool should be.

Source code: https://github.com/NikiforovAll/lazyclaude

Contributions welcome. Try it, break it, and let me know what customizations you discover.

References

VSCode Morph Agent: Let AI Control Your Workspace

Mon, 01 Dec 2025 00:00:00 +0000

TL;DR

What if AI agents could not only write code but also organize your workspace? Morph Agent is a VSCode extension that lets AI control your editor layout through natural language. It’s a proof of concept demonstrating a powerful principle: agents should be able to manipulate the ambient environment to help us focus on what matters.

Source: github.com/NikiforovAll/vscode-morph

Install: VSCode Marketplace

Introduction

Modern software development increasingly involves working with multiple artifacts simultaneously—specifications, implementation plans, task lists, code files, tests, and documentation. When using AI coding assistants, this complexity multiplies: you’re juggling context windows, chat panels, terminal output, and reference materials.

The problem isn’t just having the right files open—it’s having them arranged in a way that supports your current workflow. Manually reorganizing your workspace breaks your flow. What if your AI assistant could do this for you?

Morph Agent explores this idea. It’s a VSCode extension that gives AI the ability to control your editor layout. Through GitHub Copilot Chat, you can describe how you want your workspace arranged, and Morph makes it happen.

The idea is based on a simple principle: AI should control the ambient workspace, not just the code.

Furthermore, an agent should be able to produce additional tools or UI elements to facilitate better interaction with the user.

Find this Principle in the Other Tools

For example, in Claude Code, the user is presented with a special tool to clarify questions - AskUserQuestion. This tool opens a special input inside the terminal so that the user can provide input back to the agent. This is a great example of an agent manipulating the ambient environment to facilitate better interaction.

What is Morph Agent?

Morph Agent bridges the gap between natural language intent and editor configuration. It provides:

Natural Language Layout Control — Use @morph-layout in Copilot Chat to request arrangements like “split my files side by side” or “open the tests next to the implementation”
KDL Layout DSL — A declarative configuration language (KDL) for precise, reproducible layouts
Bidirectional Conversion — Capture your current layout as KDL code, or apply KDL to transform your workspace

The key insight is that layouts become first-class artifacts. You can version control them, share them with your team, and let AI generate them contextually.

The KDL Format

KDL (pronounced “cuddle”) is a minimal document language perfect for configuration. Here’s a quick taste:

Side-by-side:

layout {
  cols {
    group { file "src/main.ts" }
    group { file "src/test.ts" }
  }
}

Stacked:

layout {
  rows {
    group { file "README.md" }
    group { file "CHANGELOG.md" }
  }
}

2x2 Grid:

layout {
  rows {
    cols {
      group { file "a.ts" }
      group { file "b.ts" }
    }
    cols {
      group { file "c.ts" }
      group { file "d.ts" }
    }
  }
}

Here is a demo showing different layout configurations being applied:

Scenario 1: Agentic Coding Layout

When working with AI coding assistants, I find myself constantly arranging windows: specification on one side, implementation plan visible, chat ready for questions, terminal for running tests. Setting this up manually each session is tedious.

With Morph, I can define a persistent layout configuration:

window {
  layout {
    cols {
      rows size="60" {
        cols size="50" {
          group size="50" { file "spec.md" }
          group size="50" { file "plan.md" }
        }
        group size="50" { file "extension.ts" }
      }
      rows size="40" {
        group size="80" { chat }
        group size="20" { terminal }
      }
    }
  }
}

This layout gives me:

Top-left: Spec and plan files side by side (reference materials)
Bottom-left: The code I’m working on
Right side: AI chat (80%) and terminal (20%)

Save this as .layout.kdl in your project, and you can restore it instantly next time you return to work on the same project. Your workspace becomes reproducible.

Scenario 2: Spec-Driven Development

Spec-driven development follows a natural progression:

spec.md → plan.md → tasks.md → implementation

At each stage, different files are relevant. Instead of manually opening and closing files, imagine an agent that understands where you are in the workflow and adjusts the workspace accordingly.

When you’re in the planning phase:

layout {
  cols {
    group size="50" { file "spec.md" }
    group size="50" { file "plan.md" }
  }
}

When you move to implementation:

layout {
  cols {
    group size="30" { file "plan.md" file "tasks.md" }
    group size="70" { file "src/feature.ts" }
  }
}

The workspace morphs to match your mental context. This is the kind of ambient intelligence that makes AI assistants truly helpful.

Scenario 3: Context-Aware File Opening

Sometimes the agent just needs to show you the right files. During a conversation about testing, the agent might realize you need to see both the implementation and its tests:

layout {
  file "extension.ts" "test/parser.test.ts"
}

Or when debugging an issue across multiple files:

layout {
  cols {
    group { file "src/parser.ts" }
    group { file "src/compiler.ts" }
    group { file "src/types.ts" }
  }
}

The agent opens exactly what’s relevant based on the conversation context, providing better assistance through relevant file visibility.

The Future Vision

Morph Agent is just a proof of concept, but it demonstrates a principle I believe will become fundamental to agentic coding:

Agents will manipulate the ambient workspace to help us focus.

Today’s coding assistants are constrained to text—they can read and write code, but they can’t:

Open relevant files when discussing a topic
Arrange windows to match your workflow
Adjust the environment based on the task at hand

This will change. Future agents will:

Understand workflow phases and adapt the workspace automatically
Learn your preferences and suggest layouts based on past behavior
Coordinate multiple tools — editor, browser, documentation, terminal — as a unified environment
Preserve context across sessions, restoring not just files but the entire cognitive workspace

The interface between human and AI isn’t just about generating code. It’s about shaping the environment where that code gets written.

Getting Started

Install Morph Agent from the VSCode Marketplace.

Try it out:

Open Copilot Chat
Type @morph-layout generate a grid layout and apply from opened files
Watch your workspace transform

Or create a .layout.kdl file in your project and use the “Apply Layout” CodeLens to restore your preferred arrangement.

Conclusion

Morph Agent is an experiment in giving AI control over the workspace—not just the code. It’s a small step toward a future where agents understand not just what we’re building, but how we work.

The source code is available on GitHub. Try it, break it, and imagine what ambient AI assistance could look like.

References

Transform .NET Diagnostics into a Specialized AI Agent with Claude Agent SDK

Tue, 11 Nov 2025 00:00:00 +0000

TL;DR

Transform dotnet format from a CLI tool into a conversational AI agent that helps you explore and manage technical debt interactively. Learn the pattern by building with Claude Agent SDK. This blog post demonstrates how to use claude-agent-sdk to wrap dotnet format commands, expose them via MCP, and create a conversational interface for code quality analysis.

Note: You could use a general-purpose AI agent to analyze dotnet format output by copying and pasting JSON reports. However, a specialized agent offers significant advantages: it automates tool execution, maintains context across multiple queries, provides domain-specific insights, and creates a streamlined workflow. This post shows you how to build one. Also, it is kind of fun! 🎉

TL;DR
Why Build Specialized Agents?
Architecture Overview
Building with Claude Agent SDK
Demo: Interactive Code Quality
The Pattern: Reusable Building Blocks
Conclusion
References

Source code: https://github.com/NikiforovAll/dotnet-format-agent

Why Build Specialized Agents?

.NET projects often accumulate hundreds of diagnostics - formatting issues, analyzer warnings, code style violations. These can come from your IDE, dotnet format, or code analysis tools. The real challenge isn’t finding issues - it’s dealing with the overwhelming volume:

# Run format check
$ dotnet format --verify-no-changes --severity warn

# Result: 247 diagnostics across 45 files
# IDE0055, CA1031, IDE1006, CA2007, IDE0290...
# Which ones matter? Where do I start? What's safe to auto-fix?

You’re faced with questions:

🤔 Which issues should I tackle first?
🤔 What’s safe to auto-fix vs. needs manual review?
🤔 Which diagnostics indicate real problems vs. style preferences?
🤔 How do I prioritize across multiple files and rule types?

Manual triage is exhausting: you need to look up diagnostic IDs, assess their impact, decide on priorities, and then repeat this process for every single issue. But here’s the reality - you probably don’t have time for this. You’ve got features to ship, bugs to fix, and meetings to attend. Code quality is important, but it’s rarely urgent.

So what happens? You see 247 warnings and think: “I’ll deal with this later.” Except later never comes. Or worse - you start ignoring warnings entirely. When everything is highlighted as a problem, nothing feels like a problem. The warnings lose their meaning, and suddenly you’ve defeated the whole purpose of having code quality tools in the first place.

Codebase maintainability matters, but it needs to fit into your actual workflow. You need a way to quickly understand what’s important, what can wait, and what’s safe to fix right now - without spending hours analyzing diagnostics.

What if you could just have a conversation? Instead of parsing diagnostics yourself, ask: “What are the most important issues to fix first?” or “What can I safely auto-fix without breaking anything?”

That’s what specialized agents enable - they transform CLI tools into conversational interfaces that help you explore, triage, and prioritize diagnostic output in minutes.

Architecture Overview

A specialized agent has three layers:

Layer 1: Conversational Interface
What users interact with - plain English queries like “Show me formatting issues”

Layer 2: Agent Harness (Claude Agent SDK)
Understands intent, calls appropriate tools, formats responses intelligently

Layer 3: Tool Layer
Wraps dotnet format commands, parses output, returns structured data

The key insight: Keep your tool layer independent. The agent is just a conversational wrapper around existing functionality.

Building with Claude Agent SDK

Let’s build the agent piece by piece using the Claude Agent SDK.

Tool Layer: Wrapping `dotnet format`

Start with a clean abstraction over dotnet format:

class DotnetFormatRunner:
    """Wraps dotnet format CLI with structured input/output."""
    
    def run_style_check(self, project_path: str,severity: str | None = None) -> dict:
        """Run dotnet format style check."""

        # Build command
        cmd = ["dotnet", "format", "--verify-no-changes", "--report", "report.json"]
        if severity:
            cmd.extend(["--severity", severity])
        # Execute
        result = subprocess.run(cmd, capture_output=True, cwd=project_path)
        # Parse JSON report
        with open("report.json") as f:
            diagnostics = json.load(f)

        # Return structured data
        return {
            "diagnostics": diagnostics,
            "summary": self._generate_summary(diagnostics)
        }

Key principles:

✅ Accept structured inputs (paths, options)
✅ Return structured outputs (dicts with diagnostics)
✅ Handle errors gracefully
✅ Keep it testable without AI

Agent Layer: MCP Integration

The Model Context Protocol (MCP) is how Claude discovers and calls your tools. Using the Claude Agent SDK, expose your runner as MCP tools:

from claude_agent_sdk import tool

@tool(
    "extract_style_diagnostics",
    "Extract code style/formatting diagnostics from dotnet format",
    {"severity": str, "exclude": list[str]}
)
async def extract_style_diagnostics(args: dict) -> dict:
    # Normalize inputs (AI might send unexpected formats)
    severity = args.get("severity")
    if severity in ["all", "None", "", None]:
        severity = None
    
    # Call your existing tool
    runner = DotnetFormatRunner()
    result = runner.run_style_check(project_path=os.getcwd(),severity=severity)
    
    # Format response using TOON (Terminal Object Notation)
    # This reduces token usage by 30-60% compared to JSON
    formatted = format_diagnostics_toon(result["diagnostics"])
    
    return {
        "content": [{
            "type": "text",
            "text": formatted
        }]
    }

Why TOON format? Instead of verbose JSON:

[
  {"file": "Program.cs", "line": 10, "rule": "IDE0055", "message": "Fix formatting"},
  {"file": "Program.cs", "line": 15, "rule": "IDE0055", "message": "Fix formatting"}
]

Use compact format:

IDE0055 (count: 2):
  Program.cs:10
  Program.cs:15

This is easier to read and uses fewer tokens = lower costs.

Bundle tools into an MCP server:

from claude_agent_sdk import create_sdk_mcp_server

# Create MCP server with all your tools
dotnet_format_server = create_sdk_mcp_server(
    name="dotnet-format",
    version="1.0.0",
    tools=[
        extract_style_diagnostics,
        extract_analyzers_diagnostics,
        # ... more tools
    ]
)

Making It Conversational

Configure the agent with your MCP server and system prompt:

from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient

options = ClaudeAgentOptions(
    # Connect MCP servers
    mcp_servers={"dotnet-format": dotnet_format_server},
    # Which tools to enable
    allowed_tools=[
        "mcp__techdebt__extract_style_diagnostics",
        "mcp__techdebt__extract_analyzers_diagnostics",
        "Read",
        "Write",
        "Edit",
        "Glob",
        "Grep",
        "WebFetch"
    ],
    # Working directory
    cwd=os.getcwd(),
    # Auto-approve tool calls
    permission_mode="bypassPermissions",
    # System prompt
    system_prompt={
        "type": "preset",
        "preset": "claude_code",  # Base Claude Code behavior
        "append": """
You are a .NET code quality expert specializing in technical debt analysis.

When analyzing codebases:
1. Use 'warn' severity by default
2. Group similar issues together
3. Prioritize by impact and fix difficulty
4. Always include "Next Steps" section
"""
    }
)

# Run the agent
async with ClaudeSDKClient(options=options) as client:
    await client.query("What are the most important code quality issues?")
    
    async for message in client.receive_response():
        # Display response (markdown formatted)
        print(message.text)

The system prompt is crucial - it teaches the agent:

✅ Domain expertise (.NET, diagnostics)
✅ Tool usage patterns (default to ‘warn’ severity)
✅ Response formatting (Markdown, sections)
✅ Output structure (always include Next Steps)

Demo: Interactive Code Quality

$ uv run --package tda tda "List  grouped analyzers diagnostics" --cwd ../path/to/project --interactive
Technical Debt Agent
Working directory: ~/dev/path/to/project
Model: claude-sonnet-4-5
Type 'exit' or 'quit' to end the session.

You> List analyzers diagnostics grouped by diagnostic

*Agent Response Truncated*

Would you like me to drill down into any specific diagnostic code or analyze particular files where these issues occur?

Cost: $0.0886

The Pattern: Reusable Building Blocks

Every specialized agent follows this recipe:

1. Tool Layer (what you already have)

class YourToolRunner:
    def run_analysis(self, path: str, options: dict) -> dict:
        # Call external tool
        # Parse output  
        # Return structured data

2. Agent Layer (MCP wrapper)

@tool("your_tool", "description", {schema})
async def your_tool(args: dict) -> dict:
    result = runner.run(...)
    return {"content": [{"type": "text", "text": formatted_result}]}

server = create_sdk_mcp_server(tools=[your_tool])

3. Conversational Interface (configure agent)

options = ClaudeAgentOptions(
    mcp_servers={"your": server},
    system_prompt={"append": "You are a {DOMAIN} expert..."}
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Natural language question")

Conclusion

Building specialized agents transforms how we interact with CLI tools:

Before:

dotnet format --verify-no-changes --report report.json
cat report.json | jq '...'
# manually analyze, look up docs, decide...

After:

tda "What should I fix first?"
# Get prioritized recommendations with explanations

Key takeaways:

✅ Keep tool layer independent - agent is just a wrapper
✅ Use MCP to expose tools to Claude
✅ System prompt teaches domain expertise
✅ Optimize output format (TOON over JSON)
✅ Make it conversational - multi-turn exploration beats one-shot commands

The pattern is reusable. Take your existing CLI tools, wrap them with Claude Agent SDK, and give them a conversational interface.

For more details, check out the full source code. The code I provided here is a simplified version to illustrate the pattern.

References

dotnet-format-agent - Full source code
Claude Agent SDK - Python SDK
Context7 - Claude SDK Docs - API reference
dotnet format - Official docs