microsoft/autogen · error · ArgumentException

Invalid AgentId key: '{key}'. Must only contain ASCII charac

Error message

Invalid AgentId key: '{key}'. Must only contain ASCII characters 32-126.

What it means

The AgentId constructor throws ArgumentException when the agent key is null/whitespace or fails KeyRegex. Per the message, the key must consist only of printable ASCII characters 32-126 — i.e. no control characters, no non-ASCII (Unicode) characters, no spaces-only string.

Source

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

    /// 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)
    {
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="AgentId"/> struct from an <see cref="AgentType"/>.
    /// </summary>
    /// <param name="type">The agent type.</param>

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Sanitize keys to printable ASCII (strip/replace chars < 32 or > 126) before constructing AgentId.
2. Prefer opaque ASCII identifiers (GUIDs, base64url hashes) for keys derived from user data.
3. Add a startup validation pass over any configuration-supplied keys.

Example fix

// before
var id = new AgentId("weather_agent", "user-名前\n"); // throws: non-ASCII + control char

// after
var safeKey = new string("user-12345".Where(c => c >= ' ' && c <= '~').ToArray());
var id = new AgentId("weather_agent", safeKey);

static bool IsValidAgentKey(string? key) =>
    !string.IsNullOrWhiteSpace(key) && key.All(c => c >= (char)32 && c <= (char)126);

static bool IsValidAgentKey(string? key) =>
    !string.IsNullOrWhiteSpace(key) && key.All(c => c >= ' ' && c <= '~');

When it happens

Trigger: new AgentId(type, key) where the key contains control chars, tabs/newlines, or non-ASCII characters (e.g. keys derived from user IDs, emails, or GUIDs with decorations), or is empty/whitespace.

Common situations: Using raw user-provided identifiers (usernames with accents, emoji, emails) as agent keys; embedding newlines from copy-pasted config; keys built by string interpolation that include whitespace; multi-tenant keys assembled from separators not in ASCII 32-126 is fine but watch for invisible characters.

Related errors

• Invalid AgentId type: '{type}'. Must be alphanumeric (a-z, 0
• Invalid agent type: {type}. Allowed values MUST match the re
• Invalid agent id: {agent_id}
• Failed to list MCP prompts
• Failed to get MCP prompt

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