agentscope.agents package

Submodules

Module contents

Import all agent related modules in the package.

class agentscope.agents.AgentBase(*args: tuple, **kwargs: dict)[source]

Bases: Operator

Base class for all agents.

All agents should inherit from this class and implement the reply function.

__init__(name: str, sys_prompt: str | None = None, model_config_name: str | None = None, use_memory: bool = True, to_dist: DistConf | bool | None = False) → None[source]

Initialize an agent from the given arguments.

Parameters:

  • name (str) – The name of the agent.

  • sys_prompt (Optional[str]) – The system prompt of the agent, which can be passed by args or hard-coded in the agent.

  • model_config_name (str, defaults to None) – The name of the model config, which is used to load model from configuration.

  • use_memory (bool, defaults to True) – Whether the agent has memory.

  • to_dist (Optional[Union[DistConf, bool]], default to False) –

    The configurations passed to to_dist() method. Used in RpcMeta, when this parameter is provided, the agent will automatically be converted into its distributed version. Below are some examples:

    # run as a sub process
agent = XXXAgent(
    # ... other parameters
    to_dist=True,
)

# connect to an existing agent server
agent = XXXAgent(
    # ... other parameters
    to_dist=DistConf(
        host="<ip of your server>",
        port=<port of your server>,
        # other parameters
    ),
)

    See Tutorial for detail.

classmethod generate_agent_id() → str[source]

Generate the agent_id of this agent instance

reply(x: Sequence[Msg] | Msg | None = None) → Msg[source]

Define the actions taken by this agent.

Parameters:

x (Optional[Union[Msg, Sequence[Msg]]], defaults to None) – The input message(s) to the agent, which also can be omitted if the agent doesn’t need any input.

Returns:

The output message generated by the agent.

Return type:

Msg

Note

Given that some agents are in an adversarial environment, their input doesn’t include the thoughts of other agents.

speak(content: str | Msg | Generator[Tuple[bool, str], None, None]) → None[source]

Speak out the message generated by the agent. If a string is given, a Msg object will be created with the string as the content.

Parameters:

  • content

  • (`Union[str –

    The content of the message to be spoken out. If a string is given, a Msg object will be created with the agent’s name, role as “assistant”, and the given string as the content. If the content is a Generator, the agent will speak out the message chunk by chunk.

  • Msg – The content of the message to be spoken out. If a string is given, a Msg object will be created with the agent’s name, role as “assistant”, and the given string as the content. If the content is a Generator, the agent will speak out the message chunk by chunk.

  • Generator[Tuple[bool – The content of the message to be spoken out. If a string is given, a Msg object will be created with the agent’s name, role as “assistant”, and the given string as the content. If the content is a Generator, the agent will speak out the message chunk by chunk.

  • str] – The content of the message to be spoken out. If a string is given, a Msg object will be created with the agent’s name, role as “assistant”, and the given string as the content. If the content is a Generator, the agent will speak out the message chunk by chunk.

  • None – The content of the message to be spoken out. If a string is given, a Msg object will be created with the agent’s name, role as “assistant”, and the given string as the content. If the content is a Generator, the agent will speak out the message chunk by chunk.

  • None]]`) – The content of the message to be spoken out. If a string is given, a Msg object will be created with the agent’s name, role as “assistant”, and the given string as the content. If the content is a Generator, the agent will speak out the message chunk by chunk.

observe(x: Msg | Sequence[Msg]) → None[source]

Observe the input, store it in memory without response to it.

Parameters:

x (Union[Msg, Sequence[Msg]]) – The input message to be recorded in memory.

reset_audience(audience: Sequence[AgentBase]) → None[source]

Set the audience of this agent, which means if this agent generates a response, it will be passed to all audiences.

Parameters:

audience (Sequence[AgentBase]) – The audience of this agent, which will be notified when this agent generates a response message.

clear_audience() → None[source]

Remove the audience of this agent.

rm_audience(audience: Sequence[AgentBase] | AgentBase) → None[source]

Remove the given audience from the Sequence

to_dist(host: str = 'localhost', port: int | None = None, max_pool_size: int = 8192, max_expire_time: int = 7200, max_timeout_seconds: int = 5, local_mode: bool = True, retry_strategy: ~agentscope.rpc.retry_strategy.RetryBase = <agentscope.rpc.retry_strategy.RetryFixedTimes object>) → Any

Convert current object into its distributed version.

Parameters:

  • host (str, defaults to “localhost”) – Hostname of the rpc agent server.

  • port (int, defaults to None) – Port of the rpc agent server.

  • max_pool_size (int, defaults to 8192) – Only takes effect when host and port are not filled in. The max number of agent reply messages that the started agent server can accommodate. Note that the oldest message will be deleted after exceeding the pool size.

  • max_expire_time (int, defaults to 7200) – Only takes effect when host and port are not filled in. Maximum time for reply messages to be cached in the launched agent server. Note that expired messages will be deleted.

  • max_timeout_seconds (int, defaults to 5) – Max timeout seconds for the rpc call.

  • local_mode (bool, defaults to True) – Only takes effect when host and port are not filled in. Whether the started agent server only listens to local requests.

  • retry_strategy (RetryBase, defaults to _DEAFULT_RETRY_STRATEGY) – The retry strategy for the async rpc call.

Returns:

the wrapped agent instance with distributed functionality

Return type:

RpcObject

property agent_id: str

The unique id of this agent.

Returns:

agent_id

Return type:

str

class agentscope.agents.Operator[source]

Bases: ABC

Abstract base class Operator defines a protocol for classes that implement callable behavior. The class is designed to be subclassed with an overridden __call__ method that specifies the execution logic for the operator.

class agentscope.agents.DialogAgent(*args: tuple, **kwargs: dict)[source]

Bases: AgentBase

A simple agent used to perform a dialogue. Your can set its role by sys_prompt.

__init__(name: str, sys_prompt: str, model_config_name: str, use_memory: bool = True, **kwargs: Any) → None[source]

Initialize the dialog agent.

Parameters:

  • name (str) – The name of the agent.

  • sys_prompt (Optional[str]) – The system prompt of the agent, which can be passed by args or hard-coded in the agent.

  • model_config_name (str) – The name of the model config, which is used to load model from configuration.

  • use_memory (bool, defaults to True) – Whether the agent has memory.

reply(x: Sequence[Msg] | Msg | None = None) → Msg[source]

Reply function of the agent. Processes the input data, generates a prompt using the current dialogue memory and system prompt, and invokes the language model to produce a response. The response is then formatted and added to the dialogue memory.

Parameters:

x (Optional[Union[Msg, Sequence[Msg]]], defaults to None) – The input message(s) to the agent, which also can be omitted if the agent doesn’t need any input.

Returns:

The output message generated by the agent.

Return type:

Msg

to_dist(host: str = 'localhost', port: int | None = None, max_pool_size: int = 8192, max_expire_time: int = 7200, max_timeout_seconds: int = 5, local_mode: bool = True, retry_strategy: ~agentscope.rpc.retry_strategy.RetryBase = <agentscope.rpc.retry_strategy.RetryFixedTimes object>) → Any

Convert current object into its distributed version.

Parameters:

  • host (str, defaults to “localhost”) – Hostname of the rpc agent server.

  • port (int, defaults to None) – Port of the rpc agent server.

  • max_pool_size (int, defaults to 8192) – Only takes effect when host and port are not filled in. The max number of agent reply messages that the started agent server can accommodate. Note that the oldest message will be deleted after exceeding the pool size.

  • max_expire_time (int, defaults to 7200) – Only takes effect when host and port are not filled in. Maximum time for reply messages to be cached in the launched agent server. Note that expired messages will be deleted.

  • max_timeout_seconds (int, defaults to 5) – Max timeout seconds for the rpc call.

  • local_mode (bool, defaults to True) – Only takes effect when host and port are not filled in. Whether the started agent server only listens to local requests.

  • retry_strategy (RetryBase, defaults to _DEAFULT_RETRY_STRATEGY) – The retry strategy for the async rpc call.

Returns:

the wrapped agent instance with distributed functionality

Return type:

RpcObject

class agentscope.agents.DictDialogAgent(*args: tuple, **kwargs: dict)[source]

Bases: AgentBase

An agent that generates response in a dict format, where user can specify the required fields in the response via specifying the parser

About parser, please refer to our [tutorial](https://modelscope.github.io/agentscope/en/tutorial/203-parser.html)

For usage example, please refer to the example of werewolf in examples/game_werewolf

__init__(name: str, sys_prompt: str, model_config_name: str, use_memory: bool = True, max_retries: int | None = 3) → None[source]

Initialize the dict dialog agent.

Parameters:

  • name (str) – The name of the agent.

  • sys_prompt (Optional[str], defaults to None) – The system prompt of the agent, which can be passed by args or hard-coded in the agent.

  • model_config_name (str, defaults to None) – The name of the model config, which is used to load model from configuration.

  • use_memory (bool, defaults to True) – Whether the agent has memory.

  • max_retries (Optional[int], defaults to None) – The maximum number of retries when failed to parse the model output.

set_parser(parser: ParserBase) → None[source]

Set response parser, which will provide 1) format instruction; 2) response parsing; 3) filtering fields when returning message, storing message in memory. So developers only need to change the parser, and the agent will work as expected.

reply(x: Sequence[Msg] | Msg | None = None) → Msg[source]

Reply function of the agent. Processes the input data, generates a prompt using the current dialogue memory and system prompt, and invokes the language model to produce a response. The response is then formatted and added to the dialogue memory.

Parameters:

x (Optional[Union[Msg, Sequence[Msg]]], defaults to None) – The input message(s) to the agent, which also can be omitted if the agent doesn’t need any input.

Returns:

The output message generated by the agent.

Return type:

Msg

Raises:

json.decoder.JSONDecodeError – If the response from the language model is not valid JSON, it defaults to treating the response as plain text.

to_dist(host: str = 'localhost', port: int | None = None, max_pool_size: int = 8192, max_expire_time: int = 7200, max_timeout_seconds: int = 5, local_mode: bool = True, retry_strategy: ~agentscope.rpc.retry_strategy.RetryBase = <agentscope.rpc.retry_strategy.RetryFixedTimes object>) → Any

Convert current object into its distributed version.

Parameters:

  • host (str, defaults to “localhost”) – Hostname of the rpc agent server.

  • port (int, defaults to None) – Port of the rpc agent server.

  • max_pool_size (int, defaults to 8192) – Only takes effect when host and port are not filled in. The max number of agent reply messages that the started agent server can accommodate. Note that the oldest message will be deleted after exceeding the pool size.

  • max_expire_time (int, defaults to 7200) – Only takes effect when host and port are not filled in. Maximum time for reply messages to be cached in the launched agent server. Note that expired messages will be deleted.

  • max_timeout_seconds (int, defaults to 5) – Max timeout seconds for the rpc call.

  • local_mode (bool, defaults to True) – Only takes effect when host and port are not filled in. Whether the started agent server only listens to local requests.

  • retry_strategy (RetryBase, defaults to _DEAFULT_RETRY_STRATEGY) – The retry strategy for the async rpc call.

Returns:

the wrapped agent instance with distributed functionality

Return type:

RpcObject

class agentscope.agents.UserAgent(*args: tuple, **kwargs: dict)[source]

Bases: AgentBase

User agent class

__init__(name: str = 'User', input_hint: str = 'User Input: ', require_url: bool = False) → None[source]

Initialize a UserAgent object.

Parameters:

  • name (str, defaults to “User”) – The name of the agent. Defaults to “User”.

  • (str (input_hint) – “`): The hint of the input. Defaults to “User Input: “.

  • Input (defaults to `"User) –

    ”`): The hint of the input. Defaults to “User Input: “.

  • require_url (bool, defaults to False) – Whether the agent requires user to input a URL. Defaults to False. The URL can lead to a website, a file, or a directory. It will be added into the generated message in field url.

reply(x: Sequence[Msg] | Msg | None = None, required_keys: list[str] | str | None = None, timeout: int | None = None) → Msg[source]

Processes the input provided by the user and stores it in memory, potentially formatting it with additional provided details.

The method prompts the user for input, then optionally prompts for additional specifics based on the provided format keys. All information is encapsulated in a message object, which is then added to the object’s memory.

Parameters:

  • x (Optional[Union[Msg, Sequence[Msg]]], defaults to None) – The input message(s) to the agent, which also can be omitted if the agent doesn’t need any input.

  • required_keys (Optional[Union[list[str], str]], defaults to None) – Strings that requires user to input, which will be used as the key of the returned dict. Defaults to None.

  • timeout (Optional[int], defaults to None) – Raise TimeoutError if user exceed input time, set to None for no limit.

Returns:

The output message generated by the agent.

Return type:

Msg

speak(content: str | Msg) → None[source]

Speak out the message generated by the agent. If a string is given, a Msg object will be created with the string as the content.

Parameters:

content (Union[str, Msg]) – The content of the message to be spoken out. If a string is given, a Msg object will be created with the agent’s name, role as “user”, and the given string as the content.

to_dist(host: str = 'localhost', port: int | None = None, max_pool_size: int = 8192, max_expire_time: int = 7200, max_timeout_seconds: int = 5, local_mode: bool = True, retry_strategy: ~agentscope.rpc.retry_strategy.RetryBase = <agentscope.rpc.retry_strategy.RetryFixedTimes object>) → Any

Convert current object into its distributed version.

Parameters:

  • host (str, defaults to “localhost”) – Hostname of the rpc agent server.

  • port (int, defaults to None) – Port of the rpc agent server.

  • max_pool_size (int, defaults to 8192) – Only takes effect when host and port are not filled in. The max number of agent reply messages that the started agent server can accommodate. Note that the oldest message will be deleted after exceeding the pool size.

  • max_expire_time (int, defaults to 7200) – Only takes effect when host and port are not filled in. Maximum time for reply messages to be cached in the launched agent server. Note that expired messages will be deleted.

  • max_timeout_seconds (int, defaults to 5) – Max timeout seconds for the rpc call.

  • local_mode (bool, defaults to True) – Only takes effect when host and port are not filled in. Whether the started agent server only listens to local requests.

  • retry_strategy (RetryBase, defaults to _DEAFULT_RETRY_STRATEGY) – The retry strategy for the async rpc call.

Returns:

the wrapped agent instance with distributed functionality

Return type:

RpcObject

class agentscope.agents.ReActAgent(*args: tuple, **kwargs: dict)[source]

Bases: AgentBase

An agent class that implements the ReAct algorithm. More details refer to https://arxiv.org/abs/2210.03629.

This is an example implementation of ReAct algorithm in AgentScope. We follow the idea within the paper, but the detailed prompt engineering maybe different. Developers are encouraged to modify the prompt to fit their own needs.

Note

1. We use the “thought” field in the response to support Chain-of-Thought, which means the tool functions cannot use “thought” as their argument name. 2. The function name “finish” is also a reserved name when using this agent, which will be used to end the reasoning-acting loop.

__init__(name: str, model_config_name: str, service_toolkit: ServiceToolkit, sys_prompt: str = "You're a helpful assistant named {name}.", max_iters: int = 10, verbose: bool = True) → None[source]

Initialize the ReAct agent with the given name, model config name and tools.

Parameters:

  • name (str) – The name of the agent.

  • sys_prompt (str) – The system prompt of the agent.

  • model_config_name (str) – The name of the model config, which is used to load model from configuration.

  • service_toolkit (ServiceToolkit) – A ServiceToolkit object that contains the tool functions.

  • max_iters (int, defaults to 10) – The maximum number of iterations of the reasoning-acting loops.

  • verbose (bool, defaults to True) – Whether to print the detailed information during reasoning and acting steps. If False, only the content in speak field will be print out.

reply(x: Sequence[Msg] | Msg | None = None) → Msg[source]

The reply method of the agent.

static finish(response: str) → ServiceResponse[source]

Finish reasoning and generate a response to the user.

Note

The function won’t be executed, actually.

Parameters:

response (str) – The response to the user.

to_dist(host: str = 'localhost', port: int | None = None, max_pool_size: int = 8192, max_expire_time: int = 7200, max_timeout_seconds: int = 5, local_mode: bool = True, retry_strategy: ~agentscope.rpc.retry_strategy.RetryBase = <agentscope.rpc.retry_strategy.RetryFixedTimes object>) → Any

Convert current object into its distributed version.

Parameters:

  • host (str, defaults to “localhost”) – Hostname of the rpc agent server.

  • port (int, defaults to None) – Port of the rpc agent server.

  • max_pool_size (int, defaults to 8192) – Only takes effect when host and port are not filled in. The max number of agent reply messages that the started agent server can accommodate. Note that the oldest message will be deleted after exceeding the pool size.

  • max_expire_time (int, defaults to 7200) – Only takes effect when host and port are not filled in. Maximum time for reply messages to be cached in the launched agent server. Note that expired messages will be deleted.

  • max_timeout_seconds (int, defaults to 5) – Max timeout seconds for the rpc call.

  • local_mode (bool, defaults to True) – Only takes effect when host and port are not filled in. Whether the started agent server only listens to local requests.

  • retry_strategy (RetryBase, defaults to _DEAFULT_RETRY_STRATEGY) – The retry strategy for the async rpc call.

Returns:

the wrapped agent instance with distributed functionality

Return type:

RpcObject

class agentscope.agents.LlamaIndexAgent(*args: tuple, **kwargs: dict)[source]

Bases: AgentBase

A LlamaIndex agent build on LlamaIndex.

__init__(name: str, sys_prompt: str, model_config_name: str, knowledge_list: list[Knowledge] | None = None, knowledge_id_list: list[str] | None = None, similarity_top_k: int | None = None, log_retrieval: bool = True, recent_n_mem_for_retrieve: int = 1, **kwargs: Any) → None[source]

Initialize the RAG LlamaIndexAgent :param name: the name for the agent :type name: str :param sys_prompt: system prompt for the RAG agent :type sys_prompt: str :param model_config_name: language model for the agent :type model_config_name: str :param knowledge_list: a list of knowledge.

User can choose to pass a list knowledge object directly when initializing the RAG agent. Another choice can be passing a list of knowledge ids and obtain the knowledge with the equip function of a knowledge bank.

Parameters:

  • knowledge_id_list (list[Knowledge]) – a list of id of the knowledge. This is designed for easy setting up multiple RAG agents with a config file. To obtain the knowledge objects, users can pass this agent to the equip function in a knowledge bank to add corresponding knowledge to agent’s self.knowledge_list.

  • similarity_top_k (int) – the number of most similar data blocks retrieved from each of the knowledge

  • log_retrieval (bool) – whether to print the retrieved content

  • recent_n_mem_for_retrieve (int) – the number of pieces of memory used as part of retrival query

reply(x: Sequence[Msg] | Msg | None = None) → Msg[source]

Reply function of the RAG agent. Processes the input data, 1) use the input data to retrieve with RAG function; 2) generates a prompt using the current memory and system prompt; 3) invokes the language model to produce a response. The response is then formatted and added to the dialogue memory.

Parameters:

x (Optional[Union[Msg, Sequence[Msg]]], defaults to None) – The input message(s) to the agent, which also can be omitted if the agent doesn’t need any input.

Returns:

The output message generated by the agent.

Return type:

Msg

to_dist(host: str = 'localhost', port: int | None = None, max_pool_size: int = 8192, max_expire_time: int = 7200, max_timeout_seconds: int = 5, local_mode: bool = True, retry_strategy: ~agentscope.rpc.retry_strategy.RetryBase = <agentscope.rpc.retry_strategy.RetryFixedTimes object>) → Any

Convert current object into its distributed version.

Parameters:

  • host (str, defaults to “localhost”) – Hostname of the rpc agent server.

  • port (int, defaults to None) – Port of the rpc agent server.

  • max_pool_size (int, defaults to 8192) – Only takes effect when host and port are not filled in. The max number of agent reply messages that the started agent server can accommodate. Note that the oldest message will be deleted after exceeding the pool size.

  • max_expire_time (int, defaults to 7200) – Only takes effect when host and port are not filled in. Maximum time for reply messages to be cached in the launched agent server. Note that expired messages will be deleted.

  • max_timeout_seconds (int, defaults to 5) – Max timeout seconds for the rpc call.

  • local_mode (bool, defaults to True) – Only takes effect when host and port are not filled in. Whether the started agent server only listens to local requests.

  • retry_strategy (RetryBase, defaults to _DEAFULT_RETRY_STRATEGY) – The retry strategy for the async rpc call.

Returns:

the wrapped agent instance with distributed functionality

Return type:

RpcObject