Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
added skills with pydantic validation
Gregor Žunič4707bef5e334
diff --git a/browser_use/skills/README.md b/browser_use/skills/README.mdnew file mode 100644index 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__.pynew file mode 100644index 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.pynew file mode 100644index 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 = Falsediff --git a/browser_use/skills/utils.py b/browser_use/skills/utils.pynew file mode 100644index 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.pynew file mode 100644index 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.tomlindex 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