What causes "Missing required 'client' in AzureAIAgent._from_dict()" in microsoft/semantic-kernel?

Build the client first (AzureAIAgent.create_client) and pass it as client=client to the declarative loader.

microsoft/semantic-kernel · error · AgentInitializationException

Missing required 'client' in AzureAIAgent._from_dict()

Error message

Missing required 'client' in AzureAIAgent._from_dict()

What it means

Raised by AzureAIAgent._from_dict when the 'client' kwarg is absent or None. Declarative restoration needs an AIProjectClient to fetch/create the agent definition, so a missing client aborts early. Surfaced as AgentInitializationException.

Source

Thrown at python/semantic_kernel/agents/azure_ai/azure_ai_agent.py:503

        *,
        kernel: Kernel,
        prompt_template_config: PromptTemplateConfig | None = None,
        **kwargs,
    ) -> _T:
        """Create an Azure AI Agent from the provided dictionary.

        Args:
            data: The dictionary containing the agent data.
            kernel: The kernel to use for the agent.
            prompt_template_config: The prompt template configuration.
            kwargs: Additional keyword arguments. Note: unsupported keys may raise validation errors.

        Returns:
            AzureAIAgent: The Azure AI Agent instance.
        """
        client: AIProjectClient = kwargs.pop("client", None)
        if client is None:
            raise AgentInitializationException("Missing required 'client' in AzureAIAgent._from_dict()")

        spec = AgentSpec.model_validate(data)

        if "settings" in kwargs:
            kwargs.pop("settings")

        args = data.pop("arguments", None)
        arguments = None
        if args:
            arguments = KernelArguments(**args)

        # Handle arguments from kwargs, merging with any arguments from data
        if "arguments" in kwargs and kwargs["arguments"] is not None:
            incoming_args = kwargs["arguments"]
            arguments = arguments | incoming_args if arguments is not None else incoming_args

        if spec.id:
            existing_definition = await client.agents.get_agent(spec.id)

View on GitHub (pinned to c028a0c7dc)

Solutions

Build the client first (AzureAIAgent.create_client) and pass it as client=client to the declarative loader.
Check your loader/framework forwards **kwargs including 'client' down to _from_dict.
If the spec references an existing agent (spec.id set), you still need the client to fetch its definition.

Example fix

// before
agent = await AzureAIAgent._from_dict(data, kernel=kernel)  // no client
// after
client = await AzureAIAgent.create_client(credential, endpoint)
agent = await AzureAIAgent._from_dict(data, kernel=kernel, client=client)

Defensive patterns

Strategy: validation

Validate before calling

def ensure_client_for_restore(kwargs):
    if kwargs.get('client') is None:
        raise ValueError('client= must be provided to AzureAIAgent._from_dict')
    return kwargs

Type guard

def has_client_kwarg(kwargs) -> bool:
    c = kwargs.get('client')
    return c is not None and hasattr(c, 'agents')

Try / catch

try:
    agent = await AzureAIAgent._from_dict(data, kernel=kernel, **kwargs)
except AgentInitializationException as e:
    if "Missing required 'client'" in str(e):
        log.error('Build and pass client=client to the declarative loader')
    raise

Prevention

Always create the client first and inject it as client= into the loader kwargs.
Ensure any framework wrapper forwards **kwargs including client.
Add a pre-check that kwargs contains a non-None client before calling _from_dict.

When it happens

Trigger: Calling the declarative restore path (e.g. via the agent YAML loader) without supplying client=... in kwargs; passing client=None explicitly; the orchestrator that loads the spec forgot to inject the client.

Common situations: Using a higher-level helper that wraps _from_dict but does not forward the client; switching from direct AzureAIAgent(...) construction to the declarative path and not realizing a client is mandatory; copy-paste from an example that built the client in a different variable.

Related errors

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