{"record":{"id":"63ced99de8211d19","repo":"microsoft/semantic-kernel","slug":"all-declarative-agents-must-have-an-id-or-a-name-a","errorCode":null,"errorMessage":"All declarative agents must have an Id or a Name assigned.","messagePattern":"All declarative agents must have an Id or a Name assigned\\.","errorType":"exception","errorClass":"KernelException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Experimental/Process.Core/ProcessAgentBuilder.cs","lineNumber":36,"sourceCode":"/// Builder for a process step that represents an agent.\n/// </summary>\npublic class ProcessAgentBuilder<TProcessState> : ProcessStepBuilder<KernelProcessAgentExecutor> where TProcessState : class, new()\n{\n    private readonly AgentDefinition _agentDefinition;\n\n    internal Dictionary<string, string> _defaultInputBindings = [];\n\n    /// <summary>\n    /// Creates a new instance of the <see cref=\"ProcessAgentBuilder\"/> class.\n    /// </summary>\n    /// <param name=\"agentDefinition\"></param>\n    /// <param name=\"threadName\"></param>\n    /// <param name=\"nodeInputs\"></param>\n    /// <param name=\"processBuilder\"></param>\n    /// <param name=\"stepId\">Id of the step. If not provided, the Id will come from the agent Id.</param>\n    /// <exception cref=\"KernelException\"></exception>\n    public ProcessAgentBuilder(AgentDefinition agentDefinition, string threadName, Dictionary<string, Type> nodeInputs, ProcessBuilder? processBuilder, string? stepId = null)\n        : base(id: stepId ?? agentDefinition.Id ?? agentDefinition.Name ?? throw new KernelException(\"All declarative agents must have an Id or a Name assigned.\"), processBuilder)\n    {\n        Verify.NotNull(agentDefinition);\n        this._agentDefinition = agentDefinition;\n        this.DefaultThreadName = threadName;\n        this.Inputs = nodeInputs;\n    }\n\n    /// <summary>\n    /// Creates a new instance of the <see cref=\"ProcessAgentBuilder\"/> class.\n    /// </summary>\n    /// <param name=\"agentDefinition\"></param>\n    /// <param name=\"onComplete\"></param>\n    /// <param name=\"onError\"></param>\n    /// <param name=\"threadName\"></param>\n    /// <param name=\"nodeInputs\"></param>\n    /// <param name=\"processBuilder\"></param>\n    /// <exception cref=\"KernelException\"></exception>\n    public ProcessAgentBuilder(AgentDefinition agentDefinition, Action<object?, KernelProcessStepContext> onComplete, Action<object?, KernelProcessStepContext> onError, string threadName, Dictionary<string, Type> nodeInputs, ProcessBuilder processBuilder)","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Experimental/Process.Core/ProcessAgentBuilder.cs#L18-L54","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set agentDefinition.Id or agentDefinition.Name to a non-null value before constructing the builder.","Provide an explicit stepId when calling AddStepFromAgent or the ProcessAgentBuilder constructor.","Validate the agent definition file for the presence of 'id' or 'name' fields before loading it."],"exampleFix":"// before\nvar def = new AgentDefinition(); // Id and Name both null\nvar builder = new ProcessAgentBuilder(def, \"thread\", [], processBuilder); // throws\n\n// after\nvar def = new AgentDefinition { Id = \"my-agent-001\", Name = \"MyAgent\" };\nvar builder = new ProcessAgentBuilder(def, \"thread\", [], processBuilder);","handlingStrategy":"validation","validationCode":"public static string ResolveStepId(AgentDefinition def, string? stepId)\n{\n    var id = stepId ?? def.Id ?? def.Name;\n    if (string.IsNullOrWhiteSpace(id))\n    {\n        throw new KernelException(\"AgentDefinition must have an Id, Name, or explicit stepId.\");\n    }\n    return id;\n}","typeGuard":"public static bool HasValidAgentIdentifier(AgentDefinition def, string? stepId = null)\n    => !string.IsNullOrWhiteSpace(stepId)\n       || !string.IsNullOrWhiteSpace(def.Id)\n       || !string.IsNullOrWhiteSpace(def.Name);","tryCatchPattern":null,"preventionTips":["Always set Id or Name on AgentDefinition before passing to a builder.","Validate agent definition YAML/JSON files for 'id' or 'name' fields at load time.","Provide an explicit stepId as a fallback when loading untrusted definitions."],"tags":["semantic-kernel","process-framework","agent-builder","agent-definition","validation"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}