Implementation:Microsoft Semantic kernel AddStepFromAgent

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

Overview

Concrete API for incorporating AI agents as process steps using process.AddStepFromAgent(agentDefinition), enabling intelligent decision-making within event-driven process workflows.

Description

AddStepFromAgent is a method on ProcessBuilder that creates a process step backed by an AI agent defined through an AgentDefinition. The agent step participates in the process event routing like any other step: it receives input events, invokes the underlying AI model, and emits result events. The method returns a ProcessStepBuilder (or ProcessAgentBuilder) that can be used in standard routing configurations.

The method accepts an AgentDefinition object that specifies the agent's name, description, instructions, model configuration, and type. If no threadName is provided, the builder automatically creates a scoped thread named after the agent. This thread manages the agent's conversation history within the process execution scope.

The generic variant AddStepFromAgent<TProcessState> allows the agent step to access and update typed process state, enabling the agent to make decisions based on accumulated process data.

Usage

Use AddStepFromAgent when you need a process step that leverages an AI model for reasoning, generation, or natural language understanding. Pass an AgentDefinition with the desired model and instructions, then wire the agent step into the process graph using standard event routing.

Code Reference

Source Location

• Repository: semantic-kernel
• Sample: dotnet/samples/GettingStartedWithProcesses/Step04/Step04_AgentOrchestration.cs:L151-162

Key Signatures

// Add an agent step (non-generic)
public ProcessAgentBuilder AddStepFromAgent(
    AgentDefinition agentDefinition,
    string? id = null,
    IReadOnlyList<string>? aliases = null,
    string? threadName = null,
    HITLMode humanInLoopMode = HITLMode.Never);

// Add an agent step with typed process state
public ProcessAgentBuilder<TProcessState> AddStepFromAgent<TProcessState>(
    AgentDefinition agentDefinition,
    string? id = null,
    IReadOnlyList<string>? aliases = null,
    string? threadName = null,
    HITLMode humanInLoopMode = HITLMode.Never)
    where TProcessState : class, new();

Import

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;

I/O Contract

Inputs

Name	Type	Required	Description
agentDefinition	AgentDefinition	Yes	The agent configuration including name, instructions, model, and type. Name must not be null or empty.
id	string?	No	Custom identifier for the step. Defaults to the agent's name.
aliases	IReadOnlyList<string>?	No	Previous step names for backward compatibility.
threadName	string?	No	Name of the conversation thread. If null, a scoped thread is auto-created using the agent's name.
humanInLoopMode	HITLMode	No	Human-in-the-loop mode. Defaults to HITLMode.Never.

Output

Name	Type	Description
return	ProcessAgentBuilder	A step builder for the agent step. Supports standard event routing (OnFunctionResult, OnFunctionError, etc.).

AgentDefinition Properties

Property	Type	Description
Name	string	The display name of the agent. Required.
Description	string?	A description of the agent's purpose.
Instructions	string?	The system prompt / instructions for the agent.
Model	AgentModelDefinition	The AI model configuration (e.g., model Id like "gpt-4o").
Type	string	The agent type identifier (e.g., OpenAIAssistantAgentFactory.OpenAIAssistantAgentType).

Usage Examples

Single Agent as Process Step

The simplest usage: define an agent and add it as a step in a process, then wire events to and from it.

ProcessBuilder process = new("AgentProcess");

var userInputStep = process.AddStepFromType<UserInputStep>();
var renderStep = process.AddStepFromType<RenderMessageStep>();

// Add an AI agent as a process step
var agentStep = process.AddStepFromAgent(new AgentDefinition
{
    Name = "Student",
    Description = "Solves problem given",
    Instructions = "Solve the problem given, if the question is repeated " +
                   "mention something like I already answered but here is the " +
                   "answer with a bit of humor",
    Model = new AgentModelDefinition
    {
        Id = "gpt-4o",
    },
    Type = OpenAIAssistantAgentFactory.OpenAIAssistantAgentType,
});

// Wire the entry point
process.OnInputEvent(AgentOrchestrationEvents.StartProcess)
    .SendEventTo(new ProcessFunctionTargetBuilder(userInputStep));

// User input goes to the agent
userInputStep
    .OnEvent(CommonEvents.UserInputReceived)
    .SendEventTo(new ProcessFunctionTargetBuilder(agentStep, parameterName: "message"))
    .SendEventTo(new ProcessFunctionTargetBuilder(
        renderStep, RenderMessageStep.ProcessStepFunctions.RenderUserText));

// Agent response goes back to user input (loop) and to renderer
agentStep
    .OnFunctionResult()
    .SendEventTo(new ProcessFunctionTargetBuilder(userInputStep))
    .SendEventTo(new ProcessFunctionTargetBuilder(
        renderStep, RenderMessageStep.ProcessStepFunctions.RenderMessage));

// Handle agent errors
agentStep
    .OnFunctionError()
    .SendEventTo(new ProcessFunctionTargetBuilder(
        renderStep, RenderMessageStep.ProcessStepFunctions.RenderError, "error"))
    .StopProcess();

Agent with Deterministic Steps

Combine agent steps with deterministic steps for a hybrid workflow where the agent handles conversation and other steps handle structured operations.

ProcessBuilder process = new("HybridProcess");

var userInputStep = process.AddStepFromType<UserInputStep>();
var renderStep = process.AddStepFromType<RenderMessageStep>();
var managerAgentStep = process.AddStepFromType<ManagerAgentStep>();
var agentGroupStep = process.AddStepFromType<AgentGroupChatStep>();

// Entry point
process.OnInputEvent(AgentOrchestrationEvents.StartProcess)
    .SendEventTo(new ProcessFunctionTargetBuilder(userInputStep));

// User input routed to the manager agent
userInputStep
    .OnEvent(CommonEvents.UserInputReceived)
    .SendEventTo(new ProcessFunctionTargetBuilder(
        managerAgentStep,
        ManagerAgentStep.ProcessStepFunctions.InvokeAgent))
    .SendEventTo(new ProcessFunctionTargetBuilder(
        renderStep,
        RenderMessageStep.ProcessStepFunctions.RenderUserText,
        parameterName: "message"));

// Manager agent delegates to specialist group
managerAgentStep
    .OnEvent(AgentOrchestrationEvents.AgentWorking)
    .SendEventTo(new ProcessFunctionTargetBuilder(
        managerAgentStep,
        ManagerAgentStep.ProcessStepFunctions.InvokeGroup));

// Group provides input to specialist agents
managerAgentStep
    .OnEvent(AgentOrchestrationEvents.GroupInput)
    .SendEventTo(new ProcessFunctionTargetBuilder(
        agentGroupStep, parameterName: "input"));

// Group result returns to manager
agentGroupStep
    .OnEvent(AgentOrchestrationEvents.GroupCompleted)
    .SendEventTo(new ProcessFunctionTargetBuilder(
        managerAgentStep,
        ManagerAgentStep.ProcessStepFunctions.ReceiveResponse,
        parameterName: "response"));

// Manager response displayed and loops back
managerAgentStep
    .OnEvent(AgentOrchestrationEvents.AgentResponded)
    .SendEventTo(new ProcessFunctionTargetBuilder(userInputStep));

Error Handling for Agent Steps

Agent steps can fail due to AI service errors. Use OnFunctionError to handle these failures gracefully within the process.

// Attach error handlers to specific step functions
void AttachErrorStep(ProcessStepBuilder step, params string[] functionNames)
{
    foreach (string functionName in functionNames)
    {
        step
            .OnFunctionError(functionName)
            .SendEventTo(new ProcessFunctionTargetBuilder(
                renderStep,
                RenderMessageStep.ProcessStepFunctions.RenderError,
                "error"))
            .StopProcess();
    }
}

AttachErrorStep(managerAgentStep,
    ManagerAgentStep.ProcessStepFunctions.InvokeAgent,
    ManagerAgentStep.ProcessStepFunctions.InvokeGroup,
    ManagerAgentStep.ProcessStepFunctions.ReceiveResponse);

AttachErrorStep(agentGroupStep,
    AgentGroupChatStep.ProcessStepFunctions.InvokeAgentGroup);

Related Pages

Implements Principle

• Principle:Microsoft_Semantic_kernel_Agent_Process_Integration