---
layout: Conceptual
title: Set up 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/setup
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: Install Azure Cosmos DB Agent Kit skills in your AI coding assistant, verify skill discovery, and troubleshoot setup.
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: a38a5405-85c8-8600-703b-a0b91c904354
document_version_independent_id: a38a5405-85c8-8600-703b-a0b91c904354
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/setup.md
gitcommit: https://github.com/MicrosoftDocs/nosql-docs-pr/blob/d544fbd677e5c098756dbf81dcc8b6ff167255c1/azure/cosmos-db/gen-ai/agent-kit/setup.md
git_commit_id: d544fbd677e5c098756dbf81dcc8b6ff167255c1
site_name: Docs
depot_name: Learn.azure-nosql
page_type: conceptual
toc_rel: ../../toc.json
word_count: 781
asset_id: cosmos-db/gen-ai/agent-kit/setup
moniker_range_name: 
monikers: []
item_type: Content
source_path: azure/cosmos-db/gen-ai/agent-kit/setup.md
cmProducts:
- https://authoring-docs-microsoft.poolparty.biz/devrel/cd668c2f-f5b3-4573-8ad1-019570e3e2db
spProducts:
- https://authoring-docs-microsoft.poolparty.biz/devrel/cc82e69d-afbe-4554-9f4c-6705fc860c42
platformId: 702bbc08-b1f8-e01c-85ee-9fa512e32c53
---

# Set up the Azure Cosmos DB Agent Kit - Azure Cosmos DB | Microsoft Learn

Install the Azure Cosmos DB Agent Kit to give your AI coding assistant guidance on data modeling, partition keys, queries, and SDK usage. Choose one installation method for your host, and then verify that the assistant can discover the installed skill.

## Prerequisites

- An AI coding assistant that supports Agent Skills or one of the plugin formats listed in [Agent Kit compatibility](compatibility).
- Node.js with npm and npx installed if you use the skills CLI.
- Access to GitHub and the package registry used by your installation method.

You don't need an Azure subscription to install the skills or review code. Connecting separate tools to a database requires their own authentication and permissions. Don't include credentials or production data in setup prompts.

## Install with the skills CLI

Use this method to select the skills and target assistants interactively:

```bash
npx skills add AzureCosmosDB/cosmosdb-agent-kit
```

Follow the CLI prompts to choose your target assistant and installation scope. Use your host's documented project or user-level scope, and avoid installing the same skill through multiple methods in the same host.

For host-specific installation methods, use one of the following options instead.

## Install with an agent-specific method

These commands follow the [Agent Kit installation instructions](https://github.com/AzureCosmosDB/cosmosdb-agent-kit#installation). Host versions and plugin availability can change. Check your host's prerequisites before installation.

### Agent Package Manager (APM)

If you already use APM to manage agent dependencies, run:

```bash
apm install AzureCosmosDB/cosmosdb-agent-kit
```

### GitHub Copilot CLI

In a Copilot CLI session, add the marketplace and install the plugin:

```text
/plugin marketplace add AzureCosmosDB/cosmosdb-agent-kit
/plugin install cosmosdb@cosmosdb-agent-kit
```

### Claude Code

In a Claude Code session, install from the official plugin marketplace:

```text
/plugin install cosmosdb@claude-plugins-official
```

### Gemini CLI

With Gemini CLI installed, run:

```bash
gemini extensions install https://github.com/AzureCosmosDB/cosmosdb-agent-kit
```

### OpenAI Codex

Add the marketplace with the Codex CLI:

```bash
codex plugin marketplace add AzureCosmosDB/cosmosdb-agent-kit
```

Then install the Agent Kit from the Plugins Directory in the ChatGPT desktop app, as described in the [repository's Codex instructions](https://github.com/AzureCosmosDB/cosmosdb-agent-kit#openai-codex-cli).

### Grok Build

With Grok Build installed, add the marketplace, install the plugin, and inspect the discovered skills:

```bash
grok plugin marketplace add AzureCosmosDB/cosmosdb-agent-kit
grok plugin install cosmosdb --trust
grok inspect
```

The `--trust` option authorizes activation of the remote plugin. Review the source before trusting it.

### Kimi Code CLI

In a Kimi Code CLI session, install from GitHub and reload:

```text
/plugins install https://github.com/AzureCosmosDB/cosmosdb-agent-kit
/reload
```

### Cursor and other Agent Skills-compatible hosts

Use the skills CLI and select your host. If you need a plugin-specific installation, consult the [repository's plugin manifests](https://github.com/AzureCosmosDB/cosmosdb-agent-kit#per-agent-plugin-directories) and your host's current plugin instructions.

## Verify skill discovery

1. If your host requires it, reload the assistant or start a new session after installation.
2. Open the project where you installed the skills. For user-level installations, confirm that your host can discover skills in that scope.
3. Check the host's installed skills or plugins view, if available, for `cosmosdb-best-practices`.
4. Try this prompt with a sanitized code sample or data model:

    ```text
    Use the installed cosmosdb-best-practices skill to review my Azure Cosmos DB code.
    Identify the relevant guidance, explain your recommendations, and state what
    information you need before suggesting changes.
    ```

Check the host's skill-loading indicators or logs, if available. A response that mentions Azure Cosmos DB doesn't, by itself, prove that the skill loaded.

## Troubleshoot installation

| Symptom | What to check |
| --- | --- |
| `npx` isn't found. | Install Node.js with npm, then reopen your terminal so it picks up the updated path. |
| A plugin command isn't recognized. | Confirm that you're using the correct host and a version that supports the documented plugin method. Otherwise, use the skills CLI if your host supports Agent Skills. |
| Installation succeeds, but the skill isn't discovered. | Check the selected assistant, installation scope, workspace, and host trust settings. Reload the host if its instructions require it. |
| The assistant loads too much context. | Use on-demand skill loading or provide only task-relevant guidance. See [context-loading considerations](compatibility#context-loading-considerations). |
| A registry or download request fails. | Read the command's error output and check network, proxy, and registry access before retrying. |

## AI tools

Connect your coding agent to Microsoft Learn or bring these installation instructions into 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/setup?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%2Fsetup%20and%20help%20me%20install%20the%20Agent%20Kit.%20Ask%20which%20assistant%20I%20use.%20Cite%20the%20article%20and%20state%20if%20you%20cannot%20access%20it.)** Get installation guidance for your coding assistant.
> 
> **[Ask Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fazure%2Fcosmos-db%2Fgen-ai%2Fagent-kit%2Fsetup%20and%20help%20me%20install%20the%20Agent%20Kit.%20Ask%20which%20assistant%20I%20use.%20Cite%20the%20article%20and%20state%20if%20you%20cannot%20access%20it.)** Get installation guidance for your coding assistant.

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. These links don't install skills or grant database access.