Quickstart

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

Prerequisites#

Before you begin, you'll need the following:

A GitHub Personal Access Token (for GitHub Models API - free AI access)
.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 on our Enterprise Intelligence Platform to get a license key. You'll use it later to enable persistent threads, observability, 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.

Start from scratch

Get started quickly with our ready-to-go starter application.

Use an existing agent

I already have a Microsoft Agent Framework agent and want to add CopilotKit.

Run our CLI#

npx copilotkit@latest create

The CLI walks you through:

Project name
Enterprise Intelligence Platform — persistent threads, observability, 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 starter template uses GitHub Models API for free access to AI models. Set up your GitHub token:

First, get your GitHub token (requires GitHub CLI):

gh auth token

Then navigate to the agent directory and set it as a user secret:

cd agent
dotnet user-secrets set GitHubToken "$(gh auth token)"
cd ..

Want to use a different model provider?

The starter template is configured to use GitHub Models (free), but you can modify it to use:

OpenAI directly
Azure OpenAI
Any other model supported by Microsoft Agent Framework

Check the agent/Program.cs file to customize the model configuration.

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
# If you are not relying on az login:
# 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 GitHub token is set correctly via user secrets
- Both servers started successfully (check terminal output)

GitHub Token Issues

If the agent fails with "GitHubToken not found":

cd agent
dotnet user-secrets set GitHubToken "$(gh auth token)"

.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

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.