Package: agentscope
AgentScopeAgentScope 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 ourTutorial.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 citeour paper.Welcome to join our community onDiscordDingTalkWeChatTable of ContentsAgentScopeTable of ContentsInstallationFrom sourceUsing pipQuick StartBasic UsageStep 1: Prepare Model ConfigsOpenAI API ConfigPost Request API ConfigStep 2: Create AgentsStep 3: Construct ConversationAdvanced UsagePipelineandMsgHubCustomize Your Own AgentBuilt-in ResourcesAgent PoolServicesExample ApplicationsLicenseContributingReferencesInstallationTo 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.From sourceRun the following commands to install AgentScope in editable mode.# Pull the source code from githubgitclonehttps://github.com/modelscope/agentscope.git# Install the package in editable modecdAgentScope
pipinstall-e.Building a distributed multi-agent application relies ongRPClibraries, and you can install the required dependencies as follows.# On windowspipinstall-e.[distribute]# On macpipinstall-e.\[distribute\]Using pipUse the following command to install the latest released AgentScope.pipinstallAgentScopeQuick StartBasic UsageTaking a multi-agent application with user and assistant agent as an example, you need to take the following steps:Step 1: Prepare Model ConfigsStep 2: Create AgentsStep 3: Construct ConversationStep 1: Prepare Model ConfigsAgentScope supports the following model API services:OpenAI Python APIs, includingOpenAI Chat, DALL-E and Embedding APIOpenAI-Compatible platforms, e.g.FastChatandvllmPost request APIs, includingHuggingFaceandModelScopeinference APIsCustomized model APIsModel Type ArgumentSupport APIsOpenAI Chat APIopenaiStandard OpenAI Chat API, FastChat and vllmOpenAI DALL-E APIopenai_dall_eStandard DALL-E APIOpenAI Embedding APIopenai_embeddingOpenAI embedding APIPost APIpost_apiHuggingface/ModelScope inference API, and customized post APIOpenAI API ConfigFor 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.
}Post Request API ConfigFor 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 inScripts.
For more details of model services, refer to ourTutorialandAPI Document.Step 2: Create AgentsCreate built-in user and assistant agents as follows.fromagentscope.agentsimportDialogAgent,UserAgentimportagentscope# Load model configsagentscope.init(model_configs="./model_configs.json")# Create a dialog agent and a user agentdialog_agent=DialogAgent(name="assistant",model_config_name="your_config_name")user_agent=UserAgent()Step 3: Construct ConversationIn AgentScope,messageis the bridge among agents, which is adictthat contains two necessary fieldsnameandcontentand an
optional fieldurlto local files (image, video or audio) or website.fromagentscope.messageimportMsgx=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=NonewhileTrue:x=dialog_agent(x)x=user_agent(x)ifx.content=="exit":# user input "exit" to exit the conversationbreakAdvanced UsagePipelineandMsgHubTo simplify the construction of agents communication, AgentScope provides two helpful tools:PipelineandMsgHub.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 agent3WITHOUTpipeline:x1=agent1(input_msg)x2=agent2(x1)x3=agent3(x2)WITHobject-level pipeline:fromagentscope.pipelinesimportSequentialPipelinepipe=SequentialPipeline([agent1,agent2,agent3])x3=pipe(input_msg)WITHfunctional-level pipeline:fromagentscope.pipelines.functionalimportsequentialpipelinex3=sequentialpipeline([agent1,agent2,agent3],x=input_msg)MsgHub: To achieve a group conversation, AgentScope provides message hub.Achieving group conversationWITHOUTmsghub:x1=agent1(x)agent2.observe(x1)# The message x1 should be broadcast to other agentsagent3.observe(x1)x2=agent2(x1)agent1.observe(x2)agent3.observe(x2)Withmsghub: 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,msghubalso supports dynamic control of participants as follows.fromagentscopeimportmsghubwithmsghub(participants=[agent1,agent2,agent3])ashub:agent1()# `x = agent1(x)` is also okayagent2()# Broadcast a message to all participantshub.broadcast(Msg("Host","Welcome to join the group conversation!"))# Add or delete participants dynamicallyhub.delete(agent1)hub.add(agent4)Customize Your Own AgentTo implement your own agent, you need to inherit theAgentBaseclass and implement thereplyfunction.fromagentscope.agentsimportAgentBaseclassMyAgent(AgentBase):defreply(self,x):# Do something here, e.g. calling your model and get the raw field as your agent's responseresponse=self.model(x).rawreturnresponseBuilt-in ResourcesAgentScope provides built-in resources for developers to build their own applications easily. More built-in agents, services and examples are coming soon!Agent PoolUserAgentDialogAgentDictDialogAgentRpcDialogAgent...ServicesWeb Search ServiceCode Execution ServiceRetrieval ServiceDatabase ServiceFile Service...Example ApplicationsExample of Conversation:examples/ConversationExample of Werewolf:examples/WerewolfExample of Distributed Agents:examples/Distributed Agents...More built-in resources are coming soon!LicenseAgentScope is released under Apache License 2.0.ContributingContributions are always welcomed!We provide a developer version with additional pre-commit hooks to perform checks compared to the official version:# For windowspipinstall-e.[dev]# For macpipinstall-e.\[dev\]# Install pre-commit hookspre-commitinstallPlease refer to ourContribution Guidefor more details.ReferencesIf you find our work helpful for your research or application, please citeour 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},
}