@devries-cameron20 / composio-1 / commits / 366c795e4
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.

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