{"record":{"id":"8967b922cfb53a62","repo":"microsoft/semantic-kernel","slug":"failed-to-build-step-from-agent-definition-node","errorCode":null,"errorMessage":"Failed to build step from agent definition: {node.Id}","messagePattern":"Failed to build step from agent definition: (.+?)","errorType":"exception","errorClass":"KernelException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Experimental/Process.Core/Workflow/WorkflowBuilder.cs","lineNumber":139,"sourceCode":"    }\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\n        if (node.OnError != null)\n        {\n            if (node.OnError.Any(c => c is null || c.OnCondition is null))\n            {","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Experimental/Process.Core/Workflow/WorkflowBuilder.cs#L121-L157","documentation":"Thrown by BuildDeclarativeStepAsync when ProcessBuilder.AddStepFromAgent returns a builder that is not a ProcessAgentBuilder. The declarative path assumes an agent-backed step yields a ProcessAgentBuilder so it can attach OnComplete/OnError; any other type indicates a mismatch between the agent definition and the builder factory.","triggerScenarios":"Calling BuildProcessAsync where a declarative node's AgentDefinition causes ProcessBuilder.AddStepFromAgent to return a builder whose runtime type is not ProcessAgentBuilder (e.g. the agent type maps to a non-agent step, or AddStepFromAgent falls back to a generic ProcessStepBuilder).","commonSituations":"An AgentDefinition whose Type resolves to something that is not agent-shaped, or a custom AddStepFromAgent override that returns a generic step builder; version skew where AddStepFromAgent semantics changed.","solutions":["Ensure the AgentDefinition.Type corresponds to a real agent so AddStepFromAgent produces a ProcessAgentBuilder.","If using a custom AddStepFromAgent override, have it return a ProcessAgentBuilder for declarative agents.","Verify the Semantic Kernel version's AddStepFromAgent contract matches your agent definition format."],"exampleFix":"// before: agent type resolves to a plain step\nnode.Agent = new AgentDefinition { Type = \"MyPlainStep\" };\n\n// after: agent type resolves to an agent\nnode.Agent = new AgentDefinition { Type = \"MyAgent\", /* required fields */ };","handlingStrategy":"try-catch","validationCode":"var sb = processBuilder.AddStepFromAgent(agentDef, nodeId);\nif (sb is not ProcessAgentBuilder) throw new KernelException($\"Agent for {nodeId} did not produce a ProcessAgentBuilder.\");","typeGuard":"static bool IsAgentBuilder(ProcessStepBuilder? sb) => sb is ProcessAgentBuilder;","tryCatchPattern":"try { await builder.BuildProcessAsync(workflow, yaml); }\ncatch (KernelException ex) when (ex.Message.Contains(\"Failed to build step from agent\"))\n{ /* verify AgentDefinition.Type resolves to a real agent; check runtime version */ }","preventionTips":["Confirm AgentDefinition.Type maps to an agent, not a plain step, before building.","Pin the Semantic Kernel version whose AddStepFromAgent contract you rely on.","Unit-test agent definitions against AddStepFromAgent to assert ProcessAgentBuilder output."],"tags":["semantic-kernel","process","workflow","declarative","agent","builder"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}