# Quickstart

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

## Start with your coding agent [#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.

<PageAgentPrompt />

## Introduction [#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](#getting-started).
- To generate a starter project, use the [AG2 Bootstrap Template](#ag2-bootstrap-template).
- To connect an AG2 agent that you already have, go to [Connect your own AG2 agent](#connect-your-own-ag2-agent).

<Callout type="info">
  CopilotKit consumes AG-UI 1.0 protocol events streamed by AG2 (1.1.2 or newer) over HTTP. See the <a href="https://docs.ag2.ai/docs/user-guide/ag-ui/" target="_blank">AG2 AG-UI integration docs</a>.
</Callout>

## AG2 Bootstrap Template [#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 [#prerequisites]

Before you begin, you'll need the following:

- **Python 3.10 to 3.14** 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> 20.9 or newer
- <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 [#getting-started]

<Steps>
    <Step>
        ### Set up CopilotKit Intelligence [#set-up-copilotkit-intelligence]

        <SignupLink surface="docs_ag2_quickstart_step1">Sign in to cloud-hosted Intelligence</SignupLink>. 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.
    </Step>

    <Step>
        ### Clone the AG2 Samples Repository [#clone-the-ag2-samples-repository]

        ```bash
        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`.
    </Step>
    <Step>
        ### Set Up the AG2 Backend [#set-up-the-ag2-backend]

        #### Install the dependencies: [#install-the-dependencies]

        ```bash
        uv sync
        ```

        #### Set your `OPENAI_API_KEY` and `AUTH_SECRET`: [#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.

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

        #### Launch the AG2 weather agent: [#launch-the-ag2-weather-agent]

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

        <Callout type="warn">
            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](/ag2/auth).
        </Callout>
    </Step>
    <Step>
        ### Talk to your agent [#talk-to-your-agent]

        Enter a name to sign in, then ask a question:

        - `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](/ag2/multi-agent/subagents) (`ClothingAdvisor`, `TripPlanner`) | "What should I wear in Oslo?" |
        | [Interrupts](/ag2/human-in-the-loop#approve-a-tool-call-with-interrupts) (`save_favorite_city` waits for approval) | "Save Lisbon to my favorites" |
        | [Shared state](/ag2/shared-state) (the favorites panel) | Save a city, then watch the panel |
        | Capabilities | `curl localhost:8000/weather` |

        <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>

    <Step>
        ### Open Inspector and confirm setup [#open-inspector-and-confirm-setup]

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

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

        More detail: [Inspector](/ag2/inspector).
    </Step>

</Steps>

---

## Connect your own AG2 agent [#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`:

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

```python title="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-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:

```python title="run_ag_ui.py"
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](/ag2/backend/copilot-runtime) with `new HttpAgent({ url: "http://localhost:8000/chat" })`. Then the agent answers in the CopilotKit UI. See the <a href="https://docs.ag2.ai/docs/user-guide/ag-ui/" target="_blank">AG2 AG-UI integration docs</a> for supported protocol events, interrupts, capabilities, and shared-state details.

## What's next? [#whats-next]

<Cards>
  <Card
    title="Implement Human in the Loop"
    description="Allow your users and agents to collaborate together on tasks."
    href="/ag2/human-in-the-loop"
    icon={<UserIcon />}
  />
</Cards>
