# Automatic Learning

> Turn real use of your app into skills you can review and publish.

## Overview [#overview]

Automatic Learning turns patterns from real agent runs into skills you can publish. It reads completed conversations in [AG-UI Streams](/vue/deepagents/AG-UI-Streams), writes insights, and proposes instructions you review before you publish them.

<div className="not-prose shell-docs-radius-surface aspect-[7/4] w-full overflow-hidden border border-[var(--border)] bg-[var(--bg-surface)] shadow-[var(--shadow-panel)]">
  <iframe
    src="https://www.loom.com/embed/2978fbfe42324e509057ac5fd46b7a70"
    title="Automatic Learning and User Memories in CopilotKit"
    className="h-full w-full"
    frameBorder="0"
    allowFullScreen
  />
</div>

The video also shows [User Memory](/vue/deepagents/intelligence/memories), then an expense-review workflow that becomes a skill.

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

Copy this prompt into your coding agent to inspect your existing app and configure Automatic Learning for one focused workflow. Prefer to work through the setup yourself? Follow the manual steps below.

<LearningSetupPrompt />

## How Automatic Learning works [#how-automatic-learning-works]

Learning starts with a Learning Space, which groups [Threads](/vue/deepagents/intelligence/threads-explained) from the same kind of work. The API and CLI call a Learning Space a container. [Intelligence](/vue/deepagents/intelligence/overview) analyzes completed runs in that Space and summarizes recurring patterns as Insights.

When a pattern can be reused, Learning proposes a Skill. You review the supporting Threads and decide whether to publish it. A published Skill is a versioned set of instructions that you load into your agent; Learning does not change the model itself.

Automatic Learning checks eligible Learning Spaces on a daily schedule. After you approve a skill, [skill delivery](/vue/deepagents/intelligence/learned-skills) makes it available to connected agents. A scheduled run does not approve skills. Turning on delivery does not connect your agent for you.

To record what people do in your app around the agent, such as clicks in a tool's UI and page changes, see [Capture interactions](/intelligence/capture-interactions).

## Collect runs and deliver Skills [#collect-runs-and-deliver-skills]

The learning loop has two connections. Run ingestion collects evidence in a Learning Space. Skill delivery loads published instructions into an agent.

| Connection | Configuration | Result |
| --- | --- | --- |
| Runtime to Automatic Learning | `CopilotKitIntelligence.getLearningContainerId` | Assigns selected Threads to a container for analysis. |
| Browser activity to Automatic Learning | `CopilotKitIntelligence.getTrajectoryLearningContainerIds` | Assigns captured Trajectories to existing Learning Spaces. |
| Learning to agent | An Intelligence SDK adapter for your framework | Makes published Skills available during agent invocations. |

When an agent must learn from its own workflow, use the same project and Learning Space for both connections. The SDK adapters also work with native agents outside a CopilotKit frontend, but they do not collect those agents' runs automatically.

For agent setup, use the [Mastra](/vue/deepagents/intelligence/learned-skills#mastra), [LangGraph TypeScript](/vue/deepagents/intelligence/learned-skills#langgraph-typescript), or [LangGraph Python](/vue/deepagents/intelligence/learned-skills#langgraph-python) example. The delivery guide also covers [Google ADK](/vue/deepagents/intelligence/learned-skills#google-adk), [BuiltInAgent](/vue/deepagents/intelligence/learned-skills#builtinagent), and [Microsoft Agent Framework](/vue/deepagents/intelligence/learned-skills#microsoft-agent-framework).

## Assign browser activity to a Learning Space [#assign-browser-activity-to-a-learning-space]

Read this section only if your app captures browser activity as Trajectories. If you only send Threads, go to [Set up Automatic Learning manually](#set-up-automatic-learning-manually).

For capture connected to Intelligence, select existing Learning Spaces in your Runtime's server configuration:

```ts
const intelligence = new CopilotKitIntelligence({
  apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
  getTrajectoryLearningContainerIds: ({ trajectoryId, user }) =>
    ["expense-review"],
});
```

Create the Space before capture starts. The callback receives the Trajectory ID chosen by the browser and the application user verified by your Runtime. It does not require a Thread or an agent conversation. Browser-supplied Space IDs are ignored. A linked Thread's Space does not add the Trajectory; to show a Trajectory's chat during analysis, also assign its Threads to the same Space with `getLearningContainerId`.

Return `[]` to request no new assignments explicitly. Return `null` or `undefined` to omit assignments from the connect request. Each connect adds memberships and never removes existing ones, so keep the selection stable across reconnects. A membership removed in Intelligence stays removed.

Assignment problems never stop capture:

- A selected Space does not exist in the project: the Runtime logs a warning with the Trajectory and Space IDs. It connects the Trajectory without any assignments, including the Spaces that exist.
- The callback throws, returns invalid IDs, or runs past its five-second deadline: the Runtime logs the error and connects the Trajectory without assignments.

If Trajectories do not appear in a Space, check your Runtime logs.

The optional second argument of the callback is an `AbortSignal`. It cancels when the request ends or the deadline expires. Your Intelligence backend must support Trajectory inputs for Automatic Learning. Assignment alone does not start an analysis or guarantee an insight.

## Set up Automatic Learning manually [#set-up-automatic-learning-manually]

When you are done, your Runtime will send selected Threads to a Learning Space, ready to be analyzed and turned into reviewed Skills.

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

    1. Complete the [Intelligence quickstart](/vue/deepagents/intelligence/quickstart). That page signs you in with the CLI and selects the project.
    2. Send a message and make sure that it appears in [AG-UI Streams](/vue/deepagents/AG-UI-Streams).
    3. Open your project in [CopilotKit Intelligence](https://dashboard.operations.copilotkit.ai/) and make sure that Learning is available.

  </Step>

  <Step>
    ### Create a Learning Space [#create-a-learning-space]

    In your Intelligence project, open **Automatic Learning** and choose **Create learning space**. Give the Space a descriptive name and a stable **Space ID**. You can also add an **Automatic Learning focus** that says what good work looks like.

    Keep each Space focused on one kind of work, such as expense review, support quality, or customer onboarding. A Space ID contains 1 to 64 lowercase letters, numbers, or single hyphens, for example `expense-review`.

    You can also use the [CLI](/vue/deepagents/cli), which calls a Learning Space a container. Run these commands in the folder where you selected the project. First, list the containers that already exist:

    ```bash title="Terminal"
    npx copilotkit@latest learning containers list
    ```

    If a container for this kind of work exists, reuse its ID. Do not create a second container for the same work.

    If no container fits, print the default container ID for your project. The CLI makes this ID from your project slug. It does not check whether the container exists.

    ```bash title="Terminal"
    npx copilotkit@latest learning containers default-id
    ```

    Then create the container with that ID and a name:

    ```bash title="Terminal"
    npx copilotkit@latest learning containers create --id <container-id> --name "<container name>"
    ```

    To give guidance about what good work looks like, you can also add `--prompt-context` with a text value, for example `--prompt-context "Use approved answers."`.

  </Step>

  <Step>
    ### Assign Threads from your Runtime [#assign-threads-from-your-runtime]

    Return the Space ID from `getLearningContainerId` on the CopilotKit runtime you already run. Keep your agents as they are. The callback is the same for every agent framework.

    ```ts title="Your CopilotKit runtime"
    import {
      CopilotKitIntelligence,
      CopilotRuntime,
    } from "@copilotkit/runtime/v2";

    const intelligence = new CopilotKitIntelligence({
      apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
      getLearningContainerId: ({ agentId }) =>
        agentId === "expense-agent" ? "expense-review" : undefined,
    });

    const runtime = new CopilotRuntime({
      agents,
      intelligence,
      identifyUser,
    });
    ```

    Return `null` or `undefined` when a run should not participate. You can use the callback's user, surface, agent, and run input to route different workflows to different Spaces.

    If the ID is not 1 to 64 lowercase letters, numbers, and single hyphens, the run request fails with status 500. The Runtime sends the ID when it creates the Thread and when it locks each run.

    <Callout type="warn" title="Keep a Thread's assignment stable">
      Assign a Thread before its first agent run and return the same Space ID for every later run. Existing evidence is not backfilled, and a Thread cannot move between Spaces.
    </Callout>

  </Step>

  <Step>
    ### Collect examples [#collect-examples]

    Use the application normally and complete several related workflows. Corrections, tool calls, and application interactions all help Learning understand what a good result looks like.

    The Learning Space shows how many eligible Threads are ready and how many more are needed. By default, Automatic Learning requires **15 eligible Threads** for both the first run and each run after a success. Use the count shown in your Space if your deployment has a different threshold.

  </Step>

  <Step>
    ### Choose the daily schedule [#choose-the-daily-schedule]

    In the Learning Space, select **Edit schedule**. Under **This project**, the default is **Use organization schedule**. To set a time for this project, choose **Custom project schedule**. Set the daily time and time zone. Then save. The schedule applies to all Learning Spaces in the project.

    Organizations start with a daily default of **02:00 UTC**.

    When the Space is eligible, **Next scheduled run** shows a countdown and the scheduled time in your local zone and UTC. This is the next eligibility check: reaching the Thread threshold does not start a run immediately. An active analysis, a failure block, or disabled Automatic Learning can prevent a run. Saving a schedule does not start or cancel an analysis.

  </Step>

  <Step>
    ### Run Learning and review [#run-learning-and-review]

    Wait for the scheduled run, or select **Start manual run now** to analyze available evidence without waiting for the daily schedule or automatic Thread threshold. Follow its progress under **Analysis results**.

    Review the resulting Insights and their source Threads, then approve or reject each proposed Skill. Approved revisions appear under **Skills**. Automatic runs use the same review process; only published Skills are available for delivery.

    To review Skills inside your own app, see [Manage Learning from your server](#manage-learning-from-your-server).

  </Step>
</Steps>

<Callout type="info" title="Organization schedule">
  The **Organization default** tab changes the schedule for every project without an override and asks you to confirm that scope. Projects with a custom schedule keep it. Choosing **Use organization schedule** again restores inheritance, including future changes to the default.
</Callout>

<Callout type="info" title="See this in Inspector">
  Open Inspector on localhost. Go to **Automatic Learning**.
  Review published Skills, their supporting Insights, and the Thread evidence
  behind each pattern. Inspector also shows when new Threads are ready for a
  Learning run; start runs and review Skill candidates in the Intelligence web
  app.

  More detail: [Inspector](/vue/deepagents/inspector).
</Callout>

## Manage Learning from your server [#manage-learning-from-your-server]

Read this section if you want reviewers to start runs and approve Skills inside your own app. If you review in the Intelligence dashboard, go to [Use published Skills](#use-published-skills).

`CopilotKitIntelligence` can list containers, start manual runs, and review proposed Skills from your application server.
The experimental Learning management methods require an Intelligence deployment with the runtime Learning management API. Their SDK contracts can change before release.
They use the project API key from the existing client configuration.

Keep the key on your server. Authorize each application user before you call these methods.
A project key can read evidence and publish Skills across that project.
It does not represent the person who clicked a control in your application.

### Select a container and start a run [#select-a-container-and-start-a-run]

```ts title="Application server"
import { CopilotKitIntelligence } from "@copilotkit/runtime/v2";

const intelligence = new CopilotKitIntelligence({
  apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
});

const page = await intelligence.experimental.learning.listLearningContainers();
// Use page.nextCursor to request another page when it is not null.
const container = await intelligence.experimental.learning.getLearningContainer({
  containerId: "expense-review",
});

// Call only after the authorized user requests a manual run.
const admittedRun = await intelligence.experimental.learning.startLearningRun({
  containerId: container.id,
});
const runs = await intelligence.experimental.learning.listLearningRuns({
  containerId: container.id,
});
const progress = runs.find((run) => run.id === admittedRun.id);
```

A successful start response confirms admission, not completion. `listLearningRuns` returns the latest 100 runs, including their status and failure code.
A manual run analyzes eligible evidence across the selected container, including evidence from other applications that share it.
These methods do not upload workspace files, move Threads, or change their assignments.

### Review a proposed Skill [#review-a-proposed-skill]

```ts title="Application server"
const candidates = await intelligence.experimental.learning.listLearningCandidates({
  containerId: "expense-review",
});
const pending = candidates.find((item) => item.status === "pending_review");
if (pending) {
  const candidate = await intelligence.experimental.learning.getLearningCandidate({
    containerId: "expense-review",
    candidateId: pending.id,
  });
  const evidence = await Promise.all(
    candidate.supportingInsights.map((insight) =>
      intelligence.experimental.learning.getLearningInsightEvidence({
        containerId: "expense-review",
        insightId: insight.id,
      }),
    ),
  );
  // Show candidate.bundle.files and evidence to the authorized reviewer.
}
```

`listLearningCandidates` returns the latest 500 candidates, including completed reviews.
Evidence includes availability fields for missing Threads and Trajectories.

After the reviewer explicitly chooses **Approve** or **Reject**, call `reviewLearningCandidate` from your authorized server handler:

```ts title="Authorized review handler"
const review = await intelligence.experimental.learning.reviewLearningCandidate({
  containerId: "expense-review",
  candidateId, // The candidate the reviewer inspected.
  action: "approve", // Use "reject" for an explicit rejection.
});
```

Approval publishes the proposed change to the shared container. Rejection does not publish it.
Published Skill content remains available through [Skill delivery](/vue/deepagents/intelligence/learned-skills).

### Handle errors and cancellation [#handle-errors-and-cancellation]

All management methods accept an optional `signal: AbortSignal` and have a 30-second request deadline.
Cancellation stops the request; it does not undo a run or review that the server already accepted.
The SDK does not retry these requests automatically.

HTTP errors use the exported `PlatformRequestError` with `status`, `retryable`, and an optional backend `code`.
Error messages omit raw backend details. Invalid responses fail instead of returning partial data.
If a write response is lost, read the current runs or candidate before you offer another action.

## Use published Skills [#use-published-skills]

### Set up skill delivery [#set-up-skill-delivery]

Once you have published a Skill, connect the agent that should use it:

<Steps>
  <Step>
    #### Enable delivery for the Learning Space [#enable-delivery-for-the-learning-space]

    Open the Space's **Skills** tab and check that **Skill delivery** shows **Delivery enabled**. This controls new requests for published Skills from this Space.
  </Step>

  <Step>
    #### Connect your agent [#connect-your-agent]

    Select **Set up skill delivery**, then **Copy setup prompt**, and paste it into your coding agent. The prompt includes your Space ID and asks the coding agent to inspect your framework, preserve existing agent behavior, and configure the supported native adapter.

    For manual setup, follow the [framework adapter examples](/vue/deepagents/intelligence/learned-skills#native-setup). Pick the adapter for the agent you already run. Configure that adapter in the agent server environment with the same project key and Space ID used above.

    If that server does not already have the key, sign in and select the project from its directory:

    ```bash title="Terminal"
    npx copilotkit@latest login
    npx copilotkit@latest project select
    ```

    ```bash title="Agent server environment"
    CPK_INTELLIGENCE_API_KEY=cpk-...
    CPK_INTELLIGENCE_LEARNING_CONTAINER_ID=expense-review
    ```

    Keep the key server-side. Leave `CPK_INTELLIGENCE_SKILLS_REVISION` unset to follow the latest published Skills. See [container configuration](/vue/deepagents/intelligence/learned-skills#configure-one-container) for self-hosted endpoints and exact revision pins.
  </Step>

  <Step>
    #### Verify delivery in a new invocation [#verify-delivery-in-a-new-invocation]

    Initialize the adapter and start a new agent invocation. Confirm that the published Skill appears in its catalog, `copilotkit_load_skill` can load its `SKILL.md`, and `copilotkit_read_skill_file` can read a supporting file if the Skill has one. Copying the setup prompt or enabling the toggle alone does not verify the connection.

    The adapter refreshes published Skills automatically, with a default freshness window of five seconds. Each invocation keeps one snapshot; a newly published revision is available to later invocations after refresh. The model decides when to load and follow a Skill.
  </Step>
</Steps>

<Callout type="info" title="Pausing delivery is separate from Learning">
  Turning off **Skill delivery** does not stop Learning runs or revoke published revisions. Once an adapter checks delivery and receives the denial, it blocks new invocations; invocations already in progress keep their captured Skills. Pausing Learning runs likewise does not stop delivery of published Skills.
</Callout>

### Download Skills manually [#download-skills-manually]

Use the CLI for offline inspection or frameworks without a supported adapter. If you switch an agent from downloaded Skills to automatic delivery, remove the old manual loading for that container to avoid loading the same Skills twice.

From the agent directory, sign in and select the same Intelligence project. Then download the container's published Skills:

```bash title="Terminal"
npx copilotkit@latest login
npx copilotkit@latest project select
npx copilotkit@latest skills download expense-review --output ./learned-skills
```

The output contains a directory and `SKILL.md` for each published Skill. Configure your agent environment to load `./learned-skills` before expecting the new behavior in a run.

## Troubleshooting [#troubleshooting]

| Problem                                     | What to check                                                                                                                |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| A Thread never appears in the Space         | Confirm the callback returned an existing stable ID before the Thread's first run and that the run reached a terminal state. |
| The Runtime reports a container conflict    | The selector returned a different ID for an already-bound Thread. Restore the original mapping or start a new Thread.        |
| A run has no new evidence                   | Runs created before assignment, still in progress, or already included in an earlier Learning run are not new input.         |
| An automatic run has not started            | Check the Space's readiness count, daily schedule, and active or failed analysis. If it shows **Automatic learning is off**, scheduling is off for the deployment, and editing the time does not turn it on. Ask the administrator of your Intelligence deployment to turn on Automatic Learning. Until then, use **Start manual run now**. |
| Learning is waiting after a failed run      | Inspect the failure under **Analysis results**. Automatic Learning waits for additional eligible Threads before retrying that evidence; you can also start a manual run. |
| A run succeeds without a Skill candidate    | Inspect the Insights. The evidence may be useful without supporting a reusable procedural Skill.                             |
| An approved Skill does not affect the agent | Confirm delivery is enabled, the adapter uses the correct project and Space ID, and a new invocation can load the Skill. Check for an exact revision pin. For manual loading, download the latest bundle and confirm your agent loads its directory. |
| Delivery status is unavailable              | Select **Retry delivery status**. For self-hosted deployments, verify the delivery endpoint and migration are installed before relying on an adapter. See [deployment requirements](/vue/deepagents/intelligence/learned-skills#deployment-requirements). |
