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.

Support SDK-local custom tool preload

Dhawal Upadhyay847a8a04a636
diff --git a/python/composio/core/models/custom_tool.py b/python/composio/core/models/custom_tool.py
index b4664ec56..6a77bf74e 100644
--- a/python/composio/core/models/custom_tool.py
+++ b/python/composio/core/models/custom_tool.py
@@ -156,6 +156,7 @@ def _create_tool(
execute: CustomToolExecuteFn,
extends_toolkit: t.Optional[str] = None,
output_params: t.Optional[t.Type[BaseModel]] = None,
+ preload: t.Optional[bool] = None,
) -> CustomTool:
"""Internal: create and validate a CustomTool."""
context = "experimental.tool"
@@ -218,6 +219,7 @@ def _create_tool(
output_schema=output_schema,
input_params=input_params,
execute=execute,
+ preload=preload,
)
@@ -258,6 +260,7 @@ def _infer_tool_from_function(
description: t.Optional[str] = None,
extends_toolkit: t.Optional[str] = None,
output_params: t.Optional[t.Type[BaseModel]] = None,
+ preload: t.Optional[bool] = None,
annotation_locals: t.Optional[t.Mapping[str, t.Any]] = None,
) -> CustomTool:
"""Create a CustomTool by inferring metadata from a decorated function.
@@ -341,6 +344,7 @@ def _infer_tool_from_function(
execute=execute,
extends_toolkit=extends_toolkit,
output_params=output_params,
+ preload=preload,
)
@@ -372,7 +376,14 @@ class ExperimentalToolkit:
return {"results": []}
"""
- def __init__(self, *, slug: str, name: str, description: str) -> None:
+ def __init__(
+ self,
+ *,
+ slug: str,
+ name: str,
+ description: str,
+ preload: t.Optional[bool] = None,
+ ) -> None:
context = "experimental.Toolkit"
_validate_slug(slug, context)
if not name:
@@ -383,6 +394,7 @@ class ExperimentalToolkit:
self.slug = slug
self.name = name
self.description = description
+ self.preload = preload
self._tools: t.List[CustomTool] = []
@property
@@ -400,6 +412,7 @@ class ExperimentalToolkit:
name: t.Optional[str] = None,
description: t.Optional[str] = None,
output_params: t.Optional[t.Type[BaseModel]] = None,
+ preload: t.Optional[bool] = None,
) -> t.Callable[[t.Callable[..., t.Any]], CustomTool]: ...
def tool(
@@ -410,6 +423,7 @@ class ExperimentalToolkit:
name: t.Optional[str] = None,
description: t.Optional[str] = None,
output_params: t.Optional[t.Type[BaseModel]] = None,
+ preload: t.Optional[bool] = None,
) -> t.Union[CustomTool, t.Callable[[t.Callable[..., t.Any]], CustomTool]]:
"""Decorator to add a tool to this toolkit.
@@ -425,6 +439,7 @@ class ExperimentalToolkit:
name=name,
description=description,
output_params=output_params,
+ preload=preload,
annotation_locals=annotation_locals,
# No extends_toolkit for toolkit tools
)
@@ -441,6 +456,7 @@ class ExperimentalToolkit:
name=name,
description=description,
output_params=output_params,
+ preload=preload,
annotation_locals=_get_caller_locals(),
)
_validate_slug_length(
@@ -479,6 +495,7 @@ class ExperimentalAPI:
description: t.Optional[str] = None,
extends_toolkit: t.Optional[str] = None,
output_params: t.Optional[t.Type[BaseModel]] = None,
+ preload: t.Optional[bool] = None,
) -> t.Callable[[t.Callable[..., t.Any]], CustomTool]: ...
def tool(
@@ -490,6 +507,7 @@ class ExperimentalAPI:
description: t.Optional[str] = None,
extends_toolkit: t.Optional[str] = None,
output_params: t.Optional[t.Type[BaseModel]] = None,
+ preload: t.Optional[bool] = None,
) -> t.Union[CustomTool, t.Callable[[t.Callable[..., t.Any]], CustomTool]]:
"""Decorator to create a custom tool from a function.
@@ -526,6 +544,7 @@ class ExperimentalAPI:
description=description,
extends_toolkit=extends_toolkit,
output_params=output_params,
+ preload=preload,
annotation_locals=annotation_locals,
)
@@ -537,6 +556,7 @@ class ExperimentalAPI:
description=description,
extends_toolkit=extends_toolkit,
output_params=output_params,
+ preload=preload,
annotation_locals=_get_caller_locals(),
)
return decorator
@@ -547,7 +567,28 @@ class ExperimentalAPI:
# ────────────────────────────────────────────────────────────────
-def serialize_custom_tools(tools: t.List[CustomTool]) -> t.List[t.Dict[str, t.Any]]:
+def _serialized_preload_value(
+ preload: t.Optional[bool],
+ 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
+ )
+ if preload is not None or inherited_preload is not None or default_preload:
+ return resolved
+ return None
+
+
+def serialize_custom_tools(
+ tools: t.List[CustomTool],
+ *,
+ default_preload: bool = False,
+) -> t.List[t.Dict[str, t.Any]]:
"""Serialize custom tools into the format expected by the backend."""
result = []
for tool in tools:
@@ -561,12 +602,19 @@ def serialize_custom_tools(tools: t.List[CustomTool]) -> t.List[t.Dict[str, t.An
entry["output_schema"] = tool.output_schema
if tool.extends_toolkit:
entry["extends_toolkit"] = tool.extends_toolkit
+ preload = _serialized_preload_value(
+ tool.preload, inherited_preload=None, default_preload=default_preload
+ )
+ if preload is not None:
+ entry["preload"] = preload
result.append(entry)
return result
def serialize_custom_toolkits(
toolkits: t.Sequence[ExperimentalToolkit],
+ *,
+ default_preload: bool = False,
) -> t.List[t.Dict[str, t.Any]]:
"""Serialize custom toolkits into the format expected by the backend."""
result = []
@@ -581,15 +629,26 @@ def serialize_custom_toolkits(
}
if tool.output_schema:
entry["output_schema"] = tool.output_schema
+ preload = _serialized_preload_value(
+ tool.preload,
+ inherited_preload=tk.preload,
+ default_preload=default_preload,
+ )
+ if preload is not None:
+ entry["preload"] = preload
toolkit_tools.append(entry)
- result.append(
- {
- "slug": tk.slug,
- "name": tk.name,
- "description": tk.description,
- "tools": toolkit_tools,
- }
+ toolkit_entry: t.Dict[str, t.Any] = {
+ "slug": tk.slug,
+ "name": tk.name,
+ "description": tk.description,
+ "tools": toolkit_tools,
+ }
+ preload = _serialized_preload_value(
+ tk.preload, inherited_preload=None, default_preload=default_preload
)
+ if preload is not None:
+ toolkit_entry["preload"] = preload
+ result.append(toolkit_entry)
return result
@@ -729,23 +788,63 @@ def find_custom_tool_map_entry_by_final_slug(
return custom_tools_map.by_final_slug.get(slug.upper())
+def assert_no_custom_tool_slugs_in_preload(
+ preload_tools: t.Union[t.Sequence[str], t.Literal["all"], None],
+ custom_tools_map: t.Optional[CustomToolsMap],
+) -> None:
+ """Reject legacy top-level preload of custom tool slugs."""
+ if preload_tools is None or preload_tools == "all":
+ return
+
+ custom_preload_slugs = []
+ for slug in preload_tools:
+ normalized = slug.upper()
+ if normalized.startswith(LOCAL_TOOL_PREFIX) or (
+ custom_tools_map is not None
+ and (
+ normalized in custom_tools_map.by_original_slug
+ or normalized in custom_tools_map.by_final_slug
+ )
+ ):
+ custom_preload_slugs.append(slug)
+
+ if custom_preload_slugs:
+ raise ValidationError(
+ "Custom tool slugs are not supported in preload.tools: "
+ f"{', '.join(custom_preload_slugs)}. Set preload=True on the SDK "
+ "custom tool or custom toolkit definition instead."
+ )
+
+
def get_preloaded_custom_tool_slugs(
- tool_router_tools: t.Optional[t.Iterable[str]],
custom_tools_map: t.Optional[CustomToolsMap],
+ *,
+ default_preload: bool = False,
) -> t.List[str]:
- """Return final custom tool slugs selected by the backend for preload."""
- if tool_router_tools is None or custom_tools_map is None:
+ """Return final custom tool slugs selected locally for preload."""
+ if custom_tools_map is None:
return []
seen: t.Set[str] = set()
custom_tool_slugs: t.List[str] = []
- for slug in tool_router_tools:
- entry = find_custom_tool_map_entry_by_final_slug(
- custom_tools_map,
- str(slug),
+ for entry in custom_tools_map.by_final_slug.values():
+ toolkit = next(
+ (
+ tk
+ for tk in custom_tools_map.toolkits or []
+ if entry.toolkit and tk.slug.lower() == entry.toolkit.lower()
+ ),
+ None,
+ )
+ should_preload = (
+ entry.handle.preload
+ if entry.handle.preload is not None
+ else toolkit.preload
+ if toolkit is not None and toolkit.preload is not None
+ else default_preload
)
- if entry is None:
+ if not should_preload:
continue
final_slug_key = entry.final_slug.upper()
diff --git a/python/composio/core/models/custom_tool_types.py b/python/composio/core/models/custom_tool_types.py
index 4fae37115..03247cc00 100644
--- a/python/composio/core/models/custom_tool_types.py
+++ b/python/composio/core/models/custom_tool_types.py
@@ -106,6 +106,7 @@ class CustomTool:
execute: CustomToolExecuteFn
extends_toolkit: t.Optional[str] = None
output_schema: t.Optional[t.Dict[str, t.Any]] = None
+ preload: t.Optional[bool] = None
# ────────────────────────────────────────────────────────────────
diff --git a/python/composio/core/models/tool_router.py b/python/composio/core/models/tool_router.py
index d8392d4e6..6817d9c85 100644
--- a/python/composio/core/models/tool_router.py
+++ b/python/composio/core/models/tool_router.py
@@ -19,6 +19,8 @@ from composio.client import HttpClient
from composio.core.models.base import Resource
from composio.core.models.custom_tool import (
ExperimentalToolkit,
+ assert_no_custom_tool_slugs_in_preload,
+ build_custom_tools_map,
build_custom_tools_map_from_response,
get_preloaded_custom_tool_slugs,
serialize_custom_tools,
@@ -627,6 +629,10 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
- 'assistive_prompt' (dict): Configuration for assistive prompt generation.
- 'user_timezone' (str): IANA timezone identifier
(e.g., "America/New_York", "Europe/London").
+ - 'custom_tools' / 'custom_toolkits': SDK custom tools.
+ Set preload=True on a custom tool or toolkit to expose
+ it directly from session.tools(); otherwise custom tools
+ remain search-only.
Example: {'assistive_prompt': {'user_timezone': 'America/New_York'}}
:return: Tool router session object
@@ -716,6 +722,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
workbench=workbench,
preload=preload,
)
+ default_custom_preload = preload is not None and preload.get("tools") == "all"
# Parse manage_connections config
manage_connections = (
@@ -851,6 +858,8 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
# experimental.assistive_prompt_config.user_timezone
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
if experimental is not None:
experimental_payload: t.Dict[str, t.Any] = {}
@@ -866,16 +875,36 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
# Serialize custom tools and toolkits for the backend
custom_tools = experimental.get("custom_tools")
custom_toolkits = experimental.get("custom_toolkits")
+ if custom_tools or custom_toolkits:
+ local_custom_tools_map = build_custom_tools_map(
+ custom_tools or [],
+ custom_toolkits,
+ )
+ assert_no_custom_tool_slugs_in_preload(
+ preload.get("tools") if preload is not None else None,
+ local_custom_tools_map,
+ )
if custom_tools:
experimental_payload["custom_tools"] = serialize_custom_tools(
- custom_tools
+ custom_tools,
+ default_preload=default_custom_preload,
)
if custom_toolkits:
experimental_payload["custom_toolkits"] = serialize_custom_toolkits(
- custom_toolkits
+ custom_toolkits,
+ default_preload=default_custom_preload,
)
+ if (
+ "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"),
+ }
+
if experimental_payload:
create_params["experimental"] = experimental_payload
@@ -897,8 +926,8 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
experimental=session.experimental,
)
preloaded_custom_tool_slugs = get_preloaded_custom_tool_slugs(
- getattr(session, "tool_router_tools", None),
custom_tools_map,
+ default_preload=default_custom_preload,
)
# Transform experimental response:
@@ -930,6 +959,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
user_id=user_id,
preload=_session_preload_config(session),
preloaded_custom_tool_slugs=preloaded_custom_tool_slugs,
+ inline_custom_tools_payload=inline_custom_tools_payload,
)
def use(self, session_id: str) -> ToolRouterSession[TTool, TToolCollection]:
diff --git a/python/composio/core/models/tool_router_session.py b/python/composio/core/models/tool_router_session.py
index 33b86603b..3306afc7d 100644
--- a/python/composio/core/models/tool_router_session.py
+++ b/python/composio/core/models/tool_router_session.py
@@ -105,6 +105,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,
) -> None:
self._client = client
self._provider = provider
@@ -119,6 +120,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
self._custom_tools_map = custom_tools_map
self._user_id = user_id
self._preloaded_custom_tool_slugs = preloaded_custom_tool_slugs or []
+ self._inline_custom_tools_payload = inline_custom_tools_payload
# Create singleton session context if custom tools are bound
self._session_context: t.Optional[SessionContextImpl] = None
@@ -634,11 +636,14 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
Returns relevant tools for the given query with schemas and guidance.
"""
- return self._client.tool_router.session.search(
- session_id=self.session_id,
- queries=[{"use_case": query}],
- model=model if model else omit,
- )
+ 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)
def execute(
self,
@@ -676,12 +681,15 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
)
# Remote execution
- 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,
- )
+ 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)
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 31170586b..9fb79bebf 100644
--- a/python/tests/test_custom_tools.py
+++ b/python/tests/test_custom_tools.py
@@ -12,6 +12,7 @@ Covers:
- Multi-execute routing (all-local, all-remote, mixed, parallel)
"""
+from dataclasses import replace
from unittest.mock import MagicMock
import pytest
@@ -145,6 +146,14 @@ class TestDecoratorTool:
assert fetch_mail.extends_toolkit == "gmail"
+ def test_decorator_with_preload(self):
+ @exp.tool(preload=True)
+ def fetch_context(input: GrepInput, ctx):
+ """Fetch context."""
+ return {}
+
+ assert fetch_context.preload is True
+
def test_decorator_explicit_overrides(self):
@exp.tool(slug="CUSTOM", name="Custom Name", description="Custom desc")
def whatever(input: GrepInput, ctx):
@@ -408,12 +417,23 @@ class TestSerialization:
result = serialize_custom_tools([email_tool])
assert result[0]["extends_toolkit"] == "gmail"
+ def test_serialize_custom_tool_preload_hint(self, grep_tool):
+ preloaded = replace(grep_tool, preload=True)
+ result = serialize_custom_tools([preloaded])
+ assert result[0]["preload"] is True
+
def test_serialize_toolkit(self, role_toolkit):
result = serialize_custom_toolkits([role_toolkit])
assert len(result) == 1
assert result[0]["slug"] == "ROLE_MANAGER"
assert len(result[0]["tools"]) == 1
+ def test_serialize_toolkit_preload_hint(self, role_toolkit):
+ role_toolkit.preload = True
+ result = serialize_custom_toolkits([role_toolkit])
+ assert result[0]["preload"] is True
+ assert result[0]["tools"][0]["preload"] is True
+
# ────────────────────────────────────────────────────────────────
# Routing map tests
diff --git a/python/tests/test_tool_router.py b/python/tests/test_tool_router.py
index 2cefdc4db..ea86ba520 100644
--- a/python/tests/test_tool_router.py
+++ b/python/tests/test_tool_router.py
@@ -5,6 +5,7 @@ from unittest.mock import MagicMock, patch
import pytest
from pydantic import BaseModel, Field
+from composio.exceptions import ValidationError
from composio.core.models.custom_tool import ExperimentalAPI
from composio.core.models.tool_router import (
ToolkitConnectionsDetails,
@@ -628,6 +629,29 @@ class TestToolRouter:
assert kwargs["preload"] == {"tools": "all"}
assert session.preload.tools == "all"
+ def test_create_session_rejects_custom_slug_in_top_level_preload(
+ self, tool_router, mock_client
+ ):
+ @experimental_api.tool(
+ slug="GREP",
+ name="Grep",
+ description="Search local text",
+ )
+ def grep(input: GrepInput, ctx):
+ return {"matches": []}
+
+ with pytest.raises(
+ ValidationError,
+ match="Set preload=True on the SDK custom tool",
+ ):
+ tool_router.create(
+ user_id="user_123",
+ preload={"tools": ["GREP"]},
+ experimental={"custom_tools": [grep]},
+ )
+
+ 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"
@@ -672,6 +696,42 @@ class TestToolRouter:
assert kwargs["execute"] == {"enable_multi_execute": False}
assert session.preload.tools == ["GITHUB_CREATE_ISSUE"]
+ def test_direct_tools_does_not_default_custom_preload_when_preload_overridden(
+ self, tool_router, mock_client
+ ):
+ """Explicit preload config also overrides the custom-tool preload default."""
+
+ @experimental_api.tool(
+ slug="GREP",
+ name="Grep",
+ description="Search local text",
+ )
+ def grep(input: GrepInput, ctx):
+ return {"matches": []}
+
+ mock_response = mock_client.tool_router.session.create.return_value
+ mock_response.config.preload.tools = ["GITHUB_CREATE_ISSUE"]
+ mock_response.experimental = MagicMock()
+ mock_response.experimental.assistive_prompt = None
+ mock_response.experimental.custom_toolkits = []
+ mock_custom_tool = MagicMock()
+ mock_custom_tool.slug = "SERVER_GREP"
+ mock_custom_tool.original_slug = "GREP"
+ mock_custom_tool.extends_toolkit = None
+ mock_response.experimental.custom_tools = [mock_custom_tool]
+
+ tool_router.create(
+ user_id="user_123",
+ session_preset="direct_tools",
+ toolkits=["github"],
+ preload={"tools": ["GITHUB_CREATE_ISSUE"]},
+ experimental={"custom_tools": [grep]},
+ )
+
+ kwargs = mock_client.tool_router.session.create.call_args.kwargs
+ assert kwargs["preload"] == {"tools": ["GITHUB_CREATE_ISSUE"]}
+ assert "preload" not in kwargs["experimental"]["custom_tools"][0]
+
def test_create_session_complex_config(self, tool_router, mock_client):
"""Test creating a session with complex configuration."""
session = tool_router.create(
@@ -1149,18 +1209,19 @@ class TestToolRouter:
mock_client,
mock_provider,
):
- """Custom tools preloaded by the create response are exposed locally."""
+ """Custom tools with SDK preload enabled are exposed locally."""
@experimental_api.tool(
slug="GREP",
name="Grep",
description="Search local text",
+ preload=True,
)
def grep(input: GrepInput, ctx):
return {"matches": []}
mock_response = mock_client.tool_router.session.create.return_value
- mock_response.tool_router_tools = ["COMPOSIO_SEARCH_TOOLS", "server_grep"]
+ mock_response.tool_router_tools = ["COMPOSIO_SEARCH_TOOLS"]
mock_response.experimental = MagicMock()
mock_response.experimental.assistive_prompt = None
mock_response.experimental.custom_toolkits = []
diff --git a/ts/packages/core/src/models/CustomTool.ts b/ts/packages/core/src/models/CustomTool.ts
index 58e602568..efb4d8180 100644
--- a/ts/packages/core/src/models/CustomTool.ts
+++ b/ts/packages/core/src/models/CustomTool.ts
@@ -32,8 +32,8 @@ import {
type CustomToolExecuteFn,
type CustomToolsMap,
type CustomToolsMapEntry,
- type CustomToolDefinition,
- type CustomToolkitDefinition,
+ type CustomToolWireDefinition,
+ type CustomToolkitWireDefinition,
type InputParamsSchema,
} from '../types/customTool.types';
import type { SessionCreateResponse } from '@composio/client/resources/tool-router/session/session.mjs';
@@ -184,6 +184,7 @@ export function createCustomTool<T extends z.ZodType>(
name: validated.name,
description: validated.description,
extendsToolkit: validated.extendsToolkit,
+ preload: validated.preload,
inputSchema,
outputSchema,
inputParams,
@@ -250,6 +251,7 @@ export function createCustomToolkit(
slug: slugResult.data,
name: validated.name,
description: validated.description,
+ preload: validated.preload,
tools: options.tools,
};
}
@@ -340,7 +342,36 @@ export function buildCustomToolsMap(
* @param tools - The custom tools to serialize
* @returns Array of CustomToolDefinition for the API payload
*/
-export function serializeCustomTools(tools: CustomTool[]): CustomToolDefinition[] {
+type CustomToolSerializationOptions = {
+ defaultPreload?: boolean;
+};
+
+function shouldSerializePreload(
+ preload: boolean | undefined,
+ inheritedPreload: boolean | undefined,
+ defaultPreload: boolean
+): boolean | undefined {
+ const resolved = preload ?? inheritedPreload ?? defaultPreload;
+ if (preload !== undefined || inheritedPreload !== undefined || defaultPreload) {
+ return resolved;
+ }
+ return 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,
@@ -348,6 +379,7 @@ export function serializeCustomTools(tools: CustomTool[]): CustomToolDefinition[
input_schema: handle.inputSchema,
...(handle.outputSchema ? { output_schema: handle.outputSchema } : {}),
...(handle.extendsToolkit ? { extends_toolkit: handle.extendsToolkit } : {}),
+ ...preloadWireProperty(handle.preload, undefined, defaultPreload),
}));
}
@@ -358,17 +390,23 @@ export function serializeCustomTools(tools: CustomTool[]): CustomToolDefinition[
* @param toolkits - The custom toolkits to serialize
* @returns Array of CustomToolkitDefinition for the API payload
*/
-export function serializeCustomToolkits(toolkits: CustomToolkit[]): CustomToolkitDefinition[] {
+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),
})),
}));
}
@@ -452,28 +490,62 @@ export function findCustomToolMapEntryByFinalSlug(
}
/**
- * Resolve custom tools that the backend selected for direct preload.
+ * Reject legacy attempts to preload custom tools through top-level preload.tools.
*
- * The backend is the source of truth for preload expansion, including "all".
- * The SDK only keeps the final custom slugs it can serve locally because
- * the session tools endpoint only returns backend-managed tool schemas.
+ * 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 getPreloadedCustomToolSlugs(
- toolRouterTools: readonly string[] | undefined,
+export function assertNoCustomToolSlugsInPreload(
+ preloadTools: readonly string[] | 'all' | undefined,
customToolsMap: CustomToolsMap | undefined
+): void {
+ if (!preloadTools || preloadTools === 'all') {
+ return;
+ }
+
+ const customPreloadSlugs = preloadTools.filter(slug => {
+ const normalized = slug.toUpperCase();
+ return (
+ normalized.startsWith(LOCAL_TOOL_PREFIX) ||
+ customToolsMap?.byOriginalSlug.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 (!toolRouterTools?.length || !customToolsMap) {
+ if (!customToolsMap) {
return [];
}
const seen = new Set<string>();
const customToolSlugs: string[] = [];
- for (const slug of toolRouterTools) {
- const entry = findCustomToolMapEntryByFinalSlug(customToolsMap, slug);
- if (!entry) {
+ 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;
}
diff --git a/ts/packages/core/src/models/ToolRouter.ts b/ts/packages/core/src/models/ToolRouter.ts
index 0cfe85f8e..58f14b8b1 100644
--- a/ts/packages/core/src/models/ToolRouter.ts
+++ b/ts/packages/core/src/models/ToolRouter.ts
@@ -45,6 +45,8 @@ import {
} from '../lib/toolRouterParams';
import { ToolRouterSession } from './ToolRouterSession';
import {
+ assertNoCustomToolSlugsInPreload,
+ buildCustomToolsMap,
buildCustomToolsMapFromResponse,
getPreloadedCustomToolSlugs,
serializeCustomTools,
@@ -111,6 +113,9 @@ export class ToolRouter<
* },
* });
*
+ * // Custom tools are searched by default. Set `preload: true` on a custom
+ * // tool or toolkit to expose it directly from `session.tools()`.
+ *
* // Expose all tools allowed by filters directly, without meta/helper tools.
* // `preload.tools = "all"` requires a positive filter such as `toolkits`.
* const directSession = await composio.create('user_123', {
@@ -129,6 +134,12 @@ export class ToolRouter<
// Extract custom tools/toolkits from experimental config
const customTools = routerConfig.experimental?.customTools;
const customToolkits = routerConfig.experimental?.customToolkits;
+ const defaultCustomPreload = routerConfig.preload?.tools === 'all';
+ const localCustomToolsMap =
+ customTools?.length || customToolkits?.length
+ ? buildCustomToolsMap(customTools ?? [], customToolkits)
+ : undefined;
+ assertNoCustomToolSlugsInPreload(routerConfig.preload?.tools, localCustomToolsMap);
// Build the typed experimental payload for the backend
const experimentalPayload: SessionCreateParams['experimental'] = {};
@@ -140,11 +151,22 @@ export class ToolRouter<
}
if (customTools?.length) {
- experimentalPayload.custom_tools = serializeCustomTools(customTools);
+ experimentalPayload.custom_tools = serializeCustomTools(customTools, {
+ defaultPreload: defaultCustomPreload,
+ });
}
if (customToolkits?.length) {
- experimentalPayload.custom_toolkits = serializeCustomToolkits(customToolkits);
+ experimentalPayload.custom_toolkits = serializeCustomToolkits(customToolkits, {
+ defaultPreload: defaultCustomPreload,
+ });
}
+ const inlineCustomToolsPayload =
+ experimentalPayload.custom_tools || experimentalPayload.custom_toolkits
+ ? {
+ custom_tools: experimentalPayload.custom_tools,
+ custom_toolkits: experimentalPayload.custom_toolkits,
+ }
+ : undefined;
const multiAccountPayload = transformToolRouterMultiAccountParams(routerConfig.multiAccount);
@@ -182,10 +204,8 @@ export class ToolRouter<
}
const metadata = {
...getSessionMetadata(session),
- preloadedCustomToolSlugs: getPreloadedCustomToolSlugs(
- session.tool_router_tools,
- customToolsMap
- ),
+ preloadedCustomToolSlugs: getPreloadedCustomToolSlugs(customToolsMap, defaultCustomPreload),
+ inlineCustomToolsPayload,
};
const assistivePrompt = session.experimental?.assistive_prompt;
diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.ts
index 6231ff8f3..61f1d21f4 100644
--- a/ts/packages/core/src/models/ToolRouterSession.ts
+++ b/ts/packages/core/src/models/ToolRouterSession.ts
@@ -39,7 +39,10 @@ import type {
} from '../types/customTool.types';
import type { Tool, ToolExecuteResponse } from '../types/tool.types';
import type { SessionProxyExecuteParams } from '../types/toolRouter.types';
-import type { SessionExecuteParams } from '@composio/client/resources/tool-router/session/session.mjs';
+import type {
+ SessionExecuteParams,
+ SessionSearchParams,
+} from '@composio/client/resources/tool-router/session/session.mjs';
import { SessionProxyExecuteParamsSchema } from '../types/toolRouter.types';
import { SessionContextImpl } from './SessionContext';
import { findCustomTool, executeCustomTool } from './customToolExecution';
@@ -62,6 +65,7 @@ export class ToolRouterSession<
public readonly configVersion?: number;
public readonly warnings: ToolRouterSessionWarning[];
private readonly preloadedCustomToolSlugs: string[];
+ private readonly inlineCustomToolsPayload: ToolRouterSessionMetadata['inlineCustomToolsPayload'];
/** Singleton session context — shared across all custom tool executions */
private readonly sessionContext?: SessionContext;
@@ -89,6 +93,7 @@ export class ToolRouterSession<
this.configVersion = metadata?.configVersion;
this.warnings = metadata?.warnings ?? [];
this.preloadedCustomToolSlugs = metadata?.preloadedCustomToolSlugs ?? [];
+ this.inlineCustomToolsPayload = metadata?.inlineCustomToolsPayload;
// Create singleton session context if custom tools are bound
if (customToolsMap && userId) {
@@ -354,10 +359,12 @@ export class ToolRouterSession<
query: string;
toolkits?: string[];
}): Promise<ToolRouterSessionSearchResponse> {
- const response = await this.client.toolRouter.session.search(this.sessionId, {
+ const searchParams: SessionSearchParams & { toolkits?: string[] } = {
queries: [{ use_case: params.query }],
...(params.toolkits?.length ? { toolkits: params.toolkits } : {}),
- });
+ ...(this.inlineCustomToolsPayload ? { experimental: this.inlineCustomToolsPayload } : {}),
+ };
+ const response = await this.client.toolRouter.session.search(this.sessionId, searchParams);
const transformed = transformSearchResponse(response);
return ToolRouterSessionSearchResponseSchema.parse(transformed);
}
@@ -395,6 +402,7 @@ 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 e077af92c..2d72b04e4 100644
--- a/ts/packages/core/src/types/customTool.types.ts
+++ b/ts/packages/core/src/types/customTool.types.ts
@@ -135,6 +135,12 @@ export const CreateCustomToolBaseSchema = z.object({
* Leave empty for tools that don't need any Composio-managed authentication.
*/
extendsToolkit: z.string().optional(),
+ preload: z
+ .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.'
+ ),
});
/** Options for creating a custom tool via `createCustomTool()`. */
@@ -163,6 +169,11 @@ export interface CustomTool {
* Undefined means the tool doesn't need any Composio-managed authentication.
*/
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.
+ */
+ readonly preload?: boolean;
readonly inputSchema: Record<string, unknown>;
/** JSON Schema representation of the output (for backend documentation) */
readonly outputSchema?: Record<string, unknown>;
@@ -175,6 +186,10 @@ export interface CustomTool {
/** Serialized tool definition sent to backend for search indexing. Uses official client type. */
export type CustomToolDefinition = SessionCreateParams.Experimental.CustomTool;
+export type CustomToolWireDefinition = CustomToolDefinition & {
+ preload?: boolean;
+};
+
// ────────────────────────────────────────────────────────────────
// Custom toolkit types
// ────────────────────────────────────────────────────────────────
@@ -186,6 +201,12 @@ export type CustomToolDefinition = SessionCreateParams.Experimental.CustomTool;
export const CreateCustomToolkitBaseSchema = z.object({
name: z.string().min(1, 'createCustomToolkit: name is required'),
description: z.string().min(1, 'createCustomToolkit: description is required'),
+ preload: z
+ .boolean()
+ .optional()
+ .describe(
+ 'When true, expose tools in this custom toolkit directly from session.tools(). Tool-level preload values override this default.'
+ ),
});
/** Options for creating a custom toolkit via `createCustomToolkit()`. */
@@ -202,12 +223,27 @@ export interface CustomToolkit {
readonly slug: string;
readonly name: string;
readonly description: string;
+ /**
+ * Default direct-exposure setting for tools in this custom toolkit.
+ * Tool-level preload values override this default.
+ */
+ readonly preload?: boolean;
readonly tools: readonly CustomTool[];
}
/** Serialized toolkit definition sent to backend. Uses official client type. */
export type CustomToolkitDefinition = SessionCreateParams.Experimental.CustomToolkit;
+export type CustomToolkitWireDefinition = Omit<CustomToolkitDefinition, 'tools'> & {
+ preload?: boolean;
+ tools: Array<CustomToolkitDefinition['tools'][number] & { preload?: boolean }>;
+};
+
+export interface InlineCustomToolsWirePayload {
+ custom_tools?: CustomToolWireDefinition[];
+ custom_toolkits?: CustomToolkitWireDefinition[];
+}
+
// ────────────────────────────────────────────────────────────────
// Internal routing types
// ────────────────────────────────────────────────────────────────
diff --git a/ts/packages/core/src/types/toolRouter.types.ts b/ts/packages/core/src/types/toolRouter.types.ts
index 988294859..143b844f9 100644
--- a/ts/packages/core/src/types/toolRouter.types.ts
+++ b/ts/packages/core/src/types/toolRouter.types.ts
@@ -7,6 +7,7 @@ import type { SessionCreateResponse } from '@composio/client/resources/tool-rout
import type {
CustomTool,
CustomToolkit,
+ InlineCustomToolsWirePayload,
RegisteredCustomTool,
RegisteredCustomToolkit,
} from './customTool.types';
@@ -575,6 +576,7 @@ export interface ToolRouterSessionMetadata {
configVersion?: number;
warnings?: ToolRouterSessionWarning[];
preloadedCustomToolSlugs?: string[];
+ inlineCustomToolsPayload?: InlineCustomToolsWirePayload;
}
export const SessionProxyExecuteParamsSchema = z.object({
diff --git a/ts/packages/core/test/models/customToolRouting.test.ts b/ts/packages/core/test/models/customToolRouting.test.ts
index 1c70c1e8b..6b12676e6 100644
--- a/ts/packages/core/test/models/customToolRouting.test.ts
+++ b/ts/packages/core/test/models/customToolRouting.test.ts
@@ -166,6 +166,25 @@ describe('ToolRouter.create() with customTools', () => {
expect(payload.experimental.custom_tools[0].extends_toolkit).toBe('meta_ads');
});
+ it('should send custom tool preload hints under experimental', async () => {
+ const preloadedTool = createCustomTool('PINNED_CONTEXT', {
+ name: 'Pinned context',
+ description: 'Retrieve pinned user context',
+ preload: true,
+ inputParams: z.object({}),
+ execute: localExecute,
+ });
+
+ await router.create('user_1', {
+ experimental: {
+ customTools: [preloadedTool],
+ },
+ });
+
+ const payload = mockClient.toolRouter.session.create.mock.calls[0][0];
+ expect(payload.experimental.custom_tools[0].preload).toBe(true);
+ });
+
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 3569291e1..56b81e27b 100644
--- a/ts/packages/core/test/models/toolRouter.test.ts
+++ b/ts/packages/core/test/models/toolRouter.test.ts
@@ -296,6 +296,23 @@ describe('ToolRouter', () => {
expect(session.preload.tools).toBe('all');
});
+ it('should reject custom tool slugs in top-level preload', async () => {
+ const grepTool = createCustomTool('GREP', {
+ name: 'Grep',
+ description: 'Search local text',
+ inputParams: z.object({ pattern: z.string() }),
+ execute: vi.fn(async () => ({ matches: [] })),
+ });
+
+ await expect(
+ toolRouter.create(userId, {
+ preload: { tools: ['GREP'] },
+ experimental: { customTools: [grepTool] },
+ })
+ ).rejects.toThrow('Set preload: true on the SDK custom tool');
+ expect(mockClient.toolRouter.session.create).not.toHaveBeenCalled();
+ });
+
it('should apply the direct_tools session preset defaults', async () => {
mockClient.toolRouter.session.create.mockResolvedValueOnce({
...mockSessionCreateResponse,
@@ -365,6 +382,42 @@ describe('ToolRouter', () => {
expect(session.preload.tools).toEqual(['GITHUB_CREATE_ISSUE']);
});
+ it('should not apply direct_tools custom preload default when preload is explicitly overridden', async () => {
+ const grepTool = createCustomTool('GREP', {
+ name: 'Grep',
+ description: 'Search local text',
+ inputParams: z.object({ pattern: z.string() }),
+ execute: vi.fn(async () => ({ matches: [] })),
+ });
+
+ mockClient.toolRouter.session.create.mockResolvedValueOnce({
+ ...mockSessionCreateResponse,
+ config: {
+ preload: { tools: ['GITHUB_CREATE_ISSUE'] },
+ },
+ experimental: {
+ custom_tools: [
+ {
+ slug: 'SERVER_GREP',
+ original_slug: 'GREP',
+ extends_toolkit: null,
+ },
+ ],
+ },
+ });
+
+ await toolRouter.create(userId, {
+ sessionPreset: 'direct_tools',
+ toolkits: ['github'],
+ preload: { tools: ['GITHUB_CREATE_ISSUE'] },
+ experimental: { customTools: [grepTool] },
+ });
+
+ const payload = mockClient.toolRouter.session.create.mock.calls[0][0];
+ expect(payload.preload).toEqual({ tools: ['GITHUB_CREATE_ISSUE'] });
+ expect(payload.experimental?.custom_tools?.[0]).not.toHaveProperty('preload');
+ });
+
it('should create a session with user ID only and verify MCP type transformation', async () => {
mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
@@ -2164,6 +2217,47 @@ describe('ToolRouter', () => {
});
});
+ it('should pass inline custom tools to search', async () => {
+ const grepTool = createCustomTool('GREP', {
+ name: 'Grep',
+ description: 'Search local text',
+ preload: true,
+ inputParams: z.object({ pattern: z.string() }),
+ execute: vi.fn(async () => ({ matches: [] })),
+ });
+ mockClient.toolRouter.session.create.mockResolvedValueOnce({
+ ...mockSessionCreateResponse,
+ experimental: {
+ custom_tools: [
+ {
+ slug: 'LOCAL_GREP',
+ original_slug: 'GREP',
+ extends_toolkit: null,
+ },
+ ],
+ },
+ });
+ mockClient.toolRouter.session.search.mockResolvedValueOnce(mockSearchResponse);
+
+ const session = await toolRouter.create(userId, {
+ experimental: { customTools: [grepTool] },
+ });
+ await session.search({ query: 'search local text' });
+
+ expect(mockClient.toolRouter.session.search).toHaveBeenCalledWith(sessionId, {
+ queries: [{ use_case: 'search local text' }],
+ experimental: {
+ custom_tools: [
+ expect.objectContaining({
+ slug: 'GREP',
+ preload: true,
+ }),
+ ],
+ custom_toolkits: undefined,
+ },
+ });
+ });
+
it('should propagate search API errors', async () => {
mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
mockClient.toolRouter.session.search.mockRejectedValueOnce(new Error('Search failed'));
@@ -2343,10 +2437,11 @@ describe('ToolRouter', () => {
expect(tools).toBe('mocked-wrapped-tools');
});
- it('should include preloaded custom tools selected by the create response', async () => {
+ it('should include custom tools with preload enabled locally', async () => {
const grepTool = createCustomTool('GREP', {
name: 'Grep',
description: 'Search local text',
+ preload: true,
inputParams: z.object({
pattern: z.string().describe('Pattern to search for'),
}),
@@ -2355,7 +2450,7 @@ describe('ToolRouter', () => {
mockClient.toolRouter.session.create.mockResolvedValueOnce({
...mockSessionCreateResponse,
- tool_router_tools: ['COMPOSIO_SEARCH_TOOLS', 'server_grep'],
+ tool_router_tools: ['COMPOSIO_SEARCH_TOOLS'],
experimental: {
custom_tools: [
{
@@ -2385,7 +2480,7 @@ describe('ToolRouter', () => {
expect(tools).toBe('mocked-custom-tools');
});
- it('should not expose custom tools unless the backend preloaded them', async () => {
+ it('should not expose custom tools unless SDK preload selects them', async () => {
const grepTool = createCustomTool('GREP', {
name: 'Grep',
description: 'Search local text',
@@ -2411,7 +2506,6 @@ describe('ToolRouter', () => {
mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');
const session = await toolRouter.create(userId, {
- preload: { tools: 'all' },
experimental: { customTools: [grepTool] },
});
await session.tools();
@@ -2420,6 +2514,41 @@ describe('ToolRouter', () => {
expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS']);
});
+ it('should expose custom tools by default for preload all', async () => {
+ const grepTool = createCustomTool('GREP', {
+ name: 'Grep',
+ description: 'Search local text',
+ inputParams: z.object({
+ pattern: z.string(),
+ }),
+ execute: vi.fn(async () => ({ matches: [] })),
+ });
+
+ mockClient.toolRouter.session.create.mockResolvedValueOnce({
+ ...mockSessionCreateResponse,
+ tool_router_tools: ['COMPOSIO_SEARCH_TOOLS'],
+ experimental: {
+ custom_tools: [
+ {
+ slug: 'LOCAL_GREP',
+ original_slug: 'GREP',
+ extends_toolkit: null,
+ },
+ ],
+ },
+ });
+ mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');
+
+ const session = await toolRouter.create(userId, {
+ preload: { tools: 'all' },
+ experimental: { customTools: [grepTool] },
+ });
+ await session.tools();
+
+ const wrappedTools = mockProvider.wrapTools.mock.calls[0][0] as Array<{ slug: string }>;
+ expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS', 'LOCAL_GREP']);
+ });
+
it('should handle tools fetching errors', async () => {
mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);