agentscope.rpc package

Submodules

• agentscope.rpc.retry_strategy module
  • RetryBase
    • RetryBase.retry()
    • RetryBase.load_dict()
  • RetryFixedTimes
    • RetryFixedTimes.__init__()
    • RetryFixedTimes.retry()
  • RetryExpential
    • RetryExpential.__init__()
    • RetryExpential.retry()
• agentscope.rpc.rpc_agent_pb2 module
• agentscope.rpc.rpc_agent_pb2_grpc module
  • RpcAgentStub
    • RpcAgentStub.__init__()
  • RpcAgentServicer
    • RpcAgentServicer.is_alive()
    • RpcAgentServicer.stop()
    • RpcAgentServicer.create_agent()
    • RpcAgentServicer.delete_agent()
    • RpcAgentServicer.delete_all_agents()
    • RpcAgentServicer.clone_agent()
    • RpcAgentServicer.get_agent_list()
    • RpcAgentServicer.get_server_info()
    • RpcAgentServicer.set_model_configs()
    • RpcAgentServicer.get_agent_memory()
    • RpcAgentServicer.call_agent_func()
    • RpcAgentServicer.update_placeholder()
    • RpcAgentServicer.download_file()
  • add_RpcAgentServicer_to_server()
  • RpcAgent
    • RpcAgent.is_alive()
    • RpcAgent.stop()
    • RpcAgent.create_agent()
    • RpcAgent.delete_agent()
    • RpcAgent.delete_all_agents()
    • RpcAgent.clone_agent()
    • RpcAgent.get_agent_list()
    • RpcAgent.get_server_info()
    • RpcAgent.set_model_configs()
    • RpcAgent.get_agent_memory()
    • RpcAgent.call_agent_func()
    • RpcAgent.update_placeholder()
    • RpcAgent.download_file()
• agentscope.rpc.rpc_async module
  • AsyncResult
    • AsyncResult.__init__()
    • AsyncResult.update_value()
    • AsyncResult.result()
• agentscope.rpc.rpc_client module
  • RpcClient
    • RpcClient.__init__()
    • RpcClient.call_agent_func()
    • RpcClient.is_alive()
    • RpcClient.stop()
    • RpcClient.create_agent()
    • RpcClient.delete_agent()
    • RpcClient.delete_all_agent()
    • RpcClient.update_result()
    • RpcClient.get_agent_list()
    • RpcClient.get_server_info()
    • RpcClient.set_model_configs()
    • RpcClient.get_agent_memory()
    • RpcClient.download_file()
  • RpcAgentClient
    • RpcAgentClient.__init__()
• agentscope.rpc.rpc_config module
  • DistConf
    • DistConf.__init__()
• agentscope.rpc.rpc_meta module
  • async_func()
  • sync_func()
  • generate_oid()
  • RpcMeta
    • RpcMeta.__init__()
    • RpcMeta.get_class()
    • RpcMeta.register_class()
    • RpcMeta.to_dist()
• agentscope.rpc.rpc_object module
  • get_public_methods()
  • RpcObject
    • RpcObject.__init__()
    • RpcObject.create()
    • RpcObject.stop()

Module contents

Import all rpc related modules in the package.

class agentscope.rpc.RpcMeta(name: Any, bases: Any, attrs: Any)

Bases: ABCMeta

The metaclass for all classes that can use to_dist and other distributed related functionality.

Note

The RpcMeta will automatically add the to_dist method and initialization parameter to its subclasses. And it will also detect all public functions and register them into the _info attribute of the class.

__init__(name: Any, bases: Any, attrs: Any) → None

static get_class(cls_name: str) → Any

Get the class based on the specific class name.

Parameters:

cls_name (str) – the name of the class.

Raises:

ValueError – class name not exits.

Returns:

the class

Return type:

Any

static register_class(cls: type) → bool

Register the class into the registry.

Parameters:

cls (Type) – the class to be registered.

Returns:

whether the registration is successful.

Return type:

bool

static to_dist(self: ~typing.Any, 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.rpc.RpcClient(host: str, port: int)

Bases: object

A client of Rpc agent server

__init__(host: str, port: int) → None

Init a rpc agent client

Parameters:

• host (str) – The hostname of the rpc agent server which the

• connected. (is)

• port (int) – The port of the rpc agent server which the client

• connected.

call_agent_func(func_name: str, agent_id: str, value: bytes | None = None, timeout: int = 300) → bytes

Call the specific function of an agent running on the server.

Parameters:

• func_name (str) – The name of the function being called.

• value (bytes, optional) – The serialized function input value.

• None. (Defaults to)

• timeout (int, optional) – The timeout for the RPC call in seconds.

• 300. (Defaults to)

Returns:

serialized return data.

Return type:

bytes

is_alive() → bool

Check if the agent server is alive.

Returns:

Indicate whether the server is alive.

Return type:

bool

stop() → bool

Stop the agent server.

create_agent(agent_configs: dict, agent_id: str | None = None) → bool

Create a new agent for this client.

Parameters:

• agent_configs (dict) – Init configs of the agent, generated by RpcMeta.

• agent_id (str) – agent_id of the created agent.

Returns:

Indicate whether the creation is successful

Return type:

bool

delete_agent(agent_id: str | None = None) → bool

Delete agents with the specific agent_id.

Parameters:

agent_id (str) – id of the agent to be deleted.

Returns:

Indicate whether the deletion is successful

Return type:

bool

delete_all_agent() → bool

Delete all agents on the server.

update_result(task_id: int, retry: ~agentscope.rpc.retry_strategy.RetryBase = <agentscope.rpc.retry_strategy.RetryFixedTimes object>) → str

Update the value of the async result.

Note

DON’T USE THIS FUNCTION IN ThreadPoolExecutor.

Parameters:

• task_id (int) – task_id of the PlaceholderMessage.

• retry (RetryBase) – Retry strategy. Defaults to RetryFixedTimes(10, 5).

Returns:

Serialized value.

Return type:

bytes

get_agent_list() → Sequence[dict]

Get the summary of all agents on the server as a list.

Returns:

list of agent summary information.

Return type:

Sequence[str]

get_server_info() → dict

Get the agent server resource usage information.

set_model_configs(model_configs: dict | list[dict]) → bool

Set the model configs of the server.

get_agent_memory(agent_id: str) → list[Msg] | Msg

Get the memory usage of the specific agent.

download_file(path: str) → str

Download a file from a remote server to the local machine.

Parameters:

path (str) – The path of the file to be downloaded. Note that it is the path on the remote server.

Returns:

The path of the downloaded file. Note that it is the path on the local machine.

Return type:

str

class agentscope.rpc.RpcObject(cls: type, oid: str, host: str, port: int, connect_existing: bool = False, 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 | dict = <agentscope.rpc.retry_strategy.RetryFixedTimes object>, configs: dict | None = None)

Bases: ABC

A proxy object which represent an object located in an Rpc server.

Note

When to_dist is called on an object or when using the to_dist parameter to create an object, the object is moved to an Rpc server, and an RpcObject instance is left behind in the local process. The RpcObject will automatically forward all public method invocations to the original object in the rpc server.

__init__(cls: type, oid: str, host: str, port: int, connect_existing: bool = False, 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 | dict = <agentscope.rpc.retry_strategy.RetryFixedTimes object>, configs: dict | None = None) → None

Initialize the rpc object.

Parameters:

• cls (type) – The class of the object in the rpc server.

• oid (str) – The id of the object in the rpc server.

• host (str) – The host of the rpc server.

• port (int) – The port of the rpc server.

• connect_existing (bool, defaults to False) – Set to True, if the object is already running on the server.

• max_pool_size (int, defaults to 8192) – Max number of task results that the server can accommodate.

• max_expire_time (int, defaults to 7200) – Max expire time for task results.

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

• local_mode (bool, defaults to True) – Whether the started gRPC server only listens to local requests.

• retry_strategy (Union[RetryBase, dict], defaults to _DEAFULT_RETRY_STRATEGY) – The retry strategy for async rpc call.

• configs (dict, defaults to None) – The configs for the agent. Generated by RpcMeta. Don’t use this arg manually.

create(configs: dict) → None

create the object on the rpc server.

stop() → None

Stop the RpcAgent and the rpc server.

agentscope.rpc.async_func(func: Callable) → Callable

A decorator for async function.

In distributed mode, async functions will return a AsyncResult immediately.

Parameters:

func (Callable) – The function to decorate.

agentscope.rpc.sync_func(func: Callable) → Callable

A decorator for sync function.

In distributed mode, sync functions will block the current thread until the result is ready.

In most cases, you don’t need to use this decorator. RpcMeta will treat all public functions without async_func as sync_func. However, for magic methods (e.g. __str__ and __getitem__, which are started with __), you can use sync_func to mark them as sync.

Parameters:

func (Callable) – The function to decorate.

class agentscope.rpc.AsyncResult(host: str, port: int, task_id: int | None = None, stub: ~concurrent.futures._base.Future | None = None, retry: ~agentscope.rpc.retry_strategy.RetryBase = <agentscope.rpc.retry_strategy.RetryFixedTimes object>)

Bases: object

Use this class to get the the async result from rpc server.

__init__(host: str, port: int, task_id: int | None = None, stub: ~concurrent.futures._base.Future | None = None, retry: ~agentscope.rpc.retry_strategy.RetryBase = <agentscope.rpc.retry_strategy.RetryFixedTimes object>) → None

update_value() → None

Update the value. For compatibility with old version.

result() → Any

Get the result.

class agentscope.rpc.DistConf(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, lazy_launch: bool = False)

Bases: dict

Distribution configuration for agents.

__init__(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, lazy_launch: bool = False)

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_expire_time (int, defaults to 7200) – Max expire time of task results in seconds.

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

• local_mode (bool, defaults to True) – Whether the started rpc server only listens to local requests.

• lazy_launch (bool, defaults to False) – Deprecated.