microsoft/semantic-kernel · error · ArgumentException

Missing agent description: {agent.Name ?? agent.Id}

Error message

Missing agent description: {agent.Name ?? agent.Id}

What it means

Thrown by AgentActor.VerifyDescription when agent.Description is null. Orchestration actors embed each agent's description in prompts (e.g. so a group-chat manager can decide who speaks next), so a missing description makes the orchestration unable to function and is rejected up front with ArgumentException.

Source

Thrown at dotnet/src/Agents/Orchestration/AgentActor.cs:184

            lastStreamedResponse = streamedResponse.Message;
        }

        await HandleStreamedMessage(lastStreamedResponse, isFinal: true).ConfigureAwait(false);

        async ValueTask HandleStreamedMessage(StreamingChatMessageContent? streamedResponse, bool isFinal)
        {
            if (this.Context.StreamingResponseCallback != null && streamedResponse != null)
            {
                await this.Context.StreamingResponseCallback.Invoke(streamedResponse, isFinal).ConfigureAwait(false);
            }
        }
    }

    private AgentInvokeOptions GetInvokeOptions(Func<ChatMessageContent, Task> messageHandler) => this._options ??= this.CreateInvokeOptions(messageHandler);

    private static string VerifyDescription(Agent agent)
    {
        return agent.Description ?? throw new ArgumentException($"Missing agent description: {agent.Name ?? agent.Id}", nameof(agent));
    }
}

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set a meaningful Description on every agent passed into an orchestration.
2. Add a build-time/factory assertion that Description is non-null before registering agents.

Example fix

// before
var agent = new OpenAIAssistantAgent(client, id: "writer") { Name = "writer" /* no Description */ };
new GroupChatOrchestration(agent, manager).InvokeAsync(...); // throws

// after
var agent = new OpenAIAssistantAgent(client, id: "writer")
{
    Name = "writer",
    Description = "Drafts clear, concise prose."
};

foreach (var agent in agents)
{
    if (string.IsNullOrWhiteSpace(agent.Description))
        throw new InvalidOperationException($"Agent '{agent.Name ?? agent.Id}' needs a Description for orchestration.");
}

static bool HasOrchestrationDescription(Agent agent) => !string.IsNullOrWhiteSpace(agent.Description);

When it happens

Trigger: Constructing/invoking any orchestration (GroupChat, Handoff, Sequential, etc.) that uses AgentActor with an Agent whose Description was never set.

Common situations: Creating agents with only Name/Id and instructions but forgetting Description; reusing a minimal agent factory in orchestration code.

Related errors

• 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.
• Orchestration did not complete within the allowed duration (

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