# Add AG-UI Streams to ADK Sessions

> Add Intelligence’s AG-UI streams to your existing agent conversations, with optional historical import for supported stores.

<span id="what-is-this" />

## Add Intelligence to your existing app [#add-intelligence-to-your-existing-app]

Give users reconnection, catch-up, and delivery across devices around your ADK agent. Follow the [Intelligence quickstart](/vue/google-adk/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 your ADK agent and its durable storage connected so you can continue the same conversations after importing them. See [how streams work with framework storage](/vue/google-adk/intelligence/threads-explained#how-threads-work-with-framework-storage).

## Include earlier conversations (optional) [#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 that is missing from the source.

The ADK importer reads persisted sessions from ADK database session stores and Vertex/Agent Engine session history. It brings over saved messages, rich tool results, attachments, and agent state where available. Some interactive content, such as MCP app views, may not have been saved in the original history.

The following prerequisites and commands apply only to that historical import. Use Threads Drawer or [Headless Threads](/vue/google-adk/headless-threads) to open imported and new conversations through the same UI.

## Prerequisites [#prerequisites]

- An existing CopilotKit app with Intelligence connected.
- 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 `agentId`s.

<Callout type="warning" title="Legacy ADK pickle stores">
  The importer does not parse ADK pickle stores. Migrate the store first, then re-run the import:

  ```bash title="Terminal"
  adk migrate session --from 0
  ```

  If your ADK version prints a different migration command, use that command.
</Callout>

## Confirm the target project [#confirm-the-target-project]

Choose the Intelligence project that will receive the history. Its app-api URL and project-scoped runtime key select the destination. You will export those values before importing.

For a CLI-created app, you can select a cloud-hosted project:

```bash title="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`.

## Configure the source [#configure-the-source]

Choose the ADK backend to read from.

<Tabs groupId="adk_import_backend" items={['Database', 'Vertex / Agent Engine']}>
  <Tab value="Database">
    ```bash title="Terminal"
    export ADK_SOURCE_BACKEND="database"
    export ADK_DATABASE_CONNECTION_STRING="postgres://..."
    export ADK_IMPORT_SCOPES="support:user-123"
    ```

    `ADK_IMPORT_SCOPES` accepts comma-separated selectors such as `app:user`, `app:*`, `*:user`, or `*`.
  </Tab>
  <Tab value="Vertex / Agent Engine">
    ```bash title="Terminal"
    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:*"
    ```

    The importer uses your Google application default credentials or service account credentials in the same way ADK does.
  </Tab>
</Tabs>

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

```bash title="Terminal"
npx copilotkit@latest import \
  --source adk \
  --adk-source-backend database \
  --adk-import-scopes "support:user-123" \
  --dry-run
```

## Run a dry run [#run-a-dry-run]

Preview the import before writing anything.

```bash title="Terminal"
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 [#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.

```json title="agent-map.json"
{
  "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 [#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:

```bash title="Terminal"
export INTELLIGENCE_API_URL="https://..."
export CPK_INTELLIGENCE_API_KEY="cpk-..."
```

You can also pass the destination directly with `--api-url` and `--api-key` instead.

## Import the conversations [#import-the-conversations]

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

```bash title="Terminal"
npx copilotkit@latest import \
  --source adk \
  --agent-map ./agent-map.json
```

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

```bash title="Terminal"
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`. This value must match the application user ID returned by your runtime's `identifyUser`. 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 conversations [#verify-the-imported-conversations]

Sign in as the application user whose ID you imported. Open the conversation from the Threads Drawer and make sure that its earlier messages appear. Send a message and make sure that ADK updates the same native session.

## Re-run or replace [#re-run-or-replace]

Already-imported sessions are skipped by default.

Use `--replace` to refresh them; running or continued sessions are left unchanged:

```bash title="Terminal"
npx copilotkit@latest import \
  --source adk \
  --agent-map ./agent-map.json \
  --replace
```

## Continue using ADK persistence [#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 app sends future conversations through CopilotKit to CopilotKit Intelligence. Keep the original ADK agent and its durable storage connected. To continue a conversation, open it from the Threads Drawer. Supported pending approvals and requests for input continue too.

- **Threads Drawer:** already included in CLI-created starters. Use the [Threads Drawer guide](/vue/google-adk/prebuilt-components/copilot-threads-drawer) to customize its ready-made thread UI.
- **Headless Threads:** use the [Headless Threads guide](/vue/google-adk/headless-threads) 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`.

Open an imported conversation and send a follow-up to continue it.
