From an Empty Folder to an AI Agent: Meet create-cosmos-agent

The first few minutes of a new AI project often feel productive. Create a chat endpoint, connect a model, send a prompt, and display the answer.

Then the real questions arrive.

Where should the agent store memory? How do we keep one customer’s data away from another? How do we trace the source of an answer? What happens when an action requires approval? How do we test the application locally before creating cloud resources? And how do we move to Azure without rebuilding the project?

Those questions inspired me to build create-cosmos-agent, an open-source CLI for creating production-oriented TypeScript AI agent applications with an Azure Cosmos DB path.

My goal was simple: make the first command easy without hiding the decisions that matter later.

Watch the two-minute demo

In the video, I start with an empty folder, create an agent, launch the application, save a customer preference, retrieve it with a citation, and then switch users to show that the memory remains isolated.

From an Empty Folder to an AI Agent: Meet create-cosmos-agent

The entire experience starts with one command:

npx create-cosmos-agent@latest bootstrap my-agent --yes    

Then,

 cd my-agent    
 npm run dev    

That is enough to open a working API and React application at http://localhost:5173.

The default experience is deliberately simple. It uses a deterministic mock AI provider, local development identity, and in-memory storage. You do not need an Azure subscription, a model key, or Docker for this first run.

This makes it possible to explore the application before making decisions about models, credentials, capacity, or cloud resources.

One command should create more than a chat box

A starter is most useful when it creates the parts developers usually have to add after the demo.

The generated project includes:

• a TypeScript API and React web experience;
• agent memory and vector retrieval contracts;
• tenant and user isolation;
• citations and retrieval traces;
• approval-gated actions;
• multiple model-provider adapters;
• diagnostics and request-charge tracking;
• unit, security, and cost tests;
• Docker, Bicep, Azure Container Apps, and Azure Developer CLI files;
• Microsoft Entra ID and Managed Identity production paths.

These pieces share the same application contracts across local development and Azure. Moving toward production should be a change in configuration and infrastructure, not a rewrite of the agent.

A small scenario that reveals an important design

Imagine a support agent that needs to remember how a customer wants to receive deployment notifications.

In the generated application, I save this preference:

The customer prefers deployment notifications in Microsoft Teams.

Then I ask:

What notification channel does this customer prefer?

The agent retrieves the stored memory and attaches a citation. The useful part is not only the answer. The application can show which memory was selected and the tenant, user, timestamp, embedding version, and correlation information associated with the retrieval.

Now I change the local user from user-demo to user-other and ask the same question.

It is a short demo, but it exercises a boundary that matters in real applications: identity scope travels through the request context, data model, partition strategy, write path, and retrieval path. It is not just a filter added to the interface.

Local first does not mean production later

Local development should be fast, but it should also teach the shape of the production system.

Developers can begin with in-memory storage for the shortest path. When durable local behavior matters, the project can use the Azure Cosmos DB Linux vNext emulator:

The guided setup lets developers choose the scenario, AI provider, authentication mode, storage option, capacity model, and web experience. Selecting Cosmos DB with the emulator creates the local configuration needed to start the emulator, initialize the database and containers, and run the application.

The production path keeps the same application interfaces while replacing local adapters:

The project does not pretend that production is only a deployment command. Identity configuration, model availability, regional quota, role assignments, Cosmos DB capacity, and cost still require deliberate choices. The CLI makes those decisions visible and provides a readiness check before deployment.

Azure Cosmos DB guidance where developers need it

Generated projects now include an on-demand cosmosdb-best-practices Agent Skill based on the open-source Azure Cosmos DB Agent Kit.

When a coding agent works on Cosmos DB code in the project, the skill provides focused guidance for:

• data modeling and partition-key design;
• point reads, bounded queries, and continuation-token pagination;
• client reuse, retries, diagnostics, and optimistic concurrency;
• indexing and throughput choices;
• vector policies and tenant-scoped vector search;
• Managed Identity and production operations.

The guidance is loaded when it is relevant instead of placing a large body of instructions into every prompt. This keeps the developer experience focused while making Cosmos DB practices available at the point of implementation.

Guardrails developers can run

The generated application includes two commands that help turn architectural intentions into checks.

Run:

 npx create-cosmos-agent@latest doctor .    

doctor looks for configuration and security problems, including unsafe production authentication, secret handling, query patterns, and tenant partitioning concerns.

For the complete project gate, run:

  npx create-cosmos-agent@latest validate .    

validate checks generated files and runs the project’s type checks, build, tests, and Bicep validation. Generated scenarios include security tests for behaviors such as tenant isolation and approval boundaries, not only unit tests for happy paths.

The aim is not to claim that a generated project is automatically ready for every production workload. The aim is to give teams a stronger and more visible starting point.

Start with the scenario, not the plumbing

Different agents need different application shapes, so the CLI includes several working starters:

• conversational agents with memory and safe actions;
• document-grounded RAG with vector retrieval and citations;
• customer-support agents with ticket workflows;
• supervised multi-agent orchestration;
• lightweight, tenant-safe agent memory;
• event-driven workers with idempotency and retry contracts.

You can see the available choices with:

npx create-cosmos-agent@latest list    

Or use the guided experience:

npx create-cosmos-agent@latest wizard my-agent    

Help shape what comes next

create-cosmos-agent is open source, and this is an invitation to try it not a claim that every design decision is finished.

I would especially value feedback from developers building real agent workloads:

• Was the first run as simple as expected?
• Which generated parts did you keep or replace?
• Which Cosmos DB decisions still felt difficult?
• What scenario should become the next starter?
• Where should the CLI provide more guidance and where should it stay out of the way?

Try it with:

  npx create-cosmos-agent@latest bootstrap my-agent --yes    

Then explore the project:

• View the source on GitHub
• Install from npm
• Report an issue or share feedback
• Submit a project to the community showcase

The easiest first command should still lead toward sound engineering. I hope create-cosmos-agent helps more developers spend their time on the agent experience they want to create, while starting with the memory, identity, data, testing, and deployment foundations they will need along the way.

 About Azure Cosmos DB 

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. 

To stay in the loop on Azure Cosmos DB updates, follow us on X, YouTube, and LinkedIn.