azure-cognitive-search

name	azure-cognitive-search
description	Expert knowledge for Azure AI Search development including troubleshooting, best practices, decision making, architecture & design patterns, limits & quotas, security, configuration, integrations & coding patterns, and deployment. Use when building indexes/skillsets, configuring semantic/vector search, tuning indexers, or securing deployments, and other Azure AI Search related development tasks. Not for Azure Cosmos DB (use azure-cosmos-db), Azure SQL Database (use azure-sql-database), Azure Synapse Analytics (use azure-synapse-analytics), Azure Data Explorer (use azure-data-explorer).
compatibility	Requires network access. Uses mcp_microsoftdocs:microsoft_docs_fetch or fetch_webpage to retrieve documentation.
metadata	{"generated_at":"2026-08-09","generator":"docs2skills/1.0.0"}

Azure AI Search Skill

This skill provides expert guidance for Azure AI Search. Covers troubleshooting, best practices, decision making, architecture & design patterns, limits & quotas, security, configuration, integrations & coding patterns, and deployment. It combines local quick-reference content with remote documentation fetching capabilities.

How to Use This Skill

IMPORTANT for Agent: Use the Category Index below to locate relevant sections. For categories with line ranges (e.g., L35-L120), use read_file with the specified lines. For categories with file links (e.g., [security.md](security.md)), use read_file on the linked reference file

IMPORTANT for Agent: If metadata.generated_at is more than 3 months old, suggest the user pull the latest version from the repository. If mcp_microsoftdocs tools are not available, suggest the user install it: Installation Guide

This skill requires network access to fetch documentation content:

• Preferred: Use mcp_microsoftdocs:microsoft_docs_fetch with query string from=learn-agent-skill. Returns Markdown.
• Fallback: Use fetch_webpage with query string from=learn-agent-skill&accept=text/markdown. Returns Markdown.

Category Index

Category	Lines	Description
Troubleshooting	L37-L47	Diagnosing and fixing Azure AI Search indexer and skillset errors, portal debugging, OData filter issues, private link problems, and storage/metrics discrepancies.
Best Practices	L48-L66	Designing, scaling, and troubleshooting AI enrichment and indexing pipelines, optimizing performance/costs, handling data changes, and applying vector, concurrency, and responsible AI best practices.
Decision Making	L67-L81	Guidance on sizing, upgrading, and migrating Azure AI Search services and SDKs, choosing regions, tiers, pricing models, and data source connectors, and planning capacity and costs.
Architecture & Design Patterns	L82-L88	Architectural patterns for Azure AI Search: combining vector and keyword search, designing multitenant or isolated indexes, and building resilient multi-region search deployments.
Limits & Quotas	L89-L98	Limits, quotas, and scheduling for Azure AI Search: billing/free enrichment, indexer runs/resets, schedules, execution quotas on Serverless/S3 HD, service SKUs, and vector index size caps.
Security	L99-L138	Securing Azure AI Search: RBAC/ACL, Entra ID auth, keys, encryption, network isolation (VNet, private endpoints, firewalls), and secure indexer connections to data sources.
Configuration	L139-L222	Configuring Azure AI Search: indexes, indexers, analyzers, skillsets, enrichment, vectorization, semantic ranker, knowledge bases, retrieval behavior, logging, and query options.
Integrations & Coding Patterns	L223-L308	Connecting data sources, indexers, skills, vectorization, and query patterns to build, integrate, and query Azure AI Search knowledge bases and agentic retrieval experiences
Deployment	L309-L316	Deploying and moving Azure AI Search: ARM/Bicep/Terraform provisioning, cross-region migration, and deploying C# search apps to Azure Container Apps.

Troubleshooting

Topic	URL
Troubleshoot Azure AI Search indexer errors and warnings	https://learn.microsoft.com/en-us/azure/search/cognitive-search-common-errors-warnings
Debug and troubleshoot Azure AI Search skillsets	https://learn.microsoft.com/en-us/azure/search/cognitive-search-how-to-debug-skillset
Debug Azure AI Search skillsets using portal sessions	https://learn.microsoft.com/en-us/azure/search/cognitive-search-tutorial-debug-sessions
Diagnose and fix Azure AI Search indexer issues	https://learn.microsoft.com/en-us/azure/search/search-indexer-troubleshooting
Troubleshoot OData collection filters in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/search-query-troubleshoot-collection-filters
Troubleshoot shared private link resource issues in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/troubleshoot-shared-private-link-resources
Diagnose Azure AI Search storage and metric discrepancies	https://learn.microsoft.com/en-us/azure/search/troubleshoot-storage-metrics

Best Practices

Topic	URL
Design and troubleshoot AI enrichment pipelines in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/cognitive-search-concept-troubleshooting
Scale and manage custom skills in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/cognitive-search-custom-skill-scale
Apply responsible AI best practices for GenAI Prompt skill	https://learn.microsoft.com/en-us/azure/search/responsible-ai-best-practices-genai-prompt-skill
Handle changed and deleted blobs in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/search-how-to-index-azure-blob-changed-deleted
Optimize large-scale indexing in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/search-how-to-large-index
Apply optimistic concurrency for Azure AI Search resources	https://learn.microsoft.com/en-us/azure/search/search-howto-concurrency
Update or rebuild Azure AI Search indexes safely	https://learn.microsoft.com/en-us/azure/search/search-howto-reindex
Analyze Azure AI Search query and indexing performance	https://learn.microsoft.com/en-us/azure/search/search-performance-analysis
Optimize Azure AI Search query and indexing performance	https://learn.microsoft.com/en-us/azure/search/search-performance-tips
Optimize Azure AI Search Serverless costs and usage	https://learn.microsoft.com/en-us/azure/search/serverless-cost-optimization
Optimize Azure AI Search indexing with Push API in C#	https://learn.microsoft.com/en-us/azure/search/tutorial-optimize-indexing-push-api

Decision Making

Topic	URL
Migrate from deprecated Azure AI Search skills	https://learn.microsoft.com/en-us/azure/search/cognitive-search-skill-deprecated
Plan and execute Azure AI Search REST API upgrades	https://learn.microsoft.com/en-us/azure/search/search-api-migration
Estimate Azure AI Search capacity for indexing and queries	https://learn.microsoft.com/en-us/azure/search/search-capacity-planning
Create Azure AI Search services with appropriate region and tier	https://learn.microsoft.com/en-us/azure/search/search-create-service-portal
Choose appropriate data source connectors for Azure AI Search	https://learn.microsoft.com/en-us/azure/search/search-data-sources-gallery
Upgrade Azure AI Search .NET management SDKs	https://learn.microsoft.com/en-us/azure/search/search-dotnet-mgmt-sdk-migration
Migrate Azure AI Search .NET SDK to v11	https://learn.microsoft.com/en-us/azure/search/search-dotnet-sdk-migration-version-11
Upgrade Azure AI Search to higher capacity	https://learn.microsoft.com/en-us/azure/search/search-how-to-upgrade
Handle Azure AI Search regional capacity constraints	https://learn.microsoft.com/en-us/azure/search/search-region-capacity
Plan and manage Azure AI Search costs	https://learn.microsoft.com/en-us/azure/search/search-sku-manage-costs
Select Azure AI Search pricing model and service tier	https://learn.microsoft.com/en-us/azure/search/search-sku-tier

Architecture & Design Patterns

Topic	URL
Design hybrid search with vector and full-text in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/hybrid-search-overview
Design multitenant and isolated content in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/search-modeling-multitenant-saas-applications
Design multi-region architectures for Azure AI Search	https://learn.microsoft.com/en-us/azure/search/search-multi-region

Limits & Quotas

Topic	URL
Billing limits and free quotas for Azure AI Search enrichment	https://learn.microsoft.com/en-us/azure/search/cognitive-search-attach-cognitive-services
Manage Azure AI Search indexer runs and resets	https://learn.microsoft.com/en-us/azure/search/search-howto-run-reset-indexers
Configure Azure AI Search indexer schedules and limits	https://learn.microsoft.com/en-us/azure/search/search-howto-schedule-indexers
Understand indexer execution quotas on Serverless and S3 HD	https://learn.microsoft.com/en-us/azure/search/search-indexer-high-density-serverless-overview
Azure AI Search service limits by tier and SKU	https://learn.microsoft.com/en-us/azure/search/search-limits-quotas-capacity
Understand vector index size limits in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/vector-search-index-size

Security

Topic	URL
Use built-in Azure Policy definitions for Azure AI Search	https://learn.microsoft.com/en-us/azure/search/policy-reference
Ingest RBAC scope metadata from Azure Blob storage	https://learn.microsoft.com/en-us/azure/search/search-blob-indexer-role-based-access
Implement document-level access control in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/search-document-level-access-overview
Configure keyless RBAC access to Azure AI Search	https://learn.microsoft.com/en-us/azure/search/search-get-started-rbac
Configure managed identity access to SQL Managed Instance	https://learn.microsoft.com/en-us/azure/search/search-how-to-index-sql-managed-instance-with-managed-identity
Secure AI Search indexer connections to SQL Server VMs	https://learn.microsoft.com/en-us/azure/search/search-how-to-index-sql-server
Configure managed identities and RBAC for Azure AI Search	https://learn.microsoft.com/en-us/azure/search/search-how-to-managed-identities
Configure Azure AI Search indexer with Easy Auth Functions	https://learn.microsoft.com/en-us/azure/search/search-howto-managed-identities-azure-functions
Secure Cosmos DB indexer connections with managed identity	https://learn.microsoft.com/en-us/azure/search/search-howto-managed-identities-cosmos-db
Configure managed identity access from Azure AI Search to Azure SQL	https://learn.microsoft.com/en-us/azure/search/search-howto-managed-identities-sql
Configure managed identity access from Azure AI Search to Storage

Configuration

Topic	URL
Configure file-based knowledge sources in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-file
Enable or disable Web Knowledge Source access in Azure	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-web-manage
Configure answer synthesis for Azure AI Search knowledge bases	https://learn.microsoft.com/en-us/azure/search/agentic-retrieval-how-to-answer-synthesis
Configure freshness-aware retrieval for agentic knowledge sources	https://learn.microsoft.com/en-us/azure/search/agentic-retrieval-how-to-configure-freshness
Define Azure AI Search index for agentic retrieval	https://learn.microsoft.com/en-us/azure/search/agentic-retrieval-how-to-create-index
Configure agentic retrieval billing consent in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/agentic-retrieval-how-to-enable-disable
Configure image serving for agentic retrieval answer synthesis	https://learn.microsoft.com/en-us/azure/search/agentic-retrieval-how-to-image-serving
Set retrieval reasoning effort for agentic Azure AI Search	https://learn.microsoft.com/en-us/azure/search/agentic-retrieval-how-to-set-retrieval-reasoning-effort
Use annotation syntax to reference enriched nodes in skillsets	https://learn.microsoft.com/en-us/azure/search/cognitive-search-concept-annotations-syntax
Define and configure skillsets in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/cognitive-search-defining-skillset

Integrations & Coding Patterns

Topic	URL
Create Azure SQL knowledge sources for agentic retrieval	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-azure-sql
Create blob knowledge sources for agentic retrieval	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-blob
Create Fabric Data Agent knowledge sources for live grounding	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-fabric-data-agent
Create Fabric Ontology knowledge sources for agentic retrieval	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-fabric-ontology
Create MCP server knowledge sources for agentic retrieval	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-mcp-server
Create OneLake knowledge sources for agentic retrieval	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-onelake
Create indexed SharePoint knowledge sources in Azure AI Search	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-sharepoint-indexed
Create remote SharePoint knowledge sources for agentic retrieval	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-sharepoint-remote
Create web knowledge sources for agentic retrieval	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-web
Create Work IQ knowledge sources for organizational grounding	https://learn.microsoft.com/en-us/azure/search/agentic-knowledge-source-how-to-work-iq

Deployment

Topic	URL
Deploy Azure AI Search via ARM templates	https://learn.microsoft.com/en-us/azure/search/search-get-started-arm
Deploy Azure AI Search using Bicep files	https://learn.microsoft.com/en-us/azure/search/search-get-started-bicep
Provision Azure AI Search services with Terraform	https://learn.microsoft.com/en-us/azure/search/search-get-started-terraform
Move Azure AI Search services across regions	https://learn.microsoft.com/en-us/azure/search/search-howto-move-across-regions
Deploy C# Azure AI Search apps to Container Apps	https://learn.microsoft.com/en-us/azure/search/tutorial-csharp-deploy-web-search