工具

在本教程中，我们将展示如何使用 AgentScope 中内置的工具函数，以及如何创建自定义工具函数。

import json

import agentscope
from agentscope.message import Msg

内置工具函数

AgentScope 提供了一个 ServiceToolkit 模块，支持以下功能:

• 工具介绍生成,

• 提供一套默认的调用格式,

• 模型返回值解析、工具调用和面向智能体的错误处理。

在使用 ServiceToolkit 之前,我们可以先看一下 agentscope.service 模块中可用的工具。

from agentscope.service import get_help, ServiceResponse, ServiceExecStatus

get_help()

以上所有函数都是用 Python 函数实现的。 可以通过调用 add 方法注册到 ServiceToolkit 中。

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)

工具说明:
## 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.

内置的默认调用格式:

print(toolkit.tools_calling_format)

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

自动生成的工具函数 JSON Schema 格式说明:

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

{
  "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"
        ]
      }
    }
  }
}

AgentScope 提供了 ReActAgent 智能体类来使用工具，只需要将 ServiceToolkit 对象传递给这个智能体。 有关该智能体的实现细节，请参阅 内置智能体。

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)

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>用户希望我帮助他计算一个乘法问题，这个问题可以直接通过编程解决而不需要调用特定的工具函数。我可以直接计算这个数学表达式的结果。</thought>
<function>execute_shell_command</function>
<command>echo $((1615114134*4343434343))</command>
system: 1. Execute function execute_shell_command
   [ARGUMENTS]:
       command: echo $((1615114134*4343434343))
   [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>已经成功计算了用户给出的乘法表达式的结果。现在我应该使用finish函数来告诉用户结果。</thought>
<function>finish</function>
<response>计算 1615114134*4343434343 的结果是 7015142197480303962。</response>

创建工具函数

自定义工具函数必须遵循以下规则:

• 参数使用 typing 指定类型

• 使用 Google 风格书写完整的 docstring

• 函数返回值必须用 ServiceResponse 包装

def new_function(arg1: str, arg2: int) -> ServiceResponse:
    """简单介绍该函数。

    Args:
        arg1 (`str`):
            对 arg1 的简单描述
        arg2 (`int`):
            对 arg2 的简单描述
    """
    return ServiceResponse(
        status=ServiceExecStatus.SUCCESS,
        content="完成!",
    )