@dexby.ai/sdk

TypeScript client for the Dexby API.

Install

bun add @dexby.ai/sdk
# or: npm install @dexby.ai/sdk

ESM only. A framework provider also needs its framework installed; each is an optional peer dependency:

| Import | Install alongside | | --------------------------------------- | ------------------------------- | | @dexby.ai/sdk/providers/ai-sdk | ai (5, 6, or 7) | | @dexby.ai/sdk/providers/mastra | @mastra/core (^1.71.0) | | @dexby.ai/sdk/providers/langchain | @langchain/core (^1.2.13) | | @dexby.ai/sdk/providers/openai-agents | @openai/agents (^0.18.0) | | @dexby.ai/sdk/providers/llamaindex | @llamaindex/core (^0.6.23) | | @dexby.ai/sdk/providers/genkit | genkit (^1.42.0) | | @dexby.ai/sdk/providers/google-adk | @google/adk (^2.1.0) | | @dexby.ai/sdk/providers/strands | @strands-agents/sdk (^1.19.0) |

The root export and the openai, openai-responses, anthropic, gemini and bedrock providers need no extra package.

Client

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

const dexby = new Dexby({ userId: 'user_123' })

apiKey defaults to DEXBY_API_KEY; the key decides the project. userId is the default end user for sessions, executions and connect links; each call can override it. baseURL defaults to DEXBY_API_URL, else https://api.dexby.ai. mcpURL defaults to DEXBY_MCP_URL, else https://mcp.dexby.ai; self-hosted setups set it to <baseURL>/v1/mcp.

Execute

Runs one action directly, as one user:

const result = await dexby.execute({
	toolId: 'slack_post_message',
	input: { channel: 'general', text: 'Alert triggered' }
})

searchTools(query?), searchConnectors({ query, category }) and getConnector(id) read the catalog.

Sessions

A session is what one agent may find and run for one end user. Its scope is the project's enabled connectors, narrowed by connectors, actions (ids or prefix* patterns) and policy (readOnly, maxDataClass, allowDisconnect, allowProxy). The agent gets Dexby's meta tools (dexby_search_actions, dexby_get_action_schemas, dexby_execute and others) plus up to 20 pinned actions as full definitions.

import { AiSdkProvider } from '@dexby.ai/sdk/providers/ai-sdk'

const dexby = new Dexby({ provider: new AiSdkProvider() })

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

const tools = await session.tools() // for the model, in the provider's format
// Your own loop instead: give the model these, then run each call it makes.
const definitions = await session.definitions('openai-strict')
const outcome = await session.call(toolName, toolArgs)

A refusal, such as an app that is not connected, comes back as { ok: false, error } for the model to act on. When a user has several accounts for one app, a call uses the account it names, else the one accounts pins, else the user's default. The project's global accounts, which an admin connected once for every user of the project, are left out unless the session is created with allowGlobalAccounts: true; then they carry global: true, are never a user's default, and run only the actions an admin allowed each one. dexby.execute takes the same allowGlobalAccounts option, and uses a global account without it only when connectionId names one. An app that needs no sign-in reports not_required and runs with nothing connected. MCP clients use the same session at session.mcpUrl, with the project API key as a Bearer token.

The provider sets the format and the type of session.tools(). The default is OpenAI function calling (OpenAiProvider).

• Frameworks, whose tools run through the session on their own: AiSdkProvider (ai), MastraProvider (@mastra/core), LangChainProvider (@langchain/core), OpenAiAgentsProvider (@openai/agents), LlamaIndexProvider (@llamaindex/core), GenkitProvider (genkit), GoogleAdkProvider (@google/adk), StrandsProvider (@strands-agents/sdk). Each framework is an optional peer dependency, loaded only by its own provider's import.
• Model APIs, whose definitions your loop runs with session.call(): OpenAiProvider (Chat Completions and compatible APIs), OpenAiResponsesProvider, AnthropicProvider, GeminiProvider, BedrockProvider. They need no extra package.

Connect links

createConnectLink() returns a single-use link to the hosted Connect page, where the end user connects their own accounts. connectors or authConfigs narrow what it offers; expiresInMinutes defaults to 30. Set allowGlobalAccounts when the user's calls may use the project's global accounts, so the page shows those apps as already available.

const link = await dexby.createConnectLink({
	connectors: ['slack', 'stripe'],
	redirectUrl: 'https://app.example.com/integrations'
})
if (link.isOk()) sendToUser(link.value.url)

Triggers (createTrigger, listTriggers, deleteTrigger) deliver provider events to the project's webhooks as trigger.fired. mcpUrl(slug, userId?) builds the URL for one of the project's MCP endpoints: <mcpURL>/<slug>/<userId>, with the user id percent-encoded.

With a provider, one chain opens the session and returns its tools, typed for the framework:

const tools = await dexby
	.createSession({ userId: 'user_123', connectors: ['slack'] })
	.andThen((session) => session.tools())
if (tools.isErr()) throw new Error(tools.error.message)

await generateText({ model, tools: tools.value, stopWhen: stepCountIs(8), prompt })

Errors

Calls that reach the API return a neverthrow ResultAsync: await it for a Result, or chain it with andThen and map. An SdkError carries the API's code and message, plus choices for AMBIGUOUS_CONNECTION (each with id, displayName and global) and issues for VALIDATION_ERROR. A code this SDK version does not know arrives as UNKNOWN; a cancelled request as CANCELLED.

Exports

• .: Dexby, Session, OpenAiProvider, dexbyConfigSchema, and types
• ./contracts: config schema and shared types
• ./providers/<name>, one per provider: openai, openai-responses, anthropic, gemini, bedrock, ai-sdk, mastra, langchain, openai-agents, llamaindex, genkit, google-adk, strands