Import Thread History

Move historical conversations into Enterprise Intelligence, then keep future conversations synced with CopilotKit threads.

What is this?#

Thread import moves already-persisted conversations into Enterprise Intelligence as CopilotKit threads. After import, users can open those conversations through the same thread UI you use for native CopilotKit conversations. Built-in import currently supports Google ADK and LangGraph, with more sources coming soon.

Import is a historical migration, not an ongoing replication job. Run it from a CopilotKit app created with the CLI and Enterprise Intelligence enabled. The importer uses the Enterprise Intelligence project selected for the current directory.

Supported sources#

Source	Import guide	Supported history
Google ADK	Import ADK threads	Persisted ADK sessions from a database session service or Vertex/Agent Engine session service.
LangGraph	Import LangGraph threads	LangGraph Server, LangGraph Platform, or LangSmith Deployment threads exposed through the LangGraph SDK thread/run APIs.

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
original timestamps
import provenance and per-conversation import outcomes

It does not import agent state snapshots, framework transport noise, LangSmith traces, or unsupported source stores.

Import flow#

Confirm the target project#

By default, the importer uses the Enterprise 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 provisions its project-scoped runtime key. For self-hosted deployments, pass --api-url and --api-key to the import command instead.

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.

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

npx copilotkit@latest import --source langgraph --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"
}

Run the import#

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

Re-running the same import is safe: already-imported conversations are skipped. Use --replace when you intentionally want to refresh previously imported threads.

Keep future conversations synced#

Import only moves existing history. Your CLI-created app already sends new CopilotKit conversations to the selected Enterprise Intelligence project. To keep each conversation continuous, reopen it with the same CopilotKit threadId. Choose the thread UI that fits your app:

Threads Drawer: follow the Threads Drawer guide. The drawer and chat share a CopilotChatConfigurationProvider, so selecting a conversation updates the active threadId without separate state wiring.
Headless Threads: follow the Headless Threads guide. Select a thread with useThreads, store its thread.id, and pass that value to your chat component as threadId.

For the underlying persistence and replay model, see Threads & Persistence Architecture.

Deployment notes#

Cloud-hosted Enterprise Intelligence: the importer uses the CLI-selected project by default. Run project select before importing only when you need to change the target project. See Cloud-Hosted Enterprise Intelligence.
Self-hosted Enterprise Intelligence: pass your deployment's app-api URL with --api-url and a project-scoped cpk runtime key with --api-key. See Self-Hosting Enterprise Intelligence.