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
/**
* @fileoverview Factory functions for creating custom tools and toolkits.
*
* Usage:
* ```typescript
* import { experimental_createTool, experimental_createToolkit } from '@composio/core';
*
* const grep = createCustomTool('GREP', {
* name: 'Grep Search',
* description: 'Search for patterns in files',
* inputParams: z.object({ pattern: z.string() }),
* execute: async (input) => ({ matches: [] }),
* });
*
* const devTools = createCustomToolkit('DEV_TOOLS', {
* name: 'Dev Tools',
* description: 'Local dev utilities',
* tools: [grep],
* });
* ```
*/
import {
CreateCustomToolBaseSchema,
CreateCustomToolkitBaseSchema,
CustomToolSlugSchema,
type AnyZodSchema,
type CreateCustomToolParams,
type CreateCustomToolkitParams,
type CustomTool,
type CustomToolkit,
type CustomToolExecuteFn,
type CustomToolsMap,
type CustomToolsMapEntry,
type CustomToolWireDefinition,
type CustomToolkitWireDefinition,
} from '../types/customTool.types';
import type {
SessionCreateResponse,
SessionRetrieveResponse,
} from '@composio/client/resources/tool-router/session/session.mjs';
import { ValidationError } from '../errors';
import { PRELOAD_TOOLS_ALL } from '../lib/toolRouterConstants';
import {
isZodObjectSchema,
zodObjectSchemaToJsonSchema,
zodSchemaToJsonSchema,
} from '../utils/zodSchema';
/** Prefix applied by the backend to local tool slugs for disambiguation. */
export const LOCAL_TOOL_PREFIX = 'LOCAL_';
/** Maximum allowed length for the final prefixed slug. */
const MAX_SLUG_LENGTH = 60;
type InputParamsSchema = {
definitions: {
input: {
type: string;
properties: Record<string, unknown>;
required?: string[];
};
};
};
/**
* Compute the final slug length for a tool given its context.
* Returns the expected length of LOCAL_[TOOLKIT_]SLUG.
*/
function computeFinalSlugLength(toolSlug: string, toolkitSlug?: string): number {
// LOCAL_ + optional TOOLKIT_ + SLUG
return (
LOCAL_TOOL_PREFIX.length +
(toolkitSlug ? toolkitSlug.length + 1 : 0) + // +1 for underscore separator
toolSlug.length
);
}
/**
* Validate that the final slug won't exceed the max length.
* Called early in createCustomTool/createCustomToolkit for fast feedback.
*/
function validateSlugLength(
toolSlug: string,
toolkitSlug: string | undefined,
context: string
): void {
const finalLength = computeFinalSlugLength(toolSlug, toolkitSlug);
if (finalLength > MAX_SLUG_LENGTH) {
const prefix = LOCAL_TOOL_PREFIX + (toolkitSlug ? `${toolkitSlug.toUpperCase()}_` : '');
const available = MAX_SLUG_LENGTH - prefix.length;
throw new ValidationError(
`${context}: slug "${toolSlug}" is too long. ` +
`With prefix "${prefix}", the final slug would be ${finalLength} characters (max ${MAX_SLUG_LENGTH}). ` +
`Shorten the slug to at most ${available} characters.`
);
}
}
/**
* Create a custom tool for use in tool router sessions.
*
* The returned object is a lightweight reference containing the tool's metadata
* and execute function. Pass it to `composio.create(userId, { experimental: { customTools: [...] } })`
* to bind it to a session.
*
* Just return the result data from `execute`, or throw an error.
* The SDK wraps it into the standard response format internally.
*
* **Slug naming:** The slug you provide is automatically prefixed with `LOCAL_` when
* exposed to the agent (e.g. `'GREP'` becomes `LOCAL_GREP`). If the tool is inside a
* custom toolkit, the toolkit slug is also included (e.g. `LOCAL_DEV_TOOLS_GREP`).
* The `LOCAL_` prefix is reserved and cannot be used in your slug.
*
* @param slug - Unique tool identifier (alphanumeric, underscores, hyphens; no LOCAL_ or COMPOSIO_ prefix)
* @param options - Tool definition including name, schema, and execute function
* @returns A CustomTool to pass to session creation
*
* @example Standalone tool (no auth)
* ```typescript
* const grep = createCustomTool('GREP', {
* name: 'Grep Search',
* description: 'Search for patterns in files',
* inputParams: z.object({ pattern: z.string(), path: z.string() }),
* execute: async (input) => ({ matches: [] }),
* });
* ```
*
* @example Tool extending a Composio toolkit (inherits auth)
* ```typescript
* const getImportant = createCustomTool('GET_IMPORTANT_EMAILS', {
* name: 'Get Important Emails',
* description: 'Fetch high-priority emails',
* extendsToolkit: 'gmail',
* inputParams: z.object({ limit: z.number().default(10) }),
* execute: async (input, ctx) => {
* // Same response shape as session.execute(): { data, error, logId }
* const result = await ctx.execute('GMAIL_SEARCH', { query: 'is:important' });
* return { emails: result.data };
* },
* });
* ```
*/
export function createCustomTool<T extends AnyZodSchema>(
slug: string,
options: CreateCustomToolParams<T>
): CustomTool {
// Validate slug separately
const slugResult = CustomToolSlugSchema.safeParse(slug);
if (!slugResult.success) {
throw new ValidationError(`createCustomTool: ${slugResult.error.issues[0].message}`, {
cause: slugResult.error,
});
}
// Validate string/scalar fields via Zod schema
const validated = CreateCustomToolBaseSchema.parse(options);
// Manual checks for fields Zod can't validate
if (!options.inputParams) {
throw new ValidationError('createCustomTool: inputParams is required');
}
if (!isZodObjectSchema(options.inputParams)) {
throw new ValidationError(
'createCustomTool: inputParams must be a z.object() schema. ' +
'Tool input parameters are always an object with named properties.'
);
}
if (typeof options.execute !== 'function') {
throw new ValidationError('createCustomTool: execute must be a function');
}
// Early length validation (standalone or extension — we know both parts)
validateSlugLength(slug, validated.extendsToolkit, 'createCustomTool');
const { inputParams, execute } = options;
// Convert Zod input schema → JSON Schema (inputParams is guaranteed to be z.object)
const inputSchema = zodObjectSchemaToJsonSchema(inputParams, 'input');
// Convert Zod output schema → JSON Schema (if provided, any Zod type allowed)
let outputSchema: Record<string, unknown> | undefined;
if (options.outputParams) {
outputSchema = zodSchemaToJsonSchema(options.outputParams, 'output');
}
return {
slug: slugResult.data,
name: validated.name,
description: validated.description,
extendsToolkit: validated.extendsToolkit,
preload: validated.preload,
inputSchema,
outputSchema,
inputParams,
execute: execute as CustomToolExecuteFn<AnyZodSchema>,
};
}
/**
* Create a custom toolkit that groups related tools.
*
* Tools passed here must NOT have `extendsToolkit` set — they inherit the toolkit identity instead.
*
* **Slug naming:** The toolkit slug becomes part of the final tool slug exposed to the agent.
* For example, a toolkit `'DEV_TOOLS'` with a tool `'GREP'` produces `LOCAL_DEV_TOOLS_GREP`.
* The `LOCAL_` prefix is reserved and cannot be used in your slug.
*
* @param slug - Unique toolkit identifier (alphanumeric, underscores, hyphens; no LOCAL_ or COMPOSIO_ prefix)
* @param options - Toolkit definition including name, description, and tools
* @returns A CustomToolkit to pass to session creation
*
* @example
* ```typescript
* const devTools = createCustomToolkit('DEV_TOOLS', {
* name: 'Dev Tools',
* description: 'Local dev utilities',
* tools: [grepTool, sedTool],
* });
* ```
*/
export function createCustomToolkit(
slug: string,
options: CreateCustomToolkitParams
): CustomToolkit {
// Validate slug
const slugResult = CustomToolSlugSchema.safeParse(slug);
if (!slugResult.success) {
throw new ValidationError(`createCustomToolkit: ${slugResult.error.issues[0].message}`, {
cause: slugResult.error,
});
}
// Validate name/description
const validated = CreateCustomToolkitBaseSchema.parse(options);
// Non-empty tools required
if (!options.tools?.length) {
throw new ValidationError('createCustomToolkit: at least one tool is required');
}
// Validate each tool
for (const tool of options.tools) {
// Reject tools with extendsToolkit
if (tool.extendsToolkit) {
throw new ValidationError(
`createCustomToolkit: tool "${tool.slug}" has extendsToolkit set. ` +
`Tools in a custom toolkit must not use extendsToolkit — they inherit the toolkit identity instead.`
);
}
// Early length validation — we know both toolkit slug and tool slug
validateSlugLength(tool.slug, slug, `createCustomToolkit("${slug}")`);
}
return {
slug: slugResult.data,
name: validated.name,
description: validated.description,
preload: validated.preload,
tools: options.tools,
};
}
/**
* Build the final slug for a custom tool given its context.
* @internal
*/
function buildFinalSlug(toolSlug: string, toolkitSlug?: string): string {
const upper = toolSlug.toUpperCase();
return toolkitSlug
? `${LOCAL_TOOL_PREFIX}${toolkitSlug.toUpperCase()}_${upper}`
: `${LOCAL_TOOL_PREFIX}${upper}`;
}
const qualifiedOriginalSlugKey = (toolkit: string | undefined, originalSlug: string): string =>
`${toolkit?.toUpperCase() ?? ''}::${originalSlug.toUpperCase()}`;
const canShareOriginalSlug = (existing: CustomToolsMapEntry, next: CustomToolsMapEntry): boolean =>
!!existing.toolkit &&
!!next.toolkit &&
existing.toolkit.toLowerCase() !== next.toolkit.toLowerCase();
const addOriginalSlugAlias = (params: {
byOriginalSlug: Map<string, CustomToolsMapEntry>;
ambiguousOriginalSlugs: Set<string>;
originalSlug: string;
entry: CustomToolsMapEntry;
}) => {
const originalSlugKey = params.originalSlug.toUpperCase();
if (params.ambiguousOriginalSlugs.has(originalSlugKey)) {
return;
}
const existing = params.byOriginalSlug.get(originalSlugKey);
if (!existing) {
params.byOriginalSlug.set(originalSlugKey, params.entry);
return;
}
if (existing.finalSlug.toUpperCase() === params.entry.finalSlug.toUpperCase()) {
return;
}
if (canShareOriginalSlug(existing, params.entry)) {
params.byOriginalSlug.delete(originalSlugKey);
params.ambiguousOriginalSlugs.add(originalSlugKey);
return;
}
throw new ValidationError(
`Custom tool slug collision: original slug "${params.originalSlug}" maps to multiple final slugs. ` +
`"${existing.finalSlug}" and "${params.entry.finalSlug}" both resolve from "${originalSlugKey}".`
);
};
/**
* Build a CustomToolsMap from custom tools and toolkits.
* Used internally by ToolRouter.create() to construct the per-session routing map.
*
* @internal
* @param tools - Standalone custom tools
* @param toolkits - Custom toolkits containing grouped tools
* @returns Maps for O(1) lookup by both final and original slug
* @throws If duplicate slugs or cross-group collisions
*/
export function buildCustomToolsMap(
tools: CustomTool[],
toolkits?: CustomToolkit[]
): CustomToolsMap {
const byFinalSlug = new Map<string, CustomToolsMapEntry>();
const byOriginalSlug = new Map<string, CustomToolsMapEntry>();
const byToolkitAndOriginalSlug = new Map<string, CustomToolsMapEntry>();
const ambiguousOriginalSlugs = new Set<string>();
const addEntry = (handle: CustomTool, finalSlug: string, toolkit?: string) => {
const originalSlug = handle.slug.toUpperCase();
// Custom tool slugs are matched case-insensitively across local and response maps.
const finalSlugKey = finalSlug.toUpperCase();
// Length validated early in createCustomTool/createCustomToolkit, but check as safety net
if (finalSlug.length > MAX_SLUG_LENGTH) {
throw new ValidationError(
`Custom tool slug "${handle.slug}" produces final slug "${finalSlug}" ` +
`which exceeds ${MAX_SLUG_LENGTH} characters.`
);
}
// Check cross-group collisions on final slug
if (byFinalSlug.has(finalSlugKey)) {
throw new ValidationError(
`Custom tool slug collision: "${finalSlug}" is already registered.`
);
}
const qualifiedKey = qualifiedOriginalSlugKey(toolkit, originalSlug);
if (byToolkitAndOriginalSlug.has(qualifiedKey)) {
throw new ValidationError(
`Custom tool slug collision: original slug "${handle.slug}" is already registered for toolkit "${toolkit ?? 'custom'}".`
);
}
const entry: CustomToolsMapEntry = { handle, finalSlug, toolkit };
byFinalSlug.set(finalSlugKey, entry);
byToolkitAndOriginalSlug.set(qualifiedKey, entry);
addOriginalSlugAlias({ byOriginalSlug, ambiguousOriginalSlugs, originalSlug, entry });
};
// Process standalone tools
for (const handle of tools) {
addEntry(handle, buildFinalSlug(handle.slug, handle.extendsToolkit), handle.extendsToolkit);
}
// Process toolkit tools
if (toolkits) {
for (const toolkit of toolkits) {
for (const handle of toolkit.tools) {
addEntry(handle, buildFinalSlug(handle.slug, toolkit.slug), toolkit.slug);
}
}
}
return {
byFinalSlug,
byOriginalSlug,
byToolkitAndOriginalSlug,
...(ambiguousOriginalSlugs.size ? { ambiguousOriginalSlugs } : {}),
toolkits,
tools: tools.length ? tools : undefined,
};
}
/**
* Serialize custom tools into the format expected by the backend session creation API.
*
* Maps `extendsToolkit` → `extends_toolkit` for backend. Omitted for standalone tools.
*
* @internal
* @param tools - The custom tools to serialize
* @returns Array of CustomToolDefinition for the API payload
*/
type CustomToolSerializationOptions = {
defaultPreload?: boolean;
};
function shouldSerializePreload(
preload: boolean | undefined,
inheritedPreload: boolean | undefined,
defaultPreload: boolean
): boolean | undefined {
const inheritedOrDefault = inheritedPreload ?? defaultPreload;
if (preload !== undefined) {
return preload || inheritedOrDefault ? preload : undefined;
}
if (inheritedPreload !== undefined) {
return inheritedPreload || defaultPreload ? inheritedPreload : undefined;
}
return defaultPreload ? true : undefined;
}
function preloadWireProperty(
preload: boolean | undefined,
inheritedPreload: boolean | undefined,
defaultPreload: boolean
): { preload?: boolean } {
const serializedPreload = shouldSerializePreload(preload, inheritedPreload, defaultPreload);
return serializedPreload === undefined ? {} : { preload: serializedPreload };
}
export function serializeCustomTools(
tools: CustomTool[],
options: CustomToolSerializationOptions = {}
): CustomToolWireDefinition[] {
const defaultPreload = options.defaultPreload ?? false;
return tools.map(handle => ({
slug: handle.slug,
name: handle.name,
description: handle.description,
input_schema: handle.inputSchema,
...(handle.outputSchema ? { output_schema: handle.outputSchema } : {}),
...(handle.extendsToolkit ? { extends_toolkit: handle.extendsToolkit } : {}),
...preloadWireProperty(handle.preload, undefined, defaultPreload),
}));
}
/**
* Serialize custom toolkits into the format expected by the backend session creation API.
*
* @internal
* @param toolkits - The custom toolkits to serialize
* @returns Array of CustomToolkitDefinition for the API payload
*/
export function serializeCustomToolkits(
toolkits: CustomToolkit[],
options: CustomToolSerializationOptions = {}
): CustomToolkitWireDefinition[] {
const defaultPreload = options.defaultPreload ?? false;
return toolkits.map(tk => ({
slug: tk.slug,
name: tk.name,
description: tk.description,
...preloadWireProperty(tk.preload, undefined, defaultPreload),
tools: tk.tools.map(t => ({
slug: t.slug,
name: t.name,
description: t.description,
input_schema: t.inputSchema,
...(t.outputSchema ? { output_schema: t.outputSchema } : {}),
...preloadWireProperty(t.preload, tk.preload, defaultPreload),
})),
}));
}
/**
* Build a CustomToolsMap using the slug/original_slug mapping from the session create response.
* This uses the backend's authoritative prefixed slugs instead of computing them client-side.
*
* @internal
* @param tools - The original custom tools passed to session creation
* @param toolkits - The original custom toolkits passed to session creation
* @param experimental - The experimental section from the session create response
* @returns Maps for O(1) lookup by both final and original slug
*/
export function buildCustomToolsMapFromResponse(
tools: CustomTool[],
toolkits: CustomToolkit[] | undefined,
experimental:
SessionCreateResponse['experimental'] | SessionRetrieveResponse['experimental'] | undefined
): CustomToolsMap {
const byFinalSlug = new Map<string, CustomToolsMapEntry>();
const byOriginalSlug = new Map<string, CustomToolsMapEntry>();
const byToolkitAndOriginalSlug = new Map<string, CustomToolsMapEntry>();
const ambiguousOriginalSlugs = new Set<string>();
type HandleMatch = { handle: CustomTool; toolkit?: string };
const handlesByQualifiedOriginalSlug = new Map<string, HandleMatch>();
const handlesByOriginalSlug = new Map<string, HandleMatch[]>();
const registerHandle = (handle: CustomTool, toolkit?: string) => {
const originalSlug = handle.slug.toUpperCase();
const match = { handle, toolkit };
handlesByQualifiedOriginalSlug.set(qualifiedOriginalSlugKey(toolkit, originalSlug), match);
const existing = handlesByOriginalSlug.get(originalSlug) ?? [];
existing.push(match);
handlesByOriginalSlug.set(originalSlug, existing);
};
for (const handle of tools) {
registerHandle(handle, handle.extendsToolkit);
}
if (toolkits) {
for (const tk of toolkits) {
for (const handle of tk.tools) {
registerHandle(handle, tk.slug);
}
}
}
const findHandle = (
finalSlug: string,
originalSlug: string,
toolkit?: string
): HandleMatch | undefined => {
const originalSlugKey = originalSlug.toUpperCase();
const qualifiedMatch = handlesByQualifiedOriginalSlug.get(
qualifiedOriginalSlugKey(toolkit, originalSlugKey)
);
if (qualifiedMatch) return qualifiedMatch;
const bareMatches = handlesByOriginalSlug.get(originalSlugKey) ?? [];
// Response tool not defined locally; nothing to route in-process.
if (bareMatches.length === 0) return undefined;
// A bare match may only stand in when the response carries no toolkit identity.
// Binding a toolkit child to another toolkit's handler would silently execute
// the wrong implementation.
if (toolkit === undefined && bareMatches.length === 1) return bareMatches[0];
const registered = [
...new Set(bareMatches.map(m => (m.toolkit ?? 'custom').toUpperCase())),
].sort();
throw new ValidationError(
`Cannot map custom tool "${finalSlug}": original slug "${originalSlug}" for toolkit ` +
`"${toolkit ?? 'custom'}" has no exact local match. Registered for toolkits: ${registered.join(', ')}.`
);
};
const addEntry = (finalSlug: string, originalSlug: string, toolkit?: string | null) => {
const resolvedToolkit = toolkit ?? undefined;
const match = findHandle(finalSlug, originalSlug, resolvedToolkit);
if (!match) return;
const finalSlugKey = finalSlug.toUpperCase();
if (byFinalSlug.has(finalSlugKey)) {
throw new ValidationError(
`Custom tool slug collision: "${finalSlug}" is already registered.`
);
}
const entryToolkit = resolvedToolkit ?? match.toolkit;
const qualifiedKey = qualifiedOriginalSlugKey(entryToolkit, originalSlug);
if (byToolkitAndOriginalSlug.has(qualifiedKey)) {
throw new ValidationError(
`Custom tool slug collision: original slug "${match.handle.slug}" is already registered for toolkit "${entryToolkit ?? 'custom'}".`
);
}
const entry: CustomToolsMapEntry = {
handle: match.handle,
finalSlug,
toolkit: entryToolkit,
};
byFinalSlug.set(finalSlugKey, entry);
byToolkitAndOriginalSlug.set(qualifiedKey, entry);
addOriginalSlugAlias({ byOriginalSlug, ambiguousOriginalSlugs, originalSlug, entry });
};
// Map standalone custom tools from response
if (experimental?.custom_tools) {
for (const ct of experimental.custom_tools) {
addEntry(ct.slug, ct.original_slug, ct.extends_toolkit);
}
}
// Map toolkit custom tools from response
if (experimental?.custom_toolkits) {
for (const ctk of experimental.custom_toolkits) {
for (const ct of ctk.tools) {
addEntry(ct.slug, ct.original_slug, ctk.slug);
}
}
}
// Ambiguity follows the local definitions, not whichever subset the response
// happened to include: a shared child slug must never become callable by its
// bare name just because a sibling was omitted.
for (const [originalSlugKey, matches] of handlesByOriginalSlug) {
if (matches.length > 1) {
byOriginalSlug.delete(originalSlugKey);
ambiguousOriginalSlugs.add(originalSlugKey);
}
}
return {
byFinalSlug,
byOriginalSlug,
byToolkitAndOriginalSlug,
...(ambiguousOriginalSlugs.size ? { ambiguousOriginalSlugs } : {}),
toolkits,
tools: tools.length ? tools : undefined,
};
}
/**
* Find a custom tool entry by final slug only.
*
* @internal
*/
export function findCustomToolMapEntryByFinalSlug(
customToolsMap: CustomToolsMap | undefined,
slug: string
): CustomToolsMapEntry | undefined {
return customToolsMap?.byFinalSlug.get(slug.toUpperCase());
}
/**
* Find a custom toolkit tool entry by toolkit slug and original tool slug.
*
* @internal
*/
export function findCustomToolMapEntryByToolkitAndOriginalSlug(
customToolsMap: CustomToolsMap | undefined,
toolkit: string | undefined,
slug: string
): CustomToolsMapEntry | undefined {
return customToolsMap?.byToolkitAndOriginalSlug?.get(qualifiedOriginalSlugKey(toolkit, slug));
}
/**
* Reject legacy attempts to preload custom tools through top-level preload.tools.
*
* Custom tool direct exposure is controlled by CustomTool.preload /
* CustomToolkit.preload so it follows the current SDK-provided custom
* definitions instead of stale session config.
*
* @internal
*/
export function assertNoCustomToolSlugsInPreload(
preloadTools: readonly string[] | typeof PRELOAD_TOOLS_ALL | undefined,
customToolsMap: CustomToolsMap | undefined
): void {
if (!preloadTools || preloadTools === PRELOAD_TOOLS_ALL) {
return;
}
const customPreloadSlugs = preloadTools.filter(slug => {
const normalized = slug.toUpperCase();
return (
// Top-level preload.tools is only for Composio-managed tool slugs.
// Custom tools use `preload: true` on their SDK definitions instead.
normalized.startsWith(LOCAL_TOOL_PREFIX) ||
customToolsMap?.byOriginalSlug.has(normalized) ||
customToolsMap?.ambiguousOriginalSlugs?.has(normalized) ||
customToolsMap?.byFinalSlug.has(normalized)
);
});
if (customPreloadSlugs.length) {
throw new ValidationError(
`Custom tool slugs are not supported in preload.tools: ${customPreloadSlugs.join(
', '
)}. Set preload: true on the SDK custom tool or custom toolkit definition instead.`
);
}
}
/**
* Resolve custom tools that the SDK should expose directly from session.tools().
*
* @internal
*/
export function getPreloadedCustomToolSlugs(
customToolsMap: CustomToolsMap | undefined,
defaultPreload = false
): string[] {
if (!customToolsMap) {
return [];
}
const seen = new Set<string>();
const customToolSlugs: string[] = [];
for (const entry of customToolsMap.byFinalSlug.values()) {
const toolkit = customToolsMap.toolkits?.find(
tk => entry.toolkit && tk.slug.toLowerCase() === entry.toolkit.toLowerCase()
);
const shouldPreload = entry.handle.preload ?? toolkit?.preload ?? defaultPreload;
if (!shouldPreload) {
continue;
}
const finalSlugKey = entry.finalSlug.toUpperCase();
if (seen.has(finalSlugKey)) {
continue;
}
seen.add(finalSlugKey);
customToolSlugs.push(entry.finalSlug);
}
return customToolSlugs;
}