Add AG-UI Streams to ADK Sessions

Add Intelligence to your existing app#

Give users reconnection, catch-up, and delivery across devices around your ADK agent. Follow the Intelligence quickstart to connect your existing CopilotKit app and Runtime, then verify that a new conversation is saved. This enables AG-UI streams for runs through CopilotKit; no historical import is required.

Keep ADK session storage and analytics configured for agent context and execution state. Maintain a stable mapping between CopilotKit threadId values and native ADK conversation identifiers so later runs reach the same conversation. See how streams work with framework storage.

Include earlier conversations (optional)#

To let users reopen conversations recorded before Intelligence was connected, use the importer below to copy supported historical content. Importing does not enable live delivery or establish ongoing database replication, and it cannot recover history the source no longer exposes.

The ADK importer reads persisted sessions from ADK database session stores and Vertex/Agent Engine session history.

The following prerequisites and commands apply only to that historical import. Use Threads Drawer or Headless Threads to open imported and new conversations through the same UI.

Prerequisites#

• A CopilotKit app created with the CLI and CopilotKit Intelligence enabled.
• Persisted ADK sessions. In-memory ADK sessions cannot be exported.
• ADK source credentials in environment variables.
• An agent map from ADK app_name values to your live CopilotKit agentIds.

Confirm the target project#

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 ADK sessions, continue to source configuration.

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

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.

Configure the source#

Choose the ADK backend to read from.

export ADK_SOURCE_BACKEND="database"
export ADK_DATABASE_CONNECTION_STRING="postgres://..."
export ADK_IMPORT_SCOPES="support:user-123"

export ADK_SOURCE_BACKEND="vertex"
export ADK_VERTEX_PROJECT_ID="my-gcp-project"
export ADK_VERTEX_LOCATION="us-central1"
export ADK_VERTEX_AGENT_ENGINE_ID="..."
export ADK_IMPORT_SCOPES="support:*"

You can also pass the backend and scopes as CLI flags:

npx copilotkit@latest import \
  --source adk \
  --adk-source-backend database \
  --adk-import-scopes "support:user-123" \
  --dry-run

Run a dry run#

Preview the import before writing anything.

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

The dry run discovers ADK app names, counts sessions, reports sessions that cannot be imported, and estimates upload size. It does not need a CopilotKit Intelligence URL or API key.

Map ADK app names to CopilotKit agent IDs#

The source agent key for ADK is app_name. Map each discovered app name to the agentId your live CopilotKit runtime uses.

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

Using the same agentId as live traffic keeps imported sessions and future conversations grouped together.

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:

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

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

Import the sessions#

Run the import after the dry run and agent map look right.

npx copilotkit@latest import \
  --source adk \
  --agent-map ./agent-map.json

For self-hosted CopilotKit Intelligence, pass the target connection explicitly:

npx copilotkit@latest import \
  --source adk \
  --api-url "$INTELLIGENCE_API_URL" \
  --api-key "$CPK_INTELLIGENCE_API_KEY" \
  --agent-map ./agent-map.json \
  --yes

ADK user attribution defaults to session.user_id. Sessions without a recoverable user are omitted by default; use --unrecoverable imported-unknown only when you intentionally want to place those sessions under an imported fallback user.

Verify the imported sessions#

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

Re-run or replace#

Re-running the same import is idempotent. Sessions already imported from the same source are skipped.

Use --replace to delete and re-import previously imported sessions:

npx copilotkit@latest import \
  --source adk \
  --agent-map ./agent-map.json \
  --replace

Continue using ADK persistence#

Importing copies supported history; it does not establish ongoing database replication. Intelligence rename, archive, and delete operations affect only Intelligence records, leaving the native ADK session records unchanged.

Your CLI-created app sends future CopilotKit conversations to CopilotKit Intelligence. To keep each conversation continuous, reopen it with the same CopilotKit threadId. If your agent remains wired to a durable ADK session service and retains its sessions, the same future runs continue to persist in ADK for its native storage and analytics.

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

Keep the mapping between CopilotKit thread IDs and ADK session IDs stable so a resumed thread reaches the expected ADK session.

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