{"record":{"id":"710e3abcfaed7966","repo":"microsoft/semantic-kernel","slug":"entry-agent-is-not-defined-710e3a","errorCode":null,"errorMessage":"Entry agent is not defined.","messagePattern":"Entry agent is not defined\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Agents/Orchestration/Handoff/HandoffOrchestration.cs","lineNumber":55,"sourceCode":"        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);\n        await runtime.PublishMessageAsync(new HandoffMessages.Request(), entryAgent.Value).ConfigureAwait(false);\n    }\n\n    /// <inheritdoc />\n    protected override async ValueTask<AgentType?> RegisterOrchestrationAsync(IAgentRuntime runtime, OrchestrationContext context, RegistrationContext registrar, ILogger logger)\n    {\n        AgentType outputType = await registrar.RegisterResultTypeAsync<HandoffMessages.Result>(response => [response.Message]).ConfigureAwait(false);\n\n        // Each agent handsoff its result to the next agent.\n        Dictionary<string, AgentType> agentMap = [];\n        Dictionary<string, HandoffLookup> handoffMap = [];\n        AgentType agentType = outputType;\n        for (int index = this.Members.Count - 1; index >= 0; --index)\n        {\n            Agent agent = this.Members[index];\n            HandoffLookup map = [];","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Agents/Orchestration/Handoff/HandoffOrchestration.cs#L37-L73","documentation":"Thrown by HandoffOrchestration.StartAsync when entryAgent.HasValue is false. The handoff flow needs a defined entry agent to publish the initial HandoffMessages.Request; without it the orchestration cannot start and fails immediately with ArgumentException. Same shape as 254 but specific to handoff.","triggerScenarios":"Invoking a HandoffOrchestration without specifying the entry agent.","commonSituations":"Invoking the handoff orchestration via an overload that leaves entryAgent unset; missing entry-agent wiring in the orchestration builder.","solutions":["Specify the entry agent when invoking the handoff orchestration.","Ensure the chosen entry agent is one of the registered members."],"exampleFix":"// before\nhandoffOrchestration.InvokeAsync(input); // entryAgent null -> throws\n\n// after\nhandoffOrchestration.InvokeAsync(input, entryAgent: entryAgentType);","handlingStrategy":"validation","validationCode":"// Always pass the entry agent type when invoking a handoff orchestration\nawait handoffOrchestration.InvokeAsync(input, entryAgent: entryAgentType);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always specify the entry agent when invoking HandoffOrchestration.","Ensure the entry agent is among the registered members.","Test the invoke path so a missing entry agent surfaces in CI."],"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"}