microsoft/semantic-kernel · error · ArgumentException

AgentDefinition.Name cannot be null or empty.

Error message

AgentDefinition.Name cannot be null or empty.

What it means

Thrown by ProcessBuilder.AddStepFromAgent<TProcessState> when agentDefinition.Name is null, empty, or whitespace. The Name is required because it is used as a default thread name (via AddThread) and as a human-readable identifier for the agent step. This is an ArgumentException (not KernelException).

Source

Thrown at dotnet/src/Experimental/Process.Core/ProcessBuilder.cs:245

        return this.AddStep(stepBuilder, aliases);
    }

    /// <summary>
    /// Adds a step to the process from a declarative agent.
    /// </summary>
    /// <param name="agentDefinition">The <see cref="AgentDefinition"/></param>
    /// <param name="id">The unique Id of the step. If not provided, the name of the step Type will be used.</param>
    /// <param name="aliases">Aliases that have been used by previous versions of the step, used for supporting backward compatibility when reading old version Process States</param>
    /// <param name="threadName">Specifies the thread reference to be used by the agent. If not provided, the agent will create a new thread for each invocation.</param>
    /// <param name="humanInLoopMode">Specifies the human-in-the-loop mode for the agent. If not provided, the default is <see cref="HITLMode.Never"/>.</param>
    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()
    {
        Verify.NotNull(agentDefinition, nameof(agentDefinition));

        if (string.IsNullOrWhiteSpace(agentDefinition.Name))
        {
            throw new ArgumentException("AgentDefinition.Name cannot be null or empty.", nameof(agentDefinition));
        }

        if (string.IsNullOrWhiteSpace(threadName))
        {
            // No thread name was specified so add a new thread for the agent.
            this.AddThread(agentDefinition.Name, KernelProcessThreadLifetime.Scoped);
            threadName = agentDefinition.Name;
        }

        var stepBuilder = new ProcessAgentBuilder<TProcessState>(agentDefinition, threadName: threadName, [], this.ProcessBuilder, id) { HumanInLoopMode = humanInLoopMode }; // TODO: Add inputs to the agent
        return this.AddStep(stepBuilder, aliases);
    }

    /// <summary>
    /// Adds a step to the process from a declarative agent.
    /// </summary>
    /// <param name="agentDefinition">The <see cref="AgentDefinition"/></param>
    /// <param name="id">The unique Id of the step. If not provided, the name of the step Type will be used.</param>

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set agentDefinition.Name to a non-empty string before calling AddStepFromAgent.
2. Validate the agent definition file for a present, non-empty 'name' field.
3. If only Id is available, consider AddStepFromAgentProxy which requires both Id and Name (and will validate accordingly).

Example fix

// before
var def = new AgentDefinition { Id = "agent-001" }; // Name is null
process.AddStepFromAgent<MyState>(def); // throws

// after
var def = new AgentDefinition { Id = "agent-001", Name = "MyAgent" };
process.AddStepFromAgent<MyState>(def);

public static void EnsureAgentName(AgentDefinition def)
{
    if (string.IsNullOrWhiteSpace(def.Name))
    {
        throw new ArgumentException("AgentDefinition.Name is required.", nameof(def));
    }
}

public static bool HasAgentName(AgentDefinition def)
    => !string.IsNullOrWhiteSpace(def.Name);

When it happens

Trigger: Calling the generic AddStepFromAgent<TProcessState> overload with an AgentDefinition whose Name property is null or whitespace. The method checks Name before constructing the ProcessAgentBuilder, unlike the ProcessAgentBuilder constructor which checks Id/Name via null-coalescing.

Common situations: Loading an AgentDefinition from a YAML/JSON file that omits the 'name' field. Creating an AgentDefinition programmatically and setting only Id but not Name. Deserialization issues where Name maps to null.

Related errors

• AgentDefinition.Id cannot be null or empty.
• At least one action must be provided.
• All declarative agents must have an Id or a Name assigned.
• AgentDefinition Id must be set
• Expression must be a property access expression

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