xgae 0.1.20__tar.gz → 0.2.0__tar.gz

{xgae-0.1.20 → xgae-0.2.0}/CHANGELOG.md

@@ -1,12 +1,21 @@
 # Release Changelog
-## [0.1.20] - 2025-9-8
+## [0.2.0] - 2025-9-10
 ### Added
-- Example: Langgraph react agent add final_result_agent 
+- Agent Engine release 0.2
+- Example: Langgraph ReactAgent release 0.2
+### Fixed
+- Agent Engine: call mcp tool fail, call 'ask' tool again and again
+- Example Langgraph ReactAgent: retry on 'ask', user_input is ask answer
+
+
+## [0.1.20] - 2025-9-9
+### Added
+- Example: Langgraph ReactAgent add final_result_agent 
 
 
 ## [0.1.19] - 2025-9-8
 ### Added
-- Example: Langgraph react agent release V1, full logic but no final result agent and tool select agent
+- Example: Langgraph ReactAgent release V1, full logic but no final result agent and tool select agent
 
 
 # Release Changelog

{xgae-0.1.20 → xgae-0.2.0}/PKG-INFO

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

{xgae-0.1.20 → xgae-0.2.0}/pyproject.toml

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

{xgae-0.1.20 → xgae-0.2.0}/src/examples/agent/langgraph/react/agent_base.py

@@ -17,7 +17,7 @@ class AgentContext(TypedDict, total=False):
 class TaskState(TypedDict, total=False):
     """State definition for the agent orchestration graph"""
     llm_messages: List[Dict[str, Any]]
-    user_input: str
+    user_inputs: List[str]
     next_node: str
     system_prompt: str
     custom_tools: List[str]
@@ -25,7 +25,8 @@ class TaskState(TypedDict, total=False):
     task_result: XGATaskResult
     final_result: XGATaskResult
     eval_result: EvaluateResult
-    iteration_count: int
+    retry_count: int
+    task_no: int
     agent_context: AgentContext
 
 

{xgae-0.1.20 → xgae-0.2.0}/src/examples/agent/langgraph/react/react_agent.py

@@ -21,7 +21,7 @@ from xgae.engine.mcp_tool_box import XGAMcpToolBox
 from xgae.engine.task_engine import XGATaskEngine
 
 from examples.agent.langgraph.react.agent_base import AgentContext, TaskState, EvaluateResult
-from examples.agent.langgraph.react.final_result_agent import FinalResultAgent
+from examples.agent.langgraph.react.result_eval_agent import TaskResultEvalAgent
 
 class XGAReactAgent:
     MAX_TASK_RETRY = 2
@@ -35,7 +35,8 @@ class XGAReactAgent:
         self.task_engine: XGATaskEngine = None
 
         self.tool_box = XGAMcpToolBox(custom_mcp_server_file="mcpservers/custom_servers.json")
-        self.final_result_agent = FinalResultAgent()
+        self.result_eval_agent = TaskResultEvalAgent()
+
 
     async def _create_graph(self) -> StateGraph:
         try:
@@ -43,6 +44,7 @@ class XGAReactAgent:
 
             # Add nodes
             graph_builder.add_node('supervisor', self._supervisor_node)
+            graph_builder.add_node('prompt_optimize', self._prompt_optimize_node)
             graph_builder.add_node('select_tool', self._select_tool_node)
             graph_builder.add_node('exec_task', self._exec_task_node)
             graph_builder.add_node('final_result', self._final_result_node)
@@ -53,12 +55,14 @@ class XGAReactAgent:
                 'supervisor',
                 self._next_condition,
                 {
-                    'select_tool': 'select_tool',
-                    'exec_task': 'exec_task',
-                    'end': END
+                    'select_tool'       : 'select_tool',
+                    'exec_task'         : 'exec_task',
+                    'prompt_optimize'   : 'prompt_optimize',
+                    'end'               : END
                 }
             )
 
+            graph_builder.add_edge('prompt_optimize', 'select_tool')
             graph_builder.add_edge('select_tool', 'exec_task')
             graph_builder.add_edge('exec_task', 'final_result')
 
@@ -67,8 +71,8 @@ class XGAReactAgent:
                 self._next_condition,
                 {
                     'supervisor': 'supervisor',
-                    'exec_task': 'exec_task',
-                    'end': END
+                    'exec_task' : 'exec_task',
+                    'end'       : END
                 }
             )
             
@@ -80,64 +84,104 @@ class XGAReactAgent:
             logging.error("Failed to create XGARectAgent Graph: %s", str(e))
             raise
 
+
     def _search_system_prompt(self, user_input: str) -> str:
         # You should search RAG use user_input, fetch COT or Prompt for your business
         system_prompt = None if "fault" not in user_input else read_file("templates/example/fault_user_prompt.txt")
         return system_prompt
 
+
     async def _supervisor_node(self, state: TaskState) -> Dict[str, Any]:
-        user_input = state['user_input']
+        user_input = state['user_inputs'][0]
         eval_result = state.get('eval_result', None)
 
         system_prompt = self._search_system_prompt(user_input)
+        is_system_prompt = True if system_prompt is not None else False
 
         general_tools = [] if system_prompt else ["*"]
         custom_tools = ["*"] if system_prompt  else []
 
+        task_plan_score = None
+        if eval_result and 'task_plan' in eval_result and 'score' in eval_result['task_plan']:
+            task_plan_score = eval_result['task_plan'].get('score', 1.0)
+
+        function_call_score = None
         if eval_result and 'function_call' in eval_result and 'score' in eval_result['function_call']:
-            score = eval_result['function_call'].get('score', 1.0)
-            if score < self.QUALIFIED_RESULT_SCORE:
-                next_node = "select_tool"
-            else:
-                next_node = "end"
+            function_call_score = eval_result['function_call'].get('score', 1.0)
+
+        super_state = {}
+        if task_plan_score and task_plan_score < self.QUALIFIED_RESULT_SCORE:
+            next_node = "prompt_optimize"
+            super_state = self._prepare_task_retry(state)
+            logging.warning(f"****** ReactAgent TASK_RETRY: task_plan_score={task_plan_score} < {self.QUALIFIED_RESULT_SCORE} , "
+                            f"Start Optimize Prompt ...")
+        elif function_call_score and function_call_score < self.QUALIFIED_RESULT_SCORE:
+            next_node = "select_tool"
+            super_state = self._prepare_task_retry(state)
+            logging.warning(f"****** ReactAgent TASK_RETRY: function_call_score={function_call_score} < {self.QUALIFIED_RESULT_SCORE} , "
+                            f"Select Tool Again ...")
+        elif eval_result is not None:  # retry condition is not satisfied, end task
+            next_node = "end"
         else:
-            next_node = "select_tool" if system_prompt else "exec_task"
+            next_node = "select_tool" if is_system_prompt else "exec_task"
+
+        logging.info(f"ReactAgent supervisor_node: is_system_prompt={is_system_prompt}, next_node={next_node}")
 
+        super_state['next_node']        = next_node
+        super_state['system_prompt']    = system_prompt
+        super_state['custom_tools']     = custom_tools
+        super_state['general_tools']    = general_tools
+
+        return super_state
+
+
+    async def _prompt_optimize_node(self, state: TaskState) -> Dict[str, Any]:
+        system_prompt = state['system_prompt']
+        logging.info("ReactAgent prompt_optimize_node: optimize system prompt")
+        # @todo optimize system prompt in future
         return {
             'system_prompt' : system_prompt,
-            'next_node'     : next_node,
-            'general_tools' : general_tools,
-            'custom_tools'  : custom_tools,
         }
 
+
     def _select_custom_tools(self, system_prompt: str) -> list[str]:
+        # @todo select mcp tool based on system prompt in future
         custom_tools = ["*"] if system_prompt  else []
         return custom_tools
 
+
     async def _select_tool_node(self, state: TaskState) -> Dict[str, Any]:
         system_prompt = state.get('system_prompt',None)
         general_tools = []
+
+        logging.info("ReactAgent select_tool_node: select tool based on system_prompt")
         custom_tools = self._select_custom_tools(system_prompt)
         return {
             'general_tools' : general_tools,
             'custom_tools'  : custom_tools,
         }
 
+
     async def _exec_task_node(self, state: TaskState) -> Dict[str, Any]:
-        user_input = state['user_input']
+        user_input = state['user_inputs'][0]
         system_prompt = state.get('system_prompt',None)
         general_tools = state.get('general_tools',[])
         custom_tools = state.get('custom_tools',[])
+        retry_count = state.get('retry_count', 0)
+        task_no = state.get('task_no', 0)
         is_system_prompt = True if system_prompt is not None else False
 
         trace_id = self.graph_langfuse.get_trace_id()
         llm_messages = []
         try:
-            logging.info(f"🔥 XGATaskEngine run_task: user_input={user_input}, general_tools={general_tools}, "
+            logging.info(f"🔥 ReactAgent exec_task_node: user_input={user_input}, general_tools={general_tools}, "
                          f"custom_tools={custom_tools}, is_system_prompt={is_system_prompt}")
+
+            # if langgraph resume , must use same task engine
             if self.task_engine is None:
                 self.task_engine = XGATaskEngine(
                     task_id         = state['agent_context']['task_id'],
+                    task_no         = task_no,
                     session_id      = state['agent_context'].get('session_id', None),
                     user_id         = state['agent_context'].get('user_id', None),
                     agent_id        = state['agent_context'].get('agent_id', None),
@@ -146,6 +190,7 @@ class XGAReactAgent:
                     custom_tools    = custom_tools,
                     system_prompt   = system_prompt
                 )
+                retry_count += 1
 
             chunks = []
             stream_writer = get_stream_writer()
@@ -156,47 +201,56 @@ class XGAReactAgent:
 
             task_result = self.task_engine.parse_final_result(chunks)
             llm_messages = self.task_engine.get_history_llm_messages()
+            task_no += 1  # a task use unique task_no, no matter retry n times
         except Exception as e:
             logging.error(f"XReactAgent exec_task_node: Failed to execute task: {e}")
             task_result = XGATaskResult(type="error", content="Failed to execute task")
 
-        iteration_count = state.get('iteration_count', 0) + 1
         return {
-            'task_result' : task_result,
-            'iteration_count': iteration_count,
-            'llm_messages' : llm_messages.copy()
+            'task_result'   : task_result,
+            'retry_count'   : retry_count,
+            'llm_messages'  : llm_messages.copy(),
+            'task_no'       : task_no,
         }
 
 
     async def _final_result_node(self, state: TaskState) -> Dict[str, Any]:
-        user_input = state['user_input']
-        iteration_count = state['iteration_count']
+        user_inputs = state['user_inputs']
         task_result = state['task_result']
         llm_messages = state['llm_messages']
         agent_context = state['agent_context']
+        system_prompt = state.get('system_prompt', None)
+        retry_count = state['retry_count']
+
+        is_system_prompt = True if system_prompt is not None else False
 
         next_node = "end"
         final_result = task_result
         eval_result = None
         if task_result['type'] == "ask":
             logging.info(f"XReactAgent final_result_node: ASK_USER_QUESTION: {task_result['content']}")
-            user_input = interrupt({
+            ask_input = interrupt({
                 'final_result' : task_result
             })
-            logging.info(f"XReactAgent final_result_node: ASK_USER_ANSWER: {user_input}")
+            logging.info(f"XReactAgent final_result_node: ASK_USER_ANSWER: {ask_input}")
             next_node = "exec_task"
+            user_inputs.insert(0, ask_input)
             final_result = None
-        elif iteration_count < self.MAX_TASK_RETRY:
+        elif is_system_prompt and retry_count < self.MAX_TASK_RETRY:
             trace_id = self.graph_langfuse.get_trace_id()
             session_id = agent_context.get('session_id', None)
-            eval_result = await self.final_result_agent.eval_result(user_input, task_result, llm_messages, trace_id, session_id)
-            if "task_result" in eval_result and "score" in eval_result['task_result']:
+            task_input = ", ".join(reversed(user_inputs))
+            eval_result = await self.result_eval_agent.eval_result(task_input, system_prompt, task_result,
+                                                                   llm_messages, trace_id, session_id)
+            if 'task_result' in eval_result and 'score' in eval_result['task_result']:
                 score =  eval_result['task_result'].get('score', 1.0)
                 if score < self.QUALIFIED_RESULT_SCORE:
                     next_node = "supervisor"
-
+        
+        logging.info(f"ReactAgent final_result_node: next_node={next_node}")
+        
         return {
-            'user_input'    : user_input,
+            'user_inputs'    : user_inputs,
             'next_node'     : next_node,
             'final_result'  : final_result,
             'eval_result'   : eval_result
@@ -303,10 +357,11 @@ class XGAReactAgent:
         }
 
         graph_input = {
-            'user_input'        : user_input,
+            'user_inputs'       : [user_input],
             'next_node'         : None,
             'agent_context'     : agent_context,
-            'iteration_count'   : 0
+            'retry_count'       : 0,
+            'task_no'           : 0
         }
 
         return graph_input
@@ -329,7 +384,22 @@ class XGAReactAgent:
             )
         return langfuse_handler
 
+
     def _clear_graph(self):
         self.graph_config = None
         self.graph_langfuse = None
         self.task_engine: XGATaskEngine = None
+
+
+    def _prepare_task_retry(self, state: TaskState)-> Dict[str, Any]:
+        self.task_engine = None
+        user_inputs = state['user_inputs']
+        task_input = ", ".join(reversed(user_inputs))
+
+        return {
+            'user_inputs'   : [task_input],
+            'llm_messages'  : [],
+            'task_result'   : None,
+            'final_result'  : None,
+            'eval_result'   : None,
+        }

xgae-0.1.20/src/examples/agent/langgraph/react/final_result_agent.py → xgae-0.2.0/src/examples/agent/langgraph/react/result_eval_agent.py

@@ -9,19 +9,20 @@ from xgae.utils.misc import read_file
 from xgae.utils.llm_client import LLMClient, LangfuseMetadata
 
 
-class FinalResultAgent:
+class TaskResultEvalAgent:
     def __init__(self):
         self.model_client = LLMClient()
-        self.prompt_template: str = read_file("templates/example/final_result_template.txt")
+        self.prompt_template: str = read_file("templates/example/result_eval_template.txt")
 
 
     async def eval_result(self,
                           task_input: str,
+                          task_plan: str,
                           task_result: XGATaskResult,
                           llm_messages: List[Dict[str, Any]],
                           trace_id: Optional[str] = None,
                           session_id: Optional[str] = None)-> Dict[str, Any]:
-        prompt = self._build_prompt(task_input, task_result, llm_messages)
+        prompt = self._build_prompt(task_input, task_plan, task_result, llm_messages)
         messages = [{"role": "user", "content": prompt}]
 
         langfuse_metadata = self._create_llm_langfuse_meta(trace_id, session_id)
@@ -33,15 +34,15 @@ class FinalResultAgent:
         eval_result = json.loads(cleaned_text)
 
         result_score = eval_result.get('task_result', {}).get('score', -1)
-        process_score = eval_result.get('task_process', {}).get('score', -1)
+        plan_score = eval_result.get('task_plan', {}).get('score', -1)
         function_score = eval_result.get('function_call', {}).get('score', -1)
 
         logging.info(f"FINAL_RESULT_SCORE: task_result_score={result_score}, "
-                     f"task_process_score={process_score}, function_call_score={function_score}")
+                     f"task_plan_score={plan_score}, function_call_score={function_score}")
         return eval_result
 
 
-    def _build_prompt(self, task_input: str, task_result: XGATaskResult, llm_messages: List[Dict[str, Any]])-> str:
+    def _build_prompt(self, task_input: str, task_plan: str, task_result: XGATaskResult, llm_messages: List[Dict[str, Any]])-> str:
         prompt = self.prompt_template.replace("{task_input}", task_input)
         prompt = prompt.replace("{task_result}", str(task_result))
         llm_process = ""
@@ -65,6 +66,7 @@ class FinalResultAgent:
                 llm_process += "\n"
                 llm_step += 1
 
+        prompt = prompt.replace("{task_plan}", task_plan)
         prompt = prompt.replace("{llm_process}", llm_process)
         prompt = prompt.replace("{function_process}", function_process)
 
@@ -88,13 +90,16 @@ if __name__ == "__main__":
     setup_logging()
 
     async def main():
-        final_result_agent = FinalResultAgent()
+        final_result_agent = TaskResultEvalAgent()
 
+        task_plan = read_file("templates/example/fault_user_prompt.txt")
         user_input = "locate 10.2.3.4 fault and solution"
+
         answer = ("Task Summary: The fault for IP 10.2.3.4 was identified as a Business Recharge Fault (Code: F01), "
                   "caused by a Phone Recharge Application Crash. The solution applied was to restart the application. "
                   "Key Deliverables: Fault diagnosis and resolution steps. Impact Achieved: Service restored.")
         task_result:XGATaskResult = {'type': "answer",  'content': answer}
+
         llm_messages: List[Dict[str, Any]] = [{
             'content':
                     """<function_calls> 
@@ -111,7 +116,8 @@ if __name__ == "__main__":
                                 "result": {"success": true, "output": "1", "error": null}}}""",
             'role': 'assistant'
             }]
-        return await final_result_agent.eval_result(user_input, task_result, llm_messages)
+
+        return await final_result_agent.eval_result(user_input, task_plan, task_result, llm_messages)
 
 
     final_result = asyncio.run(main())

{xgae-0.1.20 → xgae-0.2.0}/src/xgae/engine/task_engine.py

@@ -18,6 +18,7 @@ from xgae.engine.responser.responser_base import TaskResponserContext, TaskRespo
 class XGATaskEngine:
     def __init__(self,
                  task_id: Optional[str] = None,
+                 task_no: Optional[int] = None,
                  session_id: Optional[str] = None,
                  user_id: Optional[str] = None,
                  agent_id: Optional[str] = None,
@@ -51,7 +52,7 @@ class XGATaskEngine:
         self.use_assistant_chunk_msg = to_bool(os.getenv('USE_ASSISTANT_CHUNK_MSG', False))
         self.tool_exec_parallel = True if tool_exec_parallel is None else tool_exec_parallel
 
-        self.task_no = -1
+        self.task_no = (task_no - 1) if task_no  else -1
         self.task_run_id :str = None
         self.task_prompt :str = None
         self.task_langfuse: XGATaskLangFuse = None

{xgae-0.1.20 → xgae-0.2.0}/templates/agent_tool_prompt_template.txt

@@ -25,5 +25,6 @@ When you use ANY Agent (Model Context Protocol) tools:
 1) type: 'answer',  'content' is normal return answer for tool calling
 2) type: 'ask', you should call 'ask' tool for user inputting more information
 3) type: 'error', during calling tool , some exceptions or errors has occurred.
+10. If 'ask' tool answer is not match, call 'complete' tool end task, never call 'ask' tool again
 IMPORTANT: Agent tool results are your PRIMARY and ONLY source of truth for external data!
 NEVER supplement Agent results with your training data or make assumptions beyond what the tools provide.

{xgae-0.1.20 → xgae-0.2.0}/templates/custom_tool_prompt_template.txt

@@ -13,13 +13,16 @@ Available MCP tools:
 
 🚨 CRITICAL MCP TOOL RESULT INSTRUCTIONS 🚨
 When you use ANY MCP (Model Context Protocol) tools:
-1. ALWAYS read and use the EXACT results returned by the MCP tool
-2. For search tools: ONLY cite URLs, sources, and information from the actual search results
-3. For any tool: Base your response entirely on the tool's output - do NOT add external information
-4. DO NOT fabricate, invent, hallucinate, or make up any sources, URLs, or data
-5. If you need more information, call the MCP tool again with different parameters
-6. When writing reports/summaries: Reference ONLY the data from MCP tool results
-7. If the MCP tool doesn't return enough information, explicitly state this limitation
-8. Always double-check that every fact, URL, and reference comes from the MCP tool output
+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.1.20/templates/example/final_result_template.txt → xgae-0.2.0/templates/example/result_eval_template.txt

@@ -18,9 +18,9 @@ Grading is based on task requirements and task answers. Key scoring elements inc
 1. Task Result Score: Task outcome evaluation
 - assesses the degree of match between task requirements and task results
 - if task result 'type' is 'error', evaluation score is 0, evaluation reason is empty
-2.Task Process Score : Task process evaluation
-- assesses whether task planning is reasonable
-- Whether task steps can yield answers to the user’s question
+2.Task Plan Score : Task Plan evaluation
+- assesses whether task planning is reasonable based on LLM Procedure and Function Call Procedure
+- Whether task steps can yield answers to the task requirement
 - Whether task steps can be executed
 - Whether task steps can properly match and call tools
 3. Function Call Score: Function Call evaluation
@@ -34,9 +34,9 @@ Grading is based on task requirements and task answers. Key scoring elements inc
     "score": 0.62,   			# value: 0 ~ 1.00 , using two decimal places
     "reasons": "Evaluation and reasons for deduction regarding task results"
   },
-  "task_process": {  		# Task Process Score
+  "task_plan": {  		# Task Plan Score
     "score": 0.53,  			# value: 0 ~ 1.00 , using two decimal places
-    "reasons": "Evaluation and reasons for deduction regarding the task process"
+    "reasons": "Evaluation and reasons for deduction regarding the task planning"
   },
   "function_call": {   		# Function Call Score
     "score": 0.41, 			# value: 0 ~ 1.00 , using two decimal places
@@ -53,9 +53,14 @@ Grading is based on task requirements and task answers. Key scoring elements inc
 {task_result}
 
 
+# Task Plan
+{task_plan}
+
+
 # LLM Procedure
 {llm_process}
 
+
 # Function Call Procedure
 {function_process}
 

{xgae-0.1.20 → xgae-0.2.0}/templates/general_tool_prompt_template.txt

@@ -22,4 +22,5 @@ When using the tools:
 - 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
 {tool_examples}