microsoft/autogen · error · ValueError

openai_endpoint is required when embedding_provider is 'azur

Error message

openai_endpoint is required when embedding_provider is 'azure_openai'

What it means

In the vector search factory, embeddings can be delegated to Azure OpenAI (embedding_provider='azure_openai'). That provider needs a deployment endpoint, so the factory raises ValueError when openai_endpoint is missing. This mirrors the config model rule (error 938) at construction time.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/tools/azure/_ai_search.py:979

                # Vector search with OpenAI embeddings
                openai_tool = AzureAISearchTool.create_vector_search(
                    name="openai-vector-search",
                    endpoint="https://your-search.search.windows.net",
                    index_name="<your-index>",
                    credential=AzureKeyCredential("<your-key>"),
                    vector_fields=["content_vector"],
                    embedding_provider="openai",  # Use OpenAI for embeddings
                    embedding_model="text-embedding-ada-002",  # Embedding model to use
                    openai_api_key="<your-openai-key>",  # Your OpenAI API key
                    select_fields=["content", "title", "url"],  # Fields to return in results
                    top=5,
                )

                # Use the tool with an Agent
                # assistant = Agent("assistant", tools=[azure_openai_tool])
        """
        if embedding_provider == "azure_openai" and not openai_endpoint:
            raise ValueError("openai_endpoint is required when embedding_provider is 'azure_openai'")

        config_dict = {
            "name": name,
            "endpoint": endpoint,
            "index_name": index_name,
            "credential": credential,
            "description": description,
            "api_version": api_version or DEFAULT_API_VERSION,
            "query_type": "vector",
            "select_fields": select_fields,
            "vector_fields": vector_fields,
            "top": top,
            "filter": filter,
            "enable_caching": enable_caching,
            "cache_ttl_seconds": cache_ttl_seconds,
            "embedding_provider": embedding_provider,
            "embedding_model": embedding_model,
            "openai_api_key": openai_api_key,

View on GitHub (pinned to 027ecf0a37)

Solutions

Pass openai_endpoint='https://<resource>.openai.azure.com' (the Azure OpenAI resource, not the search service).
Also supply openai_api_key (or token credential) and embedding_model matching a deployed embeddings model; consider openai_api_version if the deployment needs it.
If you meant public OpenAI, use embedding_provider='openai' with openai_api_key only.

Example fix

# before
tool = await AzureAISearchTool.create_vector_search_tool(..., embedding_provider='azure_openai', embedding_model='text-embedding-ada-002', openai_api_key=k)
# after
tool = await AzureAISearchTool.create_vector_search_tool(..., embedding_provider='azure_openai', embedding_model='text-embedding-ada-002', openai_endpoint='https://myres.openai.azure.com', openai_api_key=k)

Defensive patterns

Strategy: validation

Validate before calling

def azure_openai_embedding_ready(embedding_provider: str, openai_endpoint) -> bool:
    if embedding_provider == 'azure_openai':
        return isinstance(openai_endpoint, str) and openai_endpoint.startswith('https://')
    return True

Type guard

def embedding_provider_configured(provider: str, endpoint) -> bool:
    return provider != 'azure_openai' or bool(endpoint)

Prevention

Set AZURE_OPENAI_ENDPOINT and derive openai_endpoint from it in one helper.
Do not confuse the search endpoint with the Azure OpenAI endpoint — validate both start with https:// and differ.
If using public OpenAI, choose embedding_provider='openai'.

When it happens

Trigger: Creating a vector search tool with embedding_provider='azure_openai' but without openai_endpoint (or with None/''), typically while still providing openai_api_key and embedding_model.

Common situations: Copying the 'openai' (public OpenAI) example and just changing embedding_provider to 'azure_openai'; env var for the Azure OpenAI endpoint unset; confusion between the search endpoint and the Azure OpenAI endpoint.

Related errors

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