{"record":{"id":"8002793bc32d11e8","repo":"microsoft/semantic-kernel","slug":"agentdefinition-id-must-be-set","errorCode":null,"errorMessage":"AgentDefinition Id must be set","messagePattern":"AgentDefinition Id must be set","errorType":"exception","errorClass":"KernelException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Experimental/Process.Core/ProcessAgentBuilder.cs","lineNumber":55,"sourceCode":"    {\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)\n        : base(agentDefinition.Id ?? throw new KernelException(\"AgentDefinition Id must be set\"), processBuilder)\n    {\n        Verify.NotNull(agentDefinition);\n        this._agentDefinition = agentDefinition;\n        this.OnCompleteCodeAction = onComplete;\n        this.OnErrorCodeAction = onError;\n        this.DefaultThreadName = threadName;\n        this.Inputs = nodeInputs;\n    }\n\n    #region Public Interface\n\n    /// <summary>\n    /// The optional resolver for the agent ID. This is used to determine the ID of the agent at runtime.\n    /// </summary>\n    public KernelProcessStateResolver<string?>? AgentIdResolver { get; init; } = null;\n\n    /// <summary>\n    /// The name of the thread that this agent will run on.","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Experimental/Process.Core/ProcessAgentBuilder.cs#L37-L73","documentation":"Thrown by the ProcessAgentBuilder code-actions constructor (the one taking onComplete/onError callbacks) when agentDefinition.Id is null. Unlike the declarative constructor (446), this overload does not fall back to agentDefinition.Name — it strictly requires Id because the code-action agent needs a deterministic, stable identifier for its step.","triggerScenarios":"Constructing a ProcessAgentBuilder with code-based OnComplete/OnError handlers using an AgentDefinition whose Id property is null. The step id is derived directly from agentDefinition.Id with no fallback.","commonSituations":"An agent definition loaded from a file missing the 'id' field but having a 'name'. A programmatically created AgentDefinition where only Name was set. Mixing declarative and code-action constructors without realizing the code-action path has stricter Id requirements.","solutions":["Set agentDefinition.Id to a non-null value before using this constructor overload.","If you only have a Name, use the declarative constructor overload instead, or explicitly provide the Id.","Validate the agent definition's Id field before constructing the builder."],"exampleFix":"// before\nvar def = new AgentDefinition { Name = \"MyAgent\" }; // Id is null\nvar builder = new ProcessAgentBuilder(def, onComplete, onError, \"thread\", [], processBuilder); // throws\n\n// after\nvar def = new AgentDefinition { Id = \"my-agent-001\", Name = \"MyAgent\" };\nvar builder = new ProcessAgentBuilder(def, onComplete, onError, \"thread\", [], processBuilder);","handlingStrategy":"validation","validationCode":"public static void EnsureAgentId(AgentDefinition def)\n{\n    if (string.IsNullOrWhiteSpace(def.Id))\n    {\n        throw new KernelException(\"AgentDefinition.Id is required for code-action agent builders.\");\n    }\n}","typeGuard":"public static bool HasAgentId(AgentDefinition def)\n    => !string.IsNullOrWhiteSpace(def.Id);","tryCatchPattern":null,"preventionTips":["Always set AgentDefinition.Id when using the code-actions constructor.","Validate the Id field before constructing ProcessAgentBuilder with callbacks.","If only Name is available, use the declarative constructor overload instead."],"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"}