.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "build_tutorial/builtin_agent.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_build_tutorial_builtin_agent.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_build_tutorial_builtin_agent.py:


.. _builtin_agent:

内置智能体
=============================

AgentScope 内置若干智能体类，以支持不同使用场景，同时展示如何使用 AgentScope 构建智能体。

.. list-table::
    :header-rows: 1

    * - 类
      - 描述
    * - `UserAgent`
      - 允许用户参与对话的智能体。
    * - `DialogAgent`
      - 使用自然语言交谈的智能体。
    * - `DictDialogAgent`
      - 支持结构化输出的智能体。
    * - `ReActAgent`
      - 以 reasoning-acting 循环的方式使用工具的智能体。
    * - `LlamaIndexAgent`
      - 检索增强型生成 (RAG) 智能体。

.. GENERATED FROM PYTHON SOURCE LINES 27-34

.. code-block:: Python


    import agentscope

    for module in agentscope.agents.__all__:
        if module.endswith("Agent"):
            print(module)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    DialogAgent
    DictDialogAgent
    UserAgent
    ReActAgent
    LlamaIndexAgent




.. GENERATED FROM PYTHON SOURCE LINES 35-37

.. note:: 为了使同一个智能体类能够支持不同的大语言模型 API，所有内置智能体类都通过模型配置名 `model_config_name` 来进行初始化。如果你构建的智能体不打算多个不同的模型，推荐可以显式地进行模型初始化，而不是使用模型配置名。


.. GENERATED FROM PYTHON SOURCE LINES 37-48

.. code-block:: Python


    import agentscope

    agentscope.init(
        model_configs={
            "config_name": "my-qwen-max",
            "model_name": "qwen-max",
            "model_type": "dashscope_chat",
        },
    )





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    []



.. GENERATED FROM PYTHON SOURCE LINES 49-54

DialogAgent
----------------------------
DialogAgent 是 AgentScope 中最基本的智能体，可以以对话的方式与用户交互。
开发者可以通过提供不同的系统提示和模型配置来自定义它。


.. GENERATED FROM PYTHON SOURCE LINES 54-69

.. code-block:: Python


    from agentscope.agents import DialogAgent
    from agentscope.message import Msg

    # 初始化一个对话智能体
    alice = DialogAgent(
        name="Alice",
        model_config_name="my-qwen-max",
        sys_prompt="你是一个名叫 Alice 的助手。",
    )

    # 向智能体发送一条消息
    msg = Msg("Bob", "嗨！你叫什么名字？", "user")
    response = alice(msg)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Alice: 嗨！我叫Alice，是你的助手。有什么可以帮助你的吗？




.. GENERATED FROM PYTHON SOURCE LINES 70-77

UserAgent
----------------------------
`UserAgent` 类允许用户与其他智能体交互。
当调用 `UserAgent` 对象时，它会要求用户输入，并将其格式化为 `Msg` 对象。

这里我们展示如何初始化一个 `UserAgent` 对象，并与对话智能体 `alice` 进行交互。


.. GENERATED FROM PYTHON SOURCE LINES 77-93

.. code-block:: Python


    from agentscope.agents import UserAgent
    from io import StringIO
    import sys

    user = UserAgent(
        name="Bob",
        input_hint="用户输入: \n",
    )

    # 模拟用户输入
    sys.stdin = StringIO("你认识我吗？\n")

    msg = user()
    msg = alice(msg)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    User Input: Bob: 你认识我吗？
    Alice: 你好，Bob！作为你的助手，我之前没有和你交流过，所以严格来说我不“认识”你。但我很乐意帮助你，并且会随着我们的交谈更多地了解你。希望这能解答你的问题！有什么特别的事情需要我帮忙吗？




.. GENERATED FROM PYTHON SOURCE LINES 94-100

DictDialogAgent
----------------------------
`DictDialogAgent` 支持结构化输出，并可通过 `set_parser` 方法指定解析器来实现自动后处理。

我们首先初始化一个 `DictDialogAgent` 对象，然后通过更换解析器，实现不同结构化的输出。


.. GENERATED FROM PYTHON SOURCE LINES 100-129

.. code-block:: Python


    from agentscope.agents import DictDialogAgent
    from agentscope.parsers import MarkdownJsonDictParser


    charles = DictDialogAgent(
        name="Charles",
        model_config_name="my-qwen-max",
        sys_prompt="你是一个名叫 Charles 的助手。",
        max_retries=3,  # 获取所需结构化输出失败时的最大重试次数
    )

    # 要求智能体生成包含 `thought`、`speak` 和 `decision` 的结构化输出
    parser1 = MarkdownJsonDictParser(
        content_hint={
            "thought": "你的想法",
            "speak": "你要说的话",
            "decision": "你的最终决定，true/false",
        },
        keys_to_metadata="decision",
        required_keys=["thought", "speak", "decision"],
    )

    charles.set_parser(parser1)
    msg1 = charles(Msg("Bob", "在下雨天外出是个好主意吗？", "user"))

    print(f"metadata字段: {msg1.metadata}")
    print(f"metadata字段的类型: {type(msg1.metadata)}")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Charles: ```json
    {"thought": "下雨天外出可能会让人感到不适，也有可能会感冒。但是，如果做好防雨措施并且目的地值得一去的话，也是可以考虑的。", "speak": "在下雨天外出可能不是最佳选择，因为天气不好且容易感冒。不过如果你有合适的雨具，并且觉得这次外出很重要或很有意义的话，也可以尝试一下。记得做好保暖和防水措施哦。", "decision": false}
    ```
    metadata字段: False
    metadata字段的类型: <class 'bool'>




.. GENERATED FROM PYTHON SOURCE LINES 130-132

然后，我们要求智能体从 1 到 10 中选择一个数字。


.. GENERATED FROM PYTHON SOURCE LINES 132-149

.. code-block:: Python


    parser2 = MarkdownJsonDictParser(
        content_hint={
            "thought": "你的想法",
            "speak": "你要说的话",
            "number": "你选择的数字",
        },
        keys_to_metadata="number",
        keys_to_content="speak",
    )

    charles.set_parser(parser2)
    msg2 = charles(Msg("Bob", "从 1 到 10 中选择一个数字。", "user"))

    print(f"响应消息的content字段: {msg2.content}")
    print(f"响应消息的metadata字段: {msg2.metadata}")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Charles: ```json
    {"thought": "Bob 让我从1到10中选一个数字，这可能只是一个简单的互动游戏。我会随机选择一个数字来回应他。", "speak": "我选的数字是7。你呢？有没有什么特别的原因让你喜欢某个数字？", "number": "7"}
    ```
    响应消息的content字段: 我选的数字是7。你呢？有没有什么特别的原因让你喜欢某个数字？
    响应消息的metadata字段: 7




.. GENERATED FROM PYTHON SOURCE LINES 150-154

下一个问题是如何对结构化输出进行后处理。
例如，`thought` 字段应该存储在记忆中而不暴露给其他人，
而 `speak` 字段应该显示给用户，`decision` 字段应该能够在响应消息对象中轻松访问。


.. GENERATED FROM PYTHON SOURCE LINES 154-178

.. code-block:: Python


    parser3 = MarkdownJsonDictParser(
        content_hint={
            "thought": "你的想法",
            "speak": "你要说的话",
            "number": "你选择的数字",
        },
        required_keys=["thought", "speak", "number"],
        keys_to_memory=["thought", "speak", "number"],  # 需要存储在记忆中
        keys_to_content="speak",  # 需要显示给用户
        keys_to_metadata="number",  # 需要存储在响应消息的元数据中
    )

    charles.set_parser(parser3)

    msg3 = charles(Msg("Bob", "从 20 到 30 中选择一个数字。", "user"))

    print(f"内容字段: {msg3.content}")
    print(f"内容字段的类型: {type(msg3.content)}\n")

    print(f"元数据字段: {msg3.metadata}")
    print(f"元数据字段的类型: {type(msg3.metadata)}")






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Charles: ```json
    {"thought": "Bob 再次让我选择一个数字，这次是从20到30之间。我会随机选取一个数字来继续我们的互动。", "speak": "我选的数字是23。你觉得这个范围内的哪个数字比较特别？", "number": "23"}
    ```
    内容字段: 我选的数字是23。你觉得这个范围内的哪个数字比较特别？
    内容字段的类型: <class 'str'>

    元数据字段: 23
    元数据字段的类型: <class 'str'>




.. GENERATED FROM PYTHON SOURCE LINES 179-187

.. hint:: 有关结构化输出的高级用法和更多不同解析器，请参阅 :ref:`structured-output` 章节。

ReActAgent
----------------------------
`ReActAgent` 以 reasoning-acting 循环的方式使用工具来解决给定的问题。

首先我们为智能体准备一个工具函数。


.. GENERATED FROM PYTHON SOURCE LINES 187-202

.. code-block:: Python


    from agentscope.service import ServiceToolkit, execute_python_code


    toolkit = ServiceToolkit()

    # 通过指定部分参数将 execute_python_code 设置为工具，这里用户需要在 add 方法里面配置部分
    # 参数，通常是一些应该由开发者提供的参数，例如 API Key 等，剩余参数由智能体自己填写。
    toolkit.add(
        execute_python_code,
        timeout=300,
        use_docker=False,
        maximum_memory_bytes=None,
    )








.. GENERATED FROM PYTHON SOURCE LINES 203-205

然后我们初始化一个 `ReActAgent` 来解决给定的问题。


.. GENERATED FROM PYTHON SOURCE LINES 205-222

.. code-block:: Python


    from agentscope.agents import ReActAgent

    david = ReActAgent(
        name="David",
        model_config_name="my-qwen-max",
        sys_prompt="你是一个名叫 David 的助手。",
        service_toolkit=toolkit,
        max_iters=10,
        verbose=True,
    )

    task = Msg("Bob", "请帮我计算 151513434*54353453453。", "user")

    response = david(task)






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    system: Respond with specific tags as outlined below:
    <thought>{what you thought}</thought>
    <function>{the function name you want to call}</function>
    <{argument name}>{argument value}</{argument name}>
    <{argument name}>{argument value}</{argument name}>
    ...
    David: <thought>我需要使用execute_python_code函数来计算这个乘法表达式的结果。</thought>
    <function>execute_python_code</function>
    <code>print(151513434*54353453453)</code>
    system: 1. Execute function execute_python_code
       [ARGUMENTS]:
           {"code": "print(151513434*54353453453)"}
       [RESULT]: <returncode>0</returncode>
    <stdout>8235278382423187602
    </stdout>
    <stderr></stderr>

    system: Respond with specific tags as outlined below:
    <thought>{what you thought}</thought>
    <function>{the function name you want to call}</function>
    <{argument name}>{argument value}</{argument name}>
    <{argument name}>{argument value}</{argument name}>
    ...
    David: <thought>已经得到了计算结果，现在可以告诉Bob了。</thought>
    <function>finish</function>
    <response>计算 151513434*54353453453 的结果是 8235278382423187602。</response>
    system: 1. Execute function finish
       [ARGUMENTS]:
           {"response": "计算 151513434*54353453453 的结果是 8235278382423187602。"}
       [RESULT]: 计算 151513434*54353453453 的结果是 8235278382423187602。





.. GENERATED FROM PYTHON SOURCE LINES 223-227

LlamaIndexAgent
----------------------------
有关更多详细信息，请参阅检索增强型生成 (RAG) 章节。



.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 27.066 seconds)


.. _sphx_glr_download_build_tutorial_builtin_agent.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: builtin_agent.ipynb <builtin_agent.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: builtin_agent.py <builtin_agent.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: builtin_agent.zip <builtin_agent.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_