agentscope.agents package

Submodules

Module contents

Import all agent related modules in the package.

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

clear_audience() → None[source]: Remove the audience of this agent.

classmethod generate_agent_id() → str[source]: Generate the agent_id of this agent instance

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.

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.

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

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, Msg, Generator[Tuple[bool, str], None, 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.

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 DialogAgent(*args: tuple, **kwargs: dict)[source]

Bases: AgentBase

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

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 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://doc.agentscope.io/build_tutorial/structured_output.html)

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

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.

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.

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 LlamaIndexAgent(*args: tuple, **kwargs: dict)[source]

Bases: AgentBase

A LlamaIndex agent build on LlamaIndex.

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

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

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.

reply(x: Sequence[Msg] | Msg | None = None) → Msg[source]: The reply method of the agent.

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 UserAgent(*args: tuple, **kwargs: dict)[source]

Bases: AgentBase

User agent class

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