.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "build_tutorial/tool.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_tool.py>`
        to download the full example code.

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

.. _sphx_glr_build_tutorial_tool.py:


.. _tools:

Tools
====================

In this tutorial we show how to use the built-in tools in AgentScope and
how to create custom tools.

.. GENERATED FROM PYTHON SOURCE LINES 11-16

.. code-block:: Python

    import json

    import agentscope
    from agentscope.message import Msg








.. GENERATED FROM PYTHON SOURCE LINES 17-27

Using Built-in Tools
--------------------------
AgentScope provides a `ServiceToolkit` module that supports

- tool introduction generation,
- a default call format,
- response parsing, tools calling and agent-oriented error handling.

Before using `ServiceToolkit`, we can take a look at the available tools in
the `agentscope.service` module.

.. GENERATED FROM PYTHON SOURCE LINES 27-32

.. code-block:: Python


    from agentscope.service import get_help, ServiceResponse, ServiceExecStatus

    get_help()








.. GENERATED FROM PYTHON SOURCE LINES 33-35

All above functions are implemented as Python functions.
They can be registered to the `ServiceToolkit` by calling the `add` method.

.. GENERATED FROM PYTHON SOURCE LINES 35-52

.. code-block:: Python


    from agentscope.service import ServiceToolkit
    from agentscope.service import bing_search, execute_shell_command

    toolkit = ServiceToolkit()
    toolkit.add(execute_shell_command)

    # Note some parameters of the tool functions (e.g. api_key) should be handled
    # by developers.
    # You can directly pass these parameters as keyword arguments in the add
    # method as follows, the reserved parameters will be left to the agent to fill.

    toolkit.add(bing_search, api_key="xxx")

    print("The tools instruction:")
    print(toolkit.tools_instruction)





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

 .. code-block:: none

    The tools instruction:
    ## Tool Functions:
    The following tool functions are available in the format of
    ```
    {index}. {function name}: {function description}
    {argument1 name} ({argument type}): {argument description}
    {argument2 name} ({argument type}): {argument description}
    ...
    ```

    1. execute_shell_command: Executes a given shell command.
            command (string): The shell command to execute.
    2. bing_search: Search question in Bing Search API and return the searching results
            num_results (number): The number of search results to return.
            question (string): The search query string.





.. GENERATED FROM PYTHON SOURCE LINES 53-54

The built-in default calling format:

.. GENERATED FROM PYTHON SOURCE LINES 54-57

.. code-block:: Python


    print(toolkit.tools_calling_format)





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

 .. code-block:: none

    [{"name": "{function name}", "arguments": {"{argument1 name}": xxx, "{argument2 name}": xxx}}]




.. GENERATED FROM PYTHON SOURCE LINES 58-59

The JSON Schema description of the tool functions:

.. GENERATED FROM PYTHON SOURCE LINES 59-63

.. code-block:: Python


    print(json.dumps(toolkit.json_schemas, indent=2))






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

 .. code-block:: none

    {
      "execute_shell_command": {
        "type": "function",
        "function": {
          "name": "execute_shell_command",
          "description": "Executes a given shell command.",
          "parameters": {
            "type": "object",
            "properties": {
              "command": {
                "type": "string",
                "description": "The shell command to execute."
              }
            },
            "required": [
              "command"
            ]
          }
        }
      },
      "bing_search": {
        "type": "function",
        "function": {
          "name": "bing_search",
          "description": "Search question in Bing Search API and return the searching results",
          "parameters": {
            "type": "object",
            "properties": {
              "num_results": {
                "type": "number",
                "description": "The number of search results to return.",
                "default": 10
              },
              "question": {
                "type": "string",
                "description": "The search query string."
              }
            },
            "required": [
              "question"
            ]
          }
        }
      }
    }




.. GENERATED FROM PYTHON SOURCE LINES 66-70

After assembling the `ServiceToolkit`, you can integrate it into agent.
In AgentScope, we provide a `ReActAgent` to handle the tool usage, you can
directly pass the `ServiceToolkit` object into this agent.
Refer to [] for implementation details of this agent.

.. GENERATED FROM PYTHON SOURCE LINES 70-93

.. code-block:: Python


    from agentscope.agents import ReActAgent

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

    agent = ReActAgent(
        name="Friday",
        model_config_name="my-qwen-max",
        service_toolkit=toolkit,
        sys_prompt="You're a helpful assistant named Friday.",
    )

    msg_task = Msg("user", "Help me to calculate 1615114134*4343434343", "user")

    res = agent(msg_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}>
    ...
    Friday: <thought>I need to calculate the product of the two numbers provided by the user. I will use the execute_shell_command function to perform the calculation using the 'bc' command, which is a command-line calculator.</thought>
    <function>execute_shell_command</function>
    <command>echo "1615114134*4343434343" | bc</command>
    system: 1. Execute function execute_shell_command
       [ARGUMENTS]:
           command: echo "1615114134*4343434343" | bc
       [STATUS]: SUCCESS
       [RESULT]: 7015142197480303962

    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}>
    ...
    Friday: <thought>The calculation was successful, and the result is 7015142197480303962. I will now inform the user of this result.</thought>
    <function>finish</function>
    <response>The product of 1615114134 and 4343434343 is 7015142197480303962.</response>




.. GENERATED FROM PYTHON SOURCE LINES 94-101

Creating Custom Tools
--------------------------
A custom tool function must follow these rules:

- Typing for arguments
- Well-written docstring in Google style
- The return of the function must be wrapped by `ServiceResponse`

.. GENERATED FROM PYTHON SOURCE LINES 101-116

.. code-block:: Python



    def new_function(arg1: str, arg2: int) -> ServiceResponse:
        """A brief introduction of this function in one line.

        Args:
            arg1 (`str`):
                Brief description of arg1
            arg2 (`int`):
                Brief description of arg2
        """
        return ServiceResponse(
            status=ServiceExecStatus.SUCCESS,
            content="Done!",
        )








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

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


.. _sphx_glr_download_build_tutorial_tool.py:

.. only:: html

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

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

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

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

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

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

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


.. only:: html

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

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