Quickstart

Turn your Microsoft Agent Framework agent into an agent-native application in 10 minutes.

Build agents that get smarter with every use.

Rich Threads keep messages, generative UI, and tool activity available across sessions and devices.

Learning turns real usage into skills that improve your agent.

Build a new agent or bring one you already have. Any frontend, any backend.

Prerequisites#

Before you begin, you'll need the following:

An OpenAI API key for the .NET starter
.NET 9.0 SDK or later
Node.js 20+
Your favorite package manager (npm, pnpm, yarn, or bun)

Getting started#

Create a free account#

Sign up for a free developer account for CopilotKit Intelligence to get a license key. You'll use it later to enable persistent threads and the inspector.

Choose your starting point#

You can either start fresh with our starter template or integrate CopilotKit into your existing Microsoft Agent Framework agent.

Run our CLI#

npx copilotkit@latest create

The CLI walks you through:

Project name
CopilotKit Intelligence — persistent threads and the inspector. Choose Yes to scaffold a project pre-wired for the platform (the CLI walks you through sign-up, or you can create an account first), or No for a standard Microsoft Agent Framework setup.
Framework — pick Microsoft Agent Framework (.NET) or Microsoft Agent Framework (Python).

Install dependencies#

The starter includes a postinstall script that automatically installs both your npm and agent dependencies.

npm install

Manual setup

If you have issues with automatic .NET package installation, you can manually restore them:

npm run install:agent

If you have issues with automatic Python setup, you can manually install the agent dependencies:

npm run install:agent
# or manually:
cd agent
uv sync

Configure your environment#

The .NET starter uses OpenAI. Save your API key as a .NET user secret:

cd agent
dotnet user-secrets set OPENAI_API_KEY "<your-openai-api-key>"
cd ..

Want to use a different model provider?

Edit agent/Program.cs to use Azure OpenAI or another Microsoft Agent Framework model provider.

Create a .env file inside the agent folder with one of the following configurations:

agent/.env (OpenAI)

OPENAI_API_KEY=sk-...your-openai-key-here...
OPENAI_CHAT_MODEL_ID=gpt-5.4-mini

agent/.env (Azure OpenAI)

AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=gpt-5.4-mini
# Optional when az login is unavailable:
# AZURE_OPENAI_API_KEY=...

Start the development server#

npm run dev

pnpm dev

yarn dev

bun dev

This will start both the Next.js UI (port 3000) and agent server (port 8000) concurrently.

🎉 Start chatting!#

Your AI agent is now ready to use! Try asking it some questions:

Can you tell me a joke?

Can you help me understand AI?

What do you think about .NET?

Troubleshooting

Agent Connection Issues

If you see "I'm having trouble connecting to my tools", make sure:
- The C# agent is running on port 8000
- Your OpenAI API key is set via .NET user secrets
- Both servers started successfully (check terminal output)

OpenAI API Key Issues

If the agent fails with "OPENAI_API_KEY not found":

cd agent
dotnet user-secrets set OPENAI_API_KEY "<your-openai-api-key>"

.NET SDK Issues

Verify .NET SDK is installed:

dotnet --version  # Should be 9.0.x or higher

Restore packages manually if needed:
```
cd agent
dotnet restore
dotnet run
```

Port Conflicts

If port 8000 is already in use, you can change it in:
- agent/Properties/launchSettings.json - Update applicationUrl
- src/app/api/copilotkit/route.ts - Update the remote endpoint URL

Open Inspector and confirm setup#

On localhost, click the Inspector button in the corner of the app.

Open Agents, then Agent. Your agent is listed.
Send a chat message. Open Agents, then AG-UI Events. Events are moving.
Open Threads. The list is unlocked (Intelligence is on), or locked with Enable Intelligence (Intelligence is off).

More detail: Inspector.

What's next?#

Now that you have your basic agent setup, explore these advanced features:

Implement Human in the Loop

Allow your users and agents to collaborate together on tasks.

Utilize Shared State

Learn how to synchronize your agent's state with your UI's state, and vice versa.

Add some generative UI

Render your agent's progress and output in the UI.

Setup frontend actions

Give your agent the ability to call frontend tools, directly updating your application.