Skip to content

Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.

Add Clipper integrations client (#7196)

Vinicius Brasil968c3065d334
diff --git a/lib/crewai-tools/src/crewai_tools/tools/crewai_platform_tools/crewai_platform_tools.py b/lib/crewai-tools/src/crewai_tools/tools/crewai_platform_tools/crewai_platform_tools.py
index 8fab93f40..2dc083b98 100644
--- a/lib/crewai-tools/src/crewai_tools/tools/crewai_platform_tools/crewai_platform_tools.py
+++ b/lib/crewai-tools/src/crewai_tools/tools/crewai_platform_tools/crewai_platform_tools.py
@@ -7,8 +7,7 @@ from crewai_tools.tools.crewai_platform_tools.crewai_platform_action_tool import
)
from crewai_tools.tools.crewai_platform_tools.integrations_client import (
ApplicationSelector,
- IntegrationsClient,
- LegacyClient,
+ client_for_selector,
)
@@ -27,16 +26,19 @@ def CrewaiPlatformTools( # noqa: N802
A list of BaseTool instances for platform actions
"""
selectors = [ApplicationSelector.from_string(app) for app in apps]
- client: IntegrationsClient = LegacyClient()
+ tools: list[BaseTool] = []
try:
- tool_infos = client.get_actions(selectors)
+ for selector in selectors:
+ client = client_for_selector(selector)
+ tools.extend(
+ CrewAIPlatformActionTool(tool_info, client=client)
+ for tool_info in client.get_actions([selector])
+ )
except ValueError:
raise
except Exception as error:
logger.error(f"Failed to fetch platform tools for apps {apps}: {error}")
return []
- return [
- CrewAIPlatformActionTool(tool_info, client=client) for tool_info in tool_infos
- ]
+ return tools
diff --git a/lib/crewai-tools/src/crewai_tools/tools/crewai_platform_tools/integrations_client.py b/lib/crewai-tools/src/crewai_tools/tools/crewai_platform_tools/integrations_client.py
index 351f5be52..efa0e7b33 100644
--- a/lib/crewai-tools/src/crewai_tools/tools/crewai_platform_tools/integrations_client.py
+++ b/lib/crewai-tools/src/crewai_tools/tools/crewai_platform_tools/integrations_client.py
@@ -123,6 +123,106 @@ class IntegrationsClient(Protocol):
"""Execute an action with the given arguments."""
+class ClipperClient:
+ """Use the Clipper platform integrations API."""
+
+ _RESOURCE = "/clipper/v1"
+
+ def get_actions(self, selectors: list[ApplicationSelector]) -> list[ToolInfo]:
+ """Get the actions available for the selected applications."""
+ plus_api = PlusAPI()
+ base_url = f"{plus_api.base_url.rstrip('/')}{self._RESOURCE}"
+ headers = self._headers()
+ tool_infos: list[ToolInfo] = []
+
+ for selector in selectors:
+ url = f"{base_url}/applications/{selector.app}/tools"
+ if selector.action is not None:
+ url = f"{url}/{selector.action}"
+
+ params = (
+ {"connection_id": str(selector.connection_id)}
+ if selector.connection_id is not None
+ else {}
+ )
+ response = requests.get(
+ url,
+ headers=headers,
+ params=params,
+ timeout=30,
+ verify=os.environ.get("CREWAI_FACTORY", "false").lower() != "true",
+ )
+ response.raise_for_status()
+ data = response.json()["data"]
+ actions = data if selector.action is None else [data]
+
+ tool_infos.extend(
+ ToolInfo(
+ app=selector.app,
+ action=action["slug"],
+ connection_id=selector.connection_id,
+ description=action["description"],
+ parameters=action["input_schema"],
+ )
+ for action in actions
+ )
+
+ return tool_infos
+
+ def execute_action(
+ self, tool: ToolInfo, arguments: dict[str, Any]
+ ) -> ToolExecutionResult:
+ """Execute an action with the given arguments."""
+ plus_api = PlusAPI()
+ payload: dict[str, Any] = {"arguments": arguments}
+ if tool.connection_id is not None:
+ payload["connection_id"] = str(tool.connection_id)
+
+ response = requests.post(
+ (
+ f"{plus_api.base_url.rstrip('/')}{self._RESOURCE}"
+ f"/applications/{tool.app}/tools/{tool.action}/execute"
+ ),
+ headers=self._headers(),
+ json=payload,
+ timeout=60,
+ verify=os.environ.get("CREWAI_FACTORY", "false").lower() != "true",
+ )
+ if 200 <= response.status_code < 300:
+ data = response.json()
+ return ToolExecutionSuccess(output=data["data"]["output"])
+
+ try:
+ error = response.json()["errors"][0]
+ message = error["detail"]
+ code = error["code"]
+ except (
+ requests.exceptions.JSONDecodeError,
+ KeyError,
+ IndexError,
+ TypeError,
+ ):
+ message = f"Upstream API request failed with status {response.status_code}."
+ code = str(response.status_code)
+
+ return ToolExecutionFailure(
+ message=message,
+ code=code,
+ retryable=500 <= response.status_code < 600,
+ )
+
+ @staticmethod
+ def _headers() -> dict[str, str]:
+ headers = {
+ "Authorization": f"Bearer {get_platform_integration_token()}",
+ }
+ deployment_instance_uuid = os.getenv("CREWAI_DEPLOYMENT_INSTANCE_UUID")
+ if deployment_instance_uuid:
+ headers["X-Crewai-Deployment-Instance-Id"] = deployment_instance_uuid
+
+ return headers
+
+
class LegacyClient:
"""Use the existing CrewAI platform integrations API."""
@@ -210,3 +310,10 @@ class LegacyClient:
)
return ToolExecutionSuccess(output=data)
+
+
+def client_for_selector(selector: ApplicationSelector) -> IntegrationsClient:
+ """Select the integrations client for an application selector."""
+ if selector.connection_id is not None:
+ return ClipperClient()
+ return LegacyClient()
diff --git a/lib/crewai-tools/tests/tools/crewai_platform_tools/test_crewai_platform_tools.py b/lib/crewai-tools/tests/tools/crewai_platform_tools/test_crewai_platform_tools.py
index 48d7c649f..6443bdd21 100644
--- a/lib/crewai-tools/tests/tools/crewai_platform_tools/test_crewai_platform_tools.py
+++ b/lib/crewai-tools/tests/tools/crewai_platform_tools/test_crewai_platform_tools.py
@@ -81,12 +81,10 @@ class TestCrewaiPlatformTools(unittest.TestCase):
assert tools[0].description == "Create a GitHub issue"
assert tools[1].description == "Send a Slack message"
- mock_get.assert_called_once()
- args, kwargs = mock_get.call_args
- assert (
- "apps=github,slack" in args[0]
- or kwargs.get("params", {}).get("apps") == "github,slack"
- )
+ assert [request.kwargs["params"] for request in mock_get.call_args_list] == [
+ {"apps": "github"},
+ {"apps": "slack"},
+ ]
@patch.dict("os.environ", {"CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token"})
@patch(
@@ -190,9 +188,7 @@ class TestCrewaiPlatformTools(unittest.TestCase):
execution_response.json.return_value = {"issue": 42}
mock_post.return_value = execution_response
- tools = CrewaiPlatformTools(
- apps=["github@550e8400-e29b-41d4-a716-446655440000"]
- )
+ tools = CrewaiPlatformTools(apps=["github"])
result = tools[0].run(title="Contract test")
assert mock_get.call_args.kwargs["params"] == {"apps": "github"}
@@ -204,6 +200,93 @@ class TestCrewaiPlatformTools(unittest.TestCase):
}
assert result == '{\n "issue": 42\n}'
+ @patch.dict(
+ "os.environ",
+ {
+ "CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token",
+ "CREWAI_PLUS_URL": "https://platform.example.test/",
+ },
+ clear=True,
+ )
+ @patch(
+ "crewai_tools.tools.crewai_platform_tools.integrations_client.requests.post"
+ )
+ @patch(
+ "crewai_tools.tools.crewai_platform_tools.integrations_client.requests.get"
+ )
+ def test_connection_selects_clipper_api(self, mock_get, mock_post):
+ discovery_response = Mock()
+ discovery_response.raise_for_status.return_value = None
+ discovery_response.json.return_value = {
+ "data": {
+ "slug": "create_issue",
+ "description": "Create a GitHub issue",
+ "input_schema": {
+ "type": "object",
+ "properties": {"title": {"type": "string"}},
+ "required": ["title"],
+ },
+ }
+ }
+ mock_get.return_value = discovery_response
+ execution_response = Mock(status_code=200)
+ execution_response.json.return_value = {"data": {"output": {"issue": 42}}}
+ mock_post.return_value = execution_response
+ connection_id = "550e8400-e29b-41d4-a716-446655440000"
+
+ tools = CrewaiPlatformTools(
+ apps=[f"github/create_issue@{connection_id}"]
+ )
+ result = tools[0].run(title="Contract test")
+
+ assert mock_get.call_args.args[0].endswith(
+ "/clipper/v1/applications/github/tools/create_issue"
+ )
+ assert mock_get.call_args.kwargs["params"] == {
+ "connection_id": connection_id
+ }
+ assert mock_post.call_args.args[0].endswith(
+ "/clipper/v1/applications/github/tools/create_issue/execute"
+ )
+ assert mock_post.call_args.kwargs["json"] == {
+ "arguments": {"title": "Contract test"},
+ "connection_id": connection_id,
+ }
+ assert result == '{\n "issue": 42\n}'
+
+ @patch.dict(
+ "os.environ",
+ {
+ "CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token",
+ "CREWAI_PLUS_URL": "https://platform.example.test/",
+ },
+ clear=True,
+ )
+ @patch(
+ "crewai_tools.tools.crewai_platform_tools.integrations_client.requests.get"
+ )
+ def test_mixed_selectors_use_both_apis(self, mock_get):
+ legacy_response = Mock()
+ legacy_response.raise_for_status.return_value = None
+ legacy_response.json.return_value = {"actions": {"slack": []}}
+ clipper_response = Mock()
+ clipper_response.raise_for_status.return_value = None
+ clipper_response.json.return_value = {"data": []}
+ mock_get.side_effect = [legacy_response, clipper_response]
+ connection_id = "550e8400-e29b-41d4-a716-446655440000"
+
+ tools = CrewaiPlatformTools(apps=["slack", f"github@{connection_id}"])
+
+ assert tools == []
+ assert mock_get.call_count == 2
+ assert mock_get.call_args_list[0].kwargs["params"] == {"apps": "slack"}
+ assert mock_get.call_args_list[1].args[0].endswith(
+ "/clipper/v1/applications/github/tools"
+ )
+ assert mock_get.call_args_list[1].kwargs["params"] == {
+ "connection_id": connection_id
+ }
+
@patch.dict("os.environ", {"CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token"})
@patch(
"crewai_tools.tools.crewai_platform_tools.integrations_client.requests.get"
@@ -246,14 +329,10 @@ class TestCrewaiPlatformTools(unittest.TestCase):
response = Mock()
response.raise_for_status.return_value = None
response.json.return_value = {
- "actions": {
- "Google Drive": [
- {
- "name": "CreateFile!",
- "description": "Create a file",
- "parameters": {},
- }
- ]
+ "data": {
+ "slug": "CreateFile!",
+ "description": "Create a file",
+ "input_schema": {},
}
}
mock_get.return_value = response
diff --git a/lib/crewai-tools/tests/tools/crewai_platform_tools/test_integrations_client.py b/lib/crewai-tools/tests/tools/crewai_platform_tools/test_integrations_client.py
index 395af2c43..867b01d87 100644
--- a/lib/crewai-tools/tests/tools/crewai_platform_tools/test_integrations_client.py
+++ b/lib/crewai-tools/tests/tools/crewai_platform_tools/test_integrations_client.py
@@ -1,12 +1,14 @@
from dataclasses import FrozenInstanceError
from typing import Any
-from unittest.mock import Mock, patch
+from unittest.mock import Mock, call, patch
from uuid import UUID
import pytest
+from requests.exceptions import JSONDecodeError
from crewai_tools.tools.crewai_platform_tools.integrations_client import (
ApplicationSelector,
+ ClipperClient,
IntegrationsClient,
LegacyClient,
ToolExecutionFailure,
@@ -15,6 +17,362 @@ from crewai_tools.tools.crewai_platform_tools.integrations_client import (
)
+ "os.environ",
+ {
+ "CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token",
+ "CREWAI_DEPLOYMENT_INSTANCE_UUID": "deployment-instance-id",
+ "CREWAI_FACTORY": "false",
+ "CREWAI_PLUS_URL": "https://platform.example.test/",
+ },
+)
+@patch(
+ "crewai_tools.tools.crewai_platform_tools.integrations_client.requests.get"
+)
+def test_clipper_client_discovers_selected_actions(mock_get: Mock) -> None:
+ index_response = Mock()
+ index_response.raise_for_status.return_value = None
+ index_response.json.return_value = {
+ "data": [
+ {
+ "slug": "create_issue",
+ "description": "Create a GitHub issue",
+ "input_schema": {"type": "object"},
+ }
+ ]
+ }
+ show_response = Mock()
+ show_response.raise_for_status.return_value = None
+ show_response.json.return_value = {
+ "data": {
+ "slug": "create_issue",
+ "description": "Create a GitHub issue",
+ "input_schema": {"type": "object"},
+ }
+ }
+ mock_get.side_effect = [index_response, show_response]
+ connection_id = UUID("550e8400-e29b-41d4-a716-446655440000")
+
+ tools = ClipperClient().get_actions(
+ [
+ ApplicationSelector.from_string(f"github@{connection_id}"),
+ ApplicationSelector.from_string("github/create_issue"),
+ ]
+ )
+
+ expected_tool = ToolInfo(
+ app="github",
+ action="create_issue",
+ connection_id=connection_id,
+ description="Create a GitHub issue",
+ parameters={"type": "object"},
+ )
+ assert tools == [
+ expected_tool,
+ ToolInfo(
+ app="github",
+ action="create_issue",
+ connection_id=None,
+ description="Create a GitHub issue",
+ parameters={"type": "object"},
+ ),
+ ]
+ headers = {
+ "Authorization": "Bearer test_token",
+ "X-Crewai-Deployment-Instance-Id": "deployment-instance-id",
+ }
+ assert mock_get.call_args_list == [
+ call(
+ "https://platform.example.test/clipper/v1/applications/github/tools",
+ headers=headers,
+ params={"connection_id": str(connection_id)},
+ timeout=30,
+ verify=True,
+ ),
+ call(
+ "https://platform.example.test/clipper/v1/applications/github/tools/create_issue",
+ headers=headers,
+ params={},
+ timeout=30,
+ verify=True,
+ ),
+ ]
+ index_response.raise_for_status.assert_called_once_with()
+ show_response.raise_for_status.assert_called_once_with()
+
+
+ ("factory_value", "verify"),
+ [
+ (None, True),
+ ("false", True),
+ ("FALSE", True),
+ ("true", False),
+ ("TRUE", False),
+ ],
+)
+ "os.environ",
+ {
+ "CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token",
+ "CREWAI_DEPLOYMENT_INSTANCE_UUID": "deployment-instance-id",
+ },
+)
+@patch(
+ "crewai_tools.tools.crewai_platform_tools.integrations_client.requests.get"
+)
+def test_clipper_client_preserves_discovery_ssl_behavior(
+ mock_get: Mock,
+ factory_value: str | None,
+ verify: bool,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ if factory_value is None:
+ monkeypatch.delenv("CREWAI_FACTORY", raising=False)
+ else:
+ monkeypatch.setenv("CREWAI_FACTORY", factory_value)
+ response = Mock()
+ response.raise_for_status.return_value = None
+ response.json.return_value = {"data": []}
+ mock_get.return_value = response
+
+ ClipperClient().get_actions([ApplicationSelector.from_string("github")])
+
+ assert mock_get.call_args.kwargs["verify"] is verify
+
+
+ "os.environ",
+ {
+ "CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token",
+ "CREWAI_DEPLOYMENT_INSTANCE_UUID": "deployment-instance-id",
+ "CREWAI_FACTORY": "false",
+ "CREWAI_PLUS_URL": "https://platform.example.test/",
+ },
+)
+@patch(
+ "crewai_tools.tools.crewai_platform_tools.integrations_client.requests.post"
+)
+ ("arguments", "connection_id"),
+ [
+ ({}, UUID("550e8400-e29b-41d4-a716-446655440000")),
+ (
+ {
+ "filters": {"labels": ["urgent"], "enabled": True},
+ "values": [1, {"key": "value"}],
+ },
+ None,
+ ),
+ ],
+)
+def test_clipper_client_executes_action(
+ mock_post: Mock,
+ arguments: dict[str, Any],
+ connection_id: UUID | None,
+) -> None:
+ response = Mock(status_code=200)
+ response.json.return_value = {"data": {"output": {"issue": 42}}}
+ mock_post.return_value = response
+ tool = ToolInfo(
+ app="github",
+ action="create_issue",
+ connection_id=connection_id,
+ description="Create an issue",
+ parameters={},
+ )
+
+ result = ClipperClient().execute_action(tool, arguments)
+
+ assert result == ToolExecutionSuccess(output={"issue": 42})
+ expected_payload: dict[str, Any] = {"arguments": arguments}
+ if connection_id is not None:
+ expected_payload["connection_id"] = str(connection_id)
+ mock_post.assert_called_once_with(
+ "https://platform.example.test/clipper/v1/applications/github/tools/create_issue/execute",
+ headers={
+ "Authorization": "Bearer test_token",
+ "X-Crewai-Deployment-Instance-Id": "deployment-instance-id",
+ },
+ json=expected_payload,
+ timeout=60,
+ verify=True,
+ )
+
+
+ "os.environ",
+ {
+ "CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token",
+ "CREWAI_DEPLOYMENT_INSTANCE_UUID": "deployment-instance-id",
+ "CREWAI_FACTORY": "false",
+ "CREWAI_PLUS_URL": "https://platform.example.test/",
+ },
+)
+@patch(
+ "crewai_tools.tools.crewai_platform_tools.integrations_client.requests.post"
+)
+ ("status_code", "code", "detail", "retryable"),
+ [
+ (
+ 422,
+ "tool_execution_failed",
+ "The provider rejected the request.",
+ False,
+ ),
+ (
+ 503,
+ "service_unavailable",
+ "The tool provider is unavailable.",
+ True,
+ ),
+ ],
+)
+def test_clipper_client_normalizes_execution_failure(
+ mock_post: Mock,
+ status_code: int,
+ code: str,
+ detail: str,
+ retryable: bool,
+) -> None:
+ response = Mock(status_code=status_code)
+ response.json.return_value = {
+ "errors": [
+ {
+ "code": code,
+ "detail": detail,
+ }
+ ]
+ }
+ mock_post.return_value = response
+ tool = ToolInfo(
+ app="github",
+ action="create_issue",
+ connection_id=None,
+ description="Create an issue",
+ parameters={},
+ )
+
+ result = ClipperClient().execute_action(tool, {"title": "Contract test"})
+
+ assert result == ToolExecutionFailure(
+ message=detail,
+ code=code,
+ retryable=retryable,
+ )
+
+
+ "os.environ",
+ {"CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token"},
+ clear=True,
+)
+@patch(
+ "crewai_tools.tools.crewai_platform_tools.integrations_client.requests.post"
+)
+def test_clipper_client_normalizes_non_json_service_failure(
+ mock_post: Mock,
+) -> None:
+ response = Mock(status_code=503)
+ response.json.side_effect = JSONDecodeError("Expecting value", "", 0)
+ mock_post.return_value = response
+ tool = ToolInfo(
+ app="github",
+ action="create_issue",
+ connection_id=None,
+ description="Create an issue",
+ parameters={},
+ )
+
+ result = ClipperClient().execute_action(tool, {"title": "Contract test"})
+
+ assert result == ToolExecutionFailure(
+ message="Upstream API request failed with status 503.",
+ code="503",
+ retryable=True,
+ )
+
+
+ "os.environ",
+ {"CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token"},
+ clear=True,
+)
+@patch(
+ "crewai_tools.tools.crewai_platform_tools.integrations_client.requests.get"
+)
+def test_clipper_client_discovers_without_deployment_instance_uuid(
+ mock_get: Mock,
+) -> None:
+ response = Mock()
+ response.raise_for_status.return_value = None
+ response.json.return_value = {"data": []}
+ mock_get.return_value = response
+
+ assert ClipperClient().get_actions(
+ [ApplicationSelector.from_string("github")]
+ ) == []
+ assert mock_get.call_args.kwargs["headers"] == {
+ "Authorization": "Bearer test_token"
+ }
+
+
+ "os.environ",
+ {"CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token"},
+ clear=True,
+)
+@patch(
+ "crewai_tools.tools.crewai_platform_tools.integrations_client.requests.post"
+)
+def test_clipper_client_executes_without_deployment_instance_uuid(
+ mock_post: Mock,
+) -> None:
+ response = Mock(status_code=200)
+ response.json.return_value = {"data": {"output": {"issue": 42}}}
+ mock_post.return_value = response
+ tool = ToolInfo(
+ app="github",
+ action="create_issue",
+ connection_id=None,
+ description="Create an issue",
+ parameters={},
+ )
+
+ result = ClipperClient().execute_action(tool, {})
+
+ assert result == ToolExecutionSuccess(output={"issue": 42})
+ assert mock_post.call_args.kwargs["headers"] == {
+ "Authorization": "Bearer test_token"
+ }
+
+
+ "os.environ",
+ {"CREWAI_DEPLOYMENT_INSTANCE_UUID": "deployment-instance-id"},
+ clear=True,
+)
+@patch(
+ "crewai_tools.tools.crewai_platform_tools.integrations_client.requests.post"
+)
+def test_clipper_client_requires_platform_integration_token(
+ mock_post: Mock,
+) -> None:
+ tool = ToolInfo(
+ app="github",
+ action="create_issue",
+ connection_id=None,
+ description="Create an issue",
+ parameters={},
+ )
+
+ with pytest.raises(ValueError, match="CREWAI_PLATFORM_INTEGRATION_TOKEN"):
+ ClipperClient().execute_action(tool, {})
+
+ mock_post.assert_not_called()
+
+
@patch.dict("os.environ", {"CREWAI_PLATFORM_INTEGRATION_TOKEN": "test_token"})
@patch(
"crewai_tools.tools.crewai_platform_tools.integrations_client.requests.get"