.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "tutorial/quickstart_agent.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_quickstart_agent.py: .. _react-agent: 创建 ReAct 智能体 ==================== AgentScope 在 ``agentscope.agent`` 模块下提供了开箱即用的 ReAct 智能体 ``ReActAgent`` 供开发者使用。 它同时支持以下功能： - ✨ 基础功能 - 支持围绕 ``reply``、``observe``、``print``、``_reasoning`` 和 ``_acting`` 的 **钩子函数（hooks）** - 支持结构化输出 - ✋ 实时介入（Realtime Steering） - 支持用户 **中断** - 支持自定义 **中断处理** - 🛠️ 工具 - 支持 **同步/异步** 工具函数 - 支持 **流式** 工具响应 - 支持 **状态化** 的工具管理 - 支持 **并行** 工具调用 - 支持 **MCP** 服务器 - 💾 记忆 - 支持智能体 **自主管理** 长期记忆 - 支持“静态”的长期记忆管理 .. tip:: 有关这些功能的更多详细信息，请参考 :ref:`agent` 部分。本章节中，我们重点介绍如何创建 ReAct 智能体并运行。 .. GENERATED FROM PYTHON SOURCE LINES 31-43 .. code-block:: Python from agentscope.agent import ReActAgent, AgentBase from agentscope.formatter import DashScopeChatFormatter from agentscope.memory import InMemoryMemory from agentscope.message import Msg from agentscope.model import DashScopeChatModel import asyncio import os from agentscope.tool import Toolkit, execute_python_code .. GENERATED FROM PYTHON SOURCE LINES 44-99 创建 ReAct 智能体 ------------------------------ 为了提高灵活性，``ReActAgent`` 类在其构造函数中暴露了以下参数： .. list-table:: ``ReActAgent`` 类的初始化参数 :header-rows: 1 * - 参数 - 进一步阅读 - 描述 * - ``name`` (必需) - - 智能体的名称 * - ``sys_prompt`` (必需) - - 智能体的系统提示 * - ``model`` (必需) - :ref:`model` - 智能体用于生成响应的模型 * - ``formatter`` (必需) - :ref:`prompt` - 提示构建策略，应与使用的模型保持一致 * - ``toolkit`` - :ref:`tool` - 用于注册/调用工具函数的工具模块 * - ``memory`` - :ref:`memory` - 用于存储对话历史的短期记忆 * - ``long_term_memory`` - :ref:`long-term-memory` - 长期记忆 * - ``long_term_memory_mode`` - :ref:`long-term-memory` - 长期记忆的管理模式： - ``agent_control``: 允许智能体通过工具函数自己控制长期记忆 - ``static_control``: 在每次回复（reply）的开始/结束时，会自动从长期记忆中检索/记录信息 - ``both``: 同时激活上述两种模式 * - ``enable_meta_tool`` - :ref:`tool` - 是否启用元工具（Meta tool），即允许智能体自主管理工具函数 * - ``parallel_tool_calls`` - :ref:`agent` - 是否允许并行工具调用 * - ``max_iters`` - - 智能体生成响应的最大迭代次数 * - ``plan_notebook`` - :ref:`plan` - 计划模块，允许智能体制定和管理计划与子任务 * - ``print_hint_msg`` - - 是否在终端打印 ``plan_notebook`` 生成的提示消息 以 DashScope API 为例，我们创建一个智能体对象如下： .. GENERATED FROM PYTHON SOURCE LINES 99-132 .. code-block:: Python async def creating_react_agent() -> None: """创建一个 ReAct 智能体并运行一个简单任务。""" # 准备工具 toolkit = Toolkit() toolkit.register_tool_function(execute_python_code) jarvis = ReActAgent( name="Jarvis", sys_prompt="你是一个名为 Jarvis 的助手", model=DashScopeChatModel( model_name="qwen-max", api_key=os.environ["DASHSCOPE_API_KEY"], stream=True, enable_thinking=False, ), formatter=DashScopeChatFormatter(), toolkit=toolkit, memory=InMemoryMemory(), ) msg = Msg( name="user", content="你好！Jarvis，用 Python 运行 Hello World。", role="user", ) await jarvis(msg) asyncio.run(creating_react_agent()) .. rst-class:: sphx-glr-script-out .. code-block:: pytb Traceback (most recent call last): File "/Users/hjt0309/Documents/AI_project/agentscope_doc/agentscope-main/docs/tutorial/zh_CN/src/quickstart_agent.py", line 130, in asyncio.run(creating_react_agent()) File "/opt/miniconda3/lib/python3.12/asyncio/runners.py", line 194, in run return runner.run(main) ^^^^^^^^^^^^^^^^ File "/opt/miniconda3/lib/python3.12/asyncio/runners.py", line 118, in run return self._loop.run_until_complete(task) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/opt/miniconda3/lib/python3.12/asyncio/base_events.py", line 686, in run_until_complete return future.result() ^^^^^^^^^^^^^^^ File "/Users/hjt0309/Documents/AI_project/agentscope_doc/agentscope-main/docs/tutorial/zh_CN/src/quickstart_agent.py", line 127, in creating_react_agent await jarvis(msg) File "/Users/hjt0309/Documents/AI_project/agentscope_doc/agentscope-main/src/agentscope/agent/_agent_base.py", line 451, in __call__ reply_msg = await self.reply(*args, **kwargs) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/Users/hjt0309/Documents/AI_project/agentscope_doc/agentscope-main/src/agentscope/agent/_agent_meta.py", line 120, in async_wrapper current_output = await original_func( ^^^^^^^^^^^^^^^^^^^^ File "/Users/hjt0309/Documents/AI_project/agentscope_doc/agentscope-main/src/agentscope/tracing/_trace.py", line 392, in wrapper return await func(self, *args, **kwargs) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/Users/hjt0309/Documents/AI_project/agentscope_doc/agentscope-main/src/agentscope/agent/_react_agent.py", line 309, in reply msg_reasoning = await self._reasoning(tool_choice) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/Users/hjt0309/Documents/AI_project/agentscope_doc/agentscope-main/src/agentscope/agent/_agent_meta.py", line 120, in async_wrapper current_output = await original_func( ^^^^^^^^^^^^^^^^^^^^ File "/Users/hjt0309/Documents/AI_project/agentscope_doc/agentscope-main/src/agentscope/agent/_react_agent.py", line 448, in _reasoning async for content_chunk in res: File "/Users/hjt0309/Documents/AI_project/agentscope_doc/agentscope-main/src/agentscope/model/_dashscope_model.py", line 284, in _parse_dashscope_stream_response raise RuntimeError( RuntimeError: Failed to get response from _ API: {"status_code": 401, "request_id": "0f81254b-84c0-48b9-a8eb-5fcacaaac3bc", "code": "InvalidApiKey", "message": "Invalid API-key provided.", "output": null, "usage": null} .. GENERATED FROM PYTHON SOURCE LINES 133-160 从零开始创建 -------------------------------- 为了支持开发者从零开始创建智能体，AgentScope 提供了两个基类： .. list-table:: :header-rows: 1 * - 类 - 抽象方法 - 描述 * - ``AgentBase`` - | ``reply`` | ``observe`` | ``handle_interrupt`` - - 所有智能体的基类，支持 ``reply``、``observe`` 和 ``print`` 函数的前置和后置钩子函数。 - 在 ``__call__`` 函数内实现了基础的实时介入（Realtime Steering）逻辑。 * - ``ReActAgentBase`` - | ``reply`` | ``observe`` | ``handle_interrupt`` | ``_reasoning`` | ``_acting`` - 在 ``AgentBase`` 的基础上添加了两个抽象函数 ``_reasoning`` 和 ``_acting``，以及它们的钩子函数。 有关智能体类的更多详细信息，请参考 :ref:`agent` 部分。 以 ``AgentBase`` 类为例，我们可以通过继承它并实现 ``reply`` 方法来创建自定义智能体类。 .. GENERATED FROM PYTHON SOURCE LINES 160-235 .. code-block:: Python class MyAgent(AgentBase): """自定义智能体类""" def __init__(self) -> None: """初始化智能体""" super().__init__() self.name = "Friday" self.sys_prompt = "你是一个名为 Friday 的助手。" self.model = DashScopeChatModel( model_name="qwen-max", api_key=os.environ["DASHSCOPE_API_KEY"], stream=False, ) self.formatter = DashScopeChatFormatter() self.memory = InMemoryMemory() async def reply(self, msg: Msg | list[Msg] | None) -> Msg: """直接调用大模型，产生回复消息。""" await self.memory.add(msg) # 准备提示 prompt = await self.formatter.format( [ Msg("system", self.sys_prompt, "system"), *await self.memory.get_memory(), ], ) # 调用模型 response = await self.model(prompt) msg = Msg( name=self.name, content=response.content, role="assistant", ) # 在记忆中记录响应 await self.memory.add(msg) # 打印消息 await self.print(msg) return msg async def observe(self, msg: Msg | list[Msg] | None) -> None: """观察消息。""" # 将消息存储在记忆中 await self.memory.add(msg) async def handle_interrupt(self) -> Msg: """处理中断。""" # 以固定响应为例 return Msg( name=self.name, content="我注意到您打断了我的回复，我能为你做些什么？", role="assistant", ) async def run_custom_agent() -> None: """运行自定义智能体。""" agent = MyAgent() msg = Msg( name="user", content="你是谁？", role="user", ) await agent(msg) asyncio.run(run_custom_agent()) .. GENERATED FROM PYTHON SOURCE LINES 236-243 进一步阅读 --------------------- - :ref:`agent` - :ref:`model` - :ref:`prompt` - :ref:`tool` .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 0.202 seconds) .. _sphx_glr_download_tutorial_quickstart_agent.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: quickstart_agent.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: quickstart_agent.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: quickstart_agent.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_