microsoft/semantic-kernel · error · AgentInitializationException

Failed to create Copilot Studio Agent settings: {exc}

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.

Source

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

        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,
                client_secret=client_secret,
                client_certificate=client_certificate,
                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,
            mode=connection_settings.auth_mode,
            client_secret=connection_settings.client_secret.get_secret_value()
            if connection_settings.client_secret
            else None,
            client_certificate=Path(client_certificate) if client_certificate else None,
            user_assertion=user_assertion,

View on GitHub (pinned to c028a0c7dc)

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, ...)

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

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)

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

• Failed to create Azure OpenAI settings: {exc}
• AllowedCallersClaimsValidator: config object cannot be None.
• "{self.config_key}" not found in configuration.
• Copilot Studio SERVICE authentication is not available yet.
• CopilotClient cannot be None

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