Sessions

A session is the working context for one tenant/user: which tools and toolkits are visible, which connected accounts can be used, which knowledge packs are enabled, and the MCP surface the agent gets.

The session is the unit of scope

You don't pass toolkit lists on every call. You configure them once when you create the session:

A richly-scoped session

const session = await stacklink.create({
  tenantId: 'biz_123',
  userId: 'user_456',
  toolkits: { enable: ['zoho_books', 'razorpay'] },
  connectedAccounts: { zoho_books: ['acct_primary'] },
  knowledgePacks: { enable: ['in.business_compliance.authority'] },
  workbench: { enable: true, sandboxSize: 'standard' },
});

Demo placeholderOne session scoping two toolkits, a connected account, and a knowledge pack

Model surfaces

A session has one authoritative model surface. Authentication type and transport do not change it:

router

The model gets exactly six stable STACKLINK_* router tools and searches the eligible registry at runtime. This is the default for Studio, MCP, and SDK agents.

specialist

The model gets 1–10 exact provider tool keys selected when the session is created. Optional connection management counts toward the same ten-definition ceiling.

Whole-toolkit preload, preload: all, and an unbounded hybrid surface are invalid. Provider count, API-key authentication, OAuth, Knowledge, and automatic Memory never enlarge the initial model surface. Automatic Memory defaults on for identified end-user sessions; anonymous and system sessions stay off unless they explicitly declare a valid non-user grant.

Runtime waiting

Connection authorization, approval, and long-running operations are durable runtime states. The runtime suspends and resumes the session from governed events; the model does not receive polling tools. The same session projection is used by Studio, hosted MCP, API-key MCP, and SDK adapters.

Sessions have a lifecycle: active → closed / failed. Close a session when a conversation ends to release its scope; logs and evidence persist independently.

✦ Free plan

Create your first session in minutes

Sessions and everything they scope run on the free plan — 20,000 standard ops a month across 2 projects, hard-capped.

Get your API key today→No credit card or UPI mandate required