{"record":{"id":"e2e67b2b751d5c0a","repo":"microsoft/semantic-kernel","slug":"the-service-must-support-structured-output","errorCode":null,"errorMessage":"The service must support structured output.","messagePattern":"The service must support structured output\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/orchestration/magentic.py","lineNumber":252,"sourceCode":"\n        Args:\n            chat_completion_service (ChatCompletionClientBase): The chat completion service to use.\n            prompt_execution_settings (PromptExecutionSettings | None): The prompt execution settings to use.\n            **kwargs: Additional keyword arguments for prompts:\n                - task_ledger_facts_prompt: The prompt to use for the task ledger facts.\n                - task_ledger_plan_prompt: The prompt to use for the task ledger plan.\n                - task_ledger_full_prompt: The prompt to use for the full task ledger.\n                - task_ledger_facts_update_prompt: The prompt to use for the task ledger facts update.\n                - task_ledger_plan_update_prompt: The prompt to use for the task ledger plan update.\n                - progress_ledger_prompt: The prompt to use for the progress ledger.\n                - final_answer_prompt: The prompt to use for the final answer.\n        \"\"\"\n        # Bast effort to make sure the service supports structured output. Even if the service supports\n        # structured output, the model may not support it, in which case there is no good way to check.\n        if prompt_execution_settings is None:\n            prompt_execution_settings = chat_completion_service.instantiate_prompt_execution_settings()\n            if not hasattr(prompt_execution_settings, \"response_format\"):\n                raise ValueError(\"The service must support structured output.\")\n        else:\n            if not hasattr(prompt_execution_settings, \"response_format\"):\n                raise ValueError(\"The service must support structured output.\")\n            if getattr(prompt_execution_settings, \"response_format\", None) is not None:\n                raise ValueError(\"The prompt execution settings must not have a response format set.\")\n\n        super().__init__(\n            chat_completion_service=chat_completion_service,\n            prompt_execution_settings=prompt_execution_settings,\n            **kwargs,\n        )\n\n    @override\n    async def plan(self, magentic_context: MagenticContext) -> ChatMessageContent:\n        \"\"\"Plan the task.\n\n        Args:\n            magentic_context (MagenticContext): The context for the Magentic manager.","sourceCodeStart":234,"sourceCodeEnd":270,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/orchestration/magentic.py#L234-L270","documentation":"Raised as a ValueError in MagenticStandardManager.__init__ when prompt_execution_settings is None and the chat_completion_service's default-instantiated settings lack a 'response_format' attribute. The Magentic manager relies on structured output (Pydantic response_format) for its task/progress ledgers, so a service that cannot produce structured output is unusable for it.","triggerScenarios":"Constructing MagenticStandardManager(chat_completion_service=svc) without prompt_execution_settings, where svc.instantiate_prompt_execution_settings() returns an object without a response_format attribute. This is typical for chat-completion services/backends that do not support structured outputs (e.g. some Azure deployments, non-OpenAI connectors).","commonSituations":"Using a chat completion service that does not implement structured output (response_format); an older/custom connector not exposing response_format; a deployment of a model that lacks JSON/structured-output support; passing a base service class instead of a structured-output-capable one.","solutions":["Use a chat completion service/backend that supports structured output (e.g. OpenAIChatCompletion with a structured-output-capable model).","Pass explicit prompt_execution_settings that expose response_format if your service supports it.","Upgrade the connector/service so instantiate_prompt_execution_settings returns a structured-output settings object.","Switch to a model/deployment that supports JSON/structured outputs (e.g. gpt-4o)."],"exampleFix":"# before - service without response_format support\nmanager = MagenticStandardManager(chat_completion_service=plain_svc)\n# after - use a service whose settings support structured output\nfrom semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion, OpenAIChatPromptExecutionSettings\nsvc = OpenAIChatCompletion(service_id=\"openai\", ai_model_id=\"gpt-4o\", api_key=key)\nmanager = MagenticStandardManager(\n    chat_completion_service=svc,\n    prompt_execution_settings=OpenAIChatPromptExecutionSettings(),\n)","handlingStrategy":"validation","validationCode":"# Confirm the service supports structured output before constructing the manager:\nsettings = chat_completion_service.instantiate_prompt_execution_settings()\nif not hasattr(settings, \"response_format\"):\n    raise ValueError(\"Use a chat completion service that supports structured output.\")","typeGuard":"def supports_structured_output(chat_completion_service) -> bool:\n    try:\n        s = chat_completion_service.instantiate_prompt_execution_settings()\n    except Exception:\n        return False\n    return hasattr(s, \"response_format\")","tryCatchPattern":"try:\n    manager = MagenticStandardManager(chat_completion_service=svc)\nexcept ValueError as ex:\n    if \"structured output\" in str(ex):\n        # switch to a structured-output-capable service\n        svc = make_structured_output_service()\n        manager = MagenticStandardManager(chat_completion_service=svc)","preventionTips":["Use a service-specific connector whose settings expose response_format (e.g. OpenAIChatCompletion with gpt-4o).","Pass explicit prompt_execution_settings for that service.","Validate the service's structured-output support before constructing the Magentic manager."],"tags":["orchestration","magentic","structured-output","configuration"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}