microsoft/autogen · error · ArgumentException

Invalid AgentId type: '{type}'. Must be alphanumeric (a-z, 0

Error message

Invalid AgentId type: '{type}'. Must be alphanumeric (a-z, 0-9, _) and cannot start with a number or contain spaces.

What it means

The AgentId constructor throws ArgumentException when the agent type string is null/whitespace or fails TypeRegex. Per the message, type must be alphanumeric lowercase (a-z, 0-9, _), cannot start with a digit, and must contain no spaces. This is contract-level validation performed on every AgentId construction.

Source

Thrown at dotnet/src/Microsoft.AutoGen/Contracts/AgentId.cs:44

    /// </summary>
    public string Type;

    /// <summary>
    /// Agent instance identifier.
    /// Strings may only be composed of alphanumeric letters (a-z) and (0-9), or underscores (_).
    /// </summary>
    public string Key;

    /// <summary>
    /// Initializes a new instance of the <see cref="AgentId"/> struct.
    /// </summary>
    /// <param name="type">The agent type.</param>
    /// <param name="key">Agent instance identifier.</param>
    public AgentId(string type, string key)
    {
        if (string.IsNullOrWhiteSpace(type) || !TypeRegex.IsMatch(type))
        {
            throw new ArgumentException($"Invalid AgentId type: '{type}'. Must be alphanumeric (a-z, 0-9, _) and cannot start with a number or contain spaces.");
        }

        if (string.IsNullOrWhiteSpace(key) || !KeyRegex.IsMatch(key))
        {
            throw new ArgumentException($"Invalid AgentId key: '{key}'. Must only contain ASCII characters 32-126.");
        }

        Type = type;
        Key = key;
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="AgentId"/> struct from a tuple.
    /// </summary>
    /// <param name="kvPair">A tuple containing the agent type and key.</param>
    public AgentId((string Type, string Key) kvPair) : this(kvPair.Type, kvPair.Key)
    {
    }

View on GitHub (pinned to 027ecf0a37)

Solutions

Normalize the type before construction: lowercase, replace invalid chars with '_', prefix a letter if it starts with a digit.
Use the same regex the library uses (^[a-z_][a-z0-9_]*$ shape) to validate names at startup/configuration load, not at AgentId construction.
If the name comes from configuration, fix it there so logs and AgentIds stay readable.

Example fix

// before
var id = new AgentId("Weather Agent", "default"); // throws: space + uppercase

// after
var id = new AgentId("weather_agent", "default");

Defensive patterns

Strategy: validation

Validate before calling

using System.Text.RegularExpressions;
static readonly Regex TypeRx = new("^[a-z_][a-z0-9_]*$", RegexOptions.Compiled);
bool IsValidAgentType(string? type) =>
    !string.IsNullOrWhiteSpace(type) && TypeRx.IsMatch(type);

Type guard

static bool IsValidAgentType(string? type) =>
    !string.IsNullOrWhiteSpace(type) && Regex.IsMatch(type, "^[a-z_][a-z0-9_]*$");

Try / catch

try { var id = new AgentId(type, key); }
catch (ArgumentException) { type = Sanitize(type); var id = new AgentId(type, key); }

Prevention

Validate agent type strings at configuration load time, not at AgentId construction.
Derive agent types from a fixed allow-list of snake_case names.

When it happens

Trigger: new AgentId(type, key) where type contains uppercase letters, hyphens, spaces, starts with a digit, or is empty/whitespace. Also reached via the (Type, Key) tuple constructor and any API that builds AgentIds from user/config-supplied strings (e.g. agent names from appsettings or environment variables).

Common situations: Using display names like "Weather Agent" or "agent-1" as agent types; deriving agent type from a class name with dots or capitals ("MyNamespace.MyAgent"); config-driven agent names from YAML/env that were never sanitized; version upgrades that tightened the regex.

Related errors

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