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): handle all Python reserved keywords in provider parameter names
The `_python_reserved` set was hardcoded to only `{"for", "async"}`, missing `"from"` and all other Python keywords. Tools from toolkits like Intercom that have a `from` parameter caused `ValueError: 'from' is not a valid parameter name` when building function signatures. Extracted keyword substitution logic into shared utilities (`substitute_reserved_python_keywords` / `reinstate_reserved_python_keywords`) using `keyword.iskeyword()` from stdlib for complete coverage, and applied it to all affected providers: langchain, gemini, langgraph, autogen, llamaindex. Closes PLEN-1671
jkomyno committed
Mar 3, 2026 at 11:46 UTC
a5cb9c1214fbc7b5e6256bdb753fa526bb25e6f0
7 files changed
+288
-100
python/composio/utils/shared.py
+78
@@ -2,6 +2,8 @@
2
Shared utils.
3
"""
4
5
+import copy
6
+import keyword
7
import typing as t
8
import uuid
9
from inspect import Parameter
@@ -32,10 +34,86 @@ __all__ = [
34
"get_signature_format_from_schema_params",
35
"get_pydantic_signature_format_from_schema_params",
36
"generate_request_id",
37
+ "substitute_reserved_python_keywords",
38
+ "reinstate_reserved_python_keywords",
39
]
40
41
reserved_names = ["validate"]
42
43
+_OBJ_MARKER = "-_object_-"
44
+
45
+
46
+def _make_safe_name(name: str) -> str:
47
+ """Append ``_rs`` to a Python keyword so it can be used as a parameter name."""
48
+ return f"{name}_rs"
49
+
50
+
51
+def substitute_reserved_python_keywords(
52
+ schema: t.Dict,
53
+) -> t.Tuple[dict, dict]:
54
+ """Replace Python reserved keywords in a JSON schema's property names.
55
+
56
+ Returns a ``(schema, keywords)`` tuple where *schema* has safe property
57
+ names and *keywords* maps each safe name back to the original. Nested
58
+ object schemas are processed recursively.
59
+
60
+ The schema is deep-copied before any mutation so the caller's original
61
+ is never modified.
62
+ """
63
+ if "properties" not in schema:
64
+ return schema, {}
65
+
66
+ schema = copy.deepcopy(schema)
67
+
68
+ keywords: t.Dict[str, t.Any] = {}
69
+ for p_name in list(schema["properties"]):
70
+ if not keyword.iskeyword(p_name):
71
+ continue
72
+
73
+ _nested_kw: t.Dict[str, t.Any] = {}
74
+ p_val = schema["properties"].pop(p_name)
75
+ if p_val.get("type") == "object":
76
+ p_val, _nested_kw = substitute_reserved_python_keywords(schema=p_val)
77
+
78
+ safe = _make_safe_name(p_name)
79
+ schema["properties"][safe] = p_val
80
+ keywords[safe] = p_name
81
+ keywords[f"{safe}{_OBJ_MARKER}"] = _nested_kw
82
+
83
+ # Also rename entries in the ``required`` list.
84
+ if keywords and "required" in schema:
85
+ reverse = {v: k for k, v in keywords.items() if not k.endswith(_OBJ_MARKER)}
86
+ schema["required"] = [reverse.get(r, r) for r in schema["required"]]
87
+
88
+ return schema, keywords
89
+
90
+
91
+def reinstate_reserved_python_keywords(
92
+ request: dict,
93
+ keywords: dict,
94
+) -> dict:
95
+ """Reverse the substitution performed by :func:`substitute_reserved_python_keywords`.
96
+
97
+ Modifies *request* **in-place** and returns it.
98
+ """
99
+ for clean_key in sorted(list(keywords), reverse=True):
100
+ subkeys = None
101
+ if clean_key.endswith(_OBJ_MARKER):
102
+ subkeys = keywords[clean_key]
103
+ clean_key, _ = clean_key.split(_OBJ_MARKER, maxsplit=1)
104
+
105
+ if clean_key not in request:
106
+ continue
107
+
108
+ original_value = request.pop(clean_key)
109
+ if subkeys:
110
+ original_value = reinstate_reserved_python_keywords(
111
+ request=original_value,
112
+ keywords=subkeys,
113
+ )
114
+ request[keywords[clean_key]] = original_value
115
+ return request
116
+
117
118
def _coerce_default_value(
119
default: t.Any,
python/providers/autogen/composio_autogen/provider.py
+12
-2
@@ -10,7 +10,11 @@ from autogen_core.tools import FunctionTool
10
from composio.client.types import Tool
11
from composio.core.provider import AgenticProvider
12
from composio.core.provider.agentic import AgenticProviderExecuteFn
13
-from composio.utils.shared import get_signature_format_from_schema_params
13
+from composio.utils.shared import (
14
+ get_signature_format_from_schema_params,
15
+ reinstate_reserved_python_keywords,
16
+ substitute_reserved_python_keywords,
17
+)
18
19
20
class AutogenProvider(
@@ -65,9 +69,15 @@ class AutogenProvider(
69
execute_tool: AgenticProviderExecuteFn,
70
) -> FunctionTool:
71
"""Wraps a composio tool as an Autogen FunctionTool."""
72
+ schema_params, keywords = substitute_reserved_python_keywords(
73
+ schema=tool.input_parameters
74
+ )
75
76
def execute_action(**kwargs: t.Any) -> t.Dict:
77
"""Placeholder function for executing action."""
78
+ kwargs = reinstate_reserved_python_keywords(
79
+ request=kwargs, keywords=keywords
80
+ )
81
return execute_tool(slug=tool.slug, arguments=kwargs)
82
83
# Create function with proper signature
@@ -80,7 +90,7 @@ class AutogenProvider(
90
91
# Set signature and annotations
92
params = get_signature_format_from_schema_params(
83
- schema_params=tool.input_parameters,
93
+ schema_params=schema_params,
94
)
95
function.__doc__ = tool.description
96
setattr(function, "__signature__", Signature(parameters=params))
python/providers/gemini/composio_gemini/provider.py
+7
-43
@@ -5,7 +5,6 @@ Calling (AFC). The SDK can introspect the callable's signature to derive
5
FunctionDeclaration schemas and auto-execute tool calls in the chat loop.
6
"""
7
8
-import copy
8
import types as pytypes
9
import typing as t
10
from inspect import Parameter, Signature
@@ -13,7 +12,11 @@ from inspect import Parameter, Signature
12
from composio.client.types import Tool
13
from composio.core.provider import AgenticProvider
14
from composio.core.provider.agentic import AgenticProviderExecuteFn
16
-from composio.utils.shared import get_pydantic_signature_format_from_schema_params
15
+from composio.utils.shared import (
16
+ get_pydantic_signature_format_from_schema_params,
17
+ reinstate_reserved_python_keywords,
18
+ substitute_reserved_python_keywords,
19
+)
20
21
# google-genai is only needed for handle_response (backward compat)
22
try:
@@ -24,45 +27,6 @@ except ImportError:
27
genai_types = None # type: ignore
28
HAS_GENAI = False
29
27
-_python_reserved = {"for", "async"}
28
-
29
-
30
-def _clean_reserved_keyword(keyword: str) -> str:
31
- return f"{keyword}_rs"
32
-
33
-
34
-def _substitute_reserved_python_keywords(schema: t.Dict) -> t.Tuple[dict, dict]:
35
- if "properties" not in schema:
36
- return schema, {}
37
-
38
- schema = copy.deepcopy(schema)
39
-
40
- keywords: t.Dict[str, str] = {}
41
- for p_name in list(schema["properties"]):
42
- if p_name not in _python_reserved:
43
- continue
44
-
45
- p_val = schema["properties"].pop(p_name)
46
- p_name_clean = _clean_reserved_keyword(keyword=p_name)
47
- schema["properties"][p_name_clean] = p_val
48
- keywords[p_name_clean] = p_name
49
-
50
- if keywords and "required" in schema:
51
- reverse_map = {v: k for k, v in keywords.items()}
52
- schema["required"] = [
53
- reverse_map.get(name, name) for name in schema["required"]
54
- ]
55
-
56
- return schema, keywords
57
-
58
-
59
-def _reinstate_reserved_python_keywords(request: dict, keywords: dict) -> dict:
60
- for clean_key, original_key in keywords.items():
61
- if clean_key not in request:
62
- continue
63
- request[original_key] = request.pop(clean_key)
64
- return request
65
-
30
31
def _to_serializable(value: t.Any) -> t.Any:
32
"""Recursively convert Pydantic models (and other non-JSON types) to plain dicts/lists.
@@ -135,14 +99,14 @@ class GeminiProvider(AgenticProvider[t.Callable, list[t.Callable]], name="gemini
99
self._executors[tool.slug] = execute_tool
100
101
# Handle reserved Python keywords in parameter names
138
- schema_params, keywords = _substitute_reserved_python_keywords(
102
+ schema_params, keywords = substitute_reserved_python_keywords(
103
schema=tool.input_parameters
104
)
105
106
def function(**kwargs: t.Any) -> t.Dict:
107
"""Composio tool execution wrapper."""
108
kwargs = _to_serializable(kwargs)
145
- kwargs = _reinstate_reserved_python_keywords(
109
+ kwargs = reinstate_reserved_python_keywords(
110
request=kwargs, keywords=keywords
111
)
112
result = execute_tool(tool.slug, kwargs)
python/providers/langchain/composio_langchain/provider.py
+4
-51
@@ -13,57 +13,10 @@ from composio.utils.pydantic import parse_pydantic_error
13
from composio.utils.shared import (
14
get_signature_format_from_schema_params,
15
json_schema_to_model,
16
+ reinstate_reserved_python_keywords,
17
+ substitute_reserved_python_keywords,
18
)
19
18
-_python_reserved = {"for", "async"}
19
-_obj_marker = "-_object_-"
20
-
21
-
22
-def _clean_reserved_keyword(keyword: str):
23
- return f"{keyword}_rs"
24
-
25
-
26
-def _substitute_reserved_python_keywords(schema: t.Dict) -> t.Tuple[dict, dict]:
27
- if "properties" not in schema:
28
- return schema, {}
29
-
30
- keywords = {}
31
- for p_name in list(schema["properties"]):
32
- if p_name not in _python_reserved:
33
- continue
34
-
35
- _keywords = {}
36
- p_val = schema["properties"].pop(p_name)
37
- if p_val.get("type") == "object":
38
- p_val, _keywords = _substitute_reserved_python_keywords(schema=p_val)
39
-
40
- p_name_clean = _clean_reserved_keyword(keyword=p_name)
41
- schema["properties"][p_name_clean] = p_val
42
- keywords[p_name_clean] = p_name
43
- keywords[f"{p_name_clean}{_obj_marker}"] = _keywords
44
-
45
- return schema, keywords
46
-
47
-
48
-def _reinstate_reserved_python_keywords(request: dict, keywords: dict) -> dict:
49
- for clean_key in sorted(list(keywords), reverse=True):
50
- subkeys = None
51
- if clean_key.endswith(_obj_marker):
52
- subkeys = keywords[clean_key]
53
- clean_key, _ = clean_key.split(_obj_marker, maxsplit=1)
54
-
55
- if clean_key not in request:
56
- continue
57
-
58
- orginal_value = request.pop(clean_key)
59
- if subkeys is not None:
60
- orginal_value = _reinstate_reserved_python_keywords(
61
- request=orginal_value,
62
- keywords=subkeys,
63
- )
64
- request[keywords[clean_key]] = orginal_value
65
- return request
66
-
20
21
class StructuredTool(BaseStructuredTool): # type: ignore[misc]
22
def run(self, *args, **kwargs):
@@ -88,13 +41,13 @@ class LangchainProvider(
41
) -> StructuredTool:
42
"""Wraps composio tool as Langchain StructuredTool object."""
43
# Replace reserved python keywords
91
- schema_params, keywords = _substitute_reserved_python_keywords(
44
+ schema_params, keywords = substitute_reserved_python_keywords(
45
schema=tool.input_parameters
46
)
47
48
def function(**kwargs: t.Any) -> t.Dict:
49
"""Wrapper function for composio action."""
97
- kwargs = _reinstate_reserved_python_keywords(
50
+ kwargs = reinstate_reserved_python_keywords(
51
request=kwargs,
52
keywords=keywords,
53
)
python/providers/langgraph/composio_langgraph/provider.py
+12
-2
@@ -13,6 +13,8 @@ from composio.utils.pydantic import parse_pydantic_error
13
from composio.utils.shared import (
14
get_signature_format_from_schema_params,
15
json_schema_to_model,
16
+ reinstate_reserved_python_keywords,
17
+ substitute_reserved_python_keywords,
18
)
19
20
@@ -37,10 +39,14 @@ class LanggraphProvider(
39
tool: str,
40
description: str,
41
schema_params: t.Dict,
42
+ keywords: t.Dict,
43
execute_tool: AgenticProviderExecuteFn,
44
):
45
def function(**kwargs: t.Any) -> t.Dict:
46
"""Wrapper function for composio action."""
47
+ kwargs = reinstate_reserved_python_keywords(
48
+ request=kwargs, keywords=keywords
49
+ )
50
return execute_tool(tool, kwargs)
51
52
action_func = types.FunctionType(
@@ -61,20 +67,24 @@ class LanggraphProvider(
67
self, tool: Tool, execute_tool: AgenticProviderExecuteFn
68
) -> StructuredTool:
69
"""Wraps composio tool as Langchain StructuredTool object."""
70
+ schema_params, keywords = substitute_reserved_python_keywords(
71
+ schema=tool.input_parameters
72
+ )
73
return t.cast(
74
StructuredTool,
75
StructuredTool.from_function(
76
name=tool.slug,
77
description=tool.description,
78
args_schema=json_schema_to_model(
70
- json_schema=tool.input_parameters,
79
+ json_schema=schema_params,
80
skip_default=self.skip_default,
81
),
82
return_schema=True,
83
func=self._wrap_action(
84
tool=tool.slug,
85
description=tool.description,
77
- schema_params=tool.input_parameters,
86
+ schema_params=schema_params,
87
+ keywords=keywords,
88
execute_tool=execute_tool,
89
),
90
handle_tool_error=True,
python/providers/llamaindex/composio_llamaindex/provider.py
+12
-2
@@ -8,7 +8,11 @@ from llama_index.core.tools import FunctionTool
8
9
from composio.core.provider import AgenticProvider, AgenticProviderExecuteFn
10
from composio.types import Tool
11
-from composio.utils.shared import get_signature_format_from_schema_params
11
+from composio.utils.shared import (
12
+ get_signature_format_from_schema_params,
13
+ reinstate_reserved_python_keywords,
14
+ substitute_reserved_python_keywords,
15
+)
16
17
18
class LlamaIndexProvider(
@@ -27,9 +31,15 @@ class LlamaIndexProvider(
31
"""
32
Wrap a tool into a LlamaIndex FunctionTool object.
33
"""
34
+ schema_params, keywords = substitute_reserved_python_keywords(
35
+ schema=tool.input_parameters
36
+ )
37
38
def function(**kwargs: t.Any) -> t.Dict:
39
"""Wrapper function for composio action."""
40
+ kwargs = reinstate_reserved_python_keywords(
41
+ request=kwargs, keywords=keywords
42
+ )
43
return execute_tool(slug=tool.slug, arguments=kwargs)
44
45
action_func = types.FunctionType(
@@ -40,7 +50,7 @@ class LlamaIndexProvider(
50
)
51
action_func.__signature__ = Signature( # type: ignore
52
parameters=get_signature_format_from_schema_params(
43
- schema_params=tool.input_parameters,
53
+ schema_params=schema_params,
54
skip_default=self.skip_default,
55
)
56
)
python/tests/test_provider.py
+163
@@ -672,6 +672,169 @@ class TestAgenticProviderFunctionality:
672
assert wrapped[0]["has_executor"] is True
673
674
675
+class TestLangchainReservedKeywords:
676
+ """Regression tests for PLEN-1671: ValueError when tool schema has Python reserved keywords as parameter names.
677
+
678
+ Tools from some toolkits (e.g. Intercom) have parameters named 'from',
679
+ which is a Python reserved keyword. The LangchainProvider must substitute
680
+ these names before building function signatures and reinstate them when
681
+ executing the tool.
682
+ """
683
+
684
+ def _make_tool_with_params(self, properties: dict, required: list | None = None):
685
+ """Helper: create a mock Tool whose input_parameters use the given properties."""
686
+ return Tool(
687
+ name="Test Tool",
688
+ slug="TEST_TOOL",
689
+ description="A tool for testing reserved keyword handling",
690
+ input_parameters={
691
+ "type": "object",
692
+ "title": "TestToolRequest",
693
+ "properties": properties,
694
+ "required": required or [],
695
+ },
696
+ output_parameters={},
697
+ available_versions=["12012025_00"],
698
+ version="12012025_00",
699
+ scopes=[],
700
+ status="active",
701
+ toolkit=tool_list_response.ItemToolkit(name="Test", slug="test", logo=""),
702
+ deprecated=tool_list_response.ItemDeprecated(
703
+ available_versions=["12012025_00"],
704
+ displayName="Test Tool",
705
+ version="12012025_00",
706
+ toolkit=tool_list_response.ItemDeprecatedToolkit(logo=""),
707
+ is_deprecated=False,
708
+ ),
709
+ is_deprecated=False,
710
+ no_auth=False,
711
+ tags=[],
712
+ )
713
+
714
+ def test_wrap_tool_with_from_parameter(self):
715
+ """PLEN-1671: 'from' parameter must not raise ValueError."""
716
+ from composio_langchain import LangchainProvider
717
+
718
+ provider = LangchainProvider()
719
+ tool = self._make_tool_with_params(
720
+ properties={
721
+ "from": {
722
+ "type": "string",
723
+ "description": "Starting point for listing",
724
+ },
725
+ "limit": {
726
+ "type": "integer",
727
+ "description": "Max results",
728
+ "default": 20,
729
+ },
730
+ },
731
+ )
732
+
733
+ captured = {}
734
+
735
+ def mock_execute(slug, arguments):
736
+ captured.update(arguments)
737
+ return {"data": {}, "error": None, "successful": True}
738
+
739
+ # Must not raise ValueError: 'from' is not a valid parameter name
740
+ wrapped = provider.wrap_tool(tool, mock_execute)
741
+
742
+ assert wrapped.name == "TEST_TOOL"
743
+
744
+ # Invoke the tool and verify 'from' is reinstated in the arguments
745
+ wrapped.run({"from_rs": "2024-01-01", "limit": 10})
746
+ assert captured == {"from": "2024-01-01", "limit": 10}
747
+
748
+ def test_wrap_tool_with_multiple_reserved_keywords(self):
749
+ """All Python reserved keywords used as parameter names must be handled."""
750
+ from composio_langchain import LangchainProvider
751
+
752
+ provider = LangchainProvider()
753
+ tool = self._make_tool_with_params(
754
+ properties={
755
+ "from": {
756
+ "type": "string",
757
+ "description": "Start date",
758
+ },
759
+ "for": {
760
+ "type": "string",
761
+ "description": "Recipient",
762
+ },
763
+ "import": {
764
+ "type": "string",
765
+ "description": "Import source",
766
+ },
767
+ "class": {
768
+ "type": "string",
769
+ "description": "CSS class",
770
+ },
771
+ "async": {
772
+ "type": "boolean",
773
+ "description": "Async flag",
774
+ "default": False,
775
+ },
776
+ "normal_param": {
777
+ "type": "string",
778
+ "description": "A normal parameter",
779
+ },
780
+ },
781
+ )
782
+
783
+ captured = {}
784
+
785
+ def mock_execute(slug, arguments):
786
+ captured.update(arguments)
787
+ return {"data": {}, "error": None, "successful": True}
788
+
789
+ wrapped = provider.wrap_tool(tool, mock_execute)
790
+ assert wrapped.name == "TEST_TOOL"
791
+
792
+ # Invoke with renamed parameters and verify originals are reinstated
793
+ wrapped.run(
794
+ {
795
+ "from_rs": "2024-01-01",
796
+ "for_rs": "user@example.com",
797
+ "import_rs": "csv",
798
+ "class_rs": "primary",
799
+ "async_rs": True,
800
+ "normal_param": "hello",
801
+ }
802
+ )
803
+ assert captured == {
804
+ "from": "2024-01-01",
805
+ "for": "user@example.com",
806
+ "import": "csv",
807
+ "class": "primary",
808
+ "async": True,
809
+ "normal_param": "hello",
810
+ }
811
+
812
+ def test_wrap_tool_with_required_reserved_keyword_param(self):
813
+ """Reserved keywords that are also required params must work."""
814
+ from composio_langchain import LangchainProvider
815
+
816
+ provider = LangchainProvider()
817
+ tool = self._make_tool_with_params(
818
+ properties={
819
+ "from": {
820
+ "type": "string",
821
+ "description": "Required start date",
822
+ },
823
+ },
824
+ required=["from"],
825
+ )
826
+
827
+ captured = {}
828
+
829
+ def mock_execute(slug, arguments):
830
+ captured.update(arguments)
831
+ return {"data": {}, "error": None, "successful": True}
832
+
833
+ wrapped = provider.wrap_tool(tool, mock_execute)
834
+ wrapped.run({"from_rs": "2024-01-01"})
835
+ assert captured == {"from": "2024-01-01"}
836
+
837
+
838
class TestProviderEdgeCases:
839
"""Test edge cases and error handling for providers."""
840