Session Types and Purpose

Create, list, and reopen sessions with SessionDescriptor

SessionDescriptor records how a session was created. The type field is chat or work and is used to list or reopen sessions. The non-empty kind field describes the entry point or purpose.

Use casetypekind
Agent main conversationchatmain
Remote conversationchatremote
Telegram or Feishu conversationchatchannel
Member session in a group chatchatgroup
Browser extension conversationchatchrome
Ordinary work sessionworkwork
Scheduled task executionworktask

Create and reopen sessions

Creation accepts top-level type and kind, each defaulting to work when omitted. Custom purposes use a non-empty kind. Returned Sessions, summaries and info identify the Session with id; type, kind and optional parent are also top-level fields.

const session = await agent.sessions.create({
  type: "work",
  kind: "automation/daily",
  workspace,
});

const reopened = await agent.sessions.get(session.id, "work", { workspace });
console.log(reopened.kind);

Use agent.sessions.self() to open the Agent's main conversation. The SDK creates it and saves the main session pointer on the first call. list() defaults to work and supports filtering by type and kind.

const page = await agent.sessions.list({ type: "chat", kind: "main" });

Delegate work

A delegated session records its creating Agent and Session in parent. The parent can also include the originating turn_id or tool call_id. A Chat can start a Work Main, and a Work Main can delegate to a Child. Child and Task sessions execute their assigned work directly.

Each Power owns its business references. Messenger stores the account and external conversation in its routing records. Memory tracks the execution session in its Job ledger.