Ask a coding agent to "provision a Cosmos DB account with Terraform" and you'll get something that plans cleanly, applies without error, and quietly bakes in three decisions nobody made on purpose. Session consistency because that's the provider default. Fixed throughput because the agent picked a number. No zone redundancy because you didn't ask for it and neither did the model. The resource comes up green. Six weeks later a single availability zone blips and takes your write region with it, or your RU bill is double what a workload this size should cost.
The problem isn't that the agent can't write HCL. It writes HCL fine. The problem is that Cosmos DB has a few dozen configuration choices where the default and the right answer for production diverge, and a general-purpose model has no strong opinion about which is which. It optimizes for "this parses," not "this survives a zone failure at 2 a.m."
The Azure Cosmos DB Agent Kit is Microsoft's answer to exactly that gap, and it's worth understanding what it actually is before you install it, because it is not a code generator.
It's a knowledge layer, not a generator
The Agent Kit is an open-source collection of skills — packaged instructions and scripts that extend an AI coding agent's behavior. It doesn't add a chat panel or a wizard. It ships rules in a plain structure the agent reads: a SKILL.md that says when to activate, an AGENTS.md of compiled rules, individual rule files, and metadata. When you start working on something Cosmos DB-shaped — a Terraform module, a partition key, an SDK client — the skill activates automatically and folds that expertise into whatever the agent was already doing.
It's built on the open Agent Skills format, so it isn't tied to one tool. It works with GitHub Copilot, Claude Code, Gemini CLI, and anything else that speaks Agent Skills. Setup is genuinely a one-liner:
npx skills add AzureCosmosDB/cosmosdb-agent-kit
That's the whole install for a single machine. You can also drop it into .github/skills/ in a repo so the whole team's agents inherit the same rules, which is the version I'd reach for — infrastructure standards that live in the repo beat standards that live in one person's home directory.
At general availability the kit carries 120+ rules across 12 categories, up from 45 across 8 in preview. For infrastructure work the ones that earn their keep are throughput and scaling, global distribution, partition key design, and a developer-tooling category that covers emulator setup and build validation.
What it changes in an infra review
Here's the concrete before-and-after, because that's where the value shows up. Point the agent at a hand-written or agent-drafted module using the @ file reference:
@infra/main.tf Review this for multi-region production readiness
Without the kit, that review is generic — maybe it notices a hardcoded key, maybe it doesn't. With the kit loaded, it reads the file against Cosmos-specific rules and flags the things that actually bite: missing zone redundancy, a consistency level that doesn't match the workload, fixed throughput where autoscale belongs. When it generates a corrected module, the defaults flip toward production:
resource "azurerm_cosmosdb_account" "this" {
# ...
automatic_failover_enabled = true
consistency_policy {
consistency_level = "Session" # chosen, not inherited
}
geo_location {
location = "eastus2"
failover_priority = 0
zone_redundant = true
}
}
resource "azurerm_cosmosdb_sql_container" "this" {
# ...
partition_key_version = 2 # large partition keys
}
Continuous backup instead of periodic, partition_key_version = 2 so you're not capped at the old 100-byte key limit, automatic failover switched on, zone redundancy on the geo-location block. None of these are exotic. They're the settings an experienced Cosmos DB engineer sets by reflex and a generic model leaves at whatever the provider ships. The kit's whole thesis is captured in one line from the team: if we package Azure Cosmos DB expertise into a format that AI coding agents understand, developers will stop making the same expensive mistakes. The named mistakes are the usual production killers — connection exhaustion, unnecessary RU burn, hot partitions, missing retry logic.
Because it runs inside an agent with terminal and file access, the review isn't the end of it. The same session can generate a Docker Compose file with a working emulator and health checks, scaffold a GitHub Actions workflow with OIDC auth and separate dev/staging/prod, and run terraform plan to check its own output. MCP support lets it reach Azure Resource Graph and remote state backends when it needs live context.
Why "battle tested" isn't just a label
I'm allergic to "GA-ready" claims, so the validation approach here is the part that actually convinced me. The team didn't hand-check rules — they built a closed-loop harness that has AI agents build real applications from scratch using the rules, then scores the result. Five scenarios (e-commerce API, gaming leaderboard, IoT pipeline, RAG chat, multi-tenant SaaS), each run 5+ times per language for statistical confidence, across 200+ automated test iterations. Every gap the harness exposed got fixed before GA.
The scores are specific enough to be falsifiable: IoT telemetry landed at 9.5/10, the gaming leaderboard scenario climbed from 5/10 to 9/10 once the partition and throughput rules were in place, multi-tenant SaaS hit a 100% pass rate. That's a regression suite for knowledge — a more honest way to ship agent tooling than "we wrote some prompts and it felt better."
The honest caveat
This is advisory, not authoritative. The kit makes your agent propose better infrastructure; it does not review, approve, or apply it for you. The generated module still goes through your normal plan-and-review gate, and it should — an agent that now sets zone_redundant = true correctly can still get a partition key wrong for your access pattern, because it can't see your query shape unless you tell it. Treat the kit as a very well-read pair reviewer who has provisioned a thousand Cosmos DB accounts, not as the person who signs off on the change.
The takeaway is small and practical: before your next Cosmos DB Terraform review, spend the 30 seconds to npx skills add the kit into the repo, then re-run the review on a module you already shipped. The delta between what you deployed and what the kit flags is the most useful audit of your Cosmos DB defaults you'll run this quarter — and it costs one command to find out.
Sources: Accelerate Your Cosmos DB Infrastructure with GitHub Copilot CLI and Azure Cosmos DB Agent Kit, Introducing the Azure Cosmos DB Agent Kit, Azure Cosmos DB Agent Kit now battle tested for GA