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
Tighten Tool Router preload changes
Dhawal Upadhyayd2155c028b30
diff --git a/python/composio/core/models/custom_tool.py b/python/composio/core/models/custom_tool.pyindex 6a77bf74e..2f7dd6bfc 100644--- a/python/composio/core/models/custom_tool.py+++ b/python/composio/core/models/custom_tool.py@@ -54,8 +54,10 @@ from .custom_tool_types import (SLUG_REGEX,CustomTool,CustomToolExecuteFn,+ CustomToolkitWireDefinition,CustomToolsMap,CustomToolsMapEntry,+ CustomToolWireDefinition,)if t.TYPE_CHECKING:@@ -572,27 +574,25 @@ def _serialized_preload_value(inherited_preload: t.Optional[bool],default_preload: bool,) -> t.Optional[bool]:- resolved = (- preload- if preload is not None- else inherited_preload- if inherited_preload is not None- else default_preload+ inherited_or_default = (+ inherited_preload if inherited_preload is not None else default_preload)- if preload is not None or inherited_preload is not None or default_preload:- return resolved- return None+ if preload is not None:+ return preload if preload or inherited_or_default else None+ if inherited_preload is not None:+ return inherited_preload if inherited_preload or default_preload else None+ return True if default_preload else Nonedef serialize_custom_tools(tools: t.List[CustomTool],*,default_preload: bool = False,-) -> t.List[t.Dict[str, t.Any]]:+) -> t.List[CustomToolWireDefinition]:"""Serialize custom tools into the format expected by the backend."""- result = []+ result: t.List[CustomToolWireDefinition] = []for tool in tools:- entry: t.Dict[str, t.Any] = {+ entry: CustomToolWireDefinition = {"slug": tool.slug,"name": tool.name,"description": tool.description,@@ -615,13 +615,13 @@ def serialize_custom_toolkits(toolkits: t.Sequence[ExperimentalToolkit],*,default_preload: bool = False,-) -> t.List[t.Dict[str, t.Any]]:+) -> t.List[CustomToolkitWireDefinition]:"""Serialize custom toolkits into the format expected by the backend."""- result = []+ result: t.List[CustomToolkitWireDefinition] = []for tk in toolkits:- toolkit_tools = []+ toolkit_tools: t.List[CustomToolWireDefinition] = []for tool in tk.tools:- entry: t.Dict[str, t.Any] = {+ entry: CustomToolWireDefinition = {"slug": tool.slug,"name": tool.name,"description": tool.description,@@ -637,7 +637,7 @@ def serialize_custom_toolkits(if preload is not None:entry["preload"] = preloadtoolkit_tools.append(entry)- toolkit_entry: t.Dict[str, t.Any] = {+ toolkit_entry: CustomToolkitWireDefinition = {"slug": tk.slug,"name": tk.name,"description": tk.description,@@ -669,6 +669,7 @@ def build_custom_tools_map(handle: CustomTool, final_slug: str, toolkit: t.Optional[str]) -> None:original_slug = handle.slug.upper()+ # Custom tool slugs are matched case-insensitively across local and response maps.final_slug_key = final_slug.upper()if len(final_slug) > MAX_SLUG_LENGTH:@@ -795,6 +796,12 @@ def assert_no_custom_tool_slugs_in_preload("""Reject legacy top-level preload of custom tool slugs."""if preload_tools is None or preload_tools == "all":return+ if isinstance(preload_tools, str):+ raise ValidationError(+ 'preload.tools must be a list of Composio tool slugs or "all". '+ "Set preload=True on the SDK custom tool or custom toolkit "+ "definition to expose custom tools directly."+ )custom_preload_slugs = []for slug in preload_tools:diff --git a/python/composio/core/models/custom_tool_types.py b/python/composio/core/models/custom_tool_types.pyindex 03247cc00..a1bebb804 100644--- a/python/composio/core/models/custom_tool_types.py+++ b/python/composio/core/models/custom_tool_types.py@@ -109,6 +109,29 @@ class CustomTool:preload: t.Optional[bool] = None+class CustomToolWireDefinition(te.TypedDict, total=False):+ slug: te.Required[str]+ name: te.Required[str]+ description: te.Required[str]+ input_schema: te.Required[t.Dict[str, t.Any]]+ extends_toolkit: str+ output_schema: t.Dict[str, t.Any]+ preload: bool+++class CustomToolkitWireDefinition(te.TypedDict, total=False):+ slug: te.Required[str]+ name: te.Required[str]+ description: te.Required[str]+ tools: te.Required[t.List[CustomToolWireDefinition]]+ preload: bool+++class InlineCustomToolsWirePayload(te.TypedDict, total=False):+ custom_tools: t.List[CustomToolWireDefinition]+ custom_toolkits: t.List[CustomToolkitWireDefinition]++# ────────────────────────────────────────────────────────────────# Internal routing map types# ────────────────────────────────────────────────────────────────diff --git a/python/composio/core/models/tool_router.py b/python/composio/core/models/tool_router.pyindex 6817d9c85..fb49df914 100644--- a/python/composio/core/models/tool_router.py+++ b/python/composio/core/models/tool_router.py@@ -29,6 +29,7 @@ from composio.core.models.custom_tool import (from composio.core.models.custom_tool_types import (CustomTool,CustomToolsMap,+ InlineCustomToolsWirePayload,)from composio.core.models.tool_router_session import (ToolRouterSession,@@ -221,10 +222,24 @@ class ToolRouterPreloadConfig(te.TypedDict, total=False):tool lists without first calling search."""- tools: t.Union[t.List[str], str]+ tools: t.Union[t.List[str], t.Literal["all"]]-def _session_preload_config(session: t.Any) -> ToolRouterSessionPreloadConfig:+class _SessionPreloadLike(te.Protocol):+ tools: t.Union[t.List[str], t.Literal["all"], None]+++class _SessionConfigLike(te.Protocol):+ preload: _SessionPreloadLike+++class _SessionWithPreloadConfig(te.Protocol):+ config: _SessionConfigLike+++def _session_preload_config(+ session: _SessionWithPreloadConfig,+) -> ToolRouterSessionPreloadConfig:tools = session.config.preload.toolsreturn ToolRouterSessionPreloadConfig(tools=tools if isinstance(tools, str) else list(tools or [])@@ -723,6 +738,10 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):preload=preload,)default_custom_preload = preload is not None and preload.get("tools") == "all"+ assert_no_custom_tool_slugs_in_preload(+ preload.get("tools") if preload is not None else None,+ None,+ )# Parse manage_connections configmanage_connections = (@@ -859,7 +878,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):custom_tools: t.Optional[t.List[CustomTool]] = Nonecustom_toolkits: t.Optional[t.List[ExperimentalToolkit]] = Nonelocal_custom_tools_map: t.Optional[CustomToolsMap] = None- inline_custom_tools_payload: t.Optional[t.Dict[str, t.Any]] = None+ inline_custom_tools_payload: t.Optional[InlineCustomToolsWirePayload] = Noneif experimental is not None:experimental_payload: t.Dict[str, t.Any] = {}@@ -900,10 +919,15 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):"custom_tools" in experimental_payloador "custom_toolkits" in experimental_payload):- inline_custom_tools_payload = {- "custom_tools": experimental_payload.get("custom_tools"),- "custom_toolkits": experimental_payload.get("custom_toolkits"),- }+ inline_custom_tools_payload = {}+ if "custom_tools" in experimental_payload:+ inline_custom_tools_payload["custom_tools"] = experimental_payload[+ "custom_tools"+ ]+ if "custom_toolkits" in experimental_payload:+ inline_custom_tools_payload["custom_toolkits"] = experimental_payload[+ "custom_toolkits"+ ]if experimental_payload:create_params["experimental"] = experimental_payloaddiff --git a/python/composio/core/models/tool_router_session.py b/python/composio/core/models/tool_router_session.pyindex 3306afc7d..51721319c 100644--- a/python/composio/core/models/tool_router_session.py+++ b/python/composio/core/models/tool_router_session.py@@ -28,6 +28,7 @@ from composio_client.types.tool_router.session_proxy_execute_response import (from composio_client.types.tool_router.session_search_response import (SessionSearchResponse,)+from composio_client.types.tool_router import session_search_paramsfrom composio.client import HttpClientfrom composio.core.models.connected_accounts import ConnectionRequest@@ -39,6 +40,7 @@ from composio.core.models.custom_tool_execution import (from composio.core.models.custom_tool_types import (CustomToolsMap,CustomToolsMapEntry,+ InlineCustomToolsWirePayload,RegisteredCustomTool,RegisteredCustomToolkit,)@@ -65,7 +67,7 @@ MAX_PARALLEL_WORKERS = 5class ToolRouterSessionPreloadConfig:"""Preloaded tools configured for a tool router session."""- tools: t.Union[t.List[str], str]+ tools: t.Union[t.List[str], t.Literal["all"]]class ToolRouterSession(t.Generic[TTool, TToolCollection]):@@ -105,7 +107,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):user_id: t.Optional[str] = None,preload: t.Optional[ToolRouterSessionPreloadConfig] = None,preloaded_custom_tool_slugs: t.Optional[t.List[str]] = None,- inline_custom_tools_payload: t.Optional[t.Dict[str, t.Any]] = None,+ inline_custom_tools_payload: t.Optional[InlineCustomToolsWirePayload] = None,) -> None:self._client = clientself._provider = provider@@ -636,14 +638,19 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):Returns relevant tools for the given query with schemas and guidance."""- params: t.Dict[str, t.Any] = {- "session_id": self.session_id,- "queries": [{"use_case": query}],- "model": model if model else omit,- }- if self._inline_custom_tools_payload is not None:- params["experimental"] = self._inline_custom_tools_payload- return self._client.tool_router.session.search(**params)+ return self._client.tool_router.session.search(+ session_id=self.session_id,+ queries=[{"use_case": query}],+ model=model if model else omit,+ experimental=(+ t.cast(+ session_search_params.Experimental,+ self._inline_custom_tools_payload,+ )+ if self._inline_custom_tools_payload is not None+ else omit+ ),+ )def execute(self,@@ -681,15 +688,12 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):)# Remote execution- params: t.Dict[str, t.Any] = {- "session_id": self.session_id,- "tool_slug": tool_slug,- "arguments": arguments if arguments is not None else omit,- "account": account if account is not None else omit,- }- if self._inline_custom_tools_payload is not None:- params["experimental"] = self._inline_custom_tools_payload- return self._client.tool_router.session.execute(**params)+ return self._client.tool_router.session.execute(+ session_id=self.session_id,+ tool_slug=tool_slug,+ arguments=arguments if arguments is not None else omit,+ account=account if account is not None else omit,+ )def custom_tools(self, *, toolkit: t.Optional[str] = Nonediff --git a/python/tests/test_custom_tools.py b/python/tests/test_custom_tools.pyindex 9fb79bebf..ebb315b4e 100644--- a/python/tests/test_custom_tools.py+++ b/python/tests/test_custom_tools.py@@ -422,6 +422,11 @@ class TestSerialization:result = serialize_custom_tools([preloaded])assert result[0]["preload"] is True+ def test_serialize_custom_tool_omits_redundant_preload_false(self, grep_tool):+ search_only = replace(grep_tool, preload=False)+ result = serialize_custom_tools([search_only])+ assert "preload" not in result[0]+def test_serialize_toolkit(self, role_toolkit):result = serialize_custom_toolkits([role_toolkit])assert len(result) == 1diff --git a/python/tests/test_tool_router.py b/python/tests/test_tool_router.pyindex ea86ba520..bf6f47d4d 100644--- a/python/tests/test_tool_router.py+++ b/python/tests/test_tool_router.py@@ -652,6 +652,20 @@ class TestToolRouter:mock_client.tool_router.session.create.assert_not_called()+ def test_create_session_rejects_bare_string_preload_tools(+ self, tool_router, mock_client+ ):+ with pytest.raises(+ ValidationError,+ match='preload.tools must be a list of Composio tool slugs or "all"',+ ):+ tool_router.create(+ user_id="user_123",+ preload={"tools": "GMAIL_FETCH_EMAILS"},+ )++ mock_client.tool_router.session.create.assert_not_called()+def test_create_session_with_direct_tools_preset(self, tool_router, mock_client):"""direct_tools applies SDK-side defaults for direct tool exposure."""mock_client.tool_router.session.create.return_value.config.preload.tools = "all"diff --git a/ts/examples/tool-router/README.md b/ts/examples/tool-router/README.mdindex 3003c3740..f40b6ddd8 100644--- a/ts/examples/tool-router/README.md+++ b/ts/examples/tool-router/README.md@@ -5,13 +5,11 @@ This example demonstrates how to use Composio SDK for tool-router.## Setup1. **Install dependencies:**-```bashpnpm install```2. **Configure environment:**-```bashcp .env.example .env```@@ -48,7 +46,6 @@ pnpm direct-tools## CustomizationEdit `src/index.ts` to:-- Add specific apps you want to integrate with- Implement your business logic- Add error handling and loggingdiff --git a/ts/packages/core/src/lib/toolRouterParams.ts b/ts/packages/core/src/lib/toolRouterParams.tsindex 97b57be66..e82fda173 100644--- a/ts/packages/core/src/lib/toolRouterParams.ts+++ b/ts/packages/core/src/lib/toolRouterParams.ts@@ -114,7 +114,7 @@ export const transformToolRouterManageConnectionsParams = (export const transformToolRouterWorkbenchParams = (params?: ToolRouterCreateSessionConfig['workbench']): SessionCreateParams.Workbench | undefined => {- if (params === undefined) {+ if (!params) {return undefined;}diff --git a/ts/packages/core/src/models/CustomTool.ts b/ts/packages/core/src/models/CustomTool.tsindex efb4d8180..640892121 100644--- a/ts/packages/core/src/models/CustomTool.ts+++ b/ts/packages/core/src/models/CustomTool.ts@@ -286,6 +286,7 @@ export function buildCustomToolsMap(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@@ -351,11 +352,14 @@ function shouldSerializePreload(inheritedPreload: boolean | undefined,defaultPreload: boolean): boolean | undefined {- const resolved = preload ?? inheritedPreload ?? defaultPreload;- if (preload !== undefined || inheritedPreload !== undefined || defaultPreload) {- return resolved;+ const inheritedOrDefault = inheritedPreload ?? defaultPreload;+ if (preload !== undefined) {+ return preload || inheritedOrDefault ? preload : undefined;}- return undefined;+ if (inheritedPreload !== undefined) {+ return inheritedPreload || defaultPreload ? inheritedPreload : undefined;+ }+ return defaultPreload ? true : undefined;}function preloadWireProperty(diff --git a/ts/packages/core/src/models/ToolRouter.ts b/ts/packages/core/src/models/ToolRouter.tsindex 58f14b8b1..99290d8ca 100644--- a/ts/packages/core/src/models/ToolRouter.ts+++ b/ts/packages/core/src/models/ToolRouter.ts@@ -163,8 +163,12 @@ export class ToolRouter<const inlineCustomToolsPayload =experimentalPayload.custom_tools || experimentalPayload.custom_toolkits? {- custom_tools: experimentalPayload.custom_tools,- custom_toolkits: experimentalPayload.custom_toolkits,+ ...(experimentalPayload.custom_tools+ ? { custom_tools: experimentalPayload.custom_tools }+ : {}),+ ...(experimentalPayload.custom_toolkits+ ? { custom_toolkits: experimentalPayload.custom_toolkits }+ : {}),}: undefined;diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.tsindex 61f1d21f4..710bf42cb 100644--- a/ts/packages/core/src/models/ToolRouterSession.ts+++ b/ts/packages/core/src/models/ToolRouterSession.ts@@ -39,10 +39,7 @@ import type {} from '../types/customTool.types';import type { Tool, ToolExecuteResponse } from '../types/tool.types';import type { SessionProxyExecuteParams } from '../types/toolRouter.types';-import type {- SessionExecuteParams,- SessionSearchParams,-} from '@composio/client/resources/tool-router/session/session.mjs';+import type { SessionExecuteParams } from '@composio/client/resources/tool-router/session/session.mjs';import { SessionProxyExecuteParamsSchema } from '../types/toolRouter.types';import { SessionContextImpl } from './SessionContext';import { findCustomTool, executeCustomTool } from './customToolExecution';@@ -359,7 +356,7 @@ export class ToolRouterSession<query: string;toolkits?: string[];}): Promise<ToolRouterSessionSearchResponse> {- const searchParams: SessionSearchParams & { toolkits?: string[] } = {+ const searchParams = {queries: [{ use_case: params.query }],...(params.toolkits?.length ? { toolkits: params.toolkits } : {}),...(this.inlineCustomToolsPayload ? { experimental: this.inlineCustomToolsPayload } : {}),@@ -402,7 +399,6 @@ export class ToolRouterSession<const executeParams: SessionExecuteParams = {tool_slug: toolSlug,arguments: arguments_ ?? {},- ...(this.inlineCustomToolsPayload ? { experimental: this.inlineCustomToolsPayload } : {}),};if (options?.account) {executeParams.account = options.account;diff --git a/ts/packages/core/src/types/customTool.types.ts b/ts/packages/core/src/types/customTool.types.tsindex 2d72b04e4..7b2673232 100644--- a/ts/packages/core/src/types/customTool.types.ts+++ b/ts/packages/core/src/types/customTool.types.ts@@ -139,7 +139,7 @@ export const CreateCustomToolBaseSchema = z.object({.boolean().optional().describe(- 'When true, expose this custom tool directly from session.tools(). This is SDK-local for custom tools and is sent to v3.1 as an input-only hint.'+ 'When true, expose this custom tool directly from session.tools(). This is SDK-local for custom tools and is sent to v3.1 with the inline custom definition.'),});@@ -171,7 +171,8 @@ export interface CustomTool {readonly extendsToolkit?: string;/*** Whether this custom tool should be exposed directly from session.tools().- * This is SDK-local for custom tools and is sent to v3.1 as an input-only hint.+ * This is SDK-local for custom tools and is sent to v3.1 with the inline+ * custom definition.*/readonly preload?: boolean;readonly inputSchema: Record<string, unknown>;diff --git a/ts/packages/core/test/models/customToolRouting.test.ts b/ts/packages/core/test/models/customToolRouting.test.tsindex 6b12676e6..7ab5bd516 100644--- a/ts/packages/core/test/models/customToolRouting.test.ts+++ b/ts/packages/core/test/models/customToolRouting.test.ts@@ -185,6 +185,25 @@ describe('ToolRouter.create() with customTools', () => {expect(payload.experimental.custom_tools[0].preload).toBe(true);});+ it('should omit redundant custom tool preload false', async () => {+ const searchOnlyTool = createCustomTool('SEARCH_ONLY_CONTEXT', {+ name: 'Search-only context',+ description: 'Retrieve context through search',+ preload: false,+ inputParams: z.object({}),+ execute: localExecute,+ });++ await router.create('user_1', {+ experimental: {+ customTools: [searchOnlyTool],+ },+ });++ const payload = mockClient.toolRouter.session.create.mock.calls[0][0];+ expect(payload.experimental.custom_tools[0]).not.toHaveProperty('preload');+ });+it('should not send experimental.custom_tools when customTools is omitted or empty', async () => {await router.create('user_1', { toolkits: ['gmail'] });const payload1 = mockClient.toolRouter.session.create.mock.calls[0][0];diff --git a/ts/packages/core/test/models/toolRouter.test.ts b/ts/packages/core/test/models/toolRouter.test.tsindex 56b81e27b..e3c8dbc83 100644--- a/ts/packages/core/test/models/toolRouter.test.ts+++ b/ts/packages/core/test/models/toolRouter.test.ts@@ -2253,7 +2253,6 @@ describe('ToolRouter', () => {preload: true,}),],- custom_toolkits: undefined,},});});