--- layout: Conceptual title: Use the Azure Cosmos DB Agent Kit - Azure Cosmos DB | Microsoft Learn canonicalUrl: https://learn.microsoft.com/en-us/azure/cosmos-db/gen-ai/agent-kit/usage uhfHeaderId: MSDocsHeader-NoSQL permissioned-type: public recommendations: true recommendation_types: - Training - Certification breadcrumb_path: ../../../breadcrumb/azure-nosql/toc.json feedback_system: Standard feedback_product_url: https://feedback.azure.com/d365community/forum/3002b3be-0d25-ec11-b6e6-000d3a4f0858 feedback_help_link_url: /answers/tags/187/azure-cosmos-db/ feedback_help_link_type: get-help-at-qna ms.service: azure-cosmos-db ms.subservice: nosql ms.reviewer: mjbrown ms.author: sasinnat author: sajeetharan description: Use Azure Cosmos DB Agent Kit prompts to review partition keys, optimize queries, and improve SDK code, then validate the recommendations. ms.topic: how-to ms.date: 2026-10-16T00:00:00.0000000Z ms.update-cycle: 180-days ms.collection: - ce-skilling-ai-copilot ai-usage: ai-assisted locale: en-us document_id: ee6c9995-2b41-737c-25fd-cb06e879d46f document_version_independent_id: ee6c9995-2b41-737c-25fd-cb06e879d46f updated_at: 2026-10-29T12:08:00.0000000Z original_content_git_url: https://github.com/MicrosoftDocs/nosql-docs-pr/blob/live/azure/cosmos-db/gen-ai/agent-kit/usage.md gitcommit: https://github.com/MicrosoftDocs/nosql-docs-pr/blob/d544fbd677e5c098756dbf81dcc8b6ff167255c1/azure/cosmos-db/gen-ai/agent-kit/usage.md git_commit_id: d544fbd677e5c098756dbf81dcc8b6ff167255c1 site_name: Docs depot_name: Learn.azure-nosql page_type: conceptual toc_rel: ../../toc.json word_count: 744 asset_id: cosmos-db/gen-ai/agent-kit/usage moniker_range_name: monikers: [] item_type: Content source_path: azure/cosmos-db/gen-ai/agent-kit/usage.md cmProducts: - https://authoring-docs-microsoft.poolparty.biz/devrel/cd668c2f-f5b3-4573-8ad1-019570e3e2db - https://authoring-docs-microsoft.poolparty.biz/devrel/fcc3cd4a-59ea-47a2-9cc1-784142a5a25d spProducts: - https://authoring-docs-microsoft.poolparty.biz/devrel/cc82e69d-afbe-4554-9f4c-6705fc860c42 - https://authoring-docs-microsoft.poolparty.biz/devrel/d7a55faf-a992-4e27-aa3a-eadc9830e778 platformId: ba1bd52b-077a-151f-689e-bcc3a9a51c37 --- # Use the Azure Cosmos DB Agent Kit - Azure Cosmos DB | Microsoft Learn Use the Azure Cosmos DB Agent Kit to get task-specific guidance from your AI coding assistant. Provide the code, data model, or workload information needed for the task, and validate the assistant's recommendations before applying them. ## Prerequisites - [Install the Agent Kit and verify skill discovery](setup#verify-skill-discovery). - Prepare sanitized code, sample documents, or query diagnostics relevant to your task. Don't share credentials, access tokens, connection strings, or sensitive document values. Replace sensitive values while preserving the structure needed for the review. ## Review a partition key Provide your proposed partition key, representative document shapes, common query filters, estimated write rates, expected data growth, and any tenant-size differences. Ask your assistant: ```text Use the Azure Cosmos DB Agent Kit to review my proposed partition key. Evaluate it against my query patterns, write distribution, cardinality, and expected data growth. Identify hot-partition and storage risks. Ask for missing workload information before recommending a key. Explain the trade-offs between suitable alternatives. ``` Expect recommendations tied to the workload you supplied, with assumptions and missing information called out. Validate the recommendation against representative data and traffic. Don't treat a proposed key as a measured scalability result. ## Optimize a query Provide the query, partition-key definition, indexing policy, representative document shapes, required result fields, and available request unit (RU) charges and query diagnostics. Ask your assistant: ```text Use the Azure Cosmos DB Agent Kit to review this query and indexing policy. Preserve the required results. Explain possible cross-partition work, unnecessary projections, and relevant indexing changes. Separate recommendations supported by the supplied diagnostics from hypotheses. Describe how I should compare RU charge and latency before and after a change. ``` Expect an explanation of each proposed change and its effect on query behavior. Test the original and revised queries against the same representative dataset and indexing state. Confirm equivalent results, and measure RU charge and latency across representative requests before claiming an improvement. ## Review SDK code Provide the SDK language and package version, client initialization, relevant database operations, authentication approach, and sanitized error diagnostics. Ask your assistant: ```text Use the Azure Cosmos DB Agent Kit to review this SDK code. Check client reuse, asynchronous operations, parameterized queries, pagination, authentication, retry behavior, and diagnostic logging. Respect the SDK's existing retry behavior. Explain each proposed change and provide tests or checks to validate it. Prefer Microsoft Entra ID authentication where the deployment supports it. ``` Expect recommendations that match your SDK and deployment environment. Run the relevant build and tests, check error and throttling behavior, and validate access permissions in a nonproduction environment before deploying changes. ## Best use cases Use the kit when you want help with: - Designing data models and choosing partition keys. - Reducing RU consumption and improving query performance. - Writing safer SDK code, including client reuse, retries, and error handling. - Choosing authentication, access, and security patterns. - Planning indexing strategies for common and vector workloads. - Setting throughput, autoscale, and scaling options. - Choosing consistency and global distribution settings. - Reviewing monitoring, diagnostics, and operational logging. - Applying design patterns for agentic workflows, change feed, and materialized views. - Configuring vector search, full-text search, and hybrid search. - Catching platform-specific gotchas before they reach production. ## Understand the assistant's limits Skill activation depends on your host's discovery and context-loading behavior. See [Agent Kit compatibility](compatibility) if the relevant guidance doesn't load. Installing skills doesn't, by itself, connect your assistant to a database. Unless you configure separate tools and permissions, the assistant works from the information you provide. Generated recommendations don't prove that a query was executed or that RU consumption improved. For current official documentation, you can also [connect your assistant to Microsoft Learn](/en-us/training/support/mcp). Documentation retrieval is separate from database access. ## AI tools Connect your coding agent to Microsoft Learn or use these task recipes in your assistant. For a compact index of the guides and their Markdown versions, use the [Agent Kit documentation index (`llms.txt`)](llms.txt). This index is a discovery aid, not a crawler policy or a guarantee that an assistant retrieves the articles. > > **[Connect your AI agent](/en-us/training/support/mcp-get-started)** Set up Microsoft Learn MCP in Visual Studio Code. > > **[Read as Markdown](/en-us/azure/cosmos-db/gen-ai/agent-kit/usage?accept=text/markdown)** Open a text version to copy into your assistant. > > **[Ask ChatGPT](https://chatgpt.com/?hint=search&q=Read%20https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fazure%2Fcosmos-db%2Fgen-ai%2Fagent-kit%2Fusage%20and%20help%20me%20choose%20an%20Agent%20Kit%20task%20recipe.%20Ask%20for%20missing%20context.%20Cite%20the%20article%20and%20state%20if%20you%20cannot%20access%20it.)** Choose a task recipe and identify the context it needs. > > **[Ask Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fazure%2Fcosmos-db%2Fgen-ai%2Fagent-kit%2Fusage%20and%20help%20me%20choose%20an%20Agent%20Kit%20task%20recipe.%20Ask%20for%20missing%20context.%20Cite%20the%20article%20and%20state%20if%20you%20cannot%20access%20it.)** Choose a task recipe and identify the context it needs. The external links send only a public article URL and a generic prompt. You might need to sign in. If the assistant can't retrieve the article, copy the relevant Markdown text instead. Don't add secrets or sensitive data to prompts.