xgae 0.3.3__tar.gz → 0.3.4__tar.gz

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

@@ -1,7 +1,15 @@
+## [0.3.4] - 2025-11-1
+- 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
+- GAIA2 ARE MCP: Support Custom MCP Apps, example_mcp_apps.json
 
 
 ## [0.3.2] - 2025-10-24

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xgae
-Version: 0.3.3
+Version: 0.3.4
 Summary: Extreme General Agent Engine
 Requires-Python: >=3.11
 Requires-Dist: colorlog>=6.9.0

{xgae-0.3.3/examples/agent/are/simulation/agents/xga → xgae-0.3.4/examples/agent/are}/README.md

@@ -21,18 +21,18 @@
             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)
-                
-
-```
+    ```
+    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 

xgae-0.3.3/examples/agent/are/simulation/agents/xga/xga_agent.py → xgae-0.3.4/examples/agent/are/are/simulation/agents/xga/are_agent.py

@@ -24,8 +24,8 @@ from are.simulation.agents.default_agent.base_agent import (
 
 from xgae.utils.llm_client import LLMConfig
 from xgae.gaia2.are_engine import ARETaskEngine
-from are.simulation.agents.xga.xga_tool_box import XGAAreToolBox
-
+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:
@@ -166,10 +166,11 @@ class XGAAreAgent(BaseAgent):
         _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)
+        prompt_header = "#CORE IDENTITY & CAPABILITIES\n"
         if prompt_are_general:
-            prompt_are_general = prompt_are_general.group(1).strip()
+            prompt_are_general = prompt_header + prompt_are_general.group(1).strip() + "\n\n"
         else:
-            prompt_are_general = _system_prompt
+            prompt_are_general = prompt_header + _system_prompt  + "\n\n"
 
         model_config = self.llm_engine.model_config
         llm_config = LLMConfig(
@@ -177,6 +178,9 @@ class XGAAreAgent(BaseAgent):
             api_key     = model_config.api_key,
             api_base    = model_config.endpoint
         )
+
+        prompt_builder = XGAArePromptBuilder(prompt_are_general)
+
         self.task_engine =  ARETaskEngine(
             agent               = self,
             agent_id            = self.agent_id,
@@ -184,6 +188,7 @@ class XGAAreAgent(BaseAgent):
             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,
@@ -236,15 +241,18 @@ class XGAAreAgent(BaseAgent):
                             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 == "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')

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

@@ -4,7 +4,7 @@ from are.simulation.agents.default_agent.termination_methods.are_simulation impo
 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
+from are.simulation.agents.xga.are_agent import XGAAreAgent
 
 
 def xga_simulation_react_xml_agent(

xgae-0.3.4/examples/agent/are/are/simulation/agents/xga/are_prompt_builder.py

@@ -0,0 +1,19 @@
+from typing_extensions import override
+from typing import Optional, List
+
+from xgae.engine.engine_base import XGAToolSchema
+from xgae.engine.prompt_builder import XGAPromptBuilder
+
+class XGAArePromptBuilder(XGAPromptBuilder):
+    def __init__(self, system_prompt: Optional[str] = None):
+        super().__init__(system_prompt)
+
+
+    @override
+    def build_general_tool_prompt(self, tool_schemas: List[XGAToolSchema]) -> str:
+        tool_prompt = self.build_mcp_tool_prompt("templates/general_tool_prompt_template.txt", tool_schemas)
+        return tool_prompt
+
+
+
+

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

@@ -1,7 +1,7 @@
 import json
 import logging
 
-from typing import List, Any, Dict, Optional
+from typing import Any, Dict, Optional
 from typing_extensions import override
 
 from langchain_mcp_adapters.tools import load_mcp_tools
@@ -46,7 +46,7 @@ class XGAAreToolBox(XGAMcpToolBox):
             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)
+                result = XGAToolResult(success=False, output=str(e))
         else:
             async with self._mcp_client.session(server_name) as session:
                 tools = await load_mcp_tools(session)

{xgae-0.3.3/examples/agent → xgae-0.3.4/examples/agent/are}/are/simulation/agents/xga/mcp_tool_executor.py

@@ -80,12 +80,12 @@ def call_mcp_tool(url: str, tool_name: str, arguments: dict[str, Any], timeout:
     future = AsyncToolExecutor.submit(_mcp_sse_tool_call(url, tool_name, arguments))
     mcp_result:CallToolResult =  future.result(timeout=timeout)
     result = {
-        'success': not mcp_result.isError,
+        'isError': mcp_result.isError,
     }
     if mcp_result.isError:
-        result['output'] = mcp_result.content[0].text
+        result['content'] = mcp_result.content[0].text
     else:
-        result['output'] = mcp_result.structuredContent['result']
+        result['content'] = mcp_result.structuredContent['result']
 
     return  json.dumps(result)
 
@@ -93,14 +93,15 @@ def call_mcp_tool(url: str, tool_name: str, arguments: dict[str, Any], timeout:
 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):
+    if org_result and isinstance(org_result, str) and "isError" in org_result:
         try:
             _result:dict = json.loads(org_result)
-            output = _result.get('output', None)
-            success = _result.get('success', None)
+            content = _result.get('content', None)
+            isError = _result.get('isError', None)
 
-            if success and output:
-                result = XGAToolResult(success=bool(success), output=str(output))
+            if content and isError:
+                success = not bool(isError)
+                result = XGAToolResult(success=bool(success), output=str(content))
         except:
             pass
 

xgae-0.3.4/examples/agent/are/templates/custom_tool_prompt_template.txt

@@ -0,0 +1,24 @@
+# AVAILABLE MCP TOOLS 
+You have access to external MCP (Model Context Protocol) server tools.
+MCP tools can be called directly using their native function names in the standard function calling format:
+
+## MCP TOOL SCHEMAS
+{tool_schemas}
+
+## CRITICAL MCP TOOL RULES
+When you use ANY MCP (Model Context Protocol) tools:
+1. Never call a MCP tool not in 'Available MCP tools' list
+2. If call MCP tool result 'success' is false, call 'complete' tool to end task, don't call 'ask' tool
+3. ALWAYS read and use the EXACT results returned by the MCP tool
+4. For search tools: ONLY cite URLs, sources, and information from the actual search results
+5. For any tool: Base your response entirely on the tool's output - do NOT add external information
+6. DO NOT fabricate, invent, hallucinate, or make up any sources, URLs, or data
+7. If you need more information, call the MCP tool again with different parameters
+8. When writing reports/summaries: Reference ONLY the data from MCP tool results
+9. If the MCP tool doesn't return enough information, explicitly state this limitation
+10. Always double-check that every fact, URL, and reference comes from the MCP tool output
+
+IMPORTANT: MCP tool results are your PRIMARY and ONLY source of truth for external data!
+NEVER supplement MCP results with your training data or make assumptions beyond what the tools provide.
+
+

xgae-0.3.4/examples/agent/are/templates/general_tool_prompt_template.txt

@@ -0,0 +1,51 @@
+# FUNDAMENTAL RULES FOR TASK EXECUTION
+1. COMMUNICATION: Only message the user when completely done or if the task is impossible.
+2. EXECUTION: Work silently, complete tasks fully, no progress updates.
+3. COMPLIANCE: Follow user instructions exactly, ask for clarification only if the environment does not provide enough information.
+4. PROBLEM SOLVING: Try alternative approaches before reporting failure.
+5. INFORMATION: Use available tools to gather missing information before asking user.
+6. AMBIGUITY: Execute all clear and unambiguous parts of a request immediately. When you encounter ambiguities, contradictions, or impossible elements, finish unambiguous subtasks and then stop and explicitly ask the user for clarification before proceeding with those specific parts.
+
+
+# FORMAT SPECIFICATION
+## RESPONSE FORMAT SPECIFICATION
+<thought>
+[Your reasoning in plain text]
+</thought>
+
+<function_calls>
+<invoke name="function_name">
+<parameter name="param_name">param_value</parameter>
+...
+</invoke>
+</function_calls>
+
+String and scalar parameters should be specified as-is, while lists and objects should use JSON format.
+
+## THOUGHT RULES
+- Always explain your reasoning in natural language before the Action.
+- Never include tool call details inside the Thought, only in the Action.
+
+##  RESPONSE EXAMPLE
+<thought>
+I need to look up the current weather before answering, so I will call the weather tool with the city name.
+<thought>
+
+<function_calls>
+<invoke name="query_weather">
+<parameter name="city_name">Beijing</parameter>
+</invoke>
+<function_calls>
+
+
+# AVAILABLE SYSTEM TOOLS
+
+## SYSTEM TOOL SCHEMAS:
+{tool_schemas}
+## CRITICAL GENERAL TOOL RULES
+- Use the exact function names from  schema above
+- Include all required parameters as specified in the schema
+- Format complex data (objects, arrays) as JSON strings within the parameter tags
+- Boolean values should be "true" or "false" (lowercase)
+- If 'ask' tool answer is not match, call 'complete' tool end task, never call 'ask' tool again
+

xgae-0.3.4/mcpservers/xga_server.json

@@ -0,0 +1,11 @@
+{
+    "mcpServers":{
+        "xga_general": {
+      		"command": "uv",
+      		"args": [
+        		"run",
+        		"xgae-tools"
+      		]
+        }
+    }
+}

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

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

{xgae-0.3.3 → xgae-0.3.4}/xgae/gaia2/are_engine.py

@@ -4,6 +4,7 @@ from typing_extensions import override
 
 from xgae.engine.engine_base import XGAToolBox
 from xgae.engine.task_engine import XGATaskEngine
+from xgae.engine.prompt_builder import XGAPromptBuilder
 from xgae.utils.llm_client import LLMConfig
 
 
@@ -15,6 +16,7 @@ class ARETaskEngine(XGATaskEngine):
                  max_auto_run: int,
                  llm_config: Optional[LLMConfig] = None,
                  tool_box: Optional[XGAToolBox] = None,
+                 prompt_builder: Optional[XGAPromptBuilder] = None,
                  pre_run_task_fn : Callable[[Any, int, List[Dict[str, Any]]], Any] = None,
                  post_run_task_fn : Callable[[Any, int, Dict[str, Any]], Any] = None,
                  terminate_task_fn : Callable[[Any, int], bool] = None,
@@ -26,6 +28,7 @@ class ARETaskEngine(XGATaskEngine):
                          max_auto_run   = max_auto_run,
                          llm_config     = llm_config,
                          tool_box       = tool_box,
+                         prompt_builder = prompt_builder,
                          )
         self.agent = agent
         self.pre_run_task_fn = pre_run_task_fn