{"record":{"id":"75ea1c78cfd3c76d","repo":"microsoft/autogen","slug":"handoff-name-name-is-not-a-valid-identifier","errorCode":null,"errorMessage":"Handoff name '{name}' is not a valid identifier.","messagePattern":"Handoff name '(.+?)' is not a valid identifier\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Microsoft.AutoGen/AgentChat/Abstractions/Handoff.cs","lineNumber":20,"sourceCode":"// Handoff.cs\n\nnamespace Microsoft.AutoGen.AgentChat.Abstractions;\n\n/// <summary>\n/// Handoff configuration.\n/// </summary>\n/// <param name=\"target\">The name of the target agent receiving the handoff.</param>\n/// <param name=\"description\">The description of the handoff such as the condition under which it should happen and the target\n/// agent's ability. If not provided, it is generated from the target agent's name.</param>\n/// <param name=\"name\">The name of this handoff configuration. If not provided, it is generated from the target agent's name.</param>\n/// <param name=\"message\">The message to the target agent. If not provided, it is generated from the target agent's name.</param>\npublic class Handoff(string target, string? description = null, string? name = null, string? message = null)\n{\n    private static string? CheckName(string? name)\n    {\n        if (name != null && !AgentName.IsValid(name))\n        {\n            throw new ArgumentException($\"Handoff name '{name}' is not a valid identifier.\");\n        }\n\n        return name;\n    }\n\n    /// <summary>\n    /// The name of the target agent receiving the handoff.\n    /// </summary>\n    public AgentName Target { get; } = new AgentName(target);\n\n    /// <summary>\n    /// The description of the handoff such as the condition under which it should happen and the target.\n    /// </summary>\n    public string Description { get; } = description ?? $\"Handoff to {target}\";\n\n    /// <summary>\n    /// The name of this handoff configuration.\n    /// </summary>","sourceCodeStart":2,"sourceCodeEnd":38,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/dotnet/src/Microsoft.AutoGen/AgentChat/Abstractions/Handoff.cs#L2-L38","documentation":"Same identifier rule as AgentName, applied to the optional 'name' of a Handoff configuration. Handoff.CheckName runs when a Handoff is created; if an explicit name is supplied and fails AgentName.IsValid (Python-identifier regex), it throws ArgumentException. Note the target is validated too (via new AgentName(target)), but this specific message is only for the handoff's own name.","triggerScenarios":"Creating a Handoff(target, description, name: \"escalate-to-human\") or any name containing spaces/hyphens/punctuation or starting with a digit, while target itself is valid.","commonSituations":"Auto-generating handoff names from templates like \"{target}-handoff\" or from prose descriptions; hand-editing handoff names in config with friendly labels; porting workflow definitions from systems without identifier restrictions.","solutions":["Omit the name parameter — it is optional and defaults to a name generated from the target agent's name","Use an identifier-safe name: letters, digits, underscore, no leading digit (e.g. 'escalate_to_human')","Validate handoff names with AgentName.IsValid before loading workflow definitions"],"exampleFix":"// before\nvar handoff = new Handoff(\"human_agent\", name: \"escalate-to-human\");\n// after\nvar handoff = new Handoff(\"human_agent\", name: \"escalate_to_human\");\n// or omit: var handoff = new Handoff(\"human_agent\");","handlingStrategy":"validation","validationCode":"if (name != null && !AgentName.IsValid(name))\n    throw new ArgumentException($\"Handoff name '{name}' must be an identifier (letters/digits/underscore, no leading digit)\");\nvar handoff = new Handoff(target, description, name, message);","typeGuard":"static bool IsValidHandoffName(string? name) => name is null || AgentName.IsValid(name);","tryCatchPattern":null,"preventionTips":["Prefer omitting the handoff name so it is generated from the target","Apply the same identifier sanitization used for agent names to any generated handoff names","Validate handoff definitions in a startup check for the whole team"],"tags":["autogen","handoff","identifier","validation","csharp"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}