xgae 0.3.1__tar.gz → 0.3.3__tar.gz

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

@@ -1,8 +1,20 @@
-## [0.3.0] - 2025-10-24
+## [0.3.3] - 2025-10-30
 ### Added
-- Support GAIA2 ARE Engine
+- 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
+### Modified
+- ARETaskEngine
+
+
+## [0.3.0] - 2025-10-22
+### Added
+- Support GAIA2 ARE: ARETaskEngine
+
 
 ## [0.2.4] - 2025-9-23
 ### Modified

xgae-0.3.3/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: xgae
+Version: 0.3.3
+Summary: Extreme General Agent Engine
+Requires-Python: >=3.11
+Requires-Dist: colorlog>=6.9.0
+Requires-Dist: langchain-mcp-adapters>=0.1.9
+Requires-Dist: langfuse==2.60.9
+Requires-Dist: litellm>=1.71.1
+Requires-Dist: mcp>=1.11.0
+Provides-Extra: examples
+Requires-Dist: chromadb==1.1.0; extra == 'examples'
+Requires-Dist: langchain-community==0.3.29; extra == 'examples'
+Requires-Dist: langgraph==0.6.5; extra == 'examples'
+Description-Content-Type: text/markdown
+
+## XGAE: Extreme General Agent Engine 
+### Functional Features
+- Support Custom prompt and external MCP Tools
+- Support Langfuse
+- Support Langgraph
+- 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
+
+### Non-Functional Features
+- Faster than SUNA Engine's speed
+- Architecture is lighter than SUNA Engine
+- Separate tools from Agent Engine
+
+### Examples
+- langgraph:  Build React mode Langgraph Agent by XGA Engine
+- are: Build GAIA2 ARE Agent by XGA Engine
+- engine: Use XGA Engine in various scenarios
+- tools: Simulation tools for example and test

xgae-0.3.3/README.md

@@ -0,0 +1,20 @@
+## XGAE: Extreme General Agent Engine 
+### Functional Features
+- Support Custom prompt and external MCP Tools
+- Support Langfuse
+- Support Langgraph
+- 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
+
+### Non-Functional Features
+- Faster than SUNA Engine's speed
+- Architecture is lighter than SUNA Engine
+- Separate tools from Agent Engine
+
+### Examples
+- langgraph:  Build React mode Langgraph Agent by XGA Engine
+- are: Build GAIA2 ARE Agent by XGA Engine
+- engine: Use XGA Engine in various scenarios
+- tools: Simulation tools for example and test

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.3/examples/agent/are/simulation/agents/xga/env.example

@@ -0,0 +1,43 @@
+# Certificate paths may vary on different types of machines.
+ARE_SIMULATION_SSL_CERT_PATH=
+ARE_SIMULATION_SSL_KEY_PATH=
+
+# ARE_SIMULATION UI server.
+ARE_SIMULATION_SERVER_HOSTNAME=localhost
+ARE_SIMULATION_SERVER_PORT=8080
+
+# ARE_SIMULATION UI client.
+ARE_SIMULATION_CLIENT_HOSTNAME=localhost
+ARE_SIMULATION_CLIENT_PORT=8088
+ARE_SIMULATION_CLIENT_BACKEND_URL=https://${ARE_SIMULATION_SERVER_HOSTNAME}:${ARE_SIMULATION_SERVER_PORT}
+
+# Scenario discovery
+# Format: "dir1,dir2,dir3,..."
+# Example: "/path/to/custom/scenarios,/another/path"
+ARE_SCENARIO_DIRECTORIES="/Users/sharkystar/DevProjects/are"
+
+# Models.
+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
+LOG_LEVEL=INFO
+LOG_FILE=log/xgae.log
+LOG_ENABLE=True
+
+LLM_MAX_TOKENS=16384
+LLM_TEMPERATURE=0
+LLM_MAX_RETRIES=1
+LLM_STREAM=True
+LLM_ENABLE_THINKING=False
+
+LLM_LANGFUSE_ENABLE=False
+
+
+# TASK_ENGINE
+USE_ASSISTANT_CHUNK_MSG=False

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.3/examples/agent/are/simulation/agents/xga/xga_agent.py

@@ -0,0 +1,290 @@
+import re
+import asyncio
+from typing import List, Dict, Any
+from typing_extensions import override
+
+from are.simulation.agents.are_simulation_agent import AgentStoppedException
+from are.simulation.agents.llm.types import MMObservation
+from are.simulation.agents.multimodal import Attachment, attachments_to_pil
+from are.simulation.agents.agent_log import (
+    LLMInputLog,
+    LLMOutputThoughtActionLog,
+    StepLog,
+    StopLog,
+    SystemPromptLog,
+    ThoughtLog,
+    ToolCallLog,
+    FinalAnswerLog
+)
+from are.simulation.agents.default_agent.base_agent import (
+    BaseAgent,
+    RunningState,
+    get_offset_from_time_config_mode
+)
+
+from xgae.utils.llm_client import LLMConfig
+from xgae.gaia2.are_engine import ARETaskEngine
+from are.simulation.agents.xga.xga_tool_box import XGAAreToolBox
+
+
+def pre_run_task_check(agent, iterations: int, llm_messages: List[Dict[str, Any]]):
+    try:
+        agent.logger.info(f"\n\n------  Starting Run Task Iteration {iterations}...   ------")
+
+        if iterations == 0:
+            agent.system_prompt = agent.task_engine.task_prompt
+            agent.logger.info(f"------  SYSTEM_PROMPT   ------ \n{agent.system_prompt}\n")
+            agent.append_agent_log(
+                SystemPromptLog(
+                    content     = agent.system_prompt,
+                    timestamp   = agent.make_timestamp(),
+                    agent_id    = agent.agent_id,
+                )
+            )
+
+        agent.append_agent_log(
+            StepLog(
+                iteration   = agent.iterations,
+                timestamp   = agent.make_timestamp(),
+                agent_id    = agent.agent_id,
+            )
+        )
+
+        if agent.stop_event.is_set():
+            agent.logger.info(f"pre_run_task_check[{iterations}]: Recv Stop Event before condition, raise AgentStoppedException")
+            raise AgentStoppedException("Agent stopped.")
+
+        # Execute a pre_step() function if it exists
+        for conditional_step in agent.conditional_pre_steps:
+            if conditional_step.condition is None or conditional_step.condition(agent):
+                conditional_step.function(agent)
+
+        if agent.stop_event.is_set():
+            agent.logger.info(f"pre_run_task_check[{iterations}]: Recv Stop Event after condition, raise AgentStoppedException")
+            raise AgentStoppedException("Agent stopped.")
+
+        # Begin step()
+        agent.append_agent_log(
+            LLMInputLog(
+                content     = llm_messages,
+                timestamp   = agent.make_timestamp(),
+                agent_id    = agent.agent_id
+            )
+        )
+
+        if agent.simulated_generation_time_config is not None:
+            if agent.pause_env is None:
+                raise ValueError("pause_env is not set")
+            agent.pause_env()
+    except Exception as e:
+        agent.log_error(e)
+        agent.logger.info(f"pre_run_task_check[{iterations}]: Exception Occur, Stop task")
+        agent.task_engine.stop_task()
+
+
+def post_run_task_check(agent, iterations: int, llm_response: Dict[str, Any]):
+    try:
+        agent.logger.info(f"------  LLM Response Iteration [{iterations}]   ------ \n{llm_response}\n")
+
+        llm_output = str(llm_response)
+
+        # Resume the environment after the generation of a thought/action if needed
+        if agent.simulated_generation_time_config is not None:
+            if agent.resume_env is None:
+                raise ValueError("resume_env is not set")
+
+            offset = get_offset_from_time_config_mode(
+                time_config = agent.simulated_generation_time_config,
+                completion_duration = 0,
+            )
+            agent.logger.info(f"post_run_task_check[{iterations}]: Resuming environment with {offset} offset")
+            agent.resume_env(offset)
+
+        metadata = {}
+        agent.append_agent_log(
+            LLMOutputThoughtActionLog(
+                content             = llm_output,
+                timestamp           = agent.make_timestamp(),
+                agent_id            = agent.agent_id,
+                prompt_tokens       = metadata.get("prompt_tokens", 0),
+                completion_tokens   = metadata.get("completion_tokens", 0),
+                total_tokens        = metadata.get("total_tokens", 0),
+                reasoning_tokens    = metadata.get("reasoning_tokens", 0),
+                completion_duration = metadata.get("completion_duration", 0),
+            )
+        )
+        # end step()
+
+        if agent.stop_event.is_set():
+            agent.logger.info(f"post_run_task_check[{iterations}]: Recv Stop Event, raise AgentStoppedException")
+            raise AgentStoppedException("Agent stopped.")
+
+        # Execute a post_step() function if it exists (polling the Meta Agents Research Environments notifications for example)
+        for conditional_step in agent.conditional_post_steps:
+            if conditional_step.condition is None or conditional_step.condition(agent):
+                conditional_step.function(agent)
+    except Exception as e:
+        agent.log_error(e)
+        agent.logger.info(f"post_run_task_check[{iterations}]: Exception Occur, Stop task")
+        agent.task_engine.stop_task()
+    finally:
+        if agent.simulated_generation_time_config and agent.resume_env:
+            agent.resume_env(0.0)  # Resume without advancing time
+
+        agent.iterations += 1
+        agent.planning_counter += 1
+
+
+def terminate_task_check(agent, iterations: int) -> bool:
+    is_terminate_task = False
+
+    try:
+        if agent.termination_step.condition:
+            is_terminate_task = agent.termination_step.condition(agent)
+            if is_terminate_task:
+                agent.logger.info(f"terminate_task_check[{iterations}]: termination_step.condition is True")
+    except Exception as e:
+        agent.log_error(e)
+
+    return is_terminate_task
+
+
+class XGAAreAgent(BaseAgent):
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.task_engine: ARETaskEngine = None
+
+
+    @override
+    def initialize(self, attachments: list[Attachment] | None = None, **kwargs) -> None:
+        self.logs = []
+        self.iterations = 0
+        self.planning_counter = 0
+
+        tool_box = XGAAreToolBox(self.tools)
+
+        _system_prompt = "\n\n".join(prompt for prompt in self.init_system_prompts.values())
+        pattern = r'<general_instructions>(.*?)</general_instructions>'
+        prompt_are_general = re.search(pattern, _system_prompt, re.DOTALL)
+        if prompt_are_general:
+            prompt_are_general = prompt_are_general.group(1).strip()
+        else:
+            prompt_are_general = _system_prompt
+
+        model_config = self.llm_engine.model_config
+        llm_config = LLMConfig(
+            model       = model_config.model_name,
+            api_key     = model_config.api_key,
+            api_base    = model_config.endpoint
+        )
+        self.task_engine =  ARETaskEngine(
+            agent               = self,
+            agent_id            = self.agent_id,
+            system_prompt       = prompt_are_general,
+            max_auto_run        = self.max_iterations,
+            llm_config          = llm_config,
+            tool_box            = tool_box,
+            pre_run_task_fn     = pre_run_task_check,
+            post_run_task_fn    = post_run_task_check,
+            terminate_task_fn   = terminate_task_check,
+        )
+
+        # Reload the agent state if logs are provided
+        start_logs = kwargs.pop("start_logs", [])
+        if start_logs:
+            self.replay(start_logs)
+
+        # Include additional image PILs directly into state stack.
+        if attachments:
+            images = attachments_to_pil(attachments)
+            self.action_executor.inject_state({f"image_{i}": image for i, image in enumerate(images)})
+            self.logger.debug(f"XGAAreAgent initialize: Injecting images into states for {len(images)} images")
+            self.logger.debug(f"XGAAreAgent initialize: New Keys {','.join(self.action_executor.state.keys())}")
+
+        self.initialized = True
+
+
+    @override
+    def execute_agent_loop(self) -> str | None | MMObservation:
+        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():
+            return self.termination_step.function(self)
+
+
+    async def async_execute_agent_loop(self) -> str | None | MMObservation:
+        chunks = []
+        async for chunk in self.task_engine.run_task(task_input={"role": "user", "content": self.task}):
+            chunks.append(chunk)
+            chunk_type = chunk['type']
+            if chunk_type== "status":
+                status_content = chunk['content']
+                status_type = status_content['status_type']
+                if status_type == "error":
+                    error_msg = chunk.get('message')
+                    self.logger.warning(f"XGAAreAgent execute_agent_loop: Fatal error - {error_msg}")
+                    self.log_error(error_msg)
+                elif status_type == "stop":
+                    error_msg = chunk.get('message')
+                    self.logger.warning("XGAAreAgent execute_agent_loop: Agent stopped.")
+                    self.append_agent_log(
+                        StopLog(
+                            content     = f"Agent stopped - {error_msg}",
+                            timestamp   = self.make_timestamp(),
+                            agent_id    = self.agent_id,
+                        )
+                    )
+                elif status_type == "tool_started":
+                    function_name = status_content['function_name']
+                    self.append_agent_log(
+                        ThoughtLog(
+                            content     = f"To complete task, should call '{function_name}' tool",
+                            timestamp   = self.make_timestamp(),
+                            agent_id    = self.agent_id,
+                        )
+                    )
+            elif chunk_type == "tool":
+                tool_content = chunk['content']
+                tool_execution = tool_content.get('tool_execution')
+                self.append_agent_log(
+                    ToolCallLog(
+                        tool_name       = tool_execution.get('function_name'),
+                        tool_arguments  = tool_execution.get('arguments'),
+                        timestamp       = self.make_timestamp(),
+                        agent_id        = self.agent_id,
+                    )
+                )
+            #print(chunk)
+
+        final_result = self.task_engine.parse_final_result(chunks)
+        print(f"\n\nFINAL_RESULT: {final_result}")
+
+        # Send Final Result to user
+        args = {
+            'content': final_result['content']
+        }
+        self.tools['AgentUserInterface__send_message_to_user'](**args)
+        self.append_agent_log(
+            ToolCallLog(
+                tool_name       = 'AgentUserInterface__send_message_to_user',
+                tool_arguments  = args,
+                timestamp       = self.make_timestamp(),
+                agent_id        = self.agent_id,
+            )
+        )
+
+        # Return Final Result
+        if final_result['type'] == "error":
+            self.custom_state["running_state"] = RunningState.FAILED
+        else:
+            self.custom_state["running_state"] = RunningState.TERMINATED
+
+        self.append_agent_log(
+            FinalAnswerLog(
+                content     = final_result['content'],
+                timestamp   = self.make_timestamp(),
+                agent_id    = self.agent_id
+            )
+        )

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

@@ -0,0 +1,26 @@
+from are.simulation.agents.are_simulation_agent_config import ARESimulationReactBaseAgentConfig
+from are.simulation.agents.default_agent.steps.are_simulation import get_are_simulation_update_pre_step
+from are.simulation.agents.default_agent.termination_methods.are_simulation import get_gaia2_termination_step
+from are.simulation.agents.default_agent.tools.json_action_executor import JsonActionExecutor
+from are.simulation.agents.llm.llm_engine import LLMEngine
+
+from agent.are.simulation.agents.xga.xga_agent import XGAAreAgent
+
+
+def xga_simulation_react_xml_agent(
+    llm_engine: LLMEngine, base_agent_config: ARESimulationReactBaseAgentConfig
+):
+    return XGAAreAgent(
+        llm_engine=llm_engine,
+        tools={},
+        system_prompts={
+            "system_prompt": str(base_agent_config.system_prompt),
+        },
+        termination_step=get_gaia2_termination_step(),
+        max_iterations=base_agent_config.max_iterations,
+        action_executor=JsonActionExecutor(  # Just for compatible BaseAgent， useless
+            use_custom_logger=base_agent_config.use_custom_logger
+        ),
+        conditional_pre_steps=[get_are_simulation_update_pre_step()],
+        use_custom_logger=base_agent_config.use_custom_logger,
+    )

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

@@ -0,0 +1,110 @@
+import json
+import logging
+
+from typing import List, Any, Dict, Optional
+from typing_extensions import override
+
+from langchain_mcp_adapters.tools import load_mcp_tools
+
+from xgae.engine.engine_base import XGAError, XGAToolSchema, XGAToolResult, XGAToolType
+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]):
+        super().__init__()
+        self.are_tools = are_tools
+        self._is_loaded_are_tool_schemas = False
+
+
+    @override
+    async def init_tool_schemas(self):
+        await self._load_mcp_tools_schema()
+        self._load_are_tools_schema()
+
+
+    @override
+    async def call_tool(self, task_id: str, tool_name: str, args: Optional[Dict[str, Any]] = None) -> XGAToolResult:
+        if tool_name == "end_task":
+            server_name = self.GENERAL_MCP_SERVER_NAME
+        else:
+            task_tool_schemas = self.task_tool_schemas.get(task_id, {})
+            tool_schema = task_tool_schemas.get(tool_name, None)
+            if tool_schema is None:
+                raise XGAError(f"MCP tool not found: '{tool_name}'")
+            server_name = tool_schema.server_name
+
+        tool_type = self._get_tool_type(server_name)
+        if tool_type == "custom":  # ARE Tools
+            full_tool_name = server_name + "__" + tool_name
+
+            try:
+                tool_result = self.are_tools[full_tool_name](**args)
+                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}")
+                result = XGAToolResult(success=False, output=error)
+        else:
+            async with self._mcp_client.session(server_name) as session:
+                tools = await load_mcp_tools(session)
+                mcp_tool = next((t for t in tools if t.name == tool_name), None)
+
+                if mcp_tool:
+                    tool_args = args or {}
+
+                    if tool_type == "general" or tool_type == "agent":
+                        tool_args = dict({'task_id': task_id}, **tool_args)
+
+                    try:
+                        tool_result = await mcp_tool.arun(tool_args)
+                        if tool_type == "general":
+                            tool_result = json.loads(tool_result)
+                            result = XGAToolResult(success=tool_result['success'], output=str(tool_result['output']))
+                        else:
+                            result = XGAToolResult(success=True, output=str(tool_result))
+                    except Exception as e:
+                        error = f"Call MCP Tool '{tool_name}' error: {str(e)}"
+                        logging.error(f"AreToolBox call_mcp_tool: {error}")
+                        result = XGAToolResult(success=False, output=error)
+                else:
+                    error = f"No MCP tool found with name: {tool_name}"
+                    logging.info(f"AreToolBox call_mcp_tool: error={error}")
+                    result =  XGAToolResult(success=False, output=error)
+
+        return result
+
+
+    async def reload_mcp_tools_schema(self) -> None:
+        self._is_loaded_mcp_tool_schemas = False
+        self._is_loaded_are_tool_schemas = False
+        await self.init_tool_schemas()
+
+
+    def _load_are_tools_schema(self) -> None:
+        if not self._is_loaded_are_tool_schemas:
+            for are_tool in self.are_tools.values():
+                full_tool_name = are_tool.name
+                server_name , tool_name = full_tool_name.split("__")
+                tool_type :XGAToolType = "custom"
+                input_schema = {
+                    'properties': are_tool.inputs,
+                    'required': []
+                }
+
+                tool_schema = XGAToolSchema(tool_name       = tool_name,
+                                            tool_type       = tool_type,
+                                            server_name     = server_name,
+                                            description     = are_tool.description,
+                                            input_schema    = input_schema,
+                                            metadata        = {}
+                                            )
+                if server_name not in self.mcp_tool_schemas:
+                    self.mcp_tool_schemas[server_name] = []
+                self.mcp_tool_schemas[server_name].append(tool_schema)
+                if server_name not in self.mcp_server_names:
+                    self.mcp_server_names.append(server_name)
+
+        self._is_loaded_are_tool_schemas = True

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.1 → xgae-0.3.3}/pyproject.toml

@@ -1,15 +1,15 @@
 [project]
 name = "xgae"
-version = "0.3.1"
+version = "0.3.3"
 description = "Extreme General Agent Engine"
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
-    "colorlog==6.9.0",
-    "litellm==1.71.1",
-    "mcp==1.11.0",
+    "colorlog>=6.9.0",
+    "litellm>=1.71.1",
+    "mcp>=1.11.0",
     "langfuse==2.60.9",
-    "langchain-mcp-adapters==0.1.9",
+    "langchain-mcp-adapters>=0.1.9",
 ]
 
 

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

@@ -3008,7 +3008,7 @@ wheels = [
 
 [[package]]
 name = "xgae"
-version = "0.3.1"
+version = "0.3.3"
 source = { editable = "." }
 dependencies = [
     { name = "colorlog" },
@@ -3028,13 +3028,13 @@ examples = [
 [package.metadata]
 requires-dist = [
     { name = "chromadb", marker = "extra == 'examples'", specifier = "==1.1.0" },
-    { name = "colorlog", specifier = "==6.9.0" },
+    { name = "colorlog", specifier = ">=6.9.0" },
     { name = "langchain-community", marker = "extra == 'examples'", specifier = "==0.3.29" },
-    { name = "langchain-mcp-adapters", specifier = "==0.1.9" },
+    { name = "langchain-mcp-adapters", specifier = ">=0.1.9" },
     { name = "langfuse", specifier = "==2.60.9" },
     { name = "langgraph", marker = "extra == 'examples'", specifier = "==0.6.5" },
-    { name = "litellm", specifier = "==1.71.1" },
-    { name = "mcp", specifier = "==1.11.0" },
+    { name = "litellm", specifier = ">=1.71.1" },
+    { name = "mcp", specifier = ">=1.11.0" },
 ]
 provides-extras = ["examples"]
 

{xgae-0.3.1 → xgae-0.3.3}/xgae/engine/mcp_tool_box.py

@@ -167,12 +167,14 @@ class XGAMcpToolBox(XGAToolBox):
                             param_properties.pop('title', None)
 
                     metadata = tool.metadata or {}
-                    tool_schema = XGAToolSchema(tool_name=tool.name,
-                                                tool_type=tool_type,
-                                                server_name=server_name,
-                                                description=tool.description,
-                                                input_schema=input_schema,
-                                                metadata=metadata)
+                    tool_schema = XGAToolSchema(
+                        tool_name       = tool.name,
+                        tool_type       = tool_type,
+                        server_name     = server_name,
+                        description     = tool.description,
+                        input_schema    = input_schema,
+                        metadata        = metadata
+                    )
                     self.mcp_tool_schemas[server_name].append(tool_schema)
 
             self._is_loaded_mcp_tool_schemas = True

{xgae-0.3.1 → xgae-0.3.3}/xgae/engine/prompt_builder.py

@@ -83,9 +83,10 @@ class XGAPromptBuilder():
             tool_info = ""
             for tool_schema in tool_schemas:
                 description = tool_schema.description if tool_schema.description else 'No description available'
-                tool_info += f"- **{tool_schema.tool_name}**: {description}\n"
+                tool_info += f"- {tool_schema.tool_name}: {description}\n"
                 parameters = tool_schema.input_schema.get('properties', {})
-                tool_info += f"  Parameters: {parameters}\n"
+                tool_info += f"   Parameters: {parameters}\n"
+                tool_info += "\n"
             tool_prompt = tool_prompt.replace("{tool_schemas}", tool_info)
 
         return tool_prompt

{xgae-0.3.1 → xgae-0.3.3}/xgae/utils/llm_client.py

@@ -51,6 +51,9 @@ class LLMClient:
         self._init_langfuse()
 
         llm_config = llm_config or LLMConfig()
+        if llm_config.get('model') and llm_config.get('model_name') is None:
+            llm_config['model_name'] = llm_config.get('model')
+
         self.max_retries = int(os.getenv('LLM_MAX_RETRIES', 1))
 
         env_llm_model           = os.getenv('LLM_MODEL', "openai/qwen3-235b-a22b")

xgae-0.3.1/PKG-INFO

@@ -1,14 +0,0 @@
-Metadata-Version: 2.4
-Name: xgae
-Version: 0.3.1
-Summary: Extreme General Agent Engine
-Requires-Python: >=3.11
-Requires-Dist: colorlog==6.9.0
-Requires-Dist: langchain-mcp-adapters==0.1.9
-Requires-Dist: langfuse==2.60.9
-Requires-Dist: litellm==1.71.1
-Requires-Dist: mcp==1.11.0
-Provides-Extra: examples
-Requires-Dist: chromadb==1.1.0; extra == 'examples'
-Requires-Dist: langchain-community==0.3.29; extra == 'examples'
-Requires-Dist: langgraph==0.6.5; extra == 'examples'