Skip to content

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

Tighten Tool Router preload changes

Dhawal Upadhyayd2155c028b30
diff --git a/python/composio/core/models/custom_tool.py b/python/composio/core/models/custom_tool.py
index 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 None
def 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"] = preload
toolkit_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.py
index 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.py
index 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.tools
return 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 config
manage_connections = (
@@ -859,7 +878,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
custom_tools: t.Optional[t.List[CustomTool]] = None
custom_toolkits: t.Optional[t.List[ExperimentalToolkit]] = None
local_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] = None
if 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_payload
or "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_payload
diff --git a/python/composio/core/models/tool_router_session.py b/python/composio/core/models/tool_router_session.py
index 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_params
from composio.client import HttpClient
from 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 = 5
class 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 = client
self._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] = None
diff --git a/python/tests/test_custom_tools.py b/python/tests/test_custom_tools.py
index 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) == 1
diff --git a/python/tests/test_tool_router.py b/python/tests/test_tool_router.py
index 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.md
index 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.
## Setup
1. **Install dependencies:**
-
```bash
pnpm install
```
2. **Configure environment:**
-
```bash
cp .env.example .env
```
@@ -48,7 +46,6 @@ pnpm direct-tools
## Customization
Edit `src/index.ts` to:
-
- Add specific apps you want to integrate with
- Implement your business logic
- Add error handling and logging
diff --git a/ts/packages/core/src/lib/toolRouterParams.ts b/ts/packages/core/src/lib/toolRouterParams.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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,
},
});
});