Thread - Copilotkit — ContextQMD

A Channels Thread is the SDK handle for one native conversation. Handlers, tools, and JSX callbacks receive it.

Properties

Property	Type	Description
`conversationKey`	`string`	Stable managed conversation key. Also passed to the `agent(threadId)` factory.
`platform`	`string`	Delivery adapter id. Managed Channels report `"intelligence"`; use the inbound `message.platform` for Slack/Teams branching.
`supportsBlockingChoice`	`boolean \| undefined`	`false` on the managed path. Use post-and-resume instead of `awaitChoice`.

Post and update

Method	Returns	Description
`post(ui)`	`Promise<MessageRef>`	Send text or portable JSX.
`update(ref, ui)`	`Promise<MessageRef>`	Replace a prior message.
`delete(ref)`	`Promise<void>`	Remove a prior message when supported.
`stream(source)`	`Promise<MessageRef>`	Stream text where the adapter supports streaming.
`postFile(args)`	`Promise<{ ok, fileId?, error? }>`	Upload bytes with a filename when supported.
`postEphemeral(user, ui, { fallbackToDM })`	`Promise<EphemeralResult \| null>`	Provider-capability-gated private reply. The required boolean chooses whether to fall back to a direct message.

tsx

const ref = await thread.post("Working…");
await thread.update(ref, "Done.");

The MessageRef returned by thread.post() is updateable or deletable only during the current managed delivery. Do not persist arbitrary refs and reuse them to update or delete messages across deliveries.

In a later interaction, use the interaction-provided message.ref, which Intelligence stamps for that delivery. Only attempt an update when message.ref.id is non-empty, and treat that update as best-effort.

Capability-result methods such as postFile, react, and setSuggestedPrompts can return { ok: false } when unavailable. Message operations such as update, delete, and stream can reject when the current adapter or provider cannot perform them, so catch failures when they are not allowed to fail the workflow.

Run and resume the agent

Method	Returns	Description
`runAgent(input?)`	`Promise<MessageRef \| undefined>`	Run the thread's agent and render its output.
`resume(value)`	`Promise<MessageRef \| undefined>`	Re-enter an interrupted run with a human or external result.

runAgent accepts:

Field	Type	Description
`prompt`	`string \| AgentContentPart[]`	Explicit user turn. When omitted in a message handler, the SDK injects the inbound text or content parts automatically.
`context`	`ContextEntry[]`	Context for this run only.
`tools`	`ChannelTool[]`	Tools for this run only.
`transcript`	`boolean \| { limit?: number }`	Optional SDK transcript bridge when `identity` and `transcripts` are configured.

channel.onMessage(async ({ thread, message }) => {
  await thread.runAgent({
    prompt: message.contentParts?.length
      ? [
          ...(message.text
            ? [{ type: "text" as const, text: message.text }]
            : []),
          ...message.contentParts,
        ]
      : message.text,
    context: [{ description: "Originating platform", value: message.platform }],
  });
});

For managed approvals, post a registered component, return from the interrupt handler, and call resume(value) when a later click arrives. Do not call awaitChoice; see the interactive messages guide for Slack or Teams.

Conversation history and users

Method	Returns	Description
`getMessages()`	`Promise<ThreadMessage[]>`	Managed history in chronological order; returns `[]` if unavailable.
`lookupUser(query)`	`Promise<PlatformUser \| undefined>`	Provider lookup where supported.

Per-conversation state

Method	Returns	Description
`state<T>()`	`Promise<T \| undefined>`	Read the value stored for this conversation.
`setState<T>(value)`	`Promise<void>`	Replace the full stored value. Validated when `store.state` is configured.

State uses the Channel's StateStore. Without a durable store.adapter, the default MemoryStore keeps it only in the current process. See the threads and state guide for Slack or Teams.

Provider-capability methods

Method	Purpose
`react(ref, emoji)` / `unreact(ref, emoji)`	Add or remove the bot's reaction.
`setSuggestedPrompts(prompts, options?)`	Set prompts on surfaces such as an assistant pane.
`setTitle(title)`	Name the conversation.
`subscribe()` / `unsubscribe()` / `isSubscribed()`	Store a subscription flag. Proactive routing from that flag is not implemented.

These methods are not guaranteed on managed Slack and Teams. Check { ok } when the method returns a capability result.