agentscope.agents package
Submodules
- agentscope.agents.agent module
- agentscope.agents.dialog_agent module
- agentscope.agents.dict_dialog_agent module
- agentscope.agents.operator module
- agentscope.agents.rag_agent module
- agentscope.agents.react_agent module
- agentscope.agents.rpc_agent module
- agentscope.agents.user_agent module
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_AgentMeta
, 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 get_agent_class(agent_class_name: str) Type[AgentBase] [source]
Get the agent class based on the specific agent class name.
- Parameters:
agent_class_name (str) – the name of the agent class.
- Raises:
ValueError – Agent class name not exits.
- Returns:
the AgentBase subclass.
- Return type:
Type[AgentBase]
- classmethod register_agent_class(agent_class: Type[AgentBase]) None [source]
Register the agent class into the registry.
- Parameters:
agent_class (Type[AgentBase]) – the agent class to be registered.
- 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.
- rm_audience(audience: Sequence[AgentBase] | AgentBase) None [source]
Remove the given audience from the Sequence
- property agent_id: str
The unique id of this agent.
- Returns:
agent_id
- Return type:
str
- to_dist(host: str = 'localhost', port: int | None = None, max_pool_size: int = 8192, max_timeout_seconds: int = 7200, local_mode: bool = True, lazy_launch: bool = False, launch_server: bool | None = None) AgentBase [source]
Convert current agent instance into a 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_timeout_seconds (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.
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.
lazy_launch (bool, defaults to False) – Only takes effect when host and port are not filled in. If True, launch the agent server when the agent is called, otherwise, launch the agent server immediately.
launch_server (bool, defaults to None) – This field has been deprecated and will be removed in future releases.
- Returns:
the wrapped agent instance with distributed functionality
- Return type:
AgentBase
- 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
- 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.
- 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.
- 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.
- 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.
- class agentscope.agents.DistConf(host: str = 'localhost', port: int | None = None, max_pool_size: int = 8192, max_timeout_seconds: int = 7200, local_mode: bool = True, lazy_launch: bool = False)[source]
Bases:
dict
Distribution configuration for agents.
- __init__(host: str = 'localhost', port: int | None = None, max_pool_size: int = 8192, max_timeout_seconds: int = 7200, local_mode: bool = True, lazy_launch: bool = False)[source]
Init the distributed configuration.
- 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) – Max number of task results that the server can accommodate.
max_timeout_seconds (int, defaults to 7200) – Timeout for task results.
local_mode (bool, defaults to True) – Whether the started rpc server only listens to local requests.
lazy_launch (bool, defaults to False) – Only launch the server when the agent is called.
- 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