agentscope.service.service_toolkit

Service Toolkit for service function usage.

class ServiceFunction(name: str, original_func: Callable, processed_func: Callable, json_schema: dict)[source]

Bases: object

The service function class.

json_schema: dict: The JSON schema description of the service function.

name: str: The name of the service function.

original_func: Callable: The original function before processing.

processed_func: Callable: The processed function that can be called by the model directly.

require_args: bool: Whether calling the service function requests arguments. Some arguments may have default values, so it is not necessary to provide all arguments.

class ServiceToolkit[source]

Bases: object

A service toolkit class that turns service function into string prompt format.

add(service_func: Callable[[...], Any], func_description: str | None = None, include_long_description: bool = True, include_var_positional: bool = False, include_var_keyword: bool = False, **kwargs: Any) → None[source]

Add a service function to the toolkit, which will be processed into a tool function that can be called by the model directly, and registered in processed_funcs.

Parameters:

service_func (Callable[…, Any]) – The service function to be called.
func_description (Optional[str], defaults to None) – The function description. If not provided, the description will be extracted from the docstring automatically.
include_long_description (bool, defaults to True) – When extracting function description from the docstring, if the long description will be included.
include_var_positional (bool, defaults to False) – Whether to include the variable positional arguments (*args) in the function schema.
include_var_keyword (bool, defaults to False) – Whether to include the variable keyword arguments (**kwargs) in the function schema.
**kwargs (Any) – The keyword arguments that preset by developers, which will not be exposed to the agent

Returns:

A tuple of tool function and a dict in JSON Schema format to describe the function.

Return type:

Tuple(Callable[…, Any], dict)

Note

The description of the function and arguments are extracted from its docstring automatically, which should be well-formatted in Google style. Otherwise, their descriptions in the returned dictionary will be empty.

Example

def bing_search(query: str, api_key: str, num_results=10):
    """Search the query in Bing search engine.

        Args:
            query: (`str`):
                The string query to search.
            api_key: (`str`):
                The API key for Bing search.
            num_results: (`int`, optional):
                The number of results to return, default to 10.
    """

    # ... Your implementation here ...
    return ServiceResponse(status, output)

add_mcp_servers(server_configs: dict, enable_funcs: list[str] | None = None, disable_funcs: list[str] | None = None) → None[source]

Connect MCP servers according to the given configurations and add their tool functions into the toolkit.

Parameters:

server_configs (dict) – A config dictionary that follows the Model Context Protocol specification.
enable_funcs (Optional[list[str]], defaults to None) – The functions to be added into the toolkit. If None, all tool functions within the MCP servers will be added.
disable_funcs (Optional[list[str]], defaults to None) – The functions that will be filtered out. If None, no tool functions will be filtered out.

Example

One example for the server_configs:

{
    "mcpServers": {
        "{server1_name}": {
            "command": "npx",
            "args": [
                "-y",
                "@modelcontextprotocol/xxxx"
            ]
        },
        "{server2_name}": {
            "url": "http://xxx.xxx.xxx.xxx:xxxx/sse"
        }
    }
}

Fields:

“mcpServers”: A dictionary where each key is the server

name and the value is its configuration.

Field Details:

“command”: Specifies the command to execute,

which follows the stdio protocol for communication. - “args”: A list of arguments to be passed to the command. - “url”: Specifies the server’s URL, which follows the Server-Sent Events (SSE) protocol for data transmission.

classmethod get(service_func: Callable[[...], Any], func_description: str | None = None, include_long_description: bool = True, include_var_positional: bool = False, include_var_keyword: bool = False, **kwargs: Any) → Tuple[Callable[[...], Any], dict][source]

Convert a service function into a tool function that agent can use, and generate a dictionary in JSON Schema format that can be used in OpenAI API directly. While for open-source model, developers should handle the conversation from json dictionary to prompt.

Parameters:

service_func (Callable[…, Any]) – The service function to be called.
func_description (Optional[str], defaults to None) – The function description. If not provided, the description will be extracted from the docstring automatically.
include_long_description (bool, defaults to True) – When extracting function description from the docstring, if the long description will be included.
include_var_positional (bool, defaults to False) – Whether to include the variable positional arguments (*args) in the function schema.
include_var_keyword (bool, defaults to False) – Whether to include the variable keyword arguments (**kwargs) in the function schema.
**kwargs (Any) – The keyword arguments that preset by developers, which will not be exposed to the agent

Returns:

A tuple of tool function and a dict in JSON Schema format to describe the function.

Return type:

Tuple(Callable[…, Any], dict)

Note

The description of the function and arguments are extracted from its docstring automatically, which should be well-formatted in Google style. Otherwise, their descriptions in the returned dictionary will be empty.

Example

def bing_search(query: str, api_key: str, num_results: int=10):
    '''Search the query in Bing search engine.

    Args:
        query (`str`):
            The string query to search.
        api_key (`str`):
            The API key for Bing search.
        num_results (`int`):
            The number of results to return, default to 10.
    '''
    pass

parse_and_call_func(tool_calls: ToolUseBlock | list[ToolUseBlock], tools_api_mode: bool = False, raise_exception: bool = False) → Msg[source]

Execute the tool functions with the given arguments, and return the execution results.

Parameters:

tool_calls (Union[ToolUseBlock, list[ToolUseBlock]]) – A or a list of tool use blocks indicating the function calls.
tools_api_mode (bool, defaults to False) – If False, the execution results will be combined into a string content. If True, the results will be ContentBlock objects.
raise_exception (bool, defaults to False) – Whether to raise exceptions when the function call fails. If set to False, the error message will be wrapped in the ToolResultBlock and returned.

Returns:

A list of tool result blocks indicating the results of the function calls.

Return type:

list[ToolResultBlock]

remove(func_name: str) → None[source]

Remove a service function from the current toolkit.

Parameters:: func_name (str) – The name of the service function to be removed.

property json_schemas: dict: The json schema descriptions of the processed service funcs.

service_funcs: dict[str, ServiceFunction]: The registered functions in the service toolkit.

property tools_calling_format: str: The calling format of the tool functions.

property tools_instruction: str: The instruction of the tool functions.