Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 22:15 UTC
Add tool router preload support to Python SDK
Dhawal Upadhyay committed
Apr 29, 2026 at 03:06 UTC
f846993a4d2391f369a0acb038c8db65f481d5db
4 files changed
+124
-41
python/composio/core/models/tool_router.py
+31
-1
@@ -27,7 +27,10 @@ from composio.core.models.custom_tool_types import (
27
CustomTool,
28
CustomToolsMap,
29
)
30
-from composio.core.models.tool_router_session import ToolRouterSession
30
+from composio.core.models.tool_router_session import (
31
+ ToolRouterSession,
32
+ ToolRouterSessionPreloadConfig,
33
+)
34
from composio.core.models.tool_router_session_files import ToolRouterSessionFilesMount
35
from composio.core.provider import TTool, TToolCollection
36
from composio.core.provider.base import BaseProvider
@@ -206,6 +209,17 @@ class ToolRouterMultiAccountConfig(te.TypedDict, total=False):
209
require_explicit_selection: bool
210
211
212
+class ToolRouterPreloadConfig(te.TypedDict, total=False):
213
+ """Configuration for tools preloaded into a tool router session.
214
+
215
+ Attributes:
216
+ tools: Tool slugs to expose directly in ``session.tools()`` and MCP
217
+ tool lists without first calling search.
218
+ """
219
+
220
+ tools: t.List[str]
221
+
222
+
223
class ToolRouterAssistivePromptConfig(te.TypedDict, total=False):
224
"""Configuration for assistive prompt generation.
225
@@ -482,6 +496,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
496
connected_accounts: t.Optional[t.Dict[str, str]] = None,
497
workbench: t.Optional[ToolRouterWorkbenchConfig] = None,
498
multi_account: t.Optional[ToolRouterMultiAccountConfig] = None,
499
+ preload: t.Optional[ToolRouterPreloadConfig] = None,
500
experimental: t.Optional[ToolRouterExperimentalConfig] = None,
501
) -> ToolRouterSession[TTool, TToolCollection]:
502
"""
@@ -563,6 +578,10 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
578
- 'require_explicit_selection' (bool): When True, require explicit
579
account selection when multiple accounts are connected.
580
Example: {'enable': True, 'max_accounts_per_toolkit': 3}
581
+ :param preload: Optional preload configuration. Dict with:
582
+ - 'tools' (List[str]): Tool slugs to expose directly in
583
+ session.tools() and MCP tool lists.
584
+ Example: {'tools': ['GMAIL_FETCH_EMAILS']}
585
:param experimental: Optional experimental configuration (ToolRouterExperimentalConfig).
586
Note: These features are experimental and may change.
587
Dict with:
@@ -773,6 +792,9 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
792
if multi_account is not None:
793
create_params["multi_account"] = multi_account
794
795
+ if preload is not None:
796
+ create_params["preload"] = preload
797
+
798
# Build experimental config
799
# Map SDK's experimental.assistive_prompt.user_timezone to API's
800
# experimental.assistive_prompt_config.user_timezone
@@ -851,6 +873,9 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
873
experimental=experimental_response,
874
custom_tools_map=custom_tools_map,
875
user_id=user_id,
876
+ preload=ToolRouterSessionPreloadConfig(
877
+ tools=list(session.config.preload.tools)
878
+ ),
879
)
880
881
def use(self, session_id: str) -> ToolRouterSession[TTool, TToolCollection]:
@@ -905,6 +930,9 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
930
url=session.mcp.url,
931
),
932
experimental=experimental_response,
933
+ preload=ToolRouterSessionPreloadConfig(
934
+ tools=list(session.config.preload.tools)
935
+ ),
936
)
937
938
@@ -925,8 +953,10 @@ __all__ = [
953
"ToolRouterWorkbenchConfig",
954
"SandboxSize",
955
"ToolRouterMultiAccountConfig",
956
+ "ToolRouterPreloadConfig",
957
"ToolRouterExperimentalConfig",
958
"ToolRouterAssistivePromptConfig",
959
+ "ToolRouterSessionPreloadConfig",
960
"ToolkitConnectionState",
961
"ToolkitConnectionsDetails",
962
"ToolRouterMCPServerConfig",
python/composio/core/models/tool_router_session.py
+17
-1
@@ -10,6 +10,7 @@ from __future__ import annotations
10
11
import typing as t
12
from concurrent.futures import ThreadPoolExecutor
13
+from dataclasses import dataclass
14
15
from composio_client import omit
16
from composio_client.types.tool_router.session_execute_response import (
@@ -50,6 +51,13 @@ COMPOSIO_MULTI_EXECUTE_TOOL = "COMPOSIO_MULTI_EXECUTE_TOOL"
51
MAX_PARALLEL_WORKERS = 5
52
53
54
+@dataclass
55
+class ToolRouterSessionPreloadConfig:
56
+ """Preloaded tools configured for a tool router session."""
57
+
58
+ tools: t.List[str]
59
+
60
+
61
class ToolRouterSession(t.Generic[TTool, TToolCollection]):
62
"""
63
Tool router session containing session information and methods.
@@ -85,6 +93,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
93
experimental: "ToolRouterSessionExperimental",
94
custom_tools_map: t.Optional[CustomToolsMap] = None,
95
user_id: t.Optional[str] = None,
96
+ preload: t.Optional[ToolRouterSessionPreloadConfig] = None,
97
) -> None:
98
self._client = client
99
self._provider = provider
@@ -95,6 +104,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
104
self.session_id = session_id
105
self.mcp = mcp
106
self.experimental = experimental
107
+ self.preload = preload or ToolRouterSessionPreloadConfig(tools=[])
108
self._custom_tools_map = custom_tools_map
109
self._user_id = user_id
110
@@ -119,7 +129,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
129
tools_model: t.Any,
130
modifiers: t.Optional["Modifiers"] = None,
131
) -> t.Callable[..., t.Any]:
122
- """Backend execute_meta wrapper with this session's file-upload settings."""
132
+ """Backend execute wrapper with this session's file-upload settings."""
133
return tools_model._wrap_execute_tool_for_tool_router(
134
session_id=self.session_id,
135
modifiers=modifiers,
@@ -533,6 +543,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
543
tool_slug: str,
544
*,
545
arguments: t.Optional[t.Dict[str, t.Any]] = None,
546
+ account: t.Optional[str] = None,
547
) -> SessionExecuteResponse:
548
"""
549
Execute a tool within the session.
@@ -541,6 +552,10 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
552
full slug (e.g. "LOCAL_GREP"). Custom tools are executed in-process;
553
remote tools are sent to the Composio backend.
554
555
+ :param account: Account ID or alias for direct app tool execution in
556
+ multi-account sessions. Helper/meta tools either ignore this
557
+ top-level field or define their own account-selection fields.
558
+
559
Both paths return a ``SessionExecuteResponse`` with ``data``,
560
``error``, and ``log_id`` attributes.
561
"""
@@ -563,6 +578,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
578
session_id=self.session_id,
579
tool_slug=tool_slug,
580
arguments=arguments if arguments is not None else omit,
581
+ account=account if account is not None else omit,
582
)
583
584
def custom_tools(
python/composio/core/models/tools.py
+19
-17
@@ -238,11 +238,11 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
238
modifiers: t.Optional["Modifiers"] = None,
239
) -> list[Tool]:
240
"""
241
- Fetches the meta tools for a tool router session.
241
+ Fetches the tools exposed by a tool router session.
242
243
- This method fetches the meta tools from the Composio API and transforms them to
244
- the expected format. It provides access to the underlying meta tool data without
245
- provider-specific wrapping.
243
+ This method fetches helper/meta tools and any preloaded app tools from the
244
+ Composio API and transforms them to the expected format. It provides access
245
+ to the underlying tool data without provider-specific wrapping.
246
247
:param session_id: The session ID to get the meta tools for
248
:param modifiers: Optional modifiers to apply to the tool schemas
@@ -274,7 +274,7 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
274
)
275
```
276
"""
277
- # Fetch meta tools from the API
277
+ # Fetch session tools from the API
278
tools_response = self._client.tool_router.session.tools(session_id=session_id)
279
# Cast to Tool type - session.tools returns compatible Item type from different response schema
280
tools_list: t.List[Tool] = [t.cast(Tool, item) for item in tools_response.items]
@@ -297,6 +297,10 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
297
for tool in tools_list
298
]
299
300
+ self._tool_schemas.update(
301
+ {tool.slug: tool.model_copy(deep=True) for tool in tools_list}
302
+ )
303
+
304
return tools_list
305
306
def _get(
@@ -440,10 +444,10 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
444
modifiers: t.Optional[Modifiers] = None,
445
) -> AgenticProviderExecuteFn:
446
"""
443
- Create an execute function for tool router that uses the session's execute_meta endpoint.
447
+ Create an execute function for tool router session tools.
448
449
This method creates a function that executes tools within a tool router session context.
446
- It uses the session's execute_meta endpoint which handles authentication and connection
450
+ It uses the session's execute endpoint which handles authentication and connection
451
management automatically.
452
453
:param session_id: The session ID
@@ -456,7 +460,7 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
460
Execute a tool in the tool router session.
461
462
This function is used by agentic providers to execute tools within
459
- a tool router session context. It uses the session's execute_meta
463
+ a tool router session context. It uses the session's execute
464
endpoint which handles authentication and connection management
465
automatically.
466
@@ -482,7 +486,7 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
486
self._tool_schemas[slug] = tool
487
488
if self._auto_upload_download_files:
485
- meta_tk = tool.toolkit.slug if tool.toolkit else "unknown"
489
+ meta_tk = tool.toolkit.slug if tool.toolkit else "composio"
490
bfu = merge_before_file_upload(
491
modifiers,
492
tool=slug,
@@ -494,8 +498,9 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
498
before_file_upload=bfu,
499
)
500
501
+ toolkit_slug = tool.toolkit.slug if tool.toolkit else "composio"
502
+
503
# Apply before_execute modifiers
498
- # Meta tools are always from the 'composio' toolkit
504
processed_arguments = arguments
505
if modifiers is not None:
506
params: ToolExecuteParams = {
@@ -504,7 +509,7 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
509
type_before: t.Literal["before_execute"] = "before_execute"
510
modified_params = apply_modifier_by_type(
511
modifiers=modifiers,
507
- toolkit="composio",
512
+ toolkit=toolkit_slug,
513
tool=slug,
514
type=type_before,
515
request=params,
@@ -514,12 +519,9 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
519
# Serialize any Pydantic model instances before sending to the API
520
processed_arguments = _serialize_arguments(processed_arguments)
521
517
- # Execute the tool via the session's execute_meta endpoint
518
- # Note: execute_meta accepts regular tool slugs at runtime, not just meta tool slugs
519
- # The type signature expects Literal meta tool slugs, but runtime accepts any str
520
- response = self._client.tool_router.session.execute_meta(
522
+ response = self._client.tool_router.session.execute(
523
session_id=session_id,
522
- slug=slug, # type: ignore[arg-type]
524
+ tool_slug=slug,
525
arguments=processed_arguments,
526
)
527
@@ -535,7 +537,7 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
537
type_after: t.Literal["after_execute"] = "after_execute"
538
result = apply_modifier_by_type(
539
modifiers=modifiers,
538
- toolkit="composio",
540
+ toolkit=toolkit_slug,
541
tool=slug,
542
type=type_after,
543
response=result,
python/tests/test_tool_router.py
+57
-22
@@ -37,6 +37,8 @@ def mock_client():
37
]
38
mock_session_response.config = MagicMock()
39
mock_session_response.config.user_id = "user_123"
40
+ mock_session_response.config.preload = MagicMock()
41
+ mock_session_response.config.preload.tools = []
42
mock_session_response.experimental = None # Default to None
43
44
client.tool_router.session.create.return_value = mock_session_response
@@ -587,6 +589,21 @@ class TestToolRouter:
589
kwargs = mock_client.tool_router.session.create.call_args.kwargs
590
assert "multi_account" not in kwargs
591
592
+ def test_create_session_with_preload(self, tool_router, mock_client):
593
+ """preload is forwarded and exposed on the session."""
594
+ mock_client.tool_router.session.create.return_value.config.preload.tools = [
595
+ "GMAIL_FETCH_EMAILS"
596
+ ]
597
+
598
+ session = tool_router.create(
599
+ user_id="user_123",
600
+ preload={"tools": ["GMAIL_FETCH_EMAILS"]},
601
+ )
602
+
603
+ kwargs = mock_client.tool_router.session.create.call_args.kwargs
604
+ assert kwargs["preload"] == {"tools": ["GMAIL_FETCH_EMAILS"]}
605
+ assert session.preload.tools == ["GMAIL_FETCH_EMAILS"]
606
+
607
def test_create_session_complex_config(self, tool_router, mock_client):
608
"""Test creating a session with complex configuration."""
609
session = tool_router.create(
@@ -771,6 +788,10 @@ class TestToolRouter:
788
789
def test_use_session(self, tool_router, mock_client):
790
"""Test retrieving an existing session."""
791
+ mock_client.tool_router.session.retrieve.return_value.config.preload.tools = [
792
+ "GMAIL_FETCH_EMAILS"
793
+ ]
794
+
795
session = tool_router.use(session_id="session_123")
796
797
# Verify session properties
@@ -788,6 +809,7 @@ class TestToolRouter:
809
assert callable(session.tools)
810
assert callable(session.authorize)
811
assert callable(session.toolkits)
812
+ assert session.preload.tools == ["GMAIL_FETCH_EMAILS"]
813
814
# Verify retrieve was called
815
mock_client.tool_router.session.retrieve.assert_called_once_with("session_123")
@@ -819,6 +841,28 @@ class TestToolRouter:
841
with pytest.raises(Exception, match="Session not found"):
842
tool_router.use(session_id="invalid_session")
843
844
+ def test_session_execute_with_account(self, tool_router, mock_client):
845
+ """session.execute forwards account for direct app tool execution."""
846
+ mock_execute_response = MagicMock()
847
+ mock_execute_response.data = {"ok": True}
848
+ mock_execute_response.error = None
849
+ mock_execute_response.log_id = "log_123"
850
+ mock_client.tool_router.session.execute.return_value = mock_execute_response
851
+
852
+ session = tool_router.create(user_id="user_123")
853
+ session.execute(
854
+ "GMAIL_FETCH_EMAILS",
855
+ arguments={"max_results": 1},
856
+ account="work",
857
+ )
858
+
859
+ mock_client.tool_router.session.execute.assert_called_once_with(
860
+ session_id="session_123",
861
+ tool_slug="GMAIL_FETCH_EMAILS",
862
+ arguments={"max_results": 1},
863
+ account="work",
864
+ )
865
+
866
def test_authorize_function(self, tool_router, mock_client):
867
"""Test the authorize function returned by session."""
868
session = tool_router.create(user_id="user_123")
@@ -1025,6 +1069,8 @@ class TestToolRouter:
1069
1070
# Verify provider's wrap_tools was called
1071
mock_provider.wrap_tools.assert_called_once()
1072
+ wrapped_tools = mock_provider.wrap_tools.call_args.kwargs["tools"]
1073
+ assert [tool.slug for tool in wrapped_tools] == ["GMAIL_FETCH_EMAILS"]
1074
assert result == "mocked-wrapped-tools"
1075
1076
@patch("composio.core.models.tools.Tools")
@@ -1294,17 +1340,12 @@ class TestToolRouterExecution:
1340
call_args = mock_tools_instance._wrap_execute_tool_for_tool_router.call_args
1341
assert call_args.kwargs["session_id"] == "session_123"
1342
1297
- def test_execute_meta_endpoint_called(
1298
- self, tool_router, mock_client, mock_provider
1299
- ):
1300
- """Test that execute_meta endpoint is called when executing tools."""
1301
- # Setup execute_meta response
1343
+ def test_execute_endpoint_called(self, tool_router, mock_client, mock_provider):
1344
+ """Test that session execute endpoint is called when executing tools."""
1345
mock_execute_response = MagicMock()
1346
mock_execute_response.data = {"result": "success"}
1347
mock_execute_response.error = None
1305
- mock_client.tool_router.session.execute_meta.return_value = (
1306
- mock_execute_response
1307
- )
1348
+ mock_client.tool_router.session.execute.return_value = mock_execute_response
1349
1350
# Create a real Tools instance to test the execute function
1351
from composio.core.models.tools import Tools as RealTools
@@ -1321,10 +1362,10 @@ class TestToolRouterExecution:
1362
# Execute the tool
1363
result = execute_fn("GMAIL_SEND_EMAIL", {"to": "test@example.com"})
1364
1324
- # Verify execute_meta was called with correct parameters
1325
- mock_client.tool_router.session.execute_meta.assert_called_once_with(
1365
+ # Verify execute was called with correct parameters
1366
+ mock_client.tool_router.session.execute.assert_called_once_with(
1367
session_id="session_123",
1327
- slug="GMAIL_SEND_EMAIL",
1368
+ tool_slug="GMAIL_SEND_EMAIL",
1369
arguments={"to": "test@example.com"},
1370
)
1371
@@ -1337,13 +1378,10 @@ class TestToolRouterExecution:
1378
self, tool_router, mock_client, mock_provider
1379
):
1380
"""Test that modifiers are applied before and after tool execution."""
1340
- # Setup execute_meta response
1381
mock_execute_response = MagicMock()
1382
mock_execute_response.data = {"result": "success"}
1383
mock_execute_response.error = None
1344
- mock_client.tool_router.session.execute_meta.return_value = (
1345
- mock_execute_response
1346
- )
1384
+ mock_client.tool_router.session.execute.return_value = mock_execute_response
1385
1386
# Create modifier functions
1387
def before_modifier(tool, toolkit, params):
@@ -1382,9 +1420,9 @@ class TestToolRouterExecution:
1420
# Execute the tool
1421
result = execute_fn("GMAIL_SEND_EMAIL", {"to": "test@example.com"})
1422
1385
- # Verify execute_meta was called with modified arguments
1386
- mock_client.tool_router.session.execute_meta.assert_called_once()
1387
- call_args = mock_client.tool_router.session.execute_meta.call_args
1423
+ # Verify execute was called with modified arguments
1424
+ mock_client.tool_router.session.execute.assert_called_once()
1425
+ call_args = mock_client.tool_router.session.execute.call_args
1426
assert call_args.kwargs["arguments"] == {"to": "modified@example.com"}
1427
1428
# Verify result was modified by after_execute
@@ -1392,13 +1430,10 @@ class TestToolRouterExecution:
1430
1431
def test_execute_tool_error_handling(self, tool_router, mock_client, mock_provider):
1432
"""Test that tool execution errors are handled correctly."""
1395
- # Setup execute_meta to return an error
1433
mock_execute_response = MagicMock()
1434
mock_execute_response.data = {}
1435
mock_execute_response.error = "Authentication failed"
1399
- mock_client.tool_router.session.execute_meta.return_value = (
1400
- mock_execute_response
1401
- )
1436
+ mock_client.tool_router.session.execute.return_value = mock_execute_response
1437
1438
# Create a real execute function
1439
from composio.core.models.tools import Tools as RealTools