What causes "Failed to read agent spec file: {e}" in microsoft/semantic-kernel?

Verify the file exists and is readable at the exact path passed (`Path(file_path).exists()` and `.is_file()`).

microsoft/semantic-kernel · error · AgentInitializationException

Failed to read agent spec file: {e}

Error message

Failed to read agent spec file: {e}

What it means

Thrown by AgentRegistry.create_from_file when opening/reading the YAML spec file raises any exception (the broad `except Exception as e` wraps the open/read). The original exception is chained via `from e`. After a successful read the content is forwarded to create_from_yaml, so this error is purely an I/O / path problem, not a YAML parse problem.

Source

Thrown at python/semantic_kernel/agents/agent.py:869

            extras: Additional parameters to resolve placeholders in the YAML.
            encoding: The encoding of the file (default is 'utf-8').
            **kwargs: Additional parameters passed to the agent constructor if required.

        Returns:
            An instance of the requested agent.

        Raises:
            AgentInitializationException: If the file is unreadable or the agent type is unsupported.
        """
        _preload_builtin_agents()

        try:
            if encoding is None:
                encoding = "utf-8"
            with open(file_path, encoding=encoding) as f:
                yaml_str = f.read()
        except Exception as e:
            raise AgentInitializationException(f"Failed to read agent spec file: {e}") from e

        return await AgentRegistry.create_from_yaml(
            yaml_str,
            kernel=kernel,
            plugins=plugins,
            settings=settings,
            extras=extras,
            **kwargs,
        )


# endregion


# region DeclarativeSpecMixin

_D = TypeVar("_D", bound="DeclarativeSpecMixin")

View on GitHub (pinned to c028a0c7dc)

Solutions

Verify the file exists and is readable at the exact path passed (`Path(file_path).exists()` and `.is_file()`).
Pass an explicit `encoding=` matching the file (e.g. 'utf-8-sig' for a BOM file).
Use an absolute path or resolve relative to a known base directory.
Check the chained exception (`__cause__`) for the precise OS-level reason.

Example fix

# before
await AgentRegistry.create_from_file('configs/agent.yaml')  # wrong cwd

# after
from pathlib import Path
base = Path(__file__).parent / 'configs' / 'agent.yaml'
await AgentRegistry.create_from_file(str(base), encoding='utf-8')

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
p = Path(file_path)
assert p.is_file(), f'{file_path} is not a readable file'
assert os.access(p, os.R_OK), f'{file_path} is not readable'

Type guard

from pathlib import Path
def is_readable_spec_file(path: str) -> bool:
    p = Path(path)
    return p.is_file() and os.access(p, os.R_OK)

Try / catch

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    agent = await AgentRegistry.create_from_file(file_path, kernel=kernel)
except AgentInitializationException as e:
    cause = e.__cause__
    logger.error('Could not read %s: %r', file_path, cause)
    raise

Prevention

Use absolute paths resolved from a known base.
Pass an explicit encoding matching the file.
Check existence and read permission before the call.

When it happens

Trigger: Calling create_from_file with a path that does not exist, lacks read permissions, is a directory, or has an encoding mismatch with the declared/utf-8 default encoding.

Common situations: Relative path resolved against an unexpected working directory; file generated with a non-UTF-8 encoding while encoding=None defaults to utf-8; permissions locked down in a container; path passed as a Path object whose str form differs from expectation.

Related errors

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