Quickstart - Copilotkit

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.

<Callout type="info"> CopilotKit consumes AG-UI protocol events streamed by AG2 over{" "} <code>/chat</code>. See the{" "} <a href="https://docs.ag2.ai/latest/docs/user-guide/ag-ui/" target="_blank"> AG2 AG-UI integration docs </a> . </Callout>

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.

bash

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
<a href="https://docs.astral.sh/uv/getting-started/installation/" target="_blank"

uv </a> (for Python dependency management)
<a href="https://nodejs.org/en/download" target="_blank">Node.js</a> 18.18.0 or newer (specifically: ^18.18.0 || ^19.8.0 || >= 20.0.0)
<a href="https://pnpm.io/installation" target="_blank"> pnpm </a> (for frontend package management)
<a href="https://platform.openai.com/api-keys" target="_blank"> OpenAI API key </a>

Getting started

<Steps> <Step> ### Clone the AG2 Samples Repository

    ```bash
    git clone https://github.com/ag2ai/ag2-samples.git
    cd ag2-samples
    ```
</Step>
<Step>
    ### Set Up the AG2 Backend

    #### Install the dependencies:

    ```bash
    uv sync
    ```

    #### Set your `OPENAI_API_KEY`:

    ```sh
    export OPENAI_API_KEY="your_openai_api_key"
    ```

    #### Launch the AG2 weather agent:

    ```bash
    uv run python weather.py
    ```
    The backend server will start at http://localhost:8000 and serve the agent at `/weather`.
</Step>
<Step>
    ### 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:

    ```bash
    cd ui
    pnpm install
    pnpm dev
    ```

    The frontend application will start at http://localhost:3000.
</Step>
<Step>
    ### 🎉 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?
    ```

    <Callout type="info">
        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.
    </Callout>
</Step>

</Steps>

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.