Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
fix(python): attach existing tool router sessions
Abir Taheer committed
May 7, 2026 at 02:10 UTC
26eda4606d162e2b38bf08da2ecda2b0f5ffa895
2 files changed
+98
-45
python/composio/core/models/tool_router.py
+14
-11
@@ -1000,9 +1000,9 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1000
"""
1001
Retrieve and use an existing tool router session, optionally attaching custom tools.
1002
1003
- When ``custom_tools`` or ``custom_toolkits`` are provided, the SDK
1004
- attaches them to the session so they are available for search and
1005
- execution. Without customs it simply rehydrates the existing session.
1003
+ The SDK always attaches to the session endpoint. When ``custom_tools``
1004
+ or ``custom_toolkits`` are provided, they are included so they are
1005
+ available for search and execution.
1006
1007
:param session_id: The session ID to retrieve
1008
:param custom_tools: Optional custom tools to attach to the session.
@@ -1046,15 +1046,18 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1046
serialize_custom_toolkits(custom_toolkits)
1047
)
1048
1049
- from urllib.parse import quote
1049
+ from urllib.parse import quote
1050
1051
- session = self._client.post(
1052
- f"/api/v3.1/tool_router/session/{quote(session_id, safe='')}/attach",
1053
- body={"experimental": inline_custom_tools_payload},
1054
- cast_to=SessionRetrieveResponse,
1055
- )
1056
- else:
1057
- session = self._client.tool_router.session.retrieve(session_id)
1051
+ body = (
1052
+ {"experimental": inline_custom_tools_payload}
1053
+ if inline_custom_tools_payload is not None
1054
+ else {}
1055
+ )
1056
+ session = self._client.post(
1057
+ f"/api/v3.1/tool_router/session/{quote(session_id, safe='')}/attach",
1058
+ body=body,
1059
+ cast_to=SessionRetrieveResponse,
1060
+ )
1061
1062
custom_tools_map: t.Optional[CustomToolsMap] = None
1063
user_id: t.Optional[str] = None
python/tests/test_tool_router.py
+84
-34
@@ -5,6 +5,9 @@ from unittest.mock import MagicMock, patch
5
import pytest
6
from composio_client import omit
7
from pydantic import BaseModel, Field
8
+from composio_client.types.tool_router.session_retrieve_response import (
9
+ SessionRetrieveResponse,
10
+)
11
12
from composio.exceptions import ValidationError
13
from composio.core.models.custom_tool import ExperimentalAPI
@@ -56,6 +59,7 @@ def mock_client():
59
60
client.tool_router.session.create.return_value = mock_session_response
61
client.tool_router.session.retrieve.return_value = mock_session_response
62
+ client.post.return_value = mock_session_response
63
64
# Mock link response
65
mock_link_response = MagicMock()
@@ -933,10 +937,8 @@ class TestToolRouter:
937
tool_router.use(session_id="session_123")
938
939
def test_use_session(self, tool_router, mock_client):
936
- """Test retrieving an existing session."""
937
- mock_client.tool_router.session.retrieve.return_value.config.preload.tools = [
938
- "GMAIL_FETCH_EMAILS"
939
- ]
940
+ """Test attaching an existing session."""
941
+ mock_client.post.return_value.config.preload.tools = ["GMAIL_FETCH_EMAILS"]
942
943
session = tool_router.use(session_id="session_123")
944
@@ -957,21 +959,63 @@ class TestToolRouter:
959
assert callable(session.toolkits)
960
assert session.preload.tools == ["GMAIL_FETCH_EMAILS"]
961
960
- # Verify retrieve was called
961
- mock_client.tool_router.session.retrieve.assert_called_once_with("session_123")
962
+ mock_client.post.assert_called_once_with(
963
+ "/api/v3.1/tool_router/session/session_123/attach",
964
+ body={},
965
+ cast_to=SessionRetrieveResponse,
966
+ )
967
+ mock_client.tool_router.session.retrieve.assert_not_called()
968
+
969
+ def test_use_session_with_custom_tools(self, tool_router, mock_client):
970
+ """Test attaching custom tools when reusing a session."""
971
+
972
+ @experimental_api.tool(
973
+ slug="GREP",
974
+ name="Grep",
975
+ description="Search local text",
976
+ )
977
+ def grep(input: GrepInput, ctx):
978
+ return {"matches": []}
979
+
980
+ mock_response = mock_client.post.return_value
981
+ mock_response.experimental = MagicMock()
982
+ mock_response.experimental.assistive_prompt = None
983
+ mock_response.experimental.custom_toolkits = []
984
+ mock_custom_tool = MagicMock()
985
+ mock_custom_tool.slug = "SERVER_GREP"
986
+ mock_custom_tool.original_slug = "GREP"
987
+ mock_custom_tool.extends_toolkit = None
988
+ mock_response.experimental.custom_tools = [mock_custom_tool]
989
+
990
+ session = tool_router.use(session_id="session_123", custom_tools=[grep])
991
+
992
+ mock_client.post.assert_called_once()
993
+ assert mock_client.post.call_args.args[0] == (
994
+ "/api/v3.1/tool_router/session/session_123/attach"
995
+ )
996
+ kwargs = mock_client.post.call_args.kwargs
997
+ assert kwargs["cast_to"] is SessionRetrieveResponse
998
+ assert kwargs["body"]["experimental"]["custom_tools"][0]["slug"] == "GREP"
999
+ assert "custom_toolkits" not in kwargs["body"]["experimental"]
1000
+ mock_client.tool_router.session.retrieve.assert_not_called()
1001
+ assert session.custom_tools()[0].slug == "SERVER_GREP"
1002
+ assert session.custom_tools()[0].name == "Grep"
1003
1004
def test_use_session_with_different_user(self, tool_router, mock_client):
1005
"""Test that use() extracts user_id from session config."""
965
- mock_retrieve_response = MagicMock()
966
- mock_retrieve_response.session_id = "session_456"
967
- mock_retrieve_response.mcp = MagicMock()
968
- mock_retrieve_response.mcp.type = "http"
969
- mock_retrieve_response.mcp.url = "https://mcp.example.com/session_456"
970
- mock_retrieve_response.tool_router_tools = ["TOOL_1"]
971
- mock_retrieve_response.config = MagicMock()
972
- mock_retrieve_response.config.user_id = "custom_user_789"
973
-
974
- mock_client.tool_router.session.retrieve.return_value = mock_retrieve_response
1006
+ mock_attach_response = MagicMock()
1007
+ mock_attach_response.session_id = "session_456"
1008
+ mock_attach_response.mcp = MagicMock()
1009
+ mock_attach_response.mcp.type = "http"
1010
+ mock_attach_response.mcp.url = "https://mcp.example.com/session_456"
1011
+ mock_attach_response.tool_router_tools = ["TOOL_1"]
1012
+ mock_attach_response.config = MagicMock()
1013
+ mock_attach_response.config.user_id = "custom_user_789"
1014
+ mock_attach_response.config.preload = MagicMock()
1015
+ mock_attach_response.config.preload.tools = []
1016
+ mock_attach_response.experimental = None
1017
+
1018
+ mock_client.post.return_value = mock_attach_response
1019
1020
session = tool_router.use(session_id="session_456")
1021
@@ -979,10 +1023,8 @@ class TestToolRouter:
1023
assert session.mcp.type == ToolRouterMCPServerType.HTTP
1024
1025
def test_use_session_throws_error_on_failure(self, tool_router, mock_client):
982
- """Test that use() throws error if retrieve fails."""
983
- mock_client.tool_router.session.retrieve.side_effect = Exception(
984
- "Session not found"
985
- )
1026
+ """Test that use() throws error if attach fails."""
1027
+ mock_client.post.side_effect = Exception("Session not found")
1028
1029
with pytest.raises(Exception, match="Session not found"):
1030
tool_router.use(session_id="invalid_session")
@@ -1376,7 +1418,7 @@ class TestToolRouter:
1418
1419
def test_use_vs_create_independence(self, tool_router, mock_client):
1420
"""Test that use() and create() are independent."""
1379
- # Setup different responses for create and retrieve
1421
+ # Setup different responses for create and attach
1422
mock_create_response = MagicMock()
1423
mock_create_response.session_id = "created_session"
1424
mock_create_response.mcp = MagicMock()
@@ -1384,17 +1426,20 @@ class TestToolRouter:
1426
mock_create_response.mcp.url = "https://mcp.example.com/created"
1427
mock_create_response.tool_router_tools = ["TOOL_1"]
1428
1387
- mock_retrieve_response = MagicMock()
1388
- mock_retrieve_response.session_id = "retrieved_session"
1389
- mock_retrieve_response.mcp = MagicMock()
1390
- mock_retrieve_response.mcp.type = "http"
1391
- mock_retrieve_response.mcp.url = "https://mcp.example.com/retrieved"
1392
- mock_retrieve_response.tool_router_tools = ["TOOL_2"]
1393
- mock_retrieve_response.config = MagicMock()
1394
- mock_retrieve_response.config.user_id = "user_456"
1429
+ mock_attach_response = MagicMock()
1430
+ mock_attach_response.session_id = "retrieved_session"
1431
+ mock_attach_response.mcp = MagicMock()
1432
+ mock_attach_response.mcp.type = "http"
1433
+ mock_attach_response.mcp.url = "https://mcp.example.com/retrieved"
1434
+ mock_attach_response.tool_router_tools = ["TOOL_2"]
1435
+ mock_attach_response.config = MagicMock()
1436
+ mock_attach_response.config.user_id = "user_456"
1437
+ mock_attach_response.config.preload = MagicMock()
1438
+ mock_attach_response.config.preload.tools = []
1439
+ mock_attach_response.experimental = None
1440
1441
mock_client.tool_router.session.create.return_value = mock_create_response
1397
- mock_client.tool_router.session.retrieve.return_value = mock_retrieve_response
1442
+ mock_client.post.return_value = mock_attach_response
1443
1444
# Create a new session
1445
created_session = tool_router.create(user_id="user_123")
@@ -1406,7 +1451,12 @@ class TestToolRouter:
1451
1452
# Verify both methods were called
1453
mock_client.tool_router.session.create.assert_called_once()
1409
- mock_client.tool_router.session.retrieve.assert_called_once()
1454
+ mock_client.post.assert_called_once_with(
1455
+ "/api/v3.1/tool_router/session/retrieved_session/attach",
1456
+ body={},
1457
+ cast_to=SessionRetrieveResponse,
1458
+ )
1459
+ mock_client.tool_router.session.retrieve.assert_not_called()
1460
1461
1462
class TestToolRouterTypes:
@@ -1755,13 +1805,13 @@ class TestToolRouterIntegration:
1805
assert tools == ["tool1", "tool2"]
1806
1807
def test_create_and_use_same_session(self, tool_router, mock_client):
1758
- """Test creating a session and then retrieving it."""
1808
+ """Test creating a session and then attaching it."""
1809
# Create session
1810
created_session = tool_router.create(user_id="user_123")
1811
created_session_id = created_session.session_id
1812
1763
- # Setup retrieve to return the same session
1764
- mock_client.tool_router.session.retrieve.return_value = (
1813
+ # Setup attach to return the same session
1814
+ mock_client.post.return_value = (
1815
mock_client.tool_router.session.create.return_value
1816
)
1817