Anmol Baranwal

for CopilotKit

Posted on Feb 26

Give Your AG2 Agents a UI with AG‑UI and CopilotKit

#programming #webdev #frontend #backend

Agent frameworks have become increasingly capable at reasoning, orchestration and tool execution. But most of them still operate as isolated systems.

AG2 (formerly AutoGen) changes that. It provides a shared runtime where specialized agents with defined roles, tools and conversation patterns can collaborate as one coordinated team across models and even frameworks.

But orchestration alone isn’t the same as shipping an interactive experience. Every application ends up building custom protocols and UI wiring to observe runs, show tool progress and capture user actions during execution.

AG-UI (Agent-User Interaction Protocol) defines that interaction contract. It standardizes how agent activity is streamed, so any frontend can stay synchronized in real time.

Today, AG2 integrates with AG‑UI and CopilotKit to bring agent orchestration into real applications.

You can refer to the docs and try the interactive AG-UI Dojo if you want to explore it yourself.

Let’s break down how these layers fit together, the end-to-end integration flow and what this unlocks for agent builders.

AG2: Runtime for Agent Teams

AG2 (formerly AutoGen) is an open-source programming framework built around multi-agent collaboration. You define specialized agents, wire tools and run structured conversations to solve tasks.

Instead of a single monolithic loop, AG2 treats agents as composable actors that collaborate through shared context.

At its core is ConversableAgent, the primitive that defines an agent’s role, reasoning model and tool access while handling message exchange.

from autogen import ConversableAgent, LLMConfig
from dotenv import load_dotenv
import os
load_dotenv()

# Create LLM configuration first
llm_config = LLMConfig({
  "api_type": "openai",
  "model": "gpt-5-mini",
  "api_key": os.getenv("OPENAI_API_KEY"),
})

# Create the agent
lesson_planner = ConversableAgent(
    name="planner_agent",
    system_message="You are a lesson planner for a fourth grade class.",
    description="Creates lesson plans.",
    llm_config=llm_config,
)

Agents can be organized into coordinated workflows using built-in patterns such as sequential flows, group conversations, nested calls and human-in-the-loop checkpoints.

In practice, you might model a planner, executor and reviewer as distinct agents: each with its own role and tools and let AG2 manage how they interact over multiple turns.

auto_selection = AutoPattern(
    agents=[teacher, lesson_planner, lesson_reviewer],
    initial_agent=lesson_planner,
    group_manager_args={"llm_config": llm_config},
)

response = run_group_chat(
    pattern=auto_selection,
    messages="Introduce students to the solar system.",
    max_rounds=20,
)

response.process()

This allows backend behavior to evolve by assembling agents differently, rather than rewriting control logic for every new workflow.

AG-UI integration currently wraps a single ConversableAgent. Multi-agent patterns (group chat, delegation, nested flows) still run inside AG2, but are exposed through a unified interaction surface.

Staged or multi-agent UX can be modeled using context variables. The pattern is covered in the integration section.

Read all the basic concepts involved in the docs and check the example repo, which includes many examples.

The Gap: Orchestration Without an Application Contract

Even if multi-agent logic is portable, it does not automatically become app-portable.

In a production application, the UI needs a stable runtime contract for:

Streaming messages and partial results.
Tool lifecycle (start → progress → finish/fail).
State snapshots and updates while the run is still executing.
Human-in-the-loop actions that can steer or interrupt a run

AG2 manages delegation, shared context and orchestration internally. But it does not define a standard event/state interface for how that execution is exposed to a frontend.

Without that contract, every AG2 app ends up inventing its own WebSocket/SSE payload shapes and UI mapping rules. Integration becomes tightly coupled glue code instead of a reusable interaction layer.

This is where AG-UI Protocol fits.

AG-UI: The Execution & Interaction Layer

AG-UI (Agent–User Interaction Protocol) is an event-based protocol that standardizes the live interaction stream between an agent runtime and an application.

During a run, the backend emits a stream of structured event types. The frontend consumes that stream and can send compatible interaction events back.

This matters because AG2 already manages multi-agent coordination internally. What AG-UI defines is how that coordination becomes observable and interactive at the application boundary.

Instead of every app inventing custom payload formats, AG-UI defines a small set of self-describing JSON event types.

Each event includes a clear type and structured payload. For example:

TEXT_MESSAGE_CONTENT : event streams LLM tokens
TOOL_CALL_START/END : convey function call progress
STATE_DELTA : carries JSON Patch deltas to sync state

In practice, AG‑UI standardizes:

Message streaming
Tool lifecycle events (start → progress → finish / fail)
State snapshots and incremental updates
User interaction events (clicks, form submits, confirmations)

Because the stream is standard and ordered, the frontend can reliably interpret what the backend is doing and render progress in real time.

The result is decoupling. The backend doesn’t need to know how the UI renders progress and the UI doesn’t need to understand internal orchestration logic.

Here, AG-UI uses Server-Sent Events (SSE) over HTTP as its primary transport. The AG2 integration serves a text/event-stream response per run.

In AG2, this protocol is implemented via AGUIStream, which wraps a ConversableAgent and exposes it as an ASGI endpoint that streams AG-UI events.

Explore the full event specification in the AG-UI documentation and implementation details in the AG2 user guide, including best practices for when to adopt this integration.

How CopilotKit wires AG2 to AG-UI

On the backend, AG2 exposes agent runs through an AG-UI-compatible endpoint using AGUIStream. That endpoint streams standardized AG-UI events for the lifecycle of a run.

CopilotKit acts as that client and UI runtime. It connects to the AG‑UI endpoint (via @ag-ui/client), subscribes to the event stream, renders agent activity inside your application and forwards user actions back into the same execution loop.

The wiring is straightforward:

Your backend runs an AG2 agent workflow
AGUIStream wraps the agent and translates execution into AG-UI events
Those events are exposed through an AG-UI endpoint over SSE
CopilotKit connects and subscribes to the live event stream
Agent messages, tool progress and state updates are rendered in the UI
User interactions are sent back over AG-UI into the same AG2 run

The same endpoint can be consumed by any other AG-UI-compatible client. At a high level, the full interaction loop looks like this:

AG2 Runtime (multi-agent orchestration)
│
│ executes ConversableAgents
│ manages delegation + shared state
│ invokes tools
▼
AG2 ↔ AG-UI Integration Layer (AGUIStream)
│
│ wraps ConversableAgent
│ maps AG2 activity → standardized AG-UI events
│ handles SSE transport
▼
AG-UI Endpoint (event + state stream)
│
│ agent ↔ application synchronization
│ TEXT_MESSAGE_CONTENT
│ TOOL_CALL_START / END
│ STATE_DELTA / STATE_SNAPSHOT
│ USER_INTERACTION
▼
CopilotKit (AG-UI client runtime)
│
├─ subscribes to live stream
├─ renders messages + tool lifecycle
├─ synchronizes state updates
└─ forwards user actions → AG2 via AG-UI
▼
Application UI

The backend remains purely AG2. CopilotKit simply consumes the AG-UI stream and renders it as product UI.

Integration Flow: AG2 → AG-UI → CopilotKit

We have seen the conceptual flow. Now let’s look at the actual implementation.

You can check the AG-UI integration examples in the build-with-ag2 repository, which consists of two patterns: weather/ directory shows a single-agent chat with tools & factory/ directory demonstrates a multi-stage pipeline using ContextVariables.

For complete CopilotKit + AG2 integration with full UI implementations, explore the ag2-samples repository.

The integration centers on AGUIStream, which wraps a ConversableAgent and exposes it as an AG‑UI endpoint over SSE.

Define your agent exactly as you normally would, then mount the stream on FastAPI. The only important detail is enabling streaming in the LLM configuration.

from autogen import ConversableAgent, LLMConfig
from autogen.ag_ui import AGUIStream
from fastapi import FastAPI

agent = ConversableAgent(
    name="weather_agent",
    system_message="You are a helpful weather assistant. Use the get_weather tool to look up current conditions for any city.",
    llm_config=LLMConfig({
        "model": "gpt-5-mini",
        "stream": True
    }),
    functions=[get_weather],
)

# wrap the agent and mount it as an ASGI endpoint
stream = AGUIStream(agent)  

app = FastAPI()  
app.mount("/chat", stream.build_asgi())

That’s the entire backend bridge.

AGUIStream automatically maps:

Token streaming → TEXT_MESSAGE_*
Tool execution → TOOL_CALL_START, TOOL_CALL_RESULT
Context updates → STATE_SNAPSHOT / STATE_DELTA
Run lifecycle → RUN_STARTED, RUN_FINISHED, RUN_ERROR

The endpoint serves Server-Sent Events (SSE). When a client sends a RunAgentInput payload with Accept: text/event-stream, the response becomes a live event stream.

Here's a simplified example of what flows back:

data: {"type":"RUN_STARTED", ...}
data: {"type":"TEXT_MESSAGE_CONTENT","delta":"The"}
data: {"type":"TEXT_MESSAGE_CONTENT","delta":" weather"}
data: {"type":"TOOL_CALL_START", ...}
data: {"type":"TOOL_CALL_RESULT", ...}
data: {"type":"RUN_FINISHED", ...}

The frontend does not need to understand AG2 internals. It reacts to event types. At the lowest level, consuming AG-UI is just opening an SSE stream:

const response = await fetch("/chat", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "text/event-stream"
  },
  body: JSON.stringify(runAgentInput)
});

But in practice, you don’t parse SSE manually.

CopilotKit understands AG-UI natively. You keep the same backend (AGUIStream), and simply point CopilotKit to that endpoint. Proxy AG‑UI traffic through a Next.js API route.

import {
  CopilotRuntime,
  ExperimentalEmptyAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { HttpAgent } from "@ag-ui/client";
import { NextRequest } from "next/server";

// You can use any service adapter here for multi-agent support
// Use ExperimentalEmptyAdapter since AG2 handles the LLM directly
const serviceAdapter = new ExperimentalEmptyAdapter();

const runtime = new CopilotRuntime({
  agents: {
    weather_agent: new HttpAgent({
      url: "http://localhost:8000/chat"
    })
  }
});

export const POST = async (req: NextRequest) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    serviceAdapter,
    endpoint: "/api/copilotkit",
  });

  return handleRequest(req);
};

Finally, wrap your app with CopilotKit and render the chat. CopilotKit subscribes to the AG‑UI stream and renders messages, tool progress and state updates in real time.

import { CopilotKit } from "@copilotkit/react-core";
import { CopilotChat } from "@copilotkit/react-ui";

<CopilotKit runtimeUrl="/api/copilotkit" agent="weather_agent">
  <CopilotChat />
</CopilotKit>

That's the complete loop. The weather example in the build-with-ag2 repository shows this minimal streaming setup.

Multi-Agent Orchestration

The current AG-UI integration wraps a single ConversableAgent. Multi-agent workflows (group chats, delegation, nested conversations) still run inside AG2, but they are exposed through one interaction surface.

To model staged or multi-agent UX, use an orchestrator agent with ContextVariables. It is a shared state that agents use to coordinate, track progress, and make decisions across a conversation.

When a tool updates context_variables, AGUIStream automatically emits a STATE_SNAPSHOT event.

The frontend can consume that snapshot to:

Highlight which agent is active
Show pipeline progress
Render stage-specific UI

Here's the pattern:

from autogen import ConversableAgent
from autogen.ag_ui import AGUIStream

def submit_plan(plan: str, context): # context injected automatically
    """Submit the plan and move to draft stage."""
    context["active_agent"] = "drafter"
    context["stage"] = "drafting"
    context["plan"] = plan
    return {"status": "plan submitted"}

def submit_draft(draft: str, context):
    """Submit the draft and move to review stage."""
    context["active_agent"] = "reviewer"
    context["stage"] = "reviewing"
    context["draft"] = draft
    return {"status": "draft submitted"}

def submit_review(approved: bool, context):
    """Submit review and finalize."""
    context["stage"] = "complete" if approved else "revising"
    return {"status": "review complete"}

orchestrator = ConversableAgent(
    name="orchestrator",
    system_message="You coordinate a multi-stage workflow.",
    llm_config=llm_config,
    functions=[submit_plan, submit_draft, submit_review],
)

stream = AGUIStream(orchestrator)

Each tool call that updates context triggers a STATE_SNAPSHOT. The frontend reads active_agent and stage from the snapshot and updates the UI accordingly.

The factory example shows this pattern with a 3-panel UI: agent pipeline, document preview and conversation log.

Native multi-agent support is actively being developed. This orchestrator pattern is the current workaround.

What This Enables for Agent Builders

With this integration, you can keep AG2 where it’s strong and still ship real UIs without protocol glue. You can:

✅ Build AG2 agent teams and expose them as AG‑UI endpoints with one wrapper (AGUIStream).

✅ Connect those endpoints to CopilotKit (or any AG‑UI client) without custom WebSocket or polling infrastructure.

✅ Reuse AG2 agent logic across products while keeping a single frontend contract (AG-UI) instead of inventing new payloads for every application

✅ Stream agent runs, tool progress and state in real time using CopilotKit components, so users see what the system is doing instead of waiting on a single final response.

Getting Started

You can start building with this integration today.

👉 Explore the AG2 documentation

👉 Check out the CopilotKit / AG2 docs to get started

👉 Check out our example repo for a minimal integration setup

👉 Explore the build-with-ag2 AG‑UI examples: weather/ directory shows a single-agent chat with tools, factory/ directory demonstrates a multi-stage pipeline using ContextVariables

👉 Try the AG2 demo in the AG-UI Dojo playground

What's Next

This launch makes AG2 a first‑class backend for AG‑UI‑compatible frontends.

On the CopilotKit side, the focus is on richer AG‑UI rendering components, better devtools for inspecting AG‑UI streams and more starter projects that bundle AG2 + CopilotKit out of the box.

Native multi-agent support in AG‑UI is an active focus. The AG2 and CopilotKit teams are working together to bring first-class multi-agent patterns to the protocol so you won't need the orchestrator workaround.

Over the next few weeks, expect more reference implementations, clearer integration patterns and production-grade examples that show how these layers work together in real applications.