Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

python-sdk: Update Agent Client (#2579)

Abimael Martelle4eb79f16cb8
diff --git a/apps/python-sdk/firecrawl/__init__.py b/apps/python-sdk/firecrawl/__init__.py
index 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 project
logger: 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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_extract
self.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_scrape
self.get_batch_scrape_status = client_instance.get_batch_scrape_status
self.cancel_batch_scrape = client_instance.cancel_batch_scrape
@@ -132,6 +137,11 @@ class AsyncV2Proxy:
self.start_extract = client_instance.start_extract
self.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_scrape
self.get_batch_scrape_status = client_instance.get_batch_scrape_status
self.cancel_batch_scrape = client_instance.cancel_batch_scrape
@@ -203,6 +213,11 @@ class Firecrawl:
self.get_extract_status = self._v2_client.get_extract_status
self.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_concurrency
self.get_credit_usage = self._v2_client.get_credit_usage
self.get_token_usage = self._v2_client.get_token_usage
@@ -249,6 +264,11 @@ class AsyncFirecrawl:
self.get_extract_status = self._v2_client.get_extract_status
self.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_concurrency
self.get_credit_usage = self._v2_client.get_credit_usage
self.get_token_usage = self._v2_client.get_token_usage
diff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.py
index 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/name
max_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/name
poll_interval: Seconds between status checks
timeout: 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.py
index 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.py
index 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 time
from ..types import AgentResponse
from ..utils.http_client import HttpClient
from ..utils.error_handler import handle_response_error
+from ..utils.validation import _normalize_schema
def _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"] = urls
body["prompt"] = prompt
if 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.py
index 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 asyncio
from ...types import AgentResponse
from ...utils.http_client_async import AsyncHttpClient
+from ...utils.validation import _normalize_schema
def _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"] = urls
body["prompt"] = prompt
if 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_urls
return 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.py
new file mode 100644
index 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()
+