Merge branch 'feat/strands-core-apify-tools' into feat/strands-search-crawling-actor-tools

Author: daveomri

README.md

@@ -99,11 +99,7 @@ Below is a comprehensive table of all available tools, how to use them with an a
 | Tool | Agent Usage | Use Case |
 |------|-------------|----------|
 | a2a_client | `provider = A2AClientToolProvider(known_agent_urls=["http://localhost:9000"]); agent = Agent(tools=provider.tools)` | Discover and communicate with A2A-compliant agents, send messages between agents |
-| apify_run_actor | `agent.tool.apify_run_actor(actor_id="apify/website-content-crawler", run_input={"startUrls": [{"url": "https://example.com"}]})` | Run any Apify Actor by ID with arbitrary input |
-| apify_get_dataset_items | `agent.tool.apify_get_dataset_items(dataset_id="abc123", limit=50)` | Fetch items from an Apify dataset |
-| apify_run_actor_and_get_dataset | `agent.tool.apify_run_actor_and_get_dataset(actor_id="apify/website-content-crawler", run_input={"startUrls": [{"url": "https://example.com"}]})` | Run an Actor and fetch its dataset results in one step |
-| apify_run_task | `agent.tool.apify_run_task(task_id="user/my-task")` | Run a saved Apify task by ID with optional input overrides |
-| apify_run_task_and_get_dataset | `agent.tool.apify_run_task_and_get_dataset(task_id="user/my-task", dataset_items_limit=50)` | Run a task and fetch its dataset results in one step |
+| apify_run_actor | `agent.tool.apify_run_actor(actor_id="apify/website-content-crawler", run_input={"startUrls": [{"url": "https://example.com"}]})` | Run any Apify Actor with arbitrary input |
 | apify_scrape_url | `agent.tool.apify_scrape_url(url="https://example.com")` | Scrape a URL and return its content as markdown |
 | apify_google_search_scraper | `agent.tool.apify_google_search_scraper(search_query="best AI frameworks")` | Search Google and return structured results |
 | apify_google_places_scraper | `agent.tool.apify_google_places_scraper(search_query="restaurants in Prague")` | Search Google Maps for businesses and places |

src/strands_tools/apify.py

@@ -90,7 +90,7 @@
 import json
 import logging
 import os
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Literal, Optional, get_args
 from urllib.parse import urlparse
 
 from rich.panel import Panel
@@ -110,13 +110,16 @@
 except ImportError:
     HAS_APIFY_CLIENT = False
 
-WEBSITE_CONTENT_CRAWLER = "apify/website-content-crawler"
+# Attribution header - lets Apify track usage originating from strands-agents (analytics only)
 TRACKING_HEADER = {"x-apify-integration-platform": "strands-agents"}
 ERROR_PANEL_TITLE = "[bold red]Apify Error[/bold red]"
 DEFAULT_TIMEOUT_SECS = 300
 DEFAULT_SCRAPE_TIMEOUT_SECS = 120
 DEFAULT_DATASET_ITEMS_LIMIT = 100
-VALID_CRAWLER_TYPES = ("playwright:adaptive", "playwright:firefox", "cheerio")
+
+WEBSITE_CONTENT_CRAWLER = "apify/website-content-crawler"
+CrawlerType = Literal["playwright:adaptive", "playwright:firefox", "cheerio"]
+WEBSITE_CONTENT_CRAWLER_TYPES = get_args(CrawlerType)
 
 
 # --- Helper functions ---
@@ -149,6 +152,8 @@ def _format_error(e: Exception) -> str:
                     "Rate limit exceeded. The Apify client retries automatically; "
                     "if this persists, reduce request frequency."
                 )
+            case None:
+                return f"Apify API error: {msg}"
             case _:
                 return f"Apify API error ({status_code}): {msg}"
     return str(e)
@@ -230,7 +235,7 @@ def run_actor(
             self._validate_positive(memory_mbytes, "memory_mbytes")
 
         call_kwargs: Dict[str, Any] = {
-            "run_input": run_input or {},
+            "run_input": run_input if run_input is not None else {},
             "timeout_secs": timeout_secs,
             "logger": None,  # Suppress verbose apify-client logging not useful to end users
         }
@@ -354,14 +359,14 @@ def scrape_url(
         self,
         url: str,
         timeout_secs: int = DEFAULT_SCRAPE_TIMEOUT_SECS,
-        crawler_type: str = "cheerio",
+        crawler_type: CrawlerType = "cheerio",
     ) -> str:
         """Scrape a single URL using Website Content Crawler and return markdown."""
         self._validate_url(url)
         self._validate_positive(timeout_secs, "timeout_secs")
-        if crawler_type not in VALID_CRAWLER_TYPES:
+        if crawler_type not in WEBSITE_CONTENT_CRAWLER_TYPES:
             raise ValueError(
-                f"Invalid crawler_type '{crawler_type}'. Must be one of: {', '.join(VALID_CRAWLER_TYPES)}."
+                f"Invalid crawler_type '{crawler_type}'. Must be one of: {', '.join(WEBSITE_CONTENT_CRAWLER_TYPES)}."
             )
 
         run_input: Dict[str, Any] = {
@@ -374,9 +379,13 @@ def scrape_url(
             timeout_secs=timeout_secs,
             logger=None,  # Suppress verbose apify-client logging not useful to end users
         )
+        if actor_run is None:
+            raise RuntimeError("Website Content Crawler returned no run data (possible wait timeout).")
         self._check_run_status(actor_run, "Website Content Crawler")
 
         dataset_id = actor_run.get("defaultDatasetId")
+        if not dataset_id:
+            raise RuntimeError("Website Content Crawler run has no default dataset.")
         result = self.client.dataset(dataset_id).list_items(limit=1)
         items = list(result.items)
 
@@ -640,7 +649,7 @@ def apify_run_task_and_get_dataset(
 def apify_scrape_url(
     url: str,
     timeout_secs: int = DEFAULT_SCRAPE_TIMEOUT_SECS,
-    crawler_type: str = "cheerio",
+    crawler_type: CrawlerType = "cheerio",
 ) -> Dict[str, Any]:
     """Scrape a single URL and return its content as markdown.
 

tests/test_apify.py

@@ -155,6 +155,17 @@ def test_run_actor_default_input(mock_apify_env, mock_apify_client):
     assert call_kwargs["run_input"] == {}
 
 
+def test_run_actor_explicit_empty_input(mock_apify_env, mock_apify_client):
+    """Actor run passes through an explicitly empty dict instead of treating it as falsy."""
+    empty_input: dict = {}
+    with patch("strands_tools.apify.ApifyClient", return_value=mock_apify_client):
+        result = apify_run_actor(actor_id="actor/my-scraper", run_input=empty_input)
+
+    assert result["status"] == "success"
+    call_kwargs = mock_apify_client.actor.return_value.call.call_args.kwargs
+    assert call_kwargs["run_input"] is empty_input
+
+
 def test_run_actor_with_memory(mock_apify_env, mock_apify_client):
     """Actor run passes memory_mbytes when provided."""
     with patch("strands_tools.apify.ApifyClient", return_value=mock_apify_client):
@@ -197,6 +208,17 @@ def test_run_actor_api_exception(mock_apify_env, mock_apify_client):
     assert "Connection failed" in result["content"][0]["text"]
 
 
+def test_run_actor_none_response(mock_apify_env, mock_apify_client):
+    """Actor run returns error dict when ActorClient.call() returns None."""
+    mock_apify_client.actor.return_value.call.return_value = None
+
+    with patch("strands_tools.apify.ApifyClient", return_value=mock_apify_client):
+        result = apify_run_actor(actor_id="actor/my-scraper")
+
+    assert result["status"] == "error"
+    assert "no run data" in result["content"][0]["text"]
+
+
 def test_run_actor_apify_api_error_401(mock_apify_env, mock_apify_client):
     """Actor run returns friendly message for 401 authentication errors."""
     error = _make_apify_api_error(401, "Unauthorized")
@@ -280,6 +302,18 @@ def test_run_actor_and_get_dataset_success(mock_apify_env, mock_apify_client):
     assert data["items"][0]["title"] == "Widget A"
 
 
+def test_run_actor_and_get_dataset_no_dataset_id(mock_apify_env, mock_apify_client):
+    """Combined tool returns error when the Actor run has no default dataset."""
+    run_no_dataset = {**MOCK_ACTOR_RUN, "defaultDatasetId": None}
+    mock_apify_client.actor.return_value.call.return_value = run_no_dataset
+
+    with patch("strands_tools.apify.ApifyClient", return_value=mock_apify_client):
+        result = apify_run_actor_and_get_dataset(actor_id="actor/my-scraper")
+
+    assert result["status"] == "error"
+    assert "no default dataset" in result["content"][0]["text"]
+
+
 def test_run_actor_and_get_dataset_actor_failure(mock_apify_env, mock_apify_client):
     """Combined tool returns error dict when the Actor fails."""
     mock_apify_client.actor.return_value.call.return_value = MOCK_FAILED_RUN
@@ -379,6 +413,18 @@ def test_run_task_and_get_dataset_success(mock_apify_env, mock_apify_client):
     assert data["items"][0]["title"] == "Widget A"
 
 
+def test_run_task_and_get_dataset_no_dataset_id(mock_apify_env, mock_apify_client):
+    """Combined task tool returns error when the task run has no default dataset."""
+    run_no_dataset = {**MOCK_ACTOR_RUN, "defaultDatasetId": None}
+    mock_apify_client.task.return_value.call.return_value = run_no_dataset
+
+    with patch("strands_tools.apify.ApifyClient", return_value=mock_apify_client):
+        result = apify_run_task_and_get_dataset(task_id="user~my-task")
+
+    assert result["status"] == "error"
+    assert "no default dataset" in result["content"][0]["text"]
+
+
 def test_run_task_and_get_dataset_task_failure(mock_apify_env, mock_apify_client):
     """Combined task tool returns error dict when the task fails."""
     mock_apify_client.task.return_value.call.return_value = MOCK_FAILED_RUN
@@ -407,6 +453,29 @@ def test_scrape_url_success(mock_apify_env, mock_apify_client):
     mock_apify_client.actor.assert_called_once_with("apify/website-content-crawler")
 
 
+def test_scrape_url_none_response(mock_apify_env, mock_apify_client):
+    """Scrape URL returns error dict when ActorClient.call() returns None."""
+    mock_apify_client.actor.return_value.call.return_value = None
+
+    with patch("strands_tools.apify.ApifyClient", return_value=mock_apify_client):
+        result = apify_scrape_url(url="https://example.com")
+
+    assert result["status"] == "error"
+    assert "no run data" in result["content"][0]["text"]
+
+
+def test_scrape_url_no_dataset_id(mock_apify_env, mock_apify_client):
+    """Scrape URL returns error when the crawler run has no default dataset."""
+    run_no_dataset = {**MOCK_ACTOR_RUN, "defaultDatasetId": None}
+    mock_apify_client.actor.return_value.call.return_value = run_no_dataset
+
+    with patch("strands_tools.apify.ApifyClient", return_value=mock_apify_client):
+        result = apify_scrape_url(url="https://example.com")
+
+    assert result["status"] == "error"
+    assert "no default dataset" in result["content"][0]["text"]
+
+
 def test_scrape_url_no_content(mock_apify_env, mock_apify_client):
     """Scrape URL returns error dict when no content is returned."""
     mock_list_result = MagicMock()