microsoft/semantic-kernel · error · InvalidOperationException

Error loading the manifest: {messages}

Error message

Error loading the manifest: {messages}

What it means

Thrown by CreateChatCompletionAgentFromDeclarativeAgentManifestAsync when DCManifestDocument.LoadAsync reports the declarative agent manifest as invalid. Identical mechanism to the plugin-manifest error (601): problems are aggregated into the message string. Applies to the declarative agent YAML/JSON file itself (name, instructions, actions), not the CAP manifests it may reference.

Source

Thrown at dotnet/src/Functions/Functions.OpenApi.Extensions/Extensions/DeclarativeAgentExtensions.cs:56

        where T : Agent, new()
    {
        Verify.NotNull(kernel);
        Verify.NotNullOrWhiteSpace(filePath);

        var loggerFactory = kernel.LoggerFactory;
        var logger = loggerFactory.CreateLogger(typeof(DeclarativeAgentExtensions)) ?? NullLogger.Instance;
        using var declarativeAgentFileJsonContents = DocumentLoader.LoadDocumentFromFilePathAsStream(filePath,
            logger);

        var results = await DCManifestDocument.LoadAsync(declarativeAgentFileJsonContents, new ReaderOptions
        {
            ValidationRules = [] // Disable validation rules
        }).ConfigureAwait(false);

        if (!results.IsValid)
        {
            var messages = results.Problems.Select(static p => p.Message).Aggregate(static (a, b) => $"{a}, {b}");
            throw new InvalidOperationException($"Error loading the manifest: {messages}");
        }

        var document = results.Document ?? throw new InvalidOperationException("Error loading the manifest");
        var manifestDirectory = Path.GetDirectoryName(filePath);
        document.Instructions = await GetEffectiveInstructionsAsync(manifestDirectory, document.Instructions, logger, cancellationToken).ConfigureAwait(false);

        var agent = new T
        {
            Name = document.Name,
            Instructions = document.Instructions,
            Kernel = kernel,
            Arguments = new KernelArguments(promptExecutionSettings ?? new PromptExecutionSettings()
            {
                FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(),
            }),
            Description = document.Description,
            LoggerFactory = loggerFactory,
            Id = string.IsNullOrEmpty(document.Id) ? Guid.NewGuid().ToString() : document.Id!,

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Read the aggregated messages in the exception text - they identify the offending fields.
2. Run the YAML through a linter to catch indentation/syntax errors before loading.
3. Confirm the manifest is a declarative agent document (has name/instructions/actions at the top level), not a plugin manifest.
4. Use a canonical example from the Semantic Kernel or Teams Toolkit docs as a structural template.

Example fix

// before - file is actually a plugin manifest, not a declarative agent
var agent = await kernel.CreateChatCompletionAgentFromDeclarativeAgentManifestAsync<ChatCompletionAgent>("api-plugin-v2_0.json");

// after - use the declarative agent YAML
var agent = await kernel.CreateChatCompletionAgentFromDeclarativeAgentManifestAsync<ChatCompletionAgent>("agent.yaml");

var text = File.ReadAllText(filePath);
if (!text.Contains("name:") && !text.Contains("\"name\""))
    throw new InvalidOperationException("Declarative agent manifest looks malformed (no name).");

try { await kernel.CreateChatCompletionAgentFromDeclarativeAgentManifestAsync<T>(path, ct); }
catch (InvalidOperationException ex) when (ex.Message.StartsWith("Error loading the manifest"))
{ logger.LogError(ex, "DA manifest invalid: {Msg}", ex.Message); throw; }

When it happens

Trigger: Loading a declarative agent manifest that fails model binding: missing required fields, invalid YAML indentation, unparseable content, or a structure that does not match the declarative-agent schema. ValidationRules are disabled, so this is a structural/deserialization failure.

Common situations: YAML indentation errors (tabs vs spaces, inconsistent nesting); a .yaml file where a colon or list marker is misplaced; referencing $[file(...)] instructions with broken syntax; mixing the declarative-agent schema with the plugin-manifest schema.

Related errors

• Failed to deserialize workflow.
• Error loading the manifest: {messages}
• Error loading the manifest
• Invalid manifest file path.
• Missing 'type' field in agent definition.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/c0589f6fbb94811f. Report an issue: GitHub.