microsoft/semantic-kernel · 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

AgentType.Validate enforces the regex ^[a-zA-Z_][a-zA-Z0-9_]*$ (must start with a letter or underscore, then only letters/digits/underscores) and rejects null/whitespace. Because AgentType has an implicit conversion from string, this validation fires whenever you assign a string to an AgentType or construct one. It also fires inside AgentId's constructor for the type component.

Source

Thrown at dotnet/src/Agents/Runtime/Abstractions/AgentType.cs:28

/// This is a strongly-typed wrapper around a string, ensuring type safety when working with agent types.
/// </summary>
/// <remarks>
/// This struct is immutable and provides implicit conversion to and from <see cref="string"/>.
/// </remarks>
public readonly partial struct AgentType : IEquatable<AgentType>
{
#if NET
    [GeneratedRegex("^[a-zA-Z_][a-zA-Z0-9_]*$")]
    private static partial Regex TypeRegex();
#else
    private static Regex TypeRegex() => new("^[a-zA-Z_][a-zA-Z0-9_]*$", RegexOptions.Compiled);
#endif

    internal static void Validate(string type)
    {
        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.");
        }
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="AgentId"/> struct.
    /// </summary>
    /// <param name="type">The agent type.</param>
    public AgentType(string type)
    {
        Validate(type);
        this.Name = type;
    }

    /// <summary>
    /// The string representation of this agent type.
    /// </summary>
    public string Name { get; }

View on GitHub (pinned to c028a0c7dc)

Solutions

Use a simple identifier (letters, digits, underscores, leading non-digit) for the agent type.
Sanitize generated names by replacing disallowed characters with underscores and ensuring a letter/underscore prefix.
Derive the type from a safe constant rather than free-form input.

Example fix

// before
AgentType type = "My.Namespace.Agent"; // '.' rejected

// after
AgentType type = "MyNamespaceAgent";

Defensive patterns

Strategy: validation

Validate before calling

static readonly Regex AgentTypeRegex = new(@"^[a-zA-Z_][a-zA-Z0-9_]*$", RegexOptions.Compiled);
bool IsValidAgentType(string type) => !string.IsNullOrWhiteSpace(type) && AgentTypeRegex.IsMatch(type);
string SanitizeType(string type) => Regex.Replace(type ?? "", "[^a-zA-Z0-9_]", "_") is var s && char.IsDigit(s[0]) ? "_" + s : s;

Type guard

bool IsValidAgentType(string type) => !string.IsNullOrWhiteSpace(type) && Regex.IsMatch(type, @"^[a-zA-Z_][a-zA-Z0-9_]*$");

Prevention

Use simple identifiers (letters/digits/underscore, leading non-digit) for agent types.
Do not use namespace-qualified or display names as the type.
Trim and sanitize config-derived type strings.

When it happens

Trigger: Using a type string with spaces, hyphens, dots, or starting with a digit; passing a fully-qualified class name (e.g. "MyNs.MyAgent") as the type; an empty or whitespace type; a type containing slashes.

Common situations: Using a human-friendly display name or namespace-qualified type name as the agent type; reading the type from config with leading/trailing spaces; dynamic generation that yields disallowed characters.

Related errors

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