{"record":{"id":"40c007fd716748ba","repo":"microsoft/semantic-kernel","slug":"agentdefinition-name-cannot-be-null-or-empty","errorCode":null,"errorMessage":"AgentDefinition.Name cannot be null or empty.","messagePattern":"AgentDefinition\\.Name cannot be null or empty\\.","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Experimental/Process.Core/ProcessBuilder.cs","lineNumber":245,"sourceCode":"\n        return this.AddStep(stepBuilder, aliases);\n    }\n\n    /// <summary>\n    /// Adds a step to the process from a declarative agent.\n    /// </summary>\n    /// <param name=\"agentDefinition\">The <see cref=\"AgentDefinition\"/></param>\n    /// <param name=\"id\">The unique Id of the step. If not provided, the name of the step Type will be used.</param>\n    /// <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>\n    /// <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>\n    /// <param name=\"humanInLoopMode\">Specifies the human-in-the-loop mode for the agent. If not provided, the default is <see cref=\"HITLMode.Never\"/>.</param>\n    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()\n    {\n        Verify.NotNull(agentDefinition, nameof(agentDefinition));\n\n        if (string.IsNullOrWhiteSpace(agentDefinition.Name))\n        {\n            throw new ArgumentException(\"AgentDefinition.Name cannot be null or empty.\", nameof(agentDefinition));\n        }\n\n        if (string.IsNullOrWhiteSpace(threadName))\n        {\n            // No thread name was specified so add a new thread for the agent.\n            this.AddThread(agentDefinition.Name, KernelProcessThreadLifetime.Scoped);\n            threadName = agentDefinition.Name;\n        }\n\n        var stepBuilder = new ProcessAgentBuilder<TProcessState>(agentDefinition, threadName: threadName, [], this.ProcessBuilder, id) { HumanInLoopMode = humanInLoopMode }; // TODO: Add inputs to the agent\n        return this.AddStep(stepBuilder, aliases);\n    }\n\n    /// <summary>\n    /// Adds a step to the process from a declarative agent.\n    /// </summary>\n    /// <param name=\"agentDefinition\">The <see cref=\"AgentDefinition\"/></param>\n    /// <param name=\"id\">The unique Id of the step. If not provided, the name of the step Type will be used.</param>","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Experimental/Process.Core/ProcessBuilder.cs#L227-L263","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set agentDefinition.Name to a non-empty string before calling AddStepFromAgent.","Validate the agent definition file for a present, non-empty 'name' field.","If only Id is available, consider AddStepFromAgentProxy which requires both Id and Name (and will validate accordingly)."],"exampleFix":"// before\nvar def = new AgentDefinition { Id = \"agent-001\" }; // Name is null\nprocess.AddStepFromAgent<MyState>(def); // throws\n\n// after\nvar def = new AgentDefinition { Id = \"agent-001\", Name = \"MyAgent\" };\nprocess.AddStepFromAgent<MyState>(def);","handlingStrategy":"validation","validationCode":"public static void EnsureAgentName(AgentDefinition def)\n{\n    if (string.IsNullOrWhiteSpace(def.Name))\n    {\n        throw new ArgumentException(\"AgentDefinition.Name is required.\", nameof(def));\n    }\n}","typeGuard":"public static bool HasAgentName(AgentDefinition def)\n    => !string.IsNullOrWhiteSpace(def.Name);","tryCatchPattern":null,"preventionTips":["Validate agent definition files for a non-empty 'name' field at load time.","Set Name on programmatically created AgentDefinition instances.","Use AddStepFromAgentProxy if both Id and Name are available and dynamic resolution is needed."],"tags":["semantic-kernel","process-framework","agent-builder","agent-definition","validation","argument"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}