.. 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 ` 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: {what you thought} {the function name you want to call} <{argument name}>{argument value} <{argument name}>{argument value} ... Friday: 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. execute_shell_command echo "1615114134*4343434343" | bc 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: {what you thought} {the function name you want to call} <{argument name}>{argument value} <{argument name}>{argument value} ... Friday: The calculation was successful, and the result is 7015142197480303962. I will now inform the user of this result. finish The product of 1615114134 and 4343434343 is 7015142197480303962. .. 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 ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: tool.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: tool.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_