Learning

Overview#

Learning turns patterns from real agent runs into reusable Skills. It looks at completed conversations and application interactions in Rich Threads, produces evidence-backed Insights, and proposes instructions you can review before publishing.

The walkthrough begins with Memory, a separate Intelligence capability, then shows an expense-review workflow becoming a reusable Skill.

How Learning works#

Learning starts with a container, which groups Threads from the same kind of work. Intelligence analyzes completed runs in that container 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.

Set up Learning#

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

Optional: Set it up 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? Skip this step and continue below.

Use this pre-built prompt to set up Automatic Learning faster.

Connect CopilotKit Intelligence#

Complete the Intelligence quickstart, then send a message and confirm that it appears in Rich Threads. Open your project in CopilotKit Intelligence and confirm that Learning is available.

Create a Learning container#

In your Intelligence project, open Learning and choose Create Learning container. Give the container a stable ID, a descriptive name, and optional guidance about what good work looks like.

Keep each container focused on one kind of work, such as expense review, support quality, or customer onboarding. Stable IDs contain 1–64 lowercase letters, numbers, or single hyphens; for example, expense-review.

Assign Threads from your Runtime#

Return the container's stable ID from getLearningContainerId on your CopilotKitIntelligence client.

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

Keep a Thread's assignment stable

Assign a Thread before its first agent run and return the same container ID for every later run. Existing evidence is not backfilled, and a Thread cannot move between containers.

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.

Run Learning and review#

Open the container's Runs tab and select Run Learning. Review the resulting Insights and their source Threads, then approve or reject each proposed Skill. Approved revisions appear under Skills.

Use published Skills#

From a directory connected to the same Intelligence project, download the container's published Skills:

Terminal

copilotkit project select
copilotkit 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#

Problem	What to check
A Thread never appears in the container	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.
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	Download the latest bundle and confirm that your agent environment loads the generated Skill directory.