microsoft/semantic-kernel · error · ArgumentException

The following agents are not defined in the orchestration: {

Error message

The following agents are not defined in the orchestration: {string.Join(", ", badNames)}

What it means

Thrown by the HandoffOrchestration constructor when the handoff map references agent names that are not among the orchestration members. The constructor builds a set of valid names (members + FirstAgentName) and fails fast (badNames.Length > 0) if any handoff key or value name is unknown — this prevents runtime KeyNotFoundException later.

Source

Thrown at dotnet/src/Agents/Orchestration/Handoff/HandoffOrchestration.cs:39

    /// <summary>
    /// Initializes a new instance of the <see cref="HandoffOrchestration{TInput, TOutput}"/> class.
    /// </summary>
    /// <param name="handoffs">Defines the handoff connections for each agent.</param>
    /// <param name="agents">The agents participating in the orchestration.</param>
    public HandoffOrchestration(OrchestrationHandoffs handoffs, params Agent[] agents)
        : base(agents)
    {
        // Create list of distinct agent names
        HashSet<string> agentNames = new(agents.Select(a => a.Name ?? a.Id), StringComparer.Ordinal)
        {
            handoffs.FirstAgentName
        };
        // Extract names from handoffs that don't align with a member agent.
        string[] badNames = [.. handoffs.Keys.Concat(handoffs.Values.SelectMany(h => h.Keys)).Where(name => !agentNames.Contains(name))];
        // Fail fast if invalid names are present.
        if (badNames.Length > 0)
        {
            throw new ArgumentException($"The following agents are not defined in the orchestration: {string.Join(", ", badNames)}", nameof(handoffs));
        }

        this._handoffs = handoffs;
    }

    /// <summary>
    /// Gets or sets the callback to be invoked for interactive input.
    /// </summary>
    public OrchestrationInteractiveCallback? InteractiveCallback { get; init; }

    /// <inheritdoc />
    protected override async ValueTask StartAsync(IAgentRuntime runtime, TopicId topic, IEnumerable<ChatMessageContent> input, AgentType? entryAgent)
    {
        if (!entryAgent.HasValue)
        {
            throw new ArgumentException("Entry agent is not defined.", nameof(entryAgent));
        }
        await runtime.PublishMessageAsync(input.AsInputTaskMessage(), topic).ConfigureAwait(false);

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Ensure every name in the handoff map matches a member agent's Name (or Id when Name is null) exactly, ordinal case-sensitive.
2. Fix typos / casing to match the registered member names.
3. Generate handoffs from the member list rather than hardcoding strings.

Example fix

// before — "reviewer" is misspelled / not a member
var handoffs = new HandoffLookup { ["writer"] = new() { ["reviwer"] = new(/*...*/) } };
new HandoffOrchestration(new[] { writer, reviewer }, handoffs, ...); // throws

// after
var handoffs = new HandoffLookup { ["writer"] = new() { ["reviewer"] = new(/*...*/) } };

var memberNames = agents.Select(a => a.Name ?? a.Id).ToHashSet(StringComparer.Ordinal);
foreach (var kv in handoffs)
{
    foreach (var name in new[] { kv.Key }.Concat(kv.Value.Keys))
        if (!memberNames.Contains(name))
            throw new InvalidOperationException($"Handoff references unknown agent '{name}'.");
}

When it happens

Trigger: A HandoffLookup whose keys or nested values reference an agent that was not passed into the orchestration's member list — a typo in a name, a renamed agent, or a forgotten member.

Common situations: Renaming an agent but forgetting to update handoff strings; copy-paste handoff definitions; case/whitespace mismatches (names are compared ordinally).

Related errors

• The agent {agent.Name ?? agent.Id} cannot have a handoff to
• Entry agent is not defined.
• Missing agent description: {agent.Name ?? agent.Id}
• Entry agent is not defined.
• Handoffs cannot be empty. Please provide at least one handof

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