Configuring Sessions

Creating a session

session = devcaster.create(user_id="user_123")

import { Devcaster } from '@devcaster/core';
const devcaster = new Devcaster({ apiKey: 'your_api_key' });
// ---cut---
const session = await devcaster.create("user_123");

Enabling toolkits

Restrict the session to specific toolkits:

# Using array format
session = devcaster.create(
    user_id="user_123",
    toolkits=["github", "gmail", "slack"]
)

# Using object format with enable key
session = devcaster.create(
    user_id="user_123",
    toolkits={"enable": ["github", "gmail", "slack"]}
)

import { Devcaster } from '@devcaster/core';
const devcaster = new Devcaster({ apiKey: 'your_api_key' });
// ---cut---
// Using array format
const session = await devcaster.create("user_123", {
  toolkits: ["github", "gmail", "slack"],
});

// Using object format with enable key
const session2 = await devcaster.create("user_123", {
  toolkits: { enable: ["github", "gmail", "slack"] },
});

Disabling toolkits

Keep all toolkits enabled except specific ones:

session = devcaster.create(
    user_id="user_123",
    toolkits={"disable": ["exa", "firecrawl"]}
)

import { Devcaster } from '@devcaster/core';
const devcaster = new Devcaster({ apiKey: 'your_api_key' });
// ---cut---
const session = await devcaster.create("user_123", {
  toolkits: { disable: ["exa", "firecrawl"] },
});

Custom auth configs

Use your own OAuth credentials instead of Devcaster's defaults:

session = devcaster.create(
    user_id="user_123",
    auth_configs={
        "github": "ac_your_github_config",
        "slack": "ac_your_slack_config"
    }
)

import { Devcaster } from '@devcaster/core';
const devcaster = new Devcaster({ apiKey: 'your_api_key' });
// ---cut---
const session = await devcaster.create("user_123", {
  authConfigs: {
    github: "ac_your_github_config",
    slack: "ac_your_slack_config",
  },
});

See White-labeling authentication for branding, or Using custom auth configs for toolkits that require your own credentials.

Account selection

If a user has multiple connected accounts for the same toolkit, you can specify which one to use:

session = devcaster.create(
    user_id="user_123",
    connected_accounts={
        "gmail": "ca_work_gmail",
        "github": "ca_personal_github"
    }
)

import { Devcaster } from '@devcaster/core';
const devcaster = new Devcaster({ apiKey: 'your_api_key' });
// ---cut---
const session = await devcaster.create("user_123", {
  connectedAccounts: {
    gmail: "ca_work_gmail",
    github: "ca_personal_github",
  },
});

Precedence

When executing a tool, the connected account is selected in this order:

connectedAccounts override if provided in session config
authConfigs override - finds or creates connection on that config
Auth config previously created for this toolkit
Creates new auth config using Devcaster managed auth
Error if no Devcaster managed auth scheme exists for the toolkit

If a user has multiple connected accounts for a toolkit, the most recently connected one is used.

Session methods

mcp

Get the MCP server URL to use with any MCP-compatible client.

mcp_url = session.mcp.url

import { Devcaster } from '@devcaster/core';
const devcaster = new Devcaster({ apiKey: 'your_api_key' });
const session = await devcaster.create("user_123");
// ---cut---
const { mcp } = session;
console.log(mcp.url);

For framework examples, see provider-specific documentation like OpenAI Agents or Vercel AI SDK.

tools()

Get native tools from the session for use with AI frameworks.

tools = session.tools()

import { Devcaster } from '@devcaster/core';
const devcaster = new Devcaster({ apiKey: 'your_api_key' });
const session = await devcaster.create("user_123");
// ---cut---
const tools = await session.tools();

authorize()

Manually authenticate a user to a toolkit outside of the chat flow.

connection_request = session.authorize("github")

print(connection_request.redirect_url)

connected_account = connection_request.wait_for_connection()

import { Devcaster } from '@devcaster/core';
const devcaster = new Devcaster({ apiKey: 'your_api_key' });
const session = await devcaster.create("user_123");
// ---cut---
const connectionRequest = await session.authorize("github", {
  callbackUrl: "https://myapp.com/callback",
});

console.log(connectionRequest.redirectUrl);

const connectedAccount = await connectionRequest.waitForConnection();

For more details, see Manually authenticating users.

toolkits()

List available toolkits and their connection status. You can use this to build a UI showing which apps are connected.

toolkits = session.toolkits()

for toolkit in toolkits.items:
    status = toolkit.connection.connected_account.id if toolkit.connection.is_active else "Not connected"
    print(f"{toolkit.name}: {status}")

import { Devcaster } from '@devcaster/core';
const devcaster = new Devcaster({ apiKey: 'your_api_key' });
const session = await devcaster.create("user_123");
// ---cut---
const toolkits = await session.toolkits();

toolkits.items.forEach((toolkit) => {
  console.log(`${toolkit.name}: ${toolkit.connection?.connectedAccount?.id ?? "Not connected"}`);
});

Returns the first 20 toolkits by default.

Configuring Sessions

On this page