What causes "model.id required when creating a new Azure AI agent" in microsoft/semantic-kernel?

Add a model.id to the spec pointing at a deployed model (e.g. gpt-4o deployment name).

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 by AzureAIAgent._from_dict when the spec has no existing agent id (spec.id falsy) AND no model.id, i.e. you are creating a brand-new agent but did not specify which model deployment to use. The Azure Agents API requires a model on creation. Thrown as a plain ValueError.

Source

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

                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"]
        tool_defs = [d for tool in tool_objs for d in (tool.definitions if hasattr(tool, "definitions") else [tool])]
        tool_resources = _build_tool_resources(tool_objs)

        try:
            agent_definition = await client.agents.create_agent(
                model=spec.model.id,
                name=spec.name,
                description=spec.description,
                instructions=spec.instructions,
                tools=tool_defs,
                tool_resources=tool_resources,
                metadata=spec.extras,
                **kwargs,
            )
        except Exception as ex:

View on GitHub (pinned to c028a0c7dc)

Solutions

Add a model.id to the spec pointing at a deployed model (e.g. gpt-4o deployment name).
If updating an existing agent instead, provide spec.id so the code fetches the definition instead of creating.
Ensure any ${AzureAI:ChatModelId} placeholder resolves to a non-empty model_deployment_name in settings.

Example fix

// before
spec:
  name: my-agent
  instructions: ...
  // no model, no id -> new agent without model
// after
spec:
  name: my-agent
  model:
    id: gpt-4o-deployment
  instructions: ...

Defensive patterns

Strategy: validation

Validate before calling

def validate_new_agent_spec(spec_dict):
    has_id = bool(spec_dict.get('id'))
    has_model_id = bool((spec_dict.get('model') or {}).get('id'))
    if not has_id and not has_model_id:
        raise ValueError('New Azure AI agent requires either spec.id (existing) or model.id (new)')
    return spec_dict

Type guard

def spec_has_model_or_id(spec_dict) -> bool:
    return bool(spec_dict.get('id')) or bool((spec_dict.get('model') or {}).get('id'))

Try / catch

try:
    agent = await AzureAIAgent._from_dict(data, kernel=kernel, client=client)
except ValueError as e:
    if 'model.id required' in str(e):
        log.error('Provide model.id for new agents, or spec.id to update an existing one')
    raise

Prevention

Always include a model.id when creating new agents declaratively.
If referencing an existing agent, include its id so the code fetches instead of creates.
Ensure ${AzureAI:ChatModelId} resolves to a non-empty deployment name.

When it happens

Trigger: Declarative spec with no 'id' (new agent) and no 'model.id'; the model block is present but its 'id' is empty; placeholder for model was left unresolved so it became empty after validation.

Common situations: Building a new agent from YAML and forgetting the model section; relying on ${AzureAI:ChatModelId} placeholder that was not resolved (see error 753); wrong key name like model.name or deployment instead of model.id.

Related errors

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