Quickstart

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.

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.

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 1.0 protocol events streamed by AG2 (1.1.2 or newer) over HTTP. 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.14 for running the AG2 backend
uv (for Python dependency management)
Node.js 20.9 or newer
pnpm (for frontend package management)
OpenAI API key

Getting started#

Set up CopilotKit Intelligence#

Sign in to cloud-hosted Intelligence. Cloud-hosted 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` and `AUTH_SECRET`:

The sample serves the agent only to a signed-in user. AUTH_SECRET signs and verifies the user's access token, so the backend and the frontend must use the same value. Any long random string works.

export OPENAI_API_KEY="your_openai_api_key"
export AUTH_SECRET="a-long-random-string"

Launch the AG2 weather agent:

uv run python -m backend

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
AUTH_SECRET="a-long-random-string" pnpm dev

The frontend application will start at http://localhost:3000. Use the same AUTH_SECRET as the backend.

The sample's sign-in is a demonstration: it accepts any name and keeps the token in localStorage. Replace verify_access_token in backend/auth.py and the token route in the UI before reusing the pattern. See Authentication.

🎉 Talk to your agent!#

Congrats! You've successfully integrated an AG2 Agent chatbot into your application. Enter a name to sign in, then try asking a few questions:

What's the weather in London?

Weather in Tokyo

What's the weather here?

The sample also shows the AG-UI 1.0 features next to the chat:

Feature	Try it
Sub-agents (`ClothingAdvisor`, `TripPlanner`)	"What should I wear in Oslo?"
Interrupts (`save_favorite_city` waits for approval)	"Save Lisbon to my favorites"
Shared state (the favorites panel)	Save a city, then watch the panel
Capabilities	`curl localhost:8000/weather`

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.

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

More detail: Inspector.

Connect your own AG2 agent#

The samples repository is a ready-made example. To expose any AG2 agent over AG-UI, install AG2 (1.1.2+) with the AG-UI and OpenAI extras and wrap the agent in AGUIStream:

pip install "ag2[ag-ui,openai]>=1.1.2"

run_ag_ui.py

from fastapi import FastAPI, Header
from fastapi.responses import StreamingResponse

from ag2 import Agent
from ag2.ag_ui import AGUIStream, RunAgentInput
from ag2.config import OpenAIResponsesConfig

agent = Agent(
    name="support_bot",
    prompt="You help users with billing questions.",
    config=OpenAIResponsesConfig(model="gpt-5.5"),
)

stream = AGUIStream(agent)
app = FastAPI()

@app.post("/chat")
async def run_agent(
    message: RunAgentInput,
    accept: str | None = Header(None),
) -> StreamingResponse:
    return StreamingResponse(
        stream.dispatch(message, accept=accept),
        media_type=accept or "text/event-stream",
    )

If you don't need custom auth, logging, or middleware around the endpoint, AGUIStream.build_asgi() builds a ready-to-mount ASGI endpoint instead: