Sessions

A session is the agent's view of Dexby for one user. It sets which apps and tools are in reach and what the agent may do. The model gets a few meta tools to search those tools and run them, so a catalog of thousands of tools costs a handful of definitions.

import { Dexby } from '@dexby.ai/sdk'

const dexby = new Dexby()

const created = await dexby.createSession({
	userId: 'user_123',
	connectors: ['slack', 'github'],
	pinned: ['slack_post_message'],
	policy: { readOnly: false, maxDataClass: 'pii' }
})
if (created.isErr()) throw new Error(created.error.message)
const session = created.value

Give session.tools() to your framework (Frameworks), or connect an MCP client to session.mcpUrl (MCP).

OptionsCopy Anchor Link

session.state shows each app in scope with the user's connection status.

The scope covers catalog tools and the project's custom tools: MCP server tools (connector mcp:<id>) and imported REST operations (connector openapi:<prefix>). The same options apply to all of them. MCP server tools count as write and pii, so policy.readOnly or maxDataClass: 'standard' leaves them out. Tools classified phi are in scope only when the project handles health data.

Meta toolsCopy Anchor Link

Pinned tools come after the meta tools under their own ids.

RefusalsCopy Anchor Link

When a call cannot run, the tool returns { ok: false, error } to the model, for example connection_required when the app is not connected. The request can succeed at the HTTP level while the tool returns a refusal; this does not mean the action succeeded. The error message tells the model what to do next. Every code is listed in Errors.

AccountsCopy Anchor Link

When a user has several accounts for one app, a call uses the first of:

1. The account the call names.
2. The session's accounts entry for the app.
3. The user's default account.
4. The only active account.

Several accounts and no default: the model gets account_selection_required with the choices, and asks the user. An app that needs no sign-in reports not_required and runs with nothing connected.

Global accountsCopy Anchor Link

The project's global accounts are opt-in per session:

const created = await dexby.createSession({ userId: 'user_123', allowGlobalAccounts: true })

• allowGlobalAccounts: false (the default): global accounts do not exist for the session. The session state, dexby_list_connections, account choices and dexby_execute leave them out, and dexby_connect_account never suggests one. A user without an account of their own gets connection_required, even when the call names a global account.
• allowGlobalAccounts: true: global accounts are listed beside the user's own, marked global: true, and chosen by the usual rule. A name that matches both one of the user's accounts and a global account is never guessed.

Either way, a global account runs only the actions an admin allowed it. Anything else is refused with not_permitted, and nothing is sent to the app.

Your own loopCopy Anchor Link

Without a framework, get the definitions and run each call the model makes:

const definitions = await session.definitions('openai-strict') // or 'json-schema'
const outcome = await session.call('dexby_search_actions', { queries: ['post a slack message'] })

See Frameworks for Anthropic, OpenAI, Gemini and Bedrock loops.