microsoft/semantic-kernel · error · KernelException

All declarative agents must have an Id or a Name assigned.

Error message

All declarative agents must have an Id or a Name assigned.

What it means

Thrown by the ProcessAgentBuilder declarative constructor (the one taking threadName and nodeInputs) when neither stepId, agentDefinition.Id, nor agentDefinition.Name resolves to a non-null string. The builder needs a unique step identifier; the null-coalescing chain falls through to the throw when all three are null.

Source

Thrown at dotnet/src/Experimental/Process.Core/ProcessAgentBuilder.cs:36

/// Builder for a process step that represents an agent.
/// </summary>
public class ProcessAgentBuilder<TProcessState> : ProcessStepBuilder<KernelProcessAgentExecutor> where TProcessState : class, new()
{
    private readonly AgentDefinition _agentDefinition;

    internal Dictionary<string, string> _defaultInputBindings = [];

    /// <summary>
    /// Creates a new instance of the <see cref="ProcessAgentBuilder"/> class.
    /// </summary>
    /// <param name="agentDefinition"></param>
    /// <param name="threadName"></param>
    /// <param name="nodeInputs"></param>
    /// <param name="processBuilder"></param>
    /// <param name="stepId">Id of the step. If not provided, the Id will come from the agent Id.</param>
    /// <exception cref="KernelException"></exception>
    public ProcessAgentBuilder(AgentDefinition agentDefinition, string threadName, Dictionary<string, Type> nodeInputs, ProcessBuilder? processBuilder, string? stepId = null)
        : base(id: stepId ?? agentDefinition.Id ?? agentDefinition.Name ?? throw new KernelException("All declarative agents must have an Id or a Name assigned."), processBuilder)
    {
        Verify.NotNull(agentDefinition);
        this._agentDefinition = agentDefinition;
        this.DefaultThreadName = threadName;
        this.Inputs = nodeInputs;
    }

    /// <summary>
    /// Creates a new instance of the <see cref="ProcessAgentBuilder"/> class.
    /// </summary>
    /// <param name="agentDefinition"></param>
    /// <param name="onComplete"></param>
    /// <param name="onError"></param>
    /// <param name="threadName"></param>
    /// <param name="nodeInputs"></param>
    /// <param name="processBuilder"></param>
    /// <exception cref="KernelException"></exception>
    public ProcessAgentBuilder(AgentDefinition agentDefinition, Action<object?, KernelProcessStepContext> onComplete, Action<object?, KernelProcessStepContext> onError, string threadName, Dictionary<string, Type> nodeInputs, ProcessBuilder processBuilder)

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set agentDefinition.Id or agentDefinition.Name to a non-null value before constructing the builder.
2. Provide an explicit stepId when calling AddStepFromAgent or the ProcessAgentBuilder constructor.
3. Validate the agent definition file for the presence of 'id' or 'name' fields before loading it.

Example fix

// before
var def = new AgentDefinition(); // Id and Name both null
var builder = new ProcessAgentBuilder(def, "thread", [], processBuilder); // throws

// after
var def = new AgentDefinition { Id = "my-agent-001", Name = "MyAgent" };
var builder = new ProcessAgentBuilder(def, "thread", [], processBuilder);

public static string ResolveStepId(AgentDefinition def, string? stepId)
{
    var id = stepId ?? def.Id ?? def.Name;
    if (string.IsNullOrWhiteSpace(id))
    {
        throw new KernelException("AgentDefinition must have an Id, Name, or explicit stepId.");
    }
    return id;
}

public static bool HasValidAgentIdentifier(AgentDefinition def, string? stepId = null)
    => !string.IsNullOrWhiteSpace(stepId)
       || !string.IsNullOrWhiteSpace(def.Id)
       || !string.IsNullOrWhiteSpace(def.Name);

When it happens

Trigger: Constructing a ProcessAgentBuilder (or ProcessAgentBuilder<TProcessState>) with an AgentDefinition whose Id and Name are both null, and without providing an explicit stepId parameter. This typically happens when an AgentDefinition is loaded from YAML/JSON that omits both fields.

Common situations: Loading an agent definition file (YAML/JSON) that is missing both the 'id' and 'name' fields. Creating an AgentDefinition programmatically and forgetting to set Id or Name before passing it to AddStepFromAgent. Schema or deserialization issues where the fields exist but map to null.

Related errors

• AgentDefinition Id must be set
• AgentDefinition.Name cannot be null or empty.
• AgentDefinition.Id cannot be null or empty.
• At least one action must be provided.
• Expression must be a property access expression

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