Merge pull request #228 from MQ37/feat/apify

feat: apify actors

src/crewai_tools/__init__.py

@@ -1,5 +1,6 @@
 from .tools import (
     AIMindTool,
+    ApifyActorsTool,
     BraveSearchTool,
     BrowserbaseLoadTool,
     CodeDocsSearchTool,

src/crewai_tools/tools/__init__.py

@@ -1,4 +1,5 @@
 from .ai_mind_tool.ai_mind_tool import AIMindTool
+from .apify_actors_tool.apify_actors_tool import ApifyActorsTool
 from .brave_search_tool.brave_search_tool import BraveSearchTool
 from .browserbase_load_tool.browserbase_load_tool import BrowserbaseLoadTool
 from .code_docs_search_tool.code_docs_search_tool import CodeDocsSearchTool

src/crewai_tools/tools/apify_actors_tool/README.md

@@ -0,0 +1,96 @@
+# ApifyActorsTool
+
+Integrate [Apify Actors](https://apify.com/actors) into your CrewAI workflows.
+
+## Description
+
+The `ApifyActorsTool` connects [Apify Actors](https://apify.com/actors), cloud-based programs for web scraping and automation, to your CrewAI workflows.
+Use any of the 4,000+ Actors on [Apify Store](https://apify.com/store) for use cases such as extracting data from social media, search engines, online maps, e-commerce sites, travel portals, or general websites.
+
+For details, see the [Apify CrewAI integration](https://docs.apify.com/platform/integrations/crewai) in Apify documentation.
+
+## Installation
+
+To use `ApifyActorsTool`, install the necessary packages and set up your Apify API token. Follow the [Apify API documentation](https://docs.apify.com/platform/integrations/api) for steps to obtain the token.
+
+### Steps
+
+1. **Install dependencies**
+   Install `crewai[tools]` and `langchain-apify`:
+   ```bash
+   pip install 'crewai[tools]' langchain-apify
+   ```
+
+2. **Set your API token**
+   Export the token as an environment variable:
+   ```bash
+   export APIFY_API_TOKEN='your-api-token-here'
+   ```
+
+## Usage example
+
+Use the `ApifyActorsTool` manually to run the [RAG Web Browser Actor](https://apify.com/apify/rag-web-browser) to perform a web search:
+
+```python
+from crewai_tools import ApifyActorsTool
+
+# Initialize the tool with an Apify Actor
+tool = ApifyActorsTool(actor_name="apify/rag-web-browser")
+
+# Run the tool with input parameters
+results = tool.run(run_input={"query": "What is CrewAI?", "maxResults": 5})
+
+# Process the results
+for result in results:
+    print(f"URL: {result['metadata']['url']}")
+    print(f"Content: {result.get('markdown', 'N/A')[:100]}...")
+```
+
+### Expected output
+
+Here is the output from running the code above:
+
+```text
+URL: https://www.example.com/crewai-intro
+Content: CrewAI is a framework for building AI-powered workflows...
+URL: https://docs.crewai.com/
+Content: Official documentation for CrewAI...
+```
+
+The `ApifyActorsTool` automatically fetches the Actor definition and input schema from Apify using the provided `actor_name` and then constructs the tool description and argument schema. This means you need to specify only a valid `actor_name`, and the tool handles the rest when used with agents—no need to specify the `run_input`. Here's how it works:
+
+```python
+from crewai import Agent
+from crewai_tools import ApifyActorsTool
+
+rag_browser = ApifyActorsTool(actor_name="apify/rag-web-browser")
+
+agent = Agent(
+    role="Research Analyst",
+    goal="Find and summarize information about specific topics",
+    backstory="You are an experienced researcher with attention to detail",
+    tools=[rag_browser],
+)
+```
+
+You can run other Actors from [Apify Store](https://apify.com/store) simply by changing the `actor_name` and, when using it manually, adjusting the `run_input` based on the Actor input schema.
+
+For an example of usage with agents, see the [CrewAI Actor template](https://apify.com/templates/python-crewai).
+
+## Configuration
+
+The `ApifyActorsTool` requires these inputs to work:
+
+- **`actor_name`**
+  The ID of the Apify Actor to run, e.g., `"apify/rag-web-browser"`. Browse all Actors on [Apify Store](https://apify.com/store).
+- **`run_input`**
+  A dictionary of input parameters for the Actor when running the tool manually.
+  - For example, for the `apify/rag-web-browser` Actor: `{"query": "search term", "maxResults": 5}`
+  - See the Actor's [input schema](https://apify.com/apify/rag-web-browser/input-schema) for the list of input parameters.
+
+## Resources
+
+- **[Apify](https://apify.com/)**: Explore the Apify platform.
+- **[How to build an AI agent on Apify](https://blog.apify.com/how-to-build-an-ai-agent/)** - A complete step-by-step guide to creating, publishing, and monetizing AI agents on the Apify platform.
+- **[RAG Web Browser Actor](https://apify.com/apify/rag-web-browser)**: A popular Actor for web search for LLMs.
+- **[CrewAI Integration Guide](https://docs.apify.com/platform/integrations/crewai)**: Follow the official guide for integrating Apify and CrewAI.

src/crewai_tools/tools/apify_actors_tool/apify_actors_tool.py

@@ -0,0 +1,92 @@
+from crewai.tools import BaseTool
+from pydantic import Field
+from typing import TYPE_CHECKING, Any, Dict, List
+import os
+
+if TYPE_CHECKING:
+    from langchain_apify import ApifyActorsTool as _ApifyActorsTool
+
+class ApifyActorsTool(BaseTool):
+    """Tool that runs Apify Actors.
+
+       To use, you should have the environment variable `APIFY_API_TOKEN` set
+       with your API key.
+
+       For details, see https://docs.apify.com/platform/integrations/crewai
+
+       Args:
+           actor_name (str): The name of the Apify Actor to run.
+           *args: Variable length argument list passed to BaseTool.
+           **kwargs: Arbitrary keyword arguments passed to BaseTool.
+
+       Returns:
+           List[Dict[str, Any]]: Results from the Actor execution.
+
+       Raises:
+           ValueError: If `APIFY_API_TOKEN` is not set or if the tool is not initialized.
+           ImportError: If `langchain_apify` package is not installed.
+
+       Example:
+           .. code-block:: python
+            from crewai_tools import ApifyActorsTool
+
+            tool = ApifyActorsTool(actor_name="apify/rag-web-browser")
+
+            results = tool.run(run_input={"query": "What is CrewAI?", "maxResults": 5})
+            for result in results:
+                print(f"URL: {result['metadata']['url']}")
+                print(f"Content: {result.get('markdown', 'N/A')[:100]}...")
+    """
+    actor_tool: '_ApifyActorsTool' = Field(description="Apify Actor Tool")
+
+    def __init__(
+        self,
+        actor_name: str,
+        *args: Any,
+        **kwargs: Any
+    ) -> None:
+        if not os.environ.get("APIFY_API_TOKEN"):
+            msg = (
+                "APIFY_API_TOKEN environment variable is not set. "
+                "Please set it to your API key, to learn how to get it, "
+                "see https://docs.apify.com/platform/integrations/api"
+            )
+            raise ValueError(msg)
+
+        try:
+            from langchain_apify import ApifyActorsTool as _ApifyActorsTool
+        except ImportError:
+            raise ImportError(
+                "Could not import langchain_apify python package. "
+                "Please install it with `pip install langchain-apify` or `uv add langchain-apify`."
+            )
+        actor_tool = _ApifyActorsTool(actor_name)
+
+        kwargs.update(
+            {
+                "name": actor_tool.name,
+                "description": actor_tool.description,
+                "args_schema": actor_tool.args_schema,
+                "actor_tool": actor_tool,
+            }
+        )
+        super().__init__(*args, **kwargs)
+
+    def _run(self, run_input: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """Run the Actor tool with the given input.
+
+        Returns:
+            List[Dict[str, Any]]: Results from the Actor execution.
+
+        Raises:
+            ValueError: If 'actor_tool' is not initialized.
+        """
+        try:
+            return self.actor_tool._run(run_input)
+        except Exception as e:
+            msg = (
+                f'Failed to run ApifyActorsTool {self.name}. '
+                'Please check your Apify account Actor run logs for more details.'
+                f'Error: {e}'
+            )
+            raise RuntimeError(msg) from e