# AG-UI Streams

> Complement any existing thread system with AG-UI Streams. Store and restore messages, generative UI, tool calls, and uploaded files. Reconnect and catch up after a network drop, or on another tab or device.

<span id="overview" />

CopilotKit Intelligence’s AG-UI Streams complement your existing thread system, whether you use LangGraph, Google ADK, Mastra, or a custom backend. Your framework keeps managing the conversation and agent state while Intelligence records the interactions delivered through CopilotKit.

That includes messages, thinking traces, tool calls, generative UI, uploaded files (such as images, PDFs, and Excel files), and application state. You can also use CopilotKit Intelligence as your standalone thread store.

<Frame description="A support workspace that uses the Threads Drawer to move between customer conversations, while CopilotChat shows the selected case details.">
  <img
    src="/images/threads/support-desk-threads.png"
    alt="A support desk application with a Threads Drawer listing customer conversations beside CopilotChat case details for Northstar Analytics"
    className="w-full rounded-lg"
  />
</Frame>

<Accordions>
  <Accordion title="Starting fresh?">
    Intelligence stores your conversation history and restores messages, generative UI, tool interactions, and multimodal inputs when users return.
  </Accordion>
  <Accordion title="Already have your own threading system?">
    Keep it. Intelligence records its own copy of your supported AG-UI interactions while your framework manages the original conversation and agent state. [Read more](/vue/openai-agents-python/intelligence/bring-your-own-thread-system).
  </Accordion>
</Accordions>

<span id="sync-existing-conversations" />

## Add AG-UI Streams to existing threads [#add-ag-ui-streams-to-existing-threads]

Already have threads in LangGraph, Google ADK, Mastra, or a custom backend and want them to work with CopilotKit? Keep your existing storage. Your framework manages the agent’s conversation, model context, and execution state; Intelligence adds the event history and delivery needed to restore the interactive conversation for your users.

Connect your existing CopilotKit app through the [Intelligence quickstart](/vue/openai-agents-python/intelligence/quickstart) to add AG-UI delivery to future runs while your framework continues managing agent context and persistence. To include earlier conversations too, follow <DocsTrackedLink href="/vue/openai-agents-python/threads-import" surface="docs_threads_history_sync">Add AG-UI Streams to Existing Threads</DocsTrackedLink> for the optional historical steps supported for ADK, LangGraph, Mastra, and AWS Strands. Import is a one-time adoption step, not ongoing replication between databases.

Threads in Intelligence are separate from native framework session or checkpoint stores. Your backend can keep a stable mapping when the agent framework also needs its own conversation identifier.

<span id="why-use-copilotkit-rich-threads" />

## Why use CopilotKit AG-UI Streams? [#why-use-copilotkit-ag-ui-streams]

Intelligence’s AG-UI streams add delivery capabilities around your existing agent and framework threads:

- **Reconnect and catch up.** Reopen a conversation to replay recorded events and reconnect to an active run.
- **Continue in the background.** An agent run can continue after the browser disconnects while your Runtime and agent remain running. This is not execution recovery after a server failure.
- **Deliver across devices.** Users can reopen the same conversation on another device. Intelligence synchronizes thread metadata for connected clients; your application supplies a stable user identity.
- **Separate user history from model context.** Intelligence records the AG-UI events delivered through it. Your framework’s model-context compaction and Intelligence’s event replay serve different purposes.
- **Restore the interactive conversation.** Replay includes supported messages, generative UI, tool interactions, state, and multimodal inputs.

These are capabilities of CopilotKit Intelligence, not guarantees provided by the AG-UI protocol alone. Reopening or switching back to a conversation triggers replay and reconnection; see [connection behavior](/vue/openai-agents-python/intelligence/threads-explained#websocket-disconnection).

## Start with your coding agent [#start-with-your-coding-agent]

Copy this prompt into your coding agent to inspect your existing CopilotKit app and configure AG-UI Streams with CopilotKit Intelligence. Prefer to work through the setup yourself? Follow the manual steps below.

<RichThreadsSetupPrompt />

<span id="set-up-rich-threads-manually" />

## Set up AG-UI Streams manually [#set-up-ag-ui-streams-manually]

Create a new CopilotKit app connected to cloud-hosted CopilotKit Intelligence. Your application and CopilotKit Runtime run locally while CopilotKit Intelligence records AG-UI events and delivers them to connected clients. If you already have a working app, follow the [Intelligence quickstart](/vue/openai-agents-python/intelligence/quickstart#set-it-up-manually) to connect it instead.

<Steps>
  <Step>
    ### Create your app [#create-your-app]

    Run the interactive starter command:

    <DocsTrackedCopy surface="docs_threads_managed_setup">

    ```bash title="Terminal"
    npx copilotkit@latest init
    ```

    </DocsTrackedCopy>
  </Step>

  <Step>
    ### Connect CopilotKit Intelligence [#connect-copilotkit-intelligence]

    Complete browser sign-in, then create or select a CopilotKit Intelligence project when the CLI asks. To manage the project later, see [Cloud-hosted CopilotKit Intelligence](/vue/openai-agents-python/intelligence/managed-intelligence-platform).
  </Step>

  <Step>
    ### Start your app and Runtime [#start-your-app-and-runtime]

    Start the generated application and Runtime with the command printed by the CLI. For the standard npm setup:

    ```bash title="Terminal"
    cd <project-directory>
    npm run dev
    ```
  </Step>

  <Step>
    ### Verify your first thread [#verify-your-first-thread]

    Use the included Threads Drawer to create a conversation. Reload the page or reopen the conversation and confirm that its complete history returns.
  </Step>

  <Step>
    ### See it in Inspector [#see-it-in-inspector]

    Open Inspector on localhost and inspect your conversation under the **Rich Threads** pane.
    Real threads appear when Intelligence is on. When Intelligence is off, the pane is locked and shows **Copy setup prompt** and **Talk to an Engineer**.
    Open a real thread and use **Try from here** to copy it into a Playground scratch session. The stored thread does not change.

    More detail: [Inspector](/vue/openai-agents-python/inspector).
  </Step>
</Steps>

Threads-capable CLI starters already include [Threads Drawer](/vue/openai-agents-python/prebuilt-components/copilot-threads-drawer). Use its guide when you are ready to customize the drawer. Choose [Headless Threads](/vue/openai-agents-python/headless-threads) later if your product needs a fully custom thread UI. To run Intelligence in your own Kubernetes cluster, see [Self-host CopilotKit Intelligence](/vue/openai-agents-python/intelligence/self-hosting).

<span id="how-threads-work" />

## How AG-UI Streams work [#how-ag-ui-streams-work]

Threads Drawer and Headless Threads both use Intelligence’s AG-UI streams. A stable `threadId` connects the visible conversation to the runtime and its durable event history.

<Image
  src="/images/threads/threads-diagram-light.png"
  alt="A user starts a conversation on a laptop, leaves or switches devices, and returns to the same conversation on a phone."
  width={1774}
  height={919}
  className="block dark:hidden my-6 w-full mx-auto"
/>
<Image
  src="/images/threads/threads-diagram-dark.png"
  alt="A user starts a conversation on a laptop, leaves or switches devices, and returns to the same conversation on a phone."
  width={1775}
  height={918}
  className="hidden dark:block my-6 w-full mx-auto"
/>

1. Your UI opens a conversation with a stable `threadId`.
2. `CopilotRuntime` runs your agent and sends conversation events to CopilotKit Intelligence.
3. When users return, CopilotKit Intelligence replays the stored history, reconnects any live run, and synchronizes thread metadata.

<Callout type="info" title="How are threads scoped to each user?">
  Your application authenticates its users, and `CopilotRuntime` resolves that
  verified identity on the server with `identifyUser`. CopilotKit Intelligence
  uses the stable user ID to scope thread lists and lifecycle actions. See
  [Scope AG-UI Streams to the signed-in user](/vue/openai-agents-python/threads-lifecycle#scope-rich-threads-to-the-signed-in-user)
  for the Runtime contract and an implementation pattern.
</Callout>

### What CopilotKit handles [#what-copilotkit-handles]

| CopilotKit handles | You control |
|---|---|
| Durable event storage and replay | Your agent's behavior and tools |
| Replay-to-live stream reconnection | The conversation experience and layout |
| Realtime thread metadata synchronization | Which thread actions your users can access |
| Naming, pagination, archive, and delete semantics | Application authorization and permissions |
| Runtime-to-platform event plumbing and thread locks | Mapping to native framework sessions when needed |
| Cloud-hosted or self-hosted platform infrastructure | The deployment model that fits your organization |

<Callout type="info" title="Headless means custom UI, not custom infrastructure">
  Threads Drawer and Headless Threads use the same persistence, replay, synchronization, and locking infrastructure. Choose Headless Threads when you want to build the interface yourself, not when you want to rebuild the AG-UI Streams backend.
</Callout>

## Choose how to build the UI [#choose-how-to-build-the-ui]

Use Threads Drawer for a ready-made conversation list, or build your own with [`useThreads`](/reference/hooks/useThreads). Pass the selected `threadId` to your chat to load its history and receive new events.

<CTACards
  columns={2}
  cards={[
    {
      iconKey: "panelLeft",
      title: "Threads Drawer",
      description:
        "Ship a mobile-friendly conversation sidebar with switching, new conversations, archive, delete, and pagination already wired to your chat.",
      href: "/prebuilt-components/copilot-threads-drawer",
    },
    {
      iconKey: "code",
      title: "Headless Threads",
      description:
        "Build a custom layout, workflow, permission model, or thread action UI while CopilotKit continues to handle the backend.",
      href: "/headless-threads",
    },
  ]}
/>

For how Intelligence and framework persistence work together, see [AG-UI Streams & Framework Threads](/vue/openai-agents-python/intelligence/threads-explained#how-threads-work-with-framework-storage).
