microsoft/semantic-kernel · 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(string type, string key) constructor validates `key` against KeyRegex (chars 0x20-0x7E, i.e. one or more printable ASCII chars 32-126) and rejects whitespace-only or empty values with ArgumentException. The key is the per-instance identifier of an agent and is used in routing/dictionaries, so it must be non-empty printable ASCII. Note the type is validated separately by AgentType.Validate before the key check.

Source

Thrown at dotnet/src/Agents/Runtime/Abstractions/AgentId.cs:56

    /// </summary>
    public string Key { get; }

    internal static Regex KeyRegex1 => KeyRegex2;

    internal static Regex KeyRegex2 => KeyRegex;

    /// <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)
    {
        AgentType.Validate(type);

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

        this.Type = type;
        this.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>

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Sanitize the key to printable ASCII (strip/replace non-ASCII), or derive it from a stable ASCII source like a GUID or hash.
2. Ensure the key is non-empty and not whitespace-only before constructing the AgentId.
3. Use AgentId.DefaultKey ("default") when you do not need a per-instance key.

Example fix

// before
var id = new AgentId("researcher", userName); // userName may contain accents

// after
var safeKey = Regex.Replace(userName, "[^\x20-\x7E]", "_");
if (string.IsNullOrWhiteSpace(safeKey)) safeKey = AgentId.DefaultKey;
var id = new AgentId("researcher", safeKey);

static readonly Regex AgentKeyRegex = new(@"^[\x20-\x7E]+$", RegexOptions.Compiled);
string SanitizeKey(string key)
{
    key = Regex.Replace(key ?? "", "[^\x20-\x7E]", "_");
    return string.IsNullOrWhiteSpace(key) ? AgentId.DefaultKey : key;
}
var id = new AgentId(type, SanitizeKey(rawKey));

bool IsValidAgentKey(string key) => !string.IsNullOrWhiteSpace(key) && AgentKeyRegex.IsMatch(key);

When it happens

Trigger: Passing a key containing non-ASCII (e.g. localized/unicode), control characters, a key of only spaces, or an empty string; using user input, file paths, or localized strings as the agent key. Note: a GUID with dashes is fine (dash = ASCII 45).

Common situations: Deriving the key from a user display name containing accented characters; empty key from a config value; copy/paste introducing a non-breaking space; using a URL or path as the key.

Related errors

• Invalid AgentId type: '{type}'. Must be alphanumeric (a-z, 0
• Invalid key-value pair format: {inputPair}; expecting "{keyN
• Entry agent is not defined.
• Application is already running.
• Application is already stopped.

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