Patterns

One App-owned Agent, many tenants

Create shared behavior once, then state the tenant on each Turn:

const support = await client.agent("support");
 
await support.run("Summarize the request.", { tenant: "acme", user: "alice" });
await support.run("Summarize the request.", { tenant: "globex", user: "sam" });

One Conversation, changing behavior

A Conversation is not bound to an Agent. Your host may deliberately continue the same transcript with a different Agent on a later Turn. Keep that handoff explicit in product code so the behavior change is reviewable.

Parallel work

One Conversation allows one nonterminal Turn. Run independent work as standalone Turns or on separate Conversations, then combine the results in your application. Use triggered_by on exact HTTP admission when causal lineage to a parent Turn and ToolCall matters.

Shared tenant memory

Several users or Agents can intentionally select the same tenant MemorySpace:

await support.text("Remember the escalation policy.", {
  tenant: "acme",
  user: "alice",
  memory: { scope: "tenant", namespace: "support-team" },
});

The namespace is a host-selected sharing decision, not proof of membership.

Recover uncertain admission

Generate an idempotency key from the host operation, persist it with the Turn ID, and retry only the exact logical start. Never interpret a local timeout as remote cancellation.