init

functionality/plan/README.md

@@ -0,0 +1,30 @@
+# Plan with ReAct Agent
+
+This example demonstrates how to use the plan module in AgentScope to make an agent create and manage a plan formally.
+
+Specifically, we provide two examples: manual specification plan and Agent-managed plan.
+
+## Manual Specification Plan
+
+In this example, we first manually specify a plan for the agent to follow, then we let the agent execute the plan step by step.
+
+To execute this example, run:
+
+```bash
+python main_manual_plan.py
+```
+
+## Agent-managed Plan
+
+In this example, we let the agent create and manage its own plan.
+Specifically, we use a query "Review the recent changes in AgentScope GitHub repository over the past month."
+
+To run the example, execute:
+
+```bash
+python main_agent_managed_plan.py
+```
+
+> Note: The example is built with DashScope chat model. If you want to change the model in this example, don't forget
+> to change the **formatter** at the same time! The corresponding relationship between built-in models and formatters
+> are list in [our tutorial](https://doc.agentscope.io/tutorial/task_prompt.html#id1)

functionality/plan/main_agent_managed_plan.py

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+"""The main entry point of the plan example."""
+import asyncio
+import os
+
+from agentscope.agent import ReActAgent, UserAgent
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.plan import PlanNotebook
+from agentscope.tool import (
+    Toolkit,
+    execute_python_code,
+    execute_shell_command,
+    insert_text_file,
+    view_text_file,
+    write_text_file,
+)
+
+
+async def main() -> None:
+    """The main entry point for the plan example."""
+    toolkit = Toolkit()
+    toolkit.register_tool_function(execute_shell_command)
+    toolkit.register_tool_function(execute_python_code)
+    toolkit.register_tool_function(write_text_file)
+    toolkit.register_tool_function(insert_text_file)
+    toolkit.register_tool_function(view_text_file)
+
+    agent = ReActAgent(
+        name="Friday",
+        sys_prompt="""You're a helpful assistant named Friday.
+
+# Target
+Your target is to finish the given task with careful planning.
+
+# Note
+- You can equip yourself with plan related tools to help you plan and execute the given task.
+- The resouces from search engines are not always correct, you should collect information from multiple sources and give the final answer after careful consideration.
+""",  # noqa
+        model=DashScopeChatModel(
+            model_name="qwen3-max-preview",
+            api_key=os.environ["DASHSCOPE_API_KEY"],
+        ),
+        formatter=DashScopeChatFormatter(),
+        toolkit=toolkit,
+        enable_meta_tool=True,
+        plan_notebook=PlanNotebook(),
+    )
+    user = UserAgent(name="user")
+
+    msg = Msg(
+        "user",
+        "Review the recent changes in AgentScope GitHub repository "
+        "over the past month.",
+        "user",
+    )
+    while True:
+        msg = await agent(msg)
+        msg = await user(msg)
+        if msg.get_text_content() == "exit":
+            break
+
+
+asyncio.run(main())

functionality/plan/main_manual_plan.py

@@ -0,0 +1,101 @@
+# -*- coding: utf-8 -*-
+"""Manual specification plan example."""
+import asyncio
+import os
+
+from agentscope.agent import ReActAgent, UserAgent
+from agentscope.formatter import DashScopeChatFormatter
+from agentscope.message import Msg
+from agentscope.model import DashScopeChatModel
+from agentscope.plan import PlanNotebook, SubTask
+from agentscope.tool import (
+    Toolkit,
+    execute_python_code,
+    execute_shell_command,
+    insert_text_file,
+    view_text_file,
+    write_text_file,
+)
+
+plan_notebook = PlanNotebook()
+
+
+async def main() -> None:
+    """The main entry point for the manual plan example."""
+
+    # Create the plan manually
+    await plan_notebook.create_plan(
+        name="Comprehensive Report on AgentScope",
+        description="Study the code of AgentScope and write a comprehensive "
+        "report about this framework.",
+        expected_outcome="A markdown format report summarizing the features, "
+        "architecture, advantages/disadvantages, and "
+        "potential improvements of AgentScope.",
+        subtasks=[
+            SubTask(
+                name="Clone the repository",
+                description="Clone the AgentScope GitHub repository from "
+                "agentscope-ai/agentscope, and ensure it's the "
+                "latest version.",
+                expected_outcome="A local copy of the AgentScope repository.",
+            ),
+            SubTask(
+                name="View the documentation",
+                description="View the documentation of AgentScope in the "
+                "repository.",
+                expected_outcome="A comprehensive understanding of the "
+                "features and usage of AgentScope.",
+            ),
+            SubTask(
+                name="Study the code",
+                description="Study the code of AgentScope, focusing on the "
+                "core modules and their interactions.",
+                expected_outcome="A deep understanding of the architecture "
+                "and implementation of AgentScope.",
+            ),
+            SubTask(
+                name="Summarize the findings",
+                description="Summarize the findings from the documentation "
+                "and code study, and write a comprehensive report "
+                "in markdown format.",
+                expected_outcome="A markdown format report",
+            ),
+        ],
+    )
+
+    # Add basic tools
+    toolkit = Toolkit()
+    toolkit.register_tool_function(execute_shell_command)
+    toolkit.register_tool_function(execute_python_code)
+    toolkit.register_tool_function(write_text_file)
+    toolkit.register_tool_function(insert_text_file)
+    toolkit.register_tool_function(view_text_file)
+
+    # Create the agent
+    agent = ReActAgent(
+        name="Friday",
+        sys_prompt="You're a helpful assistant named Friday. Your target is "
+        "to finish the given task with careful planning.",
+        model=DashScopeChatModel(
+            model_name="qwen3-max-preview",
+            api_key=os.environ["DASHSCOPE_API_KEY"],
+        ),
+        formatter=DashScopeChatFormatter(),
+        toolkit=toolkit,
+        plan_notebook=plan_notebook,
+    )
+    user = UserAgent(name="user")
+
+    msg = Msg(
+        "user",
+        "Now start to finish the task by the given plan",
+        "user",
+    )
+    while True:
+        msg = await agent(msg)
+        msg = await user(msg)
+        if msg.get_text_content() == "exit":
+            break
+
+
+asyncio.run(main())

functionality/plan/requirements.txt

@@ -0,0 +1 @@
+agentscope[full]>=1.0.5