Implementation:Microsoft Semantic kernel Process Build And StartAsync

Knowledge Sources	Semantic Kernel Semantic Kernel Docs
Domains	Process_Orchestration, Runtime_Lifecycle
Last Updated	2026-02-11 19:00 GMT

Overview

Concrete API for materializing and launching event-driven process workflows using processBuilder.Build() and kernelProcess.StartAsync(kernel, initialEvent).

Description

ProcessBuilder.Build() compiles a process definition into an executable KernelProcess object. KernelProcess.StartAsync launches the process with a Kernel instance and an initial KernelProcessEvent, returning a LocalKernelProcessContext that represents the running process. Together, these two methods form the complete process execution lifecycle.

The Build() method resolves all step definitions and event edges into a frozen process graph. It creates a KernelProcessState with the process name, version, and unique identifier, then wraps the built steps and edges into the KernelProcess object.

The StartAsync method accepts the kernel (providing AI services and DI container) and the initial triggering event. The event's Id must match one of the OnInputEvent declarations in the process definition. The returned LocalKernelProcessContext implements IAsyncDisposable and should be used with await using to ensure proper resource cleanup.

Usage

Call Build() after completing all step additions and event routing in the ProcessBuilder. Then call StartAsync on the resulting KernelProcess with a configured kernel and the initial event. Use await using to manage the running process lifetime.

Code Reference

Source Location

• Repository: semantic-kernel
• Sample: dotnet/samples/GettingStartedWithProcesses/Step00/Step00_Processes.cs:L59-68

Key Signatures

// ProcessBuilder.Build - compiles the process definition
public KernelProcess Build(KernelProcessStateMetadata? stateMetadata = null);

// KernelProcess.StartAsync - launches the process
public async Task<LocalKernelProcessContext> StartAsync(
    Kernel kernel,
    KernelProcessEvent initialEvent);

Import

using Microsoft.SemanticKernel;

I/O Contract

Build Inputs

Name	Type	Required	Description
stateMetadata	KernelProcessStateMetadata?	No	Optional state metadata for restoring a process from a previous execution. If null, a fresh state is created.

Build Output

Name	Type	Description
return	KernelProcess	The compiled, immutable process object containing the step graph, edge map, and state.

StartAsync Inputs

Name	Type	Required	Description
kernel	Kernel	Yes	The kernel instance providing AI services, plugins, and the DI service provider.
initialEvent	KernelProcessEvent	Yes	The triggering event. Its Id must match an OnInputEvent declaration in the process definition.

StartAsync Output

Name	Type	Description
return	Task<LocalKernelProcessContext>	An asynchronous handle to the running process. Implements IAsyncDisposable for resource cleanup.

Usage Examples

Simplest Process Execution

The minimal pattern: build the process, start it with a kernel and initial event, and let await using manage the lifetime.

using Microsoft.SemanticKernel;

// Create a simple kernel
Kernel kernel = Kernel.CreateBuilder().Build();

// Define the process
ProcessBuilder process = new("ChatBot");
var startStep = process.AddStepFromType<StartStep>();
var doSomeWorkStep = process.AddStepFromType<DoSomeWorkStep>();
var doMoreWorkStep = process.AddStepFromType<DoMoreWorkStep>();
var lastStep = process.AddStepFromType<LastStep>();

process
    .OnInputEvent(ProcessEvents.StartProcess)
    .SendEventTo(new ProcessFunctionTargetBuilder(startStep));

startStep
    .OnFunctionResult()
    .SendEventTo(new ProcessFunctionTargetBuilder(doSomeWorkStep));

doSomeWorkStep
    .OnFunctionResult()
    .SendEventTo(new ProcessFunctionTargetBuilder(doMoreWorkStep));

doMoreWorkStep
    .OnFunctionResult()
    .SendEventTo(new ProcessFunctionTargetBuilder(lastStep));

lastStep
    .OnFunctionResult()
    .StopProcess();

// Phase 1: Build the process
KernelProcess kernelProcess = process.Build();

// Phase 2: Start the process
await using var runningProcess = await kernelProcess.StartAsync(
    kernel,
    new KernelProcessEvent()
    {
        Id = ProcessEvents.StartProcess,
        Data = null
    });

Process with AI Services

When steps need AI capabilities, configure the kernel with AI service connectors before passing it to StartAsync.

// Create kernel with chat completion service
Kernel kernel = Kernel.CreateBuilder()
    .AddOpenAIChatCompletion(
        modelId: TestConfiguration.OpenAI.ChatModelId,
        apiKey: TestConfiguration.OpenAI.ApiKey)
    .Build();

// Build and start the process
KernelProcess kernelProcess = process.Build();
await using var runningProcess = await kernelProcess.StartAsync(
    kernel,
    new KernelProcessEvent() { Id = "startProcess", Data = null });

Passing Initial Data

The initial event can carry data that is passed to the first step's function parameter.

// Start with initial data payload
await using var runningProcess = await kernelProcess.StartAsync(
    kernel,
    new KernelProcessEvent()
    {
        Id = "StartProcess",
        Data = new CustomerRequest { Name = "Alice", RequestType = "AccountOpening" }
    });

Accessing Process State After Execution

The LocalKernelProcessContext provides access to the process state after execution completes. This is useful for inspecting the final state of steps.

await using LocalKernelProcessContext localProcess =
    await process.StartAsync(
        kernel,
        new KernelProcessEvent()
        {
            Id = AgentOrchestrationEvents.StartProcess
        });

// Access process state after execution
var processState = await localProcess.GetStateAsync();

Generating Mermaid Diagrams

After building, the KernelProcess can generate a Mermaid diagram of the process graph for visualization.

KernelProcess kernelProcess = process.Build();

// Generate a visual diagram of the process
string mermaidGraph = kernelProcess.ToMermaid();
Console.WriteLine(mermaidGraph);

Related Pages

Implements Principle

• Principle:Microsoft_Semantic_kernel_Process_Execution