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.