Tool

Service function is a set of multi-functional utility tools that can be used to enhance the capabilities of agents, such as executing Python code, web search, file operations, and more. This tutorial provides an overview of the service functions available in AgentScope and how to use them to enhance the capabilities of your agents.

Built-in Service Functions

The following table outlines the various Service functions by type. These functions can be called using agentscope.service.{function_name}.

Service Scene	Service Function Name	Description
Code	`execute_python_code`	Execute a piece of Python code, optionally inside a Docker container.
	`NoteBookExecutor`	Compute Execute a segment of Python code in the IPython environment of the NoteBookExecutor, adhering to the IPython interactive computing style.
Retrieval	`retrieve_from_list`	Retrieve a specific item from a list based on given criteria.
	`cos_sim`	Compute the cosine similarity between two different embeddings.
SQL Query	`query_mysql`	Execute SQL queries on a MySQL database and return results.
	`query_sqlite`	Execute SQL queries on a SQLite database and return results.
	`query_mongodb`	Perform queries or operations on a MongoDB collection.
Text Processing	`summarization`	Summarize a piece of text using a large language model to highlight its main points.
Web	`bing_search`	Perform bing search
	`google_search`	Perform google search
	`arxiv_search`	Perform arXiv search
	`download_from_url`	Download file from given URL.
	`load_web`	Load and parse the web page of the specified url (currently only supports HTML).
	`digest_webpage`	Digest the content of a already loaded web page (currently only supports HTML).
	`dblp_search_publications`	Search publications in the DBLP database
	`dblp_search_authors`	Search for author information in the DBLP database
	`dblp_search_venues`	Search for venue information in the DBLP database
	`tripadvisor_search`	Search for locations using the TripAdvisor API.
	`tripadvisor_search_location_photos`	Retrieve photos for a specific location using the TripAdvisor API.
	`tripadvisor_search_location_details`	Get detailed information about a specific location using the TripAdvisor API.
File	`create_file`	Create a new file at a specified path, optionally with initial content.
	`delete_file`	Delete a file specified by a file path.
	`move_file`	Move or rename a file from one path to another.
	`create_directory`	Create a new directory at a specified path.
	`delete_directory`	Delete a directory and all its contents.
	`move_directory`	Move or rename a directory from one path to another.
	`read_text_file`	Read and return the content of a text file.
	`write_text_file`	Write text content to a file at a specified path.
	`read_json_file`	Read and parse the content of a JSON file.
	`write_json_file`	Serialize a Python object to JSON and write to a file.
Multi Modality	`dashscope_text_to_image`	Convert text to image using Dashscope API.
	`dashscope_image_to_text`	Convert image to text using Dashscope API.
	`dashscope_text_to_audio`	Convert text to audio using Dashscope API.
	`openai_text_to_image`	Convert text to image using OpenAI API
	`openai_edit_image`	Edit an image based on the provided mask and prompt using OpenAI API
	`openai_create_image_variation`	Create variations of an image using OpenAI API
	`openai_image_to_text`	Convert text to image using OpenAI API
	`openai_text_to_audio`	Convert text to audio using OpenAI API
	`openai_audio_to_text`	Convert audio to text using OpenAI API
More services coming soon		More service functions are in development and will be added to AgentScope to further enhance its capabilities.

About each service function, you can find detailed information in the API document.

How to use Service Functions

AgentScope provides two classes for service functions, ServiceToolkit and ServiceResponse.

About Service Toolkit

The use of tools for LLM usually involves five steps:

Prepare tool functions. That is, developers should pre-process the functions by providing necessary parameters, e.g. api key, username, password, etc.
Prepare instruction for LLM. A detailed description for these tool functions are required for the LLM to understand them properly.
Guide LLM how to use tool functions. A format description for calling functions is required.
Parse LLM response. Once the LLM generates a response, we need to parse it according to above format in the third step.
Call functions and handle exceptions. Calling the functions, return the results, and handle exceptions.

To simplify the above steps and improve reusability, AgentScope introduces ServiceToolkit. It can

register python functions
generate tool function descriptions in both string and JSON schema format
generate usage instruction for LLM
parse the model response, call the tool functions, and handle exceptions

How to use

Follow the steps below to use ServiceToolkit:

Init a ServiceToolkit object and register service functions with necessary parameters. Take the following Bing search function as an example.

def bing_search(
    question: str,
    api_key: str,
    num_results: int = 10,
    **kwargs: Any,
) -> ServiceResponse:
    """
    Search question in Bing Search API and return the searching results

    Args:
        question (`str`):
            The search query string.
        api_key (`str`):
            The API key provided for authenticating with the Bing Search API.
        num_results (`int`, defaults to `10`):
            The number of search results to return.
        **kwargs (`Any`):
            Additional keyword arguments to be included in the search query.
            For more details, please refer to
            https://learn.microsoft.com/en-us/bing/search-apis/bing-web-search/reference/query-parameters

    [omitted for brevity]
    """

We register the function in a ServiceToolkit object by providing api_key and num_results as necessary parameters.

from agentscope.service import ServiceToolkit

service_toolkit = ServiceToolkit()

service_toolkit.add(
    bing_search,
    api_key="xxx",
    num_results=3
)

Use the tools_instruction attribute to instruct LLM in prompt, or use the json_schemas attribute to get the JSON schema format descriptions to construct customized instruction or directly use in model APIs (e.g. OpenAI Chat API).

>> print(service_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. bing_search: Search question in Bing Search API and return the searching results
    question (str): The search query string.

>> print(service_toolkit.json_schemas)
{
  "bing_search": {
      "type": "function",
      "function": {
          "name": "bing_search",
          "description": "Search question in Bing Search API and return the searching results",
          "parameters": {
              "type": "object",
              "properties": {
                  "question": {
                      "type": "string",
                      "description": "The search query string."
                  }
              },
              "required": [
                  "question"
              ]
          }
      }
  }
}

Guide LLM how to use tool functions by the tools_calling_format attribute. The ServiceToolkit module requires LLM to return a list of dictionaries in JSON format, where each dictionary represents a function call. It must contain two fields, name and arguments, where name is the function name and arguments is a dictionary that maps from the argument name to the argument value.

>> print(service_toolkit.tools_calling_format)
[{"name": "{function name}", "arguments": {"{argument1 name}": xxx, "{argument2 name}": xxx}}]

Parse the LLM response and call functions by its parse_and_call_func method. This function takes a string or a parsed dictionary as input.

When the input is a string, this function will parse it accordingly and execute the function with the parsed arguments.
While if the input is a parse dictionary, it will call the function directly.

# a string input
string_input = '[{"name": "bing_search", "arguments": {"question": "xxx"}}]'
res_of_string_input = service_toolkit.parse_and_call_func(string_input)

# or a parsed dictionary
dict_input = [{"name": "bing_search", "arguments": {"question": "xxx"}}]
# res_of_dict_input is the same as res_of_string_input
res_of_dict_input = service_toolkit.parse_and_call_func(dict_input)

print(res_of_string_input)

1. Execute function bing_search
    [ARGUMENTS]:
        question: xxx
    [STATUS]: SUCCESS
    [RESULT]: ...

More specific examples refer to the ReActAgent class in agentscope.agents.

Create new Service Function

A new service function that can be used by ServiceToolkit should meet the following requirements:

Well-formatted docstring (Google style is recommended), so that the ServiceToolkit can extract both the function descriptions.
The name of the service function should be self-explanatory, so that the LLM can understand the function and use it properly.
The typing of the arguments should be provided when defining the function (e.g. def func(a: int, b: str, c: bool)), so that the agent can specify the arguments properly.

About ServiceResponse

ServiceResponse is a wrapper for the execution results of the services, containing two fields, status and content. When the Service function runs to completion normally, status is ServiceExecStatus.SUCCESS, and content is the return value of the function. When an error occurs during execution, status is ServiceExecStatus.Error, and content contains the error message.

class ServiceResponse(dict):
    """Used to wrap the execution results of the services"""

    __setattr__ = dict.__setitem__
    __getattr__ = dict.__getitem__

    def __init__(
        self,
        status: ServiceExecStatus,
        content: Any,
    ):
        """Constructor of ServiceResponse

        Args:
            status (`ServiceExeStatus`):
                The execution status of the service.
            content (`Any`)
                If the argument`status` is `SUCCESS`, `content` is the
                response. We use `object` here to support various objects,
                e.g. str, dict, image, video, etc.
                Otherwise, `content` is the error message.
        """
        self.status = status
        self.content = content

    # [omitted for brevity]

Example

import json
import inspect
from agentscope.service import ServiceResponse
from agentscope.agents import AgentBase
from agentscope.message import Msg

from typing import Optional, Union, Sequence


def create_file(file_path: str, content: str = "") -> ServiceResponse:
    """
    Create a file and write content to it.

    Args:
        file_path (str): The path to the file to be created.
        content (str): The content to be written to the file.

    Returns:
        ServiceResponse: A boolean indicating success or failure, and a
        string containing any error message (if any), including the error type.
    """
    # ... [omitted for brevity]


class YourAgent(AgentBase):
    # ... [omitted for brevity]

    def reply(self, x: Optional[Union[Msg, Sequence[Msg]]] = None) -> Msg:
        # ... [omitted for brevity]

        # construct a prompt to ask the agent to provide the parameters in JSON format
        prompt = (
            f"To complete the user request\n```{x['content']}```\n"
            "Please provide the necessary parameters in JSON format for the "
            "function:\n"
            f"Function: {create_file.__name__}\n"
            "Description: Create a file and write content to it.\n"
        )

        # add detailed information about the function parameters
        sig = inspect.signature(create_file)
        parameters = sig.parameters.items()
        params_prompt = "\n".join(
            f"- {name} ({param.annotation.__name__}): "
            f"{'(default: ' + json.dumps(param.default) + ')'if param.default is not inspect.Parameter.empty else ''}"
            for name, param in parameters
        )
        prompt += params_prompt

        # get the model response
        model_response = self.model(prompt).text

        # parse the model response and call the create_file function
        try:
            kwargs = json.loads(model_response)
            create_file(**kwargs)
        except:
            # Error handling
            pass

        # ... [omitted for brevity]

[Return to Top]