Quickstart
Turn your Microsoft Agent Framework agent into an agent-native application in 10 minutes.
Start with your coding agent
Use this prompt to connect your Microsoft Agent Framework agent to CopilotKit and verify a working conversation. Your coding agent will follow this guide in your project, or you can work through the manual steps below.
Open your coding agent in your project's folder, or in an empty folder for a new app.This runs in a coding agent on your computer.
Prerequisites
Before you begin, you'll need the following:
- An OpenAI API key for the .NET starter
- .NET 9.0 SDK or later, for a .NET agent
- Python 3.12 or later and uv, for a Python agent
- Node.js 20+
- Your favorite package manager (npm, pnpm, yarn, or bun)
Getting started
Set up CopilotKit Intelligence
Sign in to cloud-hosted Intelligence. You will connect the app after you create it below.
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 createThe CLI walks you through:
- Project name
- CopilotKit Intelligence: persistent threads and the Inspector. Choose Yes for a project that is wired to Intelligence. Choose 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 installManual setup
If you have issues with automatic Python setup, you can manually install the agent dependencies:
npm run install:agent
# or manually:
cd agent
uv syncConfigure your environment
Create a .env file inside the agent folder with one of the following configurations:
OPENAI_API_KEY=sk-...your-openai-key-here...
OPENAI_CHAT_MODEL_ID=gpt-6-lunaAZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=gpt-6-luna
# Optional when az login is unavailable:
# AZURE_OPENAI_API_KEY=...Start the development server
npm run devThis will start both the Next.js UI (port 3000) and agent server (port 8000) concurrently.
Start chatting
Open http://localhost:3000 and open the sidebar. Send one of these messages, and the agent replies in the sidebar:
- Can you tell me a joke?
- Can you help me understand AI?
- What do you think about .NET?
Agent Connection Issues
- If you see "I'm having trouble connecting to my tools", make sure:
- The agent is running on port 8000
- Your OpenAI API key is set: in .NET user secrets for a .NET agent, or in the
.envfile of a Python agent - Both servers started successfully (check terminal output)
OpenAI API Key Issues
- If the .NET 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:
- .NET agent:
agent/Properties/launchSettings.json- UpdateapplicationUrl - Python agent:
agent/.env- SetAGENT_PORT - Frontend:
.env- SetAGENT_URLto the new agent URL (read insrc/agent.ts)
- .NET agent:
Open Inspector and confirm setup
On localhost, click the Inspector button in the corner of the app.
- Open Inspect, then Agent. Your agent is listed.
- Send a chat message. Open Inspect, then AG-UI Events. Events are moving.
- Open Rich Threads. The list is unlocked (Intelligence is on), or locked with Copy setup prompt (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.
Add frontend tools
Give your agent the ability to call frontend tools, directly updating your application.
How is this guide?