{"record":{"id":"6612d9da311785b3","repo":"microsoft/semantic-kernel","slug":"model-id-required-when-creating-a-new-azure-ai-age","errorCode":null,"errorMessage":"model.id required when creating a new Azure AI agent","messagePattern":"model\\.id required when creating a new Azure AI agent","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/azure_ai/azure_ai_agent.py","lineNumber":548,"sourceCode":"                setattr(definition, \"description\", spec.description)\n            if spec.instructions is not None:\n                setattr(definition, \"instructions\", spec.instructions)\n            if spec.extras:\n                merged_metadata = dict(getattr(definition, \"metadata\", {}) or {})\n                merged_metadata.update(spec.extras)\n                setattr(definition, \"metadata\", merged_metadata)\n\n            return cls(\n                definition=definition,\n                client=client,\n                kernel=kernel,\n                prompt_template_config=prompt_template_config,\n                arguments=arguments,\n                **kwargs,\n            )\n\n        if not (spec.model and spec.model.id):\n            raise ValueError(\"model.id required when creating a new Azure AI agent\")\n\n        # Build tool definitions & resources\n        tool_objs = [_build_tool(t, kernel) for t in spec.tools if t.type != \"function\"]\n        tool_defs = [d for tool in tool_objs for d in (tool.definitions if hasattr(tool, \"definitions\") else [tool])]\n        tool_resources = _build_tool_resources(tool_objs)\n\n        try:\n            agent_definition = await client.agents.create_agent(\n                model=spec.model.id,\n                name=spec.name,\n                description=spec.description,\n                instructions=spec.instructions,\n                tools=tool_defs,\n                tool_resources=tool_resources,\n                metadata=spec.extras,\n                **kwargs,\n            )\n        except Exception as ex:","sourceCodeStart":530,"sourceCodeEnd":566,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/azure_ai/azure_ai_agent.py#L530-L566","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nspec:\n  name: my-agent\n  instructions: ...\n  // no model, no id -> new agent without model\n// after\nspec:\n  name: my-agent\n  model:\n    id: gpt-4o-deployment\n  instructions: ...","handlingStrategy":"validation","validationCode":"def validate_new_agent_spec(spec_dict):\n    has_id = bool(spec_dict.get('id'))\n    has_model_id = bool((spec_dict.get('model') or {}).get('id'))\n    if not has_id and not has_model_id:\n        raise ValueError('New Azure AI agent requires either spec.id (existing) or model.id (new)')\n    return spec_dict","typeGuard":"def spec_has_model_or_id(spec_dict) -> bool:\n    return bool(spec_dict.get('id')) or bool((spec_dict.get('model') or {}).get('id'))","tryCatchPattern":"try:\n    agent = await AzureAIAgent._from_dict(data, kernel=kernel, client=client)\nexcept ValueError as e:\n    if 'model.id required' in str(e):\n        log.error('Provide model.id for new agents, or spec.id to update an existing one')\n    raise","preventionTips":["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."],"tags":["azure-ai","declarative-spec","model","configuration","agent-initialization"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}