在实际的多智能体系统开发中如何快速构建一个具备对话、协作与任务执行能力的智能体集群是许多开发者面临的挑战。AgentScope作为一个新兴的多智能体框架其2.0版本在易用性、编排能力和部署灵活性上有了显著提升。本文将以一个可运行的智能体对话项目为例带你从零开始完成AgentScope 2.0的环境配置、智能体定义与编排、以及本地运行验证的全过程。无论你是希望探索多智能体协作的初学者还是寻求将智能体能力集成到现有系统的开发者都能通过本文获得一个清晰的实践起点。1. 理解AgentScope的核心概念与工作模式在开始写代码之前需要先理清几个关键概念这能帮助你理解后续每一步操作的目的而不是机械地复制命令。1.1 什么是多智能体系统Multi-Agent System简单来说多智能体系统是由多个具备一定自主决策和交互能力的“智能体”Agent组成的集合。每个智能体可以看作一个独立的软件实体它能够感知环境例如接收消息、处理信息例如调用模型API或工具、并做出响应例如回复消息或执行动作。这些智能体通过相互通信与协作共同完成单个智能体难以处理的复杂任务例如多人辩论、协同创作、分步骤问题求解等。AgentScope框架的作用就是为构建这样的系统提供一套标准化的“脚手架”。它帮你处理了智能体间消息传递的底层通信、对话状态的维护、以及执行流程的编排让你可以更专注于智能体本身的行为逻辑设计。1.2 AgentScope 2.0 的核心组件AgentScope 2.0的架构主要围绕以下几个核心组件展开理解它们之间的关系至关重要智能体Agent系统的核心执行单元。一个智能体通常包含身份Role定义其职能如“程序员”、“测试员”、“产品经理”。模型Model智能体思考与生成回复所依赖的大语言模型LLM后端例如通过OpenAI API、DashScope API或本地模型调用。系统提示词System Prompt定义智能体的行为准则、知识边界和对话风格。工具Tools智能体可以调用的外部函数用于获取信息如天气查询或执行操作如运行代码、写文件。消息Message智能体之间通信的基本载体。一条消息通常包含发送者sender、接收者recipient、内容content等字段。AgentScope内置了多种消息类型如UserMessage,AIMessage来区分消息来源。管道Pipeline这是AgentScope 2.0编排能力的核心。你可以将管道理解为智能体协作的“工作流”或“剧本”。它定义了消息在智能体之间流转的顺序和逻辑。最简单的管道是顺序对话复杂的管道可以包含条件分支、循环、并行执行等。服务Service与运行时Runtime这是部署和运行多智能体应用的底层支撑。Service负责管理智能体实例的生命周期和资源Runtime则提供了分布式运行、持久化、监控等高级能力。对于入门和本地开发我们主要与Pipeline和Agent打交道。1.3 本地开发与云端部署的差异本文聚焦于本地开发与运行这是学习和调试的最佳起点。本地环境意味着所有组件Python解释器、依赖包、智能体进程都运行在你的个人电脑上。云端部署则涉及将你的智能体应用打包成服务部署到云服务器或容器平台如Docker, Kubernetes使其能够被远程访问并提供稳定的服务。两者在配置管理、网络通信、资源监控等方面有显著不同。我们先在本地跑通核心逻辑再考虑部署会清晰得多。2. 搭建本地Python开发环境一个干净、版本匹配的Python环境是避免后续各种依赖冲突的前提。请严格按照以下步骤操作。2.1 安装Python 3.8AgentScope 2.0 需要 Python 3.8 或更高版本。如果你的系统没有安装或者版本过低请先进行安装或升级。Windows/macOS 用户建议从 Python官网 下载安装包。安装时务必勾选 “Add Python to PATH” 选项。Linux 用户通常系统已预装Python可通过python3 --version检查。如需安装使用包管理器例如 Ubuntu/Debian:sudo apt update sudo apt install python3 python3-pip。安装后打开终端Windows 为 CMD 或 PowerShellmacOS/Linux 为 Terminal执行以下命令验证python --version # 或 python3 --version预期应输出类似Python 3.10.12的信息。2.2 创建并激活虚拟环境强烈建议为每个项目创建独立的虚拟环境以隔离依赖。创建项目目录并进入mkdir agentscope-demo cd agentscope-demo创建虚拟环境使用venv(推荐)# Windows python -m venv venv # macOS/Linux python3 -m venv venv使用conda(如果你熟悉Anaconda)conda create -n agentscope-env python3.10 conda activate agentscope-env激活虚拟环境Windows (CMD)venv\Scripts\activateWindows (PowerShell).\venv\Scripts\Activate.ps1如果遇到执行策略错误先以管理员身份运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUsermacOS/Linuxsource venv/bin/activate激活成功后终端提示符前通常会显示虚拟环境名如(venv)。2.3 安装AgentScope及相关依赖在激活的虚拟环境中使用pip安装 AgentScope。为了获得完整功能我们安装agentscope基础包以及一些常用的可选依赖。pip install agentscope这个命令会安装AgentScope的核心库及其最小依赖集。为了后续示例能顺利运行我们还需要安装用于调用OpenAI兼容API的库如openai以及用于解析JSON响应的json5。同时为了演示工具调用我们安装一个用于执行Python代码的库codeinterpreterapi这是一个示例实际生产需谨慎评估安全性。pip install openai json5 codeinterpreterapi注意codeinterpreterapi仅用于本地演示它会在隔离环境中执行代码。在生产环境中开放代码执行能力是极高风险操作必须结合严格的权限控制、沙箱环境和输入审查。安装完成后可以验证一下pip list | findstr agentscope # Windows # 或 pip list | grep agentscope # macOS/Linux应能看到agentscope及其版本信息。3. 构建你的第一个多智能体对话项目现在我们来创建一个简单的多智能体对话场景一个“程序员”智能体和一个“测试员”智能体它们将围绕一段代码进行讨论。程序员负责写代码测试员负责找bug。3.1 项目结构与配置文件在项目根目录agentscope-demo下创建如下文件和目录结构agentscope-demo/ ├── configs/ # 存放配置文件 │ └── model_configs.json ├── agents/ # 存放智能体定义 │ └── my_agents.py ├── pipelines/ # 存放管道定义 │ └── code_review_pipeline.py ├── main.py # 应用入口 └── requirements.txt # 依赖列表可选可由pip freeze生成首先我们需要配置模型。在configs/model_configs.json中定义我们智能体将要使用的LLM。这里以使用OpenAI API为例。你需要准备一个有效的OpenAI API Key。{ model_configs: { gpt-4o-mini: { config_name: gpt-4o-mini, model_type: openai, model_name: gpt-4o-mini, api_key: sk-your-openai-api-key-here, // 替换成你的真实API Key organization: your-org-id, // 可选 generate_args: { temperature: 0.5, max_tokens: 2000 } }, qwen-max: { config_name: qwen-max, model_type: dashscope, model_name: qwen-max, api_key: sk-your-dashscope-api-key-here // 如需使用阿里云通义千问在此配置 } } }关键参数解释config_name: 你给这个配置起的名字后续在代码中通过这个名字引用。model_type: 指定模型提供商如openai,dashscope,ollama(本地模型) 等。model_name: 对应提供商的具体模型名称如gpt-4o-mini,gpt-4-turbo,qwen-max。api_key: 访问该模型API所需的密钥。切勿将此文件提交到公开的代码仓库。generate_args: 模型生成文本时的默认参数如temperature(创造性0-1)max_tokens(最大生成长度)。3.2 定义智能体程序员与测试员接下来在agents/my_agents.py中创建两个智能体。# agents/my_agents.py from agentscope.agents import AgentBase from agentscope.message import Msg from agentscope.models import OpenAIChatWrapper import json # 加载模型配置 with open(“configs/model_configs.json”, “r”, encoding“utf-8”) as f: model_configs json.load(f)[“model_configs”] # 初始化一个OpenAI模型包装器使用配置中的“gpt-4o-mini” model OpenAIChatWrapper(configmodel_configs[“gpt-4o-mini”]) class ProgrammerAgent(AgentBase): 程序员智能体负责编写和解释代码。 def __init__(self, name“程序员”): super().__init__(namename, modelmodel) # 设置系统提示词定义智能体的角色和行为 self.sys_prompt “”” 你是一名经验丰富的软件工程师擅长Python编程。 你的任务是清晰、简洁地编写代码并解释代码的逻辑。 当测试员指出问题时你需要认真分析并给出修复方案。 你的回复应专注于技术细节保持专业。 “”” self.memory.add(Msg(“system”, self.sys_prompt, role“system”)) def reply(self, incoming_message: Msg) - Msg: # 将收到的消息加入记忆上下文 self.memory.add(incoming_message) # 准备给模型的对话历史从记忆中提取 history_for_model self.memory.get_memory() # 调用模型生成回复 response self.model(messageshistory_for_model) # 将模型的回复封装成消息并加入自己的记忆 msg Msg(self.name, response.text, role“assistant”) self.memory.add(msg) return msg class TesterAgent(AgentBase): 测试员智能体负责审查代码并寻找潜在问题。 def __init__(self, name“测试员”): super().__init__(namename, modelmodel) # 可以复用同一个模型也可以配置不同的 self.sys_prompt “”” 你是一名严谨的软件测试工程师对代码质量有极高的要求。 你的任务是仔细审查程序员提供的代码从功能、边界条件、代码风格、潜在bug等角度提出质疑和改进建议。 你的提问和指正要具体、有依据。 “”” self.memory.add(Msg(“system”, self.sys_prompt, role“system”)) def reply(self, incoming_message: Msg) - Msg: self.memory.add(incoming_message) history_for_model self.memory.get_memory() response self.model(messageshistory_for_model) msg Msg(self.name, response.text, role“assistant”) self.memory.add(msg) return msg代码要点解析继承AgentBase这是创建自定义智能体的标准方式。初始化模型通过OpenAIChatWrapper加载我们在配置文件中定义的模型。所有智能体可以共享一个模型实例也可以各自使用不同的模型。系统提示词sys_prompt这是塑造智能体“性格”和“能力”的关键。好的提示词能显著提升智能体在特定任务上的表现。我们将它作为一条system角色的消息存入智能体的记忆memory。reply方法这是智能体处理消息的核心逻辑。流程是接收消息 - 存入记忆 - 组合记忆中的对话历史 - 发送给模型 - 得到回复 - 封装成消息并返回同时自己也记住这次回复。3.3 编排对话流程创建管道智能体定义好了但它们还不知道如何互动。我们需要在pipelines/code_review_pipeline.py中编写一个管道来定义对话流程。# pipelines/code_review_pipeline.py from agentscope.pipelines import SequentialPipeline from agentscope.message import Msg from agents.my_agents import ProgrammerAgent, TesterAgent def create_code_review_pipeline(): 创建一个代码评审对话管道。 # 1. 实例化智能体 programmer ProgrammerAgent() tester TesterAgent() # 2. 定义初始用户输入触发对话 # 假设用户要求程序员写一个函数 user_request “请编写一个Python函数接收一个整数列表作为输入返回这个列表中的最大值和最小值。函数需要处理空列表的情况。” # 3. 创建顺序管道 pipeline SequentialPipeline( agents[programmer, tester], initial_inputMsg(“user”, user_request, role“user”), max_rounds3 # 控制对话轮数程序员 - 测试员 - 程序员 - 测试员 - 程序员 ) return pipeline # 也可以定义更复杂的管道例如加入条件判断 # from agentscope.pipelines import IfElsePipeline, WhilePipeline # 根据程序员回复的代码质量决定测试员是否需要进行第二轮提问。管道工作流解析SequentialPipeline是最简单的管道它按照agents列表的顺序让消息依次流过每个智能体。initial_input是管道的启动信号这里我们模拟了一个用户请求。max_rounds3意味着这个顺序流程会执行3轮。具体流程是第1轮用户请求 -程序员- (回复)第2轮程序员回复 -测试员- (回复)第3轮测试员回复 -程序员- (回复) 然后管道结束。你可以通过调整轮数来控制对话深度。3.4 启动应用编写主程序最后在main.py中把一切串联起来并运行我们的多智能体应用。# main.py import agentscope from pipelines.code_review_pipeline import create_code_review_pipeline def main(): # 第一步初始化AgentScope运行时对于简单本地运行使用默认初始化即可 # 这一步会设置默认的消息分发器、内存管理器等基础组件。 agentscope.init() print(“ 开始多智能体代码评审对话 \n”) # 第二步创建对话管道 pipeline create_code_review_pipeline() # 第三步运行管道 final_output pipeline.run() # 第四步打印最终结果最后一轮智能体的回复 print(f“\n 对话结束 ”) print(f“最终输出内容\n{final_output.content}”) # 你也可以选择打印整个对话历史 # print(“\n 完整对话历史 ) # for agent in [pipeline.agents[0], pipeline.agents[1]]: # print(f”\n{agent.name}的记忆“) # for msg in agent.memory.get_memory(): # print(f” [{msg.role}] {msg.name}: {msg.content[:100]}...“) if __name__ “__main__”: main()4. 运行与结果验证现在让我们运行这个项目看看智能体们如何协作。4.1 执行程序在项目根目录下确保虚拟环境已激活然后运行python main.py4.2 预期输出与分析程序运行后你将在终端看到类似以下的对话过程具体内容因模型随机性而异 开始多智能体代码评审对话 [程序员] 收到用户请求请编写一个Python函数... [程序员] 回复好的我将编写一个名为 find_min_max 的函数... 此处显示程序员生成的代码和解释 [测试员] 收到程序员的消息。 [测试员] 回复代码逻辑基本正确但我有几个问题1. 函数名 find_min_max 是否足够清晰... 此处显示测试员提出的问题和建议 [程序员] 收到测试员的消息。 [程序员] 回复感谢指正。关于函数名可以考虑改为 get_range... 此处显示程序员对测试员反馈的回应和可能的代码修改 对话结束 最终输出内容 显示程序员最后一轮的回复内容如何验证项目运行成功观察流程确认控制台按“程序员-测试员-程序员”的顺序输出了对话。检查内容相关性程序员的回复应包含可运行的Python代码测试员的回复应针对代码提出具体问题如边界条件、命名、异常处理程序员的第二次回复应直接回应测试员的问题。无报错信息终端不应出现Traceback或Error等异常信息。常见的初期错误是API Key配置错误或网络连接问题。4.3 深入查看对话细节如果你想更细致地分析每个智能体的“思考”过程可以取消main.py中注释掉的打印对话历史的代码。这能帮你理解模型是如何基于完整的上下文包括系统提示词和之前的对话生成每一次回复的。5. 常见问题排查与调试指南在初次运行或修改代码后你可能会遇到一些问题。以下是典型问题的排查路径。5.1 模型调用失败问题现象可能原因检查方式处理建议报错AuthenticationError或Invalid API Key1. API Key 错误或过期。2. 配置文件路径错误未正确加载配置。1. 检查configs/model_configs.json中的api_key值。2. 在代码中打印model.config确认配置已加载。1. 前往对应平台如OpenAI重新生成或复制正确的API Key。2. 使用绝对路径或确保相对路径正确。报错RateLimitError或ConnectionError1. API调用频率超限或余额不足。2. 网络连接问题。1. 登录API提供商控制台查看用量和余额。2. 尝试ping相关API域名。1. 等待限制解除或充值。2. 检查本地代理或防火墙设置。报错ModelNotFoundError指定的model_name不存在。核对配置文件中的model_name字符串是否与提供商支持的模型列表完全一致。查阅对应模型提供商的官方文档使用正确的模型标识符。5.2 智能体不按预期回复问题现象可能原因检查方式处理建议智能体回复内容与角色不符如测试员写起了代码系统提示词 (sys_prompt) 未生效或太弱。1. 检查__init__中是否将sys_prompt以system消息加入了memory。2. 打印agent.memory.get_memory()查看消息列表。1. 确保在super().__init__后添加系统消息。2. 强化提示词明确指令如“你必须以测试员身份只提问和找茬不要提供代码解决方案”。智能体忘记了之前的对话记忆 (memory) 未正确维护或上下文长度超限。1. 检查reply方法中是否将incoming_message和自身回复都加入了memory。2. 模型有上下文长度限制旧消息可能被丢弃。1. 确保self.memory.add()调用无误。2. 对于长对话考虑使用SummarizationMemory或手动管理关键记忆。管道只执行了一轮就结束max_rounds参数设置过小或管道逻辑有误。检查SequentialPipeline初始化时的max_rounds值。增加max_rounds。对于复杂流程考虑使用WhilePipeline基于条件循环。5.3 环境与依赖问题问题现象可能原因检查方式处理建议ModuleNotFoundError: No module named ‘agentscope’1. 未安装agentscope。2. 未在正确的虚拟环境中运行。1. 执行pip list查看已安装包。2. 确认终端提示符前有(venv)等虚拟环境标识。1. 在激活的虚拟环境中执行pip install agentscope。2. 重新激活虚拟环境。安装依赖时速度慢或超时默认pip源网络连接不佳。尝试pip install package_name -i https://pypi.tuna.tsinghua.edu.cn/simple更换为国内镜像源如清华、阿里云或配置pip全局镜像。代码中使用了未定义的变量或函数拼写错误或导入错误。仔细阅读错误信息定位到具体的文件和行号。检查类名、函数名、变量名、导入语句from ... import ...是否正确。5.4 调试技巧增加日志输出在智能体的reply方法开始和结束处打印日志观察消息流。def reply(self, incoming_message): print(f“[DEBUG] {self.name} 收到消息: {incoming_message.content[:50]}...”) # ... 原有逻辑 ... print(f“[DEBUG] {self.name} 回复消息: {msg.content[:50]}...”) return msg简化复现如果遇到复杂错误先创建一个最小的、可复现的脚本只包含最核心的出错逻辑排除其他模块干扰。检查模型原始响应在调用self.model()后打印response对象的原始结构确认其包含text属性。6. 进阶实践与扩展方向成功运行基础项目后你可以从以下几个方向深化对AgentScope的理解和应用。6.1 为智能体装备工具Tools让智能体不仅能说还能“做”。例如为程序员智能体装备一个代码执行工具。首先安装工具依赖如果之前没安装pip install codeinterpreterapi然后修改agents/my_agents.py中的ProgrammerAgent# 在文件顶部导入 from agentscope.tools import tool # 定义一个工具函数 tool def execute_python_code(code: str) - str: 执行一段Python代码并返回结果。仅用于演示生产环境需极度谨慎。 try: # 这是一个高度简化的示例。实际应用应使用安全的沙箱环境。 # 例如可以使用 codeinterpreterapi 的 SafeCodeExecutor from codeinterpreterapi import SafeCodeExecutor executor SafeCodeExecutor() result executor.execute(code) return f“代码执行成功。输出\n{result}” except Exception as e: return f“代码执行出错{str(e)}” class ProgrammerAgent(AgentBase): def __init__(self, name“程序员”): super().__init__(namename, modelmodel) self.sys_prompt “...” # 同前 # 将工具注册给智能体 self.tools {“execute_python_code”: execute_python_code} # 在系统提示词中告知智能体可以使用这个工具 self.sys_prompt “\n\n你可以使用 execute_python_code 工具来运行你写的Python代码以验证其正确性。工具输入是一段代码字符串。” self.memory.add(Msg(“system”, self.sys_prompt, role“system”)) def reply(self, incoming_message): # ... 原有记忆添加逻辑 ... # 在调用模型时传入可用的工具描述 response self.model( messageshistory_for_model, toolsself.tools, # 关键让模型知道有哪些工具可用 tool_choice“auto” # 让模型自行决定是否调用工具 ) # 检查回复是否包含工具调用 if response.tool_calls: # 处理工具调用 tool_name response.tool_calls[0].function.name tool_args response.tool_calls[0].function.arguments if tool_name in self.tools: tool_result self.tools[tool_name](**tool_args) # 将工具执行结果作为一条新消息再次调用模型生成最终回复 self.memory.add(Msg(“tool”, tool_result, nametool_name)) # 重新组合历史并生成最终回复 final_history self.memory.get_memory() final_response self.model(messagesfinal_history) msg Msg(self.name, final_response.text, role“assistant”) self.memory.add(msg) return msg # 如果没有工具调用按正常流程处理 msg Msg(self.name, response.text, role“assistant”) self.memory.add(msg) return msg这样当程序员在对话中生成一段代码后模型可能会决定调用execute_python_code工具来验证代码并将运行结果反馈到对话中使对话更真实。6.2 使用更复杂的管道逻辑SequentialPipeline只是开始。AgentScope 提供了多种管道类型IfElsePipeline: 根据条件决定下一个执行的智能体。SwitchPipeline: 类似于多路开关。WhilePipeline: 在条件满足时循环执行。ForPipeline: 遍历一个序列执行。例如创建一个循环评审管道直到测试员认为代码没有问题为止简化示例from agentscope.pipelines import WhilePipeline from agentscope.message import Msg def create_iterative_review_pipeline(programmer, tester): def condition(last_message): # 一个简单的条件如果测试员的最后一条消息包含“通过”或“没问题”则停止循环 # 这是一个非常简单的启发式规则实际应用需要更复杂的判断逻辑。 last_content last_message.content.lower() return “通过” not in last_content and “没问题” not in last_content pipeline WhilePipeline( conditioncondition, pipelineSequentialPipeline(agents[programmer, tester]), max_iterations5 # 防止无限循环 ) return pipeline6.3 配置管理与生产环境考量在本地开发时我们将API Key硬编码在JSON文件中。对于生产环境这是极不安全的。你应该使用环境变量通过os.getenv(“OPENAI_API_KEY”)读取密钥。import os api_key os.getenv(“OPENAI_API_KEY”) if not api_key: raise ValueError(“请设置 OPENAI_API_KEY 环境变量”)配置文件外置化将model_configs.json移出代码仓库通过环境变量指定其路径或在部署时由配置中心注入。添加日志与监控集成日志框架如logging或structlog记录智能体的关键决策、工具调用和异常。考虑添加性能监控和告警。考虑分布式运行时对于复杂的、耗时的智能体任务可以探索使用 AgentScope 的DistributedRuntime将智能体部署到不同的进程甚至机器上提高并发能力和资源利用率。6.4 探索不同的模型后端除了OpenAIAgentScope支持多种模型后端。例如使用本地部署的Ollama模型首先确保已安装并运行 Ollama 并拉取了模型如llama3.2。修改configs/model_configs.json{ “model_configs”: { “local-llama”: { “config_name”: “local-llama”, “model_type”: “ollama”, “model_name”: “llama3.2”, “options”: { “temperature”: 0.7, “num_predict”: 512 }, “base_url”: “http://localhost:11434” // Ollama 默认地址 } } }在代码中使用OllamaWrapper加载此配置即可。这可以大幅降低API调用成本并保障数据隐私。通过以上步骤你不仅成功运行了一个多智能体对话项目还掌握了其核心组件的配置、定义和编排方法。接下来你可以尝试设计更复杂的智能体角色如产品经理、架构师、集成更丰富的工具如网络搜索、数据库查询、或构建具有决策树和循环的复杂业务流程。多智能体系统的魅力在于通过简单的个体交互涌现出复杂的群体智能而AgentScope为你提供了实现这一愿景的坚实起点。