{"record":{"id":"2c6a3c6f8cd07c5c","repo":"microsoft/semantic-kernel","slug":"the-following-agents-are-not-defined-in-the-orches","errorCode":null,"errorMessage":"The following agents are not defined in the orchestration: {string.Join(\", \", badNames)}","messagePattern":"The following agents are not defined in the orchestration: (.+?)","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Agents/Orchestration/Handoff/HandoffOrchestration.cs","lineNumber":39,"sourceCode":"    /// <summary>\n    /// Initializes a new instance of the <see cref=\"HandoffOrchestration{TInput, TOutput}\"/> class.\n    /// </summary>\n    /// <param name=\"handoffs\">Defines the handoff connections for each agent.</param>\n    /// <param name=\"agents\">The agents participating in the orchestration.</param>\n    public HandoffOrchestration(OrchestrationHandoffs handoffs, params Agent[] agents)\n        : base(agents)\n    {\n        // Create list of distinct agent names\n        HashSet<string> agentNames = new(agents.Select(a => a.Name ?? a.Id), StringComparer.Ordinal)\n        {\n            handoffs.FirstAgentName\n        };\n        // Extract names from handoffs that don't align with a member agent.\n        string[] badNames = [.. handoffs.Keys.Concat(handoffs.Values.SelectMany(h => h.Keys)).Where(name => !agentNames.Contains(name))];\n        // Fail fast if invalid names are present.\n        if (badNames.Length > 0)\n        {\n            throw new ArgumentException($\"The following agents are not defined in the orchestration: {string.Join(\", \", badNames)}\", nameof(handoffs));\n        }\n\n        this._handoffs = handoffs;\n    }\n\n    /// <summary>\n    /// Gets or sets the callback to be invoked for interactive input.\n    /// </summary>\n    public OrchestrationInteractiveCallback? InteractiveCallback { get; init; }\n\n    /// <inheritdoc />\n    protected override async ValueTask StartAsync(IAgentRuntime runtime, TopicId topic, IEnumerable<ChatMessageContent> input, AgentType? entryAgent)\n    {\n        if (!entryAgent.HasValue)\n        {\n            throw new ArgumentException(\"Entry agent is not defined.\", nameof(entryAgent));\n        }\n        await runtime.PublishMessageAsync(input.AsInputTaskMessage(), topic).ConfigureAwait(false);","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Agents/Orchestration/Handoff/HandoffOrchestration.cs#L21-L57","documentation":"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.","triggerScenarios":"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.","commonSituations":"Renaming an agent but forgetting to update handoff strings; copy-paste handoff definitions; case/whitespace mismatches (names are compared ordinally).","solutions":["Ensure every name in the handoff map matches a member agent's Name (or Id when Name is null) exactly, ordinal case-sensitive.","Fix typos / casing to match the registered member names.","Generate handoffs from the member list rather than hardcoding strings."],"exampleFix":"// before — \"reviewer\" is misspelled / not a member\nvar handoffs = new HandoffLookup { [\"writer\"] = new() { [\"reviwer\"] = new(/*...*/) } };\nnew HandoffOrchestration(new[] { writer, reviewer }, handoffs, ...); // throws\n\n// after\nvar handoffs = new HandoffLookup { [\"writer\"] = new() { [\"reviewer\"] = new(/*...*/) } };","handlingStrategy":"validation","validationCode":"var memberNames = agents.Select(a => a.Name ?? a.Id).ToHashSet(StringComparer.Ordinal);\nforeach (var kv in handoffs)\n{\n    foreach (var name in new[] { kv.Key }.Concat(kv.Value.Keys))\n        if (!memberNames.Contains(name))\n            throw new InvalidOperationException($\"Handoff references unknown agent '{name}'.\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Derive handoff names from the member list (Names are ordinal case-sensitive).","Add a pre-flight check that every handoff name resolves to a member.","Rename agents in one place and regenerate handoff maps to avoid typos."],"tags":["orchestration","handoff","configuration","agents","validation"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}