Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
python-sdk: Update Agent Client (#2579)
Abimael Martelle4eb79f16cb8
diff --git a/apps/python-sdk/firecrawl/__init__.py b/apps/python-sdk/firecrawl/__init__.pyindex 505db7ca0..18123cf7b 100644--- a/apps/python-sdk/firecrawl/__init__.py+++ b/apps/python-sdk/firecrawl/__init__.py@@ -17,7 +17,7 @@ from .v1 import (V1ChangeTrackingOptions,)-__version__ = "4.11.3"+__version__ = "4.12.0"# Define the logger for the Firecrawl projectlogger: logging.Logger = logging.getLogger("firecrawl")diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_agent.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_agent.pynew file mode 100644index 000000000..b40a4b95f--- /dev/null+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_agent.py@@ -0,0 +1,367 @@+"""+Unit tests for agent methods with mocked HTTP client.+"""++import pytest+import time+from unittest.mock import Mock, patch+from pydantic import BaseModel, Field+from typing import List, Optional++from firecrawl.v2.methods.agent import (+ start_agent,+ agent,+ get_agent_status,+ cancel_agent,+ wait_agent+)+from firecrawl.v2.types import AgentResponse+from firecrawl.v2.utils.error_handler import BadRequestError+++class TestAgentMethods:+ """Unit tests for agent methods with mocked HTTP client."""++ def setup_method(self):+ """Set up test fixtures."""+ self.mock_client = Mock()+ self.job_id = "test-agent-123"++ # Sample agent response+ self.sample_response = {+ "success": True,+ "id": self.job_id,+ "status": "completed",+ "data": {+ "founders": [+ {"name": "John Doe", "role": "CEO"},+ {"name": "Jane Smith", "role": "CTO"}+ ]+ },+ "creditsUsed": 10,+ "expiresAt": "2024-01-01T00:00:00Z"+ }++ def test_start_agent_basic(self):+ """Test starting an agent job with basic parameters."""+ mock_response = Mock()+ mock_response.ok = True+ mock_response.json.return_value = {+ "success": True,+ "id": self.job_id,+ "status": "processing"+ }++ self.mock_client.post.return_value = mock_response++ result = start_agent(+ self.mock_client,+ None,+ prompt="Find information about Firecrawl"+ )++ # Check that post was called with correct endpoint+ self.mock_client.post.assert_called_once()+ call_args = self.mock_client.post.call_args+ assert call_args[0][0] == "/v2/agent"++ # Check request body (second positional argument)+ body = call_args[0][1]+ assert body["prompt"] == "Find information about Firecrawl"+ assert "urls" not in body++ # Check result+ assert isinstance(result, AgentResponse)+ assert result.id == self.job_id+ assert result.status == "processing"++ def test_start_agent_with_urls(self):+ """Test starting an agent job with URLs."""+ mock_response = Mock()+ mock_response.ok = True+ mock_response.json.return_value = {+ "success": True,+ "id": self.job_id,+ "status": "processing"+ }++ self.mock_client.post.return_value = mock_response++ urls = ["https://example.com", "https://test.com"]+ result = start_agent(+ self.mock_client,+ urls,+ prompt="Extract data"+ )++ call_args = self.mock_client.post.call_args+ body = call_args[0][1]+ assert body["urls"] == urls++ def test_start_agent_with_dict_schema(self):+ """Test starting an agent job with dict schema."""+ mock_response = Mock()+ mock_response.ok = True+ mock_response.json.return_value = {+ "success": True,+ "id": self.job_id,+ "status": "processing"+ }++ self.mock_client.post.return_value = mock_response++ schema = {+ "type": "object",+ "properties": {+ "name": {"type": "string"}+ }+ }++ result = start_agent(+ self.mock_client,+ None,+ prompt="Extract data",+ schema=schema+ )++ call_args = self.mock_client.post.call_args+ body = call_args[0][1]+ assert body["schema"] == schema++ def test_start_agent_with_pydantic_schema(self):+ """Test starting an agent job with Pydantic schema."""+ mock_response = Mock()+ mock_response.ok = True+ mock_response.json.return_value = {+ "success": True,+ "id": self.job_id,+ "status": "processing"+ }++ self.mock_client.post.return_value = mock_response++ class Founder(BaseModel):+ name: str = Field(description="Full name")+ role: Optional[str] = Field(None, description="Role")++ class FoundersSchema(BaseModel):+ founders: List[Founder] = Field(description="List of founders")++ result = start_agent(+ self.mock_client,+ None,+ prompt="Find founders",+ schema=FoundersSchema+ )++ call_args = self.mock_client.post.call_args+ body = call_args[0][1]+ assert "schema" in body+ assert body["schema"]["type"] == "object"+ assert "founders" in body["schema"]["properties"]++ def test_start_agent_with_all_params(self):+ """Test starting an agent job with all parameters."""+ mock_response = Mock()+ mock_response.ok = True+ mock_response.json.return_value = {+ "success": True,+ "id": self.job_id,+ "status": "processing"+ }++ self.mock_client.post.return_value = mock_response++ schema = {"type": "object"}+ urls = ["https://example.com"]++ result = start_agent(+ self.mock_client,+ urls,+ prompt="Complete test",+ schema=schema,+ integration="test-integration",+ max_credits=50,+ strict_constrain_to_urls=True+ )++ call_args = self.mock_client.post.call_args+ body = call_args[0][1]+ assert body["prompt"] == "Complete test"+ assert body["urls"] == urls+ assert body["schema"] == schema+ assert body["integration"] == "test-integration"+ assert body["maxCredits"] == 50+ assert body["strictConstrainToURLs"] is True++ def test_get_agent_status(self):+ """Test getting agent status."""+ mock_response = Mock()+ mock_response.ok = True+ mock_response.json.return_value = self.sample_response++ self.mock_client.get.return_value = mock_response++ result = get_agent_status(self.mock_client, self.job_id)++ # Check that get was called with correct endpoint+ self.mock_client.get.assert_called_once_with(f"/v2/agent/{self.job_id}")++ # Check result+ assert isinstance(result, AgentResponse)+ assert result.id == self.job_id+ assert result.status == "completed"++ def test_cancel_agent(self):+ """Test canceling an agent job."""+ mock_response = Mock()+ mock_response.ok = True+ mock_response.json.return_value = {"success": True}++ self.mock_client.delete.return_value = mock_response++ result = cancel_agent(self.mock_client, self.job_id)++ # Check that delete was called with correct endpoint+ self.mock_client.delete.assert_called_once_with(f"/v2/agent/{self.job_id}")++ # Check result+ assert result is True++ @patch('time.sleep')+ def test_wait_agent_completed(self, mock_sleep):+ """Test waiting for agent to complete."""+ # First call returns processing, second returns completed+ mock_response_processing = Mock()+ mock_response_processing.ok = True+ mock_response_processing.json.return_value = {+ "success": True,+ "id": self.job_id,+ "status": "processing"+ }++ mock_response_completed = Mock()+ mock_response_completed.ok = True+ mock_response_completed.json.return_value = self.sample_response++ self.mock_client.get.side_effect = [+ mock_response_processing,+ mock_response_completed+ ]++ result = wait_agent(self.mock_client, self.job_id, poll_interval=1)++ # Should have called get twice+ assert self.mock_client.get.call_count == 2+ assert result.status == "completed"+ assert mock_sleep.call_count == 1++ @patch('time.sleep')+ def test_wait_agent_timeout(self, mock_sleep):+ """Test waiting for agent with timeout."""+ mock_response = Mock()+ mock_response.ok = True+ mock_response.json.return_value = {+ "success": True,+ "id": self.job_id,+ "status": "processing"+ }++ self.mock_client.get.return_value = mock_response++ # Mock time.time to simulate timeout+ with patch('time.time', side_effect=[0, 0, 5]): # Start at 0, timeout at 5+ result = wait_agent(+ self.mock_client,+ self.job_id,+ poll_interval=1,+ timeout=3 # Timeout after 3 seconds+ )++ # Should return processing status due to timeout+ assert result.status == "processing"++ @patch('time.sleep')+ def test_agent_complete_flow(self, mock_sleep):+ """Test the complete agent flow (start + wait)."""+ # Mock start_agent response+ mock_start_response = Mock()+ mock_start_response.ok = True+ mock_start_response.json.return_value = {+ "success": True,+ "id": self.job_id,+ "status": "processing"+ }++ # Mock get_agent_status responses+ mock_status_response = Mock()+ mock_status_response.ok = True+ mock_status_response.json.return_value = self.sample_response++ self.mock_client.post.return_value = mock_start_response+ self.mock_client.get.return_value = mock_status_response++ result = agent(+ self.mock_client,+ None,+ prompt="Find information",+ poll_interval=1+ )++ # Should have called post once and get once+ assert self.mock_client.post.call_count == 1+ assert self.mock_client.get.call_count == 1++ # Check result+ assert isinstance(result, AgentResponse)+ assert result.status == "completed"+ assert result.data is not None++ def test_agent_immediate_completion(self):+ """Test agent that completes immediately (no job ID)."""+ mock_response = Mock()+ mock_response.ok = True+ mock_response.json.return_value = {+ "success": True,+ "status": "completed",+ "data": {"result": "done"}+ }++ self.mock_client.post.return_value = mock_response++ result = agent(+ self.mock_client,+ None,+ prompt="Quick task"+ )++ # Should only call post, not get+ assert self.mock_client.post.call_count == 1+ assert self.mock_client.get.call_count == 0+ assert result.status == "completed"++ def test_start_agent_error_handling(self):+ """Test error handling in start_agent."""+ mock_response = Mock()+ mock_response.ok = False+ mock_response.status_code = 400+ mock_response.text = "Bad Request"+ # Mock response.json() to return error details+ mock_response.json.return_value = {+ "error": "Invalid request",+ "details": "Bad Request"+ }++ self.mock_client.post.return_value = mock_response++ with pytest.raises(BadRequestError) as exc_info:+ start_agent(+ self.mock_client,+ None,+ prompt="Test prompt"+ )++ # Verify the exception has the correct status code+ assert exc_info.value.status_code == 400+ assert "agent" in str(exc_info.value).lower()+diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_agent_request_preparation.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_agent_request_preparation.pynew file mode 100644index 000000000..7cb30d195--- /dev/null+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_agent_request_preparation.py@@ -0,0 +1,226 @@+"""+Unit tests for agent request preparation.+"""++import pytest+from pydantic import BaseModel, Field+from typing import List, Optional++from firecrawl.v2.methods.agent import _prepare_agent_request+++class TestAgentRequestPreparation:+ """Unit tests for agent request preparation."""++ def test_basic_request_preparation(self):+ """Test basic request preparation with minimal fields."""+ data = _prepare_agent_request(+ None,+ prompt="Find information about Firecrawl"+ )++ assert data["prompt"] == "Find information about Firecrawl"+ assert "urls" not in data+ assert "schema" not in data++ def test_request_with_urls(self):+ """Test request preparation with URLs."""+ urls = ["https://example.com", "https://test.com"]+ data = _prepare_agent_request(+ urls,+ prompt="Extract data from these pages"+ )++ assert data["prompt"] == "Extract data from these pages"+ assert data["urls"] == urls++ def test_request_with_dict_schema(self):+ """Test request preparation with dict schema."""+ schema = {+ "type": "object",+ "properties": {+ "name": {"type": "string"},+ "age": {"type": "integer"}+ }+ }+ data = _prepare_agent_request(+ None,+ prompt="Extract person data",+ schema=schema+ )++ assert data["prompt"] == "Extract person data"+ assert data["schema"] == schema++ def test_request_with_pydantic_schema(self):+ """Test request preparation with Pydantic BaseModel schema."""+ class Person(BaseModel):+ name: str = Field(description="Person's name")+ age: Optional[int] = Field(None, description="Person's age")++ data = _prepare_agent_request(+ None,+ prompt="Extract person data",+ schema=Person+ )++ assert data["prompt"] == "Extract person data"+ assert "schema" in data+ assert data["schema"]["type"] == "object"+ assert "properties" in data["schema"]+ assert "name" in data["schema"]["properties"]+ assert "age" in data["schema"]["properties"]++ def test_request_with_pydantic_schema_instance(self):+ """Test request preparation with Pydantic model instance."""+ class Person(BaseModel):+ name: str = Field(description="Person's name")+ age: Optional[int] = Field(None, description="Person's age")++ person_instance = Person(name="John", age=30)+ data = _prepare_agent_request(+ None,+ prompt="Extract person data",+ schema=person_instance+ )++ assert data["prompt"] == "Extract person data"+ assert "schema" in data+ # Should use the class schema, not the instance data+ assert data["schema"]["type"] == "object"++ def test_request_with_nested_pydantic_schema(self):+ """Test request preparation with nested Pydantic schema."""+ class Founder(BaseModel):+ name: str = Field(description="Full name of the founder")+ role: Optional[str] = Field(None, description="Role or position")++ class FoundersSchema(BaseModel):+ founders: List[Founder] = Field(description="List of founders")++ data = _prepare_agent_request(+ None,+ prompt="Find the founders",+ schema=FoundersSchema+ )++ assert data["prompt"] == "Find the founders"+ assert "schema" in data+ assert data["schema"]["type"] == "object"+ assert "founders" in data["schema"]["properties"]+ assert data["schema"]["properties"]["founders"]["type"] == "array"++ def test_request_with_integration(self):+ """Test request preparation with integration tag."""+ data = _prepare_agent_request(+ None,+ prompt="Test prompt",+ integration=" test-integration "+ )++ assert data["prompt"] == "Test prompt"+ assert data["integration"] == "test-integration"++ def test_request_with_max_credits(self):+ """Test request preparation with max credits."""+ data = _prepare_agent_request(+ None,+ prompt="Test prompt",+ max_credits=100+ )++ assert data["prompt"] == "Test prompt"+ assert data["maxCredits"] == 100++ def test_request_with_strict_constrain_to_urls(self):+ """Test request preparation with strict_constrain_to_urls."""+ data = _prepare_agent_request(+ ["https://example.com"],+ prompt="Test prompt",+ strict_constrain_to_urls=True+ )++ assert data["prompt"] == "Test prompt"+ assert data["strictConstrainToURLs"] is True++ def test_request_all_fields(self):+ """Test request preparation with all fields."""+ schema = {+ "type": "object",+ "properties": {"test": {"type": "string"}}+ }+ urls = ["https://example.com"]++ data = _prepare_agent_request(+ urls,+ prompt="Complete test",+ schema=schema,+ integration="test-integration",+ max_credits=50,+ strict_constrain_to_urls=True+ )++ assert data["prompt"] == "Complete test"+ assert data["urls"] == urls+ assert data["schema"] == schema+ assert data["integration"] == "test-integration"+ assert data["maxCredits"] == 50+ assert data["strictConstrainToURLs"] is True++ def test_request_with_empty_integration(self):+ """Test that empty integration is not included."""+ data = _prepare_agent_request(+ None,+ prompt="Test prompt",+ integration=" "+ )++ assert "integration" not in data++ def test_request_with_zero_max_credits(self):+ """Test that zero max_credits is not included."""+ data = _prepare_agent_request(+ None,+ prompt="Test prompt",+ max_credits=0+ )++ assert "maxCredits" not in data++ def test_request_with_false_strict_constrain(self):+ """Test that False strict_constrain_to_urls is not included."""+ data = _prepare_agent_request(+ None,+ prompt="Test prompt",+ strict_constrain_to_urls=False+ )++ assert "strictConstrainToURLs" not in data++ def test_request_with_invalid_schema_type_string(self):+ """Test that invalid schema types raise ValueError."""+ with pytest.raises(ValueError, match="Invalid schema type"):+ _prepare_agent_request(+ None,+ prompt="Test prompt",+ schema="invalid_string_schema"+ )++ def test_request_with_invalid_schema_type_int(self):+ """Test that invalid schema types raise ValueError."""+ with pytest.raises(ValueError, match="Invalid schema type"):+ _prepare_agent_request(+ None,+ prompt="Test prompt",+ schema=123+ )++ def test_request_with_invalid_schema_type_list(self):+ """Test that invalid schema types raise ValueError."""+ with pytest.raises(ValueError, match="Invalid schema type"):+ _prepare_agent_request(+ None,+ prompt="Test prompt",+ schema=["not", "a", "valid", "schema"]+ )+diff --git a/apps/python-sdk/firecrawl/client.py b/apps/python-sdk/firecrawl/client.pyindex 30946e947..db5c1c0a9 100644--- a/apps/python-sdk/firecrawl/client.py+++ b/apps/python-sdk/firecrawl/client.py@@ -71,6 +71,11 @@ class V2Proxy:self.start_extract = client_instance.start_extractself.get_extract_status = client_instance.get_extract_status+ self.agent = client_instance.agent+ self.start_agent = client_instance.start_agent+ self.get_agent_status = client_instance.get_agent_status+ self.cancel_agent = client_instance.cancel_agent+self.start_batch_scrape = client_instance.start_batch_scrapeself.get_batch_scrape_status = client_instance.get_batch_scrape_statusself.cancel_batch_scrape = client_instance.cancel_batch_scrape@@ -132,6 +137,11 @@ class AsyncV2Proxy:self.start_extract = client_instance.start_extractself.get_extract_status = client_instance.get_extract_status+ self.agent = client_instance.agent+ self.start_agent = client_instance.start_agent+ self.get_agent_status = client_instance.get_agent_status+ self.cancel_agent = client_instance.cancel_agent+self.start_batch_scrape = client_instance.start_batch_scrapeself.get_batch_scrape_status = client_instance.get_batch_scrape_statusself.cancel_batch_scrape = client_instance.cancel_batch_scrape@@ -203,6 +213,11 @@ class Firecrawl:self.get_extract_status = self._v2_client.get_extract_statusself.extract = self._v2_client.extract+ self.start_agent = self._v2_client.start_agent+ self.get_agent_status = self._v2_client.get_agent_status+ self.cancel_agent = self._v2_client.cancel_agent+ self.agent = self._v2_client.agent+self.get_concurrency = self._v2_client.get_concurrencyself.get_credit_usage = self._v2_client.get_credit_usageself.get_token_usage = self._v2_client.get_token_usage@@ -249,6 +264,11 @@ class AsyncFirecrawl:self.get_extract_status = self._v2_client.get_extract_statusself.extract = self._v2_client.extract+ self.start_agent = self._v2_client.start_agent+ self.get_agent_status = self._v2_client.get_agent_status+ self.cancel_agent = self._v2_client.cancel_agent+ self.agent = self._v2_client.agent+self.get_concurrency = self._v2_client.get_concurrencyself.get_credit_usage = self._v2_client.get_credit_usageself.get_token_usage = self._v2_client.get_token_usagediff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.pyindex 5beb8fb5a..7b8c35b30 100644--- a/apps/python-sdk/firecrawl/v2/client.py+++ b/apps/python-sdk/firecrawl/v2/client.py@@ -760,7 +760,7 @@ class FirecrawlClient:urls: Optional[List[str]] = None,*,prompt: str,- schema: Optional[Dict[str, Any]] = None,+ schema: Optional[Any] = None,integration: Optional[str] = None,max_credits: Optional[int] = None,strict_constrain_to_urls: Optional[bool] = None,@@ -770,7 +770,7 @@ class FirecrawlClient:Args:urls: URLs to process (optional)prompt: Natural-language instruction for the agent- schema: Target JSON schema for the output+ schema: Target JSON schema for the output (dict or Pydantic BaseModel)integration: Integration tag/namemax_credits: Maximum credits to use (optional)Returns:@@ -791,7 +791,7 @@ class FirecrawlClient:urls: Optional[List[str]] = None,*,prompt: str,- schema: Optional[Dict[str, Any]] = None,+ schema: Optional[Any] = None,integration: Optional[str] = None,poll_interval: int = 2,timeout: Optional[int] = None,@@ -803,7 +803,7 @@ class FirecrawlClient:Args:urls: URLs to process (optional)prompt: Natural-language instruction for the agent- schema: Target JSON schema for the output+ schema: Target JSON schema for the output (dict or Pydantic BaseModel)integration: Integration tag/namepoll_interval: Seconds between status checkstimeout: Maximum seconds to wait (None for no timeout)diff --git a/apps/python-sdk/firecrawl/v2/client_async.py b/apps/python-sdk/firecrawl/v2/client_async.pyindex 00e1d8e89..320a9ab96 100644--- a/apps/python-sdk/firecrawl/v2/client_async.py+++ b/apps/python-sdk/firecrawl/v2/client_async.py@@ -317,7 +317,7 @@ class AsyncFirecrawlClient:urls: Optional[List[str]] = None,*,prompt: str,- schema: Optional[Dict[str, Any]] = None,+ schema: Optional[Any] = None,integration: Optional[str] = None,poll_interval: int = 2,timeout: Optional[int] = None,@@ -344,7 +344,7 @@ class AsyncFirecrawlClient:urls: Optional[List[str]] = None,*,prompt: str,- schema: Optional[Dict[str, Any]] = None,+ schema: Optional[Any] = None,integration: Optional[str] = None,max_credits: Optional[int] = None,strict_constrain_to_urls: Optional[bool] = None,diff --git a/apps/python-sdk/firecrawl/v2/methods/agent.py b/apps/python-sdk/firecrawl/v2/methods/agent.pyindex fe7098a2d..e168fb1ba 100644--- a/apps/python-sdk/firecrawl/v2/methods/agent.py+++ b/apps/python-sdk/firecrawl/v2/methods/agent.py@@ -4,13 +4,14 @@ import timefrom ..types import AgentResponsefrom ..utils.http_client import HttpClientfrom ..utils.error_handler import handle_response_error+from ..utils.validation import _normalize_schemadef _prepare_agent_request(urls: Optional[List[str]],*,prompt: str,- schema: Optional[Dict[str, Any]] = None,+ schema: Optional[Any] = None,integration: Optional[str] = None,max_credits: Optional[int] = None,strict_constrain_to_urls: Optional[bool] = None,@@ -20,7 +21,14 @@ def _prepare_agent_request(body["urls"] = urlsbody["prompt"] = promptif schema is not None:- body["schema"] = schema+ normalized_schema = _normalize_schema(schema)+ if normalized_schema is not None:+ body["schema"] = normalized_schema+ else:+ raise ValueError(+ f"Invalid schema type: {type(schema).__name__}. "+ "Schema must be a dict, Pydantic BaseModel class, or Pydantic model instance."+ )if integration is not None and str(integration).strip():body["integration"] = str(integration).strip()if max_credits is not None and max_credits > 0:@@ -44,7 +52,7 @@ def start_agent(urls: Optional[List[str]],*,prompt: str,- schema: Optional[Dict[str, Any]] = None,+ schema: Optional[Any] = None,integration: Optional[str] = None,max_credits: Optional[int] = None,strict_constrain_to_urls: Optional[bool] = None,@@ -94,7 +102,7 @@ def agent(urls: Optional[List[str]],*,prompt: str,- schema: Optional[Dict[str, Any]] = None,+ schema: Optional[Any] = None,integration: Optional[str] = None,poll_interval: int = 2,timeout: Optional[int] = None,diff --git a/apps/python-sdk/firecrawl/v2/methods/aio/agent.py b/apps/python-sdk/firecrawl/v2/methods/aio/agent.pyindex 7b3b670be..09fb7f626 100644--- a/apps/python-sdk/firecrawl/v2/methods/aio/agent.py+++ b/apps/python-sdk/firecrawl/v2/methods/aio/agent.py@@ -3,13 +3,14 @@ import asynciofrom ...types import AgentResponsefrom ...utils.http_client_async import AsyncHttpClient+from ...utils.validation import _normalize_schemadef _prepare_agent_request(urls: Optional[List[str]],*,prompt: str,- schema: Optional[Dict[str, Any]] = None,+ schema: Optional[Any] = None,integration: Optional[str] = None,max_credits: Optional[int] = None,strict_constrain_to_urls: Optional[bool] = None,@@ -19,11 +20,20 @@ def _prepare_agent_request(body["urls"] = urlsbody["prompt"] = promptif schema is not None:- body["schema"] = schema+ normalized_schema = _normalize_schema(schema)+ if normalized_schema is not None:+ body["schema"] = normalized_schema+ else:+ raise ValueError(+ f"Invalid schema type: {type(schema).__name__}. "+ "Schema must be a dict, Pydantic BaseModel class, or Pydantic model instance."+ )if integration is not None and str(integration).strip():body["integration"] = str(integration).strip()if max_credits is not None and max_credits > 0:body["maxCredits"] = max_credits+ if strict_constrain_to_urls is not None and strict_constrain_to_urls:+ body["strictConstrainToURLs"] = strict_constrain_to_urlsreturn body@@ -41,9 +51,10 @@ async def start_agent(urls: Optional[List[str]],*,prompt: str,- schema: Optional[Dict[str, Any]] = None,+ schema: Optional[Any] = None,integration: Optional[str] = None,max_credits: Optional[int] = None,+ strict_constrain_to_urls: Optional[bool] = None,) -> AgentResponse:body = _prepare_agent_request(urls,@@ -51,6 +62,7 @@ async def start_agent(schema=schema,integration=integration,max_credits=max_credits,+ strict_constrain_to_urls=strict_constrain_to_urls,)resp = await client.post("/v2/agent", body)payload = _normalize_agent_response_payload(resp.json())@@ -85,7 +97,7 @@ async def agent(urls: Optional[List[str]],*,prompt: str,- schema: Optional[Dict[str, Any]] = None,+ schema: Optional[Any] = None,integration: Optional[str] = None,poll_interval: int = 2,timeout: Optional[int] = None,diff --git a/apps/python-sdk/tests/test_agent_integration.py b/apps/python-sdk/tests/test_agent_integration.pynew file mode 100644index 000000000..72c214e1b--- /dev/null+++ b/apps/python-sdk/tests/test_agent_integration.py@@ -0,0 +1,277 @@+"""+Integration tests for agent method with mocked requests.+"""++import unittest+from unittest.mock import patch, MagicMock+from pydantic import BaseModel, Field+from typing import List, Optional++from firecrawl import FirecrawlApp+++class Founder(BaseModel):+ name: str = Field(description="Full name of the founder")+ role: Optional[str] = Field(None, description="Role or position")+ background: Optional[str] = Field(None, description="Professional background")+++class FoundersSchema(BaseModel):+ founders: List[Founder] = Field(description="List of founders")+++class TestAgent(unittest.TestCase):+ """Integration tests for agent method."""++ @patch('firecrawl.v2.utils.http_client.requests.post')+ @patch('firecrawl.v2.utils.http_client.requests.get')+ def test_agent_basic(self, mock_get, mock_post):+ """Test basic agent call."""+ # Mock start agent response+ mock_start_response = MagicMock()+ mock_start_response.ok = True+ mock_start_response.status_code = 200+ mock_start_response.json.return_value = {+ "success": True,+ "id": "test-agent-123",+ "status": "processing"+ }+ mock_post.return_value = mock_start_response++ # Mock get status response (completed)+ mock_status_response = MagicMock()+ mock_status_response.ok = True+ mock_status_response.status_code = 200+ mock_status_response.json.return_value = {+ "success": True,+ "id": "test-agent-123",+ "status": "completed",+ "data": {+ "founders": [+ {"name": "John Doe", "role": "CEO", "background": "Tech entrepreneur"},+ {"name": "Jane Smith", "role": "CTO", "background": "Software engineer"}+ ]+ },+ "creditsUsed": 10,+ "expiresAt": "2024-01-01T00:00:00Z"+ }+ mock_get.return_value = mock_status_response++ app = FirecrawlApp(api_key="test-api-key")+ result = app.agent(+ prompt="Find the founders of Firecrawl",+ schema=FoundersSchema+ )++ # Verify post was called with correct URL and data+ mock_post.assert_called_once()+ post_call_args = mock_post.call_args+ post_url = post_call_args[1]["url"] if "url" in post_call_args[1] else post_call_args[0][0]+ assert "/v2/agent" in str(post_url)++ # Check request body+ request_body = post_call_args[1]["json"]+ assert request_body["prompt"] == "Find the founders of Firecrawl"+ assert "schema" in request_body+ assert request_body["schema"]["type"] == "object"+ assert "founders" in request_body["schema"]["properties"]++ # Verify get was called to check status+ mock_get.assert_called()++ # Check result+ assert result.status == "completed"+ assert result.data is not None++ @patch('firecrawl.v2.utils.http_client.requests.post')+ def test_agent_with_urls(self, mock_post):+ """Test agent call with URLs."""+ mock_response = MagicMock()+ mock_response.ok = True+ mock_response.status_code = 200+ mock_response.json.return_value = {+ "success": True,+ "status": "completed",+ "data": {"result": "done"}+ }+ mock_post.return_value = mock_response++ app = FirecrawlApp(api_key="test-api-key")+ result = app.agent(+ urls=["https://example.com", "https://test.com"],+ prompt="Extract information",+ schema={"type": "object", "properties": {"info": {"type": "string"}}}+ )++ # Check request body includes URLs+ post_call_args = mock_post.call_args+ request_body = post_call_args[1]["json"]+ assert request_body["urls"] == ["https://example.com", "https://test.com"]+ assert request_body["prompt"] == "Extract information"++ @patch('firecrawl.v2.utils.http_client.requests.post')+ def test_agent_with_dict_schema(self, mock_post):+ """Test agent call with dict schema."""+ mock_response = MagicMock()+ mock_response.ok = True+ mock_response.status_code = 200+ mock_response.json.return_value = {+ "success": True,+ "status": "completed",+ "data": {"result": "done"}+ }+ mock_post.return_value = mock_response++ schema = {+ "type": "object",+ "properties": {+ "name": {"type": "string"},+ "age": {"type": "integer"}+ }+ }++ app = FirecrawlApp(api_key="test-api-key")+ result = app.agent(+ prompt="Extract person data",+ schema=schema+ )++ # Check request body includes schema+ post_call_args = mock_post.call_args+ request_body = post_call_args[1]["json"]+ assert request_body["schema"] == schema++ @patch('firecrawl.v2.utils.http_client.requests.post')+ def test_agent_with_all_params(self, mock_post):+ """Test agent call with all parameters."""+ mock_response = MagicMock()+ mock_response.ok = True+ mock_response.status_code = 200+ mock_response.json.return_value = {+ "success": True,+ "status": "completed",+ "data": {"result": "done"}+ }+ mock_post.return_value = mock_response++ schema = {"type": "object"}+ urls = ["https://example.com"]++ app = FirecrawlApp(api_key="test-api-key")+ result = app.agent(+ urls=urls,+ prompt="Complete test",+ schema=schema,+ integration="test-integration",+ max_credits=50,+ strict_constrain_to_urls=True,+ poll_interval=1,+ timeout=30+ )++ # Check all parameters are in request body+ post_call_args = mock_post.call_args+ request_body = post_call_args[1]["json"]+ assert request_body["prompt"] == "Complete test"+ assert request_body["urls"] == urls+ assert request_body["schema"] == schema+ assert request_body["integration"] == "test-integration"+ assert request_body["maxCredits"] == 50+ assert request_body["strictConstrainToURLs"] is True++ @patch('firecrawl.v2.utils.http_client.requests.post')+ def test_agent_pydantic_schema_normalization(self, mock_post):+ """Test that Pydantic schemas are properly normalized."""+ mock_response = MagicMock()+ mock_response.ok = True+ mock_response.status_code = 200+ mock_response.json.return_value = {+ "success": True,+ "status": "completed",+ "data": {"result": "done"}+ }+ mock_post.return_value = mock_response++ app = FirecrawlApp(api_key="test-api-key")+ result = app.agent(+ prompt="Find founders",+ schema=FoundersSchema+ )++ # Check that schema was normalized to JSON schema format+ post_call_args = mock_post.call_args+ request_body = post_call_args[1]["json"]+ assert "schema" in request_body+ schema = request_body["schema"]+ assert schema["type"] == "object"+ assert "properties" in schema+ assert "founders" in schema["properties"]+ assert schema["properties"]["founders"]["type"] == "array"++ @patch('firecrawl.v2.utils.http_client.requests.post')+ @patch('firecrawl.v2.utils.http_client.requests.get')+ def test_agent_url_construction(self, mock_get, mock_post):+ """Test that agent requests are sent to correct URL."""+ # Mock start agent response+ mock_start_response = MagicMock()+ mock_start_response.ok = True+ mock_start_response.status_code = 200+ mock_start_response.json.return_value = {+ "success": True,+ "id": "test-agent-123",+ "status": "processing"+ }+ mock_post.return_value = mock_start_response++ # Mock get status response+ mock_status_response = MagicMock()+ mock_status_response.ok = True+ mock_status_response.status_code = 200+ mock_status_response.json.return_value = {+ "success": True,+ "id": "test-agent-123",+ "status": "completed",+ "data": {"result": "done"}+ }+ mock_get.return_value = mock_status_response++ app = FirecrawlApp(api_key="test-api-key", api_url="https://api.firecrawl.dev")+ result = app.agent(prompt="Test prompt")++ # Check POST URL - requests.post is called with url as keyword arg+ post_call_args = mock_post.call_args+ post_url = post_call_args[1].get("url") if "url" in post_call_args[1] else post_call_args[0][0]+ assert "/v2/agent" in str(post_url)++ # Check GET URL+ get_call_args = mock_get.call_args+ get_url = get_call_args[1].get("url") if "url" in get_call_args[1] else get_call_args[0][0]+ assert "/v2/agent/test-agent-123" in str(get_url)++ @patch('firecrawl.v2.utils.http_client.requests.post')+ def test_agent_headers(self, mock_post):+ """Test that agent requests include correct headers."""+ mock_response = MagicMock()+ mock_response.ok = True+ mock_response.status_code = 200+ mock_response.json.return_value = {+ "success": True,+ "status": "completed",+ "data": {"result": "done"}+ }+ mock_post.return_value = mock_response++ app = FirecrawlApp(api_key="test-api-key")+ result = app.agent(prompt="Test prompt")++ # Check headers+ post_call_args = mock_post.call_args+ headers = post_call_args[1]["headers"]+ assert "Authorization" in headers+ assert headers["Authorization"] == "Bearer test-api-key"+ assert headers["Content-Type"] == "application/json"+++if __name__ == '__main__':+ unittest.main()+