Upload 4 files

examples/tools/android/README.md

@@ -0,0 +1,79 @@
+## Android Environment Setup Guide
+
+This guide will help you set up a local Android environment for AgentWorld.
+
+### Installation Steps
+
+1. **Download and Install Android Studio**
+   - Visit [https://developer.android.com/studio](https://developer.android.com/studio)
+   - Download and install the latest version for your operating system
+
+2. **Install ADB and Android Emulator**
+   - Open Android Studio
+   - Click on the top menu: Tools → SDK Manager
+        <img src="../../../readme_assets/android_step1.png" width="70%" alt="SDK Manager">
+       <!-- ![Agent World Framework](../../readme_assets/android_step1.png){:style="width:200px; height:auto;"} -->
+   - Check the following components:
+     - Android SDK Build-Tools
+     - Android SDK Command-line Tools
+     - Android Emulator
+     - Android SDK Platform-Tools
+   - Click "Apply" to install these components
+      <img src="../../../readme_assets/android_step2.png" width="70%" alt="Check components">
+   - **Important**: Copy the installation directory path (you'll need it later for configuration)
+
+3. **Create a Virtual Device**
+   - From the main menu, select: View → Tool Windows → Device Manager
+    <img src="../../../readme_assets/android_step3.png" width="70%" alt="Device Manager">
+   - Click the "+" button, then "Create Virtual Device"
+   <img src="../../../readme_assets/android_step4.png" width="70%" alt="button">
+   - Select a device (e.g., Medium Phone), then click "Next"
+   <img src="../../../readme_assets/android_step5.png" width="70%" alt="next">
+   - Select a image (e.g., VanillalceCream), then click "Next"
+   <img src="../../../readme_assets/android_step6.png" width="70%" alt="next">
+   - Configure device settings as needed, then click "Finish"
+   - **Important**: Note down the AVD ID (device name) for later use
+   <img src="../../../readme_assets/android_step7.png" width="70%" alt="avd id">
+
+4. **Configure in Your Code**
+   - Method 1: Default Acquisition of Emulator and ADB Installation Paths
+     - Only set the AVD_ID copied during the earlier installation process.
+   - Method 2: Manually Specify Emulator and ADB Installation Paths.Provide the following:
+     - AVD_ID: The name of the virtual device you created
+     - ADB path: Your SDK directory + "/platform-tools/adb"
+     - Emulator path: Your SDK directory + "/emulator/emulator"
+### Example Code
+#### Method 1
+
+```python
+from examples.tools.android.action.adb_controller import ADBController
+
+# Initialize the Android controller
+android_controller = ADBController(avd_name="Medium_Phone_API_35")
+```
+#### Method 2
+
+```python
+from examples.tools.android.action.adb_controller import ADBController
+
+# Initialize the Android controller
+android_controller = ADBController(
+    avd_name="Medium_Phone_API_35",
+    adb_path="/Users/username/Library/Android/sdk/platform-tools/adb",
+    emulator_path="/Users/username/Library/Android/sdk/emulator/emulator"
+)
+
+# Now you can use this controller with your agent
+```
+
+### Troubleshooting
+
+- If the emulator fails to start, try increasing the memory allocation in the AVD settings
+- Make sure your paths are correct for your operating system:
+  - Windows: Use backslashes or raw strings (r"C:\path\to\sdk")
+  - macOS/Linux: Use forward slashes as shown in the example
+
+### Additional Resources
+
+- [Android SDK Official Documentation](https://developer.android.com/studio/intro)
+- [Android Emulator Documentation](https://developer.android.com/studio/run/emulator)

examples/tools/android/__init__.py

@@ -0,0 +1,2 @@
+# coding: utf-8
+# Copyright (c) 2025 inclusionAI.

examples/tools/android/android.py

@@ -0,0 +1,90 @@
+# coding: utf-8
+# Copyright (c) 2025 inclusionAI.
+
+import traceback
+from typing import Any, Tuple, List, Dict
+
+from examples.tools.tool_action import AndroidAction
+from aworld.core.common import ActionModel, Observation, ActionResult
+from aworld.logs.util import logger
+from examples.tools.android.action.adb_controller import ADBController
+from examples.tools.android.action.executor import AndroidToolActionExecutor
+from examples.tools.conf import AndroidToolConfig
+from aworld.core.tool.base import ToolFactory, Tool
+from aworld.tools.utils import build_observation
+
+ALL_UNICODE_CHARS = frozenset(chr(i) for i in range(0x10FFFF + 1))
+
+
+@ToolFactory.register(name="android",
+                      desc="android",
+                      supported_action=AndroidAction,
+                      conf_file_name=f'android_tool.yaml')
+class AndroidTool(Tool):
+
+    def __init__(self, conf: AndroidToolConfig, **kwargs):
+        super(AndroidTool, self).__init__(conf, **kwargs)
+        self.controller = ADBController(avd_name=self.conf.get('avd_name'),
+                                        adb_path=self.conf.get('adb_path'),
+                                        emulator_path=self.conf.get('emulator_path'))
+
+        if self.conf.get("custom_executor"):
+            self.action_executor = AndroidToolActionExecutor(self.controller)
+
+    def reset(self, *, seed: int | None = None, options: Dict[str, str] | None = None) -> Tuple[
+        Observation, Dict[str, Any]]:
+        # self.controller.stop_emulator()
+        # self.controller.start_emulator()
+        self.controller.setup_connection()
+        logger.info("start emulator successfully...")
+        # snapshot screen and annotate
+        xml, pic_base64 = self.get_observation()
+        action_result_list = [ActionResult(content='start', keep=True)]
+        return build_observation(observer=self.name(),
+                                 ability='',
+                                 dom_tree=xml,
+                                 image=pic_base64,
+                                 action_result=action_result_list), {}
+
+    def do_step(self, action_list: List[ActionModel], **kwargs) -> Tuple[
+        Observation, float, bool, bool, Dict[str, Any]]:
+
+        exec_state = 0
+        fail_error = ""
+        action_result_list = None
+        try:
+            action_result_list = self.action_executor.execute_action(action_list, **kwargs)
+            exec_state = 1
+        except Exception as e:
+            traceback.print_exc()
+            fail_error = str(e)
+
+        terminated = kwargs.get("terminated", False)
+        if action_result_list:
+            for action_result in action_result_list:
+                if action_result.is_done:
+                    terminated = action_result.is_done
+                    self._finish = True
+
+        info = {"exception": fail_error}
+        info.update(kwargs)
+        xml, pic_base64 = self.get_observation()
+
+        return (build_observation(observer=self.name(),
+                                  ability=action_list[-1].action_name,
+                                  dom_tree=xml,
+                                  image=pic_base64,
+                                  action_result=action_result_list),
+                exec_state,
+                terminated,
+                kwargs.get("truncated", False),
+                info)
+
+    def close(self):
+        self.controller.stop_emulator()
+
+    def get_controller(self):
+        return self.controller
+
+    def get_observation(self) -> Observation:
+        return self.controller.screenshot_and_annotate()

examples/tools/android/requirements.txt

@@ -0,0 +1,2 @@
+opencv-python~=4.11.0.86
+pyshine~=0.0.9