Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
feat(python): add custom tools support to session.use() via v3.1 attach
Mirrors the TS SDK changes: - composio.use(id, custom_tools=..., custom_toolkits=...) POSTs to /api/v3.1/tool_router/session/{id}/attach with inline experimental payload when customs are provided, else falls back to v3 retrieve. - build_custom_tools_map_from_response now accepts both create and retrieve experimental response types. - CustomToolsMap gains a `tools` field to cache the raw standalone CustomTool list for future inline re-injection. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Abir Taheer committed
May 6, 2026 at 20:01 UTC
366c795e4faf507629bf2349f5b0b372bb738ad4
3 files changed
+89
-13
python/composio/core/models/custom_tool.py
+11
-1
@@ -64,6 +64,9 @@ if t.TYPE_CHECKING:
64
from composio_client.types.tool_router.session_create_response import (
65
Experimental as SessionCreateResponseExperimental,
66
)
67
+ from composio_client.types.tool_router.session_retrieve_response import (
68
+ Experimental as SessionRetrieveResponseExperimental,
69
+ )
70
71
72
# ────────────────────────────────────────────────────────────────
@@ -716,13 +719,19 @@ def build_custom_tools_map(
719
by_final_slug=by_final_slug,
720
by_original_slug=by_original_slug,
721
toolkits=list(toolkits) if toolkits else None,
722
+ tools=list(tools) if tools else None,
723
)
724
725
726
def build_custom_tools_map_from_response(
727
tools: t.List[CustomTool],
728
toolkits: t.Optional[t.List[ExperimentalToolkit]],
725
- experimental: t.Optional[SessionCreateResponseExperimental],
729
+ experimental: t.Optional[
730
+ t.Union[
731
+ "SessionCreateResponseExperimental",
732
+ "SessionRetrieveResponseExperimental",
733
+ ]
734
+ ],
735
) -> CustomToolsMap:
736
"""Build a CustomToolsMap using the slug/original_slug mapping from the backend response."""
737
by_final_slug: t.Dict[str, CustomToolsMapEntry] = {}
@@ -776,6 +785,7 @@ def build_custom_tools_map_from_response(
785
by_final_slug=by_final_slug,
786
by_original_slug=by_original_slug,
787
toolkits=list(toolkits) if toolkits else None,
788
+ tools=list(tools) if tools else None,
789
)
790
791
python/composio/core/models/custom_tool_types.py
+1
@@ -153,6 +153,7 @@ class CustomToolsMap:
153
by_final_slug: t.Dict[str, CustomToolsMapEntry] = field(default_factory=dict)
154
by_original_slug: t.Dict[str, CustomToolsMapEntry] = field(default_factory=dict)
155
toolkits: t.Optional[t.List[t.Any]] = None
156
+ tools: t.Optional[t.List["CustomTool"]] = None
157
158
159
# ────────────────────────────────────────────────────────────────
python/composio/core/models/tool_router.py
+77
-12
@@ -31,6 +31,9 @@ from composio.core.models.custom_tool_types import (
31
CustomToolsMap,
32
InlineCustomToolsWirePayload,
33
)
34
+from composio_client.types.tool_router.session_retrieve_response import (
35
+ SessionRetrieveResponse,
36
+)
37
from composio.core.models.tool_router_session import (
38
ToolRouterSession,
39
ToolRouterSessionPreloadConfig,
@@ -981,11 +984,24 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
984
inline_custom_tools_payload=inline_custom_tools_payload,
985
)
986
984
- def use(self, session_id: str) -> ToolRouterSession[TTool, TToolCollection]:
987
+ def use(
988
+ self,
989
+ session_id: str,
990
+ *,
991
+ custom_tools: t.Optional[t.List[CustomTool]] = None,
992
+ custom_toolkits: t.Optional[t.List[ExperimentalToolkit]] = None,
993
+ ) -> ToolRouterSession[TTool, TToolCollection]:
994
"""
986
- Retrieve and use an existing tool router session.
995
+ Retrieve and use an existing tool router session, optionally attaching custom tools.
996
+
997
+ When ``custom_tools`` or ``custom_toolkits`` are provided, the SDK calls the
998
+ v3.1 ``/attach`` endpoint which validates and registers them inline for this
999
+ session without persisting them server-side. Without customs it falls back to
1000
+ the standard v3 retrieve endpoint.
1001
1002
:param session_id: The session ID to retrieve
1003
+ :param custom_tools: Optional custom tools to attach to the session.
1004
+ :param custom_toolkits: Optional custom toolkits to attach to the session.
1005
:return: Tool router session object
1006
1007
Example:
@@ -993,15 +1009,16 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1009
from composio import Composio
1010
1011
composio = Composio()
996
- tool_router = composio.tool_router
1012
998
- # Retrieve an existing session
999
- session = tool_router.use('session_123')
1013
+ # Simple rehydration
1014
+ session = composio.use('session_123')
1015
1001
- # Use the session
1002
- tools = session.tools()
1003
- connection = session.authorize('github')
1004
- toolkit_states = session.toolkits()
1016
+ # Rehydration with custom tools
1017
+ session = composio.use(
1018
+ 'session_123',
1019
+ custom_tools=[my_tool],
1020
+ custom_toolkits=[my_toolkit],
1021
+ )
1022
```
1023
"""
1024
if self._provider is None:
@@ -1010,8 +1027,53 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1027
"Please initialize ToolRouter with a provider."
1028
)
1029
1013
- # Retrieve the session from the API
1014
- session = self._client.tool_router.session.retrieve(session_id)
1030
+ has_customs = bool(custom_tools or custom_toolkits)
1031
+ inline_custom_tools_payload: t.Optional[InlineCustomToolsWirePayload] = None
1032
+
1033
+ if has_customs:
1034
+ experimental_payload: t.Dict[str, t.Any] = {}
1035
+ if custom_tools:
1036
+ experimental_payload["custom_tools"] = serialize_custom_tools(
1037
+ custom_tools
1038
+ )
1039
+ if custom_toolkits:
1040
+ experimental_payload["custom_toolkits"] = serialize_custom_toolkits(
1041
+ custom_toolkits
1042
+ )
1043
+
1044
+ inline_custom_tools_payload = {}
1045
+ if "custom_tools" in experimental_payload:
1046
+ inline_custom_tools_payload["custom_tools"] = experimental_payload[
1047
+ "custom_tools"
1048
+ ]
1049
+ if "custom_toolkits" in experimental_payload:
1050
+ inline_custom_tools_payload["custom_toolkits"] = (
1051
+ experimental_payload["custom_toolkits"]
1052
+ )
1053
+
1054
+ from urllib.parse import quote
1055
+
1056
+ session = self._client.post(
1057
+ f"/api/v3.1/tool_router/session/{quote(session_id, safe='')}/attach",
1058
+ body={"experimental": experimental_payload},
1059
+ cast_to=SessionRetrieveResponse,
1060
+ )
1061
+ else:
1062
+ session = self._client.tool_router.session.retrieve(session_id)
1063
+
1064
+ custom_tools_map: t.Optional[CustomToolsMap] = None
1065
+ user_id: t.Optional[str] = None
1066
+ if has_customs:
1067
+ custom_tools_map = build_custom_tools_map_from_response(
1068
+ tools=custom_tools or [],
1069
+ toolkits=custom_toolkits,
1070
+ experimental=session.experimental,
1071
+ )
1072
+ user_id = session.config.user_id
1073
+
1074
+ preloaded_custom_tool_slugs = get_preloaded_custom_tool_slugs(
1075
+ custom_tools_map,
1076
+ )
1077
1078
files_mount = ToolRouterSessionFilesMount(self._client, session.session_id)
1079
experimental_response = ToolRouterSessionExperimental(
@@ -1019,7 +1081,6 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1081
assistive_prompt=None,
1082
)
1083
1022
- # Create and return the session
1084
return ToolRouterSession(
1085
client=self._client,
1086
provider=self._provider,
@@ -1033,7 +1094,11 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1094
url=session.mcp.url,
1095
),
1096
experimental=experimental_response,
1097
+ custom_tools_map=custom_tools_map,
1098
+ user_id=user_id,
1099
preload=_session_preload_config(session.config.preload),
1100
+ preloaded_custom_tool_slugs=preloaded_custom_tool_slugs,
1101
+ inline_custom_tools_payload=inline_custom_tools_payload,
1102
)
1103
1104