agentscope.service package

Subpackages

Submodules

Module contents

Import all service-related modules in the package.

class agentscope.service.ServiceResponse(status: ServiceExecStatus, content: Any)[源代码]

基类：dict

Used to wrap the execution results of the services

__init__(status: ServiceExecStatus, content: Any)[源代码]

Constructor of ServiceResponse

参数:

  • 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.

class agentscope.service.ServiceExecStatus(value)[源代码]

基类：IntEnum

Enum for service execution status.

SUCCESS = 1
ERROR = -1
class agentscope.service.ServiceToolkit[源代码]

基类：object

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

__init__() → None[源代码]

Initialize the service toolkit with a list of service functions.

service_funcs: dict[str, ServiceFunction]

The registered functions in the service toolkit.

add(service_func: Callable[[...], Any], **kwargs: Any) → None[源代码]

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.

参数:

  • service_func (Callable[…, Any]) – The service function to be called.

  • kwargs (Any) – The arguments to be passed to the service function.

返回:

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

返回类型:

Tuple(Callable[…, Any], dict)

备注

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.

Suggestions:

1. The name of the service function should be self-explanatory, so that the agent can understand the function and use it properly. 2. 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. 3. The execution results should be a ServiceResponse object.

示例

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)
property json_schemas: dict

The json schema descriptions of the processed service funcs.

property tools_calling_format: str

The calling format of the tool functions.

property tools_instruction: str

The instruction of the tool functions.

parse_and_call_func(text_cmd: list[dict] | str, raise_exception: bool = False) → Msg[源代码]

Parse, check the text and call the function.

classmethod get(service_func: Callable[[...], Any], **kwargs: Any) → Tuple[Callable[[...], Any], dict][源代码]

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.

参数:

  • service_func (Callable[…, Any]) – The service function to be called.

  • kwargs (Any) – The arguments to be passed to the service function.

返回:

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

返回类型:

Tuple(Callable[…, Any], dict)

备注

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.

Suggestions:

1. The name of the service function should be self-explanatory, so that the agent can understand the function and use it properly. 2. 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.

示例

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
agentscope.service.get_help() → None[源代码]

Get help message.

agentscope.service.execute_python_code(code: str, timeout: int | float | None = 300, use_docker: bool | str | None = None, maximum_memory_bytes: int | None = None) → ServiceResponse[源代码]

Execute a piece of python code.

This function can run Python code provided in string format. It has the option to execute the code within a Docker container to provide an additional layer of security, especially important when running untrusted code.

WARNING: If use_docker is set to False, the code will be run directly in the host system’s environment. This poses a potential security risk if the code is untrusted. Only disable Docker if you are confident in the safety of the code being executed.

参数:

  • code (str, optional) – The Python code to be executed.

  • timeout (Optional[Union[int, float]], defaults to 300) – The maximum time (in seconds) allowed for the code to run. If the code execution time exceeds this limit, it will be terminated. Set to None for no time limit. Default is 300.

  • use_docker (Optional[Union[bool, str]], defaults to None) – Determines whether to execute the code within a Docker container. If False, the system’s native Python environment is used. When set to None, the function checks for Docker’s availability and uses it if present. When set to some string, will use the docker with string as the image name. Default is None.

  • maximum_memory_bytes (Optional[int], defaults to None) – The memory limit in bytes for the code execution. If not specified, there is no memory limit imposed.

返回:

A ServiceResponse containing two elements: output and error. Both output and error are strings that capture the standard output and standard error of the code execution, respectively.

返回类型:

ServiceResponse

备注

IPython-specific operations such as plt.show() for displaying matplotlib plots are currently not supported. This limitation stems from the non-interactive nature of the execution environment.

The argument timeout is not available in Windows OS, since the since signal.setitimer is only available in Unix.

agentscope.service.execute_shell_command(command: str) → ServiceResponse[源代码]

Executes a given shell command.

参数:

command (str) – The shell command to execute.

返回:

Contains either the output from the shell command as a string if sucessful, or an error message include the error type.

返回类型:

ServiceResponse

备注

Use any bash/shell commands you want (e.g. find, grep, cat, ls), but note that : 1. interactive session commands (e.g. python, vim) or commands that change current state (e.g. cd that change the current directory) are NOT supported yet, so please do not invoke them. 2. be VERY CAREFUL when using commands that will change/edit the files current directory (e.g. rm, sed).

…

agentscope.service.create_file(file_path: str, content: str = '') → ServiceResponse[源代码]

Create a file and write content to it.

参数:

  • file_path (str) – The path where the file will be created.

  • content (str) – Content to write into the file.

返回:

Where the boolean indicates success, and the str contains an error message if any, including the error type.

返回类型:

ServiceResponse

agentscope.service.delete_file(file_path: str) → ServiceResponse[源代码]

Delete a file specified by the file path.

参数:

file_path (str) – The path of the file to be deleted.

返回:

Where the boolean indicates success, and the str contains an error message if any, including the error type.

返回类型:

ServiceResponse

agentscope.service.move_file(source_path: str, destination_path: str) → ServiceResponse[源代码]

Move a file from a source path to a destination path.

参数:

  • source_path (str) – The current path of the file.

  • destination_path (str) – The new path for the file.

返回:

Where the boolean indicates success, and the str contains an error message if any, including the error type.

返回类型:

ServiceResponse

agentscope.service.create_directory(directory_path: str) → ServiceResponse[源代码]

Create a directory at the specified path.

参数:

directory_path (str) – The path where the directory will be created.

返回:

where the boolean indicates success, and the str contains an error message if any, including the error type.

返回类型:

ServiceResponse

agentscope.service.delete_directory(directory_path: str) → ServiceResponse[源代码]

Delete a directory and all of its contents.

参数:

directory_path (str) – The path of the directory to be deleted.

返回:

Where the boolean indicates success, and the str contains an error message if any, including the error type.

返回类型:

ServiceResponse

agentscope.service.move_directory(source_path: str, destination_path: str) → ServiceResponse[源代码]

Move a directory from a source path to a destination path.

参数:

  • source_path (str) – The current path of the directory.

  • destination_path (str) – The new path for the directory.

返回:

Where the boolean indicates success, and the str contains an error message if any, including the error type.

返回类型:

ServiceResponse

agentscope.service.list_directory_content(directory_path: str) → ServiceResponse[源代码]

List the contents of a directory. i.e. ls -a

参数:

directory_path (str) – The path of the directory to show.

返回:

The results contain a list of direcotry contents, or an error message if any, including the error type.

返回类型:

ServiceResponse

agentscope.service.get_current_directory() → ServiceResponse[源代码]

Get the current working directory path.

返回:

The current working directory path, or an error message if any, including the error type.

返回类型:

ServiceResponse

agentscope.service.read_text_file(file_path: str) → ServiceResponse[源代码]

Read the content of the text file.

参数:

file_path (str) – The path to the text file to be read.

返回:

A tuple (bool, str) where the boolean indicates success, and the str contains the file content or an error message if any, including the error type.

返回类型:

ServiceResponse

agentscope.service.write_text_file(file_path: str, content: str, overwrite: bool = False) → ServiceResponse[源代码]

Write content to a text file.

参数:

  • file_path (str) – The path to the file where content will be written.

  • content (str) – Content to write into the file.

  • overwrite (bool, defaults to False) – Whether to overwrite the file if it already exists.

返回:

where the boolean indicates success, and the str contains an error message if any, including the error type.

返回类型:

ServiceResponse

agentscope.service.read_json_file(file_path: str) → ServiceResponse[源代码]

Read and parse a JSON file.

参数:

file_path (str) – The path to the JSON file to be read.

返回:

Where the boolean indicates success, the Any is the parsed JSON content (typically a dict), and the str contains an error message if any, including the error type.

返回类型:

ServiceResponse

agentscope.service.write_json_file(file_path: str, data: Any, overwrite: bool = False) → ServiceResponse[源代码]

Serialize data to a JSON file.

参数:

  • file_path (str) – The path to the file where the JSON data will be written.

  • data (Any) – The data to serialize to JSON.

  • overwrite (bool) – Whether to overwrite the file if it already exists.

返回:

where the boolean indicates success, and the str contains an error message if any, including the error type.

返回类型:

ServiceResponse

Search question in Bing Search API and return the searching results

参数:
返回:

A dictionary with two variables: status and content. The status variable is from the ServiceExecStatus enum, and content is a list of search results or error information, which depends on the status variable. For each searching result, it is a dictionary with keys ‘title’, ‘link’, and ‘snippet’.

返回类型:

ServiceResponse

示例

results = bing_search(question="What is an agent?",
                     bing_api_key="your bing api key",
                     num_results=2,
                     mkt="en-US")
print(results)

It returns the following dict.

{
    'status': <ServiceExecStatus.SUCCESS: 1>,
    'content': [
        {
            'title': 'What Is an Agent? Definition, Types of
                Agents, and Examples - Investopedia',
            'link':
            'https://www.investopedia.com/terms/a/agent.asp',
            'snippet': "An agent is someone that is given
                permission (either explicitly or assumed) to act
                on an individual's behalf and may do so in a
                variety of capacities. This could include
                selling a home, executing..."},
        {
            'title': 'AGENT Definition & Usage Examples |
                        Dictionary.com',
            'link': 'https://www.dictionary.com/browse/agent',
            'snippet': 'noun. a person who acts on behalf of
                another person, group, business, government,
                etc; representative. a person or thing that acts
                or has the power to act. a phenomenon,
                substance, or organism that exerts some force or
                effect: a chemical agent.'
        }
    ]
}

Search question in Google Search API and return the searching results

参数:

  • question (str) – The search query string.

  • api_key (str) – The API key provided for authenticating with the Google Custom Search JSON API.

  • cse_id (str) – The unique identifier of a programmable search engine to use.

  • 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://developers.google.com/custom-search/v1/reference/rest/v1/cse/list

返回:

A dictionary with two variables: status and content. The status variable is from the ServiceExecStatus enum, and content is a list of search results or error information, which depends on the status variable. For each searching result, it is a dictionary with keys ‘title’, ‘link’, and ‘snippet’.

返回类型:

ServiceResponse

示例

results = google_search(
    'Python programming',
    'your_google_api_key',
    'your_cse_id',
    num_results=2
)
if results.status == ServiceExecStatus.SUCCESS:
    for result in results.content:
        print(result['title'], result['link'], result['snippet'])

Search arXiv paper by a given query string.

参数:

  • search_query (str) – The query string, supporting prefixes “all:”, “ti:”, “au:”, “abs:”, “co:”, “jr:”, “cat:”, and “rn:”, boolean operators “AND”, “OR” and “ANDNOT”. For example, searching for papers with title “Deep Learning” and author “LeCun” by a search_query ti:”Deep Learning” AND au:”LeCun”

  • id_list (List[str], defaults to None) – A list of arXiv IDs to search.

  • start (int, defaults to 0) – The index of the first search result to return.

  • max_results (Optional[int], defaults to None) – The maximum number of search results to return.

返回:

A dictionary with two variables: status and content. The status variable is from the ServiceExecStatus enum, and content is a list of search results or error information, which depends on the status variable.

返回类型:

ServiceResponse

Search the given query in Wikipedia. Note the returned text maybe related entities, which means you should adjust your query as needed and search again.

Note the returned text maybe too long for some llm, it’s recommended to summarize the returned text first.

参数:

query (str) – The searched query in wikipedia.

返回:

A response that contains the execution status and returned content.

返回类型:

ServiceResponse

agentscope.service.wikipedia_search_categories(query: str, max_members: int = 1000) → ServiceResponse[源代码]

Retrieve categories from Wikipedia:Category pages.

参数:

  • query (str) – The given searching keywords

  • max_members (int) – The maximum number of members to output

返回:

A response that contains the execution status and returned content. In the returned content, the meanings of keys:

  • ”pageid”: unique page ID for the member

  • ”ns”: namespace for the member

  • ”title”: title of the member

Example:

members = wiki_get_category_members(
    "Machine_learning",
    max_members=10
)
print(members)

It returns contents:

{
    'status': <ServiceExecStatus.SUCCESS: 1>,
    'content': [
        {
            'pageid': 67911196,
            'ns': 0,
            'title': 'Bayesian learning mechanisms'
        },
        {
            'pageid': 233488,
            'ns': 0,
            'title': 'Machine learning'
        },
        # ...
    ]
}

返回类型:

ServiceResponse

agentscope.service.query_mysql(database: str, query: str, host: str, user: str, password: str, port: int, allow_change_data: bool = False, maxcount_results: int | None = None, **kwargs: Any) → ServiceResponse[源代码]

Execute query within MySQL database.

参数:

  • database (str) – The name of the database to use.

  • query (str) – SQL query to execute.

  • host (str) – The host name or IP address of the MySQL server, e.g. “localhost”.

  • user (str) – The username of the MySQL account to use.

  • password (str) – The password of the MySQL account to use.

  • port (str) – The port number of the MySQL server, e.g. 3306.

  • allow_change_data (bool, defaults to False) – Whether to allow changing data in the database. Defaults to False to avoid accidental changes to the database.

  • maxcount_results (int, defaults to None) – The maximum number of results to return. Defaults to 100 to avoid too many results.

返回:

A ServiceResponse object that contains execution results or error message.

返回类型:

ServiceResponse

agentscope.service.query_sqlite(database: str, query: str, allow_change_data: bool = False, maxcount_results: int | None = None, **kwargs: Any) → ServiceResponse[源代码]

Executes query within sqlite database.

参数:

  • database (str) – The name of the database to use.

  • query (str) – The query to execute.

  • allow_change_data (bool, defaults to False) – Whether to allow changing data in the database. Defaults to False to avoid accidental changes to the database.

  • maxcount_results (int, defaults to None) – The maximum number of results to return.

返回:

A ServiceResponse object that contains execution results or error message.

返回类型:

ServiceResponse

agentscope.service.query_mongodb(database: str, collection: str, query: dict, host: str, port: int, maxcount_results: int | None = None, **kwargs: Any) → ServiceResponse[源代码]

Execute query within MongoDB database.

参数:

  • database (str) – The name of the database to use.

  • collection (str) – The name of the collection to use in mongodb.

  • query (dict) – The mongodb query to execute.

  • host (str) – The hostname or IP address of the MongoDB server.

  • port (int) – The port number of MongoDB server.

  • maxcount_results (int, defaults to None) – The maximum number of results to return. Defaults to 100 to avoid too many results.

  • **kwargs

返回:

A ServiceResponse object that contains execution results or error message.

返回类型:

ServiceResponse

备注

MongoDB is a little different from mysql and sqlite, for its operations corresponds to different functions. Now we only support find query and leave other operations in the future.

agentscope.service.cos_sim(a: list[Number], b: list[Number]) → ServiceResponse[源代码]

Compute the cosine similarity between two different embeddings

参数:

  • a (Embedding) – Embedding

  • b (Embedding) – Embedding

返回:

A float.

返回类型:

ServiceResponse

agentscope.service.summarization(model: ModelWrapperBase, text: str, system_prompt: str = '\nYou are a helpful agent to summarize the text.\nYou need to keep all the key information of the text in the summary.\n', max_return_token: int = -1, token_limit_prompt: str = '\nSummarize the text after TEXT in less than {} tokens:\n') → ServiceResponse[源代码]

Summarize the input text.

Summarization function (Notice: current version of token limitation is built with Open AI API)

参数:

  • model (ModelWrapperBase) – Model used to summarize provided text.

  • text (str) – Text to be summarized by the model.

  • system_prompt (str, defaults to _DEFAULT_SYSTEM_PROMPT) – Prompts as instruction for the system, will be as an instruction for the model.

  • max_return_token (int, defaults to -1) – Whether provide additional prompting instruction to limit the number of tokens in summarization returned by the model.

  • token_limit_prompt (str, defaults to _DEFAULT_TOKEN_LIMIT_PROMPT) – Prompt to instruct the model follow token limitation.

返回:

If the model successfully summarized the text, and the summarization satisfies the provided token limitation, return ServiceResponse with ServiceExecStatus.SUCCESS; otherwise return ServiceResponse with ServiceExecStatus.ERROR (if the summary is return successfully but exceed the token limits, the content contains the summary as well).

返回类型:

ServiceResponse

Example:

The default message with text to be summarized:

[
    {
        "role": "system",
        "name": "system",
        "content": "You are a helpful agent to summarize the text.\
        You need to keep all the key information of the text in the\
        summary."
    },
    {
        "role": "user",
        "name": "user",
        "content": text
    },
]

Messages will be processed by model.format() before feeding to models.

agentscope.service.retrieve_from_list(query: Any, knowledge: Sequence, score_func: Callable[[Any, Any], float], top_k: int | None = None, embedding_model: ModelWrapperBase | None = None, preserve_order: bool = True) → ServiceResponse[源代码]

Retrieve data in a list.

Memory retrieval with user-defined score function. The score function is expected to take the query and one of the element in ‘knowledge’ (a list). This function retrieves top-k elements in ‘knowledge’ with HIGHEST scores. If the ‘query’ is a dict but has no embedding, we use the embedding model to embed the query.

参数:

  • query (Any) – A message to be retrieved.

  • knowledge (Sequence) – Data/knowledge to be retrieved from.

  • score_func (Callable[[Any, Any], float]) – User-defined function for comparing two messages.

  • top_k (int, defaults to None) – Maximum number of messages returned.

  • embedding_model (Optional[ModelWrapperBase], defaults to None) – A model to embed the query/message.

  • preserve_order (bool, defaults to True) – Whether to preserve the original order of the retrieved data. Defaults to True.

返回:

The top-k retrieved messages with HIGHEST scores.

返回类型:

ServiceResponse

agentscope.service.digest_webpage(web_text_or_url: str, model: ModelWrapperBase | None = None, html_selected_tags: Sequence[str] = ('h', 'p', 'li', 'div', 'a'), digest_prompt: str = "You're a web page analyser. You job is to extract importantand useful information from html or webpage description.\n") → ServiceResponse[源代码]

Digest the given webpage.

参数:

  • web_text_or_url (str) – preprocessed web text or url to the web page

  • model (ModelWrapperBase) – the model to digest the web content

  • html_selected_tags (Sequence[str]) – the text in elements of html_selected_tags will be extracted and feed to the model

  • digest_prompt (str) – system prompt for the model to digest the web content

返回:

If successful, ServiceResponse object is returned with content field filled with the model output.

返回类型:

ServiceResponse

agentscope.service.load_web(url: str, keep_raw: bool = True, html_selected_tags: Sequence[str] | None = None, self_parse_func: Callable[[Response], Any] | None = None, timeout: int = 5) → ServiceResponse[源代码]

Function for parsing and digesting the web page.

参数:

  • url (str) – the url of the web page

  • keep_raw (bool) – Whether to keep raw HTML. If True, the content is stored with key “raw”.

  • html_selected_tags (Optional[Sequence[str]]) – the text in elements of html_selected_tags will be extracted and stored with “html_to_text” key in return.

  • self_parse_func (Optional[Callable]) – if “self_parse_func” is not None, then the function will be invoked with the requests.Response as input. The result is stored with self_define_func key

  • timeout (int) – timeout parameter for requests.

返回:

If successful, ServiceResponse object is returned with content field is a dict, where keys are subset of:

”raw”: exists if keep_raw is True, store raw HTML content`;

”self_define_func”: exists if self_parse_func is provided, store the return of self_define_func;

”html_to_text”: exists if html_selected_tags is provided and not empty;

”json”: exists if url links to a json webpage, then it is parsed as json.

For example, ServiceResponse.content field is

{
    "raw": xxxxx,
    "selected_tags_text": xxxxx
}

返回类型:

ServiceResponse

agentscope.service.parse_html_to_text(html_text: str, html_selected_tags: Sequence[str] | None = None) → str[源代码]

Parse the obtained HTML file.

参数:

  • html_text (str) – HTML source code

  • html_selected_tags (Optional[Sequence[str]]) – the text in elements of html_selected_tags will be extracted and returned.

返回:

If successful, ServiceResponse object is returned with content field is processed text content of the selected tags,

返回类型:

ServiceResponse

agentscope.service.download_from_url(url: str, filepath: str, timeout: int = 120, retries: int = 3) → ServiceResponse[源代码]

Download file from the given url to the specified location.

参数:

  • url (str) – The URL of the file to download.

  • filepath (str) – The path to save the downloaded file.

  • timeout (int, defaults to 120) – The timeout for the download request.

  • retries (int, defaults to 3) – The number of retries for the download request.

返回:

A ServiceResponse object that contains execution results or error message.

返回类型:

ServiceResponse

agentscope.service.dblp_search_publications(question: str, num_results: int = 30, start: int = 0, num_completion: int = 10) → ServiceResponse[源代码]

Search publications in the DBLP database.

参数:

  • question (str) – The search query string.

  • num_results (int, defaults to 30) – The number of search results to return.

  • start (int, defaults to 0) – The index of the first search result to return.

  • num_completion (int, defaults to 10) – The number of completions to generate.

返回:

A dictionary containing status and content. The status attribute is from the ServiceExecStatus enum, indicating success or error. The content is a list of parsed publication data if successful, or an error message if failed. Each item in the list contains publication information includes title, authors, venue, pages, year, type, DOI, and URL.

返回类型:

ServiceResponse

示例

It returns the following structure:

{
    'status': <ServiceExecStatus.SUCCESS: 1>,
    'content': [
        {
            'title': 'Power transformers fault diagnosis
            based on a meta-learning approach to kernel
            extreme learning machine with opposition-based
            learning sparrow search algorithm.',
            'venue': 'J. Intell. Fuzzy Syst.',
            'pages': '455-466',
            'year': '2023',
            'type': 'Journal Articles',
            'doi': '10.3233/JIFS-211862',
            'url': 'https://dblp.org/rec/journals/jifs/YuTZTCH23',
            'authors': 'Song Yu, Weimin Tan, Chengming Zhang,
            Chao Tang, Lihong Cai, Dong Hu'
        },
        {
            'title': 'Performance comparison of Extreme Learning
            Machinesand other machine learning methods
            on WBCD data set.',
            'venue': 'SIU',
            'pages': '1-4',
            'year': '2021',
            'type': 'Conference and Workshop Papers',
            'doi': '10.1109/SIU53274.2021.9477984',
            'url': 'https://dblp.org/rec/conf/siu/KeskinDAY21',
            'authors': 'Ömer Selim Keskin, Akif Durdu,
            Muhammet Fatih Aslan, Abdullah Yusefi'
        }
    ]
}
agentscope.service.dblp_search_authors(question: str, num_results: int = 30, start: int = 0, num_completion: int = 10) → ServiceResponse[源代码]

Search for author information in the DBLP database.

参数:

  • question (str) – The search query string.

  • num_results (int, defaults to 30) – The number of search results to return.

  • start (int, defaults to 0) – The index of the first search result to return.

  • num_completion (int, defaults to 10) – The number of completions to generate.

返回:

A dictionary containing status and content. The status attribute is from the ServiceExecStatus enum, indicating the success or error of the search. The content is a list of parsed author data if successful, or an error message if failed. Each item in the list contains author information including their name, URL, and affiliations.

返回类型:

ServiceResponse

示例

search_results = dblp_search_authors(question="Liu ZiWei",
                                     num_results=3,
                                     results_per_page=1,
                                     num_completion=1)
print(search_results)

It returns the following structure:

{
    'status': <ServiceExecStatus.SUCCESS: 1>,
    'content': [
        {
            'author': 'Ziwei Liu 0001',
            'url': 'https://dblp.org/pid/05/6300-1',
            'affiliations': 'Advantech Singapore Pte Ltd,
            Singapore;
            National University of Singapore,
            Department of Computer Science, Singapore'
        },
        {
            'author': 'Ziwei Liu 0002',
            'url': 'https://dblp.org/pid/05/6300-2',
            'affiliations': 'Nanyang Technological University,
            S-Lab, Singapore;
            Chinese University of Hong Kong,
            Department of Information Engineering,
            Hong Kong'
        }
    ]
}
agentscope.service.dblp_search_venues(question: str, num_results: int = 30, start: int = 0, num_completion: int = 10) → ServiceResponse[源代码]

Search for venue information in the DBLP database.

参数:

  • question (str) – The search query string.

  • num_results (int, defaults to 30) – The number of search results to return.

  • start (int, defaults to 0) – The index of the first search result to return.

  • num_completion (int, defaults to 10) – The number of completions to generate.

返回:

A dictionary containing status and content. The status attribute is from the ServiceExecStatus enum, indicating the success or error of the search. The content is a list of parsed venue data if successful, or an error message if failed. Each item in the list contains venue information including its name, acronym, type, and URL.

返回类型:

ServiceResponse

示例

search_results = dblp_search_venues(question="AAAI",
                                     num_results=1,
                                     results_per_page=1,
                                     num_completion=1)
print(search_results)

It returns the following structure:

{
    'status': <ServiceExecStatus.SUCCESS: 1>,
    'content': [
        {
            'venue': 'AAAI Conference on Artificial Intelligence
            (AAAI)',
            'acronym': 'AAAI',
            'type': 'Conference or Workshop',
            'url': 'https://dblp.org/db/conf/aaai/'
        },
        {
            'venue': ''AAAI Fall Symposium Series',
            'acronym': 'No acronym available',
            'type': 'Conference or Workshop',
            'url': 'https://dblp.org/db/conf/aaaifs/'
        }
    ]
}
class agentscope.service.NoteBookExecutor(timeout: int = 300)[源代码]

基类：object

Class for executing jupyter notebooks block interactively. To use the service function, you should first init the class, then call the run_code_on_notebook function.

Example:

```ipython from agentscope.service.service_toolkit import * from agentscope.service.execute_code.exec_notebook import * nbe = NoteBookExecutor() code = “print(‘helloworld’)” # calling directly nbe.run_code_on_notebook(code)

>>> Executing function run_code_on_notebook with arguments:
>>>     code: print('helloworld')
>>> END

# calling with service toolkit service_toolkit = ServiceToolkit() service_toolkit.add(nbe.run_code_on_notebook) input_obs = [{“name”: “run_code_on_notebook”, “arguments”:{“code”: code}}] res_of_string_input = service_toolkit.parse_and_call_func(input_obs)

“1. Execute function run_code_on_notebook

[ARGUMENTS]:

code: print(‘helloworld’)

[STATUS]: SUCCESS [RESULT]: [‘helloworldn’]

“

__init__(timeout: int = 300) → None[源代码]

The construct function of the NoteBookExecutor. :param timeout: The timeout for each cell execution.

Default to 300.

property cells_length: int

return cell length

async async_run_code_on_notebook(code: str) → ServiceResponse[源代码]

Run the code on interactive notebook

run_code_on_notebook(code: str) → ServiceResponse[源代码]

Run the code on interactive jupyter notebook.

参数:

code (str) – The Python code to be executed in the interactive notebook.

返回:

whether the code execution was successful, and the output of the code execution.

返回类型:

ServiceResponse

reset_notebook() → ServiceResponse[源代码]

Reset the notebook

agentscope.service.dashscope_image_to_text(image_urls: str | Sequence[str], api_key: str, prompt: str = 'Describe the image', model: str = 'qwen-vl-plus') → ServiceResponse[源代码]

Generate text based on the given images.

参数:

  • image_urls (Union[str, Sequence[str]]) – The url of single or multiple images.

  • api_key (str) – The api key for the dashscope api.

  • prompt (str, defaults to ‘Describe the image’) – The text prompt.

  • model (str, defaults to ‘qwen-vl-plus’) – The model to use in DashScope MultiModal API.

返回:

A dictionary with two variables: status and`content`. If status is ServiceExecStatus.SUCCESS, the content is the generated text.

返回类型:

ServiceResponse

示例

image_url = "image.jpg"
prompt = "Describe the image"
print(image_to_text(image_url, prompt))

> {‘status’: ‘SUCCESS’, ‘content’: ‘A beautiful sunset in the mountains’}

agentscope.service.dashscope_text_to_image(prompt: str, api_key: str, n: int = 1, size: Literal['1024*1024', '720*1280', '1280*720'] = '1024*1024', model: str = 'wanx-v1', save_dir: str | None = None) → ServiceResponse[源代码]

Generate image(s) based on the given prompt, and return image url(s).

参数:

  • prompt (str) – The text prompt to generate image.

  • api_key (str) – The api key for the dashscope api.

  • n (int, defaults to 1) – The number of images to generate.

  • (`Literal["1024*1024" (size) –

  • "720*1280"

  • "1280*720"]`

  • to (defaults)

  • "1024*1024") – Size of the image.

  • model (str, defaults to ‘“wanx-v1”’) – The model to use.

  • save_dir (Optional[str], defaults to ‘None’) – The directory to save the generated images. If not specified, will return the web urls.

返回:

A dictionary with two variables: status and`content`. If status is ServiceExecStatus.SUCCESS, the content is a dict with key ‘fig_paths” and value is a list of the paths to the generated images.

返回类型:

ServiceResponse

示例

prompt = "A beautiful sunset in the mountains"
print(dashscope_text_to_image(prompt, "{api_key}"))

> { > ‘status’: ‘SUCCESS’, > ‘content’: {‘image_urls’: [‘IMAGE_URL1’, ‘IMAGE_URL2’]} > }

agentscope.service.dashscope_text_to_audio(text: str, api_key: str, save_dir: str, model: str = 'sambert-zhichu-v1', sample_rate: int = 48000) → ServiceResponse[源代码]

Convert the given text to audio.

参数:

  • text (str) – The text to be converted into audio.

  • api_key (str) – The api key for the dashscope API.

  • save_dir (str) – The directory to save the generated audio.

  • model (str, defaults to ‘sambert-zhichu-v1’) – The model to use. Full model list can be found in https://help.aliyun.com/zh/dashscope/model-list

  • sample_rate (int, defaults to 48000) – Samplerate of the audio.

返回:

A dictionary with two variables: status and`content`. If status is ServiceExecStatus.SUCCESS, the content contains a dictionary with key “audio_path” and value is the path to the generated audio.

返回类型:

ServiceResponse

示例

text = "How is the weather today?"
print(text_to_audio(text)) gives:

> {‘status’: ‘SUCCESS’, ‘content’: {“audio_path”: “AUDIO_PATH”}}

agentscope.service.openai_audio_to_text(audio_file_url: str, api_key: str, language: str = 'en', temperature: float = 0.2) → ServiceResponse[源代码]

Convert an audio file to text using OpenAI’s transcription service.

参数:

  • audio_file_url (str) – The file path or URL to the audio file that needs to be transcribed.

  • api_key (str) – The API key for the OpenAI API.

  • language (str, defaults to “en”) – The language of the input audio. Supplying the input language in [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format will improve accuracy and latency.

  • temperature (float, defaults to 0.2) – The temperature for the transcription, which affects the randomness of the output.

返回:

A dictionary with two variables: status and content. If status is ServiceExecStatus.SUCCESS, the content contains a dictionary with key ‘transcription’ and value as the transcribed text.

返回类型:

ServiceResponse

示例

audio_file_url = "/path/to/audio.mp3"
api_key = "YOUR_API_KEY"
print(openai_audio_to_text(audio_file_url, api_key))

> { > ‘status’: ‘SUCCESS’, > ‘content’: {‘transcription’: ‘This is the transcribed text from the audio file.’} > }

agentscope.service.openai_text_to_audio(text: str, api_key: str, save_dir: str = '', model: Literal['tts-1', 'tts-1-hd'] = 'tts-1', voice: Literal['alloy', 'echo', 'fable', 'onyx', 'nova', 'shimmer'] = 'alloy', speed: float = 1.0, res_format: Literal['mp3', 'wav', 'opus', 'aac', 'flac', 'pcm'] = 'mp3') → ServiceResponse[源代码]

Convert text to an audio file using a specified model and voice, and save the audio file locally.

参数:

  • text (str) – The text to convert to audio.

  • api_key (str) – The API key for the OpenAI API.

  • save_dir (str defaults to ‘’) – The directory where the generated audio file will be saved.

  • model (Literal[“tts-1”, “tts-1-hd”], defaults to “tts-1”) – The model to use for text-to-speech conversion.

  • (`Literal["alloy" (voice) –

  • "echo"

  • "fable"

  • "onyx"

  • "nova"

  • "shimmer"]`

:param : :param defaults to “alloy”): The voice to use for the audio output. :param speed: The speed of the audio playback. A value of 1.0 is normal speed. :type speed: float, defaults to 1.0 :param res_format (Literal[“mp3”: :param “wav”: :param “opus”: :param “aac”: :param “flac”: :param : :param “wav”: :param “pcm”]: :param : :param defaults to “mp3”): The format of the audio file.

返回:

A dictionary with two variables: status and content. If status is ServiceExecStatus.SUCCESS, the content is a dict with key ‘audio_path’ and value is the path to the generated audio file.

返回类型:

ServiceResponse

示例

text = "Hello, welcome to the text-to-speech service!"
api_key = "YOUR_API_KEY"
save_dir = "./audio_files"
print(openai_text_to_audio(text, api_key, save_dir))

> { > ‘status’: ‘SUCCESS’, > ‘content’: {‘audio_path’: ‘./audio_files/Hello,_welco.mp3’} > }

agentscope.service.openai_text_to_image(prompt: str, api_key: str, n: int = 1, model: Literal['dall-e-2', 'dall-e-3'] = 'dall-e-2', size: Literal['256x256', '512x512', '1024x1024', '1792x1024', '1024x1792'] = '256x256', quality: Literal['standard', 'hd'] = 'standard', style: Literal['vivid', 'natural'] = 'vivid', save_dir: str | None = None) → ServiceResponse[源代码]

Generate image(s) based on the given prompt, and return image URL(s) or save them locally.

参数:

  • prompt (str) – The text prompt to generate images.

  • api_key (str) – The API key for the OpenAI API.

  • n (int, defaults to 1) – The number of images to generate.

  • model (Literal[“dall-e-2”, “dall-e-3”], defaults to “dall-e-2”) – The model to use for image generation.

  • (`Literal["256x256" (size) –

  • "512x512"

  • "1024x1024"

  • "1792x1024"

:param : :param “1024x1792”]`: The size of the generated image(s). :param defaults to “256x256”): The size of the generated image(s). :param quality: The quality of the generated images. :type quality: Literal[“standard”, “hdr”], defaults to “standard :param style: The style of the generated images. :type style: Literal[“vivid”, “natural”]], defaults to “vivid :param save_dir: The directory to save the generated images. If not specified, will

return the web URLs.

返回:

A dictionary with two variables: status and content. If status is ServiceExecStatus.SUCCESS, the content is a dict with key ‘image_urls’ and value is a list of the paths to the generated images or URLs.

返回类型:

ServiceResponse

示例

prompt = "A futuristic city skyline at sunset"
print(openai_text_to_image(prompt, "{api_key}"))

> { > ‘status’: ‘SUCCESS’, > ‘content’: {‘image_urls’: [‘IMAGE_URL1’, ‘IMAGE_URL2’]} > }

agentscope.service.openai_image_to_text(image_urls: str | list[str], api_key: str, prompt: str = 'Describe the image', model: Literal['gpt-4o', 'gpt-4-turbo'] = 'gpt-4o') → ServiceResponse[源代码]

Generate descriptive text for given image(s) using a specified model, and return the generated text.

参数:

  • image_urls (Union[str, list[str]]) – The URL or list of URLs pointing to the images that need to be described.

  • api_key (str) – The API key for the OpenAI API.

  • prompt (str, defaults to “Describe the image”) – The prompt that instructs the model on how to describe the image(s).

  • model (Literal[“gpt-4o”, “gpt-4-turbo”], defaults to “gpt-4o”) – The model to use for generating the text descriptions.

返回:

A dictionary with two variables: status and content. If status is ServiceExecStatus.SUCCESS, the content contains the generated text description(s).

返回类型:

ServiceResponse

示例

image_url = "https://example.com/image.jpg"
api_key = "YOUR_API_KEY"
print(openai_image_to_text(image_url, api_key))

> { > ‘status’: ‘SUCCESS’, > ‘content’: “A detailed description of the image…” > }

agentscope.service.openai_edit_image(image_url: str, prompt: str, api_key: str, mask_url: str | None = None, n: int = 1, size: Literal['256x256', '512x512', '1024x1024'] = '256x256', save_dir: str | None = None) → ServiceResponse[源代码]

Edit an image based on the provided mask and prompt, and return the edited image URL(s) or save them locally.

参数:

  • image_url (str) – The file path or URL to the image that needs editing.

  • prompt (str) – The text prompt describing the edits to be made to the image.

  • api_key (str) – The API key for the OpenAI API.

  • mask_url (Optional[str], defaults to None) – The file path or URL to the mask image that specifies the regions to be edited.

  • n (int, defaults to 1) – The number of edited images to generate.

  • (`Literal["256x256" (size) –

  • "512x512"

  • "1024x1024"]`

  • to (defaults)

  • "256x256") – The size of the edited images.

  • save_dir (Optional[str], defaults to None) – The directory to save the edited images. If not specified, will return the web URLs.

返回:

A dictionary with two variables: status and content. If status is ServiceExecStatus.SUCCESS, the content is a dict with key ‘image_urls’ and value is a list of the paths to the edited images or URLs.

返回类型:

ServiceResponse

示例

image_url = "/path/to/original_image.png"
mask_url = "/path/to/mask_image.png"
prompt = "Add a sun to the sky"
api_key = "YOUR_API_KEY"
print(openai_edit_image(image_url, prompt, api_key, mask_url))

> { > ‘status’: ‘SUCCESS’, > ‘content’: {‘image_urls’: [‘EDITED_IMAGE_URL1’, ‘EDITED_IMAGE_URL2’]} > }

agentscope.service.openai_create_image_variation(image_url: str, api_key: str, n: int = 1, size: Literal['256x256', '512x512', '1024x1024'] = '256x256', save_dir: str | None = None) → ServiceResponse[源代码]

Create variations of an image and return the image URL(s) or save them locally.

参数:

  • image_url (str) – The file path or URL to the image from which variations will be generated.

  • api_key (str) – The API key for the OpenAI API.

  • n (int, defaults to 1) – The number of image variations to generate.

  • (`Literal["256x256" (size) –

  • "512x512"

  • "1024x1024"]`

  • ` (defaults to)

  • "256x256"`) –

    The size of the generated image variations.

  • save_dir (Optional[str], defaults to None) – The directory to save the generated image variations. If not specified, will return the web URLs.

返回:

A dictionary with two variables: status and content. If status is ServiceExecStatus.SUCCESS, the content is a dict with key ‘image_urls’ and value is a list of the paths to the generated images or URLs.

返回类型:

ServiceResponse

示例

image_url = "/path/to/image.png"
api_key = "YOUR_API_KEY"
print(openai_create_image_variation(image_url, api_key))

> { > ‘status’: ‘SUCCESS’, > ‘content’: {‘image_urls’: [‘VARIATION_URL1’, ‘VARIATION_URL2’]} > }

Search for locations using the TripAdvisor API.

参数:

  • api_key (str) – Your TripAdvisor API key.

  • query (str) – The search query.

  • language (str, optional) – The language for the response. Defaults to ‘en’.

返回:

A dictionary with two variables: status and content. The status variable is from the ServiceExecStatus enum, and content is the JSON response from TripAdvisor API or error information, which depends on the status variable.

If successful, the content will be a dictionary with the following structure: {

’data’: [
{

‘location_id’: str, ‘name’: str, ‘address_obj’: {

’street1’: str, ‘street2’: str, ‘city’: str, ‘state’: str, ‘country’: str, ‘postalcode’: str, ‘address_string’: str

}

]

} Each item in the ‘data’ list represents a location matching the search query.

返回类型:

ServiceResponse

示例

result = search_tripadvisor("your_api_key", "Socotra", "en")
if result.status == ServiceExecStatus.SUCCESS:
    print(result.content)
Example of successful content:
{
‘data’: [
{

‘location_id’: ‘574818’, ‘name’: ‘Socotra Island’, ‘address_obj’: {

‘street2’: ‘’, ‘city’: ‘Aden’, ‘country’: ‘Yemen’, ‘postalcode’: ‘’, ‘address_string’: ‘Aden Yemen’

}

}, {

‘location_id’: ‘25395815’, ‘name’: ‘Tour Socotra’, ‘address_obj’: {

‘street1’: ‘20th Street’, ‘city’: ‘Socotra Island’, ‘state’: ‘Socotra Island’, ‘country’: ‘Yemen’, ‘postalcode’: ‘111’, ‘address_string’: ‘20th Street, Socotra Island 111 Yemen’

}

}, # … more results …

]

}

agentscope.service.tripadvisor_search_location_photos(api_key: str, location_id: str | None = None, query: str | None = None, language: str = 'en') → ServiceResponse[源代码]

Retrieve photos for a specific location using the TripAdvisor API.

参数:

  • api_key (str) – Your TripAdvisor API key.

  • location_id (str, optional) – The unique identifier for a location on Tripadvisor. The location ID can be obtained using the tripadvisor_search function

  • query (str, optional) – The search query to find a location. Required if location_id is not provided.

  • language (str, optional) – The language for the response. Defaults to ‘en’.

返回:

A dictionary with two variables: status and content. The status variable is from the ServiceExecStatus enum, and content is the JSON response from TripAdvisor API or error information, which depends on the status variable.

If successful, the content will be a dictionary with the following structure:

{
    'photo_data': {
        'data': [
            {
                'id': int,
                'is_blessed': bool,
                'caption': str,
                'published_date': str,
                'images': {
                    'thumbnail': {
                        'height': int,
                        'width': int,
                        'url': str
                    },
                    'small': {
                        'height': int,
                        'width': int,
                        'url': str
                    },
                    'medium': {
                        'height': int,
                        'width': int,
                        'url': str
                    },
                    'large': {
                        'height': int,
                        'width': int,
                        'url': str
                    },
                    'original': {
                        'height': int,
                        'width': int,
                        'url': str
                    }
                },
                'album': str,
                'source': {'name': str, 'localized_name': str},
                'user': {'username': str}
            },
            ...
        ]
    }
}

Each item in the ‘data’ list represents a photo associated with the location.

返回类型:

ServiceResponse

备注

Either location_id or query must be provided. If both are provided, location_id takes precedence.

示例

# Using location_id
result = tripadvisor_search_location_photos(
    "your_api_key", location_id="123456", language="en"
)
if result.status == ServiceExecStatus.SUCCESS:
    print(result.content)

# Or using a query
result = tripadvisor_search_location_photos(
    "your_api_key", query="Eiffel Tower", language="en"
)
if result.status == ServiceExecStatus.SUCCESS:
    print(result.content)
Example of successful content:
{
‘photo_data’: {
‘data’: [
{

‘id’: 215321638, ‘is_blessed’: False, ‘caption’: ‘’, ‘published_date’: ‘2016-09-04T20:40:14.284Z’, ‘images’: {

‘thumbnail’: {‘height’: 50, ‘width’: 50, ‘url’: ‘https://media-cdn…/photo0.jpg’}, ‘small’: {‘height’: 150, ‘width’: 150, ‘url’: ‘https://media-cdn…/photo0.jpg’}, ‘medium’: {‘height’: 188, ‘width’: 250, ‘url’: ‘https://media-cdn…/photo0.jpg’}, ‘large’: {‘height’: 413, ‘width’: 550, ‘url’: ‘https://media-cdn…/photo0.jpg’}, ‘original’: {‘height’: 1920, ‘width’: 2560, ‘url’: ‘https://media-cdn…/photo0.jpg’}

}, ‘album’: ‘Other’, ‘source’: {

‘name’: ‘Traveler’, ‘localized_name’: ‘Traveler’

}, ‘user’: {‘username’: ‘EvaFalleth’}

}, # … more photo entries …

]

}

}

抛出:

ValueError – If neither location_id nor query is provided.

agentscope.service.tripadvisor_search_location_details(api_key: str, location_id: str | None = None, query: str | None = None, language: str = 'en', currency: str = 'USD') → ServiceResponse[源代码]

Get detailed information about a specific location using the TripAdvisor API.

参数:

  • api_key (str) – Your TripAdvisor API key.

  • location_id (str, optional) – The unique identifier for the location. Required if query is not provided.

  • query (str, optional) – The search query to find a location. Required if location_id is not provided.

  • language (str, optional) – The language for the response. Defaults to ‘en’, ‘zh’ for Chinese.

  • currency (str, optional) – The currency code to use for request and response (should follow ISO 4217). Defaults to ‘USD’.

返回:

A dictionary with two variables: status and content. The status variable is from the ServiceExecStatus enum, and content is the JSON response from TripAdvisor API or error information, which depends on the status variable.

If successful, the content will be a dictionary with detailed information about the location, including name, address, ratings, reviews, and more.

返回类型:

ServiceResponse

备注

Either location_id or query must be provided. If both are provided, location_id takes precedence.

示例

# Using location_id
result = get_tripadvisor_location_details(
    "your_api_key",
    location_id="574818",
    language="en",
    currency="USD"
)
if result.status == ServiceExecStatus.SUCCESS:
    print(result.content)

# Or using a query
result = get_tripadvisor_location_details(
    "your_api_key",
    query="Socotra Island",
    language="en",
    currency="USD"
)
if result.status == ServiceExecStatus.SUCCESS:
    print(result.content)
Example of successful content:
{

‘location_id’: ‘574818’, ‘name’: ‘Socotra Island’, ‘web_url’: ‘https://www.tripadvisor.com/Attraction_Review…’, ‘address_obj’: {

‘street2’: ‘’, ‘city’: ‘Aden’, ‘country’: ‘Yemen’, ‘postalcode’: ‘’, ‘address_string’: ‘Aden Yemen’

}, ‘ancestors’: [

{‘level’: ‘City’, ‘name’: ‘Aden’, ‘location_id’: ‘298087’}, {‘level’: ‘Country’, ‘name’: ‘Yemen’, ‘location_id’: ‘294014’}

], ‘latitude’: ‘12.46342’, ‘longitude’: ‘53.82374’, ‘timezone’: ‘Asia/Aden’, ‘write_review’: ‘https://www.tripadvisor.com/UserReview…’, ‘ranking_data’: {

‘geo_location_id’: ‘298087’, ‘ranking_string’: ‘#1 of 7 things to do in Aden’, ‘geo_location_name’: ‘Aden’, ‘ranking_out_of’: ‘7’, ‘ranking’: ‘1’

}, ‘rating’: ‘5.0’, ‘rating_image_url’: ‘https://www.tripadvisor.com/…/5.svg’, ‘num_reviews’: ‘62’, ‘review_rating_count’: {

‘1’: ‘1’, ‘2’: ‘0’, ‘3’: ‘1’, ‘4’: ‘1’, ‘5’: ‘59’,

}, ‘photo_count’: ‘342’, ‘see_all_photos’: ‘https://www.tripadvisor.com/Attraction…’, ‘category’: {‘name’: ‘attraction’, ‘localized_name’: ‘Attraction’}, ‘subcategory’: [

{‘name’: ‘nature_parks’, ‘localized_name’: ‘Nature & Parks’}, {‘name’: ‘attractions’, ‘localized_name’: ‘Attractions’}

], ‘groups’: [

{

‘name’: ‘Nature & Parks’, ‘localized_name’: ‘Nature & Parks’, ‘categories’: [{‘name’: ‘Islands’, ‘localized_name’: ‘Islands’}]

}

], ‘neighborhood_info’: [], ‘trip_types’: [

{‘name’: ‘business’, ‘localized_name’: ‘Business’, ‘value’: ‘2’}, {‘name’: ‘couples’, ‘localized_name’: ‘Couples’, ‘value’: ‘10’}, {‘name’: ‘solo’, ‘localized_name’: ‘Solo travel’, ‘value’: ‘11’}, {‘name’: ‘family’, ‘localized_name’: ‘Family’, ‘value’: ‘2’}, {‘name’: ‘friends’, ‘localized_name’: ‘Friends getaway’, ‘value’: ‘22’}

], ‘awards’: []

}

抛出:

ValueError – If neither location_id nor query is provided.

class agentscope.service.WebBrowser(timeout: int = 30, browser_visible: bool = True, browser_width: int = 1280, browser_height: int = 1080)[源代码]

基类：object

The web browser for agent, which is implemented with playwright. This module allows agent to interact with web pages, such as visiting a web page, clicking on elements, typing text, scrolling web page, etc.

备注

1. This module is still under development, and changes will be made in the future. 2. In Playwright, because of its asynchronous operations, it is essential to use if __name__ == “__main__”: to designate the main entry point of the program. This practice ensures that asynchronous functions are executed correctly within the appropriate context.

Install:

Execute the following code to install the required packages:

pip install playwright
playwright install
Details:

1. The actions that the agent can take in the web browser includes: “action_click”, “action_type”, “action_scroll_up”, “action_scroll_down”, “action_press_key”, and “action_visit_url”. 2. You can extract the html content, title, url, screenshot of the current web page by calling the corresponding properties, e.g. page_url, page_html, page_title, page_screenshot. 3. You can set or remove the interactive marks on the web page by calling the set_interactive_marks and remove_interactive_marks methods.

示例

from agentscope.service import WebBrowser
import time

if __name__ == "__main__":
    browser = WebBrowser()
    # Visit the specific web page
    browser.action_visit_url("https://www.bing.com")
    # Set the interactive marks on the web page
    browser.set_interactive_marks()

    time.sleep(5)

    browser.close()
__init__(timeout: int = 30, browser_visible: bool = True, browser_width: int = 1280, browser_height: int = 1080) → None[源代码]

Initialize the web browser module.

参数:

  • timeout (int, defaults to 30) – The timeout (in seconds) for the browser to wait for the page to load, defaults to 60s.

  • browser_visible (bool, defaults to True) – Whether the browser is visible.

  • browser_width (int, defaults to 1280) – The width of the browser. Defaults to 1280.

  • browser_height (int, defaults to 1080) – The height of the browser. Defaults to 1080.

property url: str

The url of current page.

property page_html: str

The html content of current page.

property page_title: str

The title of current page.

property page_markdown: str

The content of current page in Markdown format.

property page_screenshot: bytes

The screenshot of the current page.

action_click(element_id: int) → ServiceResponse[源代码]

Click on the element with the given id.

参数:

element_id (int) – The id of the element to click.

返回:

The response of the click action.

返回类型:

ServiceResponse

action_type(element_id: int, text: str, submit: bool) → ServiceResponse[源代码]

Type text into the element with the given id.

参数:

  • element_id (int) – The id of the element to type text into.

  • text (str) – The text to type into the element.

  • submit (bool) – If press the “Enter” after typing text.

返回:

The response of the type action.

返回类型:

ServiceResponse

action_scroll_up() → ServiceResponse[源代码]

Scroll up the current web page.

action_scroll_down() → ServiceResponse[源代码]

Scroll down the current web page.

action_press_key(key: str) → ServiceResponse[源代码]

Press down a key in the current web page.

参数:

key (str) – Chosen from F1 - F12, Digit0- Digit9, KeyA- KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp, etc.

action_visit_url(url: str) → ServiceResponse[源代码]

Visit the given url.

参数:

url (str) – The url to visit in browser.

get_action_functions() → dict[str, Callable][源代码]

Return a dictionary of the action functions, where the key is the action name and the value is the corresponding function.

set_interactive_marks() → list[WebElementInfo][源代码]

Mark the interactive elements on the current web page.

remove_interactive_marks() → None[源代码]

Remove the interactive elements on the current web page.

close() → None[源代码]

Close the browser

class agentscope.service.WebElementInfo(*, html: str, tag_name: str, node_name: str, node_value: None | str, type: None | str, aria_label: None | str, is_clickable: str | bool, meta_data: list[str], inner_text: str, origin_x: float, origin_y: float, width: float, height: float)[源代码]

基类：BaseModel

The information of a web interactive element.

html: str

The html content of the element.

tag_name: str

The tage name of the element.

node_name: str

The node name of the element.

node_value: None | str

The node value of the element.

type: None | str

The type of the element.

aria_label: None | str

The aria label of the element.

is_clickable: str | bool

Whether the element is clickable. If clickable, the value is the link of the element, otherwise, the value is False.

meta_data: list[str]

The meta data of the elements, e.g. attributes

inner_text: str

The text content of the element.

origin_x: float

The x coordinate of the origin of the element.

origin_y: float

The y coordinate of the origin of the element.

width: float

The width of the element.

height: float

The height of the element.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'aria_label': FieldInfo(annotation=Union[NoneType, str], required=True), 'height': FieldInfo(annotation=float, required=True), 'html': FieldInfo(annotation=str, required=True), 'inner_text': FieldInfo(annotation=str, required=True), 'is_clickable': FieldInfo(annotation=Union[str, bool], required=True), 'meta_data': FieldInfo(annotation=list[str], required=True), 'node_name': FieldInfo(annotation=str, required=True), 'node_value': FieldInfo(annotation=Union[NoneType, str], required=True), 'origin_x': FieldInfo(annotation=float, required=True), 'origin_y': FieldInfo(annotation=float, required=True), 'tag_name': FieldInfo(annotation=str, required=True), 'type': FieldInfo(annotation=Union[NoneType, str], required=True), 'width': FieldInfo(annotation=float, required=True)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

class agentscope.service.ServiceFactory[源代码]

基类：object

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

classmethod get(service_func: Callable[[...], Any], **kwargs: Any) → Tuple[Callable[[...], Any], dict][源代码]

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.

参数:

  • service_func (Callable[…, Any]) – The service function to be called.

  • kwargs (Any) – The arguments to be passed to the service function.

返回:

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

返回类型:

Tuple(Callable[…, Any], dict)

备注

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.

Suggestions:

1. The name of the service function should be self-explanatory, so that the agent can understand the function and use it properly. 2. 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.

示例

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