.. 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: 工具 ==================== 在本教程中，我们将展示如何使用 AgentScope 中内置的工具函数，以及如何创建自定义工具函数。 .. GENERATED FROM PYTHON SOURCE LINES 10-15 .. code-block:: Python import json import agentscope from agentscope.message import Msg .. GENERATED FROM PYTHON SOURCE LINES 16-26 内置工具函数 -------------------------- AgentScope 提供了一个 `ServiceToolkit` 模块，支持以下功能: - 工具介绍生成, - 提供一套默认的调用格式, - 模型返回值解析、工具调用和面向智能体的错误处理。 在使用 `ServiceToolkit` 之前,我们可以先看一下 `agentscope.service` 模块中可用的工具。 .. GENERATED FROM PYTHON SOURCE LINES 26-31 .. code-block:: Python from agentscope.service import get_help, ServiceResponse, ServiceExecStatus get_help() .. GENERATED FROM PYTHON SOURCE LINES 32-35 以上所有函数都是用 Python 函数实现的。 可以通过调用 `add` 方法注册到 `ServiceToolkit` 中。 .. GENERATED FROM PYTHON SOURCE LINES 35-50 .. code-block:: Python from agentscope.service import ServiceToolkit from agentscope.service import bing_search, execute_shell_command toolkit = ServiceToolkit() toolkit.add(execute_shell_command) # 注意,一些工具函数的参数（例如 api_key）应该由开发人员处理。 # 你可以直接在 add 方法中以关键字参数的形式传递这些参数，保留其他参数留给智能体填写。 toolkit.add(bing_search, api_key="xxx") print("工具说明:") print(toolkit.tools_instruction) .. rst-class:: sphx-glr-script-out .. code-block:: none 工具说明: ## 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 51-53 内置的默认调用格式: .. GENERATED FROM PYTHON SOURCE LINES 53-56 .. 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 57-59 自动生成的工具函数 JSON Schema 格式说明: .. GENERATED FROM PYTHON SOURCE LINES 59-62 .. 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 63-66 AgentScope 提供了 `ReActAgent` 智能体类来使用工具，只需要将 `ServiceToolkit` 对象传递给这个智能体。 有关该智能体的实现细节，请参阅 :ref:`builtin_agent`。 .. GENERATED FROM PYTHON SOURCE LINES 66-89 .. 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="你是一个名为 Friday 的助手。", ) msg_task = Msg("user", "帮我计算一下 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: 用户希望我帮助他计算一个乘法问题，这个问题可以直接通过编程解决而不需要调用特定的工具函数。我可以直接计算这个数学表达式的结果。 execute_shell_command echo $((1615114134*4343434343)) system: 1. Execute function execute_shell_command [ARGUMENTS]: command: echo $((1615114134*4343434343)) [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: 已经成功计算了用户给出的乘法表达式的结果。现在我应该使用finish函数来告诉用户结果。 finish 计算 1615114134*4343434343 的结果是 7015142197480303962。 .. GENERATED FROM PYTHON SOURCE LINES 90-98 创建工具函数 -------------------------- 自定义工具函数必须遵循以下规则: - 参数使用 typing 指定类型 - 使用 Google 风格书写完整的 docstring - 函数返回值必须用 `ServiceResponse` 包装 .. GENERATED FROM PYTHON SOURCE LINES 98-113 .. code-block:: Python def new_function(arg1: str, arg2: int) -> ServiceResponse: """简单介绍该函数。 Args: arg1 (`str`): 对 arg1 的简单描述 arg2 (`int`): 对 arg2 的简单描述 """ return ServiceResponse( status=ServiceExecStatus.SUCCESS, content="完成!", ) .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 12.364 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 `_