Session Origin and Types

Every Session has an origin, made of two fields: category and type. They answer different questions, and you decide both.

category is the classification, with exactly two values: chat and work. It decides which physical partition the session lives in, and whether it can dispatch work. type is the role, describing what the session actually is. The category answers "which layer", the role answers "what it is".

Which category to use

Ask one question: is this session for talking, or for doing work?

Omitting origin defaults to { category: "work", type: "work" }, an ordinary work session.

What the category controls

Physical partition. Sessions live under sessions/<category>/<session_id>/. There are only two categories, so an Agent's session directories are at most two levels wide. The same session_id can exist under chat and under work at the same time without conflict — identity is the category plus the ID.

Whether it can dispatch work. Sessions in chat can start, check, reply to and stop other sessions, and can archive them. Sessions in work focus on the job they were handed and do not dispatch further. Only work sessions can be archived.

The role does not shape the partition. It only affects specific behavior branches, such as picking a platform prompt for external chats or validating group membership.

Open a conversation session

const session = await agent.sessions.create({
  origin: { category: "chat", type: "agent" },
  workspace,
});

Dispatch a piece of work

const work = await agent.sessions.create({
  origin: { category: "work", type: "work" },
  workspace,
});

const turn = await work.prompt({ query: "Turn this report into a table" });
await turn.finished;

List sessions by category and role

The first dimension of list is the category. Add the role when the category alone is not specific enough.

// Every session in one category
const conversations = await agent.sessions.list({ category: "chat" });

// Only the Agent's own main session
const main = await agent.sessions.list({
  category: "chat",
  origin_type: "agent",
});

Restoring an existing session also takes the category:

const session = await agent.sessions.get(session_id, "chat", { workspace });

Custom roles

The six known roles cover the common cases. If your product has its own notion of a session, you can declare a custom role, but you must also give the category. Otherwise creation fails outright:

const session = await agent.sessions.create({
  origin: {
    category: "work",
    type: "automation/daily",
    schedule_id: "daily-report",
  },
});

The category has to be chat or work, because it is the only field that decides the partition and the dispatch ability. The role name can be any non-empty string. Fields beyond those two are persisted with the origin and interpreted by you.

This constraint is deliberate: adding a role costs nothing, while adding a partition has to be stated explicitly. A typo in a string can never silently drop your session into a different directory.