xgae 0.1.20__tar.gz → 0.3.9__tar.gz

{xgae-0.1.20 → xgae-0.3.9}/.env

@@ -12,6 +12,7 @@ LANGFUSE_HOST=https://cloud.langfuse.com
 
 # LLM
 LLM_MODEL=openai/qwen3-235b-a22b
+#LLM_MODEL=openai/qwen3-4b
 LLM_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
 LLM_API_KEY=
 LLM_MAX_TOKENS=16384

xgae-0.3.9/CHANGELOG.md

@@ -0,0 +1,111 @@
+## [0.3.9] - 2025-11-4
+### Added
+- ✅ GAIA2 ARE Example:  Add new prompt template, Leading over ARE 'default agent'
+### Modified
+- GAIA2 ARE Example: Refact prompt templates, use MD format
+- GAIA2 ARE Example:  XGAArePromptBuilder add 'prior' template mode
+- ARE Engine: remove useless 'system_prompt' init parameter
+
+
+## [0.3.5] - 2025-11-1
+### Added
+- GAIA2 ARE Example:  XGAArePromptBuilder, Use MCP tool format general tool construct prompt
+### Modified
+- GAIA2 ARE Example: Refact code struct and class name
+- GAIA2 ARE Example: Optimize prompt template 
+- ARETaskEngine: add prompt_builder init parameter
+
+
+## [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
+### Modified
+- ARETaskEngine
+
+
+## [0.3.0] - 2025-10-22
+### Added
+- Support GAIA2 ARE: ARETaskEngine
+
+
+## [0.2.4] - 2025-9-23
+### Modified
+- Refact project structure
+
+
+## [0.2.3] - 2025-9-19
+### Modified
+- CustomPromptRag: remove FastEmbedEmbeddings, use 'text-embedding-v3' model for chinese, avoid download 'bge-small-zh-v1.5'
+
+
+## [0.2.1] - 2025-9-17
+### Added
+- Example ReflectionAgent: add CustomPromptRag, use FastEmbedEmbeddings and 'BAAI/bge-small-zh-v1.5' model
+### Modified
+- pyproject.toml: add [project.optional-dependencies] 'examples'
+
+
+## [0.2.0] - 2025-9-10
+### Added
+- Agent Engine release 0.2
+- Example: Langgraph ReflectionAgent release 0.2
+### Fixed
+- Agent Engine: call mcp tool fail, call 'ask' tool again and again
+- Example Langgraph ReflectionAgent: retry on 'ask', user_input is ask answer
+
+
+## [0.1.20] - 2025-9-9
+### Added
+- Example: Langgraph ReflectionAgent add final_result_agent 
+
+
+## [0.1.19] - 2025-9-8
+### Added
+- Example: Langgraph ReflectionAgent release V1, full logic but no final result agent and tool select agent
+
+
+# Release Changelog
+## [0.1.18] - 2025-9-3
+### Added
+- Support Agent tools
+
+
+## [0.1.17] - 2025-9-1
+### Target
+- Saved for XGATaskEngine base version
+### Changed
+- Delete StreamTaskResponser tool_exec_on_stream model code
+
+
+## [0.1.15] - 2025-9-1
+### Target
+- Saved for StreamResponser tool_exec_on_stream mode, next release will be abolished
+### Changed
+- Refact TaskResponseProcessor, XGATaskEngine
+### Fixed
+- Fix finish_reason judge logic
+
+
+## [0.1.14] - 2025-8-31
+### Target
+- First complete version is merged 
+### Changed
+- StreamTaskResponser first version
+
+## [0.1.10] - 2025-8-28
+### Target
+- NonStream mode release is completed
+### Changed
+- StreamTaskResponser is original
+- NonStreamTaskResponser first version is completed 
+- Langfuse use 2.x, match for LiteLLM package
+
+## [0.1.7] - 2025-8-25
+### Target
+- Langfuse use 3.x package

xgae-0.3.9/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: xgae
+Version: 0.3.9
+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, Leading over ARE 'default agent'
+- 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.9/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, Leading over ARE 'default agent'
+- 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.9/examples/agent/are/README.md

@@ -0,0 +1,56 @@
+## GAIA2 ARE Support
+### How to add XGAE to ARE Project
+- add xgae==0.3.x 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:
+                    ...
+                    # original code don't support async engine loop
+                    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  
+- You can use prompt template by two modes, 'prior' mode is leading over ARE 'default agent'
+
+### Run XGA Agent in ARE
+  ```
+# Run ARE Code Scenario
+uv run are-run -e -s scenario_apps_tutorial -a xga --model openai/qwen3-235b-a22b --provider llama-api --output_dir ./output --log-level INFO
+
+# Run Custom Scenario
+uv run example-fault-tools 
+uv run are-run -e -s scenario_bomc_fault -a xga --model openai/qwen3-235b-a22b --provider llama-api --output_dir ./output --log-level INFO
+
+# Run HF Scenario Benchmark
+uv run are-benchmark run -a xga --dataset ./scenarios --config mini --model openai/deepseek-v3.1 --provider llama-api --output_dir ./output --limit 1 --num_runs 1 --max_concurrent_scenarios 1 --log-level INFO
+
+# Run GUI
+uv run are-gui -a xga -s scenario_find_image_file --model openai/qwen3-235b-a22b --provider llama-api --log-level INFO
+
+  ```

xgae-0.3.9/examples/agent/are/are/simulation/agents/xga/are_agent.py

@@ -0,0 +1,289 @@
+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.are_tool_box import XGAAreToolBox
+from are.simulation.agents.xga.are_prompt_builder import XGAArePromptBuilder
+
+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)
+
+        general_system_prompt = "\n\n".join(prompt for prompt in self.init_system_prompts.values())
+        prompt_builder = XGAArePromptBuilder(general_system_prompt, "prior")
+
+        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,
+            max_auto_run        = self.max_iterations,
+            llm_config          = llm_config,
+            tool_box            = tool_box,
+            prompt_builder      = prompt_builder,
+            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 chunk_type == "assistant":
+                llm_content  = chunk['content']['content']
+                if "<thought>" in llm_content:
+                    thought_content = re.search(r'<thought>(.*?)</thought>', llm_content, re.DOTALL).group(1).strip()
+                    if thought_content:
+                        self.append_agent_log(
+                            ThoughtLog(
+                                content     = thought_content,
+                                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.9/examples/agent/are/are/simulation/agents/xga/are_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 are.simulation.agents.xga.are_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.9/examples/agent/are/are/simulation/agents/xga/are_prompt_builder.py

@@ -0,0 +1,48 @@
+import re
+from typing_extensions import override
+from typing import Optional, List, Literal
+
+from xgae.engine.engine_base import XGAToolSchema
+from xgae.engine.prompt_builder import XGAPromptBuilder
+
+class XGAArePromptBuilder(XGAPromptBuilder):
+    def __init__(self,
+                 general_system_prompt: Optional[str],
+                 prompt_template_mode: Literal["basic", "prior"] = "prior"
+        ):
+        system_prompt = ""
+        if prompt_template_mode == "basic":
+            system_prompt = self.build_general_system_prompt(general_system_prompt)
+
+        super().__init__(system_prompt)
+
+        self.prompt_template_mode = prompt_template_mode
+
+
+    def build_general_system_prompt(self, _system_prompt: str)-> str:
+        pattern = r'<general_instructions>(.*?)</general_instructions>'
+        prompt_are_general = re.search(pattern, _system_prompt, re.DOTALL)
+        prompt_header = "# CORE IDENTITY\n"
+        if prompt_are_general:
+            prompt_are_general = prompt_header + prompt_are_general.group(1).strip() + "\n\n"
+        else:
+            prompt_are_general = prompt_header + _system_prompt  + "\n\n"
+        return prompt_are_general
+
+
+    @override
+    def build_general_tool_prompt(self, tool_schemas: List[XGAToolSchema])-> str:
+        tool_prompt = ""
+        if self.prompt_template_mode == "basic":
+            tool_prompt = self.build_mcp_tool_prompt("templates/system_tool_prompt_template.md", tool_schemas)
+        return tool_prompt
+
+
+    @override
+    def build_custom_tool_prompt(self, tool_schemas:List[XGAToolSchema])-> str:
+        if self.prompt_template_mode == "basic":
+            tool_prompt = self.build_mcp_tool_prompt("templates/app_tool_prompt_template.md", tool_schemas)
+        else:
+            tool_prompt = self.build_mcp_tool_prompt("templates/are_prompt_template.md", tool_schemas)
+        return tool_prompt
+