History and transcripts
Distinguish Intelligence-managed conversation history from the optional SDK transcript store, and use each without duplicating turns.
Your agent needs earlier messages to answer well. Some apps also need one record per user across Slack and Teams. Pick the source by what you need:
| Need | Use |
|---|---|
| Continue the current Slack or Teams conversation | Managed conversation history |
| Inspect recent text in one provider thread | thread.getMessages() |
| Carry user context between Slack and Teams | SDK transcripts with a stable identity |
| Store workflow progress | thread.state() |
| Meet application deletion or retention requirements | A durable SDK transcript store plus your provider/Intelligence policies |
Managed conversation history rebuilds the current provider thread for the agent. SDK transcripts are an application-owned record, keyed by identity, that can span providers and conversations. They are not interchangeable.
Use managed conversation history
On each delivered turn, Intelligence fetches recent messages for that native conversation and seeds a fresh agent instance. The default history limit in the managed adapter is 20 messages.
The managed conversation history already holds the current turn, with its text and hydrated
attachments. Call runAgent() without a prompt to answer it:
channel.onMessage(async ({ thread }) => {
await thread.runAgent();
});Create a fresh agent for every conversationKey; the managed adapter assigns
the managed conversation history to that instance. Sharing one mutable agent between
threads can leak or overwrite history.
Read the current provider thread
thread.getMessages() returns a best-effort, oldest-first text view of recent
history:
const messages = await thread.getMessages();
const transcript = messages
.map((message) => `${message.isBot ? "Agent" : "User"}: ${message.text}`)
.join("\n");On the managed path, getMessages() throws when the history fetch fails. Catch
the error if the turn must continue without history. The method is text-oriented: binary image, audio, and video content is
available to the agent through multimodal history, but is not reproduced as
binary data in ThreadMessage.
Add cross-platform SDK transcripts
Use SDK transcripts when your application needs a user-centric record across
Slack and Teams. Configure top-level identifyUser and store.transcripts.
When identity resolves to null, the transcript bridge skips personal reads
and writes.
Resolve the current actor first
Read Identity and Memory before using a provider actor as an application user. A shared provider conversation has no personal owner, and each event resolves its actor independently.
import { createChannel } from "@copilotkit/channels";
import { accounts } from "./accounts.js";
import { makeAgent } from "./agent.js";
import { durableStateStore } from "./state-store.js";
const channel = createChannel({
name: process.env.CHANNEL_CODE,
identifyUser: async ({ provider, actor }) => {
const account = await accounts.findByExternalIdentity({
provider,
externalUserId: actor.id,
});
return account ? { id: account.id, name: account.name } : null;
},
agent: makeAgent,
store: {
adapter: durableStateStore,
transcripts: {
retention: "30d",
maxPerUser: 500,
},
},
});Provider user ids are not cross-platform identities. Resolve them to a stable
application user id, verified email, or another identity your application
controls. Returning null skips transcript storage for that turn.
The transcript list facet must be durable if this record must survive a restart.
The default MemoryStore is not sufficient.
Let runAgent bridge the transcript once
Set transcript: true to inject prior SDK transcript entries, append the
current user turn, run the agent, and capture its reply:
channel.onMessage(async ({ thread, message }) => {
await thread.runAgent({
prompt: message.text,
transcript: { limit: 20 },
});
});Do not also call channel.transcripts.append() for the same user and assistant
turns. runAgent({ transcript: ... }) owns that bridge and manual appends would
duplicate the record.
Query and delete the application record
channel.transcripts is available after the runner starts the Channel:
const recent = await channel.transcripts.list({
userId: "usr_123",
limit: 50,
});
const { deleted } = await channel.transcripts.delete({
userId: "usr_123",
});list() returns entries oldest-first. You can filter by platform, thread id, or
role. Managed entries use the native "slack" or "teams" provider. Resolve
cross-provider identity through the application userId; use the platform
filter only when you intentionally want one provider's entries.
delete() removes the SDK-owned transcript for that user; provider history and
any separate Intelligence retention policy remain independent.
See the Transcripts reference and
persistence guide before enabling this in
production.
How is this guide?