MCP Browser Agent

Instructions

Args:
    actions: A dictionary containing the planner state and actions in format:
            {
                "current_state": {
                    "evaluation_previous_goal": str,
                    "memory": str,
                    "next_goal": str
                },
                "action": [
                    {"action_name": {"param1": "value1"}},
                    ...
                ]
            }
            
Note: If the page state changes (new elements appear) during action execution,
the sequence will be interrupted and you'll need to get a new planner state.

Implementation Reference

• browser-use.py:210-299 (handler)

  The execute_actions tool handler, registered via @mcp.tool(). Validates the actions input dictionary, converts actions to models using Controller.registry, executes them sequentially with DOM change detection to prevent stale selectors, and returns execution results or errors.

  @mcp.tool()
  async def execute_actions(actions: Dict[str, Any], ctx: Context) -> str:
      """Execute actions from the planner state.
      
      Args:
          actions: A dictionary containing the planner state and actions in format:
                  {
                      "current_state": {
                          "evaluation_previous_goal": str,
                          "memory": str,
                          "next_goal": str
                      },
                      "action": [
                          {"action_name": {"param1": "value1"}},
                          ...
                      ]
                  }
                  
      Note: If the page state changes (new elements appear) during action execution,
      the sequence will be interrupted and you'll need to get a new planner state.
      """
      browser_context = await browser_initialized_check()
      controller = ctx.request_context.lifespan_context["controller"]
      
      try:
          # Validate input format
          if not isinstance(actions, dict) or "action" not in actions:
              return "Error: Actions must be a dictionary containing 'action' list"
          
          action_list = actions["action"]
          if not action_list:
              return "No actions to execute"
          
          # Get initial state for DOM change detection
          initial_state = await browser_context.get_state()
          initial_path_hashes = set(e.hash.branch_path_hash for e in initial_state.selector_map.values())
          
          # Convert system prompt action format to action models
          action_models = []
          for action_dict in action_list:
              if not isinstance(action_dict, dict) or len(action_dict) != 1:
                  return "Error: Each action must be a dictionary with exactly one key-value pair"
                  
              action_name = list(action_dict.keys())[0]
              params = action_dict[action_name]
              
              # Create action model using the controller's registry
              action_model = controller.registry.create_action_model()(**{action_name: params})
              action_models.append(action_model)
          
          # Execute actions one by one to check for DOM changes
          results = []
          for i, action_model in enumerate(action_models):
              # Execute single action
              result = await controller.act(action_model, browser_context)
              results.append(result)
              
              # Check if this action requires element interaction
              requires_elements = any(param in str(action_model) for param in ["index", "xpath"])
              
              # If not the last action and next action might need elements, check for DOM changes
              if i < len(action_models) - 1:
                  new_state = await browser_context.get_state()
                  new_path_hashes = set(e.hash.branch_path_hash for e in new_state.selector_map.values())
                  
                  # If DOM changed and next action needs elements, break sequence
                  if requires_elements and not new_path_hashes.issubset(initial_path_hashes):
                      msg = f"Page state changed after action {i + 1}/{len(action_models)}. Please get new planner state before continuing."
                      logger.info(msg)
                      results.append(ActionResult(extracted_content=msg, include_in_memory=True))
                      break
              
              # Stop if there was an error
              if result.error:
                  break
          
          # Process results
          output = []
          for result in results:
              if result.extracted_content:
                  output.append(result.extracted_content)
              elif result.error:
                  output.append(f"Error: {result.error}")
              else:
                  output.append("Action executed successfully")
                  
          return "\n".join(output)
      except Exception as e:
          logger.error(f"Error executing actions: {str(e)}")
          return f"Error executing actions: {str(e)}"

• browser-use.py:212-230 (schema)

  Docstring defining the expected input schema for the actions parameter, including structure for current_state and action list.

  """Execute actions from the planner state.
  
  Args:
      actions: A dictionary containing the planner state and actions in format:
              {
                  "current_state": {
                      "evaluation_previous_goal": str,
                      "memory": str,
                      "next_goal": str
                  },
                  "action": [
                      {"action_name": {"param1": "value1"}},
                      ...
                  ]
              }
              
  Note: If the page state changes (new elements appear) during action execution,
  the sequence will be interrupted and you'll need to get a new planner state.
  """

• browser-use.py:210-210 (registration)

  MCP tool registration decorator for execute_actions.

  @mcp.tool()