Skip to content

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): dereference $ref/$defs in Google provider (#4297)

CoralGarden5285d49235072d
diff --git a/python/providers/crewai/composio_crewai/providers.py b/python/providers/crewai/composio_crewai/providers.py
index 39c237ab6..8c54b35b9 100644
--- a/python/providers/crewai/composio_crewai/providers.py
+++ b/python/providers/crewai/composio_crewai/providers.py
@@ -5,6 +5,7 @@ from crewai.tools import BaseTool
from composio.core.provider import AgenticProvider, AgenticProviderExecuteFn
from composio.types import Tool
+from composio.utils.json_schema import dereference_json_schema
from composio.utils.pydantic import parse_pydantic_error
from composio.utils.shared import (
json_schema_to_model,
@@ -57,11 +58,19 @@ class CrewAIProvider(AgenticProvider[BaseTool, list[BaseTool]], name="crewai"):
"data": None,
}
+ # Inline internal $ref/$defs before building the Pydantic model. The
+ # converter types a referenced property as Any, so CrewAI would show the
+ # model an untyped argument. Dangling references degrade to a permissive
+ # object instead of raising, matching the other providers.
+ input_parameters = dereference_json_schema(
+ tool.input_parameters,
+ on_unresolved="sentinel",
+ )
return Wrapper(
name=tool.slug,
description=tool.description,
args_schema=json_schema_to_model(
- json_schema=tool.input_parameters,
+ json_schema=input_parameters,
skip_default=self.skip_default,
),
)
diff --git a/python/providers/google/composio_google/provider.py b/python/providers/google/composio_google/provider.py
index 6604bece6..7f2cb7285 100644
--- a/python/providers/google/composio_google/provider.py
+++ b/python/providers/google/composio_google/provider.py
@@ -14,6 +14,7 @@ from vertexai.generative_models import (
from composio.core.provider import NonAgenticProvider
from composio.types import Modifiers, Tool, ToolExecutionResponse
+from composio.utils.json_schema import dereference_json_schema
from composio.utils.shared import normalize_tool_arguments
@@ -35,10 +36,14 @@ class GoogleProvider(
def wrap_tool(self, tool: Tool) -> FunctionDeclaration:
"""Wraps composio tool as Google AI Python Gemini FunctionDeclaration object."""
+ input_parameters = dereference_json_schema(
+ tool.input_parameters,
+ on_unresolved="sentinel",
+ )
# Clean up properties by removing 'examples' field
properties = t.cast(
dict[str, dict],
- tool.input_parameters.get("properties", {}),
+ input_parameters.get("properties", {}),
)
cleaned_properties = {
prop_name: {k: v for k, v in prop_schema.items() if k != "examples"}
@@ -50,7 +55,7 @@ class GoogleProvider(
parameters={
"type": "object",
"properties": cleaned_properties,
- "required": tool.input_parameters.get("required", []),
+ "required": input_parameters.get("required", []),
},
)
diff --git a/python/tests/test_crewai_provider.py b/python/tests/test_crewai_provider.py
new file mode 100644
index 000000000..2b656e58e
--- /dev/null
+++ b/python/tests/test_crewai_provider.py
@@ -0,0 +1,36 @@
+"""Tests for the CrewAI provider."""
+
+import pytest
+from pydantic import BaseModel
+
+from composio.client.types import Tool
+
+CrewAIProvider = pytest.importorskip("composio_crewai").CrewAIProvider
+
+
+def test_wrap_tool_dereferences_internal_refs() -> None:
+ """Referenced input properties must keep their type in the args schema."""
+ tool = Tool.model_construct(
+ slug="TEST_REF",
+ description="test",
+ input_parameters={
+ "type": "object",
+ "properties": {"message": {"$ref": "#/$defs/Message"}},
+ "required": ["message"],
+ "$defs": {
+ "Message": {
+ "type": "object",
+ "properties": {"subject": {"type": "string"}},
+ "required": ["subject"],
+ }
+ },
+ },
+ )
+
+ wrapped = CrewAIProvider().wrap_tool(tool, lambda slug, arguments: {})
+ assert wrapped.args_schema is not None
+ message_type = wrapped.args_schema.model_fields["message"].annotation
+
+ assert isinstance(message_type, type)
+ assert issubclass(message_type, BaseModel)
+ assert message_type.model_fields["subject"].annotation is str
diff --git a/python/tests/test_google_provider.py b/python/tests/test_google_provider.py
new file mode 100644
index 000000000..db7885184
--- /dev/null
+++ b/python/tests/test_google_provider.py
@@ -0,0 +1,33 @@
+"""Tests for the Vertex AI Google provider."""
+
+import pytest
+
+from composio.client.types import Tool
+
+GoogleProvider = pytest.importorskip("composio_google").GoogleProvider
+
+
+def test_wrap_tool_dereferences_internal_refs() -> None:
+ """Referenced input properties must be expanded before Vertex translation."""
+ tool = Tool.model_construct(
+ slug="TEST_REF",
+ description="test",
+ input_parameters={
+ "type": "object",
+ "properties": {"message": {"$ref": "#/$defs/Message"}},
+ "required": ["message"],
+ "$defs": {
+ "Message": {
+ "type": "object",
+ "properties": {"subject": {"type": "string"}},
+ "required": ["subject"],
+ }
+ },
+ },
+ )
+
+ wrapped = GoogleProvider().wrap_tool(tool)
+ message_schema = wrapped.to_dict()["parameters"]["properties"]["message"]
+
+ assert "ref" not in message_schema
+ assert message_schema["properties"]["subject"]["type"] == "STRING"
diff --git a/python/tests/test_provider_ref_contract.py b/python/tests/test_provider_ref_contract.py
new file mode 100644
index 000000000..f3c226dfb
--- /dev/null
+++ b/python/tests/test_provider_ref_contract.py
@@ -0,0 +1,183 @@
+"""Cross-provider ``$ref`` handling contract.
+
+Every provider under ``python/providers`` must be classified here. A provider
+either resolves internal ``$ref``/``$defs`` pointers before translating the
+schema for its framework, or forwards the schema whole to a vendor that
+resolves references natively. Adding a provider without classifying it fails
+the suite, so the taxonomy is a build gate rather than tribal knowledge.
+
+The test reads source text instead of importing the providers: importing all
+of them would make every vendor SDK a test dependency of the core package.
+Behavioral assertions live next to each provider (for example
+``tests/test_google_provider.py``); this test owns completeness.
+
+TypeScript counterpart: ``ts/packages/core/test/providers/refContract.test.ts``.
+"""
+
+from __future__ import annotations
+
+import typing as t
+from dataclasses import dataclass
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+PROVIDERS_DIR = REPO_ROOT / "python" / "providers"
+
+# Helpers that inline internal references before schema translation.
+# ``alias_tool_input_schema`` and ``substitute_reserved_python_keywords``
+# call ``dereference_json_schema`` internally. ``json_schema_to_model`` is
+# not one of them: it types a referenced property as ``Any``.
+RESOLVER_HELPERS: t.Final = (
+ "dereference_json_schema",
+ "alias_tool_input_schema",
+ "substitute_reserved_python_keywords",
+)
+
+
+@dataclass(frozen=True)
+class Classification:
+ """How a provider treats a tool's input schema."""
+
+ treatment: t.Literal["resolves-refs", "passthrough"]
+ reason: str
+ # Helper the provider relies on; required for ``resolves-refs``.
+ via: t.Optional[str] = None
+
+
+PROVIDER_PACKAGES: t.Final[dict[str, Classification]] = {
+ "anthropic": Classification(
+ "resolves-refs",
+ "aliases property keys, which requires keys behind a ref to be materialized",
+ via="alias_tool_input_schema",
+ ),
+ "autogen": Classification(
+ "resolves-refs",
+ "builds a Python signature from properties, so refs must be inlined first",
+ via="substitute_reserved_python_keywords",
+ ),
+ "claude_agent_sdk": Classification(
+ "resolves-refs",
+ "aliases property keys before building the MCP tool schema",
+ via="alias_tool_input_schema",
+ ),
+ "crewai": Classification(
+ "resolves-refs",
+ "converts to a Pydantic model; the converter types a $ref property as Any",
+ via="dereference_json_schema",
+ ),
+ "gemini": Classification(
+ "resolves-refs",
+ "aliases property keys and converts to a Pydantic model",
+ via="alias_tool_input_schema",
+ ),
+ "google": Classification(
+ "resolves-refs",
+ "rebuilds the root from properties/required; Vertex FunctionDeclaration "
+ "has no ref/defs field",
+ via="dereference_json_schema",
+ ),
+ "google_adk": Classification(
+ "resolves-refs",
+ "builds a Python signature from properties, so refs must be inlined first",
+ via="alias_tool_input_schema",
+ ),
+ "langchain": Classification(
+ "resolves-refs",
+ "builds a Pydantic args schema from properties",
+ via="substitute_reserved_python_keywords",
+ ),
+ "langgraph": Classification(
+ "resolves-refs",
+ "builds a Pydantic args schema from properties",
+ via="substitute_reserved_python_keywords",
+ ),
+ "llamaindex": Classification(
+ "resolves-refs",
+ "builds a Python signature from properties, so refs must be inlined first",
+ via="substitute_reserved_python_keywords",
+ ),
+ "openai": Classification(
+ "passthrough",
+ "re-exports the core OpenAI providers, which forward the whole schema",
+ ),
+ "openai_agents": Classification(
+ "passthrough",
+ "forwards the whole schema; OpenAI resolves $defs/$ref natively",
+ ),
+}
+
+# Sources outside ``python/providers`` that hand schemas to a vendor.
+EXTRA_PASSTHROUGH_SOURCES: t.Final[dict[str, str]] = {
+ "python/composio/core/provider/_openai.py": "forwards the whole schema",
+ "python/composio/core/provider/_openai_responses.py": "forwards the whole schema",
+}
+
+
+def _discover_providers() -> list[str]:
+ return sorted(
+ entry.name
+ for entry in PROVIDERS_DIR.iterdir()
+ if entry.is_dir() and (entry / "pyproject.toml").is_file()
+ )
+
+
+def _provider_source(provider: str) -> str:
+ package_dirs = [
+ entry
+ for entry in (PROVIDERS_DIR / provider).iterdir()
+ if entry.is_dir() and entry.name.startswith("composio_")
+ ]
+ assert package_dirs, f"no composio_* package under providers/{provider}"
+ return "\n".join(
+ path.read_text(encoding="utf-8")
+ for package_dir in package_dirs
+ for path in sorted(package_dir.rglob("*.py"))
+ )
+
+
+DISCOVERED: t.Final = _discover_providers()
+
+
+def test_discovers_provider_packages() -> None:
+ # Guards the test itself: a broken path would make everything below
+ # vacuously pass.
+ assert len(DISCOVERED) >= 12
+
+
+def test_classifies_every_provider_package() -> None:
+ assert [name for name in DISCOVERED if name not in PROVIDER_PACKAGES] == []
+
+
+def test_does_not_classify_removed_providers() -> None:
+ assert [name for name in PROVIDER_PACKAGES if name not in DISCOVERED] == []
+
+
+ "provider",
+ [n for n, c in PROVIDER_PACKAGES.items() if c.treatment == "resolves-refs"],
+)
+def test_resolves_refs_before_translation(provider: str) -> None:
+ classification = PROVIDER_PACKAGES[provider]
+ assert classification.via in RESOLVER_HELPERS, classification.reason
+ assert classification.via in _provider_source(provider), classification.reason
+
+
+ "provider",
+ [n for n, c in PROVIDER_PACKAGES.items() if c.treatment == "passthrough"],
+)
+def test_forwards_schema_whole(provider: str) -> None:
+ classification = PROVIDER_PACKAGES[provider]
+ assert classification.via is None
+ source = _provider_source(provider)
+ assert [h for h in RESOLVER_HELPERS if h in source] == [], classification.reason
+
+
[email protected]("relative_path", sorted(EXTRA_PASSTHROUGH_SOURCES))
+def test_extra_sources_forward_schema_whole(relative_path: str) -> None:
+ path = REPO_ROOT / relative_path
+ assert path.is_file(), f"{relative_path} not found; update this test"
+ source = path.read_text(encoding="utf-8")
+ assert [h for h in RESOLVER_HELPERS if h in source] == []