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
});