DEV Community: Venya Brodetskiy

Introducing design-lens-workshop: A Technical Design Skill for Complex Features

Venya Brodetskiy — Sun, 02 Aug 2026 08:51:43 +0000

A technical design workshop brings people with different responsibilities into the same conversation. Together, they look at a feature from several angles, challenge assumptions, and turn an idea into something the team can actually build.

When developers work with a team of AI agents, that conversation does not happen automatically. Agents can move from a feature request to an implementation plan before the key questions about architecture, data, UX, security, or operations have even been asked.

design-lens-workshop adds that missing step as a structured conversation with an AI agent. It builds a compact design brief, selects the perspectives most likely to affect the solution, and works through the key trade-offs and decisions with you before producing a design the team can review. It is meant for new products, subsystems, and larger or uncertain features — cases where finding gaps early is worth the extra effort.

The skill grew out of one of my favorite parts of Specrew: its Design Workshop.

What is Specrew?

Specrew was created by Alon Fliess. It is a governed workflow for AI-assisted software development.

Instead of treating an AI coding agent as a chatbot that waits for the next prompt, Specrew drives the software development lifecycle. It helps move work through discovery, specification, design, planning, implementation, review, and closeout. The agents do the work between boundaries, while the human remains responsible for the important decisions.

Alon explains the motivation and the complete approach in The AI SDLC — From Vibe Coding to Governed Agentic Development.

Specrew is a complete methodology and runtime. But while looking through it, I started thinking that some of its ideas could also be useful independently. I especially liked the Design Workshop — it quickly became one of my favorite parts of Specrew. It felt valuable enough to stand on its own, even without adopting the complete Specrew workflow.

The part that interested me most

The Design Workshop sits between understanding what we want to build and deciding how to implement it.

Instead of asking one agent for a finished architecture, it examines the feature through several design lenses. Each lens brings a different perspective and asks the questions a specialist in that area would normally ask.

For example:

What are the system boundaries and component responsibilities?
Which requirements and non-functional qualities actually drive the design?
Who owns the data, and what consistency guarantees do we need?
How do integrations fail, retry, and evolve?
What are the trust boundaries?
How will we deploy, observe, and recover the feature?

This is very close to how I approach design work as a tech lead. I do not only want an answer. I want to explore the problem from several relevant directions, understand the trade-offs, and make the decisions visible before they turn into code.

I wondered: why not make this workshop available as a standalone skill?

A standalone Design Lens Workshop

I adapted the Specrew Design Workshop into design-lens-workshop, a reusable Agent Skill that can be installed and invoked independently.

The skill retains the lens-driven facilitation and co-design method, while leaving out the surrounding Specrew lifecycle and runtime. It does not manage feature stages, enforce gates, generate an implementation plan, or continue into coding. It runs a technical design workshop and ends with a reviewable design handoff.

The workshop remains part of Specrew's full lifecycle, but it can also be useful as an independently invoked skill.

The standalone version keeps the same set of nine technical lenses as the original Specrew Design Workshop:

architecture core;
component design;
requirements and non-functional requirements;
UI and UX;
data and storage;
security and compliance;
integrations and APIs;
DevOps and operations;
observability and resilience.

The skill does not explore all nine lenses at the same depth. It always evaluates architecture, component design, and requirements/NFRs as foundations. From the remaining six, the agent selects those that can materially shape the design, assigns each selected lens full, medium, or light depth, and explains the skipped lenses. A light foundation may simply establish that it introduces no new concern.

How the skill works

The default is Workshop mode. Its flow is intentionally simple:

The agent builds a small design brief from the conversation, supplied documents, and relevant repository evidence. Important statements are marked as known, assumed, or open.
It proposes the workshop agenda and waits for confirmation or adjustment.
It works through one selected lens at a time.
For each lens, it presents the current understanding and evidence before asking only for input that can materially change the design. A light lens with no new concern may need only a quick confirm / correct / move on review.
It records the decision, rationale, consequences, and whether the direction was recommended, confirmed, delegated, provisional, skipped, or left open.
It reconciles the decisions across lenses and returns a design handoff.

Workshop mode right-sizes the agenda, then explores each selected lens with the human.

Workshop mode is deliberately thorough. The skill also offers Parallel scan mode, but only when I request it explicitly. It scans every selected lens independently and, when the host supports delegation, runs those scans in parallel with separate subagents.

The coordinator consolidates overlapping findings into cross-lens concern clusters and a prioritized question agenda, then stops for discussion. Any concern cluster can then continue in Workshop mode.

Workshop mode retains the Specrew workshop approach; Parallel scan mode is an addition made for this standalone adaptation.

One rule I especially like is render before you ask. The agent should not ask you to approve an architecture, component map, set of options, or design verdict that it has not actually shown and explained. When a diagram or shared view helps, it must be visible in the conversation before the approval question.

The workshop is also collaborative. For architecture and component work, the agent should not immediately hand down a finished solution. It builds the component map with you, walks an important flow through it, and then discusses the remaining trade-offs.

Once the selected lenses — or the load-bearing concerns surfaced by a parallel scan — have been discussed, the skill summarizes the design context, decisions, components, important flows, alternatives, risks, open questions, and validation signals. Then it stops. Planning and implementation remain separate steps that I can start when I am ready.

When to use it

The skill activates only when you explicitly ask for a design workshop. It is useful when you want to:

deepen a technical design before planning;
challenge an existing direction;
compare two possible designs;
uncover cross-cutting concerns or missing decisions;
prepare a design for review with another engineer or architect.

It is not intended for every coding request. Asking an agent to implement a small change or write an implementation plan should not silently start a workshop.

After dogfooding the skill, I do not expect to run the full workshop for every feature. Its depth is the point, but that depth also takes time.

I would reach for Workshop mode when starting a new product or subsystem, entering an unfamiliar part of a system, or designing a genuinely large feature. Knowing how a feature should behave does not necessarily mean that its implementation model is clear: gaps may remain in the data model, ownership, usability, security, or operations.

If I want a faster broad review from several perspectives and do not mind spending more model tokens, I can start with Parallel scan mode. On hosts with subagent support, it front-loads the research in parallel; afterward, I can take the important points into Workshop mode one by one.

After installation, I can invoke the skill explicitly with /design-lens-workshop:

/design-lens-workshop Workshop the technical design of a new caching subsystem
for product catalog reads before we plan implementation.

Product updates can arrive at any time, stale prices are unacceptable, and
the API must remain available when the catalog provider is slow. Inspect the
current repository first, then start with a design brief and workshop agenda.

Or I can start with Parallel scan mode:

/design-lens-workshop Run a parallel scan for this caching subsystem first.
Inspect the current repository and surface the main concerns and questions
across the relevant lenses.

Install and try it

The skill is available in the public ZioNet skills repository.

Preview it with GitHub CLI:

gh skill preview Zio-Net/skills design-lens-workshop

Install it for Codex at project scope:

gh skill install Zio-Net/skills design-lens-workshop --agent codex --scope project

For Claude Code, replace codex with claude-code. The repository follows the open Agent Skills structure, so the skill can also be copied manually into the appropriate skills directory.

In conclusion

Specrew remains a complete approach to governing an AI-assisted software development lifecycle. The standalone skill does not try to replace that.

It offers another way to use one particularly useful idea from Specrew: a structured, collaborative technical design workshop that can be invoked at the point where it is useful.

For me, that means having an AI agent help with a familiar tech-lead responsibility — looking at a design from the relevant angles when the work deserves that depth, making trade-offs explicit, and reaching the implementation plan with fewer hidden decisions.

If you try it, I would be glad to hear your feedback and ideas for improving it.

The skill is a standalone adaptation of the Specrew Design Workshop under the MIT License, with attribution to Alon Fliess, Specrew, and its contributors. It is maintained in Zio-Net/skills and is not an official Specrew distribution.

Where Should Your Agent Run? Three Patterns with Microsoft Foundry

Venya Brodetskiy — Sat, 01 Aug 2026 16:41:58 +0000

A practical comparison of who owns the code, state, deployment, and telemetry.

In my previous articles, I covered individual agents and multi-step workflows with Microsoft Agent Framework. Once the prompt works and the tools return the right data, the next question sounds simple:

Where should this agent actually run?

That decision changes more than deployment. It determines who owns the process, conversation state, scaling, identity, and telemetry. It also determines which problems your team will debug when the agent fails at 2 a.m.

The accompanying demo repository contains three deliberately different patterns:

A declarative prompt agent managed by Foundry.
Custom Agent Framework code deployed to a Foundry-hosted runtime.
The same kind of custom code running on your own infrastructure and exporting telemetry to Foundry.

These are not three copies of the same agent. They are three different ownership choices.

To keep the comparison practical, demos 2 and 3 use the same two C# tools: a weather function and an office-climate function. The user can ask the same question and receive the same deterministic result. What changes is everything around the tool call—how the process starts, where state lives, how it is deployed, and who must make its trace visible. Demo 1 intentionally stays simpler: it has instructions and managed conversation state, but no custom tools.

The runtime spectrum

Think of the options as a spectrum. Moving from left to right gives you more control, but also more operational responsibility.

From a prompt agent to self-hosted code: more infrastructure control also means more to operate. Open in full size

The useful question is not “Which option is best?” It is “Which responsibilities do I actually need to own?”

Pattern 1: let Foundry run a prompt agent

A Foundry prompt agent is a declarative, configuration-driven agent—the closest of these three patterns to a no-code option. In the Foundry portal, you can select a model, write instructions, attach supported tools, and test the agent in the Playground without writing application code or using Microsoft Agent Framework.

That does not make it a toy. You can improve its instructions with the Prompt Optimizer (currently in preview), ground responses in your own documents with file search, and attach tools for search, code execution, APIs, MCP servers, and other actions. Custom function tools are supported too, but they are not fully no-code: your application or another service must execute the function code.

The trade-off is control. You can configure the model, instructions, knowledge, and supported tools, but Foundry owns the orchestration loop and runtime. If you need arbitrary application logic or custom orchestration, a code-based agent is the better fit.

The portal is only one authoring path. The same agent can also be created and versioned through the Foundry SDK or REST API. This demo uses C# so the definition is reproducible in source control, but that code creates a managed Foundry resource—it is not a runtime you host yourself.

The demo creates a small pirate assistant. The persona is not important; the definition is:

ProjectsAgentDefinition definition = new DeclarativeAgentDefinition(modelName)
{
    Instructions = agentInstructions,
};

ProjectsAgentVersion version =
    await aiProjectClient.AgentAdministrationClient.CreateAgentVersionAsync(
        agentName: agentName,
        options: new(definition));

Every update creates a new version under the same agent name. Whether you author the definition in the portal or in code, Foundry runs the agent; your application only connects to it.

The repository does use Microsoft Agent Framework on the client side. AsAIAgent(agentRecord) adapts the managed prompt agent to the common AIAgent API, which the console uses to invoke the agent and resume an AgentSession. It does not turn Demo 1 into a code-hosted agent: Azure.AI.Projects still creates the Foundry resource, and Foundry still owns the runtime.

There is a small detail in this demo that explains the ownership model well. The local file stores only a Foundry conversation ID. The message history remains in the cloud. On restart, the console app reads that ID and reconnects to the same conversation.

You can see both pieces in the repository: the prompt-agent setup and the small conversation ID store.

The prompt agent stays intentionally simple: Foundry runs it, keeps the conversation state, and the agent answers without custom code tools. Open in full size

With project monitoring enabled, Foundry records the prompt agent's server-side trace automatically—no instrumentation code required.

The trace shows the agent invocation, model call, duration, and token usage. Open in full size

Choose this pattern when instructions and service-supported tools describe most of the agent, and you want the smallest runtime surface to operate.

Pattern 2: bring your code, let Foundry host it

The second demo needs custom C# functions. It exposes deterministic weather data and mock office-climate data, then packages that logic as a Foundry hosted agent.

Here, you own the agent code and tools:

AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: modelName,
        instructions: "Use the appropriate demo tool and keep answers concise.",
        tools:
        [
            AIFunctionFactory.Create(WeatherTools.GetWeather),
            AIFunctionFactory.Create(WeatherTools.GetOfficeClimateStatus)
        ]);

var builder = AgentHost.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.RegisterProtocol("responses", endpoints => endpoints.MapFoundryResponses());

AddFoundryResponses connects the agent to the Responses protocol handler, while MapFoundryResponses exposes the /responses endpoint. According to the Agent Framework hosting documentation, Responses is the recommended starting protocol for most conversational agents. Foundry manages conversation history, streaming, and session lifecycle around that endpoint.

What is happening here? The AIAgent still contains normal application logic. AgentHost supplies the hosting boundary, and the Responses adapter supplies the HTTP contract. This separation is useful: the tool methods do not need to know whether the process is running locally or inside Foundry.

Local execution has one extra concern. A request sent directly to localhost does not contain the user and chat isolation context injected by Foundry, so the demo registers a local fallback session-isolation provider. That fallback exists to make direct development calls work; the deployed platform provides the real request context.

The source manifest declares the hosted-agent kind, Responses protocol, CPU and memory, and environment variables. During initialization, azd turns it into deployment configuration that also specifies the .NET runtime, entry point, and remote build. From the demo directory, the intended deployment flow is short:

azd ai agent init -m .\agent.manifest.yaml --deploy-mode code
azd deploy
azd ai agent invoke "Is the AC working in Venya's home office?"

If you prefer a UI, the Microsoft Foundry Toolkit for Visual Studio Code provides a Foundry Toolkit: Deploy Hosted Agent workflow. It supports both code and container deployment and lets you review the settings before deploying, so the azd commands are not the only path.

A useful mental model is serverless containers: you provide code or an image, while Foundry manages the infrastructure and scaling. This demo uses the code path, so azd or the Toolkit uploads the project as a ZIP and Foundry performs the .NET build remotely.

Under the hood, the result still runs in a platform-provided container on Azure Container Apps, inside a per-session VM-isolated sandbox. Idle compute can scale to zero, while session files are restored when the session resumes. The Hosted agents documentation and networking deep dive cover the Container Apps and Micro VM layers in more detail.

The agent code is still yours. The running environment is not. Foundry gives the deployed agent an identity and endpoint and supplies platform configuration such as the project endpoint and Application Insights connection string. Microsoft describes the managed Hosted Agents service as generally available, while this sample still pins preview versions of some .NET integration packages.

The complete hosted-agent program, deployment manifest, and demo commands are kept together in the repository.

The Foundry-hosted Agent Framework agent executes the custom get_office_climate_status C# function and returns the deterministic FAC-1042 result. Open in full size

With project monitoring enabled, the Foundry hosting integration exports OpenTelemetry traces automatically, so this demo needs no separate tracing setup.

The hosted trace also reveals protocol, identity, model, and platform storage spans. Open in full size

Choose this pattern when you need custom code and tools but do not want to operate the agent runtime yourself.

Pattern 3: keep the runtime, export the telemetry

The third demo uses the same weather and office-climate scenario, but the process runs locally—or anywhere you choose to deploy it. That means your team owns process lifetime, scaling, secrets, networking, and state.

It also means telemetry is your responsibility. The demo creates an OpenTelemetry resource with a stable agent identity and exports traces to Azure Monitor:

const string agentId = "local-weather-agent";

var resource = ResourceBuilder.CreateDefault()
    .AddService(agentId)
    .AddAttributes([
        new("gen_ai.agent.id", agentId),
        new("gen_ai.agent.name", agentId),
    ]);

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resource)
    .AddSource("Experimental.Microsoft.Agents.AI")
    .AddSource("Experimental.Microsoft.Extensions.AI")
    .AddAzureMonitorTraceExporter(options =>
        options.ConnectionString = applicationInsightsConnectionString)
    .Build();

Your process sends OpenTelemetry traces directly to Application Insights. Registering it as an external agent does not deploy or host the code; it simply tells Foundry which traces belong to that agent. The key link is a stable ID: the gen_ai.agent.id emitted by the runtime must match the ID used during registration.

The self-hosted demo shows the exporter, stable agent ID, two tools, and local conversation loop in one file.

The self-hosted trace separates the agent run, two model calls, and the office-climate tool execution. Open in full size

Here, execute_tool is a separate span. Foundry shows which function ran, how long it took, and—when sensitive-data capture is enabled—its input and output.

Choose this pattern when infrastructure control, private networking, portability, or a custom hosting platform matters more than managed operations.

State is not one thing

“Foundry manages state” is an easy phrase to overread. In practice, there are at least three different concerns:

Conversation history: the messages exchanged with the agent.
Agent session: the technical context used to continue that conversation.
Business state: orders, approvals, user preferences, workflow checkpoints, and anything else your application must preserve.

In the prompt-agent demo, Foundry stores the conversation while the console application saves only its ID. With Foundry-hosted code, the Responses protocol manages conversational history and session lifecycle around the endpoint. Neither pattern turns Foundry into a database for your domain model: durable business state still belongs in your application and data store.

In the self-hosted demo, the current AgentSession exists inside the running process. If that process restarts, persistence and recovery are your responsibility. This leads to a more useful design question than simply asking whether a platform “has state”: what must survive a process restart, deployment, or regional failure?

The decision in one table

	Prompt agent	Foundry-hosted code	Self-hosted code
Best fit	Mostly declarative behavior	Custom code, managed runtime	Maximum infrastructure control
Runtime owner	Foundry	Foundry	Your team
Deployment unit	Agent definition	Code package/container	Your application
Conversation state	Foundry-managed	Protocol/platform-managed	Your implementation
Telemetry	Platform-managed	Hosting integration	You configure export and identity

The middle option is often the practical default for a code-based agent: you keep normal application code without immediately taking ownership of another production service. But the table is not a maturity ladder. Self-hosting is not “more advanced,” and a prompt agent is not “just a demo.” Each option optimizes for a different ownership boundary.

Demo notes

The weather and office-climate tools return deterministic fake data. The self-hosted demo also enables sensitive telemetry content so prompts and tool results are easier to inspect. Keep that setting disabled by default unless your privacy and retention requirements allow it.

Conclusion

Choosing an agent runtime is really choosing an ownership boundary.

Use a prompt agent when the definition is the product.
Use a Foundry-hosted agent when custom code is the product but operating the runtime is not.
Self-host when you need to own the environment—and accept responsibility for state, deployment, and telemetry.

The durable idea is simple: choose who owns the runtime, then keep a consistent telemetry contract.

Building Multi-Step Workflows with Agent Framework

Venya Brodetskiy — Sat, 01 Aug 2026 12:27:34 +0000

Originally published on Medium on December 28, 2025.

In the previous article, we explored how to build individual AI agents with Microsoft Agent Framework — agents that can call functions, extract structured data, and leverage RAG. These are powerful building blocks, but real-world scenarios often require something more: orchestrating multiple agents and deterministic logic into complex, multi-step processes.

That's where Agent Framework's workflow system comes in.

Think about a customer support email system. A single agent can't handle everything. You need to preprocess the email, classify it, apply business rules, route it appropriately, draft responses, and sometimes escalate to humans. Each step has different requirements — some need AI reasoning, others need deterministic logic, and all need to work together seamlessly.

In this guide, we'll build exactly that: a customer support email triage workflow that combines LLM agents with business logic to automatically process, classify, and respond to customer emails.

What Are Workflows?

Workflows in Agent Framework are graph-based orchestration systems. Instead of writing monolithic code that tries to handle every scenario, you build a directed graph where:

Executors are individual processing units (agents or custom logic)
Edges connect executors and define the flow of data
Conditions on edges enable dynamic routing based on context

This architecture gives you:

Modularity: Each executor focuses on one task
Clarity: The graph structure makes the process flow explicit
Flexibility: Conditional edges adapt to different scenarios
Maintainability: Changes to one step don’t cascade through the entire system

For more on workflows, see the Agent Framework Workflows Guide.

The Use Case: Customer Support Email Triage

Let’s define our business problem. We receive hundreds of customer support emails daily. We want to:

Automatically process routine requests
Apply business rules consistently
Escalate appropriately when human judgment is needed
Maintain compliance with data protection and policies

Here’s the workflow we’ll build:

The workflow handles four routing scenarios:

High-priority escalations: Negative sentiment + high urgency → human handoff
Clarification needed: Missing information → agent drafts questions
Refund requests: Automated refund creation → human review
Normal replies: Standard responses → agent drafts reply

Workflow Architecture: The Building Blocks

Before diving into code, let’s understand the three core concepts.

Executors

An executor is a processing unit that takes an input, performs some operation, and returns an output. Every executor inherits from Executor<TInput, TOutput>:

internal sealed class PreprocessEmailExecutor : Executor<string, EmailDocument>
{
    public override async ValueTask<EmailDocument> HandleAsync(
        string message,
        IWorkflowContext context,
        CancellationToken cancellationToken = default)
    {
        // Process the raw email...
        return processedEmail;
    }
}

Executors can be:

Deterministic: Pure logic, no AI (preprocessing, routing, validation)
Agentic: Uses LLM for reasoning (classification, response drafting)

Edges

Edges connect executors and can include conditions for dynamic routing:

var workflow = new WorkflowBuilder(startExecutor)
    .AddEdge(preprocess, intake)  // Simple edge
    .AddEdge<PolicyContext>(      // Conditional edge
        source: policyGate,
        target: responder,
        condition: ctx => ctx.Policy.Mode == ResponseMode.DraftReply)
    .Build();

Conditions let you build branching logic: “If sentiment is negative AND urgency is high, escalate to human.”

Shared State

Executors can communicate through shared state. This is crucial when multiple executors need access to the same data:

// Write to shared state
await context.QueueStateUpdateAsync(
    SupportRunState.KeyEmail,
    email,
    scopeName: SupportRunState.ScopeName
);

// Read from shared state
var email = await context.ReadStateAsync<EmailDocument>(
    SupportRunState.KeyEmail,
    scopeName: SupportRunState.ScopeName
);

Deterministic vs. Agentic Executors

Let’s compare two executors to see the difference in approach.

Deterministic Executor: PreprocessEmailExecutor

This executor uses pure C# logic to clean emails and detect PII:

internal sealed partial class PreprocessEmailExecutor : Executor<string, EmailDocument>
{
    public override async ValueTask<EmailDocument> HandleAsync(
        string message,
        IWorkflowContext context,
        CancellationToken cancellationToken = default)
    {
        var lines = SplitLines(message);
        // Extract headers
        string? from = TryExtractHeaderValue(lines, "From:");
        string? subject = TryExtractHeaderValue(lines, "Subject:");
        // Clean the body
        var body = RemoveHeaders(lines);
        body = StripQuotedReplies(body);
        body = NormalizeWhitespace(body);
        // Detect PII using regex
        var detectedEmails = EmailRegex().Matches(body)...;
        var detectedPhones = PhoneRegex().Matches(body)...;
        var detectedOrderIds = OrderIdRegex().Matches(body)...;
        // Mask PII for model safety
        var modelSafe = MaskPii(body);
        var email = new EmailDocument
        {
            OriginalText = message,
            CleanText = body,
            ModelSafeText = modelSafe,
            ContainsPii = detectedEmails.Count > 0 || detectedPhones.Count > 0,
            DetectedEmails = detectedEmails,
            DetectedPhones = detectedPhones,
            DetectedOrderIds = detectedOrderIds
        };
        // Store in shared state and emit event
        await context.QueueStateUpdateAsync(SupportRunState.KeyEmail, email, ...);
        await context.AddEventAsync(new EmailPreprocessedEvent(email), ...);
        return email;
    }
}

What makes it deterministic?

Uses regex patterns to detect emails, phones, and order IDs
Applies consistent text cleaning rules
No LLM calls — predictable, fast, and cost-free
Perfect for operations where you need guaranteed behavior

Agentic Executor: EmailIntakeExecutor

This executor uses an LLM to classify the email:

internal sealed class EmailIntakeExecutor : Executor<EmailDocument, IntakeContext>
{
    private readonly AIAgent _agent;
    private readonly AgentThread _thread;

    public EmailIntakeExecutor(string id, IChatClient chatClient) : base(id)
    {
        ChatClientAgentOptions agentOptions = new()
        {
            ChatOptions = new()
            {
                Instructions = """
                    You are a customer support intake assistant.
                    Return JSON that matches the schema exactly.
                    Be concise and do not invent missing facts.
                    """,
                ResponseFormat = ChatResponseFormat.ForJsonSchema<IntakeResult>()
            }
        };

        _agent = new ChatClientAgent(chatClient, agentOptions);
        _thread = _agent.GetNewThread();
    }

    public override async ValueTask<IntakeContext> HandleAsync(
        EmailDocument message,
        IWorkflowContext context,
        CancellationToken cancellationToken = default)
    {
        var prompt = $"""
            Classify this inbound customer support email.

            Subject: {message.Subject ?? "(none)"}
            From: {message.From ?? "(unknown)"}

            Email:
            {message.ModelSafeText}
            """;

        var result = await _agent.RunAsync(prompt, _thread, cancellationToken: cancellationToken);
        var intake = JsonSerializer.Deserialize<IntakeResult>(result.Text);

        var intakeContext = new IntakeContext { Email = message, Intake = intake };
        await context.QueueStateUpdateAsync(SupportRunState.KeyIntake, intakeContext, ...);
        await context.AddEventAsync(new IntakeCompletedEvent(intakeContext), ...);

        return intakeContext;
    }
}

What makes it agentic?

Uses an LLM to understand the email’s intent, urgency, and sentiment
Extracts structured data through ForJsonSchema<IntakeResult>()
Handles nuance and context that regex can’t capture
Perfect for classification, reasoning, and natural language understanding

The Hybrid Approach

By combining both types of executors, you get the best of both worlds:

Deterministic steps provide speed, consistency, and cost control
Agentic steps handle complexity, nuance, and reasoning
Together, they create a system that’s both intelligent and reliable

Conditional Routing: PolicyGateExecutor

The PolicyGateExecutor demonstrates how to implement business logic routing:

internal sealed class PolicyGateExecutor : Executor<IntakeContext, PolicyContext>
{
    public override async ValueTask<PolicyContext> HandleAsync(
        IntakeContext message,
        IWorkflowContext context,
        CancellationToken cancellationToken = default)
    {
        // Apply business rules
        var missingInfo = message.Intake.MissingInformation ?? [];
        var mode = missingInfo.Count > 0
            ? ResponseMode.AskClarifyingQuestions
            : ResponseMode.DraftReply;

        var sla = message.Intake.Urgency switch
        {
            UrgencyLevel.High => "4h",
            UrgencyLevel.Normal => "24h",
            _ => "72h"
        };

        var complianceNotes = new List<string>();

        if (message.Email.ContainsPii)
        {
            complianceNotes.Add("PII detected. Use only redacted content in replies.");
        }

        if (message.Intake.Intent is UserIntent.Refund or UserIntent.CancelOrder)
        {
            complianceNotes.Add("Do not promise refund. Confirm policy first.");
        }

        // Build policy decision
        var policy = new PolicyDecision
        {
            Mode = mode,
            RedactedEmailText = message.Email.ModelSafeText,
            Sla = sla,
            ComplianceNotes = complianceNotes
        };

        var policyContext = new PolicyContext
        {
            Email = message.Email,
            Intake = message.Intake,
            Policy = policy
        };

        // Store routing decision in shared state
        var isEscalation = policyContext.Intake.Sentiment == Sentiment.Negative
                           && policyContext.Intake.Urgency == UrgencyLevel.High;
        var isRefund = policyContext.Policy.Mode == ResponseMode.DraftReply
                       && policyContext.Intake.Intent == UserIntent.Refund
                       && !isEscalation;

        var route = isEscalation ? "Human escalation"
                  : isRefund ? "Refund request (human review)"
                  : "Normal reply";

        await context.QueueStateUpdateAsync(SupportRunState.KeySelectedRoute, route, ...);

        return policyContext;
    }
}

This executor:

Evaluates intake results to determine response mode
Applies SLA rules based on urgency
Enforces compliance by flagging PII and sensitive requests
Determines routing through conditional logic

The workflow builder then uses these decisions to route appropriately:

return new WorkflowBuilder(preprocess)
    .AddEdge(preprocess, intake)
    .AddEdge(intake, policyGate)

    // Escalate: negative + high urgency
    .AddEdge<PolicyContext>(
        source: policyGate,
        target: humanPrep,
        condition: ctx => ctx.Intake.Sentiment == Sentiment.Negative
                          && ctx.Intake.Urgency == UrgencyLevel.High)

    // Refund: no missing info + refund intent
    .AddEdge<PolicyContext>(
        source: policyGate,
        target: refundRequest,
        condition: ctx => ctx.Policy.Mode == ResponseMode.DraftReply
                          && ctx.Intake.Intent == UserIntent.Refund
                          && !(ctx.Intake.Sentiment == Sentiment.Negative
                               && ctx.Intake.Urgency == UrgencyLevel.High))

    // Default: normal reply
    .AddEdge<PolicyContext>(
        source: policyGate,
        target: responder,
        condition: ctx => ctx.Policy.Mode == ResponseMode.DraftReply
                          && ctx.Intake.Intent != UserIntent.Refund
                          && !(ctx.Intake.Sentiment == Sentiment.Negative
                               && ctx.Intake.Urgency == UrgencyLevel.High))
    .Build();

Custom Events: Building Your Observability Story

One of the most powerful features of Agent Framework workflows is the custom events system. Events provide real-time insight into what’s happening inside your workflow, making debugging and monitoring dramatically easier.

Creating Custom Events

Custom events inherit from WorkflowEvent and can carry any data you need:

internal sealed class EmailPreprocessedEvent(EmailDocument email) : WorkflowEvent(email)
{
    public EmailDocument Email { get; } = email;
}

internal sealed class IntakeCompletedEvent(IntakeContext context) : WorkflowEvent(context)
{
    public IntakeContext Context { get; } = context;
}

internal sealed class PolicyAppliedEvent(PolicyContext context) : WorkflowEvent(context)
{
    public PolicyContext Context { get; } = context;
}

These events are simple data carriers, but they transform how you observe workflow execution.

Emitting Events from Executors

Inside any executor, you emit events through the workflow context:

public override async ValueTask<EmailDocument> HandleAsync(
    string message,
    IWorkflowContext context,
    CancellationToken cancellationToken = default)
{
    // ... process the email ...

    var email = new EmailDocument
    {
        OriginalText = message,
        CleanText = body,
        ModelSafeText = modelSafe,
        ContainsPii = containsPii,
        // ... other properties
    };

    // Emit the event
    await context.AddEventAsync(new EmailPreprocessedEvent(email), cancellationToken);

    return email;
}

Events are emitted in real-time as the workflow executes, allowing you to observe progress as it happens.

Consuming Events: Real-Time Workflow Monitoring

Here’s where it gets interesting. When you run a workflow, you can watch the event stream:

await using StreamingRun run = await InProcessExecution.StreamAsync(workflow, input: email);

await foreach (var evt in run.WatchStreamAsync())
{
    switch (evt)
    {
        case EmailPreprocessedEvent e:
            Console.WriteLine(
                $"[Preprocess|Deterministic] Subject='{e.Email.Subject}' | " +
                $"PII={e.Email.ContainsPii} | OrderIds={e.Email.DetectedOrderIds.Count}");
            break;

        case IntakeCompletedEvent e:
            Console.WriteLine(
                $"[Intake|Agent] {e.Context.Intake.Category} | " +
                $"{e.Context.Intake.Urgency} | {e.Context.Intake.Sentiment}");
            Console.WriteLine($"  Summary: {e.Context.Intake.Summary}");
            break;

        case PolicyAppliedEvent e:
            Console.WriteLine(
                $"[Policy|Deterministic] Mode={e.Context.Policy.Mode} | " +
                $"SLA={e.Context.Policy.Sla}");
            break;

        case ResponseDraftedEvent e:
            Console.WriteLine(
                $"[Responder|Agent] Generated {e.Info.Mode} response");
            break;

        case HumanHandoffPreparedEvent e:
            Console.WriteLine(
                $"[Human Prep|Hybrid] Queue='{e.Package.Queue}' | " +
                $"SLA={e.Package.Sla}");
            Console.WriteLine($"  Summary: {e.Package.Summary}");
            break;

        case RefundRequestCreatedEvent e:
            Console.WriteLine(
                $"[Refund|Deterministic] Id={e.Request.RefundRequestId}");
            break;

        case WorkflowOutputEvent outputEvent:
            Console.WriteLine("=== Workflow Output ===");
            Console.WriteLine(outputEvent.Data);
            break;

        case WorkflowErrorEvent errorEvent:
            Console.WriteLine($"ERROR: {errorEvent}");
            break;
    }
}

What makes this powerful:

Real-time visibility: You see exactly what’s happening as the workflow executes
Type-safe pattern matching: Each event type can be handled differently
Rich context: Events carry the full data from each step
Built-in events: WorkflowOutputEvent and WorkflowErrorEvent are provided automatically

Event-Driven Debugging

When something goes wrong, events tell the story:

OpenTelemetry Integration: Distributed Tracing

Beyond custom events, Agent Framework integrates with OpenTelemetry for production-grade observability.

Setting Up OpenTelemetry

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(
        ResourceBuilder.CreateDefault()
            .AddService("AgentFrameworkWorkflows"))
    .AddSource("Microsoft.Agents.AI.*")
    .SetSampler(new AlwaysOnSampler())
    .AddOtlpExporter(options =>
    {
        options.Endpoint = new Uri("http://localhost:4319");
        options.Protocol = OtlpExportProtocol.Grpc;
    })
    .Build();

This configuration:

Identifies your service (AgentFrameworkWorkflows)
Captures Agent Framework traces (Microsoft.Agents.AI.*)
Samples all traces (use selective sampling in production)
Exports via OTLP to your observability backend (Jaeger, Zipkin, Azure Monitor, etc.)

What Gets Traced

OpenTelemetry automatically captures:

Executor execution times: How long each step takes
Agent LLM calls: Token counts, latencies, model calls
State operations: Reads and writes to shared state
Edge transitions: Which conditional paths were taken
Error contexts: Stack traces with workflow context

Visualizing Workflows with AI Foundry

Here’s where it gets really powerful. The Azure AI Foundry VS Code extension can visualize your workflow execution using OpenTelemetry traces.

Setting up visualization:

Install the Azure AI Foundry extension in VS Code
Configure OTLP endpoint (default http://localhost:4319
Run your workflow with OpenTelemetry enabled
Open the Foundry extension panel to see the live trace

The extension shows your workflow graph in real-time, highlighting the active executor as it runs and showing the complete path when finished.

Production Observability

In production, this same infrastructure feeds standard observability tools:

Azure Monitor: Native integration with Application Insights
Jaeger: Open-source distributed tracing
Zipkin: Lightweight tracing visualization
Datadog/New Relic: Commercial APM platforms

All support OTLP, so you can monitor workflows alongside the rest of your infrastructure.

Running the Demo

To run the workflow example:

Configure Azure OpenAI in appsettings.Development.json:

{
  "ModelName": "your-model-deployment",
  "Endpoint": "https://your-resource.openai.azure.com/",
  "ApiKey": "your-api-key"
}

Run the project:

cd AgentFrameworkWorkflows
dotnet run

The workflow will process the email and show you:

Preprocessing results (detected PII, order IDs)
Classification output (category, urgency, sentiment)
Policy decisions (SLA, compliance notes)
Routing decision and final output

Key Patterns and Best Practices

When to Use Workflows

Workflows shine when you need:

Multi-step processes that involve both AI and business logic
Conditional routing based on context
Human-in-the-loop patterns
Compliance requirements that need deterministic enforcement
Observability into complex agent interactions

The Hybrid Approach

Don’t make everything an agent. The power of workflows is in the combination:

Use deterministic executors for validation, routing, formatting, compliance checks
Use agentic executors for classification, reasoning, content generation
Use shared state to pass data between executors
Use events for observability and debugging

Keep Executors Focused

Each executor should do one thing well:

PreprocessEmailExecutor: Clean and detect PII
EmailIntakeExecutor: Classify the email
PolicyGateExecutor: Apply business rules
SupportResponderExecutor: Draft responses

This modularity makes testing, debugging, and maintenance significantly easier.

In Conclusion

Agent Framework workflows transform how we build complex AI systems. By providing graph-based orchestration, conditional routing, and shared state management, they enable a hybrid approach that combines the intelligence of LLMs with the reliability of deterministic logic.

The customer support email triage workflow we explored demonstrates these concepts in action: preprocessing with rules, classification with AI, routing with business logic, and responses crafted by agents — all working together seamlessly.

As you build your own workflows, remember: the power isn’t in making everything intelligent — it’s in applying intelligence exactly where it’s needed, and using deterministic logic everywhere else.

🔗 Explore the complete workflow implementation: AgentFrameworkWorkflows on GitHub

🔍 Start from the beginning: Read Getting Started with Microsoft Agent Framework for the fundamentals

🤝 Your feedback is invaluable! Feel free to drop comments, ask questions, or share your insights and optimizations. Every contribution helps to enhance our collective knowledge and build a resourceful developer community.

Happy Coding! 🚀

Getting Started with Microsoft Agent Framework

Venya Brodetskiy — Sat, 01 Aug 2026 11:38:56 +0000

Originally published on Medium on December 27, 2025.

If you’re building agents in C#/.NET in 2025, the hardest part often isn’t writing prompts — it’s picking a foundation. Should you use Semantic Kernel? AutoGen? The OpenAI / Azure OpenAI SDKs directly? And if you’re in Python, the menu gets even longer.

Microsoft created Microsoft Agent Framework (MAF) to reduce that “framework roulette”. The idea (based on Microsoft’s own announcement posts) is to unify two things developers kept having to choose between:

Semantic Kernel’s enterprise-friendly SDK approach (connectors, platform integration, a stable developer surface)
AutoGen-style multi-agent orchestration patterns (coordination, handoffs, richer agent-to-agent flows)

In other words: one open-source SDK + runtime that’s meant to carry you from local experiments to production systems, without rewriting your agent when you move from “demo” to “deployment”.

If you want Microsoft’s official framing and roadmap language, read these two posts:

- Semantic Kernel team perspective (including SK support expectations)

- Foundry announcement (the “why now” + pillars)

In this guide, we’ll focus on the basics through runnable demos from my repo: agents that call functions, produce structured output, persist threads, integrate with Azure AI Foundry, and use RAG.

What is Agent Framework?

Agent Framework is an open-source SDK and runtime for building AI agents and orchestrating them into workflows. Today it’s in public preview, and Microsoft positions it as the successor to Semantic Kernel for agent development — effectively “Semantic Kernel v2”.

That doesn’t mean Semantic Kernel disappears overnight. Microsoft’s stated intent is to keep supporting Semantic Kernel v1.x for the foreseeable future (critical bug fixes and security fixes, plus some features reaching GA), while most new investment goes into Agent Framework.

The framework focuses on two core capabilities:

1. AI Agents: Individual agents that use LLMs to process inputs, call tools, and generate responses

2. Workflows: Graph-based orchestration that connects multiple agents and functions to perform complex, multi-step tasks

Why build something new at all? The short version is: agents need more than prompt templates. MAF is designed around enterprise realities — durability for long-running agents, richer observability, better portability/interoperability, and a clearer path from local dev to managed hosting.

You can learn more in the official Microsoft Agent Framework documentation

Prerequisites

Before diving in, make sure you have:

.NET 10.0 SDK or later
Azure OpenAI account with:\ – API endpoint\ – API key\ – Model deployment (e.g., gpt-4.1, gpt-5.2)\ – Embedding model deployment (for RAG examples)

Most projects require an appsettings.json or appsettings.Development.json file with your Azure OpenAI configuration:

{
  "ModelName": "your-model-deployment-name",
  "Endpoint": "https://your-resource.openai.azure.com/",
  "ApiKey": "your-api-key",
  "EmbeddingModel": "your-embedding-model-name"
}

⚠️ Note: Agent Framework is currently in public preview. APIs may evolve in future releases.

Core Concepts

Before we jump into examples, let’s establish the foundational concepts:

AIAgent: The core abstraction representing an AI agent. It encapsulates the LLM, instructions, and tools the agent can use.

Tools/Functions: Actions your agent can perform — from simple C# methods to complex API calls. Agent Framework uses AIFunctionFactory to convert methods into tools the LLM can call. For a deep dive on function calling, check out OpenAI’s function calling guide.

AgentThread: Manages conversation context and history. Think of it as the stateful container for your agent’s interactions with users.

With these building blocks in mind, let’s see them in action.

Example 1: Simple Agent with Function Calling

Let’s start with the fundamentals: creating an agent that can call tools.

// Define a function the agent can call
[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.";

// Convert the function to a tool
var weatherFunction = AIFunctionFactory.Create(GetWeather);
// Create the agent
var agent = new AzureOpenAIClient(
        new Uri(endpoint),
        new AzureKeyCredential(apiKey))
    .GetChatClient(modelName)
    .CreateAIAgent(
        instructions: "say 'just a second' before answering question",
        tools: [weatherFunction],
        name: "myagent");
// Create a thread for conversation
var thread = agent.GetNewThread();
// Run the agent with streaming
var streamingResponse = agent.RunStreamingAsync(userInput, thread);
await foreach (var chunk in streamingResponse)
{
    Console.Write(chunk);
}

What’s happening here?

Function Definition: We define a simple C# method with [Description] attributes. These descriptions are crucial — they’re sent to the LLM to help it understand when and how to use the tool.
Tool Registration: AIFunctionFactory.Create() uses reflection to analyze your method’s signature and attributes, then generates the tool schema the LLM expects. This schema includes parameter names, types, and descriptions.
Agent Creation: CreateAIAgent() is an extension method that wraps the ChatClient and provides agent-specific capabilities. The instructions parameter sets the system prompt that guides the agent’s behavior.
Thread Management: GetNewThread() creates a conversation context that maintains message history. Each thread is isolated, allowing you to manage multiple conversations independently.
Streaming Execution: RunStreamingAsync() sends the user input to the LLM and streams back responses in chunks. This provides immediate feedback to users instead of waiting for the complete response.

Under the Hood: Function Calling Flow

When a user asks “What’s the weather in Paris?”, here’s what happens:

The LLM receives the question and the available tool schemas
It decides to call GetWeather with parameter location: "Paris"
Agent Framework intercepts this, executes your C# method
The result is sent back to the LLM as a “tool message”
The LLM incorporates the result into its final response: “Just a second… The weather in Paris is cloudy with a high of 15°C.”

This orchestration happens automatically — you just define functions and the framework handles the rest.

Why This Matters

Compared to Semantic Kernel’s plugin registration ceremony, this is dramatically simpler:

// Semantic Kernel approach (more verbose)
var kernel = builder.Build();
kernel.ImportPluginFromFunctions("WeatherPlugin",
    new[] { KernelFunctionFactory.CreateFromMethod(GetWeather) });

// Agent Framework approach (concise)
var weatherFunction = AIFunctionFactory.Create(GetWeather);
var agent = chatClient.CreateAIAgent(tools: [weatherFunction]);

You can find the complete implementation in the AgentFramework project.

Example 2: Structured Output

Structured output isn’t unique to Microsoft Agent Framework — it’s a core pattern you’ll want in any serious agent application.

The moment your agent needs to do something concrete (create a ticket, call an API, route a request), free-form text becomes a liability. You don’t want to regex an LLM response — you want a contract.

Why it matters:

Reliable downstream code (typed fields, not prose)
Less prompt wrangling (“valid JSON only” becomes the default)
Easier testing/evals (assert on fields)

There’s a second, underrated effect: a schema becomes a reasoning scaffold. Instead of producing a nice-sounding paragraph, the model has to commit to specific slots (category, entities, action items, etc.), which often makes behavior more decisive.

The tradeoff: if you force the model to fill fields when the input is missing info, it may hallucinate values just to satisfy the schema. Mitigate by designing for uncertainty (nullable fields, "unknown" values, or explicit instructions like “leave fields null if not stated”). OpenAI calls this out explicitly in their Structured Outputs guide: https://platform.openai.com/docs/guides/structured-outputs

MAF supports structured output directly: define a C# type describing the output you want, then call RunAsync<T>(). The framework generates a schema from your type, asks the model for a response that matches it, and deserializes the result back into T.

Here’s how to extract structured information from a meeting transcript:

// Define your output structure with nested types
[Description("Structured meeting information")]
public class MeetingAnalysis
{
    [JsonPropertyName("date")]
    public string? Date { get; set; }
    [JsonPropertyName("duration_minutes")]
    public int? DurationMinutes { get; set; }
    [JsonPropertyName("attendees")]
    public List<string>? Attendees { get; set; }
    [JsonPropertyName("decisions")]
    public List<string>? Decisions { get; set; }
    [JsonPropertyName("action_items")]
    public List<ActionItem>? ActionItems { get; set; }
}
public class ActionItem
{
    [JsonPropertyName("assignee")]
    public string? Assignee { get; set; }
    [JsonPropertyName("task")]
    public string? Task { get; set; }
    [JsonPropertyName("due_date")]
    public string? DueDate { get; set; }
}
// Create the agent
var agent = chatClient.CreateAIAgent(
    name: "MeetingAnalyzer",
    instructions: "You are an assistant that extracts structured information from meeting transcripts.");
// Run with structured output - notice the generic type parameter
var response = await agent.RunAsync<MeetingAnalysis>(
    $"Please analyze this meeting transcript and extract key information:\n\n{meetingTranscript}",
    thread
);
// Access type-safe properties - no parsing needed!
Console.WriteLine($"Meeting Date: {response.Result.Date}");
Console.WriteLine($"Duration: {response.Result.DurationMinutes} minutes");
Console.WriteLine($"Attendees: {string.Join(", ", response.Result.Attendees)}");
foreach (var item in response.Result.ActionItems)
{
    Console.WriteLine($"- {item.Assignee}: {item.Task} (due: {item.DueDate})");
}

How It Works: JSON Schema Generation

When you call RunAsync<MeetingAnalysis>(), Agent Framework:

Generates a JSON schema from your C# class using reflection
Sends it to the LLM as part of the function calling specification
Constrains the response to match your schema exactly
Deserializes the JSON response into your strongly-typed object

The [Description] attributes on your class help the LLM understand what each field represents, improving extraction accuracy. The [JsonPropertyName] attributes control the JSON property names, which is especially useful when working with LLMs that expect specific naming conventions (like snake_case).

Check out the full example in the AgentFrameworkStructuredOutput project.

Example 3: Thread Persistence

In production scenarios, you often need to save and resume conversations. Agent Framework makes this straightforward with custom storage providers.

var agent = chatClient.CreateAIAgent(new ChatClientAgentOptions
{
    Name = "Assistant",
    ChatOptions = new() { Instructions = "You are a helpful assistant." },

    // This is the key: you plug in your own message store.
    // Agent Framework will call it to load/save chat history.
    ChatMessageStoreFactory = ctx => new FileChatMessageStore(ctx.SerializedState)
});

var threadStore = new FileThreadStore(
    storageDirectory: Path.Combine(Environment.CurrentDirectory, "ThreadStorage"));

AgentThread thread;
if (threadStore.Exists)
{
    // Restore the thread state via the agent (not via the thread itself)
    thread = threadStore.Load(serialized => agent.DeserializeThread(serialized));

    // Chat history is loaded from the message store (see below)
    await DisplayHistoricalMessagesAsync(thread);
}
else
{
    thread = agent.GetNewThread();
}

// After each user turn, save thread state
threadStore.Save(thread);

How it works in this demo (two layers)

This project persists two things:

Thread state (via thread.Serialize()): this is what lets you resume the same AgentThread object.
Chat messages (via ChatMessageStore): this is what lets you show conversation history even after a restart.

Thread state is saved as JSON by FileThreadStore. Restoring is done by the agent:

Save: threadStore.Save(thread)
Load: threadStore.Load(serialized => agent.DeserializeThread(serialized))

The message store is intentionally small. In FileChatMessageStore, you mainly override 2–3 members:

AddMessagesAsync(...) to append and persist messages
GetMessagesAsync(...) to load messages
Serialize(...) to persist a stable store id into the thread state (this demo stores a generated thread id, then uses it as a filename)

If you want Redis/SQL/etc, you just need to create your own implementation of ChatMessageStore

Explore the complete implementation in the AgentFrameworkThreadPersistancy project.

Example 4: Azure AI Foundry Integration

Microsoft Foundry (old name: Azure AI Foundry) provides managed agent infrastructure in the cloud. Instead of managing agent lifecycle yourself, you can leverage Foundry’s persistent agents.

// Connect to Azure AI Foundry
var credential = new AzureCliCredential();
var client = new PersistentAgentsClient(
    new Uri(projectEndpoint),
    credential
);

// Create or retrieve a managed agent
var agent = await client.CreateAgentAsync(
    model: modelName,
    instructions: "You are a helpful assistant",
    tools: tools
);
// Use the agent like any other
var thread = await client.CreateThreadAsync();
var response = await client.RunAsync(agent.Id, thread.Id, userMessage);

Why use Foundry?

Cloud-native persistence: Agents and threads are automatically stored
Lifecycle management: No need to handle agent state yourself
Azure integration: Seamless authentication and monitoring
Scale: Leverage Azure’s infrastructure for production workloads

For teams building production systems, Foundry removes significant operational overhead.

See the working example in the AgentFrameworkFoundryAgent project.

Example 5: RAG with Vector Search

Retrieval-Augmented Generation (RAG) enhances agents with external knowledge. In this demo, Agent Framework integrates RAG via TextSearchProvider as an AI context provider: the agent can trigger retrieval on demand, and the provider injects relevant snippets into the prompt.

Setting Up the Vector Store

First, define your document schema using vector store attributes:

private sealed class SearchRecord
{
    // Embedding dimension must match your model (e.g., text-embedding-3-large is 3072)
    private const int EmbeddingDimensions = 3072;
    [VectorStoreKey]
    public required string SourceId { get; init; }
    [VectorStoreData]
    public string? SourceName { get; init; }
    [VectorStoreData]
    public string? SourceLink { get; init; }
    [VectorStoreData(IsFullTextIndexed = true)]
    public string? Text { get; init; }
    [VectorStoreVector(EmbeddingDimensions)]
    public ReadOnlyMemory<float> TextEmbedding { get; init; }
}

These attributes tell the vector store what’s searchable text, what’s metadata, and which field contains the embedding.

Creating and Populating the Knowledge Base

var azureOpenAiClient = new AzureOpenAIClient(
    new Uri(endpoint),
    ncew AzureKeyCredential(apiKey));

// In this demo, we use an in-memory vector store and Azure OpenAI embeddings.
var embeddingGenerator = azureOpenAiClient
    .GetEmbeddingClient(embeddingModel)
    .AsIEmbeddingGenerator();
VectorStore vectorStore = new InMemoryVectorStore(new InMemoryVectorStoreOptions
{
    EmbeddingGenerator = embeddingGenerator
});
// This helper creates the collection and uploads sample documents.
var knowledgeBase = await RagKnowledgeBase.CreateAsync(vectorStore, embeddingGenerator);

Integrating RAG with Your Agent

Func<string, CancellationToken, Task<IEnumerable<TextSearchProvider.TextSearchResult>>> searchAdapter =
    knowledgeBase.SearchAsync;

TextSearchProviderOptions textSearchOptions = new()
{
    SearchTime = TextSearchProviderOptions.TextSearchBehavior.OnDemandFunctionCalling,
    RecentMessageMemoryLimit = 6,
};

var agent = azureOpenAiClient
    .GetChatClient(modelName)
    .CreateAIAgent(new ChatClientAgentOptions
    {
        Name = "myagent",
        ChatOptions = new ChatOptions
        {
            Instructions = "Say 'just a second' before answering."
        },

        // RAG is wired as context provider (not as a normal tool list).
        AIContextProviderFactory = ctx => new TextSearchProvider(
            searchAdapter,
            ctx.SerializedState,
            ctx.JsonSerializerOptions,
            textSearchOptions)
    });

var thread = agent.GetNewThread();
var response = await agent.RunAsync("What's your return policy?", thread);

What Happens Under the Hood:

User query arrives: “What’s your return policy?”
The provider forms a search query (including a bit of recent chat history).
The vector store returns the top matches (this demo uses top 3).
The provider injects the retrieved text into the model’s context.
The model answers grounded in that context.

In production you’d typically swap the in-memory store for a persistent vector backend, but the wiring stays the same.

Dive into the full RAG implementation in the AgentFrameworkRag project.

Bonus: Python Support

Agent Framework isn’t just for C# developers. Microsoft provides Python support, enabling cross-language agent development.

from azure.ai.agents import AIAgent
from azure.ai.openai import AzureOpenAIClient

# Create agent
client = AzureOpenAIClient(endpoint=endpoint, credential=credential)
agent = client.create_agent(
    model=model_name,
    instructions="You are a helpful assistant",
    tools=[weather_tool]
)
# Run the agent
thread = agent.create_thread()
response = agent.run(user_input, thread)

The Python API mirrors the C# design, making it easy to work across languages or migrate existing Python projects to Agent Framework.

Check out the Python example in the AgentFrameworkPython directory.

What’s Next?

We’ve covered the fundamentals — individual agents with various capabilities. But what happens when you need to orchestrate multiple agents and deterministic logic into complex workflows?

That’s where Agent Framework’s workflow system comes in. Workflows let you build graph-based processes that combine LLM agents with business rules, conditional routing, and shared state management.

In the next article, we’ll explore how to build a real-world customer support email triage system that automatically classifies emails, applies business policies, and routes to either automated responses or human escalation.

In Conclusion

Microsoft Agent Framework represents a significant step forward in AI agent development. By learning from Semantic Kernel and AutoGen, it delivers a cleaner, more intuitive API that accelerates development without sacrificing power.

Whether you’re building simple chatbots or complex multi-agent systems, Agent Framework provides the building blocks you need — and as the successor to SK and AutoGen, it’s the future direction for Microsoft’s AI agent ecosystem.

🔗 Explore the complete demo repository: AgentFrameworkPlayground on GitHub

🤝 Your feedback is invaluable! Feel free to drop comments, ask questions, or share your insights and optimizations. Every contribution helps to enhance our collective knowledge and build a resourceful developer community.

Happy Coding! 🚀

AWS Lambda and NestJS: Communication between services

Venya Brodetskiy — Sat, 01 Aug 2026 11:15:31 +0000

Originally published on Medium on November 11, 2023.

In this guide, we’ll speak about communication in a distributed system using AWS Lambda and NestJS.

Building on our previous exploration, where we integrated NestJS with AWS Lambda and set up debugging and hot reload within Docker, this guide takes the next logical step. We’ll use the same foundational setup and enhance it to enable seamless communication between lambdas.

The approach in this guide is inspired by a past project where I used Dapr with C# microservices. Dapr simplifies the challenges of building microservices. For example, instead of manually setting up communication between services, Dapr provides straightforward methods to do so. This lets developers concentrate on writing the actual functionality without getting bogged down by the technical details of inter-service communication. This Lambda + NestJS communication strategy is deeply inspired by the simplicity and effectiveness of Dapr.

If you’re interested in learning more about Dapr and C#, check out my other repository.

This guide focuses on synchronous requests, but I’ll cover asynchronous requests with SQS later on in other guide.

You can find demo application in this repo: https://github.com/VenyaBrodetskiy/Lambda-NestJS-Demo

The demo includes:

An app configured to work locally as per the previous guide.
Implementation of communication between lambdas to function both locally and post-deployment (the focus of this guide).
How to add queues (SQS) to your solution

In the subsequent sections, we’ll break down the steps involved in creating communication between lambdas:

Understanding the Service Design for Simplified Lambda Communication
Building the Lambda Communication service
Enhancing the Lambda Communication Service with Retries
Implementing Lambda Factory to support Local and Cloud Environments

Let’s get started!

Part 1. Understanding the Service Design for Simplified Lambda Communication

The Concept: The goal is to create a service that encapsulates complex logic, making it as user-friendly and straightforward as Dapr. In essence, this service acts as a bridge, simplifying communication between different components of our system.

Practical Example: Let’s illustrate how this service should work with a simple NestJS controller. This controller handles an external request (e.g., from a frontend application or Postman) and communicates with another lambda function to fetch data from a database.

Here’s the code for our PlanController:

import { LambdaCommunicationService } from 'src/core/modules/communication';

@Controller('plan')
export class PlanController {
  private readonly logger = new Logger(PlanController.name);
  constructor(
    private readonly lambdaService: LambdaCommunicationService,
  ) {}

  @Get('/:id')
  public async getPlanById(@Param('id') id: string): Promise<PlanRes> {
    this.logger.log(`Inside ${this.getPlanById.name}, id: ${id}`);

    // service to call other lambda
    const result: PlanRes = await this.lambdaService.invoke<PlanRes>(
      Accessor.Plan,          // name of lambda to be called. `Accessor` is an enum representing different lambda functions
      `/planaccessor/${id}`,  // path of request
      HttpMethod.Get,         // the HTTP method for the request
    );
    return result;
  }

signature of method lambdaService.invoke :

LambdaCommunicationService.invoke<TResponse>(
  service: string, 
  path: string, 
  httpMethod?: HttpMethod, 
  payload?: object): Promise<TResponse>

service: Identifies the name of lambda function to be called.
path: Specifies the request's path.
httpMethod: The HTTP method for the request, defaulting to GET if not specified.
payload: Optional object containing data to be sent to the lambda.

The Benefit: With a service like this, calling other lambdas becomes straightforward. All you need is the function name, the path for the call, the method, and any payload if necessary.

This design significantly reduces development time, as there’s less need to write and maintain complex code for lambda interactions. It also minimizes errors by standardizing how services communicate, ensuring consistency and reliability. Furthermore, such a service improves code readability and maintainability, making it easier for teams to understand and modify the codebase over time.

Note about Error Handling: You might notice the absence of a try-catch block. This is because NestJS has built-in exception filters, which handle errors elegantly. You can learn more about this feature in the NestJS documentation on exception filters. Additionally, my Lambda-NestJS Demo repository contains a custom implementation of an exception filter, though it’s a topic beyond the scope of this guide.

Part 2. Building the Lambda Communication service

In this part let’s implement the service described in Part 1 :

@Injectable()
export class LambdaCommunicationService {
  private readonly logger = new Logger(LambdaCommunicationService.name);
  constructor(private lambdaFactory: LambdaFactory) {}

  public async invoke<TResponse>(
    service: string,
    path: string,
    httpMethod: HttpMethod = HttpMethod.Get,
    payload?: object,
  ): Promise<TResponse> {
    try {
      // get instance of lambda object
      const { lambda, functionName } = this.lambdaFactory.getLambda(service);

      // prepare payload
      const lambdaPayload: ICommunicationPayload = {
        httpMethod: httpMethod,
        path: path,
        body: payload ?? undefined,
        headers: {
          'Content-Type': 'application/json',
        },
      };

      const params: InvokeCommandInput = {
        FunctionName: functionName,
        Payload: JSON.stringify(lambdaPayload),
      };

      this.logger.debug(
        `Inside ${this.invoke.name}. Invoking function: ${params.FunctionName} with payload: ${params.Payload}`,
      );

      // call other lambda using aws-sdk
      const response: InvokeCommandOutput = await lambda.invoke(params);

      // handle the response
      const responsePayload = JSON.parse(Buffer.from(response.Payload).toString());
      if (RetriableStatusCodes.includes(responsePayload.statusCode)) {
        throw new CommunicationException(
          JSON.parse(responsePayload.body),
          responsePayload.statusCode,
        );
      }

      this.logger.debug(
        `Inside ${this.invoke.name}. Lambda invoke response payload: ${JSON.stringify(
          responsePayload,
          null,
          ' ',
        )}`,
      );

      // parse the response to expected type
      if (typeof responsePayload.body === 'string' && this.isJsonString(responsePayload.body)) {
        const result = JSON.parse(responsePayload.body) as TResponse;
        return result;
      }

      return responsePayload.body as TResponse;
    } catch (error: any) {
      if (error.code === 'ECONNREFUSED')
        throw new CommunicationException(
          `Failed to invoke lambda: ${service}`,
          HttpStatus.INTERNAL_SERVER_ERROR,
        );
      throw error;
    }
  }

  private isJsonString(str: string): boolean {
    try {
      JSON.parse(str);
      return true;
    } catch (e) {
      return false;
    }
  }
}

Now I will break down the code above and explain it one by one.

For the first step, we utilize the AWS SDK to instantiate a lambda object. This object is responsible for invoking other lambda functions. Alongside this, we also retrieve the specific function name that we intend to call. The creation and management of this lambda object are efficiently handled by the LambdaFactory. Understanding the workings of LambdaFactory is key to our implementation, and it will be explored in greater detail in the further sections (part 4):

const { lambda, functionName } = this.lambdaFactory.getLambda(service);

2. Next step is to build Lambda Payload and invoke params,invoke lambda:

const lambdaPayload: ICommunicationPayload = {
  ...
};

const params: InvokeCommandInput = {
  ...
};

const response: InvokeCommandOutput = await lambda.invoke(params);

3. Handling the Response

This is a critical step. We need to understand the internal status code in responsePayload to determine if the invocation was successful:

const responsePayload = JSON.parse(Buffer.from(response.Payload).toString());

if (RetriableStatusCodes.includes(responsePayload.statusCode)) {
  throw new CommunicationException(
    ...
  );
}

4. Parsing the Response

The response from the lambda can be an object of type TResponse (defined by the developer) or a string. Here's how we handle it:

if (typeof responsePayload.body === 'string' && this.isJsonString(responsePayload.body)) {
  const result = JSON.parse(responsePayload.body) as TResponse;
  return result;
}

return responsePayload.body as TResponse;

This part of the code checks the type of the body in the response and parses it accordingly. The use of TypeScript allows us to cast the response to the type TResponse specified by the developer.

Part 3. Enhancing the Lambda Communication Service with Retries

In this part, we are adding retry functionality to our Lambda Communication Service. The ability to retry failed requests is a critical feature, particularly for dealing with transient network issues or temporary service unavailability.

Note. However, it’s essential to carefully select HTTP methods due to their idempotency characteristics. GET and DELETE are primarily targeted for retries because they do not change the state in a way that leads to side effects upon repetition. PUT and PATCH can also be considered for retries as they are designed to be idempotent, ensuring that repeated requests result in the same state. However, caution is advised with POST requests, which typically modify state or create resources, could lead to unintended consequences if retried without proper idempotence handling.

Retries should be applied for error codes that indicate transient issues or server errors where a repeat request might succeed. Generally, 5xx series errors (e.g., 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout) are suitable candidates for retries, suggesting temporary server-side issues, but retrying on 501 Not Implemented is not advisable as this error indicates a permanent limitation of the server, and subsequent retries are unlikely to succeed. As for 4xx series errors (e.g., 400 Bad Request, 401 Unauthorized, 404 Not Found), they typically indicate client-side problems that are unlikely to be resolved by retrying without changes to the request. However, transient errors like 408 Request Timeout, 423 Locked, and 429 Too Many Requests can be exceptions, where retrying with a backoff strategy might be successful.

To integrate this feature, we’ll use the async-retry npm package, which provides a straightforward way to implement retry logic. The invoke method in the Lambda Communication Service is enhanced as follows:

Adding a Retry Parameter: The invoke method now includes an additional parameter retries with a default value of 3. This parameter determines the maximum number of retries for a request.

public async invoke<TResponse>(
    service: string,
    path: string,
    httpMethod: HttpMethod = HttpMethod.Get,
    payload?: object,
    retries: number = 3,  // new parameter
  ): Promise<TResponse> {

2. Conditional Retry Logic: We introduce a check to enable retries only for idempotent requests. For other HTTP methods, the effective number of retries is set to zero.

// enable retries only for Retriable Http Methods requests
let effectiveRetries;
if (RetriableHttpMethods.includes(httpMethod)) {
  effectiveRetries = retries;
} else {
  effectiveRetries = 0;
}

3. Retry Mechanism: Using the retry function from the async-retry package, we wrap the actual lambda invocation logic. This function will automatically retry the invocation based on the provided retry conditions.

let responsePayload;
await retry(
  async () => {
    this.logger.debug(
      `Inside ${this.invoke.name}. Invoking function: ${params.FunctionName} with payload: ${params.Payload}`,
    );

    const response = await lambda.invoke(params);
    responsePayload = JSON.parse(Buffer.from(response.Payload).toString());

    if (RetriableStatusCodes.includes(responsePayload.statusCode)) {
      throw new CommunicationException(
        JSON.parse(responsePayload.body),
        responsePayload.statusCode,
      );
    }
  },
  // retry configuration
  {
    retries: effectiveRetries,
    onRetry: (error) => {
      error &&
        this.logger.warn(`Error while calling lambda: ${params.FunctionName} with payload: ${
          params.Payload
        }, retrying...
        Error: ${JSON.stringify(error, null, ' ')}`);
    },
  },
);

Error Handling During Retries: In case of an error during an invocation attempt, an error log is generated. This helps in monitoring and debugging issues related to failed lambda invocations.

By implementing this retry mechanism, we ensure that our Lambda Communication Service is more robust and can handle transient failures more gracefully, thereby improving the overall reliability of the system.

Part 4. Implementing Lambda Factory to support Local and Cloud Environments

In the previous section, we introduced the LambdaFactory within our Lambda Communication Service.

const { lambda, functionName } = this.lambdaFactory.getLambda(service);

Now, let’s explore why it’s important and how to implement it to ensure smooth operation both locally and in the cloud.

The LambdaFactory role is to abstract the creation and configuration of AWS Lambda instances. This abstraction is crucial because it allows our application to adapt dynamically to different environments — local development or cloud deployment—without altering the core business logic.

1. Understanding the LambdaFactory Implementation

Let’s examine the key components of the LambdaFactory service.

lambda-factory.service.ts:

...
import { Configuration } from 'src/config';

interface ILambdaClient {
  lambda: Lambda;
  functionName: string;
}

@Injectable()
export class LambdaFactory {
  private lambdaInstance: Lambda;

  constructor(private config: Configuration) {}

  public getLambda(service: string): ILambdaClient {
    // get function name and endpoint from configuration
    const { name: functionName, endpoint: endpoint } = this.config.getService(service);

    // for cloud
    if (!this.config.IsOffline) {
      this.lambdaInstance = this.lambdaInstance ?? new Lambda({});

      return {
        lambda: this.lambdaInstance,
        functionName: functionName,
      };
    }

    // for local development
    this.lambdaInstance = new Lambda({
      endpoint: endpoint,
    });

    return {
      lambda: this.lambdaInstance,
      functionName: functionName,
    };
  }
}

The getLambda method in the LambdaFactory service is key to configuring the Lambda client instance for either local development or cloud deployment, as determined by the Configuration service. This is crucial for two main reasons:

Local Development: For local testing, especially with the Serverless framework, each Lambda function often requires a unique endpoint. Therefore, the method creates a new Lambda object for each call, ensuring accurate local simulation.
Cloud Deployment: In the cloud, Lambda functions are identified by their names, not endpoints. Here, the method optimizes performance by reusing the same Lambda instance for each invocation, following a singleton-like pattern.

This approach ensures flexibility and consistency across different environments, simplifying development and deployment processes.

2. Understanding the Configuration service

In LambdaFactory we used getService method from Configuration service to fetch specific settings for LambdaCommunicationService, based on defined enums.

configuration.service.ts:

@Injectable()
export class Configuration {
  constructor(private configService: ConfigService) {
    this.validateConfig();
  }

  get IsOffline(): boolean {
    return Boolean(this.configService.get<boolean>('IS_OFFLINE'));
  }

  public getService(service: string): IAcccessorConfig {
    try {
      switch (service) {
        case Accessor.Plan:
          return {
            name: this.configService.getOrThrow<string>('PLANACCESSOR_NAME'),
            endpoint: this.configService.getOrThrow<string>('PLANACCESSOR_ENDPOINT'),
          };
        // case Accessor.OtherAccessor:
        // ...
        default:
          throw new Error(
            `Unknown accessor type. Configuration.service misses accessor: ${service}`,
          );
      }
    } catch (e) {
      throw new Error(e);
    }
  }
  private validateConfig(): void {
    // when running application, this function checks that developer didn't forget to add necessary configs to configuration.service (mostly for enums)

    // Validate accessor configurations
    for (const accessor of Object.values(Accessor)) {
      this.getService(accessor as Accessor);
    }

    // Validate queue configuration not missed
    for (const queue of Object.values(Queue)) {
      this.getQueue(queue as Queue);
    }
  }
}

You will need to do some actions to get benefits from using Configuration service:

Define Enums: Developers need to create enums for different services to streamline configuration retrieval.
Maintain .env File: They must set up and update the .env file with all necessary variables.

Error Handling and Validation: The service includes error handling in the getService method and a validateConfig method to ensure all configurations are correct and complete.

3. Key Benefits of Using LambdaFactory

In summary, the LambdaFactory is a powerful pattern that simplifies the management of environment-specific configurations and enhances the robustness of our Lambda Communication Service, making it adaptable to both local and cloud environments. Let’s sum up advantages of this approach:

Environment Agnostic: LambdaFactory seamlessly switches between local and cloud configurations, enhancing developer productivity and reducing environment-specific bugs.
Configurational Flexibility: By centralizing Lambda configurations, it allows easy updates and maintenance of service configurations without altering the core logic.
Enhanced Readability: The clear separation of concerns and abstraction of environment-specific details make the code more readable and maintainable.

In Conclusion

As we finish this guide on improving communication in AWS Lambda with NestJS, we’ve explored the details of creating a communication system that works well both for local development and when used in the cloud.

From understanding service design and building a robust Lambda Communication service to implementing a Lambda Factory for environment adaptability, this guide has provided a comprehensive pathway to mastering Lambda communications in a distributed system.

🔗 Explore the Demo Repository with the practical implementation of the concepts discussed.

🔍 If you’re keen to see where it all began, revisit the first part of this exploration in my article: “Local Development with AWS Lambda and NestJS: Docker, Debugging, and Hot Reload”.

Happy Coding and looking forward to exploring asynchronous requests with SQS in our upcoming guide! 🚀

Local Development with AWS Lambda and NestJS: Docker Debugging and Hot Reload

Venya Brodetskiy — Sun, 22 Oct 2023 19:15:06 +0000

If you’ve ever worked with C#, Azure Functions, and Visual Studio, you know the comfort. Click here, debug there, drop in Docker with a single click — it’s smooth sailing. Visual Studio does a lot behind the scenes, making our dev life so easy.

But step into AWS Lambdas and Node.js, and the scene changes. Suddenly, things aren’t handed to you on a silver platter. You’re configuring, tweaking, and piecing together bits to make things click.

In this guide, we’re diving into that setup. How to integrate NestJS and AWS Lambda, dockerize it, and even get debugging and hot reload to play nicely inside Docker — all to mimic the ease Visual Studio provides for Azure Functions, but in the Node.js and AWS domain.

Why Integrate NestJS with Lambda?

AWS Lambda provides a serverless computing environment, enabling easy scaling and operational cost savings

NestJS offers a progressive environment for developing scalable server-side applications with Node.js, blending various programming paradigms.

Combining AWS Lambda and NestJS infuses the developer-friendly and flexible environment of NestJS with the serverless, auto-scaling capabilities of AWS Lambda, offering a robust solution for efficient development and deployment.

Advantages of Lambda + NestJS:

Enhanced Scaling: NestJS’s effective HTTP request handling merged with Lambda’s effortless scaling.
Boosted Developer Productivity: Harness NestJS’s developer-friendly aspects in a serverless architecture.
Optimized Costs and Resources: Develop using NestJS’s comfortable environment and deploy with Lambda’s resource-effective strategy.

In the upcoming sections, let’s break down in the steps involved:

Wrapping NestJS with Lambda
Configuring Hot Reload with Nodemon
Setting Up Docker-Compose
Enabling Debugging in VS Code

You can also find demo application in this repo: https://github.com/VenyaBrodetskiy/Lambda-NestJS-Demo

In demo you can find:

configured app according to this guide
how to implement communication between lambdas to work both locally and after deploy
how to add queues (SQS) to your solution

1. Wrapping NestJS with Lambda

In this part I will explain how to wrap the NestJS application within an AWS Lambda function. I used guide from NestJS official documentation, so I will not dive too deep in it here. By link you can also find how NestJS influence on lambda cold start and how to optimize it.

In my case I use serverless-http library, which facilitates the translation of the Lambda event to an HTTP request that a framework (like Express, which NestJS sits on top of) integrates with.

main.ts:

import { NestFactory } from '@nestjs/core';
import serverless, { Handler } from 'serverless-http';
import { AppModule } from './app.module';
import { LogLevel } from '@nestjs/common';

let server: Handler;

async function bootstrap(): Promise<Handler> {
  const isDev: boolean = Boolean(process.env.IS_OFFLINE);
  const logLevels: LogLevel[] = isDev
    ? ['error', 'warn', 'log', 'verbose', 'debug']
    : ['error', 'warn', 'log'];

  const app = await NestFactory.create(AppModule, {
    logger: logLevels,
  });
  await app.init();

  const expressApp = app.getHttpAdapter().getInstance();
  return serverless(expressApp);
}

export const handler: any = async (event: any, context: any) => {
  server = server ?? (await bootstrap());
  return server(event, context);
};

To locally run the Lambda, I’m utilizing the Serverless framework, notable for both emulating Lambda locally and streamlining deployments to AWS.

serverless.yaml:

service: notificationaccessor
frameworkVersion: '3'

provider:
  name: aws
  runtime: nodejs18.x

functions:
  notificationaccessor:
    handler: dist/main.handler
    timeout: 300 # Incremented to prevent timeouts during debugging
    memorySize: 128
    events:
      - httpApi: '*'

plugins: 
  - serverless-offline

custom:
  serverless-offline:
    host: '0.0.0.0' # Vital when operating from within a docker container
    httpPort: ${env:HTTP_PORT, '3002'}
    lambdaPort: ${env:LAMBDA_PORT, '4002'}

notificationaccessoris name of function, feel free to substitute it with your preferred function name
pluginsand custom: Utilize serverless-offline to emulate AWS Lambda and API Gateway on your local machine, essential for local development and testing. Ensure the npm package is installed as a dev dependency.

Post-completion of this stage, you should be capable of running your app utilizing the serverless offlinecommand.

2. Configuring Hot Reload with Nodemon

Adopting Nodemon ensures smooth and efficient local development by automatically restarting application when file changes are detected. Additionally, we’ll be utilizing its features to set the stage for seamless debugging — particularly from within a Docker container.

The configuration for Nodemon is stored in a JSON file, typically named nodemon.json. Here’s how it can be set up for our project:

nodemon.json:

{
  "watch": ["src/**/*.ts", "src/**/*.yaml"],
  "ext": "ts",
  "ignore": ["node_modules"],
  "exec": "nest build && node --inspect=0.0.0.0 node_modules/serverless/bin/serverless offline",
  "legacyWatch": true
}

exec: The command to execute each time an observed file is modified.
nest build: Compiles your NestJS application.
node --inspect=0.0.0.0: Enables the Node.js debugger, binding it to all network interfaces. Crucially, --inspect=0.0.0.0 is essential to permit debugging from inside Docker in forthcoming steps.
node_modules/serverless/bin/serverless offline: Initiates the Serverless Offline plugin.
legacyWatch: A fallback mode which can be useful if native file system events are unreliable.

To invoke Nodemon with this configuration, adjust your npm run start script in your package.json to simply call the nodemon command. For instance:

"scripts": {
  ...
  "start": "nodemon",
  ...
}

With these settings, each time you modify a TypeScript file within the src directory, Nodemon will rebuild your NestJS app and restart the Serverless Offline plugin, while keeping the Node.js debugger accessible for Docker-based debugging in upcoming segments.

3. Setting Up Docker-Compose

Guide to install docker on your machine

Docker is hailed in the development realm for its ability to create a consistent environment across all stages of a project, which simplifies debugging and facilitates collaborative development by keeping the software environment consistent among all developers.

Before we hop into Docker-Compose, let's ensure our Dockerfile is prepared.

Dockerfile:

FROM node:18.18.2-slim

# Installing curl to facilitate health checks if necessary.
RUN apt-get update && apt-get install curl -y

WORKDIR /app

# Copy package manifests and install dependencies
COPY package*.json ./
RUN npm install

# Copy app source to the container
COPY . .

EXPOSE 3000

CMD [ "npm", "start"]

In this Dockerfile, Node 18 is utilized as the base image, ensuring an LTS version to run our app. Dependencies are installed before copying the source code, optimizing Docker cache utilization during builds.

In the docker-compose.yml, one service is defined as an example:

version: '3.8'

services:
  notificationaccessor:
    build: 
      context: ./accessors/accessor.notification
    ports:
      - "3000:3000"
      - "9229:9229"
    environment: 
      - HTTP_PORT=3000
      - LAMBDA_PORT=4000
    volumes:
      - ./accessors/accessor.notification:/app
      - notificationacccessor_nodemodules:/app/node_modules
    # healthcheck to warmup the lambda 
    healthcheck: 
      test: ["CMD", "curl", "-f", "http://localhost:3000"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s

volumes:
  notificationacccessor_nodemodules:

Ports:

3000:3000: Mapping the HTTP port inside Docker to our local to be able to call API Gateway from Postman
9229:9229: Facilitates debugging by mapping the debug port inside Docker to a local port.

Environment Variables:

HTTP_PORT and LAMBDA_PORT: These are correlated with parameters in your serverless.yaml, ensuring consistency between local and Docker-run environments.

Volumes:

./accessors/accessor.notification:/app maps your local code into the Docker container, enabling hot reload and live debugging
notificationacccessor_nodemodules:/app/node_modules ensures that the installed node_modules are utilized and not overwritten by the local volume, aiding in consistency, and speed during local development.

Healthcheck:

While optional, a health check to warmup your Lambda can ensure it's primed and ready. Adjust intervals as needed.

4. Enabling Debugging in VS Code

Now let's configure VS code debugger.

Inside your project's .vscode directory, you'll need to create a launch.json file. This file instructs VS Code on how to manage the startup of your debug environment.

launch.json:

{
  "version": "0.2.0",
  "compounds": [
    {
      "name": "Debug Backend",
      "configurations": ["Debug Manager.Plan", "Debug Accessor.Plan"]
    }
  ],
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Debug Manager.Plan",
      "address": "localhost",
      "port": 9229,
      "localRoot": "${workspaceFolder}/managers/manager.plan",
      "remoteRoot": "/app",
      "protocol": "inspector",
      "restart": true
    },
    ...
  ]
}

Breaking down launch.json:

Compounds: Compound configurations allow you to group multiple debug configurations for simultaneous (or sequential) launch in VS Code.

"name": "Debug Backend": Simply a friendly name for the compound configuration.
"configurations": [ "Debug Manager.Plan", ...]: An array holding all configurations to be launched. If you have more than a single service, you can add here all of them and attach debugger to each of them in one click

Configurations: Array of configurations for attaching the debugger to different containers. Specific points to note:

"address": "localhost" and "port": 9229": Tell VS Code where to find the debugging session to attach to. When you have more than a single container running, you will need to use unique port for each service
localRootand remoteRoot: Paths ensuring VS Code maps local code files to their corresponding paths inside the Docker container.
"restart": true: Ensures the debugger will try to reattach if the connection is lost.

How to Add Configuration for New Service

When expanding your services, you might need to add new debugging configurations. Simply add a new object inside the configurations array. Update the name, port, and localRoot accordingly, ensuring they correspond to the new service context.

To group multiple configurations into a single debug instance, simply add them to the configurations array inside your compound.

Attaching the Debugger

After running docker-compose up, ensure your application is running inside Docker. Now:

In VS Code, navigate to the Run and Debug sidebar.
Select the appropriate compound or individual configuration.
Click on Start Debugging (or press F5).

If configured correctly, VS Code will attach to the debug session running inside your Docker container. You'll be able to set breakpoints, inspect variables, and utilize all the features of the VS Code debugger - right inside your running container.

Optional Setup: Running Backend with a Button in VS Code

To fully embrace a Visual Studio-like experience in VS Code, particularly running your Docker-encapsulated backend with a single-click functionality, you may also configure VS Code to run your Docker-encapsulated backend with a single click, instead of using docker-compose commands directly. This is achievable with the help of VS Code tasks defined in tasks.json within the .vscode folder.

Here's a concise version of tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start backend with docker-compose",
      "type": "shell",
      "command": "docker-compose -f ./docker-compose.yml up",
      "isBackground": true,
      "problemMatcher": []
    }
  ]
}

You will also need to change launch.json, adding new configuration:

{
  "type": "node",
  "request": "attach",
  "name": "Run backend",
  "address": "localhost",
  "preLaunchTask": "Start backend with docker-compose",
}

With the above setup, here's how to run your backend with a click:

In VS Code, navigate to the Run and Debug sidebar.
Select the Run backend configuration

Click on Start(or press F5).
Now select the appropriate compound or individual configuration for debugging and click Start Debugging to attach debugger. Once debugger is attached, you will see it in logs of docker containers.

Now your Docker-encapsulated backend should begin to build and run, directly from within VS Code, simplifying the local development process and ensuring a consistent environment among all developers.

In Conclusion

Thank you for embarking on this journey through local AWS Lambda development with NestJS, leveraging Docker for consistency and hot reload, and enriching the development process with seamless debugging using VS Code.

Your local development with AWS Lambda should now be as smooth and comfortable as possible, mimicking the ease experienced in other development environments.

🔗 Explore the Demo Repository with the practical implementation of the concepts discussed.

Happy Coding! 🚀