microsoft/semantic-kernel · error · ValueError

The service must support structured output.

Error message

The service must support structured output.

What it means

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.

Source

Thrown at python/semantic_kernel/agents/orchestration/magentic.py:252

        Args:
            chat_completion_service (ChatCompletionClientBase): The chat completion service to use.
            prompt_execution_settings (PromptExecutionSettings | None): The prompt execution settings to use.
            **kwargs: Additional keyword arguments for prompts:
                - task_ledger_facts_prompt: The prompt to use for the task ledger facts.
                - task_ledger_plan_prompt: The prompt to use for the task ledger plan.
                - task_ledger_full_prompt: The prompt to use for the full task ledger.
                - task_ledger_facts_update_prompt: The prompt to use for the task ledger facts update.
                - task_ledger_plan_update_prompt: The prompt to use for the task ledger plan update.
                - progress_ledger_prompt: The prompt to use for the progress ledger.
                - final_answer_prompt: The prompt to use for the final answer.
        """
        # Bast effort to make sure the service supports structured output. Even if the service supports
        # structured output, the model may not support it, in which case there is no good way to check.
        if prompt_execution_settings is None:
            prompt_execution_settings = chat_completion_service.instantiate_prompt_execution_settings()
            if not hasattr(prompt_execution_settings, "response_format"):
                raise ValueError("The service must support structured output.")
        else:
            if not hasattr(prompt_execution_settings, "response_format"):
                raise ValueError("The service must support structured output.")
            if getattr(prompt_execution_settings, "response_format", None) is not None:
                raise ValueError("The prompt execution settings must not have a response format set.")

        super().__init__(
            chat_completion_service=chat_completion_service,
            prompt_execution_settings=prompt_execution_settings,
            **kwargs,
        )

    @override
    async def plan(self, magentic_context: MagenticContext) -> ChatMessageContent:
        """Plan the task.

        Args:
            magentic_context (MagenticContext): The context for the Magentic manager.

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Use a chat completion service/backend that supports structured output (e.g. OpenAIChatCompletion with a structured-output-capable model).
2. Pass explicit prompt_execution_settings that expose response_format if your service supports it.
3. Upgrade the connector/service so instantiate_prompt_execution_settings returns a structured-output settings object.
4. Switch to a model/deployment that supports JSON/structured outputs (e.g. gpt-4o).

Example fix

# before - service without response_format support
manager = MagenticStandardManager(chat_completion_service=plain_svc)
# after - use a service whose settings support structured output
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion, OpenAIChatPromptExecutionSettings
svc = OpenAIChatCompletion(service_id="openai", ai_model_id="gpt-4o", api_key=key)
manager = MagenticStandardManager(
    chat_completion_service=svc,
    prompt_execution_settings=OpenAIChatPromptExecutionSettings(),
)

# Confirm the service supports structured output before constructing the manager:
settings = chat_completion_service.instantiate_prompt_execution_settings()
if not hasattr(settings, "response_format"):
    raise ValueError("Use a chat completion service that supports structured output.")

def supports_structured_output(chat_completion_service) -> bool:
    try:
        s = chat_completion_service.instantiate_prompt_execution_settings()
    except Exception:
        return False
    return hasattr(s, "response_format")

try:
    manager = MagenticStandardManager(chat_completion_service=svc)
except ValueError as ex:
    if "structured output" in str(ex):
        # switch to a structured-output-capable service
        svc = make_structured_output_service()
        manager = MagenticStandardManager(chat_completion_service=svc)

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• The prompt execution settings must not have a response forma
• Missing agent description: {agent.Name ?? agent.Id}
• Entry agent is not defined.
• The agent {agent.Name ?? agent.Id} cannot have a handoff to
• The following agents are not defined in the orchestration: {

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