Feat/workflow upgrade

docs/ColabNotebook/tutorial_notebooks/first_workflow.ipynb

@@ -207,14 +207,17 @@
         "workflow = WorkFlow(graph=graph, agent_manager=agent_manager, llm=llm)\n",
         "\n",
         "# Execute the workflow with inputs\n",
-        "output = workflow.execute(\n",
+        "result = workflow.execute(\n",
         "    inputs = {\n",
         "        \"problem\": \"Write a function to find the longest palindromic substring in a given string.\"\n",
         "    }\n",
         ")\n",
         "\n",
-        "print(\"Workflow completed!\")\n",
-        "print(\"Workflow output:\\n\", output)"
+        "if result.status == \"success\":\n",
+        "    print(\"Workflow completed!\")\n",
+        "    print(\"Workflow output:\\n\", result.result)\n",
+        "else:\n",
+        "    print(\"Workflow failed:\\n\", result.displayable_error)"
       ]
     },
     {
@@ -276,4 +279,4 @@
   },
   "nbformat": 4,
   "nbformat_minor": 5
-}
+}

docs/ColabNotebook/tutorial_notebooks/quickstart.ipynb

@@ -446,8 +446,11 @@
       "outputs": [],
       "source": [
         "workflow = WorkFlow(graph=workflow_graph, agent_manager=agent_manager, llm=llm)\n",
-        "output = workflow.execute()\n",
-        "print(output)"
+        "result = workflow.execute()\n",
+        "if result.status == \"success\":\n",
+        "    print(result.result)\n",
+        "else:\n",
+        "    print(result.displayable_error)"
       ]
     },
     {
@@ -467,8 +470,11 @@
         "\n",
         "nest_asyncio.apply()\n",
         "workflow = WorkFlow(graph=workflow_graph, agent_manager=agent_manager, llm=llm)\n",
-        "output = workflow.execute()\n",
-        "print(output)"
+        "result = workflow.execute()\n",
+        "if result.status == \"success\":\n",
+        "    print(result.result)\n",
+        "else:\n",
+        "    print(result.displayable_error)"
       ],
       "metadata": {
         "id": "iU2124jInCdy"
@@ -500,4 +506,4 @@
   },
   "nbformat": 4,
   "nbformat_minor": 5
-}
+}

docs/ColabNotebook/tutorial_notebooks/textgrad_optimizer.ipynb

@@ -443,7 +443,7 @@
         "            \"system_prompt\": \"You are a math-focused assistant dedicated to providing clear, concise, and educational solutions to mathematical problems. Your goal is to deliver structured and pedagogically sound explanations, ensuring mathematical accuracy and logical reasoning. Begin with a brief overview of the problem-solving approach, followed by detailed calculations, and conclude with a verification step. Use precise mathematical notation and consider potential edge cases. Present the final answer clearly, using the specified format, and incorporate visual aids or analogies where appropriate to enhance understanding and engagement. \\n\\nExplicitly include geometric explanations when applicable, describing the geometric context and relationships. Emphasize the importance of visual aids, such as diagrams or sketches, to enhance understanding. Ensure consistency in formatting and mathematical notation. Provide a brief explanation of the reference angle concept and its significance. Include contextual explanations of trigonometric identities and their applications. Critically evaluate initial assumptions and verify geometric properties before proceeding. Highlight the use of symmetry and conjugate pairs in complex numbers. Encourage re-evaluation and verification of steps, ensuring logical flow and clarity. Focus on deriving the correct answer and consider problem-specific strategies or known techniques.\",\n",
         "            \"parse_mode\": \"str\",\n",
         "            \"parse_func\": null,\n",
-        "            \"parse_title\": null\n",
+        "            \"title_format\": \"## {title}\"\n",
         "        }\n",
         "    ]\n",
         "}"
@@ -472,4 +472,4 @@
   },
   "nbformat": 4,
   "nbformat_minor": 5
-}
+}

docs/ColabNotebook/tutorial_notebooks_zh/first_workflow.ipynb

@@ -208,14 +208,17 @@
         "workflow = WorkFlow(graph=graph, agent_manager=agent_manager, llm=llm)\n",
         "\n",
         "# Execute the workflow with inputs\n",
-        "output = workflow.execute(\n",
+        "result = workflow.execute(\n",
         "    inputs = {\n",
         "        \"problem\": \"Write a function to find the longest palindromic substring in a given string.\"\n",
         "    }\n",
         ")\n",
         "\n",
-        "print(\"Workflow completed!\")\n",
-        "print(\"Workflow output:\\n\", output)"
+        "if result.status == \"success\":\n",
+        "    print(\"Workflow completed!\")\n",
+        "    print(\"Workflow output:\\n\", result.result)\n",
+        "else:\n",
+        "    print(\"Workflow failed:\\n\", result.displayable_error)"
       ]
     },
     {
@@ -281,4 +284,4 @@
   },
   "nbformat": 4,
   "nbformat_minor": 5
-}
+}

docs/ColabNotebook/tutorial_notebooks_zh/quickstart.ipynb

@@ -450,8 +450,11 @@
       "outputs": [],
       "source": [
         "workflow = WorkFlow(graph=workflow_graph, agent_manager=agent_manager, llm=llm)\n",
-        "output = workflow.execute()\n",
-        "print(output)"
+        "result = workflow.execute()\n",
+        "if result.status == \"success\":\n",
+        "    print(result.result)\n",
+        "else:\n",
+        "    print(result.displayable_error)"
       ]
     },
     {
@@ -471,8 +474,11 @@
         "\n",
         "nest_asyncio.apply()\n",
         "workflow = WorkFlow(graph=workflow_graph, agent_manager=agent_manager, llm=llm)\n",
-        "output = workflow.execute()\n",
-        "print(output)"
+        "result = workflow.execute()\n",
+        "if result.status == \"success\":\n",
+        "    print(result.result)\n",
+        "else:\n",
+        "    print(result.displayable_error)"
       ],
       "metadata": {
         "id": "xIB1AIbbm5Dt"
@@ -508,4 +514,4 @@
   },
   "nbformat": 4,
   "nbformat_minor": 5
-}
+}

docs/ColabNotebook/tutorial_notebooks_zh/textgrad_optimizer.ipynb

@@ -423,7 +423,7 @@
         "            \"system_prompt\": \"You are a math-focused assistant dedicated to providing clear, concise, and educational solutions to mathematical problems. Your goal is to deliver structured and pedagogically sound explanations, ensuring mathematical accuracy and logical reasoning. Begin with a brief overview of the problem-solving approach, followed by detailed calculations, and conclude with a verification step. Use precise mathematical notation and consider potential edge cases. Present the final answer clearly, using the specified format, and incorporate visual aids or analogies where appropriate to enhance understanding and engagement. \\n\\nExplicitly include geometric explanations when applicable, describing the geometric context and relationships. Emphasize the importance of visual aids, such as diagrams or sketches, to enhance understanding. Ensure consistency in formatting and mathematical notation. Provide a brief explanation of the reference angle concept and its significance. Include contextual explanations of trigonometric identities and their applications. Critically evaluate initial assumptions and verify geometric properties before proceeding. Highlight the use of symmetry and conjugate pairs in complex numbers. Encourage re-evaluation and verification of steps, ensuring logical flow and clarity. Focus on deriving the correct answer and consider problem-specific strategies or known techniques.\",\n",
         "            \"parse_mode\": \"str\",\n",
         "            \"parse_func\": null,\n",
-        "            \"parse_title\": null\n",
+        "            \"title_format\": \"## {title}\"\n",
         "        }\n",
         "    ]\n",
         "}"
@@ -456,4 +456,4 @@
   },
   "nbformat": 4,
   "nbformat_minor": 5
-}
+}

docs/modules/workflow_graph.md

@@ -74,10 +74,10 @@ The `SequentialWorkFlowGraph` accepts a simplified input format that makes it ea
 - `outputs` (required): List of output parameters produced by the task
 - `prompt` (required): The prompt template to guide the agent's behavior
 - `system_prompt` (optional): System message to provide context to the agent
-- `output_parser` (optional): The output parser to parse the output of the task 
+- `output_parser` (optional): The output parser to parse the output of the task
 - `parse_mode` (optional): Mode for parsing outputs, defaults to "str"
 - `parse_func` (optional): Custom function for parsing outputs
-- `parse_title` (optional): Title for the parsed output
+- `title_format` (optional): Title format used when `parse_mode` is "title", e.g. "## {title}"
 
 The parameters related to prompts and parsing will be used to create a `CustomizeAgent` instance in the `agent_manager`. Please refer to the [Customize Agent](./customize_agent.md) documentation for more details about the agent configuration. 
 
@@ -183,9 +183,13 @@ agent_manager.add_agents_from_workflow(workflow_graph, llm_config=llm_config)
 
 # create a workflow instance for execution 
 workflow = WorkFlow(graph=workflow_graph, agent_manager=agent_manager, llm=llm)
-workflow.execute(inputs={"data_source": "xxx"})
+result = workflow.execute(inputs={"data_source": "xxx"})
+if result.status == "success":
+    print(result.result)
 ```
 
+`WorkFlow.execute()` returns a `WorkflowResult` object. By default, the workflow result is the structured output data as a `dict`. Pass `extract_output=True` if you want the older text-extraction behavior.
+
 ### Creating a SequentialWorkFlowGraph
 
 ```python
@@ -255,4 +259,4 @@ sequential_workflow_graph.save_module("examples/output/my_sequential_workflow.js
 workflow_graph.display()
 ```
 
-The `WorkFlowGraph` and `SequentialWorkFlowGraph` classes provide a flexible and powerful way to design complex agent workflows, track their execution, and manage the flow of data between tasks. 
+The `WorkFlowGraph` and `SequentialWorkFlowGraph` classes provide a flexible and powerful way to design complex agent workflows, track their execution, and manage the flow of data between tasks. 

docs/quickstart.md

@@ -132,9 +132,13 @@ agent_manager.add_agents_from_workflow(workflow_graph, llm_config=openai_config)
 Once agents are ready, you can create a `WorkFlow` instance and run it:
 ```python
 workflow = WorkFlow(graph=workflow_graph, agent_manager=agent_manager, llm=llm)
-output = workflow.execute()
-print(output)
+result = workflow.execute()
+if result.status == "success":
+    print(result.result)
+else:
+    print(result.displayable_error)
 ```
 
-For a complete working example, check out the [full workflow demo](https://github.com/EvoAgentX/EvoAgentX/blob/main/examples/workflow_demo.py).
+`WorkFlow.execute()` returns a `WorkflowResult` object. By default, `result.result` is the structured workflow output as a `dict`. If you want the older text-extraction behavior, call `workflow.execute(extract_output=True)`.
 
+For a complete working example, check out the [full workflow demo](https://github.com/EvoAgentX/EvoAgentX/blob/main/examples/workflow_demo.py).

docs/tutorial/first_workflow.md

@@ -111,17 +111,22 @@ agent_manager.add_agents_from_workflow(
 workflow = WorkFlow(graph=graph, agent_manager=agent_manager, llm=llm)
 
 # Execute the workflow with inputs
-output = workflow.execute(
+result = workflow.execute(
     inputs = {
         "problem": "Write a function to find the longest palindromic substring in a given string."
     }
 )
 
-print("Workflow completed!")
-print("Workflow output:\n", output)
+if result.status == "success":
+    print("Workflow completed!")
+    print("Workflow output:\n", result.result)
+else:
+    print("Workflow failed:\n", result.displayable_error)
 ```
 
-You should specify all the required inputs for the workflow in the `inputs` argument of the `execute` method. 
+`WorkFlow.execute()` returns a `WorkflowResult` object. By default, `result.result` is the structured workflow output as a `dict`. If you want the older text-extraction behavior, call `workflow.execute(extract_output=True)`.
+
+You should specify all the required inputs for the workflow in the `inputs` argument of the `execute` method.
 
 For a complete working example, please refer to the [Sequential Workflow example](https://github.com/EvoAgentX/EvoAgentX/blob/main/examples/sequential_workflow.py). 
 

docs/tutorial/hitl.md

@@ -159,6 +159,11 @@ workflow = WorkFlow(graph=graph, llm=llm, agent_manager=manager, hitl_manager=hi
 result = await workflow.async_execute(inputs={
     "data_source": "2025Q2 financial report ..."
 })
+
+if result.status == "success":
+    print(result.result)
+else:
+    print(result.displayable_error)
 ```
 
 When the interceptor runs you will see a prompt like below. Type `a` (approve) or `r` (reject):

docs/tutorial/mcp.md

@@ -428,7 +428,10 @@ result = workflow.execute(inputs={
     "output_format": "summary"
 })
 
-print(f"Workflow result: {result}")
+if result.status == "success":
+    print(f"Workflow result: {result.result}")
+else:
+    print(f"Workflow failed: {result.displayable_error}")
 
 # Clean up
 toolkit.disconnect()

docs/tutorial/textgrad_optimizer.md

@@ -216,10 +216,10 @@ Below is an example of a saved workflow graph after optimization using `TextGrad
             "system_prompt": "You are a math-focused assistant dedicated to providing clear, concise, and educational solutions to mathematical problems. Your goal is to deliver structured and pedagogically sound explanations, ensuring mathematical accuracy and logical reasoning. Begin with a brief overview of the problem-solving approach, followed by detailed calculations, and conclude with a verification step. Use precise mathematical notation and consider potential edge cases. Present the final answer clearly, using the specified format, and incorporate visual aids or analogies where appropriate to enhance understanding and engagement. \n\nExplicitly include geometric explanations when applicable, describing the geometric context and relationships. Emphasize the importance of visual aids, such as diagrams or sketches, to enhance understanding. Ensure consistency in formatting and mathematical notation. Provide a brief explanation of the reference angle concept and its significance. Include contextual explanations of trigonometric identities and their applications. Critically evaluate initial assumptions and verify geometric properties before proceeding. Highlight the use of symmetry and conjugate pairs in complex numbers. Encourage re-evaluation and verification of steps, ensuring logical flow and clarity. Focus on deriving the correct answer and consider problem-specific strategies or known techniques.",
             "parse_mode": "str",
             "parse_func": null,
-            "parse_title": null
+            "title_format": "## {title}"
         }
     ]
 }
 ```
 
-For a complete working example, please refer to [examples/textgrad/math_textgrad.py](https://github.com/EvoAgentX/EvoAgentX/blob/main/examples/optimization/textgrad/math_textgrad.py). Additional TextGrad optimization scripts for other datasets (e.g., [`hotpotqa_textgrad.py`](https://github.com/EvoAgentX/EvoAgentX/blob/main/examples/optimization/textgrad/hotpotqa_textgrad.py) and [`mbqq_textgrad.py`](https://github.com/EvoAgentX/EvoAgentX/blob/main/examples/optimization/textgrad/mbpp_textgrad.py)) are available in the [examples/optimization/textgrad](https://github.com/EvoAgentX/EvoAgentX/tree/main/examples/optimization/textgrad) directory.
+For a complete working example, please refer to [examples/textgrad/math_textgrad.py](https://github.com/EvoAgentX/EvoAgentX/blob/main/examples/optimization/textgrad/math_textgrad.py). Additional TextGrad optimization scripts for other datasets (e.g., [`hotpotqa_textgrad.py`](https://github.com/EvoAgentX/EvoAgentX/blob/main/examples/optimization/textgrad/hotpotqa_textgrad.py) and [`mbqq_textgrad.py`](https://github.com/EvoAgentX/EvoAgentX/blob/main/examples/optimization/textgrad/mbpp_textgrad.py)) are available in the [examples/optimization/textgrad](https://github.com/EvoAgentX/EvoAgentX/tree/main/examples/optimization/textgrad) directory.

docs/zh/modules/workflow_graph.md

@@ -76,7 +76,7 @@
 - `output_parser`（可选）：用于解析任务输出的解析器
 - `parse_mode`（可选）：解析输出的模式，默认为 "str"
 - `parse_func`（可选）：用于解析输出的自定义函数
-- `parse_title`（可选）：解析输出的标题
+- `title_format`（可选）：当 `parse_mode` 为 "title" 时使用的标题格式，例如 "## {title}"
 
 与提示和解析相关的参数将用于在 `agent_manager` 中创建 `CustomizeAgent` 实例。有关代理配置的更多详细信息，请参阅[自定义代理](./customize_agent.md)文档。
 
@@ -182,9 +182,13 @@ agent_manager.add_agents_from_workflow(workflow_graph, llm_config=llm_config)
 
 # 创建工作流实例以执行
 workflow = WorkFlow(graph=workflow_graph, agent_manager=agent_manager, llm=llm)
-workflow.execute(inputs={"data_source": "xxx"})
+result = workflow.execute(inputs={"data_source": "xxx"})
+if result.status == "success":
+    print(result.result)
 ```
 
+`WorkFlow.execute()` 会返回一个 `WorkflowResult` 对象。默认情况下，工作流结果是结构化的 `dict` 输出。若想保留旧的文本抽取行为，可以传入 `extract_output=True`。
+
 ### 创建顺序工作流图
 
 ```python
@@ -254,4 +258,4 @@ sequential_workflow_graph.save_module("examples/output/my_sequential_workflow.js
 workflow_graph.display()
 ```
 
-`WorkFlowGraph` 和 `SequentialWorkFlowGraph` 类提供了一种灵活而强大的方式来设计复杂的代理工作流、跟踪其执行并管理任务之间的数据流。 
+`WorkFlowGraph` 和 `SequentialWorkFlowGraph` 类提供了一种灵活而强大的方式来设计复杂的代理工作流、跟踪其执行并管理任务之间的数据流。 

docs/zh/quickstart.md

@@ -130,8 +130,13 @@ agent_manager.add_agents_from_workflow(workflow_graph, llm_config=openai_config)
 代理准备就绪后，可以创建 `WorkFlow` 实例并运行：
 ```python
 workflow = WorkFlow(graph=workflow_graph, agent_manager=agent_manager, llm=llm)
-output = workflow.execute()
-print(output)
+result = workflow.execute()
+if result.status == "success":
+    print(result.result)
+else:
+    print(result.displayable_error)
 ```
 
-更多示例请参见 [完整工作流演示](https://github.com/EvoAgentX/EvoAgentX/blob/main/examples/workflow_demo.py)。
+`WorkFlow.execute()` 会返回一个 `WorkflowResult` 对象。默认情况下，`result.result` 是结构化的工作流输出，类型为 `dict`。如果你想保留旧的文本抽取行为，可以调用 `workflow.execute(extract_output=True)`。
+
+更多示例请参见 [完整工作流演示](https://github.com/EvoAgentX/EvoAgentX/blob/main/examples/workflow_demo.py)。

docs/zh/tutorial/first_workflow.md

@@ -111,16 +111,21 @@ agent_manager.add_agents_from_workflow(
 workflow = WorkFlow(graph=graph, agent_manager=agent_manager, llm=llm)
 
 # Execute the workflow with inputs
-output = workflow.execute(
+result = workflow.execute(
     inputs = {
         "problem": "Write a function to find the longest palindromic substring in a given string."
     }
 )
 
-print("Workflow completed!")
-print("Workflow output:\n", output)
+if result.status == "success":
+    print("Workflow completed!")
+    print("Workflow output:\n", result.result)
+else:
+    print("Workflow failed:\n", result.displayable_error)
 ```
 
+`WorkFlow.execute()` 会返回一个 `WorkflowResult` 对象。默认情况下，`result.result` 是结构化的工作流输出，类型为 `dict`。如果你想保留旧的文本抽取行为，可以调用 `workflow.execute(extract_output=True)`。
+
 你应该在 `execute` 方法的 `inputs` 参数中指定工作流所需的所有输入。
 
 有关完整的工作示例，请参考 [顺序工作流示例](https://github.com/EvoAgentX/EvoAgentX/blob/main/examples/sequential_workflow.py)。