microsoft/semantic-kernel · error · ArgumentException

Entry agent is not defined.

Error message

Entry agent is not defined.

What it means

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.

Source

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

        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);
        await runtime.PublishMessageAsync(new HandoffMessages.Request(), entryAgent.Value).ConfigureAwait(false);
    }

    /// <inheritdoc />
    protected override async ValueTask<AgentType?> RegisterOrchestrationAsync(IAgentRuntime runtime, OrchestrationContext context, RegistrationContext registrar, ILogger logger)
    {
        AgentType outputType = await registrar.RegisterResultTypeAsync<HandoffMessages.Result>(response => [response.Message]).ConfigureAwait(false);

        // Each agent handsoff its result to the next agent.
        Dictionary<string, AgentType> agentMap = [];
        Dictionary<string, HandoffLookup> handoffMap = [];
        AgentType agentType = outputType;
        for (int index = this.Members.Count - 1; index >= 0; --index)
        {
            Agent agent = this.Members[index];
            HandoffLookup map = [];

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Specify the entry agent when invoking the handoff orchestration.
2. Ensure the chosen entry agent is one of the registered members.

Example fix

// before
handoffOrchestration.InvokeAsync(input); // entryAgent null -> throws

// after
handoffOrchestration.InvokeAsync(input, entryAgent: entryAgentType);

// Always pass the entry agent type when invoking a handoff orchestration
await handoffOrchestration.InvokeAsync(input, entryAgent: entryAgentType);

When it happens

Trigger: Invoking a HandoffOrchestration without specifying the entry agent.

Common situations: Invoking the handoff orchestration via an overload that leaves entryAgent unset; missing entry-agent wiring in the orchestration builder.

Related errors

• The agent {agent.Name ?? agent.Id} cannot have a handoff to
• The following agents are not defined in the orchestration: {
• 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/710e3abcfaed7966. Report an issue: GitHub.