microsoft/autogen · error · ValueError

Invalid name: {name}. Only letters, numbers, '_' and '-' are

Error message

Invalid name: {name}. Only letters, numbers, '_' and '-' are allowed.

What it means

Raised by assert_valid_name in autogen_ext.models.azure._azure_ai_client when an agent/source name contains characters outside [a-zA-Z0-9_-] (the regex ^[a-zA-Z0-9_-]+$ must fully match). It exists because the Azure AI service rejects such names; assert_valid_name is meant for validating user-supplied configuration, while _normalize_name should be used to munge LLM-generated names.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/models/azure/_azure_ai_client.py:175

def normalize_name(name: str) -> str:
    """
    LLMs sometimes ask functions while ignoring their own format requirements, this function should be used to replace invalid characters with "_".

    Prefer _assert_valid_name for validating user configuration or input
    """
    return re.sub(r"[^a-zA-Z0-9_-]", "_", name)[:64]


def assert_valid_name(name: str) -> str:
    """
    Ensure that configured names are valid, raises ValueError if not.

    For munging LLM responses use _normalize_name to ensure LLM specified names don't break the API.
    """
    if not re.match(r"^[a-zA-Z0-9_-]+$", name):
        raise ValueError(f"Invalid name: {name}. Only letters, numbers, '_' and '-' are allowed.")
    if len(name) > 64:
        raise ValueError(f"Invalid name: {name}. Name must be less than 64 characters.")
    return name


class AzureAIChatCompletionClient(ChatCompletionClient):
    """
    Chat completion client for models hosted on Azure AI Foundry or GitHub Models.
    See `here <https://learn.microsoft.com/en-us/azure/ai-studio/reference/reference-model-inference-chat-completions>`_ for more info.

    Args:
        endpoint (str): The endpoint to use. **Required.**
        credential (union, AzureKeyCredential, AsyncTokenCredential): The credentials to use. **Required**
        model_info (ModelInfo): The model family and capabilities of the model. **Required.**
        model (str): The name of the model. **Required if model is hosted on GitHub Models.**
        frequency_penalty: (optional,float)
        presence_penalty: (optional,float)
        temperature: (optional,float)

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Rename the agent/source to use only letters, digits, underscore and hyphen (e.g. 'helper_agent')
2. If the name comes from an LLM response, pass it through _normalize_name (re.sub(r"[^a-zA-Z0-9_-]", "_", name)[:64]) instead of assert_valid_name
3. Add an early check in your agent factory that validates names against ^[a-zA-Z0-9_-]+$ before any request is sent

Example fix

# before
agent = AssistantAgent("helper agent", ...)  # space is invalid

# after
agent = AssistantAgent("helper_agent", ...)

import re

VALID_NAME = re.compile(r"^[a-zA-Z0-9_-]+$")

def name_ok(name: str) -> bool:
    return bool(VALID_NAME.match(name)) and len(name) <= 64

def is_valid_agent_name(name: str) -> bool:
    import re
    return bool(re.match(r"^[a-zA-Z0-9_-]+$", name)) and len(name) <= 64

When it happens

Trigger: Calling client.create()/create_stream() with a message whose source (or a tool/agent name validated via assert_valid_name) contains spaces, dots, '@', unicode, or is empty. Also triggered by AssistantMessage conversion, which calls assert_valid_name(message.source) first.

Common situations: Human-readable agent names like "helper agent" or "agent@example.com" used as message sources; empty string source; names with leading/trailing whitespace from config files.

Related errors

• Invalid name: {name}. Name must be less than 64 characters.
• BING_API_KEY environment variable is not set
• Please set AZURE_OPENAI_API_KEY environment variable.
• Please set AZURE_OPENAI_ENDPOINT environment variable.
• Please set environment variable AZURE_OPENAI_API_KEY

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