microsoft/autogen · error · ArgumentException

Agent name '{name}' is not a valid identifier.

Error message

Agent name '{name}' is not a valid identifier.

What it means

Thrown by AgentName's constructor via AgentName.CheckValid. Agent and team names must be valid Python-style identifiers (regex ^[IdStart][IdContinue]*$ over Unicode letter/underscore start and word-char continue classes) to keep parity with the Python AutoGen runtime. Names containing spaces, hyphens, dots, leading digits, or other punctuation are rejected.

Source

Thrown at dotnet/src/Microsoft.AutoGen/AgentChat/Abstractions/ChatAgent.cs:109

    private static readonly Regex AgentNameRegex = new Regex($"^{IdStartClass}{IdContinueClass}*$", RegexOptions.Compiled | RegexOptions.Singleline);

    public string Value { get; }

    public AgentName(string name)
    {
        AgentName.CheckValid(name);

        this.Value = name;
    }

    public static bool IsValid(string name) => AgentNameRegex.IsMatch(name);

    public static void CheckValid(string name)
    {
        if (!AgentName.IsValid(name))
        {
            throw new ArgumentException($"Agent name '{name}' is not a valid identifier.");
        }
    }

    // Implicit cast to string
    public static implicit operator string(AgentName agentName) => agentName.Value;
}

/// <summary>
/// A response from calling <see cref="IChatAgent"/>'s <see cref="IHandleChat{TIn, Response}.HandleAsync(TIn)"/>."/>
/// </summary>
public class Response
{
    /// <summary>
    /// A chat message produced by the agent as a response.
    /// </summary>
    public required ChatMessage Message { get; set; }

    /// <summary>

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Use identifier-safe names: letters/digits/underscore, not starting with a digit (e.g. 'writer_agent' not 'writer-agent')
2. Sanitize names before construction: replace non-word characters with underscores and strip leading digits
3. Validate early with AgentName.IsValid(name) and surface a friendly error before building the team

Example fix

// before
var agent = new SomeChatAgent(name: "primary-agent");
// after
static string Sanitize(string n) { var s = Regex.Replace(n, @"\W", "_"); return char.IsDigit(s[0]) ? "_" + s : s; }
var agent = new SomeChatAgent(name: Sanitize("primary-agent")); // primary_agent

if (!AgentName.IsValid(name))
    name = Regex.Replace(name, @"\W", "_").TrimStart('0','1','2','3','4','5','6','7','8','9');
if (!AgentName.IsValid(name)) throw new ArgumentException($"'{name}' cannot be made a valid agent name");

static bool IsValidAgentName(string name) => AgentName.IsValid(name); // letters/digits/underscore, no leading digit, no spaces/hyphens

catch (ArgumentException ex) when (ex.Message.Contains("not a valid identifier")) { throw new ArgumentException("Agent names must be Python-style identifiers (letters, digits, underscore; no leading digit)", ex); }

When it happens

Trigger: Constructing any Microsoft.AutoGen.AgentChat type that takes an agent name (ChatAgent name, AgentName) with strings like "primary-agent", "Writer Agent", "1st_agent", or names derived from unvalidated user/environment input.

Common situations: Deriving agent names from display names, file names, or LLM-generated labels that contain hyphens/spaces; interop with systems that allow arbitrary name strings; multi-agent teams where names come from a config file without the identifier restriction documented.

Related errors

• Handoff name '{name}' is not a valid identifier.
• ImageMessage must have Url or DataUri
• Unsupported content type {item.GetType()}
• Unsupported config type {llmConfig.GetType()}
• Invalid mode

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/84ff82fa086d9812. Report an issue: GitHub.