Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
/**
* ToolRouter class for managing tool router sessions.
*
* @description Allows you to create an isolated toolRouter MCP session for a user
* @example
* ```typescript
* import { Composio } from '@composio/core';
*
* const composio = new Composio();
* const userId = 'user_123';
*
* const session = await composio.sessions.create(userId, {
* toolkits: ['gmail'],
* manageConnections: true
* });
*
* console.log(session.mcp.url);
* ```
*/
import { Composio as ComposioClient } from '@composio/client';
import { telemetry } from '../telemetry/Telemetry';
import type { BaseComposioProvider } from '../provider/BaseProvider';
import type { ComposioConfig } from '../composio';
import {
ToolRouterCreateSessionConfig,
Session,
SessionWithoutMcp,
MCPServerType,
ToolRouterMCPServerConfig,
ToolRouterSessionMetadata,
SessionPreset,
type ToolRouterSessionDeleteResponse,
} from '../types/toolRouter.types';
import { ToolRouterCreateSessionConfigSchema } from '../types/toolRouter.types';
import {
SessionAttachResponse,
SessionCreateParams,
SessionCreateResponse,
SessionRetrieveResponse,
} from '@composio/client/resources/tool-router/session/session.mjs';
import type {
CustomTool,
CustomToolkit,
InlineCustomToolsWirePayload,
} from '../types/customTool.types';
import {
transformToolRouterTagsParams,
transformToolRouterToolsParams,
transformToolRouterManageConnectionsParams,
transformToolRouterSandboxParams,
transformToolRouterToolkitsParams,
transformToolRouterMultiAccountParams,
resolveToolRouterSandboxConfig,
} from '../lib/toolRouterParams';
import { PRELOAD_TOOLS_ALL } from '../lib/toolRouterConstants';
import { ToolRouterSession } from './ToolRouterSession';
import { ComposioRequestOptions } from '../types/requestOptions.types';
import { withCancellation } from '../utils/cancellation';
import { deleteToolRouterSession } from '../lib/toolRouterSessionDelete';
import {
assertNoCustomToolSlugsInPreload,
buildCustomToolsMap,
buildCustomToolsMapFromResponse,
getPreloadedCustomToolSlugs,
serializeCustomTools,
serializeCustomToolkits,
} from './CustomTool';
import type { CustomToolsMap } from '../types/customTool.types';
function getSessionMetadata(
session: SessionCreateResponse | SessionRetrieveResponse | SessionAttachResponse
) {
const metadata: ToolRouterSessionMetadata = {
preload: session.config.preload,
workbench: session.config.workbench,
configVersion: session.config_version,
warnings: 'warnings' in session ? (session.warnings ?? []) : [],
};
return metadata;
}
function preloadsAllCustomTools(preload?: { tools?: readonly string[] | string }): boolean {
return preload?.tools === PRELOAD_TOOLS_ALL;
}
function prepareInlineCustomTools(options: {
customTools?: CustomTool[];
customToolkits?: CustomToolkit[];
defaultPreload?: boolean;
preloadTools?: readonly string[] | typeof PRELOAD_TOOLS_ALL;
}): InlineCustomToolsWirePayload | undefined {
const { customTools, customToolkits, defaultPreload = false, preloadTools } = options;
const hasCustoms = !!(customTools?.length || customToolkits?.length);
const localCustomToolsMap = hasCustoms
? buildCustomToolsMap(customTools ?? [], customToolkits)
: undefined;
// Top-level preload.tools is for Composio-managed slugs only. Custom tools
// use their own preload flag, so reject LOCAL/custom slugs there before
// serializing the inline custom definitions.
assertNoCustomToolSlugsInPreload(preloadTools, localCustomToolsMap);
const serializedTools = customTools?.length
? serializeCustomTools(customTools, { defaultPreload })
: undefined;
const serializedToolkits = customToolkits?.length
? serializeCustomToolkits(customToolkits, { defaultPreload })
: undefined;
const inlineCustomToolsPayload =
serializedTools || serializedToolkits
? {
...(serializedTools ? { custom_tools: serializedTools } : {}),
...(serializedToolkits ? { custom_toolkits: serializedToolkits } : {}),
}
: undefined;
return inlineCustomToolsPayload;
}
export class ToolRouter<
TToolCollection,
TTool,
TProvider extends BaseComposioProvider<TToolCollection, TTool, unknown>,
> {
constructor(
private client: ComposioClient,
private config?: ComposioConfig<TProvider>
) {
telemetry.instrument(this, 'ToolRouter');
}
private createMCPServerConfig({
type,
url,
}: {
type: MCPServerType;
url: string;
}): ToolRouterMCPServerConfig {
return {
type,
url,
headers: {
...(this.config?.apiKey ? { 'x-api-key': this.config.apiKey } : {}),
},
};
}
/**
* Creates a new tool router session for a user.
* Use `sessionPreset: SessionPreset.DIRECT_TOOLS` when all needed tools
* should be exposed directly; see `ToolRouterCreateSessionConfig`.
*
* @param userId {string} The user id to create the session for
* @param config {ToolRouterCreateSessionConfig} The config for the tool router session
* @returns {Promise<Session<TToolCollection, TTool, TProvider>>} The tool router session
*
* @example
* ```typescript
* import { Composio } from '@composio/core';
*
* const composio = new Composio();
*
* const session = await composio.sessions.create('user_123', {
* toolkits: ['gmail'],
* manageConnections: true,
* experimental: {
* customTools: [myCustomTool],
* customToolkits: [myToolkit],
* },
* });
* ```
*/
// Overloads: passing `{ mcp: true }` surfaces `session.mcp` in the returned
// type. Otherwise the MCP endpoint is omitted from the type (it still exists
// at runtime). See https://docs.composio.dev/docs/sessions-via-mcp
async create(
userId: string,
config: ToolRouterCreateSessionConfig & { mcp: true },
requestOptions?: ComposioRequestOptions
): Promise<Session<TToolCollection, TTool, TProvider>>;
async create(
userId: string,
config?: ToolRouterCreateSessionConfig,
requestOptions?: ComposioRequestOptions
): Promise<SessionWithoutMcp<TToolCollection, TTool, TProvider>>;
async create(
userId: string,
config?: ToolRouterCreateSessionConfig,
requestOptions?: ComposioRequestOptions
): Promise<Session<TToolCollection, TTool, TProvider>> {
const routerConfig = ToolRouterCreateSessionConfigSchema.parse(config ?? {});
const isDirectToolsPreset = routerConfig.sessionPreset === SessionPreset.DIRECT_TOOLS;
// Extract custom tools/toolkits from experimental config
const customTools = routerConfig.experimental?.customTools;
const customToolkits = routerConfig.experimental?.customToolkits;
const defaultCustomPreload = preloadsAllCustomTools(routerConfig.preload);
const inlineCustomToolsPayload = prepareInlineCustomTools({
customTools,
customToolkits,
defaultPreload: defaultCustomPreload,
preloadTools: routerConfig.preload?.tools,
});
// Build the typed experimental payload for the backend
const experimentalPayload: SessionCreateParams['experimental'] = {};
if (routerConfig.experimental?.assistivePrompt?.userTimezone) {
experimentalPayload.assistive_prompt_config = {
user_timezone: routerConfig.experimental.assistivePrompt.userTimezone,
};
}
if (inlineCustomToolsPayload?.custom_tools) {
experimentalPayload.custom_tools = inlineCustomToolsPayload.custom_tools;
}
if (inlineCustomToolsPayload?.custom_toolkits) {
experimentalPayload.custom_toolkits = inlineCustomToolsPayload.custom_toolkits;
}
const multiAccountPayload = transformToolRouterMultiAccountParams(routerConfig.multiAccount);
const sandboxPayload = transformToolRouterSandboxParams(
resolveToolRouterSandboxConfig(routerConfig)
);
const connectedAccountsPayload =
routerConfig.connectedAccounts === undefined
? undefined
: Object.fromEntries(
Object.entries(routerConfig.connectedAccounts).map(([toolkit, ids]) => [
toolkit,
typeof ids === 'string' ? [ids] : ids,
])
);
const payload: SessionCreateParams = {
user_id: userId,
auth_configs: routerConfig.authConfigs,
connected_accounts: connectedAccountsPayload,
toolkits: transformToolRouterToolkitsParams(routerConfig.toolkits),
tools: transformToolRouterToolsParams(routerConfig.tools),
tags: transformToolRouterTagsParams(routerConfig.tags),
manage_connections: transformToolRouterManageConnectionsParams(
routerConfig.manageConnections
),
workbench: sandboxPayload,
multi_account: multiAccountPayload,
preload: routerConfig.preload,
...(isDirectToolsPreset && {
search: { enable: false },
execute: { enable_multi_execute: false },
}),
experimental: Object.keys(experimentalPayload).length > 0 ? experimentalPayload : undefined,
};
const session = await withCancellation(
() => this.client.toolRouter.session.create(payload, requestOptions),
requestOptions?.signal
);
// Build custom tools map from the response's slug/original_slug mapping
// instead of computing LOCAL_ prefix client-side
let customToolsMap: CustomToolsMap | undefined;
if (customTools?.length || customToolkits?.length) {
customToolsMap = buildCustomToolsMapFromResponse(
customTools ?? [],
customToolkits,
session.experimental
);
}
const metadata = {
...getSessionMetadata(session),
preloadedCustomToolSlugs: getPreloadedCustomToolSlugs(customToolsMap, defaultCustomPreload),
inlineCustomToolsPayload,
};
const assistivePrompt = session.experimental?.assistive_prompt;
return new ToolRouterSession<TToolCollection, TTool, TProvider>(
this.client,
this.config,
session.session_id,
this.createMCPServerConfig(session.mcp),
{ assistivePrompt },
customToolsMap,
userId,
metadata
);
}
/**
* Use an existing session
* @param id {string} The id of the session to use
* @returns {Promise<Session<TToolCollection, TTool, TProvider>>} The tool router session
*
* @example
* ```typescript
* import { Composio } from '@composio/core';
*
* const composio = new Composio();
* const id = 'session_123';
* const session = await composio.sessions.use(id);
*
* console.log(session.mcp.url);
* console.log(session.mcp.headers);
* ```
*/
// Overloads mirror `create()`: pass `{ mcp: true }` to surface `session.mcp`
// in the returned type. See https://docs.composio.dev/docs/sessions-via-mcp
async use(
id: string,
options: { customTools?: CustomTool[]; customToolkits?: CustomToolkit[]; mcp: true },
requestOptions?: ComposioRequestOptions
): Promise<Session<TToolCollection, TTool, TProvider>>;
async use(
id: string,
options?: { customTools?: CustomTool[]; customToolkits?: CustomToolkit[]; mcp?: boolean },
requestOptions?: ComposioRequestOptions
): Promise<SessionWithoutMcp<TToolCollection, TTool, TProvider>>;
async use(
id: string,
options?: { customTools?: CustomTool[]; customToolkits?: CustomToolkit[]; mcp?: boolean },
requestOptions?: ComposioRequestOptions
): Promise<Session<TToolCollection, TTool, TProvider>> {
const customTools = options?.customTools;
const customToolkits = options?.customToolkits;
const hasCustoms = !!(customTools?.length || customToolkits?.length);
let session: SessionRetrieveResponse | SessionAttachResponse;
const attachInlineCustomToolsPayload = prepareInlineCustomTools({
customTools,
customToolkits,
});
let inlineCustomToolsPayload = attachInlineCustomToolsPayload;
if (hasCustoms) {
const attachBody = { experimental: attachInlineCustomToolsPayload };
session = await withCancellation(
() => this.client.toolRouter.session.attach(id, attachBody, requestOptions),
requestOptions?.signal
);
} else {
session = await withCancellation(
() => this.client.toolRouter.session.retrieve(id, requestOptions),
requestOptions?.signal
);
}
const defaultCustomPreload = preloadsAllCustomTools(session.config.preload);
if (hasCustoms && defaultCustomPreload) {
// preload.tools = "all" on the existing session is server-authoritative:
// the backend exposes every custom tool regardless of per-definition
// preload flags, so the initial attach above (which used the caller's
// explicit hints) doesn't need re-sending. We only rebuild the in-memory
// payload so future search/execute calls re-inject with preload=true and
// session.tools() locally mirrors what the server returns.
inlineCustomToolsPayload = prepareInlineCustomTools({
customTools,
customToolkits,
defaultPreload: true,
});
}
let customToolsMap: CustomToolsMap | undefined;
let userId: string | undefined;
if (hasCustoms) {
customToolsMap = buildCustomToolsMapFromResponse(
customTools ?? [],
customToolkits,
session.experimental
);
userId = session.config.user_id;
}
const metadata = {
...getSessionMetadata(session),
preloadedCustomToolSlugs: getPreloadedCustomToolSlugs(customToolsMap, defaultCustomPreload),
inlineCustomToolsPayload,
};
return new ToolRouterSession<TToolCollection, TTool, TProvider>(
this.client,
this.config,
session.session_id,
this.createMCPServerConfig(session.mcp),
undefined,
customToolsMap,
userId,
metadata
);
}
/**
* Delete a tool router session by ID.
*
* Deleted sessions immediately stop being retrievable or executable. Deleting
* a missing or already-deleted session surfaces the backend 404.
*/
async delete(
id: string,
requestOptions?: ComposioRequestOptions
): Promise<ToolRouterSessionDeleteResponse> {
return deleteToolRouterSession(this.client, id, requestOptions);
}
}