Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
feat(core): add custom tools support to session.use() via v3.1 attach
composio.use(id, { customTools, customToolkits }) now POSTs to /api/v3.1/tool_router/session/{id}/attach with inline experimental.custom_* when customs are provided, hydrating the session and binding the local tools map. Without options it keeps using the v3 retrieve endpoint. Also caches the original CustomTool[] / CustomToolkit[] arrays on CustomToolsMap so the SDK has the data needed to re-inject inline customs on subsequent v3.1 search/execute/execute_meta calls. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Abir Taheer committed
May 5, 2026 at 18:03 UTC
7534447373072421abf57677a8fdb8c8c49e0e0f
4 files changed
+69
-9
ts/packages/core/src/composio.ts
+5
-1
@@ -19,6 +19,7 @@ import { getDefaultHeaders } from './utils/session';
19
import { ToolkitVersionParam } from './types/tool.types';
20
import { ToolRouter } from './models/ToolRouter';
21
import { ToolRouterCreateSessionConfig, Session } from './types/toolRouter.types';
22
+import type { CustomTool, CustomToolkit } from './types/customTool.types';
23
import { CONFIG_DEFAULTS } from './utils/config-defaults';
24
import { expandHomeAndResolve, expandHomeAndResolveMany } from './utils/fileDirs';
25
export type ComposioConfig<
@@ -234,7 +235,10 @@ export class Composio<
235
* @param id {string} The id of the session to use
236
* @returns {Promise<Session<TToolCollection, TTool, TProvider>>} The tool router session
237
*/
237
- use: (id: string) => Promise<Session<unknown, unknown, TProvider>>;
238
+ use: (
239
+ id: string,
240
+ options?: { customTools?: CustomTool[]; customToolkits?: CustomToolkit[] }
241
+ ) => Promise<Session<unknown, unknown, TProvider>>;
242
243
/**
244
* Creates a new instance of the Composio SDK.
ts/packages/core/src/models/CustomTool.ts
+20
-4
@@ -36,7 +36,10 @@ import {
36
type CustomToolkitWireDefinition,
37
type InputParamsSchema,
38
} from '../types/customTool.types';
39
-import type { SessionCreateResponse } from '@composio/client/resources/tool-router/session/session.mjs';
39
+import type {
40
+ SessionCreateResponse,
41
+ SessionRetrieveResponse,
42
+} from '@composio/client/resources/tool-router/session/session.mjs';
43
import { ValidationError } from '../errors';
44
45
/** Prefix applied by the backend to local tool slugs for disambiguation. */
@@ -331,7 +334,12 @@ export function buildCustomToolsMap(
334
}
335
}
336
334
- return { byFinalSlug, byOriginalSlug, toolkits };
337
+ return {
338
+ byFinalSlug,
339
+ byOriginalSlug,
340
+ toolkits,
341
+ tools: tools.length ? tools : undefined,
342
+ };
343
}
344
345
/**
@@ -428,7 +436,10 @@ export function serializeCustomToolkits(
436
export function buildCustomToolsMapFromResponse(
437
tools: CustomTool[],
438
toolkits: CustomToolkit[] | undefined,
431
- experimental: SessionCreateResponse['experimental'] | undefined
439
+ experimental:
440
+ | SessionCreateResponse['experimental']
441
+ | SessionRetrieveResponse['experimental']
442
+ | undefined
443
): CustomToolsMap {
444
const byFinalSlug = new Map<string, CustomToolsMapEntry>();
445
const byOriginalSlug = new Map<string, CustomToolsMapEntry>();
@@ -478,7 +489,12 @@ export function buildCustomToolsMapFromResponse(
489
}
490
}
491
481
- return { byFinalSlug, byOriginalSlug, toolkits };
492
+ return {
493
+ byFinalSlug,
494
+ byOriginalSlug,
495
+ toolkits,
496
+ tools: tools.length ? tools : undefined,
497
+ };
498
}
499
500
/**
ts/packages/core/src/models/ToolRouter.ts
+42
-4
@@ -35,6 +35,7 @@ import {
35
SessionCreateResponse,
36
SessionRetrieveResponse,
37
} from '@composio/client/resources/tool-router/session/session.mjs';
38
+import type { CustomTool, CustomToolkit } from '../types/customTool.types';
39
import {
40
transformToolRouterTagsParams,
41
transformToolRouterToolsParams,
@@ -243,16 +244,53 @@ export class ToolRouter<
244
* console.log(session.mcp.headers);
245
* ```
246
*/
246
- async use(id: string): Promise<Session<TToolCollection, TTool, TProvider>> {
247
- const session = await this.client.toolRouter.session.retrieve(id);
247
+ async use(
248
+ id: string,
249
+ options?: { customTools?: CustomTool[]; customToolkits?: CustomToolkit[] }
250
+ ): Promise<Session<TToolCollection, TTool, TProvider>> {
251
+ const customTools = options?.customTools;
252
+ const customToolkits = options?.customToolkits;
253
+ const hasCustoms = !!(customTools?.length || customToolkits?.length);
254
+
255
+ let session: SessionRetrieveResponse;
256
+ if (hasCustoms) {
257
+ const experimentalPayload: {
258
+ custom_tools?: SessionCreateParams.Experimental.CustomTool[];
259
+ custom_toolkits?: SessionCreateParams.Experimental.CustomToolkit[];
260
+ } = {};
261
+ if (customTools?.length) {
262
+ experimentalPayload.custom_tools = serializeCustomTools(customTools);
263
+ }
264
+ if (customToolkits?.length) {
265
+ experimentalPayload.custom_toolkits = serializeCustomToolkits(customToolkits);
266
+ }
267
+ session = await this.client.post<SessionRetrieveResponse>(
268
+ `/api/v3.1/tool_router/session/${encodeURIComponent(id)}/attach`,
269
+ { body: { experimental: experimentalPayload } }
270
+ );
271
+ } else {
272
+ session = await this.client.toolRouter.session.retrieve(id);
273
+ }
274
+
275
+ let customToolsMap: CustomToolsMap | undefined;
276
+ let userId: string | undefined;
277
+ if (hasCustoms) {
278
+ customToolsMap = buildCustomToolsMapFromResponse(
279
+ customTools ?? [],
280
+ customToolkits,
281
+ session.experimental
282
+ );
283
+ userId = session.config.user_id;
284
+ }
285
+
286
return new ToolRouterSession<TToolCollection, TTool, TProvider>(
287
this.client,
288
this.config,
289
session.session_id,
290
this.createMCPServerConfig(session.mcp),
291
undefined,
254
- undefined,
255
- undefined,
292
+ customToolsMap,
293
+ userId,
294
getSessionMetadata(session)
295
);
296
}
ts/packages/core/src/types/customTool.types.ts
+2
@@ -266,6 +266,8 @@ export type CustomToolsMap = {
266
byOriginalSlug: Map<string, CustomToolsMapEntry>;
267
/** The original custom toolkits passed at session creation — used for session.customToolkits() */
268
toolkits?: CustomToolkit[];
269
+ /** The original standalone custom tools passed at session creation — kept for inline re-injection on subsequent v3.1 requests. */
270
+ tools?: CustomTool[];
271
};
272
273
// ────────────────────────────────────────────────────────────────