microsoft/semantic-kernel · error · ValueError

model.id required when creating a new Azure AI agent

Error message

model.id required when creating a new Azure AI agent

What it means

Raised as a ValueError by _from_dict() when the declarative spec has no existing assistant id (spec.id falsy) AND the spec.model or spec.model.id is missing. In that branch the agent must create a brand-new assistant via client.beta.assistants.create(model=...), and OpenAI requires a model; without spec.model.id the create call cannot proceed. Note the message text says 'Azure AI agent' though it fires on the OpenAI Assistant path too.

Source

Thrown at python/semantic_kernel/agents/open_ai/openai_assistant_agent.py:505

                setattr(definition, "description", spec.description)
            if spec.instructions is not None:
                setattr(definition, "instructions", spec.instructions)
            if spec.extras:
                merged_metadata = dict(getattr(definition, "metadata", {}) or {})
                merged_metadata.update(spec.extras)
                setattr(definition, "metadata", merged_metadata)

            return cls(
                definition=definition,
                client=client,
                kernel=kernel,
                prompt_template_config=prompt_template_config,
                arguments=arguments,
                **kwargs,
            )

        if not (spec.model and spec.model.id):
            raise ValueError("model.id required when creating a new Azure AI agent")

        # Build tool definitions & resources
        tool_objs = [
            _build_tool(t, kernel) for t in spec.tools if t.type != "function"
        ]  # List[tuple[list[ToolParam], ToolResources]]
        all_tools: list[AssistantToolParam] = []
        all_resources: ToolResources = {}

        for tool_list, resource in tool_objs:
            all_tools.extend(tool_list)
            all_resources.update(resource)

        try:
            agent_definition = await client.beta.assistants.create(
                model=spec.model.id,
                name=spec.name,
                description=spec.description,
                instructions=spec.instructions,

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Add a model.id to your spec, e.g. model: { id: 'gpt-4o' }, so a new assistant can be created.
2. Provide spec.id referencing an existing assistant to skip creation entirely.
3. Validate the spec with AgentSpec.model_validate(data) and assert spec.model and spec.model.id before calling _from_dict.

Example fix

# before
spec = {'name': 'my-agent', 'instructions': '...'}
agent = await OpenAIAssistantAgent.from_dict(spec, kernel=kernel, client=client)

# after
spec = {'name': 'my-agent', 'instructions': '...', 'model': {'id': 'gpt-4o'}}
agent = await OpenAIAssistantAgent.from_dict(spec, kernel=kernel, client=client)

spec = AgentSpec.model_validate(data)
assert spec.id or (spec.model and spec.model.id), 'must provide spec.id (reuse) or spec.model.id (create)'

def spec_has_target(spec: AgentSpec) -> bool:
    return bool(spec.id) or bool(spec.model and spec.model.id)

try:
    agent = await OpenAIAssistantAgent.from_dict(spec, kernel=kernel, client=client)
except ValueError as e:
    if 'model.id' in str(e):
        spec.setdefault('model', {})['id'] = 'gpt-4o'
        agent = await OpenAIAssistantAgent.from_dict(spec, kernel=kernel, client=client)

When it happens

Trigger: Deserializing an agent spec that lacks both an id (to reuse an existing assistant) and a model.id (to create a new one); YAML/template missing the model section; passing a partial spec where model is null.

Common situations: Hand-written YAML agent template without a model block; copying a spec for a different provider and forgetting the model; model field renamed in a spec schema upgrade; spec.model set but spec.model.id omitted.

Related errors

• The OpenAI model ID is required.
• Missing required 'client' in OpenAIAssistantAgent._from_dict
• Unresolved placeholders in spec: {', '.join(f'${{{key}}}' fo
• Failed to create OpenAI settings.
• The OpenAI API key is required.

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