{"id":11736,"date":"2026-01-22T09:16:17","date_gmt":"2026-01-22T17:16:17","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cosmosdb\/?p=11736"},"modified":"2026-01-29T11:03:52","modified_gmt":"2026-01-29T19:03:52","slug":"azure-cosmos-db-agent-kit-ai-coding-assistants","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cosmosdb\/azure-cosmos-db-agent-kit-ai-coding-assistants\/","title":{"rendered":"Introducing the Azure Cosmos DB Agent Kit: Your AI Pair Programmer Just Got Smarter"},"content":{"rendered":"<p>The <a href=\"https:\/\/github.com\/AzureCosmosDB\/cosmosdb-agent-kit\"><strong>Azure Cosmos DB Agent Kit<\/strong> <\/a>is an open-source collection of skills that teaches your AI coding assistant (GitHub Copilot, Claude Code, Gemini CLI) <strong>expert-level Azure Cosmos DB best practices<\/strong>.<\/p>\n<p>Install with one command, get production-ready guidance instantly.<\/p>\n<h2>The Challenge Every Azure Cosmos DB Developer Faces<\/h2>\n<p>You&#8217;re building a new application with Azure Cosmos DB. You&#8217;ve got your data, you&#8217;ve got your queries, but then come the questions that keep you up at night:<\/p>\n<ul>\n<li>&#8220;Is this the right partition key?&#8221;<\/li>\n<li>&#8220;Why is my query consuming so many RUs?&#8221;<\/li>\n<li>&#8220;Should I embed this data or reference it?&#8221;<\/li>\n<li>&#8220;Am I going to hit a hot partition in production?&#8221;<\/li>\n<\/ul>\n<p>These aren&#8217;t trivial questions. Poor decisions here can mean the difference between a blazing-fast application and one that struggles under load or worse, one that becomes prohibitively expensive to run.<\/p>\n<p>Until now, getting these answers meant diving into documentation, searching Stack Overflow, or hoping someone on your team had battle-tested experience.<\/p>\n<p><strong>What if your AI coding assistant already knew the answers?<\/strong><\/p>\n<h2>Introducing the Azure Cosmos DB Agent Kit<\/h2>\n<p>The <strong>Azure Cosmos DB Agent Kit<\/strong> is an open-source project that extends AI coding agents with deep Azure Cosmos DB expertise.<\/p>\n<p>Built on the <strong>Agent Skills format<\/strong>, it works seamlessly with:<\/p>\n<ul>\n<li>\u2705 GitHub Copilot<\/li>\n<li>\u2705 Claude Code<\/li>\n<li>\u2705 Gemini CLI<\/li>\n<li>\u2705 Any Agent Skills-compatible tool<\/li>\n<\/ul>\n<h2>What&#8217;s Inside?<\/h2>\n<p>The kit includes <strong>45+ curated rules across 8 categories<\/strong>, each prioritized by real-world impact:<\/p>\n<table style=\"border-collapse: collapse; width: 100%; height: 224px;\">\n<tbody>\n<tr style=\"height: 23px;\">\n<td style=\"width: 29.5169%; height: 40px;\"><strong>Category<\/strong><\/td>\n<td style=\"width: 70.4831%; height: 40px;\"><strong>What You&#8217;ll Learn<\/strong><\/td>\n<\/tr>\n<tr style=\"height: 23px;\">\n<td style=\"width: 29.5169%; height: 23px;\">Data Modeling<\/td>\n<td style=\"width: 70.4831%; height: 23px;\">Embedding vs. referencing, document size limits, hierarchical data<\/td>\n<\/tr>\n<tr style=\"height: 23px;\">\n<td style=\"width: 29.5169%; height: 23px;\">Partition Key Design<\/td>\n<td style=\"width: 70.4831%; height: 23px;\">High cardinality, avoiding hot partitions, synthetic keys<\/td>\n<\/tr>\n<tr style=\"height: 23px;\">\n<td style=\"width: 29.5169%; height: 23px;\">Query Optimization<\/td>\n<td style=\"width: 70.4831%; height: 23px;\">Cross-partition queries, projection, pagination<\/td>\n<\/tr>\n<tr style=\"height: 23px;\">\n<td style=\"width: 29.5169%; height: 23px;\">SDK Best Practices<\/td>\n<td style=\"width: 70.4831%; height: 23px;\">Connection management, retry logic, async patterns<\/td>\n<\/tr>\n<tr style=\"height: 23px;\">\n<td style=\"width: 29.5169%; height: 23px;\">Indexing Strategies<\/td>\n<td style=\"width: 70.4831%; height: 23px;\">Custom policies, composite indexes, spatial indexing<\/td>\n<\/tr>\n<tr style=\"height: 23px;\">\n<td style=\"width: 29.5169%; height: 23px;\">Throughput &amp; Scaling<\/td>\n<td style=\"width: 70.4831%; height: 23px;\">Autoscale, provisioned RUs, serverless decisions<\/td>\n<\/tr>\n<tr style=\"height: 23px;\">\n<td style=\"width: 29.5169%; height: 23px;\">Global Distribution<\/td>\n<td style=\"width: 70.4831%; height: 23px;\">Multi-region writes, consistency levels, failover<\/td>\n<\/tr>\n<tr style=\"height: 23px;\">\n<td style=\"width: 29.5169%; height: 23px;\">Monitoring &amp; Diagnostics<\/td>\n<td style=\"width: 70.4831%; height: 23px;\">Logging, metrics, troubleshooting<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>Getting Started in 60 Seconds<\/h2>\n<h3>Step 1: Install the Skill<\/h3>\n<p>Open your terminal and run:<\/p>\n<pre style=\"background: #000; color: #0f0; padding: 16px; border-radius: 6px; font-family: monospace; font-size: 14px; overflow-x: auto;\">npx skills add AzureCosmosDB\/cosmosdb-agent-kit<\/pre>\n<p>That&#8217;s it. The skill is now installed in your development environment.<\/p>\n<h3>Step 2: Start Coding<\/h3>\n<p>The skill activates automatically when you work on Azure Cosmos DB-related tasks. Just ask your AI agent naturally:<\/p>\n<pre style=\"background: #000; color: #0f0; padding: 16px; border-radius: 6px; font-family: monospace; font-size: 14px; overflow-x: auto;\">Review my Cosmos DB data model for performance issues\r\nHelp me choose a partition key for my e-commerce orders collection\r\nOptimize this query that's consuming too many RUs\r\nWhat's wrong with my Cosmos DB connection code?<\/pre>\n<h2>Real-World Example: Building a Product Catalog<\/h2>\n<p>Let&#8217;s walk through a practical example. You&#8217;re building a product catalog API and want to ensure you&#8217;re following best practices from the start.<\/p>\n<h3>Your Initial Code<\/h3>\n<pre style=\"background: #000; color: #0f0; padding: 16px; border-radius: 6px; font-family: monospace; font-size: 14px; overflow-x: auto;\">\/\/ cosmosService.js\r\nconst { CosmosClient } = require('@azure\/cosmos');\r\n\r\nconst endpoint = process.env.COSMOS_ENDPOINT;\r\nconst key = process.env.COSMOS_KEY;\r\n\r\n\/\/ \u274c Creating new client on every request\r\nasync function getProducts(category) {\r\n    const client = new CosmosClient({ endpoint, key });\r\n    const database = client.database('ProductCatalog');\r\n    const container = database.container('Products');\r\n\r\n    \/\/ \u274c Using SELECT * pulls all properties\r\n    const query = `SELECT * FROM c WHERE c.category = '${category}'`;\r\n    const { resources } = await container.items.query(query).fetchAll();\r\n    return resources;\r\n}\r\n\r\nmodule.exports = { getProducts };<\/pre>\n<h3>Ask Your AI Agent<\/h3>\n<p>Simply prompt: <strong>&#8220;Review this Azure Cosmos DB service code for best practices issues&#8221;<\/strong><\/p>\n<h3>What the Agent Knows (Thanks to the Skill)<\/h3>\n<p>The Azure Cosmos DB Agent Kit teaches your AI agent to identify multiple issues:<\/p>\n<ol>\n<li><strong>SDK Anti-pattern:<\/strong> Creating a new CosmosClient on every request wastes resources<\/li>\n<li><strong>Query Optimization:<\/strong> SELECT * pulls unnecessary data, consuming extra RUs<\/li>\n<li><strong>Security Risk:<\/strong> String concatenation in queries can lead to injection attacks<\/li>\n<li><strong>Missing Error Handling:<\/strong> No retry logic for rate limiting (429 errors)<\/li>\n<\/ol>\n<h3>The Improved Code<\/h3>\n<pre style=\"background: #000; color: #0f0; padding: 16px; border-radius: 6px; font-family: monospace; font-size: 14px; overflow-x: auto;\">\/\/ cosmosService.js\r\nconst { CosmosClient } = require('@azure\/cosmos');\r\n\r\nconst endpoint = process.env.COSMOS_ENDPOINT;\r\nconst key = process.env.COSMOS_KEY;\r\n\r\n\/\/ \u2705 Singleton client instance - reuse across requests\r\nconst client = new CosmosClient({\r\n    endpoint,\r\n    key,\r\n    connectionPolicy: {\r\n        retryOptions: {\r\n            maxRetryAttemptCount: 5,\r\n            maxWaitTimeInSeconds: 30\r\n        }\r\n    }\r\n});\r\n\r\nconst database = client.database('ProductCatalog');\r\nconst container = database.container('Products');\r\n\r\nasync function getProducts(category) {\r\n    \/\/ \u2705 Project only needed fields to reduce RU consumption\r\n    const query = {\r\n        query: `SELECT c.id, c.name, c.price, c.description, c.imageUrl \r\n                FROM c WHERE c.category = @category`,\r\n        parameters: [{ name: '@category', value: category }]\r\n    };\r\n\r\n    try {\r\n        const { resources, requestCharge } = await container.items\r\n            .query(query)\r\n            .fetchAll();\r\n\r\n        \/\/ \u2705 Log RU consumption for monitoring\r\n        console.log(`Query consumed ${requestCharge} RUs`);\r\n\r\n        return resources;\r\n    } catch (error) {\r\n        if (error.code === 429) {\r\n            \/\/ \u2705 Handle rate limiting gracefully\r\n            console.warn('Rate limited, retry after:', error.retryAfterInMs);\r\n            throw new Error('Service temporarily unavailable');\r\n        }\r\n        throw error;\r\n    }\r\n}\r\n\r\nmodule.exports = { getProducts };<\/pre>\n<h2>Choosing the Right Partition Key<\/h2>\n<p>One of the most critical decisions in Azure Cosmos DB is partition key selection. Let&#8217;s say you&#8217;re designing a multi-tenant SaaS application.<\/p>\n<h3>Ask Your Agent<\/h3>\n<p><strong>&#8220;Help me choose a partition key for a multi-tenant order management system where each tenant has thousands of orders, and we frequently query orders by tenant and date range&#8221;<\/strong><\/p>\n<h3>What the Agent Recommends<\/h3>\n<p>Based on the skill&#8217;s knowledge, your agent will guide you toward:<\/p>\n<pre style=\"background: #000; color: #0f0; padding: 16px; border-radius: 6px; font-family: monospace; font-size: 14px; overflow-x: auto;\">\/\/ \u2705 Using Hierarchical Partition Keys for multi-tenant scenarios\r\nconst containerDefinition = {\r\n    id: 'Orders',\r\n    partitionKey: {\r\n        paths: ['\/tenantId', '\/year'],  \/\/ Hierarchical partition key\r\n        version: 2\r\n    }\r\n};\r\n\r\n\/\/ Document structure\r\nconst order = {\r\n    id: 'order-12345',\r\n    tenantId: 'tenant-abc',     \/\/ First level: tenant isolation\r\n    year: 2026,                  \/\/ Second level: time-based distribution\r\n    orderDate: '2026-01-22T10:30:00Z',\r\n    customerId: 'cust-789',\r\n    items: [...],\r\n    total: 299.99\r\n};<\/pre>\n<p><strong>Why this works:<\/strong><\/p>\n<ul>\n<li><strong>Tenant isolation:<\/strong> Queries for a single tenant stay within partition boundaries<\/li>\n<li><strong>Avoids hot partitions:<\/strong> Orders distribute across time-based partitions<\/li>\n<li><strong>Scales beyond 20GB:<\/strong> Hierarchical keys overcome single partition limits<\/li>\n<li><strong>Efficient range queries:<\/strong> Date-range queries within a tenant are optimized<\/li>\n<\/ul>\n<h2>The Skill Structure<\/h2>\n<p>Curious how the skill works under the hood? Each skill contains:<\/p>\n<pre style=\"background: #000; color: #0f0; padding: 16px; border-radius: 6px; font-family: monospace; font-size: 14px; overflow-x: auto;\">skills\/cosmosdb-best-practices\/\r\n\u251c\u2500\u2500 SKILL.md          # Triggers activation, describes capabilities\r\n\u251c\u2500\u2500 AGENTS.md         # Compiled rules (what agents read)\r\n\u251c\u2500\u2500 rules\/            # Individual rule files\r\n\u2502   \u251c\u2500\u2500 data-modeling.md\r\n\u2502   \u251c\u2500\u2500 partition-keys.md\r\n\u2502   \u251c\u2500\u2500 query-optimization.md\r\n\u2502   \u2514\u2500\u2500 ...\r\n\u2514\u2500\u2500 metadata.json     # Version and metadata<\/pre>\n<p>When you work on Azure Cosmos DB code, the AI agent automatically loads the relevant rules and applies them to your context.<\/p>\n<h2>We Need Your Expertise!<\/h2>\n<p>The Azure Cosmos DB Agent Kit is open source, and we want your contributions!<\/p>\n<p>Have you discovered a best practice we haven&#8217;t covered? Maybe you&#8217;ve learned something the hard way:<\/p>\n<ul>\n<li>A query pattern that dramatically reduced RUs<\/li>\n<li>A data modeling approach that scaled beautifully<\/li>\n<li>An SDK configuration that improved reliability<\/li>\n<li>A monitoring technique that caught issues early<\/li>\n<\/ul>\n<p><strong>Share it with the community!<\/strong><\/p>\n<h3>How to Contribute<\/h3>\n<ol>\n<li>Fork the repository<\/li>\n<li>Add your rule to the appropriate category in <code>\/skills\/cosmosdb-best-practices\/rules\/<\/code><\/li>\n<li>Submit a PR with a description of the scenario and impact<\/li>\n<li>Help thousands of developers write better Azure Cosmos DB code<\/li>\n<\/ol>\n<p>Check out <strong>AGENTS.md<\/strong> for contribution guidelines.<\/p>\n<h2>Get Started Today<\/h2>\n<pre style=\"background: #000; color: #0f0; padding: 16px; border-radius: 6px; font-family: monospace; font-size: 14px; overflow-x: auto;\">npx skills add AzureCosmosDB\/cosmosdb-agent-kit<\/pre>\n<p>\ud83c\udf1f <strong>Star the repo:<\/strong> <a href=\"https:\/\/github.com\/AzureCosmosDB\/cosmosdb-agent-kit\">github.com\/AzureCosmosDB\/cosmosdb-agent-kit<\/a><\/p>\n<p>\ud83d\udcac <strong>Share feedback:<\/strong> Open an issue or discussion<\/p>\n<p>\ud83e\udd1d <strong>Contribute:<\/strong> Your best practices can help the entire community<\/p>\n<h2>Learn Cosmos DB Visually<\/h2>\n<div>Prefer learning through visuals? Check out the <a href=\"https:\/\/sajeetharan.github.io\/cosmos-graphic\/\">Azure Cosmos DB Visual Storybook\u00a0<\/a> an interactive collection of infographics covering everything from the basics to advanced AI integration. It&#8217;s a great companion to the agent-kit, helping you understand why the best practices exist before Copilot applies them to your code.<\/div>\n<h2>Leave a Review<\/h2>\n<p>Tell us about your Azure Cosmos DB experience! Leave a review on PeerSpot and get a $50 gift.\u00a0<a href=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/azure-cosmos-db-agent-kit-ai-coding-assistants\/#\">Get started here<\/a>.<\/p>\n<h2 id=\"about-azure-cosmos-db\"><strong>About Azure Cosmos DB<\/strong><\/h2>\n<p>Azure Cosmos DB is a fully managed and serverless NoSQL and vector database for modern app development, including AI applications. With its SLA-backed speed and availability as well as instant dynamic scalability, it is ideal for real-time NoSQL and MongoDB applications that require high performance and distributed computing over massive volumes of NoSQL and vector data.<\/p>\n<p>To stay in the loop on Azure Cosmos DB updates, follow us on\u00a0<a href=\"https:\/\/twitter.com\/AzureCosmosDB\" target=\"_blank\" rel=\"noopener\">X<\/a>,\u00a0<a href=\"https:\/\/aka.ms\/AzureCosmosDBYouTube\" target=\"_blank\" rel=\"noopener\">YouTube<\/a>, and\u00a0<a href=\"https:\/\/www.linkedin.com\/company\/azure-cosmos-db\/\" target=\"_blank\" rel=\"noopener\">LinkedIn<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>The Azure Cosmos DB Agent Kit is an open-source collection of skills that teaches your AI coding assistant (GitHub Copilot, Claude Code, Gemini CLI) expert-level Azure Cosmos DB best practices. Install with one command, get production-ready guidance instantly. The Challenge Every Azure Cosmos DB Developer Faces You&#8217;re building a new application with Azure Cosmos DB. [&hellip;]<\/p>\n","protected":false},"author":80443,"featured_media":11749,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1610,1980],"tags":[1986,1987,1989,957,1990,1988,1993,1992,1991],"class_list":["post-11736","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-ai","category-azure-cosmos-db","tag-agentkit","tag-azurecosmsodb","tag-claude","tag-cosmosdb","tag-gemini","tag-githubcopilot","tag-instructions","tag-skills","tag-windsurf"],"acf":[],"blog_post_summary":"<p>The Azure Cosmos DB Agent Kit is an open-source collection of skills that teaches your AI coding assistant (GitHub Copilot, Claude Code, Gemini CLI) expert-level Azure Cosmos DB best practices. Install with one command, get production-ready guidance instantly. The Challenge Every Azure Cosmos DB Developer Faces You&#8217;re building a new application with Azure Cosmos DB. [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/11736","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/users\/80443"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/comments?post=11736"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/11736\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media\/11749"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media?parent=11736"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/categories?post=11736"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/tags?post=11736"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}