xgae 0.3.2__tar.gz → 0.3.3__tar.gz

{xgae-0.3.2 → xgae-0.3.3}/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.3.3] - 2025-10-30
+### Added
+- GAIA2 ARE Scenario:  scenario_bomc_fault
+- GAIA2 ARE  MCP: Support Custom MCP Apps, example_mcp_apps.json
+
+
 ## [0.3.2] - 2025-10-24
 ### Added
 - GAIA2 ARE Example:  XGAAreAgent, XGAAreToolBox

{xgae-0.3.2 → xgae-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xgae
-Version: 0.3.2
+Version: 0.3.3
 Summary: Extreme General Agent Engine
 Requires-Python: >=3.11
 Requires-Dist: colorlog>=6.9.0
@@ -19,7 +19,7 @@ Description-Content-Type: text/markdown
 - Support Custom prompt and external MCP Tools
 - Support Langfuse
 - Support Langgraph
-- Support GAIA2 ARE agent
+- Support GAIA2 ARE agent and Custom MCP Apps
 - Support Human-in-Loop in agent
 - Can Use A2A protocol call A2A Agent as tool by 'xgaproxy' project
 - Can Use E2B or Daytona Sandbox of 'xgatools' project

{xgae-0.3.2 → xgae-0.3.3}/README.md

@@ -3,7 +3,7 @@
 - Support Custom prompt and external MCP Tools
 - Support Langfuse
 - Support Langgraph
-- Support GAIA2 ARE agent
+- Support GAIA2 ARE agent and Custom MCP Apps
 - Support Human-in-Loop in agent
 - Can Use A2A protocol call A2A Agent as tool by 'xgaproxy' project
 - Can Use E2B or Daytona Sandbox of 'xgatools' project

xgae-0.3.3/examples/agent/are/example_mcp_apps.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "BomcFault": {
+      "type": "sse",
+      "url": "http://localhost:17070/sse",
+      "headers": {
+        "Authorization": "Bearer YOURLONGLIVEDTOKENS"
+      }
+    }
+  }
+}

xgae-0.3.3/examples/agent/are/simulation/agents/xga/README.md

@@ -0,0 +1,44 @@
+## GAIA2 ARE Support
+### How to add XGAE to ARE Project
+- add xgae==0.3.2 to ARE requirements.txt
+- uv pip install -r requirements.txt
+- modify ARE 'AgentBuilder' and 'AgentConfigBuilder' class, add "xga" type agent :
+  ```
+  File: agent_builder.py
+      class AgentBuilder:
+        def list_agents(self) -> list[str]:
+          return ["default", "xga"]
+            
+        def build():
+            ...
+            agent_name = agent_config.get_agent_name()
+            if agent_name in ["default", "xga"]:
+                # add xga agent code
+      
+  File: agent_config_builder.py
+    class AgentConfigBuilder:
+        def build():
+            if agent_name in["default", "xga"]:
+  ```
+- modify ARE 'MCPApp' :
+```
+File: mcp_app.py
+    class MCPApp:
+        def _call_tool(self, tool_name: str, **kwargs) -> str:
+            try:
+                ...
+                from are.simulation.agents.xga.mcp_tool_executor import call_mcp_tool
+                result = call_mcp_tool(self.server_url, tool_name, kwargs, 10)
+                return str(result)
+                
+
+```
+
+
+- modify ARE .env, add XGAE .env config, refer to env.example 
+- copy XGAE package 'mcpservers' and 'templates' directory to ARE project root  
+
+### Run XGA Agent in ARE
+  ```
+uv run are-run -e -s scenario_find_image_file -a xga --model openai/qwen3-235b-a22b --provider llama-api --output_dir ./output
+  ```

{xgae-0.3.2 → xgae-0.3.3}/examples/agent/are/simulation/agents/xga/env.example

@@ -22,6 +22,7 @@ ALL_MODELS=""
 
 DEMO_FS_PATH="hf://datasets/meta-agents-research-environments/gaia2_filesystem/demo_filesystem"
 
+MCP_APPS_JSON_PATH=/Users/sharkystar/DevProjects/are/mcpservers/example_mcp_apps.json
 
 ###     XGA ENV        ###
 # LOG

xgae-0.3.3/examples/agent/are/simulation/agents/xga/mcp_tool_executor.py

@@ -0,0 +1,133 @@
+import asyncio
+import json
+import threading
+import time
+
+from concurrent.futures import Future as ConcurrentFuture
+from typing import Any, Optional, Coroutine, List, Dict
+
+from mcp.client.session import ClientSession
+from mcp.client.sse import sse_client
+
+from xgae.engine.engine_base import  XGAToolResult
+
+
+class AsyncToolExecutor:
+    _instance = None
+    _loop = None
+    _thread = None
+    _lock = threading.Lock()
+
+    def __new__(cls):
+        with cls._lock:
+            if cls._instance is None:
+                cls._instance = super().__new__(cls)
+                cls._init_event_loop()
+            return cls._instance
+
+
+    @classmethod
+    def _init_event_loop(cls):
+        if cls._loop is None or cls._loop.is_closed():
+            cls._loop = asyncio.new_event_loop()
+
+        def start_loop(loop):
+            asyncio.set_event_loop(loop)
+            try:
+                loop.run_forever()
+            finally:
+                if not loop.is_closed():
+                    loop.close()
+
+        cls._thread = threading.Thread(target=start_loop, args=(cls._loop,), daemon=True)
+        cls._thread.start()
+
+        time.sleep(0.1)
+
+    @classmethod
+    def submit(cls, coro: Coroutine) -> ConcurrentFuture:
+        if cls._loop is None or cls._loop.is_closed():
+            cls._init_event_loop()
+
+        return asyncio.run_coroutine_threadsafe(coro, cls._loop)
+
+    @classmethod
+    def run_and_wait(cls, coro: Coroutine, timeout: Optional[float] = None) -> Any:
+        future = cls.submit(coro)
+        return future.result(timeout=timeout)
+
+    @classmethod
+    def get_loop(cls):
+        if cls._loop is None or cls._loop.is_closed():
+            cls._init_event_loop()
+        return cls._loop
+
+    @classmethod
+    def shutdown(cls):
+        if cls._loop is not None and not cls._loop.is_closed():
+            cls._loop.call_soon_threadsafe(cls._loop.stop)
+
+from mcp.types import CallToolResult
+
+async def _mcp_sse_tool_call(url: str, tool_name: str, arguments: dict[str, Any]) -> CallToolResult:
+    async with sse_client(url, sse_read_timeout=5) as streams:
+        async with ClientSession(*streams) as session:
+            await session.initialize()
+            return  await session.call_tool(tool_name, arguments)
+
+
+def call_mcp_tool(url: str, tool_name: str, arguments: dict[str, Any], timeout: Optional[float] = None) -> Any:
+    future = AsyncToolExecutor.submit(_mcp_sse_tool_call(url, tool_name, arguments))
+    mcp_result:CallToolResult =  future.result(timeout=timeout)
+    result = {
+        'success': not mcp_result.isError,
+    }
+    if mcp_result.isError:
+        result['output'] = mcp_result.content[0].text
+    else:
+        result['output'] = mcp_result.structuredContent['result']
+
+    return  json.dumps(result)
+
+
+def convert_mcp_tool_result(org_result: str)->XGAToolResult:
+    result = XGAToolResult(success=True, output=str(org_result))
+
+    if org_result and isinstance(org_result, str):
+        try:
+            _result:dict = json.loads(org_result)
+            output = _result.get('output', None)
+            success = _result.get('success', None)
+
+            if success and output:
+                result = XGAToolResult(success=bool(success), output=str(output))
+        except:
+            pass
+
+    return result
+
+
+if __name__ == "__main__":
+    async def sample_task(name, duration):
+        print(f"Task '{name}' Begin，time = {duration} ")
+        await asyncio.sleep(duration)
+        return f"Task '{name}' Finished"
+
+    async def main():
+        try:
+            # result = AsyncToolExecutor.run_and_wait(sample_task("mytool", 1))
+            # print(f"Result1: {result}")
+
+            result = call_mcp_tool("http://localhost:17070/sse", "get_alarm", {"ip":"13.0.0.13"})
+            result = convert_mcp_tool_result(result)
+            print(f"Result2: {result}")
+
+            result = call_mcp_tool("http://localhost:17070/sse", "get_alarm1", {"ip":"13.0.0.13"})
+            result = convert_mcp_tool_result(result)
+            print(f"Result3: {result}")
+
+        except Exception as e:
+            print(f"Thread Fail: {e}")
+
+    with asyncio.Runner() as runner:
+            runner.run(main())

{xgae-0.3.2 → xgae-0.3.3}/examples/agent/are/simulation/agents/xga/xga_agent.py

@@ -1,4 +1,5 @@
 import re
+import asyncio
 from typing import List, Dict, Any
 from typing_extensions import override
 
@@ -23,7 +24,7 @@ from are.simulation.agents.default_agent.base_agent import (
 
 from xgae.utils.llm_client import LLMConfig
 from xgae.gaia2.are_engine import ARETaskEngine
-from agent.are.simulation.agents.xga.xga_tool_box import XGAAreToolBox
+from are.simulation.agents.xga.xga_tool_box import XGAAreToolBox
 
 
 def pre_run_task_check(agent, iterations: int, llm_messages: List[Dict[str, Any]]):
@@ -205,8 +206,8 @@ class XGAAreAgent(BaseAgent):
 
     @override
     def execute_agent_loop(self) -> str | None | MMObservation:
-        import asyncio
-        asyncio.run(self.async_execute_agent_loop())
+        with asyncio.Runner() as runner:
+            runner.run(self.async_execute_agent_loop())
 
         # We have reached a termination condition, execute the termination method
         if self.termination_step.function is not None and not self.stop_event.is_set():

{xgae-0.3.2 → xgae-0.3.3}/examples/agent/are/simulation/agents/xga/xga_tool_box.py

@@ -10,6 +10,7 @@ from xgae.engine.engine_base import XGAError, XGAToolSchema, XGAToolResult, XGAT
 from xgae.engine.mcp_tool_box import XGAMcpToolBox
 
 from are.simulation.tools import Tool
+from are.simulation.agents.xga.mcp_tool_executor import convert_mcp_tool_result
 
 class XGAAreToolBox(XGAMcpToolBox):
     def __init__(self, are_tools: Dict[str, Tool]):
@@ -41,7 +42,7 @@ class XGAAreToolBox(XGAMcpToolBox):
 
             try:
                 tool_result = self.are_tools[full_tool_name](**args)
-                result = XGAToolResult(success=True, output=str(tool_result))
+                result = convert_mcp_tool_result(str(tool_result))
             except Exception as e:
                 error = f"Call ARE Tool '{tool_name}' error: {str(e)}"
                 logging.error(f"AreToolBox call_are_tool: {error}")

xgae-0.3.3/examples/agent/are/simulation/scenarios/scenario_bomc_fault/scenario.py

@@ -0,0 +1,184 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+
+import datetime
+import json
+import logging
+import os
+from typing import Any
+
+from dotenv import load_dotenv
+from are.simulation.apps.agent_user_interface import AgentUserInterface
+from are.simulation.apps.mcp.mcp_app import MCPApp
+from are.simulation.scenarios.scenario import Scenario, ScenarioValidationResult
+from are.simulation.scenarios.utils.env_utils import expand_env_vars
+
+from are.simulation.scenarios.utils.registry import register_scenario
+from are.simulation.types import EventRegisterer, event_registered
+
+# Set up logger
+logger = logging.getLogger(__name__)
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+
+@register_scenario("scenario_bomc_fault")
+class ScenarioBomcFault(Scenario):
+    start_time: float | None = datetime.datetime.now().timestamp()
+    duration: float | None = None
+
+    def init_and_populate_apps(self, *args, **kwargs) -> None:
+
+        # get apps from the demo
+        agui = AgentUserInterface()
+        self.apps = [agui]
+
+        # form task from universe params
+        self.start_time = datetime.datetime.now().timestamp()
+
+        # Load additional MCP apps from JSON file if specified
+        self._load_mcp_apps_from_json()
+
+
+    def build_events_flow(self) -> None:
+        """Define the sequence of events that will occur during the scenario"""
+
+        agui = self.get_typed_app(AgentUserInterface)
+
+        with EventRegisterer.capture_mode():
+            # User event: User requests task creation
+            event1 = agui.send_message_to_agent(
+                content="locate 10.0.0.1 fault and solution",
+            ).depends_on(None, delay_seconds=2)
+
+            oracle1 = (
+                agui.send_message_to_user(
+                    content="Fault Cause: Phone Recharge Application Crash; Solution: Restart Phone Recharge Application",
+                )
+                .oracle()
+                .depends_on(event1, delay_seconds=10)
+            )
+
+
+        self.events = [event1]
+
+
+    def validate(self, env) -> ScenarioValidationResult:
+        """
+        Validate that the scenario completed successfully.
+
+        Check that the agent properly interacted with our custom app.
+        """
+        try:
+            aui = env.get_app("AgentUserInterface")
+            msg = aui.get_last_message_from_agent()
+            content = msg.content
+            if "Phone Recharge Application Crash" in content:
+                return ScenarioValidationResult(success=True)
+            else:
+                return ScenarioValidationResult(success=False)
+        except Exception as e:
+            return ScenarioValidationResult(success=False, exception=e)
+
+
+    def _load_mcp_apps_from_json(self) -> None:
+        """
+        Load additional MCP apps from a JSON file specified in the environment variables.
+
+        The JSON file should follow the Claude MCP definition format with a ``mcpServers``
+        key containing server configurations. Environment variables in the JSON are
+        expanded using the current environment.
+
+        :return: None
+        """
+        # Get the JSON file path from environment variables
+        mcp_apps_json_path = os.environ.get("MCP_APPS_JSON_PATH")
+
+        if not mcp_apps_json_path:
+            return
+
+        # Ensure self.apps is initialized
+        if not hasattr(self, "apps") or self.apps is None:
+            self.apps = []
+
+        try:
+            with open(mcp_apps_json_path, "r") as f:
+                mcp_config = json.load(f)
+
+            if "mcpServers" not in mcp_config:
+                logger.warning(
+                    f"No 'mcpServers' key found in MCP apps JSON file: {mcp_apps_json_path}"
+                )
+                return
+
+            # Create MCP apps from the JSON configuration
+            for server_name, server_config in mcp_config["mcpServers"].items():
+                mcp_app = self._create_mcp_app(server_name, server_config)
+                if mcp_app:
+                    self.apps.append(mcp_app)
+                    logger.info(f"Added MCP app: {server_name}")
+
+        except Exception as e:
+            logger.error(f"Error loading MCP apps from JSON: {e}", exc_info=True)
+
+    def _create_mcp_app(self, name: str, config: dict[str, Any]) -> MCPApp | None:
+        """
+        Create an MCPApp instance from a server configuration.
+
+        Supports two types of MCP servers:
+
+        1. Local servers with command and arguments
+        2. Remote SSE servers with URL and headers
+
+        Environment variables in the configuration are expanded before creating the app.
+
+        :param name: The name of the MCP app
+        :type name: str
+        :param config: The server configuration from the JSON file
+        :type config: dict[str, Any]
+        :return: An MCPApp instance or None if creation fails
+        :rtype: MCPApp | None
+        """
+        try:
+            # Expand environment variables in the configuration
+            expanded_config = expand_env_vars(config, allowed=["HF_TOKEN"])
+
+            # Handle SSE remote servers
+            if expanded_config.get("type") == "sse" or "url" in expanded_config:
+                return MCPApp(
+                    name=name,
+                    server_url=expanded_config.get("url"),
+                    sse_headers=expanded_config.get("headers", {}),
+                )
+
+            # Handle local servers with command and args
+            elif "command" in expanded_config:
+                return MCPApp(
+                    name=name,
+                    server_command=expanded_config.get("command"),
+                    server_args=expanded_config.get("args", []),
+                    server_env=expanded_config.get("env", {}),
+                )
+
+            else:
+                logger.warning(f"Unsupported MCP server configuration for {name}")
+                return None
+
+        except Exception as e:
+            logger.error(f"Error creating MCP app {name}: {e}", exc_info=True)
+            return None
+
+
+# Before Run Scenario, should xage project , execute command:
+# 1. Vailid Success: uv run example-fault-tools
+# 2. Vailid Fail: uv run example-fault-tools --alarmtype 2
+if __name__ == "__main__":
+    from are.simulation.scenarios.utils.cli_utils import run_and_validate
+
+    run_and_validate(ScenarioBomcFault())

{xgae-0.3.2 → xgae-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xgae"
-version = "0.3.2"
+version = "0.3.3"
 description = "Extreme General Agent Engine"
 readme = "README.md"
 requires-python = ">=3.11"

{xgae-0.3.2 → xgae-0.3.3}/uv.lock

@@ -3008,7 +3008,7 @@ wheels = [
 
 [[package]]
 name = "xgae"
-version = "0.3.2"
+version = "0.3.3"
 source = { editable = "." }
 dependencies = [
     { name = "colorlog" },

xgae-0.3.2/examples/agent/are/simulation/agents/xga/README.md

@@ -1,30 +0,0 @@
-## GAIA2 ARE Support
-### How to add XGAE to ARE Project
-- add xgae==0.3.2 to ARE requirements.txt
-  - uv pip install -r requirements.txt
-    - modify ARE 'AgentBuilder' and 'AgentConfigBuilder' class, add "xga" type agent
-      ```
-      File: agent_builder.py
-          class AgentBuilder:
-            def list_agents(self) -> list[str]:
-              return ["default", "xga"]
-            
-            def build():
-                ...
-                agent_name = agent_config.get_agent_name()
-                if agent_name in ["default", "xga"]:
-                    # add xga agent code
-      
-      File: agent_config_builder.py
-        class AgentConfigBuilder:
-            def build():
-                if agent_name in["default", "xga"]:
-      ```
-
-- modify ARE .env, add XGAE .env config, refer to env.example 
-- copy XGAE package 'mcpservers' and 'templates' directory to ARE project root  
-
-### Run XGA Agent in ARE
-  ```
-uv run are-run -e -s scenario_find_image_file -a xga --model openai/qwen3-235b-a22b --provider llama-api --output_dir ./output
-  ```