@devries-cameron20 / composio Mirror · read-only / commits / d2155c028
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 22:15 UTC

Tighten Tool Router preload changes

Dhawal Upadhyay committed May 6, 2026 at 16:26 UTC d2155c028b306f9c2444f7d10a2b371c643baa8d
14 files changed +159 -62
python/composio/core/models/custom_tool.py
+24 -17
@@ -54,8 +54,10 @@ from .custom_tool_types import (
54 SLUG_REGEX,
55 CustomTool,
56 CustomToolExecuteFn,
57 + CustomToolkitWireDefinition,
58 CustomToolsMap,
59 CustomToolsMapEntry,
60 + CustomToolWireDefinition,
61 )
62
63 if t.TYPE_CHECKING:
@@ -572,27 +574,25 @@ def _serialized_preload_value(
574 inherited_preload: t.Optional[bool],
575 default_preload: bool,
576 ) -> t.Optional[bool]:
575 - resolved = (
576 - preload
577 - if preload is not None
578 - else inherited_preload
579 - if inherited_preload is not None
580 - else default_preload
577 + inherited_or_default = (
578 + inherited_preload if inherited_preload is not None else default_preload
579 )
582 - if preload is not None or inherited_preload is not None or default_preload:
583 - return resolved
584 - return None
580 + if preload is not None:
581 + return preload if preload or inherited_or_default else None
582 + if inherited_preload is not None:
583 + return inherited_preload if inherited_preload or default_preload else None
584 + return True if default_preload else None
585
586
587 def serialize_custom_tools(
588 tools: t.List[CustomTool],
589 *,
590 default_preload: bool = False,
591 -) -> t.List[t.Dict[str, t.Any]]:
591 +) -> t.List[CustomToolWireDefinition]:
592 """Serialize custom tools into the format expected by the backend."""
593 - result = []
593 + result: t.List[CustomToolWireDefinition] = []
594 for tool in tools:
595 - entry: t.Dict[str, t.Any] = {
595 + entry: CustomToolWireDefinition = {
596 "slug": tool.slug,
597 "name": tool.name,
598 "description": tool.description,
@@ -615,13 +615,13 @@ def serialize_custom_toolkits(
615 toolkits: t.Sequence[ExperimentalToolkit],
616 *,
617 default_preload: bool = False,
618 -) -> t.List[t.Dict[str, t.Any]]:
618 +) -> t.List[CustomToolkitWireDefinition]:
619 """Serialize custom toolkits into the format expected by the backend."""
620 - result = []
620 + result: t.List[CustomToolkitWireDefinition] = []
621 for tk in toolkits:
622 - toolkit_tools = []
622 + toolkit_tools: t.List[CustomToolWireDefinition] = []
623 for tool in tk.tools:
624 - entry: t.Dict[str, t.Any] = {
624 + entry: CustomToolWireDefinition = {
625 "slug": tool.slug,
626 "name": tool.name,
627 "description": tool.description,
@@ -637,7 +637,7 @@ def serialize_custom_toolkits(
637 if preload is not None:
638 entry["preload"] = preload
639 toolkit_tools.append(entry)
640 - toolkit_entry: t.Dict[str, t.Any] = {
640 + toolkit_entry: CustomToolkitWireDefinition = {
641 "slug": tk.slug,
642 "name": tk.name,
643 "description": tk.description,
@@ -669,6 +669,7 @@ def build_custom_tools_map(
669 handle: CustomTool, final_slug: str, toolkit: t.Optional[str]
670 ) -> None:
671 original_slug = handle.slug.upper()
672 + # Custom tool slugs are matched case-insensitively across local and response maps.
673 final_slug_key = final_slug.upper()
674
675 if len(final_slug) > MAX_SLUG_LENGTH:
@@ -795,6 +796,12 @@ def assert_no_custom_tool_slugs_in_preload(
796 """Reject legacy top-level preload of custom tool slugs."""
797 if preload_tools is None or preload_tools == "all":
798 return
799 + if isinstance(preload_tools, str):
800 + raise ValidationError(
801 + 'preload.tools must be a list of Composio tool slugs or "all". '
802 + "Set preload=True on the SDK custom tool or custom toolkit "
803 + "definition to expose custom tools directly."
804 + )
805
806 custom_preload_slugs = []
807 for slug in preload_tools:
python/composio/core/models/custom_tool_types.py
+23
@@ -109,6 +109,29 @@ class CustomTool:
109 preload: t.Optional[bool] = None
110
111
112 +class CustomToolWireDefinition(te.TypedDict, total=False):
113 + slug: te.Required[str]
114 + name: te.Required[str]
115 + description: te.Required[str]
116 + input_schema: te.Required[t.Dict[str, t.Any]]
117 + extends_toolkit: str
118 + output_schema: t.Dict[str, t.Any]
119 + preload: bool
120 +
121 +
122 +class CustomToolkitWireDefinition(te.TypedDict, total=False):
123 + slug: te.Required[str]
124 + name: te.Required[str]
125 + description: te.Required[str]
126 + tools: te.Required[t.List[CustomToolWireDefinition]]
127 + preload: bool
128 +
129 +
130 +class InlineCustomToolsWirePayload(te.TypedDict, total=False):
131 + custom_tools: t.List[CustomToolWireDefinition]
132 + custom_toolkits: t.List[CustomToolkitWireDefinition]
133 +
134 +
135 # ────────────────────────────────────────────────────────────────
136 # Internal routing map types
137 # ────────────────────────────────────────────────────────────────
python/composio/core/models/tool_router.py
+31 -7
@@ -29,6 +29,7 @@ from composio.core.models.custom_tool import (
29 from composio.core.models.custom_tool_types import (
30 CustomTool,
31 CustomToolsMap,
32 + InlineCustomToolsWirePayload,
33 )
34 from composio.core.models.tool_router_session import (
35 ToolRouterSession,
@@ -221,10 +222,24 @@ class ToolRouterPreloadConfig(te.TypedDict, total=False):
222 tool lists without first calling search.
223 """
224
224 - tools: t.Union[t.List[str], str]
225 + tools: t.Union[t.List[str], t.Literal["all"]]
226
227
227 -def _session_preload_config(session: t.Any) -> ToolRouterSessionPreloadConfig:
228 +class _SessionPreloadLike(te.Protocol):
229 + tools: t.Union[t.List[str], t.Literal["all"], None]
230 +
231 +
232 +class _SessionConfigLike(te.Protocol):
233 + preload: _SessionPreloadLike
234 +
235 +
236 +class _SessionWithPreloadConfig(te.Protocol):
237 + config: _SessionConfigLike
238 +
239 +
240 +def _session_preload_config(
241 + session: _SessionWithPreloadConfig,
242 +) -> ToolRouterSessionPreloadConfig:
243 tools = session.config.preload.tools
244 return ToolRouterSessionPreloadConfig(
245 tools=tools if isinstance(tools, str) else list(tools or [])
@@ -723,6 +738,10 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
738 preload=preload,
739 )
740 default_custom_preload = preload is not None and preload.get("tools") == "all"
741 + assert_no_custom_tool_slugs_in_preload(
742 + preload.get("tools") if preload is not None else None,
743 + None,
744 + )
745
746 # Parse manage_connections config
747 manage_connections = (
@@ -859,7 +878,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
878 custom_tools: t.Optional[t.List[CustomTool]] = None
879 custom_toolkits: t.Optional[t.List[ExperimentalToolkit]] = None
880 local_custom_tools_map: t.Optional[CustomToolsMap] = None
862 - inline_custom_tools_payload: t.Optional[t.Dict[str, t.Any]] = None
881 + inline_custom_tools_payload: t.Optional[InlineCustomToolsWirePayload] = None
882
883 if experimental is not None:
884 experimental_payload: t.Dict[str, t.Any] = {}
@@ -900,10 +919,15 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
919 "custom_tools" in experimental_payload
920 or "custom_toolkits" in experimental_payload
921 ):
903 - inline_custom_tools_payload = {
904 - "custom_tools": experimental_payload.get("custom_tools"),
905 - "custom_toolkits": experimental_payload.get("custom_toolkits"),
906 - }
922 + inline_custom_tools_payload = {}
923 + if "custom_tools" in experimental_payload:
924 + inline_custom_tools_payload["custom_tools"] = experimental_payload[
925 + "custom_tools"
926 + ]
927 + if "custom_toolkits" in experimental_payload:
928 + inline_custom_tools_payload["custom_toolkits"] = experimental_payload[
929 + "custom_toolkits"
930 + ]
931
932 if experimental_payload:
933 create_params["experimental"] = experimental_payload
python/composio/core/models/tool_router_session.py
+23 -19
@@ -28,6 +28,7 @@ from composio_client.types.tool_router.session_proxy_execute_response import (
28 from composio_client.types.tool_router.session_search_response import (
29 SessionSearchResponse,
30 )
31 +from composio_client.types.tool_router import session_search_params
32
33 from composio.client import HttpClient
34 from composio.core.models.connected_accounts import ConnectionRequest
@@ -39,6 +40,7 @@ from composio.core.models.custom_tool_execution import (
40 from composio.core.models.custom_tool_types import (
41 CustomToolsMap,
42 CustomToolsMapEntry,
43 + InlineCustomToolsWirePayload,
44 RegisteredCustomTool,
45 RegisteredCustomToolkit,
46 )
@@ -65,7 +67,7 @@ MAX_PARALLEL_WORKERS = 5
67 class ToolRouterSessionPreloadConfig:
68 """Preloaded tools configured for a tool router session."""
69
68 - tools: t.Union[t.List[str], str]
70 + tools: t.Union[t.List[str], t.Literal["all"]]
71
72
73 class ToolRouterSession(t.Generic[TTool, TToolCollection]):
@@ -105,7 +107,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
107 user_id: t.Optional[str] = None,
108 preload: t.Optional[ToolRouterSessionPreloadConfig] = None,
109 preloaded_custom_tool_slugs: t.Optional[t.List[str]] = None,
108 - inline_custom_tools_payload: t.Optional[t.Dict[str, t.Any]] = None,
110 + inline_custom_tools_payload: t.Optional[InlineCustomToolsWirePayload] = None,
111 ) -> None:
112 self._client = client
113 self._provider = provider
@@ -636,14 +638,19 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
638
639 Returns relevant tools for the given query with schemas and guidance.
640 """
639 - params: t.Dict[str, t.Any] = {
640 - "session_id": self.session_id,
641 - "queries": [{"use_case": query}],
642 - "model": model if model else omit,
643 - }
644 - if self._inline_custom_tools_payload is not None:
645 - params["experimental"] = self._inline_custom_tools_payload
646 - return self._client.tool_router.session.search(**params)
641 + return self._client.tool_router.session.search(
642 + session_id=self.session_id,
643 + queries=[{"use_case": query}],
644 + model=model if model else omit,
645 + experimental=(
646 + t.cast(
647 + session_search_params.Experimental,
648 + self._inline_custom_tools_payload,
649 + )
650 + if self._inline_custom_tools_payload is not None
651 + else omit
652 + ),
653 + )
654
655 def execute(
656 self,
@@ -681,15 +688,12 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
688 )
689
690 # Remote execution
684 - params: t.Dict[str, t.Any] = {
685 - "session_id": self.session_id,
686 - "tool_slug": tool_slug,
687 - "arguments": arguments if arguments is not None else omit,
688 - "account": account if account is not None else omit,
689 - }
690 - if self._inline_custom_tools_payload is not None:
691 - params["experimental"] = self._inline_custom_tools_payload
692 - return self._client.tool_router.session.execute(**params)
691 + return self._client.tool_router.session.execute(
692 + session_id=self.session_id,
693 + tool_slug=tool_slug,
694 + arguments=arguments if arguments is not None else omit,
695 + account=account if account is not None else omit,
696 + )
697
698 def custom_tools(
699 self, *, toolkit: t.Optional[str] = None
python/tests/test_custom_tools.py
+5
@@ -422,6 +422,11 @@ class TestSerialization:
422 result = serialize_custom_tools([preloaded])
423 assert result[0]["preload"] is True
424
425 + def test_serialize_custom_tool_omits_redundant_preload_false(self, grep_tool):
426 + search_only = replace(grep_tool, preload=False)
427 + result = serialize_custom_tools([search_only])
428 + assert "preload" not in result[0]
429 +
430 def test_serialize_toolkit(self, role_toolkit):
431 result = serialize_custom_toolkits([role_toolkit])
432 assert len(result) == 1
python/tests/test_tool_router.py
+14
@@ -652,6 +652,20 @@ class TestToolRouter:
652
653 mock_client.tool_router.session.create.assert_not_called()
654
655 + def test_create_session_rejects_bare_string_preload_tools(
656 + self, tool_router, mock_client
657 + ):
658 + with pytest.raises(
659 + ValidationError,
660 + match='preload.tools must be a list of Composio tool slugs or "all"',
661 + ):
662 + tool_router.create(
663 + user_id="user_123",
664 + preload={"tools": "GMAIL_FETCH_EMAILS"},
665 + )
666 +
667 + mock_client.tool_router.session.create.assert_not_called()
668 +
669 def test_create_session_with_direct_tools_preset(self, tool_router, mock_client):
670 """direct_tools applies SDK-side defaults for direct tool exposure."""
671 mock_client.tool_router.session.create.return_value.config.preload.tools = "all"
ts/examples/tool-router/README.md
-3
@@ -5,13 +5,11 @@ This example demonstrates how to use Composio SDK for tool-router.
5 ## Setup
6
7 1. **Install dependencies:**
8 -
8 ```bash
9 pnpm install
10 ```
11
12 2. **Configure environment:**
14 -
13 ```bash
14 cp .env.example .env
15 ```
@@ -48,7 +46,6 @@ pnpm direct-tools
46 ## Customization
47
48 Edit `src/index.ts` to:
51 -
49 - Add specific apps you want to integrate with
50 - Implement your business logic
51 - Add error handling and logging
ts/packages/core/src/lib/toolRouterParams.ts
+1 -1
@@ -114,7 +114,7 @@ export const transformToolRouterManageConnectionsParams = (
114 export const transformToolRouterWorkbenchParams = (
115 params?: ToolRouterCreateSessionConfig['workbench']
116 ): SessionCreateParams.Workbench | undefined => {
117 - if (params === undefined) {
117 + if (!params) {
118 return undefined;
119 }
120
ts/packages/core/src/models/CustomTool.ts
+8 -4
@@ -286,6 +286,7 @@ export function buildCustomToolsMap(
286
287 const addEntry = (handle: CustomTool, finalSlug: string, toolkit?: string) => {
288 const originalSlug = handle.slug.toUpperCase();
289 + // Custom tool slugs are matched case-insensitively across local and response maps.
290 const finalSlugKey = finalSlug.toUpperCase();
291
292 // Length validated early in createCustomTool/createCustomToolkit, but check as safety net
@@ -351,11 +352,14 @@ function shouldSerializePreload(
352 inheritedPreload: boolean | undefined,
353 defaultPreload: boolean
354 ): boolean | undefined {
354 - const resolved = preload ?? inheritedPreload ?? defaultPreload;
355 - if (preload !== undefined || inheritedPreload !== undefined || defaultPreload) {
356 - return resolved;
355 + const inheritedOrDefault = inheritedPreload ?? defaultPreload;
356 + if (preload !== undefined) {
357 + return preload || inheritedOrDefault ? preload : undefined;
358 }
358 - return undefined;
359 + if (inheritedPreload !== undefined) {
360 + return inheritedPreload || defaultPreload ? inheritedPreload : undefined;
361 + }
362 + return defaultPreload ? true : undefined;
363 }
364
365 function preloadWireProperty(
ts/packages/core/src/models/ToolRouter.ts
+6 -2
@@ -163,8 +163,12 @@ export class ToolRouter<
163 const inlineCustomToolsPayload =
164 experimentalPayload.custom_tools || experimentalPayload.custom_toolkits
165 ? {
166 - custom_tools: experimentalPayload.custom_tools,
167 - custom_toolkits: experimentalPayload.custom_toolkits,
166 + ...(experimentalPayload.custom_tools
167 + ? { custom_tools: experimentalPayload.custom_tools }
168 + : {}),
169 + ...(experimentalPayload.custom_toolkits
170 + ? { custom_toolkits: experimentalPayload.custom_toolkits }
171 + : {}),
172 }
173 : undefined;
174
ts/packages/core/src/models/ToolRouterSession.ts
+2 -6
@@ -39,10 +39,7 @@ import type {
39 } from '../types/customTool.types';
40 import type { Tool, ToolExecuteResponse } from '../types/tool.types';
41 import type { SessionProxyExecuteParams } from '../types/toolRouter.types';
42 -import type {
43 - SessionExecuteParams,
44 - SessionSearchParams,
45 -} from '@composio/client/resources/tool-router/session/session.mjs';
42 +import type { SessionExecuteParams } from '@composio/client/resources/tool-router/session/session.mjs';
43 import { SessionProxyExecuteParamsSchema } from '../types/toolRouter.types';
44 import { SessionContextImpl } from './SessionContext';
45 import { findCustomTool, executeCustomTool } from './customToolExecution';
@@ -359,7 +356,7 @@ export class ToolRouterSession<
356 query: string;
357 toolkits?: string[];
358 }): Promise<ToolRouterSessionSearchResponse> {
362 - const searchParams: SessionSearchParams & { toolkits?: string[] } = {
359 + const searchParams = {
360 queries: [{ use_case: params.query }],
361 ...(params.toolkits?.length ? { toolkits: params.toolkits } : {}),
362 ...(this.inlineCustomToolsPayload ? { experimental: this.inlineCustomToolsPayload } : {}),
@@ -402,7 +399,6 @@ export class ToolRouterSession<
399 const executeParams: SessionExecuteParams = {
400 tool_slug: toolSlug,
401 arguments: arguments_ ?? {},
405 - ...(this.inlineCustomToolsPayload ? { experimental: this.inlineCustomToolsPayload } : {}),
402 };
403 if (options?.account) {
404 executeParams.account = options.account;
ts/packages/core/src/types/customTool.types.ts
+3 -2
@@ -139,7 +139,7 @@ export const CreateCustomToolBaseSchema = z.object({
139 .boolean()
140 .optional()
141 .describe(
142 - '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.'
142 + '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.'
143 ),
144 });
145
@@ -171,7 +171,8 @@ export interface CustomTool {
171 readonly extendsToolkit?: string;
172 /**
173 * Whether this custom tool should be exposed directly from session.tools().
174 - * This is SDK-local for custom tools and is sent to v3.1 as an input-only hint.
174 + * This is SDK-local for custom tools and is sent to v3.1 with the inline
175 + * custom definition.
176 */
177 readonly preload?: boolean;
178 readonly inputSchema: Record<string, unknown>;
ts/packages/core/test/models/customToolRouting.test.ts
+19
@@ -185,6 +185,25 @@ describe('ToolRouter.create() with customTools', () => {
185 expect(payload.experimental.custom_tools[0].preload).toBe(true);
186 });
187
188 + it('should omit redundant custom tool preload false', async () => {
189 + const searchOnlyTool = createCustomTool('SEARCH_ONLY_CONTEXT', {
190 + name: 'Search-only context',
191 + description: 'Retrieve context through search',
192 + preload: false,
193 + inputParams: z.object({}),
194 + execute: localExecute,
195 + });
196 +
197 + await router.create('user_1', {
198 + experimental: {
199 + customTools: [searchOnlyTool],
200 + },
201 + });
202 +
203 + const payload = mockClient.toolRouter.session.create.mock.calls[0][0];
204 + expect(payload.experimental.custom_tools[0]).not.toHaveProperty('preload');
205 + });
206 +
207 it('should not send experimental.custom_tools when customTools is omitted or empty', async () => {
208 await router.create('user_1', { toolkits: ['gmail'] });
209 const payload1 = mockClient.toolRouter.session.create.mock.calls[0][0];
ts/packages/core/test/models/toolRouter.test.ts
-1
@@ -2253,7 +2253,6 @@ describe('ToolRouter', () => {
2253 preload: true,
2254 }),
2255 ],
2256 - custom_toolkits: undefined,
2256 },
2257 });
2258 });