@devries-cameron20 / composio Mirror · read-only / commits / e8782784b
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, 06:00 UTC

feat(python): rename custom tools options to local_tools and local_toolkits (#5216)

## Summary Asked for: stop calling SDK-defined in-process tools "custom tools" and rename the SDK options to **local tools**, in line with the docs rename in #5213. "Custom toolkits" also refers to the unrelated server-side Custom MCP toolkits (`composio.experimental.custom_toolkits`, `CUSTOM_*` slugs), and the overlap was confusing. These tools already get the `LOCAL_` slug prefix. This is the Python counterpart of #5215. New names, with the old names kept as deprecated aliases: | New | Deprecated alias (still works) | |---|---| | `experimental={"local_tools": ..., "local_toolkits": ...}` on `composio.create()` | `"custom_tools"` / `"custom_toolkits"` | | `composio.use(..., local_tools=..., local_toolkits=...)` | `custom_tools=` / `custom_toolkits=` | | `session.local_tools(toolkit=...)` / `session.local_toolkits()` | `session.custom_tools()` / `session.custom_toolkits()` | | `LocalTool`, `LocalToolkit`, `RegisteredLocalTool`, `RegisteredLocalToolkit` | `CustomTool`, `RegisteredCustomTool`, `RegisteredCustomToolkit` | - **Deprecation warnings:** the old options and session methods emit `ComposioDeprecationWarning`, e.g. "`custom_tools` is deprecated; use `local_tools`", pointing at the caller's line. The old type names are plain aliases with no warning, so `from composio import *` stays quiet. This matches the TypeScript PR. - **Passing both names** for the same option raises `InvalidParams` (``Pass either `local_tools` or `custom_tools`, not both``) before any API call. - **Request body unchanged:** the API still receives `experimental.custom_tools` / `custom_toolkits`. Tests assert these keys for create, attach, search, execute and execute_meta. - **Not renamed:** internal names (`custom_tool.py`, `CustomToolsMap`, wire types), the MCP server's `custom_tools` allowed-tools list in `mcp.py` (a different feature), and the server-side Custom MCP surface. - **`session_config_id`:** the Python SDK has no rule against combining it with local tools, unlike TypeScript, so nothing changed there. - **Examples** under `python/examples/` use the new names. ## Verification - `nox -s chk`: Ruff passes. mypy finds no issues in `composio/`, `providers/`, `tests/` and `scripts/`. - `nox -s chk_examples`: 25/25 pass. - `pytest tests/test_custom_tools.py tests/test_tool_router.py tests/test_imports.py tests/test_sdk.py`: 379 passed, 2 skipped. - Full `tests/` suite (before the last commit): 2650 passed, 34 skipped, 1 failed. The failure is `test_path_join_guardrail.py::test_module_constant_exemption_requires_a_literal`, which also fails on a clean `origin/next`. - `python -W error::UserWarning -c "from composio import *"`: runs without warnings. ## Follow-up - **Docs:** once this is released, switch the docs code samples to `local_tools` / `local_toolkits` and remove the "the SDK options keep their names" note added in #5213. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Palash Kala [zen] <palash@composio.dev> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: jkomyno <alberto@composio.dev>

composio-zen[bot] committed Nov 4, 2026 at 23:56 UTC e8782784b9af1cdc46895554235b6cf51398e04c
11 files changed +426 -55
python/composio/__init__.py
+4 -1
@@ -1,7 +1,8 @@
1 from .__version__ import __version__
2 -from .core.models.custom_tool import ExperimentalToolkit
2 +from .core.models.custom_tool import ExperimentalToolkit, LocalToolkit
3 from .core.models.custom_tool_types import (
4 CustomTool,
5 + LocalTool,
6 SessionContext,
7 )
8 from .core.models.tool_router_constants import SESSION_PRESET_DIRECT_TOOLS
@@ -36,6 +37,8 @@ __all__ = (
37 "ComposioDeprecationWarning",
38 "CustomTool",
39 "ExperimentalToolkit",
40 + "LocalTool",
41 + "LocalToolkit",
42 "RemoteFile",
43 "SessionContext",
44 "SESSION_PRESET_DIRECT_TOOLS",
python/composio/core/models/__init__.py
+8 -1
@@ -1,11 +1,14 @@
1 from .auth_configs import AuthConfigs
2 from .connected_accounts import ConnectedAccounts
3 -from .custom_tool import ExperimentalToolkit
3 +from .custom_tool import ExperimentalToolkit, LocalToolkit
4 from .custom_tool_types import (
5 CustomTool,
6 + LocalTool,
7 ProxyExecuteBinaryData,
8 RegisteredCustomTool,
9 RegisteredCustomToolkit,
10 + RegisteredLocalTool,
11 + RegisteredLocalToolkit,
12 SessionContext,
13 ToolRouterSessionProxyExecuteBlocked,
14 ToolRouterSessionProxyExecuteCompleted,
@@ -62,6 +65,8 @@ __all__ = [
65 "ExperimentalCustomToolkits",
66 "ExperimentalToolkit",
67 "ExperimentalUsage",
68 + "LocalTool",
69 + "LocalToolkit",
70 "UsageSummaryResponse",
71 "Keyring",
72 "Logs",
@@ -69,6 +74,8 @@ __all__ = [
74 "ProxyExecuteBinaryData",
75 "RegisteredCustomTool",
76 "RegisteredCustomToolkit",
77 + "RegisteredLocalTool",
78 + "RegisteredLocalToolkit",
79 "RemoteFile",
80 "SessionContext",
81 "SESSION_PRESET_DIRECT_TOOLS",
python/composio/core/models/custom_tool.py
+7 -3
@@ -32,8 +32,8 @@ Usage::
32 session = composio.create(
33 user_id="default",
34 experimental={
35 - "custom_tools": [grep],
36 - "custom_toolkits": [dev_tools],
35 + "local_tools": [grep],
36 + "local_toolkits": [dev_tools],
37 },
38 )
39 """
@@ -438,7 +438,7 @@ class ExperimentalToolkit:
438 """Custom toolkit that groups related tools under one namespace.
439
440 Use ``@toolkit.tool()`` to add tools. Pass the toolkit to
441 - ``composio.create(experimental={"custom_toolkits": [toolkit]})``.
441 + ``composio.create(experimental={"local_toolkits": [toolkit]})``.
442
443 Tools added to a toolkit must NOT use ``extends_toolkit`` — they
444 inherit the toolkit identity instead.
@@ -550,6 +550,10 @@ class ExperimentalToolkit:
550 return decorator
551
552
553 +LocalToolkit = ExperimentalToolkit
554 +"""Toolkit that groups local tools, created with ``composio.experimental.Toolkit()``."""
555 +
556 +
557 # ────────────────────────────────────────────────────────────────
558 # Serialization (for backend API payload)
559 # ────────────────────────────────────────────────────────────────
python/composio/core/models/custom_tool_types.py
+13 -2
@@ -188,7 +188,7 @@ class SessionContext(te.Protocol):
188 class CustomTool:
189 """Custom tool definition returned from ``@composio.experimental.tool()``.
190
191 - Pass to ``composio.create(user_id, experimental={"custom_tools": [...]})``
191 + Pass to ``composio.create(user_id, experimental={"local_tools": [...]})``
192 to bind to a session.
193 """
194
@@ -203,6 +203,10 @@ class CustomTool:
203 preload: t.Optional[bool] = None
204
205
206 +LocalTool = CustomTool
207 +"""Definition of one of the SDK's local tools, returned from ``@composio.experimental.tool()``."""
208 +
209 +
210 CustomToolWireDefinition = session_create_params.ExperimentalCustomTool
211 CustomToolkitWireDefinition = session_create_params.ExperimentalCustomToolkit
212
@@ -244,7 +248,7 @@ class CustomToolsMap:
248
249
250 # ────────────────────────────────────────────────────────────────
247 -# Registered types (returned by session.custom_tools() / .custom_toolkits())
251 +# Registered types (returned by session.local_tools() / .local_toolkits())
252 # ────────────────────────────────────────────────────────────────
253
254
@@ -268,3 +272,10 @@ class RegisteredCustomToolkit:
272 name: str
273 description: str
274 tools: t.List[RegisteredCustomTool]
275 +
276 +
277 +RegisteredLocalTool = RegisteredCustomTool
278 +"""One of the session's local tools, as returned by ``session.local_tools()``."""
279 +
280 +RegisteredLocalToolkit = RegisteredCustomToolkit
281 +"""A toolkit of the session's local tools, as returned by ``session.local_toolkits()``."""
python/composio/core/models/tool_router.py
+82 -17
@@ -9,6 +9,7 @@ from __future__ import annotations
9
10 import logging
11 import typing as t
12 +import warnings
13 from dataclasses import dataclass
14 from enum import Enum
15 from urllib.parse import urlsplit
@@ -27,6 +28,7 @@ from composio.client import HttpClient
28 from composio.core.models.base import Resource, credential_headers, scope_headers
29 from composio.core.models.custom_tool import (
30 ExperimentalToolkit,
31 + LocalToolkit,
32 assert_no_custom_tool_slugs_in_preload,
33 build_custom_tools_map,
34 build_custom_tools_map_from_response,
@@ -38,6 +40,7 @@ from composio.core.models.custom_tool_types import (
40 CustomTool,
41 CustomToolsMap,
42 InlineCustomToolsWirePayload,
43 + LocalTool,
44 )
45 from composio.core.models.inline_custom_tools_payload import (
46 inline_custom_tools_attach_experimental,
@@ -65,7 +68,11 @@ from composio.core.models.tool_router_session_delete import (
68 from composio.core.models.tool_router_session_files import ToolRouterSessionFilesMount
69 from composio.core.provider import TTool, TToolCollection
70 from composio.core.provider.base import BaseProvider
68 -from composio.exceptions import InvalidParams, MCPDestinationError
71 +from composio.exceptions import (
72 + ComposioDeprecationWarning,
73 + InvalidParams,
74 + MCPDestinationError,
75 +)
76
77 logger = logging.getLogger(__name__)
78
@@ -410,6 +417,34 @@ def _apply_session_preset_defaults(
417 )
418
419
420 +_LocalOption = t.TypeVar("_LocalOption")
421 +
422 +
423 +def _resolve_local_option(
424 + new_name: str,
425 + new_value: t.Optional[_LocalOption],
426 + old_name: str,
427 + old_value: t.Optional[_LocalOption],
428 +) -> t.Optional[_LocalOption]:
429 + # `custom_*` options were renamed to `local_*` because "custom toolkits"
430 + # also names the server-side Custom MCP toolkits.
431 + if old_value is None:
432 + return new_value
433 + if new_value is not None:
434 + raise InvalidParams(
435 + f"Pass either `{new_name}` or `{old_name}`, not both. "
436 + f"`{old_name}` is a deprecated alias for `{new_name}`."
437 + )
438 + warnings.warn(
439 + f"`{old_name}` is deprecated; use `{new_name}`",
440 + ComposioDeprecationWarning,
441 + # Point at the caller of create()/use(), past this helper and the
442 + # Resource tracing wrapper around those methods.
443 + stacklevel=4,
444 + )
445 + return old_value
446 +
447 +
448 def _prepare_inline_custom_tools(
449 *,
450 custom_tools: t.Optional[t.List[CustomTool]],
@@ -464,11 +499,15 @@ class ToolRouterExperimentalConfig(te.TypedDict, total=False):
499
500 Attributes:
501 assistive_prompt: Configuration for assistive prompt generation.
467 - custom_tools: Custom tools to include in the session.
468 - custom_toolkits: Custom toolkits with grouped tools.
502 + local_tools: Local tools to include in the session.
503 + local_toolkits: Local toolkits with grouped tools.
504 + custom_tools: Deprecated alias for ``local_tools``.
505 + custom_toolkits: Deprecated alias for ``local_toolkits``.
506 """
507
508 assistive_prompt: ToolRouterAssistivePromptConfig
509 + local_tools: t.List[LocalTool]
510 + local_toolkits: t.List[LocalToolkit]
511 custom_tools: t.List[CustomTool]
512 custom_toolkits: t.List[ExperimentalToolkit]
513 no_elicitation_support_fallback: t.Literal["deny", "allow"]
@@ -958,12 +997,14 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
997 - 'assistive_prompt' (dict): Configuration for assistive prompt generation.
998 - 'user_timezone' (str): IANA timezone identifier
999 (e.g., "America/New_York", "Europe/London").
961 - - 'custom_tools' / 'custom_toolkits': SDK custom tools.
1000 + - 'local_tools' / 'local_toolkits': local tools that
1001 + run in-process. 'custom_tools' / 'custom_toolkits'
1002 + are deprecated aliases.
1003 - 'no_elicitation_support_fallback' ('deny' or 'allow'):
1004 what happens to a call that needs approval when the
1005 session's MCP client can't ask the user.
965 - Set preload=True on a custom tool or toolkit to expose
966 - it directly from session.tools(); otherwise custom tools
1006 + Set preload=True on a local tool or toolkit to expose
1007 + it directly from session.tools(); otherwise local tools
1008 remain search-only.
1009 Example: {'assistive_prompt': {'user_timezone': 'America/New_York'}}
1010 :param proxy_execute: Optional proxy execute configuration: a bool or
@@ -1286,9 +1327,19 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1327 if fallback is not None:
1328 experimental_payload["no_elicitation_support_fallback"] = fallback
1329
1289 - # Serialize custom tools and toolkits for the backend
1290 - custom_tools = experimental.get("custom_tools")
1291 - custom_toolkits = experimental.get("custom_toolkits")
1330 + # Serialize local tools and toolkits for the backend
1331 + custom_tools = _resolve_local_option(
1332 + "local_tools",
1333 + experimental.get("local_tools"),
1334 + "custom_tools",
1335 + experimental.get("custom_tools"),
1336 + )
1337 + custom_toolkits = _resolve_local_option(
1338 + "local_toolkits",
1339 + experimental.get("local_toolkits"),
1340 + "custom_toolkits",
1341 + experimental.get("custom_toolkits"),
1342 + )
1343
1344 inline_custom_tools_payload = _prepare_inline_custom_tools(
1345 custom_tools=custom_tools,
@@ -1378,6 +1429,8 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1429 self,
1430 session_id: str,
1431 *,
1432 + local_tools: t.Optional[t.List[LocalTool]] = None,
1433 + local_toolkits: t.Optional[t.List[LocalToolkit]] = None,
1434 custom_tools: t.Optional[t.List[CustomTool]] = None,
1435 custom_toolkits: t.Optional[t.List[ExperimentalToolkit]] = None,
1436 mcp: t.Literal[True],
@@ -1388,6 +1441,8 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1441 self,
1442 session_id: str,
1443 *,
1444 + local_tools: t.Optional[t.List[LocalTool]] = None,
1445 + local_toolkits: t.Optional[t.List[LocalToolkit]] = None,
1446 custom_tools: t.Optional[t.List[CustomTool]] = None,
1447 custom_toolkits: t.Optional[t.List[ExperimentalToolkit]] = None,
1448 mcp: t.Literal[False] = False,
@@ -1397,6 +1452,8 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1452 self,
1453 session_id: str,
1454 *,
1455 + local_tools: t.Optional[t.List[LocalTool]] = None,
1456 + local_toolkits: t.Optional[t.List[LocalToolkit]] = None,
1457 custom_tools: t.Optional[t.List[CustomTool]] = None,
1458 custom_toolkits: t.Optional[t.List[ExperimentalToolkit]] = None,
1459 mcp: bool = False,
@@ -1404,17 +1461,19 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1461 """
1462 Use an existing tool router session.
1463
1407 - Provide ``custom_tools`` or ``custom_toolkits`` to bind SDK-local tools
1464 + Provide ``local_tools`` or ``local_toolkits`` to bind local tools
1465 to the session for search and execution.
1466
1467 If the existing session has ``preload.tools = "all"``, every bound
1411 - custom tool is also exposed via ``session.tools()`` and re-injected
1412 - with ``preload=True`` on subsequent search/execute calls. A custom tool
1468 + local tool is also exposed via ``session.tools()`` and re-injected
1469 + with ``preload=True`` on subsequent search/execute calls. A local tool
1470 with explicit ``preload=False`` still opts out.
1471
1472 :param session_id: The session ID to use.
1416 - :param custom_tools: Optional custom tools to bind to the session.
1417 - :param custom_toolkits: Optional custom toolkits to bind to the session.
1473 + :param local_tools: Optional local tools to bind to the session.
1474 + :param local_toolkits: Optional local toolkits to bind to the session.
1475 + :param custom_tools: Deprecated alias for ``local_tools``.
1476 + :param custom_toolkits: Deprecated alias for ``local_toolkits``.
1477 :param mcp: When True, the returned session surfaces its hosted MCP
1478 endpoint in the type (returns ToolRouterSessionWithMcp).
1479 The session credential is exported in ``session.mcp.headers``
@@ -1438,11 +1497,11 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1497 # Use an existing session
1498 session = composio.use('session_123')
1499
1441 - # Use an existing session with custom tools
1500 + # Use an existing session with local tools
1501 session = composio.use(
1502 'session_123',
1444 - custom_tools=[my_tool],
1445 - custom_toolkits=[my_toolkit],
1503 + local_tools=[my_tool],
1504 + local_toolkits=[my_toolkit],
1505 )
1506 ```
1507 """
@@ -1452,6 +1511,12 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1511 "Please initialize ToolRouter with a provider."
1512 )
1513
1514 + custom_tools = _resolve_local_option(
1515 + "local_tools", local_tools, "custom_tools", custom_tools
1516 + )
1517 + custom_toolkits = _resolve_local_option(
1518 + "local_toolkits", local_toolkits, "custom_toolkits", custom_toolkits
1519 + )
1520 has_customs = bool(custom_tools or custom_toolkits)
1521 attach_inline_custom_tools_payload = _prepare_inline_custom_tools(
1522 custom_tools=custom_tools,
python/composio/core/models/tool_router_session.py
+40 -7
@@ -2,13 +2,14 @@
2 ToolRouterSession class for managing a single tool router session.
3
4 Provides methods for tools, authorize, toolkits, search, execute, and files.
5 -When custom tools are bound to the session, execution is routed: local tools
5 +When local tools are bound to the session, execution is routed: local tools
6 run in-process, remote tools are sent to the backend.
7 """
8
9 from __future__ import annotations
10
11 import typing as t
12 +import warnings
13 from concurrent.futures import ThreadPoolExecutor
14 from dataclasses import dataclass
15
@@ -52,6 +53,8 @@ from composio.core.models.custom_tool_types import (
53 InlineCustomToolsWirePayload,
54 RegisteredCustomTool,
55 RegisteredCustomToolkit,
56 + RegisteredLocalTool,
57 + RegisteredLocalToolkit,
58 ToolRouterSessionProxyExecuteResponse,
59 )
60 from composio.core.models.experimental import ACL_ONLY_FOR_SHARED_ERROR_FRAGMENT
@@ -308,6 +311,14 @@ class ToolRouterUpdateExperimentalConfig(te.TypedDict, total=False):
311 session's MCP client can't ask the user: ``"deny"`` or ``"allow"``."""
312
313
314 +_CUSTOM_TOOLS_DEPRECATION = (
315 + "`session.custom_tools()` is deprecated; use `session.local_tools()`"
316 +)
317 +_CUSTOM_TOOLKITS_DEPRECATION = (
318 + "`session.custom_toolkits()` is deprecated; use `session.local_toolkits()`"
319 +)
320 +
321 +
322 class ToolRouterSession(t.Generic[TTool, TToolCollection]):
323 """
324 A Composio session — the object returned by ``composio.create(...)`` /
@@ -1130,15 +1141,15 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1141 slug,
1142 )
1143
1133 - def custom_tools(
1144 + def local_tools(
1145 self, *, toolkit: t.Optional[str] = None
1135 - ) -> t.List[RegisteredCustomTool]:
1136 - """List all custom tools registered in this session.
1146 + ) -> t.List[RegisteredLocalTool]:
1147 + """List all local tools registered in this session.
1148
1149 Returns tools with their final slugs, schemas, and resolved toolkit.
1150
1151 :param toolkit: Filter by toolkit slug (e.g. 'gmail', 'DEV_TOOLS')
1141 - :returns: Array of registered custom tools
1152 + :returns: Array of registered local tools
1153 """
1154 if not self._custom_tools_map:
1155 return []
@@ -1161,8 +1172,8 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1172 for entry in entries
1173 ]
1174
1164 - def custom_toolkits(self) -> t.List[RegisteredCustomToolkit]:
1165 - """List all custom toolkits registered in this session.
1175 + def local_toolkits(self) -> t.List[RegisteredLocalToolkit]:
1176 + """List all toolkits of local tools registered in this session.
1177
1178 Returns toolkits with their tools showing final slugs.
1179 """
@@ -1207,6 +1218,28 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1218 )
1219 return result
1220
1221 + @te.deprecated(_CUSTOM_TOOLS_DEPRECATION, category=None)
1222 + def custom_tools(
1223 + self, *, toolkit: t.Optional[str] = None
1224 + ) -> t.List[RegisteredCustomTool]:
1225 + """Deprecated alias for :meth:`local_tools`."""
1226 + warnings.warn(
1227 + _CUSTOM_TOOLS_DEPRECATION,
1228 + exceptions.ComposioDeprecationWarning,
1229 + stacklevel=2,
1230 + )
1231 + return self.local_tools(toolkit=toolkit)
1232 +
1233 + @te.deprecated(_CUSTOM_TOOLKITS_DEPRECATION, category=None)
1234 + def custom_toolkits(self) -> t.List[RegisteredCustomToolkit]:
1235 + """Deprecated alias for :meth:`local_toolkits`."""
1236 + warnings.warn(
1237 + _CUSTOM_TOOLKITS_DEPRECATION,
1238 + exceptions.ComposioDeprecationWarning,
1239 + stacklevel=2,
1240 + )
1241 + return self.local_toolkits()
1242 +
1243 def proxy_execute(
1244 self,
1245 *,
python/examples/custom_tools_agent_test.py
+2 -2
@@ -137,8 +137,8 @@ async def run_test(prompt, test_name):
137 toolkits=["gmail", "weathermap"],
138 manage_connections=True,
139 experimental={
140 - "custom_tools": [get_user, greet, create_draft],
141 - "custom_toolkits": [role_manager],
140 + "local_tools": [get_user, greet, create_draft],
141 + "local_toolkits": [role_manager],
142 },
143 )
144 tools = session.tools()
python/examples/tool_router/direct_tools_preset.py
+1 -1
@@ -66,7 +66,7 @@ session = composio.create(
66 toolkits=["hackernews"],
67 tools={"hackernews": {"enable": ["HACKERNEWS_GET_USER"]}},
68 experimental={
69 - "custom_toolkits": [hn_research],
69 + "local_toolkits": [hn_research],
70 },
71 )
72
python/examples/tool_router/preload.py
+5 -5
@@ -3,8 +3,8 @@ Tool Router preload with OpenAI Agents.
3
4 Shows direct tool exposure for:
5 1. Composio tools via preload["tools"].
6 -2. SDK custom tools via preload=True on the custom tool or toolkit.
7 -3. A nested custom tool override with preload=False inside a preloaded toolkit.
6 +2. SDK local tools via preload=True on the local tool or toolkit.
7 +3. A nested local tool override with preload=False inside a preloaded toolkit.
8
9 Usage:
10 COMPOSIO_API_KEY=... OPENAI_API_KEY=... python examples/tool_router/preload.py
@@ -80,7 +80,7 @@ def lookup_internal_user(input: UserLookupInput, ctx):
80 slug="SEARCH_INTERNAL_USERS",
81 name="Search internal users",
82 description=(
83 - "Search demo internal users by team. This custom tool is search-only "
83 + "Search demo internal users by team. This local tool is search-only "
84 "because preload is not enabled."
85 ),
86 )
@@ -137,8 +137,8 @@ session = composio.create(
137 preload={"tools": ["HACKERNEWS_GET_USER"]},
138 manage_connections=False,
139 experimental={
140 - "custom_tools": [lookup_internal_user, search_internal_users],
141 - "custom_toolkits": [internal_admin],
140 + "local_tools": [lookup_internal_user, search_internal_users],
141 + "local_toolkits": [internal_admin],
142 },
143 )
144
python/tests/test_custom_tools.py
+69 -8
@@ -8,11 +8,12 @@ Covers:
8 - Custom tool execution (validation, defaults, errors)
9 - Routing map building and lookup
10 - SessionContextImpl sibling routing
11 -- ToolRouterSession integration (execute routing, custom_tools(), custom_toolkits())
11 +- ToolRouterSession integration (execute routing, local_tools(), local_toolkits())
12 - Multi-execute routing (all-local, all-remote, mixed, parallel)
13 """
14
15 import sys
16 +import warnings
17 from dataclasses import replace
18 from unittest.mock import MagicMock
19
@@ -40,13 +41,18 @@ from composio.core.models.custom_tool_execution import (
41 execute_custom_tool,
42 find_custom_tool,
43 )
44 +from composio.core.models.custom_tool_types import (
45 + CustomTool,
46 + RegisteredCustomTool,
47 + RegisteredCustomToolkit,
48 +)
49 from composio.core.models.experimental import ExperimentalAPI
50 from composio.core.models.session_context import SessionContextImpl
51 from composio.core.models.tool_router_session import (
52 ToolRouterSession,
53 ToolRouterSessionExecuteResponse,
54 )
49 -from composio.exceptions import ValidationError
55 +from composio.exceptions import ComposioDeprecationWarning, ValidationError
56 from tests.conftest import mock_http_client
57
58 # ────────────────────────────────────────────────────────────────
@@ -1280,15 +1286,15 @@ class TestToolRouterSessionCustomTools:
1286
1287 def test_custom_tools_list(self, mock_session_deps):
1288 s = _session(mock_session_deps)
1283 - assert len(s.custom_tools()) == 3
1289 + assert len(s.local_tools()) == 3
1290
1291 def test_custom_tools_filter(self, mock_session_deps):
1292 s = _session(mock_session_deps)
1287 - assert len(s.custom_tools(toolkit="gmail")) == 1
1293 + assert len(s.local_tools(toolkit="gmail")) == 1
1294
1295 def test_custom_toolkits_list(self, mock_session_deps):
1296 s = _session(mock_session_deps)
1291 - tks = s.custom_toolkits()
1297 + tks = s.local_toolkits()
1298 assert len(tks) == 1
1299 assert tks[0].slug == "ROLE_MANAGER"
1300
@@ -1312,7 +1318,7 @@ class TestToolRouterSessionCustomTools:
1318 user_id="u",
1319 )
1320
1315 - toolkits = s.custom_toolkits()
1321 + toolkits = s.local_toolkits()
1322
1323 assert [tk.tools[0].slug for tk in toolkits] == [
1324 "LOCAL_ALPHA_GREP",
@@ -1351,7 +1357,7 @@ class TestToolRouterSessionCustomTools:
1357 user_id="u",
1358 )
1359
1354 - assert [tk.tools[0].slug for tk in s.custom_toolkits()] == [
1360 + assert [tk.tools[0].slug for tk in s.local_toolkits()] == [
1361 "LOCAL_ALPHA_GREP",
1362 "GREP",
1363 ]
@@ -1395,7 +1401,62 @@ class TestToolRouterSessionCustomTools:
1401 mcp=MagicMock(),
1402 experimental=MagicMock(),
1403 )
1398 - assert s.custom_tools() == []
1404 + assert s.local_tools() == []
1405 +
1406 + def test_deprecated_custom_tools_matches_local_tools(self, mock_session_deps):
1407 + s = _session(mock_session_deps)
1408 +
1409 + with pytest.warns(
1410 + ComposioDeprecationWarning,
1411 + match=r"^`session\.custom_tools\(\)` is deprecated; use `session\.local_tools\(\)`$",
1412 + ) as record:
1413 + deprecated = s.custom_tools(toolkit="gmail")
1414 +
1415 + assert record[0].filename == __file__
1416 + assert deprecated == s.local_tools(toolkit="gmail")
1417 + assert len(deprecated) == 1
1418 +
1419 + def test_deprecated_custom_toolkits_matches_local_toolkits(self, mock_session_deps):
1420 + s = _session(mock_session_deps)
1421 +
1422 + with pytest.warns(
1423 + ComposioDeprecationWarning,
1424 + match=r"^`session\.custom_toolkits\(\)` is deprecated; use `session\.local_toolkits\(\)`$",
1425 + ) as record:
1426 + deprecated = s.custom_toolkits()
1427 +
1428 + assert record[0].filename == __file__
1429 + assert deprecated == s.local_toolkits()
1430 + assert [tk.slug for tk in deprecated] == ["ROLE_MANAGER"]
1431 +
1432 +
1433 +class TestLocalToolTypeNames:
1434 + def test_new_names_import_without_warning(self):
1435 + with warnings.catch_warnings():
1436 + warnings.simplefilter("error")
1437 + from composio import LocalTool, LocalToolkit
1438 + from composio.core.models import (
1439 + RegisteredLocalTool,
1440 + RegisteredLocalToolkit,
1441 + )
1442 +
1443 + assert LocalTool is CustomTool
1444 + assert LocalToolkit is ExperimentalToolkit
1445 + assert RegisteredLocalTool is RegisteredCustomTool
1446 + assert RegisteredLocalToolkit is RegisteredCustomToolkit
1447 +
1448 + def test_deprecated_type_names_stay_plain_aliases(self):
1449 + # Type names don't warn, so `from composio import *` stays quiet;
1450 + # the deprecated options and session methods carry the warning.
1451 + with warnings.catch_warnings():
1452 + warnings.simplefilter("error")
1453 + import composio
1454 + from composio.core import models
1455 +
1456 + assert composio.CustomTool is composio.LocalTool
1457 + assert models.CustomTool is models.LocalTool
1458 + assert models.RegisteredCustomTool is models.RegisteredLocalTool
1459 + assert models.RegisteredCustomToolkit is models.RegisteredLocalToolkit
1460
1461
1462 # ────────────────────────────────────────────────────────────────
python/tests/test_tool_router.py
+195 -8
@@ -54,6 +54,7 @@ from composio.core.models.tool_router_session import (
54 ToolRouterSessionWithMcp,
55 )
56 from composio.exceptions import (
57 + ComposioDeprecationWarning,
58 InvalidParams,
59 MCPDestinationError,
60 SessionConfigConflictError,
@@ -892,7 +893,7 @@ class TestToolRouter:
893 tool_router.create(
894 user_id="user_123",
895 preload={"tools": ["GREP"]},
895 - experimental={"custom_tools": [grep]},
896 + experimental={"local_tools": [grep]},
897 )
898
899 mock_client.tool_router.session.create.assert_not_called()
@@ -984,7 +985,7 @@ class TestToolRouter:
985 session_preset=SESSION_PRESET_DIRECT_TOOLS,
986 toolkits=["github"],
987 preload={"tools": ["GITHUB_CREATE_ISSUE"]},
987 - experimental={"custom_tools": [grep]},
988 + experimental={"local_tools": [grep]},
989 )
990
991 kwargs = mock_client.tool_router.session.create.call_args.kwargs
@@ -1278,7 +1279,7 @@ class TestToolRouter:
1279 mock_custom_tool.extends_toolkit = None
1280 mock_response.experimental.custom_tools = [mock_custom_tool]
1281
1281 - session = tool_router.use(session_id="session_123", custom_tools=[grep])
1282 + session = tool_router.use(session_id="session_123", local_tools=[grep])
1283
1284 mock_client.tool_router.session.attach.assert_called_once()
1285 kwargs = mock_client.tool_router.session.attach.call_args.kwargs
@@ -1286,8 +1287,8 @@ class TestToolRouter:
1287 assert "custom_toolkits" not in kwargs["experimental"]
1288 mock_client.tool_router.session.retrieve.assert_not_called()
1289 mock_client.post.assert_not_called()
1289 - assert session.custom_tools()[0].slug == "SERVER_GREP"
1290 - assert session.custom_tools()[0].name == "Grep"
1290 + assert session.local_tools()[0].slug == "SERVER_GREP"
1291 + assert session.local_tools()[0].name == "Grep"
1292
1293 @patch("composio.core.models.tools.Tools")
1294 def test_use_session_attaches_preloaded_custom_tools(
@@ -1330,7 +1331,7 @@ class TestToolRouter:
1331 mock_tools_class.return_value = mock_tools_instance
1332 mock_provider.wrap_tools.return_value = "mocked-custom-tools"
1333
1333 - session = tool_router.use(session_id="session_123", custom_tools=[grep])
1334 + session = tool_router.use(session_id="session_123", local_tools=[grep])
1335 session.tools()
1336
1337 mock_client.tool_router.session.attach.assert_called_once()
@@ -1386,7 +1387,7 @@ class TestToolRouter:
1387 mock_tools_class.return_value = mock_tools_instance
1388 mock_provider.wrap_tools.return_value = "mocked-custom-tools"
1389
1389 - session = tool_router.use(session_id="session_123", custom_tools=[grep])
1390 + session = tool_router.use(session_id="session_123", local_tools=[grep])
1391 session.tools()
1392 session.search(query="search local text")
1393
@@ -1734,7 +1735,7 @@ class TestToolRouter:
1735
1736 session = tool_router.create(
1737 user_id="user_123",
1737 - experimental={"custom_tools": [grep]},
1738 + experimental={"local_tools": [grep]},
1739 )
1740 result = session.tools()
1741
@@ -1903,6 +1904,192 @@ class TestToolRouter:
1904 mock_client.post.assert_not_called()
1905
1906
1907 +def _local_grep_tool():
1908 + @experimental_api.tool(slug="GREP", name="Grep", description="Search local text")
1909 + def grep(input: GrepInput, ctx):
1910 + return {"matches": []}
1911 +
1912 + return grep
1913 +
1914 +
1915 +def _local_role_toolkit():
1916 + toolkit = experimental_api.Toolkit(
1917 + slug="ROLES", name="Roles", description="Manage roles"
1918 + )
1919 +
1920 + @toolkit.tool(slug="SET_ROLE")
1921 + def set_role(input: GrepInput, ctx):
1922 + """Set a role."""
1923 + return {"ok": True}
1924 +
1925 + return toolkit
1926 +
1927 +
1928 +def _mock_local_tools_response(response):
1929 + response.experimental = MagicMock()
1930 + response.experimental.assistive_prompt = None
1931 + server_tool = MagicMock()
1932 + server_tool.slug = "LOCAL_GREP"
1933 + server_tool.original_slug = "GREP"
1934 + server_tool.extends_toolkit = None
1935 + response.experimental.custom_tools = [server_tool]
1936 + server_toolkit = MagicMock()
1937 + server_toolkit.slug = "ROLES"
1938 + server_toolkit.tools = [
1939 + MagicMock(slug="LOCAL_ROLES_SET_ROLE", original_slug="SET_ROLE")
1940 + ]
1941 + response.experimental.custom_toolkits = [server_toolkit]
1942 +
1943 +
1944 +class TestLocalToolsOptions:
1945 + """`local_tools`/`local_toolkits` and their deprecated `custom_*` aliases."""
1946 +
1947 + def test_create_with_local_tools_sends_custom_wire_fields(
1948 + self, tool_router, mock_client
1949 + ):
1950 + _mock_local_tools_response(mock_client.tool_router.session.create.return_value)
1951 + tool = _local_grep_tool()
1952 + toolkit = _local_role_toolkit()
1953 +
1954 + with warnings.catch_warnings():
1955 + warnings.simplefilter("error")
1956 + session = tool_router.create(
1957 + user_id="user_123",
1958 + experimental={
1959 + "local_tools": [tool],
1960 + "local_toolkits": [toolkit],
1961 + },
1962 + )
1963 +
1964 + experimental = mock_client.tool_router.session.create.call_args.kwargs[
1965 + "experimental"
1966 + ]
1967 + assert set(experimental) == {"custom_tools", "custom_toolkits"}
1968 + assert experimental["custom_tools"][0]["slug"] == "GREP"
1969 + assert experimental["custom_toolkits"][0]["slug"] == "ROLES"
1970 + assert [tool.slug for tool in session.local_tools()] == [
1971 + "LOCAL_GREP",
1972 + "LOCAL_ROLES_SET_ROLE",
1973 + ]
1974 + assert [tk.slug for tk in session.local_toolkits()] == ["ROLES"]
1975 +
1976 + def test_create_with_deprecated_custom_names_warns(self, tool_router, mock_client):
1977 + _mock_local_tools_response(mock_client.tool_router.session.create.return_value)
1978 + tool = _local_grep_tool()
1979 + toolkit = _local_role_toolkit()
1980 +
1981 + with pytest.warns(ComposioDeprecationWarning) as record:
1982 + session = tool_router.create(
1983 + user_id="user_123",
1984 + experimental={
1985 + "custom_tools": [tool],
1986 + "custom_toolkits": [toolkit],
1987 + },
1988 + )
1989 +
1990 + assert [str(w.message) for w in record] == [
1991 + "`custom_tools` is deprecated; use `local_tools`",
1992 + "`custom_toolkits` is deprecated; use `local_toolkits`",
1993 + ]
1994 + assert record[0].filename == __file__
1995 + experimental = mock_client.tool_router.session.create.call_args.kwargs[
1996 + "experimental"
1997 + ]
1998 + assert experimental["custom_tools"][0]["slug"] == "GREP"
1999 + assert experimental["custom_toolkits"][0]["slug"] == "ROLES"
2000 + assert session.local_tools()[0].slug == "LOCAL_GREP"
2001 +
2002 + @pytest.mark.parametrize(
2003 + ("new_name", "old_name", "value"),
2004 + [
2005 + ("local_tools", "custom_tools", _local_grep_tool),
2006 + ("local_toolkits", "custom_toolkits", _local_role_toolkit),
2007 + ],
2008 + )
2009 + def test_create_rejects_new_and_deprecated_names_together(
2010 + self, tool_router, mock_client, new_name, old_name, value
2011 + ):
2012 + with pytest.raises(
2013 + InvalidParams,
2014 + match=f"^Pass either `{new_name}` or `{old_name}`, not both",
2015 + ):
2016 + tool_router.create(
2017 + user_id="user_123",
2018 + experimental=t.cast(
2019 + ToolRouterExperimentalConfig,
2020 + {new_name: [value()], old_name: [value()]},
2021 + ),
2022 + )
2023 +
2024 + mock_client.tool_router.session.create.assert_not_called()
2025 +
2026 + def test_use_with_local_tools_sends_custom_wire_fields(
2027 + self, tool_router, mock_client
2028 + ):
2029 + _mock_local_tools_response(mock_client.tool_router.session.attach.return_value)
2030 + tool = _local_grep_tool()
2031 + toolkit = _local_role_toolkit()
2032 +
2033 + with warnings.catch_warnings():
2034 + warnings.simplefilter("error")
2035 + session = tool_router.use(
2036 + "session_123",
2037 + local_tools=[tool],
2038 + local_toolkits=[toolkit],
2039 + )
2040 +
2041 + experimental = mock_client.tool_router.session.attach.call_args.kwargs[
2042 + "experimental"
2043 + ]
2044 + assert set(experimental) == {"custom_tools", "custom_toolkits"}
2045 + assert [tool.slug for tool in session.local_tools()] == [
2046 + "LOCAL_GREP",
2047 + "LOCAL_ROLES_SET_ROLE",
2048 + ]
2049 +
2050 + def test_use_with_deprecated_custom_names_warns(self, tool_router, mock_client):
2051 + _mock_local_tools_response(mock_client.tool_router.session.attach.return_value)
2052 + tool = _local_grep_tool()
2053 + toolkit = _local_role_toolkit()
2054 +
2055 + with pytest.warns(ComposioDeprecationWarning) as record:
2056 + session = tool_router.use(
2057 + "session_123",
2058 + custom_tools=[tool],
2059 + custom_toolkits=[toolkit],
2060 + )
2061 +
2062 + assert [str(w.message) for w in record] == [
2063 + "`custom_tools` is deprecated; use `local_tools`",
2064 + "`custom_toolkits` is deprecated; use `local_toolkits`",
2065 + ]
2066 + assert record[0].filename == __file__
2067 + experimental = mock_client.tool_router.session.attach.call_args.kwargs[
2068 + "experimental"
2069 + ]
2070 + assert experimental["custom_tools"][0]["slug"] == "GREP"
2071 + assert session.local_toolkits()[0].slug == "ROLES"
2072 +
2073 + @pytest.mark.parametrize(
2074 + ("new_name", "old_name", "value"),
2075 + [
2076 + ("local_tools", "custom_tools", _local_grep_tool),
2077 + ("local_toolkits", "custom_toolkits", _local_role_toolkit),
2078 + ],
2079 + )
2080 + def test_use_rejects_new_and_deprecated_names_together(
2081 + self, tool_router, mock_client, new_name, old_name, value
2082 + ):
2083 + with pytest.raises(
2084 + InvalidParams,
2085 + match=f"^Pass either `{new_name}` or `{old_name}`, not both",
2086 + ):
2087 + tool_router.use("session_123", **{new_name: [value()], old_name: [value()]})
2088 +
2089 + mock_client.tool_router.session.attach.assert_not_called()
2090 + mock_client.tool_router.session.retrieve.assert_not_called()
2091 +
2092 +
2093 class TestToolRouterTypes:
2094 """Test type definitions for ToolRouter."""
2095