{"record":{"id":"d62a266d0643dac8","repo":"microsoft/semantic-kernel","slug":"invalid-agentid-key-key-must-only-contain-as","errorCode":null,"errorMessage":"Invalid AgentId key: '{key}'. Must only contain ASCII characters 32-126.","messagePattern":"Invalid AgentId key: '(.+?)'\\. Must only contain ASCII characters 32-126\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Agents/Runtime/Abstractions/AgentId.cs","lineNumber":56,"sourceCode":"    /// </summary>\n    public string Key { get; }\n\n    internal static Regex KeyRegex1 => KeyRegex2;\n\n    internal static Regex KeyRegex2 => KeyRegex;\n\n    /// <summary>\n    /// Initializes a new instance of the <see cref=\"AgentId\"/> struct.\n    /// </summary>\n    /// <param name=\"type\">The agent type.</param>\n    /// <param name=\"key\">Agent instance identifier.</param>\n    public AgentId(string type, string key)\n    {\n        AgentType.Validate(type);\n\n        if (string.IsNullOrWhiteSpace(key) || !KeyRegex.IsMatch(key))\n        {\n            throw new ArgumentException($\"Invalid AgentId key: '{key}'. Must only contain ASCII characters 32-126.\");\n        }\n\n        this.Type = type;\n        this.Key = key;\n    }\n\n    /// <summary>\n    /// Initializes a new instance of the <see cref=\"AgentId\"/> struct from a tuple.\n    /// </summary>\n    /// <param name=\"kvPair\">A tuple containing the agent type and key.</param>\n    public AgentId((string Type, string Key) kvPair)\n        : this(kvPair.Type, kvPair.Key)\n    {\n    }\n\n    /// <summary>\n    /// Initializes a new instance of the <see cref=\"AgentId\"/> struct from an <see cref=\"AgentType\"/>.\n    /// </summary>","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Agents/Runtime/Abstractions/AgentId.cs#L38-L74","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Sanitize the key to printable ASCII (strip/replace non-ASCII), or derive it from a stable ASCII source like a GUID or hash.","Ensure the key is non-empty and not whitespace-only before constructing the AgentId.","Use AgentId.DefaultKey (\"default\") when you do not need a per-instance key."],"exampleFix":"// before\nvar id = new AgentId(\"researcher\", userName); // userName may contain accents\n\n// after\nvar safeKey = Regex.Replace(userName, \"[^\\x20-\\x7E]\", \"_\");\nif (string.IsNullOrWhiteSpace(safeKey)) safeKey = AgentId.DefaultKey;\nvar id = new AgentId(\"researcher\", safeKey);","handlingStrategy":"validation","validationCode":"static readonly Regex AgentKeyRegex = new(@\"^[\\x20-\\x7E]+$\", RegexOptions.Compiled);\nstring SanitizeKey(string key)\n{\n    key = Regex.Replace(key ?? \"\", \"[^\\x20-\\x7E]\", \"_\");\n    return string.IsNullOrWhiteSpace(key) ? AgentId.DefaultKey : key;\n}\nvar id = new AgentId(type, SanitizeKey(rawKey));","typeGuard":"bool IsValidAgentKey(string key) => !string.IsNullOrWhiteSpace(key) && AgentKeyRegex.IsMatch(key);","tryCatchPattern":null,"preventionTips":["Never use localized/unicode display names as agent keys.","Prefer GUIDs or stable ASCII identifiers for keys.","Sanitize user-derived keys to printable ASCII before constructing an AgentId."],"tags":["agentid","validation","ascii","runtime","dotnet"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}