microsoft/autogen · error · ArgumentException

Handoff name '{name}' is not a valid identifier.

Error message

Handoff name '{name}' is not a valid identifier.

What it means

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.

Source

Thrown at dotnet/src/Microsoft.AutoGen/AgentChat/Abstractions/Handoff.cs:20

// Handoff.cs

namespace Microsoft.AutoGen.AgentChat.Abstractions;

/// <summary>
/// Handoff configuration.
/// </summary>
/// <param name="target">The name of the target agent receiving the handoff.</param>
/// <param name="description">The description of the handoff such as the condition under which it should happen and the target
/// agent's ability. If not provided, it is generated from the target agent's name.</param>
/// <param name="name">The name of this handoff configuration. If not provided, it is generated from the target agent's name.</param>
/// <param name="message">The message to the target agent. If not provided, it is generated from the target agent's name.</param>
public class Handoff(string target, string? description = null, string? name = null, string? message = null)
{
    private static string? CheckName(string? name)
    {
        if (name != null && !AgentName.IsValid(name))
        {
            throw new ArgumentException($"Handoff name '{name}' is not a valid identifier.");
        }

        return name;
    }

    /// <summary>
    /// The name of the target agent receiving the handoff.
    /// </summary>
    public AgentName Target { get; } = new AgentName(target);

    /// <summary>
    /// The description of the handoff such as the condition under which it should happen and the target.
    /// </summary>
    public string Description { get; } = description ?? $"Handoff to {target}";

    /// <summary>
    /// The name of this handoff configuration.
    /// </summary>

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Omit the name parameter — it is optional and defaults to a name generated from the target agent's name
2. Use an identifier-safe name: letters, digits, underscore, no leading digit (e.g. 'escalate_to_human')
3. Validate handoff names with AgentName.IsValid before loading workflow definitions

Example fix

// before
var handoff = new Handoff("human_agent", name: "escalate-to-human");
// after
var handoff = new Handoff("human_agent", name: "escalate_to_human");
// or omit: var handoff = new Handoff("human_agent");

if (name != null && !AgentName.IsValid(name))
    throw new ArgumentException($"Handoff name '{name}' must be an identifier (letters/digits/underscore, no leading digit)");
var handoff = new Handoff(target, description, name, message);

static bool IsValidHandoffName(string? name) => name is null || AgentName.IsValid(name);

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Agent name '{name}' is not a valid identifier.
• ImageMessage must have Url or DataUri
• Unsupported content type {item.GetType()}
• Unsupported config type {llmConfig.GetType()}
• Invalid mode

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