Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

added skills with pydantic validation

Gregor Žunič4707bef5e334
diff --git a/browser_use/skills/README.md b/browser_use/skills/README.md
new file mode 100644
index 000000000..ca1f4a4b4
--- /dev/null
+++ b/browser_use/skills/README.md
@@ -0,0 +1,29 @@
+# Skills Module
+
+The Skills module provides integration with the Browser Use API to fetch and execute skills.
+
+## Basic Usage
+
+```python
+import asyncio
+from browser_use.skills import SkillService
+
+async def main():
+ skill_ids = ['skill-id-1', 'skill-id-2']
+
+ # Using context manager (recommended)
+ async with SkillService(skill_ids=skill_ids, api_key='your-api-key') as service:
+ # Get all loaded skills (auto-initializes on first call)
+ skills = await service.get_all_skills()
+
+ # Execute a skill (auto-initializes if needed)
+ result = await service.execute_skill(
+ skill_id='skill-id-1',
+ parameters={'param1': 'value1'}
+ )
+
+ if result.success:
+ print(f'Success! Result: {result.result}')
+
+asyncio.run(main())
+```
diff --git a/browser_use/skills/__init__.py b/browser_use/skills/__init__.py
new file mode 100644
index 000000000..3983a21cc
--- /dev/null
+++ b/browser_use/skills/__init__.py
@@ -0,0 +1,3 @@
+from browser_use.skills.service import SkillService
+
+__all__ = ['SkillService']
diff --git a/browser_use/skills/service.py b/browser_use/skills/service.py
new file mode 100644
index 000000000..8c50cd6c3
--- /dev/null
+++ b/browser_use/skills/service.py
@@ -0,0 +1,206 @@
+"""Skills service for fetching and executing skills from the Browser Use API"""
+
+import asyncio
+import logging
+import os
+from typing import Any
+
+from browser_use_sdk import AsyncBrowserUse
+from pydantic import BaseModel, ValidationError
+
+from browser_use.skills.views import ExecuteSkillResponse, Skill, SkillResponse
+
+logger = logging.getLogger(__name__)
+
+
+class SkillService:
+ """Service for managing and executing skills from the Browser Use API"""
+
+ def __init__(self, skill_ids: list[str], api_key: str | None = None):
+ """Initialize the skills service
+
+ Args:
+ skill_ids: List of skill IDs to fetch and cache
+ api_key: Browser Use API key (optional, will use env var if not provided)
+ """
+ self.skill_ids = skill_ids
+ self.api_key = api_key or os.getenv('BROWSER_USE_API_KEY') or ''
+
+ if not self.api_key:
+ raise ValueError('BROWSER_USE_API_KEY environment variable is not set')
+
+ self._skills: dict[str, Skill] = {}
+ self._client: AsyncBrowserUse | None = None
+ self._initialized = False
+
+ async def async_init(self) -> None:
+ """Async initialization to fetch all skills concurrently
+
+ This should be called after __init__ to fetch and cache all skills.
+ """
+ if self._initialized:
+ logger.debug('SkillService already initialized')
+ return
+
+ # Create the SDK client
+ self._client = AsyncBrowserUse(api_key=self.api_key)
+
+ # Fetch all skills concurrently
+ logger.info(f'Fetching {len(self.skill_ids)} skills from Browser Use API...')
+
+ fetch_tasks = [self._fetch_skill(skill_id) for skill_id in self.skill_ids]
+ results = await asyncio.gather(*fetch_tasks, return_exceptions=True)
+
+ # Process results
+ for skill_id, result in zip(self.skill_ids, results):
+ if isinstance(result, Exception):
+ logger.error(f'Failed to fetch skill {skill_id}: {result}')
+ elif isinstance(result, Skill):
+ self._skills[skill_id] = result
+ logger.debug(f'Cached skill: {result.title} ({skill_id})')
+
+ logger.info(f'Successfully loaded {len(self._skills)}/{len(self.skill_ids)} skills')
+ self._initialized = True
+
+ async def _fetch_skill(self, skill_id: str) -> Skill | None:
+ """Fetch a single skill from the API and convert to Skill model
+
+ Args:
+ skill_id: The UUID of the skill to fetch
+
+ Returns:
+ Skill model or None if fetch failed
+ """
+ assert self._client is not None, 'Client not initialized - call async_init() first'
+
+ try:
+ # Fetch skill details from API (returns SkillResponse from SDK)
+ skill_response: SkillResponse = await self._client.skills.get_skill(skill_id=skill_id)
+
+ # Check if skill is finished and enabled
+ if skill_response.status != 'finished':
+ logger.warning(f'Skill {skill_id} is not finished (status: {skill_response.status})')
+ return None
+
+ if not skill_response.is_enabled:
+ logger.warning(f'Skill {skill_id} is not enabled')
+ return None
+
+ # Convert SDK SkillResponse to our Skill model with helper properties
+ skill = Skill.from_skill_response(skill_response)
+
+ return skill
+
+ except Exception as e:
+ logger.error(f'Error fetching skill {skill_id}: {type(e).__name__}: {e}')
+ return None
+
+ async def get_skill(self, skill_id: str) -> Skill | None:
+ """Get a cached skill by ID. Auto-initializes if not already initialized.
+
+ Args:
+ skill_id: The UUID of the skill
+
+ Returns:
+ Skill model or None if not found in cache
+ """
+ if not self._initialized:
+ await self.async_init()
+
+ return self._skills.get(skill_id)
+
+ async def get_all_skills(self) -> list[Skill]:
+ """Get all cached skills. Auto-initializes if not already initialized.
+
+ Returns:
+ List of all successfully loaded skills
+ """
+ if not self._initialized:
+ await self.async_init()
+
+ return list(self._skills.values())
+
+ async def execute_skill(self, skill_id: str, parameters: dict[str, Any] | BaseModel) -> ExecuteSkillResponse:
+ """Execute a skill with the provided parameters. Auto-initializes if not already initialized.
+
+ Parameters are validated against the skill's Pydantic schema before execution.
+
+ Args:
+ skill_id: The UUID of the skill to execute
+ parameters: Either a dictionary or BaseModel instance matching the skill's parameter schema
+
+ Returns:
+ ExecuteSkillResponse with execution results
+
+ Raises:
+ ValueError: If skill not found in cache or parameter validation fails
+ Exception: If API call fails
+ """
+ # Auto-initialize if needed
+ if not self._initialized:
+ await self.async_init()
+
+ assert self._client is not None, 'Client not initialized'
+
+ # Check if skill exists in cache
+ skill = await self.get_skill(skill_id)
+ if skill is None:
+ raise ValueError(f'Skill {skill_id} not found in cache. Available skills: {list(self._skills.keys())}')
+
+ # Get the skill's pydantic model for parameter validation
+ ParameterModel = skill.parameters_pydantic
+
+ # Validate and convert parameters to dict
+ validated_params_dict: dict[str, Any]
+
+ try:
+ if isinstance(parameters, BaseModel):
+ # Already a pydantic model - validate it matches the skill's schema
+ # by converting to dict and re-validating with the skill's model
+ params_dict = parameters.model_dump()
+ validated_model = ParameterModel(**params_dict)
+ validated_params_dict = validated_model.model_dump()
+ else:
+ # Dict provided - validate with the skill's pydantic model
+ validated_model = ParameterModel(**parameters)
+ validated_params_dict = validated_model.model_dump()
+
+ except ValidationError as e:
+ # Pydantic validation failed
+ error_msg = f'Parameter validation failed for skill {skill.title}:\n'
+ for error in e.errors():
+ field = '.'.join(str(x) for x in error['loc'])
+ error_msg += f' - {field}: {error["msg"]}\n'
+ raise ValueError(error_msg) from e
+ except Exception as e:
+ raise ValueError(f'Failed to validate parameters for skill {skill.title}: {type(e).__name__}: {e}') from e
+
+ # Execute skill via API
+ try:
+ logger.info(f'Executing skill: {skill.title} ({skill_id})')
+ result: ExecuteSkillResponse = await self._client.skills.execute_skill(
+ skill_id=skill_id, parameters=validated_params_dict
+ )
+
+ if result.success:
+ logger.info(f'Skill {skill.title} executed successfully (latency: {result.latency_ms}ms)')
+ else:
+ logger.error(f'Skill {skill.title} execution failed: {result.error}')
+
+ return result
+
+ except Exception as e:
+ logger.error(f'Error executing skill {skill_id}: {type(e).__name__}: {e}')
+ # Return error response
+ return ExecuteSkillResponse(
+ success=False,
+ error=f'Failed to execute skill: {type(e).__name__}: {str(e)}',
+ )
+
+ async def close(self) -> None:
+ """Close the SDK client and cleanup resources"""
+ if self._client is not None:
+ # AsyncBrowserUse client cleanup if needed
+ # The SDK doesn't currently have a close method, but we set to None for cleanup
+ self._client = None
+ self._initialized = False
diff --git a/browser_use/skills/utils.py b/browser_use/skills/utils.py
new file mode 100644
index 000000000..e842bdbef
--- /dev/null
+++ b/browser_use/skills/utils.py
@@ -0,0 +1,140 @@
+"""Utilities for skill schema conversion"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field, create_model
+
+from browser_use.skills.views import ParameterSchema
+
+
+def convert_parameters_to_pydantic(parameters: list[ParameterSchema], model_name: str = 'SkillParameters') -> type[BaseModel]:
+ """Convert a list of ParameterSchema to a pydantic model for structured output
+
+ Args:
+ parameters: List of parameter schemas from the skill API
+ model_name: Name for the generated pydantic model
+
+ Returns:
+ A pydantic BaseModel class with fields matching the parameter schemas
+ """
+ if not parameters:
+ # Return empty model if no parameters
+ return create_model(model_name, __base__=BaseModel)
+
+ fields: dict[str, Any] = {}
+
+ for param in parameters:
+ # Map parameter type string to Python types
+ python_type: Any = str # default
+
+ param_type = param.type
+
+ if param_type == 'string':
+ python_type = str
+ elif param_type == 'number':
+ python_type = float
+ elif param_type == 'boolean':
+ python_type = bool
+ elif param_type == 'object':
+ python_type = dict[str, Any]
+ elif param_type == 'array':
+ python_type = list[Any]
+ elif param_type == 'cookie':
+ python_type = str # Treat cookies as strings
+
+ # Check if parameter is required (defaults to True if not specified)
+ is_required = param.required if param.required is not None else True
+
+ # Make optional if not required
+ if not is_required:
+ python_type = python_type | None # type: ignore
+
+ # Create field with description
+ field_kwargs = {}
+ if param.description:
+ field_kwargs['description'] = param.description
+
+ if is_required:
+ fields[param.name] = (python_type, Field(**field_kwargs))
+ else:
+ fields[param.name] = (python_type, Field(default=None, **field_kwargs))
+
+ # Create and return the model
+ return create_model(model_name, __base__=BaseModel, **fields)
+
+
+def convert_json_schema_to_pydantic(schema: dict[str, Any], model_name: str = 'SkillOutput') -> type[BaseModel]:
+ """Convert a JSON schema to a pydantic model
+
+ Args:
+ schema: JSON schema dictionary (OpenAPI/JSON Schema format)
+ model_name: Name for the generated pydantic model
+
+ Returns:
+ A pydantic BaseModel class matching the schema
+
+ Note:
+ This is a simplified converter that handles basic types.
+ For complex nested schemas, consider using datamodel-code-generator.
+ """
+ if not schema or 'properties' not in schema:
+ # Return empty model if no schema
+ return create_model(model_name, __base__=BaseModel)
+
+ fields: dict[str, Any] = {}
+ properties = schema.get('properties', {})
+ required_fields = set(schema.get('required', []))
+
+ for field_name, field_schema in properties.items():
+ # Get the field type
+ field_type_str = field_schema.get('type', 'string')
+ field_description = field_schema.get('description')
+
+ # Map JSON schema types to Python types
+ python_type: Any = str # default
+
+ if field_type_str == 'string':
+ python_type = str
+ elif field_type_str == 'number':
+ python_type = float
+ elif field_type_str == 'integer':
+ python_type = int
+ elif field_type_str == 'boolean':
+ python_type = bool
+ elif field_type_str == 'object':
+ python_type = dict[str, Any]
+ elif field_type_str == 'array':
+ # Check if items type is specified
+ items_schema = field_schema.get('items', {})
+ items_type = items_schema.get('type', 'string')
+
+ if items_type == 'string':
+ python_type = list[str]
+ elif items_type == 'number':
+ python_type = list[float]
+ elif items_type == 'integer':
+ python_type = list[int]
+ elif items_type == 'boolean':
+ python_type = list[bool]
+ elif items_type == 'object':
+ python_type = list[dict[str, Any]]
+ else:
+ python_type = list[Any]
+
+ # Make optional if not required
+ is_required = field_name in required_fields
+ if not is_required:
+ python_type = python_type | None # type: ignore
+
+ # Create field with description
+ field_kwargs = {}
+ if field_description:
+ field_kwargs['description'] = field_description
+
+ if is_required:
+ fields[field_name] = (python_type, Field(**field_kwargs))
+ else:
+ fields[field_name] = (python_type, Field(default=None, **field_kwargs))
+
+ # Create and return the model
+ return create_model(model_name, __base__=BaseModel, **fields)
diff --git a/browser_use/skills/views.py b/browser_use/skills/views.py
new file mode 100644
index 000000000..604d499db
--- /dev/null
+++ b/browser_use/skills/views.py
@@ -0,0 +1,67 @@
+"""Skills views - wraps SDK types with helper methods"""
+
+from typing import Any
+
+from browser_use_sdk.types import (
+ app_api_v2skills_views_parameter_schema as parameter_schema_module,
+)
+from browser_use_sdk.types import (
+ app_api_v2skills_views_parameter_type as parameter_type_module,
+)
+from browser_use_sdk.types import (
+ execute_skill_response,
+ skill_response,
+ skills_generation_status,
+)
+from pydantic import BaseModel, ConfigDict, Field
+
+# Re-export SDK types for convenience
+SkillsGenerationStatus = skills_generation_status.SkillsGenerationStatus
+ParameterType = parameter_type_module.AppApiV2SkillsViewsParameterType
+ParameterSchema = parameter_schema_module.AppApiV2SkillsViewsParameterSchema
+SkillResponse = skill_response.SkillResponse
+ExecuteSkillResponse = execute_skill_response.ExecuteSkillResponse
+
+
+class Skill(BaseModel):
+ """Skill model with helper methods for LLM integration
+
+ This wraps the SDK SkillResponse with additional helper properties
+ for converting schemas to Pydantic models.
+ """
+
+ model_config = ConfigDict(extra='forbid', validate_assignment=True)
+
+ id: str
+ title: str
+ description: str
+ parameters: list[ParameterSchema]
+ output_schema: dict[str, Any] = Field(default_factory=dict)
+
+ @staticmethod
+ def from_skill_response(response: SkillResponse) -> 'Skill':
+ """Create a Skill from SDK SkillResponse"""
+ return Skill(
+ id=response.id,
+ title=response.title,
+ description=response.description,
+ parameters=response.parameters,
+ output_schema=response.output_schema,
+ )
+
+ @property
+ def parameters_pydantic(self) -> type[BaseModel]:
+ """Convert parameter schemas to a pydantic model for structured output"""
+ from browser_use.skills.utils import convert_parameters_to_pydantic
+
+ return convert_parameters_to_pydantic(self.parameters, model_name=f'{self.title}Parameters')
+
+ @property
+ def output_type_pydantic(self) -> type[BaseModel] | None:
+ """Convert output schema to a pydantic model for structured output"""
+ if not self.output_schema:
+ return None
+
+ from browser_use.skills.utils import convert_json_schema_to_pydantic
+
+ return convert_json_schema_to_pydantic(self.output_schema, model_name=f'{self.title}Output')
diff --git a/pyproject.toml b/pyproject.toml
index 018e12720..b2ffa1754 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -47,6 +47,7 @@ dependencies = [
"cloudpickle>=3.1.1",
"markdownify>=1.2.0",
"python-docx>=1.2.0",
+ "browser-use-sdk>=2.0.11",
]
# google-api-core: only used for Google LLM APIs
# pyperclip: only used for examples that use copy/paste