From fd21daa3d6f808f53c68bf5a7c0c1abf5ec1ede4 Mon Sep 17 00:00:00 2001 From: "panxuchen.pxc" Date: Fri, 26 Apr 2024 15:27:10 +0800 Subject: [PATCH] update dist doc --- .../en/source/tutorial/208-distribute.md | 8 ++--- .../zh_CN/source/tutorial/208-distribute.md | 8 ++--- examples/distributed_simulation/main.py | 2 +- src/agentscope/agents/agent.py | 29 ++++++++++++++++--- 4 files changed, 34 insertions(+), 13 deletions(-) diff --git a/docs/sphinx_doc/en/source/tutorial/208-distribute.md b/docs/sphinx_doc/en/source/tutorial/208-distribute.md index 23e7956a5..126f21a45 100644 --- a/docs/sphinx_doc/en/source/tutorial/208-distribute.md +++ b/docs/sphinx_doc/en/source/tutorial/208-distribute.md @@ -22,8 +22,8 @@ The above concepts may seem complex, but don't worry, for application developers ### Step 1: Convert your agent to its distributed version -All agents in AgentScope can automatically convert to its distributed version by calling its `to_dist` method. -But note that your agent must inherit from the `agentscope.agents.AgentBase` class, because the `to_dist` method is provided by the `AgentBase` class. +All agents in AgentScope can automatically convert to its distributed version by calling its {func}`to_dist` method. +But note that your agent must inherit from the {class}`agentscope.agents.AgentBase` class, because the `to_dist` method is provided by the `AgentBase` class. Suppose there are two agent classes `AgentA` and `AgentB`, both of which inherit from `AgentBase`. @@ -122,7 +122,7 @@ And developers just need to write the application flow in a centralized way in t #### Advanced Usage of `to_dist` -All examples described above convert initialized agents into their distributed version through the `to_dist()` method, which is equivalent to initialize the agent twice, once in the main process and once in the agent server process. +All examples described above convert initialized agents into their distributed version through the {func}`to_dist` method, which is equivalent to initialize the agent twice, once in the main process and once in the agent server process. For agents whose initialization process is time-consuming, the `to_dist` method is inefficient. Therefore, AgentScope also provides a method to convert the Agent instance into its distributed version while initializing it, that is, passing in `to_dist` parameter to the Agent's initialization function. In Child Process Mode, just pass `to_dist=True` to the Agent's initialization function. @@ -241,7 +241,7 @@ By implementing each Agent as an Actor, an Agent will automatically wait for its #### PlaceHolder -Meanwhile, to support centralized application orchestration, AgentScope introduces the concept of Placeholder. +Meanwhile, to support centralized application orchestration, AgentScope introduces the concept of {class}`Placeholder`. A Placeholder is a special message that contains the address and port number of the agent that generated the placeholder, which is used to indicate that the output message of the Agent is not ready yet. When calling the `reply` method of a distributed agent, a placeholder is returned immediately without blocking the main process. The interface of placeholder is exactly the same as the message, so that the orchestration flow can be written in a centralized way. diff --git a/docs/sphinx_doc/zh_CN/source/tutorial/208-distribute.md b/docs/sphinx_doc/zh_CN/source/tutorial/208-distribute.md index dc4784ee2..94b193d33 100644 --- a/docs/sphinx_doc/zh_CN/source/tutorial/208-distribute.md +++ b/docs/sphinx_doc/zh_CN/source/tutorial/208-distribute.md @@ -20,8 +20,8 @@ AgentScope中，我们将运行应用流程的进程称为**主进程 (Main Proc ### 步骤1: 转化为分布式版本 -AgentScope 中所有智能体都可以通过 `to_dist` 方法转化为对应的分布式版本。 -但需要注意，你的智能体必须继承自 `agentscope.agents.AgentBase` 类，因为是 `AgentBase` 提供了 `to_dist` 方法。 +AgentScope 中所有智能体都可以通过 {func}`to_dist` 方法转化为对应的分布式版本。 +但需要注意，你的智能体必须继承自 {class}`agentscope.agents.AgentBase` 类，因为是 `AgentBase` 提供了 `to_dist` 方法。 假设有两个智能体类`AgentA`和`AgentB`，它们都继承自 `AgentBase`。 @@ -121,7 +121,7 @@ b = AgentB( #### `to_dist` 进阶用法 -上面介绍的案例都是将一个已经初始化的 Agent 通过 `to_dist()` 方法转化为其分布式版本，相当于要执行两次初始化操作，一次在主进程中，一次在智能体进程中。如果 Agent 的初始化过程耗时较长，直接使用 `to_dist` 方法会严重影响运行效率。为此 AgentScope 也提供了在初始化 Agent 实例的同时将其转化为其分布式版本的方法，即在原 Agent 实例初始化时传入 `to_dist` 参数。 +上面介绍的案例都是将一个已经初始化的 Agent 通过 {func}`to_dist` 方法转化为其分布式版本，相当于要执行两次初始化操作，一次在主进程中，一次在智能体进程中。如果 Agent 的初始化过程耗时较长，直接使用 `to_dist` 方法会严重影响运行效率。为此 AgentScope 也提供了在初始化 Agent 实例的同时将其转化为其分布式版本的方法，即在原 Agent 实例初始化时传入 `to_dist` 参数。 子进程模式下，只需要在 Agent 初始化函数中传入 `to_dist=True` 即可： @@ -240,7 +240,7 @@ D-->F #### PlaceHolder -同时，为了支持中心化的应用编排，AgentScope引入了Placeholder这一概念。 +同时，为了支持中心化的应用编排，AgentScope 引入了 {class}`Placeholder` 这一概念。 Placeholder 可以理解为消息的指针，指向消息真正产生的位置，其对外接口与传统模式中的消息完全一致，因此可以按照传统中心化的消息使用方式编排应用。 Placeholder 内部包含了该消息产生方的联络方法，可以通过网络获取到被指向消息的真正值。 每个分布式部署的 Agent 在收到其他 Agent 发来的消息时都会立即返回一个 Placeholder，从而避免阻塞请求发起方。 diff --git a/examples/distributed_simulation/main.py b/examples/distributed_simulation/main.py index 6534cc1c7..89d4c1557 100644 --- a/examples/distributed_simulation/main.py +++ b/examples/distributed_simulation/main.py @@ -1,5 +1,5 @@ # -*- coding: utf-8 -*- -""" Average """ +""" A large-scale social simulation experiment """ import argparse import time diff --git a/src/agentscope/agents/agent.py b/src/agentscope/agents/agent.py index eabcc2b8a..3b6a70f54 100644 --- a/src/agentscope/agents/agent.py +++ b/src/agentscope/agents/agent.py @@ -120,10 +120,31 @@ def __init__( memory_config (`Optional[dict]`): The config of memory. to_dist (`Optional[Union[dict, bool]]`, default to `False`): - The parameter dict for `to_dist` method. Used in `_AgentMeta`, - when this parameter is provided, the agent will automatically - be converted into its distributed version. See - :doc:`Tutorial ` for detail. + The parameter dict passed to :py:meth:`to_dist` method. Used in + :py:class:`_AgentMeta`, when this parameter is provided, + the agent will automatically be converted into its distributed + version. The input format is as follows: + + .. code-block:: python + + # run as a sub process + agent = XXXAgent( + # ... other parameters + to_dist=True, + ) + + # connect to an existing agent server + agent = XXXAgent( + # ... other parameters + to_dist={ + "host": "ip of your server", + "port": 12345, + # other parameters of `to_dist` + }, + ) + + See :doc:`Distribution Tutorial ` for + detail. """ self.name = name self.memory_config = memory_config