microsoft/semantic-kernel · error · ArgumentException

Entry agent is not defined.

Error message

Entry agent is not defined.

What it means

SequentialOrchestration.StartAsync requires a non-null entryAgent because the first agent in the chain must receive the input message. When entryAgent.HasValue is false it throws ArgumentException(nameof(entryAgent)). The entry agent is computed by RegisterOrchestrationAsync, which returns null when there are zero members, so an empty agents array propagates a null entry agent up to StartAsync.

Source

Thrown at dotnet/src/Agents/Orchestration/Sequential/SequentialOrchestration.cs:32

/// and sequentially passes each agent result to the next agent.
/// </summary>
public class SequentialOrchestration<TInput, TOutput> : AgentOrchestration<TInput, TOutput>
{
    /// <summary>
    /// Initializes a new instance of the <see cref="SequentialOrchestration{TInput, TOutput}"/> class.
    /// </summary>
    /// <param name="agents">The agents participating in the orchestration.</param>
    public SequentialOrchestration(params Agent[] agents)
        : base(agents)
    {
    }

    /// <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.AsRequestMessage(), entryAgent.Value).ConfigureAwait(false);
    }

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

        // Each agent handsoff its result to the next agent.
        AgentType nextAgent = outputType;
        for (int index = this.Members.Count - 1; index >= 0; --index)
        {
            Agent agent = this.Members[index];
            nextAgent = await RegisterAgentAsync(agent, index, nextAgent).ConfigureAwait(false);

            logger.LogRegisterActor(this.OrchestrationLabel, nextAgent, "MEMBER", index + 1);
        }

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Ensure at least one Agent is passed to the SequentialOrchestration constructor.
2. Validate the agents collection is non-empty before invoking: `if (agents.Length == 0) throw ...`.
3. If building the list dynamically, guard with a fallback/default agent so the chain always has an entry point.

Example fix

// before
var orch = new SequentialOrchestration<TIn, TOut>(agents.Where(a => a.Enabled).ToArray());

// after
var members = agents.Where(a => a.Enabled).ToArray();
if (members.Length == 0) throw new InvalidOperationException("At least one agent is required.");
var orch = new SequentialOrchestration<TIn, TOut>(members);

Agent[] members = GetAgents();
if (members is null || members.Length == 0)
{
    throw new InvalidOperationException("SequentialOrchestration requires at least one agent.");
}
var orch = new SequentialOrchestration<TIn, TOut>(members);

When it happens

Trigger: Constructing `new SequentialOrchestration(...)` with an empty `params Agent[]` so RegisterOrchestrationAsync's loop never runs and returns null; calling the protected StartAsync directly with `entryAgent: null`; a custom orchestration overriding registration to return null.

Common situations: Dynamically building the agents array from a filter/query that yields nothing; unit tests instantiating the orchestration with no members; config-driven agent lists where none are registered.

Related errors

• Missing agent description: {agent.Name ?? agent.Id}
• Entry agent is not defined.
• 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.

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