DEV Community: Hamed Hajiloo

The AI Has Hands

Hamed Hajiloo — Tue, 04 Aug 2026 09:39:13 +0000

Ask Crysta — the AI agent on CrystaCode.ai — to switch the site to dark mode, and the site actually turns dark. Ask it to show the login popup, and the modal actually opens. The model doesn't just answer anymore; it operates the UI.

But here's the thing: the LLM lives on the server, and the UI lives in the browser. A model can't click buttons. So how do you give a remote brain hands?

The answer is a pattern we ended up calling the Client Driver Skill: function calling, with SignalR as the hand.

The Problem

The first version of our chat was a one-way street. The model could say "sure, I'll take you to the plans page" — and then nothing happened. The answer was text; the UI was deaf.

You have two classic options:

The client polls the server for commands (ugly, wasteful, feels like 2010)
The server pushes commands to the client (real-time, instant, exactly what SignalR is for)

We went with the push. The flow became: the model calls a function → the function runs on the server → the server pushes a typed command over SignalR → the client executes it.

How It Works (The Full Loop)

[Browser]                    [Server]
   |                             |
   | 1. "switch to dark mode"    |
   | ---- InvokeAsync ---------> |
   |                             | 2. Brain runs, model sees
   |                             |    the UpdateSiteTheme tool
   |                             | 3. Model calls the function
   |                             |    (function calling)
   |                             | 4. Push to the exact tab:
   | <--- ChangeSiteTheme ------ |    Clients.Client(connId)
   | 5. ThemeService flips it    |
   | 6. "Site theme changed..."  | 5b. return value re-enters
   |                             |     the model's context
   | <--- chat answer ---------- |

User types "switch to dark mode" → the Blazor client calls the hub
The server session runs the brain; the model sees a tool called UpdateSiteTheme
The model decides the user wants dark mode and calls the function
The server pushes ChangeSiteTheme(DarkMode) to the exact browser connection
The client applies the theme and re-renders
The function's return value goes back into the model's context, so the AI knows the theme changed and confirms it in the chat

1) The Client Registers Its Remote Controls

On the client, our chat component subscribes to a set of hub events. Each one is a "remote control" the server can press:

HubConnection.On<SiteTheme>("ChangeSiteTheme", OnChangeTheme);
HubConnection.On("ShowLoginPopup", ShowLoginPopup);
HubConnection.On<CrystaPages>("NavigateToPage", HubOnNavigateToPage);
HubConnection.On("ShowInvitationModal", HanleOnShowInvitationModal);

That's it. The UI doesn't poll, doesn't guess — it just waits for the server to press a button.

2) The Model's Tools Are Functions With Descriptions

The trick that makes this work: we turn our skill methods into LLM tools with AIFunctionFactory.Create. The [Description] attribute is the user manual the model reads — write it like an instruction, not a docstring:

[Description("When user ask to change site ui theme, call this method
  to change user ui, site theme can be dark or light mode")]
public async Task<string> UpdateSiteTheme(
    [Description("Site theme based on user request")] SiteTheme siteTheme)
{
    await OnUpdateSiteTheme(siteTheme);

    return $"Site theme changed by crysta to {siteTheme}.";
}

Then the skill exposes its tool set:

public List<AIFunction> GetTools()
{
    return
    [
        AIFunctionFactory.Create(UpdateSiteTheme),
        AIFunctionFactory.Create(NavigateToPage),
        AIFunctionFactory.Create(ShowLoginPopup),
        AIFunctionFactory.Create(ShowMarkdown),
        AIFunctionFactory.Create(StartInitialFreeTrialSubscription),
        // ... every UI action the model is allowed to trigger
    ];
}

The brain collects these from all registered skills and attaches them to the Microsoft.Extensions.AI chat pipeline. The model doesn't know (or care) that the effect happens in a browser somewhere — to it, these are just tools it can call.

3) The Server Pushes to the Exact Tab

This is the part that matters most. The function body runs on the server, and the effect must land in one specific browser tab:

protected override async Task OnUpdateSiteTheme(SiteTheme siteTheme)
{
    var lastConnectionId = await interactionCoordinator.GetLastConnectionId(UserSessionId);

    if (!string.IsNullOrWhiteSpace(lastConnectionId))
    {
        await HubContext.Clients.Client(lastConnectionId).ChangeSiteTheme(siteTheme);
    }
}

Two details here are easy to miss, and both cost us debugging time:

Target the connection, not the user. Clients.User(userId) broadcasts to every tab and device a user has open. The command must land in the tab where the conversation is happening — so we track the session's last active connection id and push to Clients.Client(connectionId).

Type your hub. We use IHubContext<CrystaHub, ICrystaHubClient> — the client contract is a real C# interface:

public interface ICrystaHubClient
{
    Task ChangeSiteTheme(SiteTheme siteTheme);
    Task NavigateToPage(CrystaPages page);
    Task ShowLoginPopup();
    Task ShowMarkDown(string markdown);
    Task ShowInitialTrialSubscriptionStartedModal();
    // ...
}

No magic strings, no typos killing a production demo at 2am. If the client and server disagree, it doesn't compile.

4) The Client Applies It

Back in the browser, the registered handler fires:

private async Task OnChangeTheme(SiteTheme theme)
{
    await Task.Delay(500);
    await themeService.ChangeSiteTheme(theme);
}

One small detail: half a second of patience before the flip. We found that giving the UI a moment to settle after the chat bubble renders makes the theme transition feel intentional instead of jarring.

ThemeService does the actual work through the component library's theme manager, then notifies every component that cares via pub/sub:

public async Task ChangeSiteTheme(SiteTheme siteTheme)
{
    var current = await bitThemeManager.GetCurrentThemeAsync();
    var shouldBeDark = siteTheme == SiteTheme.DarkMode;

    if ((shouldBeDark && current != "dark") || (!shouldBeDark && current == "dark"))
    {
        await bitThemeManager.ToggleDarkLightAsync();
    }

    await bitDeviceCoordinator.ApplyTheme(shouldBeDark);
    pubSubService.Publish(ClientPubSubMessages.THEME_CHANGED, theme);
}

5) Modals Are the Same Trick

The theme was the easy one. The fun part: opening a modal is just another hub event. The model decides the user needs to log in, calls ShowLoginPopup, and the server pushes the command:

private async Task ShowLoginPopup()
{
    _ = signInModalService.SignIn();
}

Even richer: when the model wants to show details about a team member, it doesn't just navigate — it passes the data with the command:

HubConnection.On<TeamMemberDto>("OnNavigateToTeamMemberPage", dto =>
{
    AddComponentItem(typeof(CrystaMember), new() { { "TeamMemberDto", dto } },
        new PageInfo() { FullComponent = typeof(TeamMemberModal) });
});

The model already had the data from a GetTeamInfo call — so the command carries a typed DTO and the client opens the exact modal with the data pre-filled. The AI describes the person in chat and a modal with their full profile appears at the same time.

6) The Reverse Channel: The UI Talks Back

The loop doesn't stop at server → client. Sometimes the UI needs to tell the model what happened — because the model's next sentence depends on it.

Example: the invitation-code modal closes. The client pushes an instruction straight into the model's context:

// user closed the modal without a code
var instructionText = """
    The user could not enter an invitation code.
    Tell them that if they don't have one, they can get it from their friends.
    """;

await HubConnection.InvokeAsync("InstructCrysta", instructionText);

The server injects that instruction into the running session, the model responds to the actual UI event, and the answer streams back through the same chat channel. Browser and brain end up in a genuine two-way conversation — the UI has a voice too.

The Pattern, Summarized

LLM tools don't have to return data. They can trigger side effects. The model's "toolbox" is also its remote control.
SignalR is the hand. Server-side brain, browser-side UI, one typed channel between them.
Target the session's last connection, not the user. Multi-tab users will make you debug this for a day.
Type the hub. IHubContext<Hub, IClientContract> turns runtime typos into compile errors.
Return a status string. The model reads the function result — "Site theme changed to DarkMode" — so it can confirm what actually happened instead of guessing.
Build the reverse channel. Let the UI push instructions back (InstructCrysta), and the model's answers become consistent with what's really on screen.

That's the difference between "AI that answers" and "AI that acts" — and it's exactly what we built at CrystaCode.ai.

Centralized Rule Structures

Hamed Hajiloo — Thu, 30 Jul 2026 08:38:53 +0000

Enforcing AI Agent Adherence Through Single-Source Architecture in CrystaCode projects

AI agents require strict directory structures to execute project rules without logic divergence. Rule duplication causes execution failure. Establish a single source of truth. Define each rule in exactly one location. Secondary files function exclusively as routing parameters.

System Architecture

AGENTS.md                        # Primary entry file
CLAUDE.md                        # Pointer to AGENTS.md

agents/
  rules/
    productA.md                  # Component directives
    productB.md
  skills/
    styling-guidelines-a/SKILL.md
    styling-guidelines-b/SKILL.md
  hooks/
    styling-guard.ps1            # Interceptor execution script

docs/
  Conventions/
    ProductA/styling-guidelines.md   # Absolute rule text
    ProductB/styling-guidelines.md

.claude/
  settings.json                  # Claude hook directive
  skills/*/SKILL.md              # Auto-generated artifacts

.github/
  instructions/*.instructions.md # GitHub agent pointers
  hooks/preToolUse.json          # GitHub hook directive

Component Specifications

Primary Node

AGENTS.md: The mandatory initialization file. Contains routing matrices. Outlines file extension triggers and maps them to specific requisite documents.

Redirection Nodes

CLAUDE.md: Contains a single pointer instructing the parser to evaluate AGENTS.md.
.github/instructions/: Pointers redirecting GitHub Copilot to module-specific rules.

Operational Directives

agents/rules/: Isolated procedural steps and checklists mapped to specific project modules. Defers rule definitions to the skills directory.
agents/skills/: Contextual triggers dictating exact pre-conditions for operation. Defers absolute rule text to the docs/ repository.

Absolute Documentation

docs/: The definitive repository. Contains complete technical specifications and rule text. The sole location for rule definitions.

Automated Mirrors

.claude/skills/: Automated mirror of agents/skills. Manual modification is strictly prohibited.

Interceptor Script Protocol

The styling-guard.ps1 hook enforces compliance by gating execution based on session markers.

Intercept Request:
The script intercepts the AI file modification request pre-execution.
Evaluate Target Parameters:
The file extension is evaluated against target parameters (.scss, .razor). Unmatched files bypass interception.
Ascertain Product Association:
The script evaluates the target file path to identify the associated project module.
Query Session Data:
The script checks session data for an existing execution marker corresponding to the file type and module. If present, the AI bypasses interception.
Halt Execution:
If the marker is absent, execution is blocked. The AI receives an explicit directive to parse the required skill documentation.
Write Execution Marker:
The script writes the execution marker to session data. Subsequent modification attempts in the same session proceed without interruption.

Interceptor Implementation Logic
The interception mechanism outputs explicit standard error directives to halt execution when session markers are absent:

Deployment Checklist

if ($category -eq 'scss') {
    [Console]::Error.WriteLine(
        "MANDATORY styling gate: this is the first .scss edit in this session for the " +
        "'$product' product. Invoke the '$skill' skill (canonical rules: $doc), apply its " +
        "rules -- $checklist -- then retry this exact edit. $forbidden " +
        "This gate fires once per session per product per file category.")
} else {
    [Console]::Error.WriteLine(
        "MANDATORY component gate: this is the first .razor edit in this session for the " +
        "'$product' product. Before this edit: (1) invoke the '$skill' skill (canonical " +
        "rules: $doc) for color/typography/component conventions -- use $components. " +
        "(2) invoke the 'localize-app-strings' skill -- never hardcode user-facing text, " +
        "always route through IStringLocalizer<AppStrings>. Then retry this exact edit. " +
        "This gate fires once per session per product per file category.")
}

[ ] Initialize root entry node (AGENTS.md).
[ ] Define routing matrix mapping file extensions to required rules.
[ ] Isolate module-specific rules into distinct files.
[ ] Establish definitive rule repository (docs/) as the single source of truth.
[ ] Define skill triggers with explicit operational pre-conditions.
[ ] Deploy interceptor script to halt execution and mandate rule review.
[ ] Restrict tool-specific directories (.claude, .github) to pointer artifacts.

Enjoy it: CrystaCode

MCP for .NET: AI Agents That Can Actually Do Things

Hamed Hajiloo — Wed, 18 Feb 2026 08:08:02 +0000

Crysta is an AI app where you can build your own AI agents for real business use.

What makes it powerful is this: you are not limited to the default behavior of a chatbot.
You can connect different MCP servers and give your agent practical capabilities like scheduling, reservations, and data access.

In short, Crysta helps you build an AI agent that does more than talk, it can actually get work done.

What Users Can Connect

With MCP, an agent can connect to tools such as:

Google Calendar workflows
Reservation and scheduling systems
Business data tools exposed through MCP
Knowledge tools like DeepWiki (through MCP)

So instead of only answering a request like "book a meeting," the agent can actually do it through a connected tool.

Why This Matters for .NET Developers

MCP gives .NET developers a straightforward way to add real capabilities to an AI agent without building every integration yourself. Instead of wiring each API directly into your app, you connect MCP‑compatible tools and let the agent use them through the same function‑calling flow.

This leads to two big benefits:

Faster development: new features come from adding MCP tools, not writing new integrations.
Cleaner architecture: your agent grows by adding tools, not by adding more prompt logic or custom glue code.

How We Built It (High Level)

We kept the flow simple:

User adds an MCP server link to an agent.
System validates the link and reads tool metadata.
Connected MCP tools become part of that agent’s available actions.
During chat, the model can call those tools when needed.
We track failures and connection health so users can fix broken links quickly.

Packages We Use for This

These are the key packages behind this MCP workflow:

ModelContextProtocol
Microsoft.Extensions.AI
Microsoft.Extensions.AI.OpenAI
Azure.AI.OpenAI

This combination gives us MCP tool discovery plus a solid function-calling pipeline in .NET.

Small Code Examples (Based on Our Code)

Here’s a sample snippet that reflects the structure we use in our production pattern.

1) MCP client + validation service

using ModelContextProtocol.Client;

public class McpServerService : IMcpServerService
{
    public async Task<StoredMcpServer> ValidateAndGetMcpInfoAsync(string mcpUrl)
    {
        if (!Uri.TryCreate(mcpUrl, UriKind.Absolute, out _))
        {
            return new StoredMcpServer { IsValid = false, ErrorMessage = "Invalid URL format" };
        }

        try
        {
            var transport = new HttpClientTransport(
                new HttpClientTransportOptions { Endpoint = new Uri(mcpUrl) },
                loggerFactory: null);

            var client = await McpClient.CreateAsync(transport);
            var serverInfo = client.ServerInfo;

            return new StoredMcpServer
            {
                Url = mcpUrl,
                Title = serverInfo?.Name ?? "Unknown MCP Server",
                Description = serverInfo?.Title ?? "No description available",
                AddedDate = DateTime.Now,
                IsValid = serverInfo is not null
            };
        }
        catch (Exception ex)
        {
            return new StoredMcpServer { IsValid = false, ErrorMessage = ex.Message };
        }
    }

    public async Task<McpClient> CreateClientAsync(string mcpUrl, CancellationToken cancellationToken = default)
    {
        var transport = new HttpClientTransport(
            new HttpClientTransportOptions { Endpoint = new Uri(mcpUrl) },
            loggerFactory: null);
        return await McpClient.CreateAsync(transport);
    }
}

2) Load MCP tools from agent skills (runtime)

using Microsoft.Extensions.AI;
using ModelContextProtocol.Client;

private async Task<List<AIFunction>> GetMcpToolsAsync()
{
    if (interactiveAgent?.Skills == null) return [];

    var allTools = new List<AIFunction>();
    using var scope = ServiceScopeFactory.CreateScope();
    var mcpServerService = scope.ServiceProvider.GetRequiredService<IMcpServerService>();

    foreach (var skill in interactiveAgent.Skills)
    {
        if (skill.SkillType != SkillType.MCP) continue;
        if (skill.SkillJson is null) continue;

        var check = await mcpServerService.ValidateAndGetMcpInfoAsync(skill.SkillJson);
        if (!check.IsValid) continue;

        var client = await mcpServerService.CreateClientAsync(skill.SkillJson);
        var tools = await client.ListToolsAsync();
        allTools.AddRange(tools);
    }

    return allTools;
}

3) Attach MCP tools to `Microsoft.Extensions.AI` chat pipeline

using System.ClientModel;
using Azure.AI.OpenAI;
using Microsoft.Extensions.AI;

var azureChatClient = new AzureOpenAIClient(
    new Uri(endpoint),
    new ApiKeyCredential(apiKey))
    .GetChatClient(deployment)
    .AsIChatClient();

var mcpTools = await GetMcpToolsAsync();

var chatClient = new ChatClientBuilder(azureChatClient)
    .ConfigureOptions(options =>
    {
        options.Tools ??= [];
        foreach (var tool in mcpTools)
        {
            options.Tools.Add(tool);
        }
    })
    .UseFunctionInvocation(c => c.AllowConcurrentInvocation = true)
    .Build();

This is the exact idea we use: validate MCP links, discover tools, then pass those tools into the chat client so the agent can call them.

Closing

MCP moved our product from "AI that answers" to "AI that acts."

That is the difference users notice immediately.

If you want to see the end result, check it here: https://crystacode.ai

How I Fixed a Web Audio Echo Problem with a 5-Second Delay

Hamed Hajiloo — Sat, 01 Nov 2025 14:28:10 +0000

How I fixed a web audio echo problem with a 5-second delay

if you want to do anything with audio in the browser, you’ll have to deal with the Web Audio API. it’s what powers everything — from music apps to AI voice chats.

recently I was building a real-time user ↔ AI voice conversation app CrystaCode.ai.

everything worked fine except one weird thing:

👉 during the first few seconds of each conversation, the AI’s voice got picked up by the mic. after that? no echo at all.

I spent days trying everything different routing, gain nodes, worklets, custom dsp, RNNoise — nothing fixed it. then, out of frustration, i added one line:

await new Promise(res => setTimeout(res, 5000));

between starting the mic and sending audio to the AI. and boom — echo gone forever.

wait... why did this work?
when you call:

navigator.mediaDevices.getUserMedia({
  audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true }
});

the browser gives you a mic stream with built-in acoustic echo cancellation (aec).
that aec runs natively inside chrome, firefox, safari, or edge usually the same code used in webrtc (like webrtc::EchoCanceller in chrome).

the browser AEC works like this:

it watches what’s playing from your speakers
it listens to your microphone at the same time
it learns the relationship between the two — basically: “when I play this, the mic hears that”
it builds a model of your room acoustics and device path
after a few seconds, it knows how to subtract the speaker sound from the mic signal

so it needs time to adapt — normally 2–5 seconds. during that time, the AEC hasn’t finished learning yet, so a little bit of echo leaks through. the bug wasn’t a bug

my web audio code was fine. the browser just needed time to adapt.

by delaying the start of sending mic audio to the ai for 5 seconds, I let the AEC finish adapting. after that, no more echo.

why browsers behave like this

browser AEC uses adaptive algorithms. they constantly adjust to changing acoustics speaker position, device, user movement, etc.

so, every time you start the mic, the algorithm resets and starts learning again. the first few seconds are a "training phase". if you stream mic audio too early, it still contains echo. after it converges — everything becomes clean.

TL;DR

problem: ai voice was picked up by mic in first seconds
reason: browser AEC needs time to adapt
fix: delay sending mic data for ~5s before starting conversation

More info

MDN: Web Audio API
MDN: getUserMedia constraints