What causes "Subclasses must implement _get_embedding" in microsoft/autogen?

Implement `async def _get_embedding(self, query: str) -> List[float]` in your subclass returning the embedding for the query using the same model/dimensions as the index's vector field.

microsoft/autogen · error · NotImplementedError

Subclasses must implement _get_embedding

Error message

Subclasses must implement _get_embedding

What it means

_get_embedding is the abstract hook that turns a query string into a vector for vector/hybrid search. Any subclass that supports vector queries must implement it; the base body raises NotImplementedError when called. This is hit when a subclass inherits the base's default body instead of overriding it (or an embedding provider mixin failed to supply it).

Source

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

    @classmethod
    @abstractmethod
    def _from_config(cls, config: AzureAISearchConfig) -> "BaseAzureAISearchTool":
        """Create a tool instance from a configuration object.

        This is an abstract method that must be implemented by subclasses.
        """
        if cls is BaseAzureAISearchTool:
            raise NotImplementedError(
                "BaseAzureAISearchTool is an abstract base class and cannot be instantiated directly. "
                "Use a concrete implementation like AzureAISearchTool."
            )
        raise NotImplementedError("Subclasses must implement _from_config")

    @abstractmethod
    async def _get_embedding(self, query: str) -> List[float]:
        """Generate embedding vector for the query text."""
        raise NotImplementedError("Subclasses must implement _get_embedding")


_allow_private_constructor = ContextVar("_allow_private_constructor", default=False)


class AzureAISearchTool(EmbeddingProviderMixin, BaseAzureAISearchTool):
    """Azure AI Search tool for querying Azure search indexes.

    This tool provides a simplified interface for querying Azure AI Search indexes using
    various search methods. It's recommended to use the factory methods to create
    instances tailored for specific search types:

    1.  **Full-Text Search**: For traditional keyword-based searches, Lucene queries, or
        semantically re-ranked results.
        - Use `AzureAISearchTool.create_full_text_search()`
        - Supports `query_type`: "simple" (keyword), "full" (Lucene), "semantic".

    2.  **Vector Search**: For pure similarity searches based on vector embeddings.

View on GitHub (pinned to 027ecf0a37)

Solutions

Implement `async def _get_embedding(self, query: str) -> List[float]` in your subclass returning the embedding for the query using the same model/dimensions as the index's vector field.
If you intended standard OpenAI/Azure OpenAI embeddings, inherit from EmbeddingProviderMixin (as AzureAISearchTool does) instead of reimplementing.
Add a startup smoke test: await tool._get_embedding('ping') to fail fast on wiring mistakes.

Example fix

# before
class MyTool(BaseAzureAISearchTool):  # no _get_embedding
    ...
# after
class MyTool(BaseAzureAISearchTool):
    async def _get_embedding(self, query: str) -> List[float]:
        return await self._embedder.embed(query)  # must match index vector dimensions

Defensive patterns

Strategy: type-guard

Validate before calling

import inspect

def embedding_hook_ready(cls) -> bool:
    return '_get_embedding' in cls.__dict__ or any(
        '_get_embedding' in vars(c) for c in cls.__mro__ if c not in (object,)
    )

Type guard

def can_embed(tool) -> bool:
    import inspect
    cls = type(tool)
    for c in cls.__mro__:
        if '_get_embedding' in vars(c) and vars(c)['_get_embedding'] is not getattr(__import__('autogen_ext.tools.azure._ai_search', fromlist=['BaseAzureAISearchTool']).BaseAzureAISearchTool, '_get_embedding', None):
            return True
    return False

Try / catch

try:
    vec = await tool._get_embedding('ping')
except NotImplementedError:
    raise TypeError(f'{type(tool).__name__} cannot vector-search: implement _get_embedding')

Prevention

Smoke-test `await tool._get_embedding('ping')` at startup for any vector/hybrid tool.
Ensure your subclass MRO includes an embedding provider (e.g. EmbeddingProviderMixin) or your own implementation.
Match embedding model dimensions to the index vector field dimensions to avoid the next failure downstream.

When it happens

Trigger: Running a vector or hybrid search with a custom subclass that does not override _get_embedding; calling tool._get_embedding('query') on such a class; constructing a vector tool from a class whose MRO does not include EmbeddingProviderMixin.

Common situations: Writing a custom embedding backend (local model, non-OpenAI provider) and forgetting to wire in the embedding method before testing search; subclass composition where the mixin providing _get_embedding was omitted from the bases.

Related errors

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