Conversations

A Conversation is optional ordered transcript continuity. It has an explicit tenant or user owner and at most one nonterminal Turn. It never selects an Agent, actor, or MemorySpace.

Bind a reusable Conversation workflow

const agent = await client.agent("support");
const chat = agent.conversation({
  tenant: "acme",
  user: "alice",
  key: "ticket-483",
  owner: "user",
});
 
await chat.text("Remember that the order number is 1842.");
console.log(await chat.text("What is the order number?"));

The bound handle carries tenant, optional user, Conversation selection, memory, and default narrowed limits. Each start, run, or text call creates a new Turn with the same continuity.

Create-time options

Keyed selection can define immutable creation policy:

const chat = agent.conversation({
  tenant: "acme",
  key: "temporary-research",
  owner: "tenant",
  retention: { ttlSeconds: 86_400 },
  ifActive: "reject",
  metadata: { source: "research-panel" },
});

ifActive may be reject, supersede, or interrupt. The SDK serializes calls made through one bound handle, while the server policy handles competing callers.

Select an existing Conversation by ID

const chat = agent.conversation({
  tenant: "acme",
  id: "019b0a13-6e08-7b52-9d41-2af7c9e30b16",
});

ID selection does not repeat the owner or key. The runtime still verifies the Conversation belongs to the asserted App and tenant.

Read and stream exact resources

Use client.raw().conversations to list Conversations, read messages and compactions, drain a transcript, fork, update metadata, delete retained content, or open the long-lived Conversation stream.

A Conversation stream may remain open while idle. A Turn stream closes after that Turn ends.