What causes "Unknown speaker: {next_speaker}" in microsoft/semantic-kernel?

Ensure each agent.name exactly matches the name used in its description and that names are short, distinct, and model-friendly.

microsoft/semantic-kernel · error · ValueError

Unknown speaker: {next_speaker}

Error message

Unknown speaker: {next_speaker}

What it means

After building the progress ledger, the manager asks the model to pick the next speaker; the answer string must match a key in self._participant_descriptions (the registered agent names). If the model returns a name that isn't a known participant, the manager cannot route the request and raises ValueError.

Source

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

        self._context.chat_history.add_message(
            ChatMessageContent(
                role=AuthorRole.ASSISTANT,
                content=next_step if isinstance(next_step, str) else str(next_step),
                name=self.__class__.__name__,
            )
        )
        await self.publish_message(
            MagenticResponseMessage(
                body=self._context.chat_history.messages[-1],
            ),
            TopicId(self._internal_topic_type, self.id.key),
            cancellation_token=cancellation_token,
        )

        # 2.4 Request the next speaker to speak
        next_speaker = current_progress_ledger.next_speaker.answer
        if next_speaker not in self._participant_descriptions:
            raise ValueError(f"Unknown speaker: {next_speaker}")

        logger.debug(f"Magentic One manager selected agent: {next_speaker}")

        await self.publish_message(
            MagenticRequestMessage(agent_name=next_speaker),
            TopicId(self._internal_topic_type, self.id.key),
            cancellation_token=cancellation_token,
        )

    async def _reset_for_outer_loop(self, cancellation_token: CancellationToken) -> None:
        """Reset the context for the outer loop."""
        if self._context is None:
            raise RuntimeError("The Magentic manager is not started yet. Make sure to send a start message first.")

        await self.publish_message(
            MagenticResetMessage(),
            TopicId(self._internal_topic_type, self.id.key),
            cancellation_token=cancellation_token,

View on GitHub (pinned to c028a0c7dc)

Solutions

Ensure each agent.name exactly matches the name used in its description and that names are short, distinct, and model-friendly.
Switch to a stronger chat completion model for the manager so the speaker answer strictly matches a listed participant.
Customize progress_ledger_prompt to reinforce 'answer must be exactly one of the listed names'.
If subclassing, override the speaker-selection step to fuzzy-match or clamp the answer to a known participant.

Example fix

// before
agents = [
    ChatCompletionAgent(name="Researcher-Bot-9000!!!", description="does research"),
    ChatCompletionAgent(name="researcher", description="also research"),  # ambiguous
]

// after
agents = [
    ChatCompletionAgent(name="Researcher", description="Researcher: gathers information."),
    ChatCompletionAgent(name="Coder", description="Coder: writes code."),
]

Defensive patterns

Strategy: validation

Validate before calling

# Make speaker names model-friendly and stable
for a in members:
    assert a.name and a.name.isidentifier(), f"Bad agent name: {a.name!r}"
    assert a.description and a.name in a.description, "Description should reference the exact name"
result = await orchestration.invoke(task_msg, runtime)

Type guard

def names_are_distinct_and_simple(members) -> bool:
    names = [m.name for m in members]
    return len(set(names)) == len(names) and all(n.isidentifier() for n in names)

Try / catch

try:
    await result.get()
except ValueError as e:
    if "Unknown speaker" in str(e):
        log.warning("Model picked an unknown speaker; retry with a stronger model or clearer names.")
    raise

Prevention

Use short, unique, identifier-safe agent names.
Reference each agent.name verbatim inside its description.
Use a capable model for the manager so speaker answers strictly match the list.

When it happens

Trigger: current_progress_ledger.next_speaker.answer (model output) is not a key in self._participant_descriptions. Happens when the LLM hallucinates a name, returns extra text, or agent.name doesn't match what the prompt/descriptions advertise.

Common situations: Agent names that are hard for the model to reproduce (symbols, long names, similar names). Agent.description or agent.name changed after orchestration construction. Weak model that ignores the participant list. Descriptions that reference different names than agent.name.

Related errors

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