autogen_ext.tools.azure#

pydantic model AzureAISearchConfig[source]#

Bases: BaseModel

Configuration for Azure AI Search with validation.

This class defines the configuration parameters for Azure AI Search tools, including authentication, search behavior, caching, and embedding settings.

Note

This class requires the azure extra for the autogen-ext package.

pip install -U "autogen-ext[azure]"

Note

Prerequisites:

  1. An Azure AI Search service must be created in your Azure subscription.

  2. The search index must be properly configured for your use case:

    • For vector search: Index must have vector fields

    • For semantic search: Index must have semantic configuration

    • For hybrid search: Both vector fields and text fields must be configured

  3. Required packages:

    • Base functionality: azure-search-documents>=11.4.0

    • For Azure OpenAI embeddings: openai azure-identity

    • For OpenAI embeddings: openai

Example Usage:
from azure.core.credentials import AzureKeyCredential
from autogen_ext.tools.azure import AzureAISearchConfig

# Basic configuration for full-text search
config = AzureAISearchConfig(
    name="doc-search",
    endpoint="https://your-search.search.windows.net",  # Your Azure AI Search endpoint
    index_name="<your-index>",  # Name of your search index
    credential=AzureKeyCredential("<your-key>"),  # Your Azure AI Search admin key
    query_type="simple",
    search_fields=["content", "title"],  # Update with your searchable fields
    top=5,
)

# Configuration for vector search with Azure OpenAI embeddings
vector_config = AzureAISearchConfig(
    name="vector-search",
    endpoint="https://your-search.search.windows.net",
    index_name="<your-index>",
    credential=AzureKeyCredential("<your-key>"),
    query_type="vector",
    vector_fields=["embedding"],  # Update with your vector field name
    embedding_provider="azure_openai",
    embedding_model="text-embedding-ada-002",
    openai_endpoint="https://your-openai.openai.azure.com",  # Your Azure OpenAI endpoint
    openai_api_key="<your-openai-key>",  # Your Azure OpenAI key
    top=5,
)

# Configuration for hybrid search with semantic ranking
hybrid_config = AzureAISearchConfig(
    name="hybrid-search",
    endpoint="https://your-search.search.windows.net",
    index_name="<your-index>",
    credential=AzureKeyCredential("<your-key>"),
    query_type="semantic",
    semantic_config_name="<your-semantic-config>",  # Name of your semantic configuration
    search_fields=["content", "title"],  # Update with your search fields
    vector_fields=["embedding"],  # Update with your vector field name
    embedding_provider="openai",
    embedding_model="text-embedding-ada-002",
    openai_api_key="<your-openai-key>",  # Your OpenAI API key
    top=5,
)

Show JSON schema
{
   "title": "AzureAISearchConfig",
   "description": "Configuration for Azure AI Search with validation.\n\nThis class defines the configuration parameters for Azure AI Search tools, including\nauthentication, search behavior, caching, and embedding settings.\n\n.. note::\n    This class requires the ``azure`` extra for the ``autogen-ext`` package.\n\n    .. code-block:: bash\n\n        pip install -U \"autogen-ext[azure]\"\n\n.. note::\n    **Prerequisites:**\n\n    1. An Azure AI Search service must be created in your Azure subscription.\n    2. The search index must be properly configured for your use case:\n\n       - For vector search: Index must have vector fields\n       - For semantic search: Index must have semantic configuration\n       - For hybrid search: Both vector fields and text fields must be configured\n    3. Required packages:\n\n       - Base functionality: ``azure-search-documents>=11.4.0``\n       - For Azure OpenAI embeddings: ``openai azure-identity``\n       - For OpenAI embeddings: ``openai``\n\nExample Usage:\n    .. code-block:: python\n\n        from azure.core.credentials import AzureKeyCredential\n        from autogen_ext.tools.azure import AzureAISearchConfig\n\n        # Basic configuration for full-text search\n        config = AzureAISearchConfig(\n            name=\"doc-search\",\n            endpoint=\"https://your-search.search.windows.net\",  # Your Azure AI Search endpoint\n            index_name=\"<your-index>\",  # Name of your search index\n            credential=AzureKeyCredential(\"<your-key>\"),  # Your Azure AI Search admin key\n            query_type=\"simple\",\n            search_fields=[\"content\", \"title\"],  # Update with your searchable fields\n            top=5,\n        )\n\n        # Configuration for vector search with Azure OpenAI embeddings\n        vector_config = AzureAISearchConfig(\n            name=\"vector-search\",\n            endpoint=\"https://your-search.search.windows.net\",\n            index_name=\"<your-index>\",\n            credential=AzureKeyCredential(\"<your-key>\"),\n            query_type=\"vector\",\n            vector_fields=[\"embedding\"],  # Update with your vector field name\n            embedding_provider=\"azure_openai\",\n            embedding_model=\"text-embedding-ada-002\",\n            openai_endpoint=\"https://your-openai.openai.azure.com\",  # Your Azure OpenAI endpoint\n            openai_api_key=\"<your-openai-key>\",  # Your Azure OpenAI key\n            top=5,\n        )\n\n        # Configuration for hybrid search with semantic ranking\n        hybrid_config = AzureAISearchConfig(\n            name=\"hybrid-search\",\n            endpoint=\"https://your-search.search.windows.net\",\n            index_name=\"<your-index>\",\n            credential=AzureKeyCredential(\"<your-key>\"),\n            query_type=\"semantic\",\n            semantic_config_name=\"<your-semantic-config>\",  # Name of your semantic configuration\n            search_fields=[\"content\", \"title\"],  # Update with your search fields\n            vector_fields=[\"embedding\"],  # Update with your vector field name\n            embedding_provider=\"openai\",\n            embedding_model=\"text-embedding-ada-002\",\n            openai_api_key=\"<your-openai-key>\",  # Your OpenAI API key\n            top=5,\n        )",
   "type": "object",
   "properties": {
      "name": {
         "description": "The name of this tool instance",
         "title": "Name",
         "type": "string"
      },
      "description": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Description explaining the tool's purpose",
         "title": "Description"
      },
      "endpoint": {
         "description": "The full URL of your Azure AI Search service",
         "title": "Endpoint",
         "type": "string"
      },
      "index_name": {
         "description": "Name of the search index to query",
         "title": "Index Name",
         "type": "string"
      },
      "credential": {
         "anyOf": [],
         "description": "Azure credential for authentication (API key or token)",
         "title": "Credential"
      },
      "api_version": {
         "default": "2023-10-01-preview",
         "description": "Azure AI Search API version to use. Defaults to 2023-10-01-preview.",
         "title": "Api Version",
         "type": "string"
      },
      "query_type": {
         "default": "simple",
         "description": "Type of search to perform: simple, full, semantic, or vector",
         "enum": [
            "simple",
            "full",
            "semantic",
            "vector"
         ],
         "title": "Query Type",
         "type": "string"
      },
      "search_fields": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Fields to search within documents",
         "title": "Search Fields"
      },
      "select_fields": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Fields to return in search results",
         "title": "Select Fields"
      },
      "vector_fields": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Fields to use for vector search",
         "title": "Vector Fields"
      },
      "top": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Maximum number of results to return. For vector searches, acts as k in k-NN.",
         "title": "Top"
      },
      "filter": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "OData filter expression to refine search results",
         "title": "Filter"
      },
      "semantic_config_name": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Semantic configuration name for enhanced results",
         "title": "Semantic Config Name"
      },
      "enable_caching": {
         "default": false,
         "description": "Whether to cache search results",
         "title": "Enable Caching",
         "type": "boolean"
      },
      "cache_ttl_seconds": {
         "default": 300,
         "description": "How long to cache results in seconds",
         "title": "Cache Ttl Seconds",
         "type": "integer"
      },
      "embedding_provider": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Name of embedding provider for client-side embeddings",
         "title": "Embedding Provider"
      },
      "embedding_model": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Model name for client-side embeddings",
         "title": "Embedding Model"
      },
      "openai_api_key": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "API key for OpenAI/Azure OpenAI embeddings",
         "title": "Openai Api Key"
      },
      "openai_api_version": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "API version for Azure OpenAI embeddings",
         "title": "Openai Api Version"
      },
      "openai_endpoint": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Endpoint URL for Azure OpenAI embeddings",
         "title": "Openai Endpoint"
      }
   },
   "required": [
      "name",
      "endpoint",
      "index_name",
      "credential"
   ]
}

Fields:

  • api_version (str)

  • cache_ttl_seconds (int)

  • credential (azure.core.credentials.AzureKeyCredential | azure.core.credentials_async.AsyncTokenCredential)

  • description (str | None)

  • embedding_model (str | None)

  • embedding_provider (str | None)

  • enable_caching (bool)

  • endpoint (str)

  • filter (str | None)

  • index_name (str)

  • name (str)

  • openai_api_key (str | None)

  • openai_api_version (str | None)

  • openai_endpoint (str | None)

  • query_type (Literal['simple', 'full', 'semantic', 'vector'])

  • search_fields (List[str] | None)

  • select_fields (List[str] | None)

  • semantic_config_name (str | None)

  • top (int | None)

  • vector_fields (List[str] | None)

Validators:

  • normalize_query_type » query_type

  • validate_endpoint » endpoint

  • validate_interdependent_fields » all fields

  • validate_top » top

field api_version: str = '2023-10-01-preview'#

Azure AI Search API version to use. Defaults to 2023-10-01-preview.

Validated by:

  • validate_interdependent_fields

field cache_ttl_seconds: int = 300#

How long to cache results in seconds

Validated by:

  • validate_interdependent_fields

field credential: AzureKeyCredential | AsyncTokenCredential [Required]#

Azure credential for authentication (API key or token)

Validated by:

  • validate_interdependent_fields

field description: str | None = None#

Description explaining the tool’s purpose

Validated by:

  • validate_interdependent_fields

field embedding_model: str | None = None#

Model name for client-side embeddings

Validated by:

  • validate_interdependent_fields

field embedding_provider: str | None = None#

Name of embedding provider for client-side embeddings

Validated by:

  • validate_interdependent_fields

field enable_caching: bool = False#

Whether to cache search results

Validated by:

  • validate_interdependent_fields

field endpoint: str [Required]#

The full URL of your Azure AI Search service

Validated by:

  • validate_endpoint

  • validate_interdependent_fields

field filter: str | None = None#

OData filter expression to refine search results

Validated by:

  • validate_interdependent_fields

field index_name: str [Required]#

Name of the search index to query

Validated by:

  • validate_interdependent_fields

field name: str [Required]#

The name of this tool instance

Validated by:

  • validate_interdependent_fields

field openai_api_key: str | None = None#

API key for OpenAI/Azure OpenAI embeddings

Validated by:

  • validate_interdependent_fields

field openai_api_version: str | None = None#

API version for Azure OpenAI embeddings

Validated by:

  • validate_interdependent_fields

field openai_endpoint: str | None = None#

Endpoint URL for Azure OpenAI embeddings

Validated by:

  • validate_interdependent_fields

field query_type: Literal['simple', 'full', 'semantic', 'vector'] = 'simple'#

Type of search to perform: simple, full, semantic, or vector

Validated by:

  • normalize_query_type

  • validate_interdependent_fields

field search_fields: List[str] | None = None#

Fields to search within documents

Validated by:

  • validate_interdependent_fields

field select_fields: List[str] | None = None#

Fields to return in search results

Validated by:

  • validate_interdependent_fields

field semantic_config_name: str | None = None#

Semantic configuration name for enhanced results

Validated by:

  • validate_interdependent_fields

field top: int | None = None#

Maximum number of results to return. For vector searches, acts as k in k-NN.

Validated by:

  • validate_interdependent_fields

  • validate_top

field vector_fields: List[str] | None = None#

Fields to use for vector search

Validated by:

  • validate_interdependent_fields

validator normalize_query_type  »  query_type[source]#

Normalize query type to standard values.

validator validate_endpoint  »  endpoint[source]#

Validate that the endpoint is a valid URL.

validator validate_interdependent_fields  »  all fields[source]#

Validate interdependent fields after all fields have been parsed.

validator validate_top  »  top[source]#

Ensure top is a positive integer if provided.

class AzureAISearchTool(name: str, endpoint: str, index_name: str, credential: AzureKeyCredential | AsyncTokenCredential | Dict[str, str], description: str | None = None, api_version: str = DEFAULT_API_VERSION, query_type: Literal['simple', 'full', 'semantic', 'vector'] = 'simple', search_fields: List[str] | None = None, select_fields: List[str] | None = None, vector_fields: List[str] | None = None, top: int | None = None, filter: str | None = None, semantic_config_name: str | None = None, enable_caching: bool = False, cache_ttl_seconds: int = 300, embedding_provider: str | None = None, embedding_model: str | None = None, openai_api_key: str | None = None, openai_api_version: str | None = None, openai_endpoint: str | None = None)[source]#

Bases: 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. - Use AzureAISearchTool.create_vector_search()

  3. Hybrid Search: For combining vector search with full-text or semantic search to get the benefits of both. - Use AzureAISearchTool.create_hybrid_search() - The text component can be “simple”, “full”, or “semantic” via the query_type parameter.

Each factory method configures the tool with appropriate defaults and validations for the chosen search strategy.

Warning

If you set query_type=”semantic”, you must also provide a valid semantic_config_name. This configuration must be set up in your Azure AI Search index beforehand.

component_provider_override: ClassVar[str | None] = 'autogen_ext.tools.azure.AzureAISearchTool'#

Override the provider string for the component. This should be used to prevent internal module names being a part of the module name.

classmethod create_full_text_search(name: str, endpoint: str, index_name: str, credential: AzureKeyCredential | AsyncTokenCredential | Dict[str, str], description: str | None = None, api_version: str | None = None, query_type: Literal['simple', 'full', 'semantic'] = 'simple', search_fields: List[str] | None = None, select_fields: List[str] | None = None, top: int | None = 5, filter: str | None = None, semantic_config_name: str | None = None, enable_caching: bool = False, cache_ttl_seconds: int = 300) → AzureAISearchTool[source]#

Create a tool for traditional text-based searches.

This factory method creates an AzureAISearchTool optimized for full-text search, supporting keyword matching, Lucene syntax, and semantic search capabilities.

Parameters:

  • name – The name of this tool instance

  • endpoint – The full URL of your Azure AI Search service

  • index_name – Name of the search index to query

  • credential – Azure credential for authentication (API key or token)

  • description – Optional description explaining the tool’s purpose

  • api_version – Azure AI Search API version to use

  • query_type –

    Type of text search to perform:

    • simple : Basic keyword search that matches exact terms and their variations

    • full: Advanced search using Lucene query syntax for complex queries

    • semantic: AI-powered search that understands meaning and context, providing enhanced relevance ranking

  • search_fields – Fields to search within documents

  • select_fields – Fields to return in search results

  • top – Maximum number of results to return (default: 5)

  • filter – OData filter expression to refine search results

  • semantic_config_name – Semantic configuration name (required for semantic query_type)

  • enable_caching – Whether to cache search results

  • cache_ttl_seconds – How long to cache results in seconds

Returns:

An initialized AzureAISearchTool for full-text search

Example

from azure.core.credentials import AzureKeyCredential
from autogen_ext.tools.azure import AzureAISearchTool

# Basic keyword search
tool = AzureAISearchTool.create_full_text_search(
    name="doc-search",
    endpoint="https://your-search.search.windows.net",  # Your Azure AI Search endpoint
    index_name="<your-index>",  # Name of your search index
    credential=AzureKeyCredential("<your-key>"),  # Your Azure AI Search admin key
    query_type="simple",  # Enable keyword search
    search_fields=["content", "title"],  # Required: fields to search within
    select_fields=["content", "title", "url"],  # Optional: fields to return
    top=5,
)

# full text (Lucene query) search
full_text_tool = AzureAISearchTool.create_full_text_search(
    name="doc-search",
    endpoint="https://your-search.search.windows.net",  # Your Azure AI Search endpoint
    index_name="<your-index>",  # Name of your search index
    credential=AzureKeyCredential("<your-key>"),  # Your Azure AI Search admin key
    query_type="full",  # Enable Lucene query syntax
    search_fields=["content", "title"],  # Required: fields to search within
    select_fields=["content", "title", "url"],  # Optional: fields to return
    top=5,
)

# Semantic search with re-ranking
# Note: Make sure your index has semantic configuration enabled
semantic_tool = AzureAISearchTool.create_full_text_search(
    name="semantic-search",
    endpoint="https://your-search.search.windows.net",
    index_name="<your-index>",
    credential=AzureKeyCredential("<your-key>"),
    query_type="semantic",  # Enable semantic ranking
    semantic_config_name="<your-semantic-config>",  # Required for semantic search
    search_fields=["content", "title"],  # Required: fields to search within
    select_fields=["content", "title", "url"],  # Optional: fields to return
    top=5,
)

# The search tool can be used with an Agent
# assistant = Agent("assistant", tools=[semantic_tool])

Create a tool that combines vector and text search capabilities.

This factory method creates an AzureAISearchTool configured for hybrid search, which combines the benefits of vector similarity and traditional text search.

Parameters:

  • name – The name of this tool instance

  • endpoint – The full URL of your Azure AI Search service

  • index_name – Name of the search index to query

  • credential – Azure credential for authentication (API key or token)

  • vector_fields – Fields to use for vector search (required)

  • search_fields – Fields to use for text search (required)

  • description – Optional description explaining the tool’s purpose

  • api_version – Azure AI Search API version to use

  • query_type –

    Type of text search to perform:

    • simple: Basic keyword search that matches exact terms and their variations

    • full: Advanced search using Lucene query syntax for complex queries

    • semantic: AI-powered search that understands meaning and context, providing enhanced relevance ranking

  • select_fields – Fields to return in search results

  • top – Maximum number of results to return (default: 5)

  • filter – OData filter expression to refine search results

  • semantic_config_name – Semantic configuration name (required if query_type=”semantic”)

  • enable_caching – Whether to cache search results

  • cache_ttl_seconds – How long to cache results in seconds

  • embedding_provider – Provider for client-side embeddings (e.g., ‘azure_openai’, ‘openai’)

  • embedding_model – Model for client-side embeddings (e.g., ‘text-embedding-ada-002’)

  • openai_api_key – API key for OpenAI/Azure OpenAI embeddings

  • openai_api_version – API version for Azure OpenAI embeddings

  • openai_endpoint – Endpoint URL for Azure OpenAI embeddings

Returns:

An initialized AzureAISearchTool for hybrid search

Raises:

  • ValueError – If vector_fields or search_fields is empty

  • ValueError – If query_type is “semantic” without semantic_config_name

  • ValueError – If embedding_provider is ‘azure_openai’ without openai_endpoint

  • ValueError – If required parameters are missing or invalid

Example

from azure.core.credentials import AzureKeyCredential
from autogen_ext.tools.azure import AzureAISearchTool

# Basic hybrid search with service-side vectorization
tool = AzureAISearchTool.create_hybrid_search(
    name="hybrid-search",
    endpoint="https://your-search.search.windows.net",  # Your Azure AI Search endpoint
    index_name="<your-index>",  # Name of your search index
    credential=AzureKeyCredential("<your-key>"),  # Your Azure AI Search admin key
    vector_fields=["content_vector"],  # Your vector field name
    search_fields=["content", "title"],  # Your searchable fields
    top=5,
)

# Hybrid search with semantic ranking and Azure OpenAI embeddings
semantic_tool = AzureAISearchTool.create_hybrid_search(
    name="semantic-hybrid-search",
    endpoint="https://your-search.search.windows.net",
    index_name="<your-index>",
    credential=AzureKeyCredential("<your-key>"),
    vector_fields=["content_vector"],
    search_fields=["content", "title"],
    query_type="semantic",  # Enable semantic ranking
    semantic_config_name="<your-semantic-config>",  # Your semantic config name
    embedding_provider="azure_openai",  # Use Azure OpenAI for embeddings
    embedding_model="text-embedding-ada-002",  # Embedding model to use
    openai_endpoint="https://your-openai.openai.azure.com",  # Your Azure OpenAI endpoint
    openai_api_key="<your-openai-key>",  # Your Azure OpenAI key
    openai_api_version="2024-02-15-preview",  # Azure OpenAI API version
    select_fields=["content", "title", "url"],  # Fields to return in results
    filter="language eq 'en'",  # Optional OData filter
    top=5,
)

# The search tool can be used with an Agent
# assistant = Agent("assistant", tools=[semantic_tool])

Create a tool for pure vector/similarity search.

This factory method creates an AzureAISearchTool optimized for vector search, allowing for semantic similarity-based matching using vector embeddings.

Parameters:

  • name – The name of this tool instance

  • endpoint – The full URL of your Azure AI Search service

  • index_name – Name of the search index to query

  • credential – Azure credential for authentication (API key or token)

  • vector_fields – Fields to use for vector search (required)

  • description – Optional description explaining the tool’s purpose

  • api_version – Azure AI Search API version to use

  • select_fields – Fields to return in search results

  • top – Maximum number of results to return / k in k-NN (default: 5)

  • filter – OData filter expression to refine search results

  • enable_caching – Whether to cache search results

  • cache_ttl_seconds – How long to cache results in seconds

  • embedding_provider – Provider for client-side embeddings (e.g., ‘azure_openai’, ‘openai’)

  • embedding_model – Model for client-side embeddings (e.g., ‘text-embedding-ada-002’)

  • openai_api_key – API key for OpenAI/Azure OpenAI embeddings

  • openai_api_version – API version for Azure OpenAI embeddings

  • openai_endpoint – Endpoint URL for Azure OpenAI embeddings

Returns:

An initialized AzureAISearchTool for vector search

Raises:

  • ValueError – If vector_fields is empty

  • ValueError – If embedding_provider is ‘azure_openai’ without openai_endpoint

  • ValueError – If required parameters are missing or invalid

Example Usage:
from azure.core.credentials import AzureKeyCredential
from autogen_ext.tools.azure import AzureAISearchTool

# Vector search with service-side vectorization
tool = AzureAISearchTool.create_vector_search(
    name="vector-search",
    endpoint="https://your-search.search.windows.net",  # Your Azure AI Search endpoint
    index_name="<your-index>",  # Name of your search index
    credential=AzureKeyCredential("<your-key>"),  # Your Azure AI Search admin key
    vector_fields=["content_vector"],  # Your vector field name
    select_fields=["content", "title", "url"],  # Fields to return in results
    top=5,
)

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

# 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])
class BaseAzureAISearchTool(name: str, endpoint: str, index_name: str, credential: AzureKeyCredential | AsyncTokenCredential | Dict[str, str], description: str | None = None, api_version: str = DEFAULT_API_VERSION, query_type: Literal['simple', 'full', 'semantic', 'vector'] = 'simple', search_fields: List[str] | None = None, select_fields: List[str] | None = None, vector_fields: List[str] | None = None, top: int | None = None, filter: str | None = None, semantic_config_name: str | None = None, enable_caching: bool = False, cache_ttl_seconds: int = 300, embedding_provider: str | None = None, embedding_model: str | None = None, openai_api_key: str | None = None, openai_api_version: str | None = None, openai_endpoint: str | None = None)[source]#

Bases: BaseTool[SearchQuery, SearchResults], Component[AzureAISearchConfig], EmbeddingProvider, ABC

Abstract base class for Azure AI Search tools.

This class defines the common interface and functionality for all Azure AI Search tools. It handles configuration management, client initialization, and the abstract methods that subclasses must implement.

search_config#

Configuration parameters for the search service.

Note

This is an abstract base class and should not be instantiated directly. Use concrete implementations or the factory methods in AzureAISearchTool.

async close() → None[source]#

Explicitly close the Azure SearchClient if needed (for cleanup).

component_config_schema#

alias of AzureAISearchConfig

component_provider_override: ClassVar[str | None] = 'autogen_ext.tools.azure.BaseAzureAISearchTool'#

Override the provider string for the component. This should be used to prevent internal module names being a part of the module name.

return_value_as_string(value: SearchResults) → str[source]#

Convert the search results to a string representation.

async run(args: str | Dict[str, Any] | SearchQuery, cancellation_token: CancellationToken | None = None) → SearchResults[source]#

Execute a search against the Azure AI Search index.

Parameters:

  • args – Search query text or SearchQuery object

  • cancellation_token – Optional token to cancel the operation

Returns:

SearchResults – Container with search results and metadata

Raises:

  • ValueError – If the search query is empty or invalid

  • ValueError – If there is an authentication error or other search issue

  • CancelledError – If the operation is cancelled

property schema: ToolSchema#

Return the schema for the tool.

pydantic model SearchQuery[source]#

Bases: BaseModel

Search query parameters.

This simplified interface only requires a search query string. All other parameters (top, filters, vector fields, etc.) are specified during tool creation rather than at query time, making it easier for language models to generate structured output.

Parameters:

query (str) – The search query text.

Show JSON schema
{
   "title": "SearchQuery",
   "description": "Search query parameters.\n\nThis simplified interface only requires a search query string.\nAll other parameters (top, filters, vector fields, etc.) are specified during tool creation\nrather than at query time, making it easier for language models to generate structured output.\n\nArgs:\n    query (str): The search query text.",
   "type": "object",
   "properties": {
      "query": {
         "description": "Search query text",
         "title": "Query",
         "type": "string"
      }
   },
   "required": [
      "query"
   ]
}

Fields:

  • query (str)

field query: str [Required]#

Search query text

pydantic model SearchResult[source]#

Bases: BaseModel

Search result.

Parameters:

  • score (float) – The search score.

  • content (ContentDict) – The document content.

  • metadata (MetadataDict) – Additional metadata about the document.

Show JSON schema
{
   "title": "SearchResult",
   "description": "Search result.\n\nArgs:\n    score (float): The search score.\n    content (ContentDict): The document content.\n    metadata (MetadataDict): Additional metadata about the document.",
   "type": "object",
   "properties": {
      "score": {
         "description": "The search score",
         "title": "Score",
         "type": "number"
      },
      "content": {
         "description": "The document content",
         "title": "Content",
         "type": "object"
      },
      "metadata": {
         "description": "Additional metadata about the document",
         "title": "Metadata",
         "type": "object"
      }
   },
   "required": [
      "score",
      "content",
      "metadata"
   ]
}

Fields:

  • content (Dict[str, Any])

  • metadata (Dict[str, Any])

  • score (float)

field content: ContentDict [Required]#

The document content

field metadata: MetadataDict [Required]#

Additional metadata about the document

field score: float [Required]#

The search score

pydantic model SearchResults[source]#

Bases: BaseModel

Container for search results.

Parameters:

results (List[SearchResult]) – List of search results.

Show JSON schema
{
   "title": "SearchResults",
   "description": "Container for search results.\n\nArgs:\n    results (List[SearchResult]): List of search results.",
   "type": "object",
   "properties": {
      "results": {
         "description": "List of search results",
         "items": {
            "$ref": "#/$defs/SearchResult"
         },
         "title": "Results",
         "type": "array"
      }
   },
   "$defs": {
      "SearchResult": {
         "description": "Search result.\n\nArgs:\n    score (float): The search score.\n    content (ContentDict): The document content.\n    metadata (MetadataDict): Additional metadata about the document.",
         "properties": {
            "score": {
               "description": "The search score",
               "title": "Score",
               "type": "number"
            },
            "content": {
               "description": "The document content",
               "title": "Content",
               "type": "object"
            },
            "metadata": {
               "description": "Additional metadata about the document",
               "title": "Metadata",
               "type": "object"
            }
         },
         "required": [
            "score",
            "content",
            "metadata"
         ],
         "title": "SearchResult",
         "type": "object"
      }
   },
   "required": [
      "results"
   ]
}

Fields:

  • results (List[autogen_ext.tools.azure._ai_search.SearchResult])

field results: List[SearchResult] [Required]#

List of search results

class VectorizableTextQuery(*, text: str, k_nearest_neighbors: int | None = None, fields: str | None = None, exhaustive: bool | None = None, oversampling: float | None = None, weight: float | None = None, **kwargs: Any)[source]#

Bases: VectorQuery

The query parameters to use for vector search when a text value that needs to be vectorized is provided.

All required parameters must be populated in order to send to server.

Variables:

  • kind (str or VectorQueryKind) – The kind of vector query being performed. Required. Known values are: “vector” and “text”.

  • k_nearest_neighbors (int) – Number of nearest neighbors to return as top hits.

  • fields (str) – Vector Fields of type Collection(Edm.Single) to be included in the vector searched.

  • exhaustive (bool) – When true, triggers an exhaustive k-nearest neighbor search across all vectors within the vector index. Useful for scenarios where exact matches are critical, such as determining ground truth values.

  • oversampling (float) – Oversampling factor. Minimum value is 1. It overrides the ‘defaultOversampling’ parameter configured in the index definition. It can be set only when ‘rerankWithOriginalVectors’ is true. This parameter is only permitted when a compression method is used on the underlying vector field.

  • weight (float) – Relative weight of the vector query when compared to other vector query and/or the text query within the same search request. This value is used when combining the results of multiple ranking lists produced by the different vector queries and/or the results retrieved through the text query. The higher the weight, the higher the documents that matched that query will be in the final ranking. Default is 1.0 and the value needs to be a positive number larger than zero.

  • text (str) – The text to be vectorized to perform a vector search query. Required.

On this page
Edit on GitHub
Show Source