microsoft/semantic-kernel · error · AgentInitializationException

Failed to create Copilot Studio Agent settings

Error message

Failed to create Copilot Studio Agent settings: {exc}

What it means

Raised by CopilotStudioAgent.create_client() when constructing CopilotStudioAgentSettings raises a Pydantic ValidationError. The ValidationError is caught, wrapped in an AgentInitializationException, and chained (from exc). This means one or more settings fields failed Pydantic validation — type mismatches, invalid enum values, or constraint violations.

Solutions

  1. Read the full ValidationError message embedded in the exception (it lists each invalid field and the expected type).
  2. Correct the offending field value — ensure cloud, copilot_agent_type, and auth_mode match their enum members exactly.
  3. Validate env file values against CopilotStudioAgentSettings field definitions before calling create_client().
  4. If loading from a .env file, check env_file_path and env_file_encoding are correct so values are parsed properly.

Example fix

# before — invalid cloud value
client = CopilotStudioAgent.create_client(cloud="prod", ...)

# after — valid PowerPlatformCloud enum member
from microsoft_agents.copilotstudio.client import PowerPlatformCloud
client = CopilotStudioAgent.create_client(cloud=PowerPlatformCloud.PUBLIC, ...)
Defensive patterns

Strategy: try-catch

Validate before calling

from semantic_kernel.agents.copilot_studio.copilot_studio_agent_settings import CopilotStudioAgentSettings

# Pre-validate settings to get the raw ValidationError detail
try:
    settings = CopilotStudioAgentSettings(
        app_client_id=app_client_id, tenant_id=tenant_id, cloud=cloud, ...
    )
except ValidationError as e:
    print(e.errors())  # inspect before it gets wrapped

Try / catch

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException

try:
    client = CopilotStudioAgent.create_client(cloud=cloud, ...)
except AgentInitializationException as exc:
    # exc.__cause__ holds the original Pydantic ValidationError
    detail = exc.__cause__.errors() if exc.__cause__ else str(exc)
    logger.error("Settings validation failed: %s", detail)

Prevention

When it happens

Trigger: Calling create_client() with an invalid value for a typed field, e.g. cloud not a valid PowerPlatformCloud, copilot_agent_type not a valid AgentType, auth_mode not a valid CopilotStudioAgentAuthMode, or env_file_encoding with an unsupported value. Values loaded from a .env file or environment variables that do not parse into the expected types also trigger this.

Common situations: Typos in .env file values (e.g. cloud=sovereign instead of a valid enum); passing a string where an enum is expected; missing required env vars that have no default; version mismatch where an enum gained/lost members.

Related errors

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

Appendix: source

Thrown at python/semantic_kernel/agents/copilot_studio/copilot_studio_agent.py:315

        if auth_mode is not None and isinstance(auth_mode, str):
            auth_mode = CopilotStudioAgentAuthMode(auth_mode)

        try:
            connection_settings = CopilotStudioAgentSettings(
                app_client_id=app_client_id,
                tenant_id=tenant_id,
                environment_id=environment_id,
                agent_identifier=agent_identifier,
                cloud=cloud,
                type=copilot_agent_type,
                custom_power_platform_cloud=custom_power_platform_cloud,
                env_file_path=env_file_path,
                env_file_encoding=env_file_encoding,
                user_assertion=user_assertion,
                auth_mode=auth_mode,
            )
        except ValidationError as exc:
            raise AgentInitializationException(f"Failed to create Copilot Studio Agent settings: {exc}") from exc

        missing_params = [name for name in ("app_client_id", "tenant_id") if not getattr(connection_settings, name)]
        if missing_params:
            raise AgentInitializationException(f"Missing required configuration field(s): {', '.join(missing_params)}")

        cache_file = environ.get("TOKEN_CACHE_PATH_INTERACTIVE") or path.join(
            path.dirname(__file__), "bin", "token_cache_interactive.bin"
        )

        token = _CopilotStudioAgentTokenFactory(
            settings=connection_settings,
            cache_path=cache_file,
        ).acquire()

        return CopilotClient(connection_settings, token)

    # region Invocation Methods

View on GitHub (pinned to 6eab62d273)