{"record":{"id":"7901ba75b78a5d6d","repo":"microsoft/autogen","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/Microsoft.AutoGen/Contracts/AgentId.cs","lineNumber":49,"sourceCode":"    /// Strings may only be composed of alphanumeric letters (a-z) and (0-9), or underscores (_).\n    /// </summary>\n    public string Key;\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        if (string.IsNullOrWhiteSpace(type) || !TypeRegex.IsMatch(type))\n        {\n            throw new ArgumentException($\"Invalid AgentId type: '{type}'. Must be alphanumeric (a-z, 0-9, _) and cannot start with a number or contain spaces.\");\n        }\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        Type = type;\n        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) : 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>\n    /// <param name=\"type\">The agent type.</param>","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/dotnet/src/Microsoft.AutoGen/Contracts/AgentId.cs#L31-L67","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Sanitize keys to printable ASCII (strip/replace chars < 32 or > 126) before constructing AgentId.","Prefer opaque ASCII identifiers (GUIDs, base64url hashes) for keys derived from user data.","Add a startup validation pass over any configuration-supplied keys."],"exampleFix":"// before\nvar id = new AgentId(\"weather_agent\", \"user-名前\\n\"); // throws: non-ASCII + control char\n\n// after\nvar safeKey = new string(\"user-12345\".Where(c => c >= ' ' && c <= '~').ToArray());\nvar id = new AgentId(\"weather_agent\", safeKey);","handlingStrategy":"validation","validationCode":"static bool IsValidAgentKey(string? key) =>\n    !string.IsNullOrWhiteSpace(key) && key.All(c => c >= (char)32 && c <= (char)126);","typeGuard":"static bool IsValidAgentKey(string? key) =>\n    !string.IsNullOrWhiteSpace(key) && key.All(c => c >= ' ' && c <= '~');","tryCatchPattern":null,"preventionTips":["Map external/user-derived identifiers to opaque ASCII keys (GUID, hash) before use.","Trim and filter invisible characters from config-supplied keys at startup."],"tags":["validation","agent-id","contracts","ascii"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}