Add AG-UI Streams to Existing Threads

Add Intelligence to your existing app#

Add reconnection, catch-up, and delivery across devices to the conversations your agent already manages. Follow the Intelligence quickstart to connect your existing CopilotKit app and Runtime, then verify that a new conversation is saved. That setup enables AG-UI streams for runs through CopilotKit; importing old conversations is not required.

Your framework continues managing agent context and execution state. Keep your durable LangGraph checkpointer or durable ADK session service configured and keep the mapping between CopilotKit threadId values and native framework conversation identifiers stable. See AG-UI Streams & Framework Threads for the responsibilities of each layer.

Include earlier conversations (optional)#

If you also want users to reopen history recorded before Intelligence was connected, copy supported history into Intelligence using the steps below. The importer currently supports Google ADK, LangGraph, and Mastra stores. It copies historical content; it does not enable live delivery, recover past execution, or establish ongoing database replication.

Use Threads Drawer or useThreads to select a conversation, and pass its threadId to your chat. Imported and new conversations then use the same UI. Importing cannot recover content the source no longer exposes.

Supported sources#

Source	Import guide	Supported history
Google ADK	Add AG-UI streams to ADK sessions	Persisted ADK sessions from a database session service or Vertex/Agent Engine session service.
LangGraph	Add AG-UI streams to LangGraph threads	LangGraph Server, LangGraph Platform, or LangSmith Deployment threads exposed through the LangGraph SDK thread/run APIs.
Mastra	Add AG-UI streams to Mastra conversations	Saved conversations from a local LibSQL database or a Mastra server.

What gets imported?#

The importer preserves conversation content that can render in the CopilotKit chat UI or help downstream learning systems:

user, assistant, tool, system, and developer messages
tool calls and tool results
reasoning traces when the source exposes them
media that can be resolved during extraction
saved agent state when supported by the source
original timestamps
import provenance and per-conversation import outcomes

It does not import framework transport noise, LangSmith traces, or unsupported source stores. What is available depends on what your source saved; see your framework’s import guide for details.

Import flow#

Confirm the target project#

By default, the importer targets the CopilotKit Intelligence project selected when you created the app with the CopilotKit CLI. If that is the project that should receive the imported threads, continue to the dry run.

To target a different cloud-hosted project, select it before the dry run:

Terminal

npx copilotkit@latest project select

The command updates the project selected for the current directory and writes its project-scoped runtime key to the app's generated .env.

Run a dry run#

A dry run reads the source, discovers source agent keys, counts conversations, reports skips, and estimates upload size without opening an import batch. It does not need a CopilotKit Intelligence URL or API key.

npx copilotkit@latest import --source adk --dry-run

npx copilotkit@latest import --source langgraph --dry-run

Configure your source using the Mastra import guide, then run:

npx copilotkit@latest import --source mastra --dry-run

Map source agents#

The importer maps each source agent key to the agentId your live CopilotKit runtime uses. Keeping those labels aligned prevents imported history and future native traffic from splitting across different agent IDs.

For scripted imports, put the mapping in a JSON file:

agent-map.json

{
  "support-agent": "support-agent",
  "sales-agent": "sales-agent"
}

Prepare the CopilotKit Intelligence destination#

A real import needs the destination app-api URL and project-scoped runtime key. A CLI-created starter writes them to .env, but the importer reads the current process environment and does not load .env or .copilotkit/project.json automatically.

Copy the generated values into your shell before importing:

Terminal

export INTELLIGENCE_API_URL="https://..."
export CPK_INTELLIGENCE_API_KEY="cpk-..."

COPILOTKIT_API_KEY is also accepted for the key. You can pass the same values directly with --api-url and --api-key instead.

Run the import#

Run the source-specific import after the dry run looks right:

Already-imported threads are skipped by default. Use --replace to refresh them; running or continued threads are left unchanged.

Verify the imported conversations#

Open the Threads Drawer, select an imported conversation, and confirm that its history appears in the chat.

Continue using your framework's persistence#

Your app sends future conversations that run through CopilotKit to CopilotKit Intelligence. Keep your durable LangGraph or ADK persistence configured so those runs continue using both persistence layers. Reopen a conversation with the same CopilotKit threadId and a stable mapping to its native thread or session so its history stays continuous.

Importing copies supported history; it does not establish ongoing database replication. Intelligence rename, archive, and delete operations affect only Intelligence records.

Threads Drawer: already included in CLI-created starters. Use the Threads Drawer guide to customize its ready-made thread UI.
Headless Threads: use the Headless Threads guide only when you need a custom UI. Select a thread with useThreads, store its thread.id, and pass that value to your chat component as threadId.

Create one new conversation through CopilotKit, then confirm that it appears in CopilotKit Intelligence and in the native persistence store that remains connected to your agent.

For the underlying persistence and replay model, see AG-UI Streams & Framework Threads.

Deployment notes#

Cloud-hosted CopilotKit Intelligence: export the destination values generated in the CLI-created app's .env, or pass them with --api-url and --api-key. project select can rewrite the app's generated values, but the importer still reads only flags or the current process environment. See Cloud-hosted CopilotKit Intelligence.
Self-hosted CopilotKit Intelligence: pass the deployment's app-api URL with --api-url and a project-scoped cpk runtime key with --api-key. See Self-host CopilotKit Intelligence.