{"record":{"id":"71a032b636be8ec3","repo":"microsoft/semantic-kernel","slug":"declarative-steps-must-have-an-agent-defined","errorCode":null,"errorMessage":"Declarative steps must have an agent defined.","messagePattern":"Declarative steps must have an agent defined\\.","errorType":"exception","errorClass":"KernelException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Experimental/Process.Core/Workflow/WorkflowBuilder.cs","lineNumber":135,"sourceCode":"        else\n        {\n            throw new ArgumentException($\"Unsupported node type: {node.Type}\");\n        }\n    }\n\n    private Task BuildDeclarativeStepAsync(Node node, ProcessBuilder processBuilder)\n    {\n        Verify.NotNull(node);\n\n        // Check for built-in step types\n        if (node.Id.Equals(\"End\", StringComparison.OrdinalIgnoreCase))\n        {\n            var endBuilder = processBuilder.AddEndStep();\n            this._stepBuilders[\"End\"] = endBuilder;\n            return Task.CompletedTask;\n        }\n\n        AgentDefinition? agentDefinition = node.Agent ?? throw new KernelException(\"Declarative steps must have an agent defined.\");\n        var stepBuilder = processBuilder.AddStepFromAgent(agentDefinition, node.Id);\n        if (stepBuilder is not ProcessAgentBuilder agentBuilder)\n        {\n            throw new KernelException($\"Failed to build step from agent definition: {node.Id}\");\n        }\n\n        // ########################### Parsing on_complete and on_error conditions ###########################\n\n        if (node.OnComplete != null)\n        {\n            if (node.OnComplete.Any(c => c is null || c.OnCondition is null))\n            {\n                throw new ArgumentException(\"A complete on_complete condition is required for declarative steps.\");\n            }\n\n            agentBuilder.OnComplete([.. node.OnComplete.Select(c => c.OnCondition!)]);\n        }\n","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Experimental/Process.Core/Workflow/WorkflowBuilder.cs#L117-L153","documentation":"Thrown by BuildDeclarativeStepAsync when a declarative node (not the built-in 'End' node) has no Agent definition. Declarative steps are backed by an AgentDefinition, so a missing node.Agent is treated as an invalid step definition.","triggerScenarios":"A node with Type 'declarative', an Id other than 'End', and node.Agent == null. The null-coalescing throw fires immediately when reading node.Agent.","commonSituations":"Declarative workflow YAML that declares a step but omits the 'agent' block; authoring a declarative step without specifying which agent powers it.","solutions":["Add a complete 'agent' block to the declarative node so node.Agent is non-null.","If the node is meant to be the terminal step, set its Id to 'End' (case-insensitive) which needs no agent.","Validate that every non-End declarative node has an agent before building."],"exampleFix":"// before\nnode.Type = \"declarative\"; node.Id = \"myStep\"; node.Agent = null;\n\n// after\nnode.Agent = new AgentDefinition { Type = \"...\", /* ... */ };","handlingStrategy":"validation","validationCode":"foreach (var n in workflow.Nodes.Where(x => x.Type == \"declarative\" && !x.Id.Equals(\"End\", StringComparison.OrdinalIgnoreCase)))\n    if (n.Agent is null) throw new ArgumentException($\"Declarative node {n.Id} has no agent.\");","typeGuard":"static bool DeclarativeNodeHasAgent(Node n) => n.Id.Equals(\"End\", StringComparison.OrdinalIgnoreCase) || n.Agent is not null;","tryCatchPattern":"try { await builder.BuildProcessAsync(workflow, yaml); }\ncatch (KernelException ex) when (ex.Message.Contains(\"agent defined\"))\n{ /* add the agent block or use Id=End */ }","preventionTips":["Require an agent block for every non-End declarative node in authoring templates.","Run a structural validator over the workflow before building.","Document the End-step special case for terminal nodes."],"tags":["semantic-kernel","process","workflow","declarative","agent"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}