Principle:Microsoft Semantic kernel Event Routing
| Knowledge Sources | |
|---|---|
| Domains | Process_Orchestration, Event_Driven_Architecture |
| Last Updated | 2026-02-11 19:00 GMT |
Overview
Event routing connects process steps through event-based message passing, forming execution graphs where the output events of one step are declaratively mapped to the input parameters of subsequent steps.
Description
Event Routing is the principle that defines how steps in a Semantic Kernel process communicate. Instead of steps calling each other directly, each step emits events that the process runtime routes to designated target steps based on the routing configuration established at build time. This creates a loosely coupled, message-driven architecture where the process graph topology is defined separately from the step logic.
The routing mechanism operates at three levels:
Process entry routing: External events enter the process through OnInputEvent(eventId), which declares that the process responds to an external event with the given identifier. The SendEventTo method on the returned edge builder specifies which step and function should receive the initial event.
Step-to-step routing: After a step completes execution, its output is routed to the next step using OnFunctionResult() (for the implicit result event) or OnEvent(eventId) (for explicitly emitted named events). The SendEventTo method maps these outputs to ProcessFunctionTargetBuilder objects that specify the target step, and optionally a specific function name and parameter name.
Termination routing: A step's output can terminate the process by calling StopProcess() instead of SendEventTo. This signals the runtime to cease event processing and complete the process execution.
The target specification through ProcessFunctionTargetBuilder allows precise control over routing:
- Specifying only the step targets the step's default (single) function with its default parameter
- Specifying step and function name targets a specific function when the step has multiple [KernelFunction] methods
- Specifying step, function name, and parameter name targets a specific parameter when the function has multiple parameters
This three-tier precision allows the routing system to handle both simple linear chains and complex fan-out/fan-in topologies.
Usage
Use event routing whenever you connect steps within a process. Every process requires at least one entry route (OnInputEvent) and typically requires routes between each pair of connected steps. Use StopProcess() on the final step's output to define process termination.
Theoretical Basis
Event routing in Semantic Kernel processes is an implementation of the Pipes and Filters architectural pattern combined with Publish-Subscribe event semantics.
Directed Event Graph: The routing configuration defines a directed graph where:
- Nodes are step functions (the specific [KernelFunction] method on a step)
- Edges are event routes (SendEventTo declarations)
- Sources are external event entry points (OnInputEvent)
- Sinks are termination points (StopProcess())
Graph G = (V, E) where:
V = {external_event, step1.funcA, step2.funcB, step3.funcC, STOP}
E = {
(external_event → step1.funcA),
(step1.funcA → step2.funcB),
(step2.funcB → step3.funcC),
(step3.funcC → STOP)
}
Fan-Out Semantics: A single event source can route to multiple targets. When a step emits an event, the runtime dispatches it to all registered targets in parallel. This enables fan-out patterns:
step1.OnEvent("E1") → {step2.funcA, step3.funcB} // Fan-out
Parameter Binding: Event routing includes parameter-level targeting. When an event carries data, that data is bound to a specific parameter on the target function:
Route: step1.OnEvent("UserInput") → step2.funcA(parameterName: "userMessage")
Runtime: step2.funcA(userMessage: event.Data)
This parameter binding is resolved at build time by inspecting the target function's KernelFunctionMetadata. If the function has exactly one parameter, the binding is inferred automatically. If it has multiple parameters, the parameterName must be specified explicitly.
Decoupling Through Indirection: Steps never reference each other directly. The routing layer provides indirection that allows the same step to participate in different process graphs with different routing topologies:
Process A: step1 → step2 → step3
Process B: step1 → step3 (skip step2)
Process C: step1 → step2, step1 → step3 (fan-out)
The step implementations remain identical across all three processes; only the routing configuration changes.