microsoft/semantic-kernel · error · ArgumentException

Entry agent is not defined.

Error message

Entry agent is not defined.

What it means

Thrown by GroupChatOrchestration.StartAsync when entryAgent.HasValue is false. GroupChat requires a designated entry agent to receive the first input task message; the framework passes entryAgent from the invoke call, and if none is supplied the orchestration cannot route the initial message and fails fast.

Source

Thrown at dotnet/src/Agents/Orchestration/GroupChat/GroupChatOrchestration.cs:40

    /// <summary>
    /// Initializes a new instance of the <see cref="GroupChatOrchestration{TInput, TOutput}"/> class.
    /// </summary>
    /// <param name="manager">The manages the flow of the group-chat.</param>
    /// <param name="agents">The agents participating in the orchestration.</param>
    public GroupChatOrchestration(GroupChatManager manager, params Agent[] agents)
        : base(agents)
    {
        Verify.NotNull(manager, nameof(manager));

        this._manager = manager;
    }

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

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

        int agentCount = 0;
        GroupChatTeam team = [];
        foreach (Agent agent in this.Members)
        {
            ++agentCount;
            AgentType agentType = await RegisterAgentAsync(agent, agentCount).ConfigureAwait(false);
            string name = agent.Name ?? agent.Id ?? agentType;
            string? description = agent.Description;

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Specify the entry agent when invoking the group chat.
2. Use the orchestration API that lets you declare the entry agent, and make sure one of the registered members is chosen.

Example fix

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

// after — declare the entry agent member
orchestration.InvokeAsync(input, entryAgent: agentType);

// Always pass the entry agent type when invoking a group chat
await groupChatOrchestration.InvokeAsync(input, entryAgent: entryAgentType);

When it happens

Trigger: Invoking a GroupChatOrchestration without specifying the entry agent (the orchestration invoke overload that leaves entryAgent null).

Common situations: Calling the orchestration's invoke without chaining .WithEntryAgent(...) / without the entry-agent parameter; misconfigured orchestration builder.

Related errors

• Missing agent description: {agent.Name ?? agent.Id}
• The agent {agent.Name ?? agent.Id} cannot have a handoff to
• The following agents are not defined in the orchestration: {
• Entry agent is not defined.
• Orchestration did not complete within the allowed duration (

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