microsoft/semantic-kernel · error · AgentInitializationException

model.id required when creating a new OpenAI Responses Agent

Error message

model.id required when creating a new OpenAI Responses Agent.

What it means

Raised by _from_dict() when the validated AgentSpec has no model or no model.id. A declarative Responses Agent spec must name the model it will use, since there is no env-var fallback in this deserialization path. The check is `if not (spec.model and spec.model.id)`.

Source

Thrown at python/semantic_kernel/agents/open_ai/openai_responses_agent.py:560

            raise AgentInitializationException("Missing required 'client' in OpenAIResponsesAgent._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 not (spec.model and spec.model.id):
            raise AgentInitializationException("model.id required when creating a new OpenAI Responses Agent.")

        # Build tool definitions & resources
        tool_objs = [_build_tool(t, kernel) for t in spec.tools if t.type != "function"]

        return cls(
            name=spec.name,
            description=spec.description,
            instruction_role=spec.instructions,
            ai_model_id=spec.model.id,
            client=client,
            arguments=arguments,
            kernel=kernel,
            prompt_template_config=prompt_template_config,
            tools=tool_objs,
            **kwargs,
        )

    @classmethod

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Add a model.id to the spec, e.g. model: { id: 'gpt-4o' }.
2. Validate the spec dict before calling from_dict(): assert data.get('model', {}).get('id').
3. If the model is dynamic, inject it into the data dict before deserialization: data.setdefault('model', {})['id'] = 'gpt-4o'.
4. Check your spec-generation/template step is populating model.id.

Example fix

// before
spec = {"name": "my-agent", "instructions": "..."}
agent = OpenAIResponsesAgent.from_dict(spec, kernel=kernel, client=client)

// after
spec = {"name": "my-agent", "instructions": "...", "model": {"id": "gpt-4o"}}
agent = OpenAIResponsesAgent.from_dict(spec, kernel=kernel, client=client)

model_id = (data.get('model') or {}).get('id')
if not model_id:
    data.setdefault('model', {})['id'] = 'gpt-4o'
agent = OpenAIResponsesAgent.from_dict(data, kernel=kernel, client=client)

def spec_has_model_id(data: dict) -> bool:
    return bool((data.get('model') or {}).get('id'))

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    agent = OpenAIResponsesAgent.from_dict(data, kernel=kernel, client=client)
except AgentInitializationException as e:
    if 'model.id' in str(e):
        data.setdefault('model', {})['id'] = 'gpt-4o'
        agent = OpenAIResponsesAgent.from_dict(data, kernel=kernel, client=client)
    raise

When it happens

Trigger: Loading a YAML/JSON declarative spec whose top-level model field is missing, null, or whose model object lacks an id. The AgentSpec.model_validate(data) succeeds but the model sub-object is empty.

Common situations: Hand-writing a spec file and omitting the model section, a templating step that failed to fill model.id, or an older spec schema that placed the model id elsewhere. Distinct from the env-var path: from_dict() does not fall back to OPENAI_RESPONSES_MODEL_ID.

Related errors

• Expected AzureOpenAISettings, got {type(settings).__name__}
• Expected AzureOpenAISettings, got {type(settings).__name__}
• model.id required when creating a new Azure AI agent
• Missing required 'client' in OpenAIResponsesAgent._from_dict
• The Google AI Gemini model ID is required.

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