English | δΈζ
AgentScope is an innovative multi-agent platform designed to empower developers to build multi-agent applications with ease, reliability, and high performance. It features three high-level capabilities:
-
Easy-to-Use: Programming in pure Python with various pre-built components for immediate use, suitable for developers or users with varying levels of customization requirements. Detailed documentation and examples are provided to help you get started, see our Tutorial.
-
High Robustness: Supporting customized fault-tolerance controls and retry mechanisms to enhance application stability.
-
Actor-Based Distribution: Enabling developers to build distributed multi-agent applications in a centralized programming manner for streamlined development.
If you find our work helpful, please kindly cite our paper.
Welcome to join our community on
Discord | DingTalk | |
---|---|---|
[2024-02-27] We release AgentScope v0.0.1 now, which is also available in PyPI!
[2024-02-14] We release our paper "AgentScope: A Flexible yet Robust Multi-Agent Platform" in arXiv now!
To install AgentScope, you need to have Python 3.9 or higher installed.
Note: This project is currently in active development, it's recommended to install AgentScope from source.
- Run the following commands to install AgentScope in editable mode.
# Pull the source code from GitHub
git clone https://github.com/modelscope/agentscope.git
# Install the package in editable mode
cd AgentScope
pip install -e .
- Building a distributed multi-agent application relies on gRPC libraries, and you can install the required dependencies as follows.
# On windows
pip install -e .[distribute]
# On mac
pip install -e .\[distribute\]
- Use the following command to install the latest released AgentScope.
pip install agentscope
Taking a multi-agent application with user and assistant agent as an example, you need to take the following steps:
AgentScope supports the following model API services:
- OpenAI Python APIs, including
- Post request APIs, including
- HuggingFace and ModelScope inference APIs
- Customized model APIs
Model Type Argument | Support APIs | |
---|---|---|
OpenAI Chat API | openai |
Standard OpenAI Chat API, FastChat and vllm |
OpenAI DALL-E API | openai_dall_e |
Standard DALL-E API |
OpenAI Embedding API | openai_embedding |
OpenAI embedding API |
DashScope Chat API | dashscope_chat |
DashScope chat API, including Qwen series |
Post API | post_api |
Huggingface/ModelScope inference API, and customized post API |
For OpenAI APIs, you need to prepare a dict of model config with the following fields:
{
"config_name": "{config name}", # The name to identify the config
"model_type": "openai" | "openai_dall_e" | "openai_embedding",
"model_name": "{model name, e.g. gpt-4}", # The model in openai API
# Optional
"api_key": "xxx", # The API key for OpenAI API. If not set, env
# variable OPENAI_API_KEY will be used.
"organization": "xxx", # The organization for OpenAI API. If not set, env
# variable OPENAI_ORGANIZATION will be used.
}
For DashScope APIs, you need to prepare a dict of model config with the following fields:
{
"config_name": "{config name}", # The name to identify the config
"model_type": "dashscope_chat" | "dashscope_text_embedding" | "dashscope_image_synthesis",
"model_name": "{model name, e.g. qwen-max}", # The model in dashscope API
"api_key": "xxx", # The API key for DashScope API.
}
Note: The dashscope APIs may have strict requirements on the
role
field in messages. Please use with caution.
For post requests APIs, the config contains the following fields.
{
"config_name": "{config name}", # The name to identify the config
"model_type": "post_api",
"api_url": "https://xxx", # The target url
"headers": { # Required headers
...
},
}
AgentScope provides fruitful scripts to fast deploy model services in Scripts. For more details of model services, refer to our Tutorial and API Document.
Create built-in user and assistant agents as follows.
from agentscope.agents import DialogAgent, UserAgent
import agentscope
# Load model configs
agentscope.init(model_configs="./model_configs.json")
# Create a dialog agent and a user agent
dialog_agent = DialogAgent(name="assistant", model_config_name="your_config_name")
user_agent = UserAgent()
In AgentScope, message is the bridge among agents, which is a
dict that contains two necessary fields name
and content
and an
optional field url
to local files (image, video or audio) or website.
from agentscope.message import Msg
x = Msg(name="Alice", content="Hi!")
x = Msg("Bob", "What about this picture I took?", url="/path/to/picture.jpg")
Start a conversation between two agents (e.g. dialog_agent and user_agent) with the following code:
x = None
while True:
x = dialog_agent(x)
x = user_agent(x)
if x.content == "exit": # user input "exit" to exit the conversation
break
To simplify the construction of agents communication, AgentScope provides two helpful tools: Pipeline and MsgHub.
-
Pipeline: It allows users to program a communication among agents easily. Taking a sequential pipeline as an example, the following two codes are equivalent, but pipeline is more convenient and elegant.
-
Passing message throught agent1, agent2 and agent3 WITHOUT pipeline:
x1 = agent1(input_msg) x2 = agent2(x1) x3 = agent3(x2)
-
WITH object-level pipeline:
from agentscope.pipelines import SequentialPipeline pipe = SequentialPipeline([agent1, agent2, agent3]) x3 = pipe(input_msg)
-
WITH functional-level pipeline:
from agentscope.pipelines.functional import sequentialpipeline x3 = sequentialpipeline([agent1, agent2, agent3], x=input_msg)
-
-
MsgHub: To achieve a group conversation, AgentScope provides message hub.
-
Achieving group conversation WITHOUT
msghub
:x1 = agent1(x) agent2.observe(x1) # The message x1 should be broadcast to other agents agent3.observe(x1) x2 = agent2(x1) agent1.observe(x2) agent3.observe(x2)
-
With
msghub
: In a message hub, the messages from participants will be broadcast to all other participants automatically. In such case, participated agents even don't need input and output messages explicitly. All we need to do is to decide the order of speaking. Besides,msghub
also supports dynamic control of participants as follows.from agentscope import msghub with msghub(participants=[agent1, agent2, agent3]) as hub: agent1() # `x = agent1(x)` is also okay agent2() # Broadcast a message to all participants hub.broadcast(Msg("Host", "Welcome to join the group conversation!")) # Add or delete participants dynamically hub.delete(agent1) hub.add(agent4)
-
To implement your own agent, you need to inherit the AgentBase
class and implement the reply
function.
from agentscope.agents import AgentBase
class MyAgent(AgentBase):
def reply(self, x):
# Do something here, e.g. calling your model and get the raw field as your agent's response
response = self.model(x).raw
return response
AgentScope provides built-in resources for developers to build their own applications easily. More built-in agents, services and examples are coming soon!
- UserAgent
- DialogAgent
- DictDialogAgent
- ...
- Web Search Service
- Code Execution Service
- Retrieval Service
- Database Service
- File Service
- ...
- Example of Conversation: examples/conversation
- Example of Werewolf: examples/werewolf
- Example of Distributed Agents: examples/distributed
- ...
More built-in resources are coming soon!
AgentScope is released under Apache License 2.0.
Contributions are always welcomed!
We provide a developer version with additional pre-commit hooks to perform checks compared to the official version:
# For windows
pip install -e .[dev]
# For mac
pip install -e .\[dev\]
# Install pre-commit hooks
pre-commit install
Please refer to our Contribution Guide for more details.
If you find our work helpful for your research or application, please cite our paper:
@article{agentscope,
author = {Dawei Gao and
Zitao Li and
Weirui Kuang and
Xuchen Pan and
Daoyuan Chen and
Zhijian Ma and
Bingchen Qian and
Liuyi Yao and
Lin Zhu and
Chen Cheng and
Hongzhu Shi and
Yaliang Li and
Bolin Ding and
Jingren Zhou},
title = {AgentScope: A Flexible yet Robust Multi-Agent Platform},
journal = {CoRR},
volume = {abs/2402.14034},
year = {2024},
}