microsoft/semantic-kernel · error · KernelException

Failed to load the agent for node with id {node.Id}.

Error message

Failed to load the agent for node with id {node.Id}.

What it means

Thrown by BuildDotNetStepAsync when resolving node.Agent.Type throws a TypeLoadException (the step class cannot be loaded). The inner TypeLoadException is wrapped so the node Id is included, distinguishing load failures from missing-type failures.

Source

Thrown at dotnet/src/Experimental/Process.Core/Workflow/WorkflowBuilder.cs:205

            throw new ArgumentException($"The agent specified in the Node with id {node.Id} is not fully specified.");
        }

        // For dotnet node type, the agent type specifies the assembly qualified namespace of the class to be executed.
        Type? dotnetAgentType = null;
        try
        {
            if (stepTypes is not null && stepTypes.TryGetValue(node.Agent.Type, out var type) && type is not null)
            {
                dotnetAgentType = type;
            }
            else
            {
                dotnetAgentType = Type.GetType(node.Agent.Type);
            }
        }
        catch (TypeLoadException tle)
        {
            throw new KernelException($"Failed to load the agent for node with id {node.Id}.", tle);
        }

        if (dotnetAgentType == null)
        {
            throw new KernelException("The agent type specified in the node is not found.");
        }

        var stepBuilder = processBuilder.AddStepFromType(dotnetAgentType, id: node.Id);
        this._stepBuilders[node.Id] = stepBuilder;
        return Task.CompletedTask;
    }

    #endregion

    #region Orchestration

    private Task BuildOrchestrationAsync(List<OrchestrationStep> orchestrationSteps, ProcessBuilder processBuilder)
    {

View on GitHub (pinned to c028a0c7dc)

Solutions

  1. Reference/deploy the assembly containing the step type so Type.GetType can resolve it.
  2. Pass a stepTypes dictionary mapping node.Agent.Type to the resolved Type to avoid runtime assembly probing.
  3. Inspect the inner TypeLoadException for the exact failing assembly/type and fix the name string.
  4. Ensure the assembly-qualified name includes the correct full type name, assembly name, version, and token.

Example fix

// before: assembly not referenced -> TypeLoadException
node.Agent.Type = "MyApp.Steps.MyStep, MyApp.Steps";

// after: pass pre-resolved type map
var stepTypes = new Dictionary<string, Type> { ["MyApp.Steps.MyStep, MyApp.Steps"] = typeof(MyStep) };
await builder.BuildProcessAsync(workflow, yaml, stepTypes);
Defensive patterns

Strategy: try-catch

Validate before calling

var stepTypes = new Dictionary<string, Type> { ["MyApp.Steps.MyStep, MyApp.Steps"] = typeof(MyStep) };
// pass stepTypes to BuildProcessAsync to bypass Type.GetType probing

Type guard

static bool CanResolveType(string name, Dictionary<string, Type>? preloaded) => (preloaded?.ContainsKey(name) == true) || Type.GetType(name) is not null;

Try / catch

try { await builder.BuildProcessAsync(workflow, yaml, stepTypes); }
catch (KernelException ex) when (ex.InnerException is TypeLoadException)
{ /* inspect inner message for the failing assembly/type; deploy or pre-map it */ }

Prevention

When it happens

Trigger: node.Agent.Type is a non-empty string that fails Type.GetType / the stepTypes lookup because the assembly is not referenced, the type name is malformed, or the assembly fails to load.

Common situations: Step assembly not deployed/referenced; assembly-qualified name with a typo or stale version; preloaded stepTypes dictionary missing the requested key while the string form is also unresolvable.

Related errors

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/ce87557b79ddecb5. Report an issue: GitHub.