{"record":{"id":"ae7ba78c63c2a938","repo":"microsoft/semantic-kernel","slug":"unable-to-create-agent","errorCode":null,"errorMessage":"Unable to create agent","messagePattern":"Unable to create agent","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"dotnet/samples/GettingStartedWithAgents/AzureAIAgent/Step08_AzureAIAgent_Declarative.cs","lineNumber":385,"sourceCode":"                    description: The topic of the story.\n                    required: true\n                    default: Cats\n                length:\n                    description: The number of sentences in the story.\n                    required: true\n                    default: 2\n            outputs:\n                output1:\n                    description: output1 description\n            template:\n                format: semantic-kernel\n            \"\"\";\n        AzureAIAgentFactory factory = new();\n        var promptTemplateFactory = new KernelPromptTemplateFactory();\n\n        var agent =\n            await factory.CreateAgentFromYamlAsync(text, new() { Kernel = this._kernel }, TestConfiguration.ConfigurationRoot) ??\n            throw new InvalidOperationException(\"Unable to create agent\");\n\n        var options = new AgentInvokeOptions()\n        {\n            KernelArguments = new()\n            {\n                { \"topic\", \"Dogs\" },\n                { \"length\", \"3\" },\n            }\n        };\n\n        Microsoft.SemanticKernel.Agents.AgentThread? agentThread = null;\n        try\n        {\n            await foreach (var response in agent!.InvokeAsync(Array.Empty<ChatMessageContent>(), agentThread, options))\n            {\n                agentThread = response.Thread;\n                this.WriteAgentChatMessage(response);\n            }","sourceCodeStart":367,"sourceCodeEnd":403,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/samples/GettingStartedWithAgents/AzureAIAgent/Step08_AzureAIAgent_Declarative.cs#L367-L403","documentation":"AzureAIAgentFactory.CreateAgentFromYamlAsync returns Task<Agent?> — a nullable Agent. It parses YAML into an AgentDefinition, then delegates to AgentFactory.CreateAsync, which returns null if no registered factory can handle the agent definition's Type. The ?? throw converts that null into an InvalidOperationException. The YAML 'type' field (e.g., 'foundry_agent') must match a type the factory recognizes.","triggerScenarios":"The YAML's 'type' field is missing, misspelled, or set to a value not registered with the AzureAIAgentFactory; the AgentDefinitionYaml parser couldn't determine the type and the factory's Types collection is empty or doesn't contain the YAML's type; the configuration root is missing required model/credential keys referenced by ${...} tokens in the YAML.","commonSituations":"YAML 'type' field doesn't match the AzureAIAgentFactory's expected type string; using AzureAIAgentFactory with a YAML meant for OpenAIAssistantAgentFactory or ChatCompletionAgentFactory; TestConfiguration.ConfigurationRoot is null or missing the AzureAI section; YAML syntax errors that cause partial parsing; version mismatch where the factory's type registry changed.","solutions":["Ensure the YAML 'type' field is set to the correct value for AzureAIAgentFactory (e.g., 'foundry_agent').","Verify TestConfiguration.ConfigurationRoot contains the required AzureAI configuration section referenced by ${...} tokens.","Check that the YAML is valid and the AgentDefinitionYaml parser consumed it without error (log the parsed AgentDefinition before the null check).","If using a custom factory, ensure your agent type is registered in the factory's Types collection."],"exampleFix":"// before\nvar agent =\n    await factory.CreateAgentFromYamlAsync(text, new() { Kernel = this._kernel }, TestConfiguration.ConfigurationRoot) ??\n    throw new InvalidOperationException(\"Unable to create agent\");\n\n// after — surface the parsed definition and type for diagnosis\nvar agent = await factory.CreateAgentFromYamlAsync(text, new() { Kernel = this._kernel }, TestConfiguration.ConfigurationRoot);\nif (agent is null)\n    throw new InvalidOperationException(\n        $\"Unable to create agent. YAML type: '{parsedType}'. Registered factory types: {string.Join(\", \", factory.Types)}. \" +\n        \"Verify the 'type' field in your YAML and the AzureAI configuration section.\");","handlingStrategy":"validation","validationCode":"// Validate YAML type and configuration before calling the factory\nvar agentDefinition = AgentDefinitionYaml.FromYaml(text, configuration);\nif (string.IsNullOrWhiteSpace(agentDefinition.Type))\n    throw new InvalidOperationException(\"YAML 'type' field is missing or empty.\");\nif (!factory.Types.Contains(agentDefinition.Type))\n    throw new InvalidOperationException($\"Agent type '{agentDefinition.Type}' not registered. Registered: {string.Join(\", \", factory.Types)}\");","typeGuard":null,"tryCatchPattern":"try { var agent = await factory.CreateAgentFromYamlAsync(text, options, config); if (agent is null) logger.LogWarning(\"Factory returned null for YAML type '{Type}'.\", parsedType); } catch (Exception ex) { logger.LogError(ex, \"Agent creation failed.\"); throw; }","preventionTips":["Always set the 'type' field in agent YAML and verify it matches the factory's registered types.","Ensure TestConfiguration.ConfigurationRoot contains all ${...} token references in the YAML.","Log the parsed AgentDefinition before the null check to diagnose type mismatches."],"tags":["agent","yaml","declarative","azure-ai-agent","factory","null-result"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}