掌握Multi-Agent实践(一)：使用AgentScope实践入门和Workstation上手指南

AgentScope是通义实验室开源的multi-agent编程框架，专为开发人员设计，提供了丰富的组件, 全面的文档和广泛的兼容性。同时，AgentScope Workstation提供了在线拖拉拽编程和在线小助手(copilot)功能，帮助开发者迅速上手！支持自定义的容错控制和重试机制，以提高应用程序的稳定性,支持以中心化的方式构建分布式多智能体应用程序。

• github链接：https://github.com/modelscope/agentscope
• 论文链接：AgentScope: A Flexible yet Robust Multi-Agent Platform
  

• 更多介绍参考：

  • 打造可靠的多智能体生态系统：从集成到部署AgentScope为多智能体应用提供的全面支持方案
  • 解决多Agent信息传递难题：AgentScope实现分布式架构下的高效协作与优化跨机器通信与任务调度，扩展性提升

1.实践上手AgentScope

1.1 安装

• 从github上clone AgentScope仓库(https://github.com/modelscope/agentscope)，安装最新代码

git clone [e-mail]:modelscope/agentscope.git
cd AgentScope
# On mac
pip install -e .\[full\]
# On windows
pip install -e .[full]

#从pip安装的AgentScope-推荐
pip install agentscope

1.2 配置模型

• 在AgentScope中配置DashScope支持的通义（qwen-max）模型配置or 其他配置：

import os

"""
在环境变量中设置了'DASHSCOPE_API_KEY'：
命令行中执行：export DASHSCOPE_API_KEY='替换成你的apikey'
可以通过命令行：echo $DASHSCOPE_API_KEY 来检查是否真的设置成功
"""

dashscope_example_config = {
    "model_type": "dashscope_chat",
    "config_name": "tongyi_qwen_config",
    "model_name": "qwen-max",
    "api_key": f"{os.environ.get('DASHSCOPE_API_KEY')}",
}

除了DashScope的API，在AgentScope中也可以配置其他流行的模型

# 使用OpenAI模型(gpt-4o，或者替换成其他openai模型)的配置 
# 相似的可以echo $OPENAI_API_KEY 来检查OPENAI_API_KEY是否设置成功
openai_example_config = {
    "model_type": "openai",
    "config_name": "gpt-4o-config",
    "model_name": "gpt-4o",
    "api_key": f"{os.environ.get('OPENAI_API_KEY')}",
    "generate_args": {
        "temperature": 0.5,
    },
}


# 其他可以通过post 访问的LLM接口
# 下面的my_postapi_config可以对应的open ai的post ai端口规则
# curl $YOUR_URL_TO_MODEL \
# -H "Content-Type: application/json" \
# -H "Authorization: Bearer $YOUR_API_KEY_IF_ANY" \
# -d '{
#   "model": "XXX",
#   "messages": [
#      .....
#   ]
# }'
postapi_example_config = {
    "model_type": "post_api_chat",
    "config_name": "my_postapi_config",
    "api_url": "$YOUR_URL_TO_MODEL",
    "headers": {
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_API_KEY_IF_ANY"
    },
    "messages_key": "messages",
    "json_args": {
        "model": "XXX",
    }
}

• 目前推荐直接配置一个model_configs.json文件

  这里使用零一万物主要是新用户免费 🐶

[
    {
        "config_name": "yi-lightning",
        "model_name": "yi-lightning",
        "model_type": "yi_chat",
        "api_key": "57c7959c"
    },
    {
        "config_name": "yi-vision-v2",
        "model_name": "yi-vision-v2",
        "model_type": "yi_chat",
        "api_key": "57a28cbc7959c"
    },
    {
        "model_type": "openai_chat",
        "config_name": "gpt-4o",
        "model_name": "gpt-4o",
        "api_key": "sk-",
        "client_args": {
            "base_url": "http://xxx.com:4000"
        }
    },
    {
        "model_type": "openai_chat",
        "config_name": "gemini-2.0-flash",
        "model_name": "google_ai_studio/gemini-2.0-flash-001",
        "api_key": "sk-",
        "client_args": {
            "base_url": "http://:4000"
        }
    },
    {
        "model_type": "openai_chat",
        "config_name": "gemini-2.5-flash",
        "model_name": "google_ai_studio/gemini-2.5-flash-preview-04-17",
        "api_key": "sk-",
        "client_args": {
            "base_url": "http://:4000"
        }
    }
]

1.3 初始化，创建dialog_agent

显示和隐式看个人喜好，

import agentscope

# 让config生效
agentscope.init(
    model_configs=[
      dashscope_example_config,
      openai_examaple_config,
      # 其他模型配置也可以继续添加在这里~
    ],
)


# or 
agentscope.init(model_configs="agentscope/model_configs.json")

作为最基础的一种agent，DialogAgent可能是最简单上手的一个agent。创建一个实例，只需要给dialog agent命名、简单的系统提示词和一个模型的配置（config）的名字

from agentscope.agents import DialogAgent

dialog_agent = DialogAgent(
    name="Assistant",
    sys_prompt="You're a helpful assistant.",
    model_config_name="gemini-2.0-flash",  # 其中一个你在上面步骤准备好的配置名字（config_name对应的值）
)

1.4 创建user_agent

有了一个有记忆、能和你对话的智能体dialog_agent，现在我们创建一个user_agent作为你在电子世界的代理，用来接收用户输入信息。

from agentscope.agents.user_agent import UserAgent

user_agent = UserAgent()

 # start the conversation between user and assistant
x = None
while x is None or x.content != "exit":
    x = dialog_agent(x)
    x = user_agent(x)

1.5 UI可视化

AgentScope 支持基于 AgentScope Studio 和 Gradio 的网页可视化，同时支持用户对接自定义或第三方的可视化平台。

AgentScope Studio

AgentScope Studio 是基于 React(vite) 和 NodeJS 开发的 WebUI 工具，用于应用的可视化，和监控应用运行，监控 API 调用以及 Token 使用情况。

• 首先需要安装 npm

# MacOS
brew install node

# Ubuntu
sudo apt update
sudo apt install nodejs npm

# Windows 请访问 https://nodejs.org/ 进行安装

通过以下命令进行安装

npm install -g @agentscope/studio

• 在命令台通过如下命令启动

as_studio

启动 AgentScope 的 Python 程序时，通过 agentscope.init 函数中的 studio_url 字段连接 AgentScope Studio。

import agentscope

agentscope.init(
    # ...
    studio_url="https://localhost:3000"  # 替换成你本地的 AgentScope Studio 地址
)

# ...

备注：一旦连接，Python 程序中所有智能体对象调用 speak 函数打印出的输出都将转发 到 AgentScope Studio，同时程序中的 UserAgent 的输入操作也将从终端转移到 AgentScope Studio 的 Dashboard 面板中。

Studio 中的 Dashboard 页面将按照 agentscope.init 函数中传入的 project 参数对程序 进行分组，点击后即可查看该项目分组内所有历史运行情况。

需要用户进行输入时，对话界面的输入按键会进行提示，不需要输入时，输入按钮会处于禁用状态。

• 完整代码：

from agentscope.agents import DialogAgent, UserAgent
import agentscope


agentscope.init(model_configs="agentscope/agentscope/examples/test_ting/test/model_configs.json",
                studio_url="http://127.0.0.1:5000")

# 创建对话Agent和用户Agent
dialog_agent = DialogAgent(
    name="Assistant",
    sys_prompt="你是一个AI助手，你会回答用户的问题。",
    model_config_name="gpt-4o",  
)

user_agent = UserAgent()

# 开始对话 user and assistant
x = None
while x is None or x.content != "exit":
    x = dialog_agent(x)
    x = user_agent(x)

Gradio

首先，请确保已安装完整版本的 AgentScope, 其中包含 Gradio 包。

# From pypi
pip install agentscope[full]

# From source code
cd agentscope
pip install .[full]

之后，请确保您的应用程序被封装在一个 main 函数中。

from agentscope.agents import DialogAgent, UserAgent
import agentscope


def main():
    # Your code here
    agentscope.init(model_configs={
        "config_name": "my-qwen-max",
        "model_type": "dashscope_chat",
        "model_name": "qwen-max"
    })

    agent = DialogAgent(
        name="Alice,
        model_config_,
        sys_prompt="You're a helpful assistant named Alice."
    )
    user = UserAgent(agent)

    msg = None
    while True:
        msg = agent(msg)
        msg = user(msg)
        if msg.content == "exit":
            break

然后在终端执行以下命令启动 Gradio UI:

as_gradio {path_to_your_python_code}

最后，您可以访问 Gradio UI，如下所示:

自定义可视化

自定义可视化主要分为两个组成部分

1. 消息显示：将智能体中 speak 函数打印的输出转发到需要显示的地方
2. 用户输入：将 UserAgent 中的 输入操作 转移到目标平台，这样用户可以从目标平台进行输入

上述两个操作分别是通过 AgentScope 中的钩子函数 pre_speak_hook，以及 UserAgent 中 的 override_input_method 完成（AgentScope 中的 Studio 和 Gradio 也是 通过同样的方法实现）。

更多内容参考文档：自定义可视化

2. AgentScope Workstation

2.1 Workstation

首先确保您已安装最新版本的 AgentScope。

执行以下 Python 代码来启动 AgentScope Studio：

import agentscope
agentscope.studio.init()

或在终端中运行以下 bash 命令：

然后访问 https://127.0.0.1:5000 进入 AgentScope Studio，并点击侧边栏中的 Workstation 图标进入。

• 中央工作区：您可以在这个主要区域拖拽组件来构建应用程序。
• 顶部工具箱：用于导入、导出、检查和运行您的应用程序。

• 内置示例

对于初学者，我们强烈建议从预构建的示例开始。您可以直接单击示例将其导入到中央工作区。或者，为了获得更加结构化的学习体验，您也可以选择跟随每个示例链接的教程。这些教程将一步步指导如何在 AgentScope Workstation 上构建多智能体应用。

• 构建应用

  要构建应用程序，请执行以下步骤：

  • 选择并拖拽组件：从侧边栏中单击并拖拽所选组件到中央工作区。
  • 连接节点：大多数节点都有输入和输出点。单击一个组件的输出点并拖拽到另一个组件的输入点，以创建消息流管道。这样不同的节点就可以传递消息。
  • 配置节点：将节点放入工作区后，单击任意一个节点来填写其配置设置。您可以自定义提示、参数和其他属性。
• 运行应用

构建完应用程序后，单击 "运行" 按钮。在运行之前，Workstation 会检查应用程序中是否有任何错误。如果有错误，系统会提示您在继续之前进行修正。之后，您的应用程序将在与 AgentScope Studio 相同的 Python 环境中执行，您可以在 Dashboard 中找到它。

• 导入 / 导出应用

Workstation 支持导入和导出您的应用程序。单击 "导出 HTML" 或 "导出 Python" 按钮可生成代码，您可以将其分发给社区或本地保存。如果要将导出的代码转换为 Python 代码，可以使用以下命令将 JSON 配置编译为 Python 代码：

# 编译
as_workflow config.json --compile ${YOUR_PYTHON_SCRIPT_NAME}.py

如果您想直接运行本地配置，可以使用以下命令：

# 运行
as_gradio config.json

想要进一步编辑您的应用程序吗？只需单击 "导入 HTML" 按钮，将以前导出的 HTML 代码重新上传到 AgentScope Workstation 即可。

• 检查应用

  构建应用程序后，您可以单击 "检查" 按钮来验证应用程序结构的正确性。将执行以下检查规则：

  • 模型和智能体存在检查：每个应用程序必须至少包含一个模型节点和一个智能体节点。
  • 单连接策略：每个组件的每个输入不应该有多于一个连接。
  • 必填字段验证：所有必填输入字段都必须填写，以确保每个节点都有正确运行所需的参数。
  • 配置命名一致性：智能体节点使用的 "模型配置名称" 必须与模型节点中定义的 "配置名称" 相对应。
  • 适当的节点嵌套：像 ReActAgent 这样的节点应该只包含工具节点。同样，像 IfElsePipeline 这样的管道节点应该包含正确数量的元素（不超过 2 个），而 ForLoopPipeline、WhileLoopPipeline 和 MsgHub 应该遵守只有一个元素的规则（必须是 SequentialPipeline 作为子节点）。

2.2 快速使用

• 案例教学
  
• 自动转化代码
  
  点击运行后可以在Dashboard查看效果