.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "tutorial/task_plan.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code. .. rst-class:: sphx-glr-example-title .. _sphx_glr_tutorial_task_plan.py: .. _plan: Plan ========================= The Plan Module enables agents to formally break down complex tasks into manageable sub-tasks and execute them systematically. Key features include: - Support **manual plan specification** - Comprehensive plan management capabilities: - **Creating, modifying, abandoning, and restoring** plans - **Switching** between multiple plans - **Gracefully handling interruptions** by temporarily suspending plans to address user queries or urgent tasks - **Real-time visualization and monitoring** of plan execution .. note:: The current plan module has the following limitations, and we are working on improving them: - The subtasks in a plan must be executed sequentially Specifically, the plan module works by - providing tool functions for plan management - inserting hint messages to guide the ReAct agent to complete the plan The following figure illustrates how the plan module works with the ReAct agent: .. figure:: ../../_static/images/plan.png :width: 90% :alt: Plan module :class: bordered-image :align: center How the plan module works with the ReAct agent .. GENERATED FROM PYTHON SOURCE LINES 37-45 .. code-block:: Python import asyncio import os from agentscope.agent import ReActAgent from agentscope.formatter import DashScopeChatFormatter from agentscope.model import DashScopeChatModel from agentscope.plan import PlanNotebook, Plan, SubTask .. GENERATED FROM PYTHON SOURCE LINES 46-129 PlanNotebook ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The `PlanNotebook` class is the core of the plan module, responsible for providing - plan-related tool functions - hint messages to guide the agent to finish the plan The `PlanNotebook` class can be instantiated with the following parameters: .. list-table:: Parameters of the `PlanNotebook` constructor :header-rows: 1 * - Name - Type - Description * - ``max_subtasks`` - ``int | None`` - The maximum number of subtasks allowed in a plan, infinite if None * - ``plan_to_hint`` - ``Callable[[Plan | None], str | None] | None`` - The function to generate hint message based on the current plan. If not provided, a default `DefaultPlanToHint` object will be used. * - ``storage`` - ``PlanStorageBase | None`` - The plan storage. If not provided, a default in-memory storage will be used. The ``plan_to_hint`` callable object is the most important part of the `PlanNotebook` class, also serves as the interface for prompt engineering. We have built a default `DefaultPlanToHint` class that can be used directly. Developers are encouraged to providing their own ``plan_to_hint`` function for better performance. The ``storage`` is to store historical plans, allowing agent to retrieve and restore historical plans. Developers are encouraged to implement their own plan storage by inheriting the ``PlanStorageBase`` class. If not provided, a default in-memory storage will be used. .. tip:: The ``PlanStorageBase`` class inherits from the ``StateModule`` class, so that the plan storage will also be saved and loaded by the session management. The core attributes and methods of the `PlanNotebook` class are summarized as follows: .. list-table:: Core attributes and methods of the `PlanNotebook` class :header-rows: 1 * - Type - Name - Description * - attribute - ``current_plan`` - The current plan that the agent is executing * - - ``storage`` - The storage for historical plans, used for retrieving and restoring historical plans * - - ``plan_to_hint`` - A callable object that takes the current plan as input and generates a hint message to guide the agent to finish the plan * - method - ``list_tools`` - List all the tool functions provided by the `PlanNotebook` class * - - ``get_current_hint`` - Get the hint message for the current plan, which will call the ``plan_to_hint`` function * - - | ``create_plan``, | ``view_subtasks``, | ``revise_current_plan``, | ``update_subtask_state``, | ``finish_subtask``, | ``finish_plan``, | ``view_historical_plans``, | ``recover_historical_plan`` - The tool functions that allows the agent to manage the plan and subtasks * - - ``register_plan_change_hook`` - Register a hook function that will be called when the plan is changed, used to plan visualization and monitoring * - - ``remove_plan_change_hook`` - Remove a registered plan change hook function The ``list_tools`` method is a quick way to obtain all tool functions, so that you can register them to the agent's toolkit. .. GENERATED FROM PYTHON SOURCE LINES 129-143 .. code-block:: Python plan_notebook = PlanNotebook() async def list_tools() -> None: """List the tool functions provided by PlanNotebook.""" print("The tools provided by PlanNotebook:") for tool in await plan_notebook.list_tools(): print(tool.__name__) asyncio.run(list_tools()) .. rst-class:: sphx-glr-script-out .. code-block:: none The tools provided by PlanNotebook: view_subtasks update_subtask_state finish_subtask create_plan revise_current_plan finish_plan view_historical_plans recover_historical_plan .. GENERATED FROM PYTHON SOURCE LINES 144-162 Working with ReActAgent ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The `ReActAgent` in AgentScope has integrated the plan module by a ``plan_notebook`` parameter in its constructor. Once provided, the agent will - be equipped with the plan management tool functions, and - be inserted with the hint messages at the beginning of each reasoning step There are two ways to use the plan module with the `ReActAgent`: - Manual plan specification: Users can manually create a plan by calling the ``create_plan`` tool function, and initialize the `ReActAgent` with the plan notebook. - Agent-managed plan execution: The agent will create and manage the plan by itself, by calling the plan management tool functions. Manual Plan Specification --------------------------------- Manually creating a plan is straightforward by calling the ``create_plan`` tool function. The following is an example of manually creating a plan to conduct a comprehensive research on the LLM-empowered agent. .. GENERATED FROM PYTHON SOURCE LINES 162-218 .. code-block:: Python async def manual_plan_specification() -> None: """Manual plan specification example.""" await plan_notebook.create_plan( name="Research on Agent", description="Conduct a comprehensive research on the LLM-empowered agent.", expected_outcome="A Markdown format report answer three questions: 1. What's agent? 2. What's the current state of the art of agent? 3. What's the future trend of agent?", subtasks=[ SubTask( name="Search agent-related survey papers", description=( "Search for survey parers on multiple sources, including " "Google Scholar, arXiv, and Semantic Scholar. Must be " "published after 2021 and have more than 50 citations." ), expected_outcome="A paper list in Markdown format", ), SubTask( name="Read and summarize the papers", description=( "Read the papers found in the previous step, and " "summarize the key points, including the definition, " "taxonomy, challenges, and key directions." ), expected_outcome="A summary of the key points in Markdown format", ), SubTask( name="Research on recent advances of large company", description=( "Research on the recent advances of large companies, " "including Google, Microsoft, OpenAI, Anthropic, Alibaba " "and Meta. Find the official blogs or news articles." ), expected_outcome="A recent advances of large company ", ), SubTask( name="Write a report", description=( "Write a report based on the previous steps, and answer " "the three questions in the expected outcome." ), expected_outcome=( "A Markdown format report answer three questions: 1. " "What's agent? 2. What's the current state of the art of " "agent? 3. What's the future trend of agent?" ), ), ], ) print("The current hint message:\n") msg = await plan_notebook.get_current_hint() print(f"{msg.name}: {msg.content}") asyncio.run(manual_plan_specification()) .. rst-class:: sphx-glr-script-out .. code-block:: none The current hint message: user: The current plan: ``` # Research on Agent **Description**: Conduct a comprehensive research on the LLM-empowered agent. **Expected Outcome**: A Markdown format report answer three questions: 1. What's agent? 2. What's the current state of the art of agent? 3. What's the future trend of agent? **State**: todo **Created At**: 2025-09-15 07:48:55.020 ## Subtasks - [ ] Search agent-related survey papers - [ ] Read and summarize the papers - [ ] Research on recent advances of large company - [ ] Write a report ``` Your options include: - Mark the first subtask as 'in_progress' by calling 'update_subtask_state' with subtask_idx=0 and state='in_progress', and start executing it. - If the first subtask is not executable, analyze why and what you can do to advance the plan, e.g. ask user for more information, revise the plan by calling 'revise_current_plan'. - If the user asks you to do something unrelated to the plan, prioritize the completion of user's query first, and then return to the plan afterward. - If the user no longer wants to perform the current plan, confirm with the user and call the 'finish_plan' function. .. GENERATED FROM PYTHON SOURCE LINES 219-221 After creating the plan, you can initialize the `ReActAgent` with the plan notebook as follows: .. GENERATED FROM PYTHON SOURCE LINES 221-233 .. code-block:: Python agent = ReActAgent( name="Friday", sys_prompt="You are a helpful assistant.", model=DashScopeChatModel( model_name="qwen-max", api_key=os.environ["DASHSCOPE_API_KEY"], ), formatter=DashScopeChatFormatter(), plan_notebook=plan_notebook, ) .. GENERATED FROM PYTHON SOURCE LINES 234-239 Agent-Managed Plan Execution --------------------------------- Agent can also create and manage the plan by itself, by calling the plan management tool functions. We just need to initialize the `ReActAgent` with the plan notebook as follows: .. GENERATED FROM PYTHON SOURCE LINES 239-251 .. code-block:: Python agent = ReActAgent( name="Friday", sys_prompt="You are a helpful assistant.", model=DashScopeChatModel( model_name="qwen-max", api_key=os.environ["DASHSCOPE_API_KEY"], ), formatter=DashScopeChatFormatter(), plan_notebook=PlanNotebook(), ) .. GENERATED FROM PYTHON SOURCE LINES 252-282 After that, we can build a loop to interact with the agent as follows. Once the task is complex, the agent will create a plan by itself and execute the plan step by step. .. code-block:: python :caption: Build conversation with the plan agent async def interact_with_agent() -> None: """Interact with the plan agent.""" user = UserAgent(name="user") msg = None while True: msg = await user(msg) if msg.get_text_content() == "exit": break msg = await agent(msg) asyncio.run(interact_with_agent()) Plan Visualization and Monitoring ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ AgentScope supports real-time visualization and monitoring of the plan execution by the plan change hook function. They will be triggered when the plan is changed by calling the tool functions. A template of the plan change hook function is as follows: .. GENERATED FROM PYTHON SOURCE LINES 282-294 .. code-block:: Python def plan_change_hook_template(self: PlanNotebook, plan: Plan) -> None: """A template of the plan change hook function. Args: self (`PlanNotebook`): The PlanNotebook instance. plan (`Plan`): The current plan instance (after the change). """ # Forward the plan to the frontend for visualization or other processing .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 0.029 seconds) .. _sphx_glr_download_tutorial_task_plan.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: task_plan.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: task_plan.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: task_plan.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_