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.
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
Build a Weather Agent with AG2 and connect it to CopilotKit's chat UI. Users ask the agent for the weather in a city. AG2's AGUIStream sends the agent's events to the UI over the AG-UI protocol.
Pick the path that fits you:
- To run the AG2 sample, follow Getting started.
- To generate a starter project, use the AG2 Bootstrap Template.
- To connect an AG2 agent that you already have, go to Connect your own AG2 agent.
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 initFollow 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 to 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 selectproject 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 syncSet 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 backendThe 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 devThe 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
Enter a name to sign in, then ask a question:
What's the weather in London?Weather in TokyoWhat'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 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.
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"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-6-luna"),
)
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:
from fastapi import FastAPI
from ag2 import Agent
from ag2.ag_ui import AGUIStream
from ag2.config import OpenAIResponsesConfig
agent = Agent(
name="support_bot",
prompt="You help users with billing questions.",
config=OpenAIResponsesConfig(model="gpt-6-luna"),
)
stream = AGUIStream(agent)
app = FastAPI()
app.mount("/chat", stream.build_asgi())Register the agent in your Copilot Runtime with new HttpAgent({ url: "http://localhost:8000/chat" }). Then the agent answers in the CopilotKit UI. See the AG2 AG-UI integration docs for supported protocol events, interrupts, capabilities, and shared-state details.
What's next?
How is this guide?