CopilotKit

Quickstart

Turn your AG2 Agents into an agent-native application in 5 minutes.

Start with your coding agent#

Use this prompt to connect your AG2 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.

Introduction#

This quickstart guide shows how to build a Weather Agent using AG2 and CopilotKit. In just minutes, you'll have a working application where users can ask for real-time weather conditions in any city worldwide — powered by AG2's AGUIStream over the AG-UI protocol and rendered with CopilotKit's chat UI.

CopilotKit consumes AG-UI protocol events streamed by AG2 over /chat. See the AG2 AG-UI integration docs.

AG2 Bootstrap Template#

If you prefer a generated starter instead of cloning the repo, use the CopilotKit bootstrap template and select AG2 during setup. This wires up an AG2 backend over AG-UI and a ready-to-run frontend.

npx copilotkit@latest init

Follow the prompts to pick AG2 and the features you want, then run the install/start commands it prints.

Prerequisites#

Before you begin, you'll need the following:

  • Python 3.10–3.13 for running the AG2 backend
  • uv (for Python dependency management)
  • Node.js 18.18.0 or newer (specifically: ^18.18.0 || ^19.8.0 || >= 20.0.0)
  • pnpm (for frontend package management)
  • OpenAI API key

Getting started#

Set up CopilotKit Intelligence#

Sign in to managed Intelligence. Managed setup uses a server-side project API key and does not issue COPILOTKIT_LICENSE_TOKEN. You will connect the app after you clone it below.

Clone the AG2 Samples Repository#

git clone https://github.com/ag2ai/ag2-samples.git
cd ag2-samples
npx copilotkit@latest project select

project select creates or selects an Intelligence project and writes its server-side API key to .env as CPK_INTELLIGENCE_API_KEY.

Set Up the AG2 Backend#

Install the dependencies:

uv sync

Set your OPENAI_API_KEY:

export OPENAI_API_KEY="your_openai_api_key"

Launch the AG2 weather agent:

uv run python weather.py

The backend server will start at http://localhost:8000 and serve the agent at /weather.

Set Up the CopilotKit UI#

The last step is to use CopilotKit's UI components to render the chat interaction with your agent.

In a new terminal:

cd ui
pnpm install
pnpm dev

The frontend application will start at http://localhost:3000.

🎉 Talk to your agent!#

Congrats! You've successfully integrated an AG2 Agent chatbot into your application. Try asking a few questions:

What's the weather in London?
Weather in Tokyo
What's the weather here?

Asking "What's the weather here?" will use your browser's location if you allow it. If location access is denied, the agent will ask you for a city name instead.

Open Inspector and confirm setup#

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

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

More detail: Inspector.

What's next?#

You've now got a Weather Agent running with CopilotKit! This demonstrates how quickly you can build practical AI applications by combining AG2's AGUIStream with CopilotKit's user interface components.

👤

Implement Human in the Loop

Allow your users and agents to collaborate together on tasks.