@devries-cameron20 / composio Mirror · read-only / commits / f846993a4
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, 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