microsoft/semantic-kernel · error · ArgumentException

The agent specified in the Node with id {node.Id} is not ful

Error message

The agent specified in the Node with id {node.Id} is not fully specified.

What it means

Thrown by BuildDotNetStepAsync when a dotnet node's agent is missing or its Type string is empty. The builder needs node.Agent with a non-empty Type (the assembly-qualified name of the step class) to load the step type.

Source

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

            //agentBuilder.WithNodeInputs(node.Inputs); TODO: What to do here?
        }

        this._stepBuilders[node.Id] = stepBuilder;
        return Task.CompletedTask;
    }

    private Task BuildPythonStepAsync(Node node, ProcessBuilder processBuilder)
    {
        throw new KernelException("Python nodes are not supported in the dotnet runtime.");
    }

    private Task BuildDotNetStepAsync(Node node, ProcessBuilder processBuilder, Dictionary<string, Type>? stepTypes = null)
    {
        Verify.NotNull(node);

        if (node.Agent is null || string.IsNullOrEmpty(node.Agent.Type))
        {
            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);

View on GitHub (pinned to c028a0c7dc)

Solutions

Populate node.Agent.Type with the assembly-qualified type name of the target KernelProcessStep subclass.
Use typeof(MyStep).AssemblyQualifiedName to obtain the exact string rather than hand-typing it.
Validate node.Agent?.Type is non-empty for every dotnet node before building.

Example fix

// before
node.Type = "dotnet"; node.Agent = new AgentDefinition { Type = "" };

// after
node.Agent = new AgentDefinition { Type = typeof(MyStep).AssemblyQualifiedName };

Defensive patterns

Strategy: validation

Validate before calling

foreach (var n in workflow.Nodes.Where(x => x.Type == "dotnet"))
    if (n.Agent is null || string.IsNullOrEmpty(n.Agent.Type))
        throw new ArgumentException($"Node {n.Id} agent is not fully specified.");

Type guard

static bool DotNetNodeIsSpecified(Node n) => n.Agent is not null && !string.IsNullOrEmpty(n.Agent.Type);

Try / catch

try { await builder.BuildProcessAsync(workflow, yaml); }
catch (ArgumentException ex) when (ex.Message.Contains("not fully specified"))
{ /* set node.Agent.Type to an assembly-qualified name */ }

Prevention

Always set agent.type to typeof(Step).AssemblyQualifiedName.
Validate dotnet node agents in a pre-build pass.
Use templates that require agent.type for dotnet nodes.

When it happens

Trigger: A node with Type 'dotnet' whose node.Agent is null, or whose node.Agent.Type is null/empty. The guard fires before any type resolution attempt.

Common situations: Workflow YAML with a dotnet node missing the agent.type field; partial agent blocks; typos in the 'type' property name causing it to deserialize as null.

Related errors

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