microsoft/semantic-kernel · error · KernelException

The agent type specified in the node is not found.

Error message

The agent type specified in the node is not found.

What it means

Thrown by BuildDotNetStepAsync when type resolution returns null without throwing. Type.GetType returns null for unqualified or unresolvable names that do not raise TypeLoadException; the builder treats a null result as 'type not found'.

Source

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

        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)
    {
        // If there are no orchestration steps, return
        if (orchestrationSteps.Count == 0)
        {
            return Task.CompletedTask;
        }

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Use the assembly-qualified type name (typeof(MyStep).AssemblyQualifiedName) so Type.GetType can resolve it.
2. Provide a stepTypes dictionary mapping the name string to the Type for reliable resolution.
3. Ensure the type is public and the assembly is loadable in the host context.

Example fix

// before: unqualified name -> null
node.Agent.Type = "MyApp.Steps.MyStep";

// after: assembly-qualified
node.Agent.Type = typeof(MyApp.Steps.MyStep).AssemblyQualifiedName;

if (Type.GetType(node.Agent.Type) is null && !(stepTypes?.ContainsKey(node.Agent.Type) == true))
    throw new KernelException($"Agent type {node.Agent.Type} could not be resolved.");

static bool IsResolvableType(string name, Dictionary<string, Type>? preloaded) => (preloaded?.TryGetValue(name, out _) == true) || Type.GetType(name) is not null;

try { await builder.BuildProcessAsync(workflow, yaml, stepTypes); }
catch (KernelException ex) when (ex.Message.Contains("agent type specified in the node is not found"))
{ /* use assembly-qualified name or add to stepTypes */ }

When it happens

Trigger: node.Agent.Type is a partially-qualified name (no assembly) that Type.GetType cannot resolve and that is absent from the stepTypes dictionary, yielding null without an exception.

Common situations: Passing just the fully qualified namespace name without the assembly qualifier; the type lives in an assembly that Type.GetType cannot probe by default; stepTypes lookup miss.

Related errors

• Failed to load the agent for node with id {node.Id}.
• The agent specified in the Node with id {node.Id} is not ful
• Workflow nodes are not specified.
• Workflow inputs are not specified.
• Unsupported node type: {node.Type}

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