最近在尝试构建多智能体应用时你是否也遇到过这样的困扰网上资料零散环境配置复杂智能体之间的协作逻辑难以梳理更别提将应用部署到云端了。AgentScope 2.0 的出现为开发者提供了一个强大且易用的多智能体应用开发框架。本文将为你带来一份从零开始的保姆级教程涵盖环境搭建、核心概念、智能体编排实战一直到云端部署的完整闭环。无论你是刚接触多智能体概念的新手还是希望将想法快速落地的开发者都能从中找到清晰的路径和可复用的代码。1. AgentScope 2.0 是什么为什么需要它在深入实操之前我们有必要先理解 AgentScope 2.0 的核心价值。简单来说AgentScope 2.0 是一个专为构建、管理和编排多智能体应用而设计的开源框架。它旨在降低多智能体系统开发的复杂性让开发者能够像搭积木一样将不同的 AI 模型如 OpenAI GPT、DeepSeek、本地模型等封装成智能体并定义它们之间的交互规则从而完成复杂的协作任务。它解决了什么问题环境隔离与依赖管理不同 AI 模型API 或本地的调用方式、参数格式各异手动整合费时费力且容易出错。AgentScope 提供了统一的接口和模型服务层。智能体间通信与状态管理多智能体协作的核心是消息传递和状态共享。AgentScope 内置了成熟的消息总线Message Bus和对话内存Dialog Memory机制让智能体间的“对话”变得清晰可控。流程编排复杂定义“谁在什么时候、对谁、说什么”是编排的难点。AgentScope 提供了 Pipeline、Workflow 等多种编排模式支持顺序、并行、循环等复杂逻辑。部署与监控困难从本地开发到生产部署存在鸿沟。AgentScope 支持容器化部署并提供了 Web UI 等工具便于监控和调试智能体应用。常见应用场景智能客服与销售路由智能体分析用户意图专业智能体解答问题最后总结智能体生成报告。代码审查与生成代码生成智能体、代码审查智能体、测试用例生成智能体协同工作。游戏与模拟创建多个具有不同性格和目标的 NPC非玩家角色智能体在虚拟环境中互动。数据分析与报告数据获取智能体、分析智能体、可视化智能体、报告撰写智能体组成流水线。掌握 AgentScope意味着你拥有了快速构建复杂 AI 协作系统的“脚手架”能将更多精力聚焦在业务逻辑和创新上而非底层通信和调度。2. 环境准备与安装指南工欲善其事必先利其器。AgentScope 2.0 基于 Python 开发因此一个干净的 Python 环境是第一步。为了避免与系统中其他项目的依赖冲突强烈建议使用虚拟环境。2.1 基础环境准备操作系统Windows 10/11, macOS, Linux (如 Ubuntu 20.04) 均可。Python 版本推荐 Python 3.8 至 3.11。Python 3.12 及以上版本可能存在部分依赖兼容性问题建议暂时使用 3.11。首先检查你的 Python 和 pip 版本python --version pip --version如果未安装或版本过低请前往 Python 官网 下载安装。2.2 创建并激活虚拟环境使用venv创建虚拟环境是标准做法。在 Windows 上# 在项目目录下打开命令行 python -m venv agentscope_env # 激活虚拟环境 agentscope_env\Scripts\activate激活后命令行提示符前会出现(agentscope_env)字样。在 macOS/Linux 上python3 -m venv agentscope_env # 激活虚拟环境 source agentscope_env/bin/activate2.3 安装 AgentScope 2.0激活虚拟环境后使用 pip 进行安装。官方推荐从 PyPI 安装稳定版。pip install agentscope安装过程会自动处理核心依赖。为了获得更完整的体验如 Web UI可以安装全量包pip install “agentscope[all]”安装完成后可以通过以下命令验证是否成功python -c “import agentscope; print(agentscope.__version__)”如果输出版本号如2.0.0则说明安装成功。2.4 配置模型服务以 OpenAI 为例AgentScope 本身不提供 AI 模型它需要连接后端的模型服务。我们以最常用的 OpenAI API 为例进行配置。获取 API Key登录 OpenAI Platform 创建一个新的 API Key 并妥善保存。创建配置文件在项目根目录下创建一个名为model_configs.yaml的文件YAML 格式更清晰。AgentScope 支持通过配置文件集中管理所有模型。# model_configs.yaml model_configs: # 定义一个名为 “gpt-4” 的配置 gpt-4: config_name: “gpt-4” # 配置名称 model_type: “openai” # 模型类型 model_name: “gpt-4” # 具体模型名称如 gpt-3.5-turbo, gpt-4-turbo-preview api_key: “sk-…” # 替换为你的真实 API Key organization: “org-…” # 可选你的组织 ID generate_args: # 可选的生成参数 temperature: 0.7 max_tokens: 1000重要安全提示永远不要将包含真实 API Key 的配置文件提交到 Git 等版本控制系统。建议将api_key的值设置为环境变量在配置文件中引用例如api_key: “${OPENAI_API_KEY}”然后在系统或.env文件中设置该环境变量。3. 核心概念与快速上手在开始编排智能体之前需要理解 AgentScope 中的几个核心对象Agent、Message、Model和Pipeline。3.1 智能体 (Agent)智能体是封装了特定角色、能力和记忆的实体。AgentScope 提供了多种内置智能体最常用的是DialogAgent它能够根据历史对话进行响应。创建一个简单的对话智能体# quick_start.py import agentscope from agentscope.agents import DialogAgent from agentscope.models import OpenAIChatWrapper # 第一步初始化 AgentScope加载配置 agentscope.init(model_configs“./model_configs.yaml”) # 第二步从配置中创建模型包装器 model OpenAIChatWrapper(config_name“gpt-4”) # 第三步创建智能体为其赋予一个角色 agent DialogAgent( name“助手”, modelmodel, sys_prompt“你是一个乐于助人且知识渊博的AI助手请用中文回答用户的问题。” ) # 第四步与智能体对话 response agent(“你好请介绍一下Python的列表推导式。”) print(response.text) # 打印智能体的回复运行python quick_start.py你将看到 AI 助手对问题的回答。sys_prompt是系统提示词用于定义智能体的行为和角色。3.2 消息 (Message)智能体之间通过Message对象进行通信。一个Message通常包含name发送者、content内容和role角色如user,assistant,system。from agentscope.message import Msg # 创建一个用户消息 user_msg Msg(“用户”, “今天天气怎么样”, role“user”) # 创建一个助手消息 assistant_msg Msg(“助手”, “我是一个AI无法获取实时天气。”, role“assistant”)3.3 你的第一个多智能体对话让我们创建两个智能体让它们互相交谈。# two_agents_chat.py import agentscope from agentscope.agents import DialogAgent from agentscope.models import OpenAIChatWrapper from agentscope.message import Msg agentscope.init(model_configs“./model_configs.yaml”) model OpenAIChatWrapper(config_name“gpt-4”) # 创建两个具有不同角色的智能体 alice DialogAgent( name“Alice”, modelmodel, sys_prompt“你是一个乐观的旅行爱好者喜欢分享有趣的目的地。说话风格热情。” ) bob DialogAgent( name“Bob”, modelmodel, sys_prompt“你是一个谨慎的规划师注重旅行的预算和安全。说话风格务实。” ) # 开始对话Alice 先发起话题 topic “周末去郊外露营” print(f“话题: {topic}”) print(“-” * 30) msg_to_bob Msg(“Alice”, f“嘿Bob我们在讨论{topic}我觉得这太棒了你有什么想法”, role“user”) for i in range(3): # 让它们交流三个回合 # Bob 回复 Alice reply_from_bob bob(msg_to_bob) print(f“Bob: {reply_from_bob.text}”) # Alice 回复 Bob msg_to_alice Msg(“Bob”, reply_from_bob.text, role“user”) reply_from_alice alice(msg_to_alice) print(f“Alice: {reply_from_alice.text}”) # 更新消息用于下一轮 msg_to_bob Msg(“Alice”, reply_from_alice.text, role“user”) print(“-” * 10)运行这个脚本你会看到 Alice 和 Bob 围绕露营话题展开带有各自角色特色的讨论。这展示了最基本的智能体间交互。4. 智能体编排实战构建一个代码审查流水线现在我们来完成一个更实用的项目一个简单的自动化代码审查流水线。这个流水线包含三个智能体代码理解智能体分析提交的代码提取关键信息。漏洞检查智能体基于规则或模型检查潜在的安全漏洞和坏味道。报告生成智能体汇总前两者的分析生成一份友好的审查报告。我们将使用Pipeline来编排它们。Pipeline 允许数据消息按顺序流经一系列处理节点智能体。4.1 项目结构code_review_pipeline/ ├── model_configs.yaml # 模型配置文件 ├── pipeline_demo.py # 主程序 └── requirements.txt # 依赖文件requirements.txt内容agentscope[all]4.2 定义智能体类我们将创建三个自定义智能体类继承自AgentBase。# pipeline_demo.py import agentscope from agentscope.agents import AgentBase from agentscope.message import Msg from agentscope.models import OpenAIChatWrapper from agentscope.pipelines import Pipeline # 1. 代码理解智能体 class CodeUnderstandingAgent(AgentBase): def __init__(self, name, model): super().__init__(namename) self.model model self.sys_prompt “””你是一个资深的代码架构师。你的任务是分析用户提供的代码片段并总结 1. 这段代码的主要功能是什么 2. 使用了哪些关键库或框架 3. 代码结构上有何特点 请用简洁的 bullet points 回答。“”” def reply(self, message: Msg): # 将系统提示和用户代码组合成给模型的输入 prompt f“{self.sys_prompt}\n\n请分析以下代码\npython\n{message.content}\n” response self.model(prompt) # 返回一个新的消息发送者是当前智能体 return Msg(self.name, response.text, role“assistant”) # 2. 漏洞检查智能体 class VulnerabilityAgent(AgentBase): def __init__(self, name, model): super().__init__(namename) self.model model self.sys_prompt “””你是一个安全专家。检查以下代码可能存在的安全问题或不良实践例如 - SQL注入风险 - 硬编码的敏感信息如密码、API密钥 - 缺少输入验证 - 潜在的资源泄漏文件、网络连接未关闭 - 错误处理不完善 请列出你发现的所有问题并为每个问题提供简要说明和改进建议。“”” def reply(self, message: Msg): prompt f“{self.sys_prompt}\n\n代码\npython\n{message.content}\n” response self.model(prompt) return Msg(self.name, response.text, role“assistant”) # 3. 报告生成智能体 class ReportAgent(AgentBase): def __init__(self, name, model): super().__init__(namename) self.model model self.sys_prompt “””你是一个技术文档工程师。请根据前两位专家的分析代码理解和漏洞检查生成一份综合的代码审查报告。 报告需要包含以下部分 - 概述 - 代码功能总结 - 发现的问题与风险按严重性排序 - 具体的改进建议 - 总体评价 请使用清晰、专业的语言并以Markdown格式输出。“”” def reply(self, message: Msg): # 注意这里的 message.content 应该包含前两个智能体的输出 prompt f“{self.sys_prompt}\n\n以下是分析材料\n{message.content}” response self.model(prompt) return Msg(self.name, response.text, role“assistant”)4.3 构建并运行 Pipeline# pipeline_demo.py (续) def main(): # 初始化加载配置 agentscope.init(model_configs“./model_configs.yaml”) model OpenAIChatWrapper(config_name“gpt-4”) # 实例化三个智能体 understand_agent CodeUnderstandingAgent(name“理解者”, modelmodel) vuln_agent VulnerabilityAgent(name“安全检查员”, modelmodel) report_agent ReportAgent(name“报告员”, modelmodel) # 待审查的代码示例一个存在问题的简单函数 code_to_review “”” import sqlite3 def get_user_data(user_id): conn sqlite3.connect(‘mydatabase.db’) cursor conn.cursor() # 警告直接拼接字符串存在SQL注入风险 query f“SELECT * FROM users WHERE id {user_id}” cursor.execute(query) data cursor.fetchall() # 注意连接没有关闭 return data “”” print(“ 开始代码审查流水线 ”) print(f“待审查代码\n{code_to_review}”) print(“-” * 50) # 构建 Pipeline理解 - 检查 - 生成报告 pipeline Pipeline( [ understand_agent, vuln_agent, report_agent, ] ) # 运行 Pipeline输入初始消息原始代码 # Pipeline 会将上一个智能体的输出自动作为下一个智能体的输入。 final_message pipeline(Msg(“用户”, code_to_review, role“user”)) print(“\n 生成的审查报告 ) print(final_message.content) print(“ 流水线执行完毕 ”) if __name__ “__main__”: main()4.4 运行与结果分析运行python pipeline_demo.py。你会看到流水线依次执行“理解者”智能体分析代码功能。“安全检查员”智能体找出 SQL 注入和资源泄漏问题。“报告员”智能体汇总生成一份完整的 Markdown 格式报告。这个例子展示了如何将复杂任务分解由不同专长的智能体协作完成。Pipeline 自动处理了消息传递让开发者只需关注每个智能体的核心逻辑。5. 进阶编排使用 Workflow 处理复杂逻辑Pipeline 适合线性流程。对于更复杂的交互如需要根据智能体的回答内容决定下一步走向条件分支或者让多个智能体并行执行后再汇总结果就需要用到Workflow。假设一个场景用户输入一个需求由一个“主管”智能体判断需求类型然后并行分派给“文案”和“设计”智能体最后汇总结果。5.1 引入条件与并行这里我们使用IfElseBlock和Placeholder等组件来构建 Workflow。由于 Workflow 定义相对复杂我们使用一个简化的串行流程来演示其概念。在实际复杂应用中你可以利用agentscope.workflows中的IfElseBlock,SwitchCaseBlock,ForLoopBlock,WhileLoopBlock等来构建有向无环图 (DAG)。# workflow_demo.py import agentscope from agentscope.agents import DialogAgent from agentscope.message import Msg from agentscope.models import OpenAIChatWrapper from agentscope.workflows import Workflow agentscope.init(model_configs“./model_configs.yaml”) model OpenAIChatWrapper(config_name“gpt-4”) # 定义几个智能体 manager DialogAgent(name“经理”, modelmodel, sys_prompt“你是项目经理负责拆解任务。”) coder DialogAgent(name“程序员”, modelmodel, sys_prompt“你是后端开发负责设计API和数据库。”) tester DialogAgent(name“测试员”, modelmodel, sys_prompt“你是QA工程师负责设计测试用例。”) # 定义一个自定义的工作流函数 def development_workflow(requirement: str) - str: “”“模拟一个简单的开发工作流经理拆解 - 程序员设计 - 测试员设计测试。”“” print(f“需求: {requirement}”) # 步骤1: 经理拆解任务 task_msg Msg(“用户”, f“请将以下需求拆解成技术任务{requirement}”, role“user”) task_breakdown manager(task_msg) print(f“[经理拆解]: {task_breakdown.text}”) # 步骤2: 程序员根据拆解进行设计 design_msg Msg(“经理”, task_breakdown.text, role“user”) api_design coder(design_msg) print(f“[程序员设计]: {api_design.text}”) # 步骤3: 测试员根据设计写测试用例 test_msg Msg(“程序员”, api_design.text, role“user”) test_cases tester(test_msg) print(f“[测试用例]: {test_cases.text}”) # 汇总结果 summary f“需求‘{requirement}’的处理结果\n” summary f“1. 任务拆解\n{task_breakdown.text}\n\n” summary f“2. API设计\n{api_design.text}\n\n” summary f“3. 测试用例\n{test_cases.text}” return summary # 使用 Workflow 包装这个函数这里Workflow主要起管理和记录作用 workflow Workflow(development_workflow) # 运行工作流 result workflow.run(“开发一个用户注册登录功能包含邮箱验证。”) print(“\n 工作流最终汇总 ) print(result)这个示例虽然将逻辑写在了函数里但展示了工作流“分步骤、有状态”的核心思想。对于真正的并行、条件分支你需要深入学习Workflow的块Block式 API。6. 云端部署使用 Docker 容器化你的智能体应用开发完成后你需要将应用部署到服务器或云平台如阿里云、腾讯云、AWS。Docker 是实现环境一致性和便捷部署的标准工具。6.1 编写 Dockerfile在项目根目录code_review_pipeline/下创建Dockerfile# 使用官方 Python 轻量级镜像 FROM python:3.11-slim # 设置工作目录 WORKDIR /app # 复制依赖文件并安装 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple # 复制应用代码 COPY . . # 设置环境变量用于传递API Key更安全的方式是使用云平台的密钥管理服务 # ENV OPENAI_API_KEY“your_key_here” # 声明容器运行时监听的端口如果应用有Web服务 # EXPOSE 8080 # 运行应用 CMD [“python”, “pipeline_demo.py”]6.2 构建 Docker 镜像在包含Dockerfile的目录下执行docker build -t agentscope-code-review:latest .这会将你的应用及其所有依赖打包成一个名为agentscope-code-review的镜像。6.3 运行 Docker 容器运行容器并通过环境变量传入 API Key避免写在代码或镜像中docker run -e OPENAI_API_KEY“sk-your-actual-key-here” agentscope-code-review:latest容器会启动并执行pipeline_demo.py。6.4 部署到云服务器推送镜像到镜像仓库将构建好的镜像推送到 Docker Hub、阿里云容器镜像服务等。docker tag agentscope-code-review:latest yourusername/agentscope-code-review:latest docker push yourusername/agentscope-code-review:latest在云服务器上拉取并运行# 在云服务器上执行 docker pull yourusername/agentscope-code-review:latest docker run -d -e OPENAI_API_KEY“${YOUR_KEY}” --name code-review-app yourusername/agentscope-code-review:latest使用-d参数让容器在后台运行。7. 常见问题与排查思路 (FAQ)在学习和使用 AgentScope 2.0 的过程中你可能会遇到以下问题问题现象常见原因解决思路ModuleNotFoundError: No module named ‘agentscope’1. 未安装 AgentScope。2. 在错误的 Python 环境或未激活虚拟环境中运行。1. 使用pip install agentscope安装。2. 检查命令行前缀是否有(venv_name)使用which python或where python确认 Python 解释器路径。OpenAIError: Invalid API key1. API Key 错误或过期。2. 配置文件格式错误Key 未正确加载。3. 网络问题导致无法访问 OpenAI API。1. 在 OpenAI 平台检查并重置 Key。2. 检查model_configs.yaml中api_key的拼写和缩进尝试使用环境变量。3. 检查网络连接和代理设置。智能体回复内容不符合预期或混乱1.sys_prompt定义不清晰。2. 不同智能体使用了相同的模型实例导致记忆混淆。3. 消息历史管理不当。1. 优化系统提示词明确角色和任务边界。2. 为每个智能体创建独立的模型包装器实例。3. 检查是否使用了DialogAgent的memory参数或手动管理消息列表。Pipeline 或 Workflow 执行卡住或无输出1. 某个智能体的reply方法陷入死循环或未返回Message对象。2. 模型 API 调用超时或失败。3. Workflow 逻辑存在循环依赖。1. 在智能体的reply方法中添加日志打印。2. 检查网络和 API 状态为模型调用增加超时和重试机制。3. 绘制 Workflow 的流程图检查是否存在环。Docker 容器启动后立即退出1. 应用脚本执行完毕非持久化应用。2. 脚本中发生未捕获的异常。3. CMD 命令错误。1. 如果是 Web 服务确保应用是持续运行的如使用uvicorn app:app --host 0.0.0.0。2. 查看 Docker 日志docker logs container_id。3. 检查Dockerfile中的CMD指令是否正确。8. 最佳实践与工程建议将多智能体应用投入实际项目需要遵循一些工程化实践以确保稳定性、可维护性和安全性。配置管理密钥分离永远不要将 API Key、数据库密码等敏感信息硬编码在代码或配置文件中。使用环境变量如os.getenv(“KEY”)或专业的密钥管理服务如 AWS Secrets Manager, HashiCorp Vault。配置分层为开发、测试、生产环境准备不同的配置文件如config_dev.yaml,config_prod.yaml通过环境变量AGENTSCOPE_ENV来切换。错误处理与健壮性模型调用容错网络波动和 API 限流是常态。在模型调用层封装重试逻辑和退避策略。from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10)) def safe_model_call(model, prompt): return model(prompt)智能体超时为智能体的reply方法设置超时防止单个智能体卡住整个流水线。验证输入输出对流入智能体的消息和智能体产出的消息进行格式和内容验证。可观测性与调试结构化日志使用logging模块记录关键步骤、输入输出和错误。为不同智能体设置不同的 Logger。利用 AgentScope Web UIAgentScope 提供了 Web 界面来可视化智能体的交互和消息流在调试复杂 Workflow 时非常有用。确保在开发环境启用它。持久化对话历史将重要的对话历史保存到数据库或文件便于事后分析和模型优化。性能优化模型并行调用在 Workflow 中对于无依赖的智能体任务使用asyncio或ThreadPoolExecutor实现并行调用减少总等待时间。缓存对于内容不变或变化缓慢的模型请求如知识库查询可以考虑引入缓存机制。轻量级模型在不需要最强能力的环节使用更小、更快的模型如 GPT-3.5-turbo以降低成本和提高响应速度。安全边界输入净化对用户输入进行严格的检查和过滤防止 Prompt 注入攻击避免智能体被诱导执行不当操作。输出审查对智能体生成的内容尤其是对外发布的进行二次审查防止产生有害、偏见或不合规的内容。权限控制在多租户系统中严格隔离不同用户或组织的智能体运行环境和数据。从理解 AgentScope 2.0 的核心概念到完成环境配置和第一个智能体对话从构建线性的代码审查流水线到探索更复杂的 Workflow 编排最后通过 Docker 将应用容器化并部署。这条路径涵盖了从开发到上线的关键环节。多智能体系统的魅力在于通过分工协作解决复杂问题而 AgentScope 为你提供了实现这一愿景的高效工具箱。接下来你可以尝试将更多类型的模型如本地部署的 Llama、DeepSeek集成进来或者设计更精巧的智能体协作模式如辩论、评审、谈判等解锁 AI 应用的更多可能性。 
长河君 · 2026/9/4 3:18:38 · 阅读 1.2k AgentScope 2.0 保姆级教程：从零构建多智能体应用，实现代码审查与云端部署
最近在尝试构建多智能体应用时你是否也遇到过这样的困扰网上资料零散环境配置复杂智能体之间的协作逻辑难以梳理更别提将应用部署到云端了。AgentScope 2.0 的出现为开发者提供了一个强大且易用的多智能体应用开发框架。本文将为你带来一份从零开始的保姆级教程涵盖环境搭建、核心概念、智能体编排实战一直到云端部署的完整闭环。无论你是刚接触多智能体概念的新手还是希望将想法快速落地的开发者都能从中找到清晰的路径和可复用的代码。1. AgentScope 2.0 是什么为什么需要它在深入实操之前我们有必要先理解 AgentScope 2.0 的核心价值。简单来说AgentScope 2.0 是一个专为构建、管理和编排多智能体应用而设计的开源框架。它旨在降低多智能体系统开发的复杂性让开发者能够像搭积木一样将不同的 AI 模型如 OpenAI GPT、DeepSeek、本地模型等封装成智能体并定义它们之间的交互规则从而完成复杂的协作任务。它解决了什么问题环境隔离与依赖管理不同 AI 模型API 或本地的调用方式、参数格式各异手动整合费时费力且容易出错。AgentScope 提供了统一的接口和模型服务层。智能体间通信与状态管理多智能体协作的核心是消息传递和状态共享。AgentScope 内置了成熟的消息总线Message Bus和对话内存Dialog Memory机制让智能体间的“对话”变得清晰可控。流程编排复杂定义“谁在什么时候、对谁、说什么”是编排的难点。AgentScope 提供了 Pipeline、Workflow 等多种编排模式支持顺序、并行、循环等复杂逻辑。部署与监控困难从本地开发到生产部署存在鸿沟。AgentScope 支持容器化部署并提供了 Web UI 等工具便于监控和调试智能体应用。常见应用场景智能客服与销售路由智能体分析用户意图专业智能体解答问题最后总结智能体生成报告。代码审查与生成代码生成智能体、代码审查智能体、测试用例生成智能体协同工作。游戏与模拟创建多个具有不同性格和目标的 NPC非玩家角色智能体在虚拟环境中互动。数据分析与报告数据获取智能体、分析智能体、可视化智能体、报告撰写智能体组成流水线。掌握 AgentScope意味着你拥有了快速构建复杂 AI 协作系统的“脚手架”能将更多精力聚焦在业务逻辑和创新上而非底层通信和调度。2. 环境准备与安装指南工欲善其事必先利其器。AgentScope 2.0 基于 Python 开发因此一个干净的 Python 环境是第一步。为了避免与系统中其他项目的依赖冲突强烈建议使用虚拟环境。2.1 基础环境准备操作系统Windows 10/11, macOS, Linux (如 Ubuntu 20.04) 均可。Python 版本推荐 Python 3.8 至 3.11。Python 3.12 及以上版本可能存在部分依赖兼容性问题建议暂时使用 3.11。首先检查你的 Python 和 pip 版本python --version pip --version如果未安装或版本过低请前往 Python 官网 下载安装。2.2 创建并激活虚拟环境使用venv创建虚拟环境是标准做法。在 Windows 上# 在项目目录下打开命令行 python -m venv agentscope_env # 激活虚拟环境 agentscope_env\Scripts\activate激活后命令行提示符前会出现(agentscope_env)字样。在 macOS/Linux 上python3 -m venv agentscope_env # 激活虚拟环境 source agentscope_env/bin/activate2.3 安装 AgentScope 2.0激活虚拟环境后使用 pip 进行安装。官方推荐从 PyPI 安装稳定版。pip install agentscope安装过程会自动处理核心依赖。为了获得更完整的体验如 Web UI可以安装全量包pip install “agentscope[all]”安装完成后可以通过以下命令验证是否成功python -c “import agentscope; print(agentscope.__version__)”如果输出版本号如2.0.0则说明安装成功。2.4 配置模型服务以 OpenAI 为例AgentScope 本身不提供 AI 模型它需要连接后端的模型服务。我们以最常用的 OpenAI API 为例进行配置。获取 API Key登录 OpenAI Platform 创建一个新的 API Key 并妥善保存。创建配置文件在项目根目录下创建一个名为model_configs.yaml的文件YAML 格式更清晰。AgentScope 支持通过配置文件集中管理所有模型。# model_configs.yaml model_configs: # 定义一个名为 “gpt-4” 的配置 gpt-4: config_name: “gpt-4” # 配置名称 model_type: “openai” # 模型类型 model_name: “gpt-4” # 具体模型名称如 gpt-3.5-turbo, gpt-4-turbo-preview api_key: “sk-…” # 替换为你的真实 API Key organization: “org-…” # 可选你的组织 ID generate_args: # 可选的生成参数 temperature: 0.7 max_tokens: 1000重要安全提示永远不要将包含真实 API Key 的配置文件提交到 Git 等版本控制系统。建议将api_key的值设置为环境变量在配置文件中引用例如api_key: “${OPENAI_API_KEY}”然后在系统或.env文件中设置该环境变量。3. 核心概念与快速上手在开始编排智能体之前需要理解 AgentScope 中的几个核心对象Agent、Message、Model和Pipeline。3.1 智能体 (Agent)智能体是封装了特定角色、能力和记忆的实体。AgentScope 提供了多种内置智能体最常用的是DialogAgent它能够根据历史对话进行响应。创建一个简单的对话智能体# quick_start.py import agentscope from agentscope.agents import DialogAgent from agentscope.models import OpenAIChatWrapper # 第一步初始化 AgentScope加载配置 agentscope.init(model_configs“./model_configs.yaml”) # 第二步从配置中创建模型包装器 model OpenAIChatWrapper(config_name“gpt-4”) # 第三步创建智能体为其赋予一个角色 agent DialogAgent( name“助手”, modelmodel, sys_prompt“你是一个乐于助人且知识渊博的AI助手请用中文回答用户的问题。” ) # 第四步与智能体对话 response agent(“你好请介绍一下Python的列表推导式。”) print(response.text) # 打印智能体的回复运行python quick_start.py你将看到 AI 助手对问题的回答。sys_prompt是系统提示词用于定义智能体的行为和角色。3.2 消息 (Message)智能体之间通过Message对象进行通信。一个Message通常包含name发送者、content内容和role角色如user,assistant,system。from agentscope.message import Msg # 创建一个用户消息 user_msg Msg(“用户”, “今天天气怎么样”, role“user”) # 创建一个助手消息 assistant_msg Msg(“助手”, “我是一个AI无法获取实时天气。”, role“assistant”)3.3 你的第一个多智能体对话让我们创建两个智能体让它们互相交谈。# two_agents_chat.py import agentscope from agentscope.agents import DialogAgent from agentscope.models import OpenAIChatWrapper from agentscope.message import Msg agentscope.init(model_configs“./model_configs.yaml”) model OpenAIChatWrapper(config_name“gpt-4”) # 创建两个具有不同角色的智能体 alice DialogAgent( name“Alice”, modelmodel, sys_prompt“你是一个乐观的旅行爱好者喜欢分享有趣的目的地。说话风格热情。” ) bob DialogAgent( name“Bob”, modelmodel, sys_prompt“你是一个谨慎的规划师注重旅行的预算和安全。说话风格务实。” ) # 开始对话Alice 先发起话题 topic “周末去郊外露营” print(f“话题: {topic}”) print(“-” * 30) msg_to_bob Msg(“Alice”, f“嘿Bob我们在讨论{topic}我觉得这太棒了你有什么想法”, role“user”) for i in range(3): # 让它们交流三个回合 # Bob 回复 Alice reply_from_bob bob(msg_to_bob) print(f“Bob: {reply_from_bob.text}”) # Alice 回复 Bob msg_to_alice Msg(“Bob”, reply_from_bob.text, role“user”) reply_from_alice alice(msg_to_alice) print(f“Alice: {reply_from_alice.text}”) # 更新消息用于下一轮 msg_to_bob Msg(“Alice”, reply_from_alice.text, role“user”) print(“-” * 10)运行这个脚本你会看到 Alice 和 Bob 围绕露营话题展开带有各自角色特色的讨论。这展示了最基本的智能体间交互。4. 智能体编排实战构建一个代码审查流水线现在我们来完成一个更实用的项目一个简单的自动化代码审查流水线。这个流水线包含三个智能体代码理解智能体分析提交的代码提取关键信息。漏洞检查智能体基于规则或模型检查潜在的安全漏洞和坏味道。报告生成智能体汇总前两者的分析生成一份友好的审查报告。我们将使用Pipeline来编排它们。Pipeline 允许数据消息按顺序流经一系列处理节点智能体。4.1 项目结构code_review_pipeline/ ├── model_configs.yaml # 模型配置文件 ├── pipeline_demo.py # 主程序 └── requirements.txt # 依赖文件requirements.txt内容agentscope[all]4.2 定义智能体类我们将创建三个自定义智能体类继承自AgentBase。# pipeline_demo.py import agentscope from agentscope.agents import AgentBase from agentscope.message import Msg from agentscope.models import OpenAIChatWrapper from agentscope.pipelines import Pipeline # 1. 代码理解智能体 class CodeUnderstandingAgent(AgentBase): def __init__(self, name, model): super().__init__(namename) self.model model self.sys_prompt “””你是一个资深的代码架构师。你的任务是分析用户提供的代码片段并总结 1. 这段代码的主要功能是什么 2. 使用了哪些关键库或框架 3. 代码结构上有何特点 请用简洁的 bullet points 回答。“”” def reply(self, message: Msg): # 将系统提示和用户代码组合成给模型的输入 prompt f“{self.sys_prompt}\n\n请分析以下代码\npython\n{message.content}\n” response self.model(prompt) # 返回一个新的消息发送者是当前智能体 return Msg(self.name, response.text, role“assistant”) # 2. 漏洞检查智能体 class VulnerabilityAgent(AgentBase): def __init__(self, name, model): super().__init__(namename) self.model model self.sys_prompt “””你是一个安全专家。检查以下代码可能存在的安全问题或不良实践例如 - SQL注入风险 - 硬编码的敏感信息如密码、API密钥 - 缺少输入验证 - 潜在的资源泄漏文件、网络连接未关闭 - 错误处理不完善 请列出你发现的所有问题并为每个问题提供简要说明和改进建议。“”” def reply(self, message: Msg): prompt f“{self.sys_prompt}\n\n代码\npython\n{message.content}\n” response self.model(prompt) return Msg(self.name, response.text, role“assistant”) # 3. 报告生成智能体 class ReportAgent(AgentBase): def __init__(self, name, model): super().__init__(namename) self.model model self.sys_prompt “””你是一个技术文档工程师。请根据前两位专家的分析代码理解和漏洞检查生成一份综合的代码审查报告。 报告需要包含以下部分 - 概述 - 代码功能总结 - 发现的问题与风险按严重性排序 - 具体的改进建议 - 总体评价 请使用清晰、专业的语言并以Markdown格式输出。“”” def reply(self, message: Msg): # 注意这里的 message.content 应该包含前两个智能体的输出 prompt f“{self.sys_prompt}\n\n以下是分析材料\n{message.content}” response self.model(prompt) return Msg(self.name, response.text, role“assistant”)4.3 构建并运行 Pipeline# pipeline_demo.py (续) def main(): # 初始化加载配置 agentscope.init(model_configs“./model_configs.yaml”) model OpenAIChatWrapper(config_name“gpt-4”) # 实例化三个智能体 understand_agent CodeUnderstandingAgent(name“理解者”, modelmodel) vuln_agent VulnerabilityAgent(name“安全检查员”, modelmodel) report_agent ReportAgent(name“报告员”, modelmodel) # 待审查的代码示例一个存在问题的简单函数 code_to_review “”” import sqlite3 def get_user_data(user_id): conn sqlite3.connect(‘mydatabase.db’) cursor conn.cursor() # 警告直接拼接字符串存在SQL注入风险 query f“SELECT * FROM users WHERE id {user_id}” cursor.execute(query) data cursor.fetchall() # 注意连接没有关闭 return data “”” print(“ 开始代码审查流水线 ”) print(f“待审查代码\n{code_to_review}”) print(“-” * 50) # 构建 Pipeline理解 - 检查 - 生成报告 pipeline Pipeline( [ understand_agent, vuln_agent, report_agent, ] ) # 运行 Pipeline输入初始消息原始代码 # Pipeline 会将上一个智能体的输出自动作为下一个智能体的输入。 final_message pipeline(Msg(“用户”, code_to_review, role“user”)) print(“\n 生成的审查报告 ) print(final_message.content) print(“ 流水线执行完毕 ”) if __name__ “__main__”: main()4.4 运行与结果分析运行python pipeline_demo.py。你会看到流水线依次执行“理解者”智能体分析代码功能。“安全检查员”智能体找出 SQL 注入和资源泄漏问题。“报告员”智能体汇总生成一份完整的 Markdown 格式报告。这个例子展示了如何将复杂任务分解由不同专长的智能体协作完成。Pipeline 自动处理了消息传递让开发者只需关注每个智能体的核心逻辑。5. 进阶编排使用 Workflow 处理复杂逻辑Pipeline 适合线性流程。对于更复杂的交互如需要根据智能体的回答内容决定下一步走向条件分支或者让多个智能体并行执行后再汇总结果就需要用到Workflow。假设一个场景用户输入一个需求由一个“主管”智能体判断需求类型然后并行分派给“文案”和“设计”智能体最后汇总结果。5.1 引入条件与并行这里我们使用IfElseBlock和Placeholder等组件来构建 Workflow。由于 Workflow 定义相对复杂我们使用一个简化的串行流程来演示其概念。在实际复杂应用中你可以利用agentscope.workflows中的IfElseBlock,SwitchCaseBlock,ForLoopBlock,WhileLoopBlock等来构建有向无环图 (DAG)。# workflow_demo.py import agentscope from agentscope.agents import DialogAgent from agentscope.message import Msg from agentscope.models import OpenAIChatWrapper from agentscope.workflows import Workflow agentscope.init(model_configs“./model_configs.yaml”) model OpenAIChatWrapper(config_name“gpt-4”) # 定义几个智能体 manager DialogAgent(name“经理”, modelmodel, sys_prompt“你是项目经理负责拆解任务。”) coder DialogAgent(name“程序员”, modelmodel, sys_prompt“你是后端开发负责设计API和数据库。”) tester DialogAgent(name“测试员”, modelmodel, sys_prompt“你是QA工程师负责设计测试用例。”) # 定义一个自定义的工作流函数 def development_workflow(requirement: str) - str: “”“模拟一个简单的开发工作流经理拆解 - 程序员设计 - 测试员设计测试。”“” print(f“需求: {requirement}”) # 步骤1: 经理拆解任务 task_msg Msg(“用户”, f“请将以下需求拆解成技术任务{requirement}”, role“user”) task_breakdown manager(task_msg) print(f“[经理拆解]: {task_breakdown.text}”) # 步骤2: 程序员根据拆解进行设计 design_msg Msg(“经理”, task_breakdown.text, role“user”) api_design coder(design_msg) print(f“[程序员设计]: {api_design.text}”) # 步骤3: 测试员根据设计写测试用例 test_msg Msg(“程序员”, api_design.text, role“user”) test_cases tester(test_msg) print(f“[测试用例]: {test_cases.text}”) # 汇总结果 summary f“需求‘{requirement}’的处理结果\n” summary f“1. 任务拆解\n{task_breakdown.text}\n\n” summary f“2. API设计\n{api_design.text}\n\n” summary f“3. 测试用例\n{test_cases.text}” return summary # 使用 Workflow 包装这个函数这里Workflow主要起管理和记录作用 workflow Workflow(development_workflow) # 运行工作流 result workflow.run(“开发一个用户注册登录功能包含邮箱验证。”) print(“\n 工作流最终汇总 ) print(result)这个示例虽然将逻辑写在了函数里但展示了工作流“分步骤、有状态”的核心思想。对于真正的并行、条件分支你需要深入学习Workflow的块Block式 API。6. 云端部署使用 Docker 容器化你的智能体应用开发完成后你需要将应用部署到服务器或云平台如阿里云、腾讯云、AWS。Docker 是实现环境一致性和便捷部署的标准工具。6.1 编写 Dockerfile在项目根目录code_review_pipeline/下创建Dockerfile# 使用官方 Python 轻量级镜像 FROM python:3.11-slim # 设置工作目录 WORKDIR /app # 复制依赖文件并安装 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple # 复制应用代码 COPY . . # 设置环境变量用于传递API Key更安全的方式是使用云平台的密钥管理服务 # ENV OPENAI_API_KEY“your_key_here” # 声明容器运行时监听的端口如果应用有Web服务 # EXPOSE 8080 # 运行应用 CMD [“python”, “pipeline_demo.py”]6.2 构建 Docker 镜像在包含Dockerfile的目录下执行docker build -t agentscope-code-review:latest .这会将你的应用及其所有依赖打包成一个名为agentscope-code-review的镜像。6.3 运行 Docker 容器运行容器并通过环境变量传入 API Key避免写在代码或镜像中docker run -e OPENAI_API_KEY“sk-your-actual-key-here” agentscope-code-review:latest容器会启动并执行pipeline_demo.py。6.4 部署到云服务器推送镜像到镜像仓库将构建好的镜像推送到 Docker Hub、阿里云容器镜像服务等。docker tag agentscope-code-review:latest yourusername/agentscope-code-review:latest docker push yourusername/agentscope-code-review:latest在云服务器上拉取并运行# 在云服务器上执行 docker pull yourusername/agentscope-code-review:latest docker run -d -e OPENAI_API_KEY“${YOUR_KEY}” --name code-review-app yourusername/agentscope-code-review:latest使用-d参数让容器在后台运行。7. 常见问题与排查思路 (FAQ)在学习和使用 AgentScope 2.0 的过程中你可能会遇到以下问题问题现象常见原因解决思路ModuleNotFoundError: No module named ‘agentscope’1. 未安装 AgentScope。2. 在错误的 Python 环境或未激活虚拟环境中运行。1. 使用pip install agentscope安装。2. 检查命令行前缀是否有(venv_name)使用which python或where python确认 Python 解释器路径。OpenAIError: Invalid API key1. API Key 错误或过期。2. 配置文件格式错误Key 未正确加载。3. 网络问题导致无法访问 OpenAI API。1. 在 OpenAI 平台检查并重置 Key。2. 检查model_configs.yaml中api_key的拼写和缩进尝试使用环境变量。3. 检查网络连接和代理设置。智能体回复内容不符合预期或混乱1.sys_prompt定义不清晰。2. 不同智能体使用了相同的模型实例导致记忆混淆。3. 消息历史管理不当。1. 优化系统提示词明确角色和任务边界。2. 为每个智能体创建独立的模型包装器实例。3. 检查是否使用了DialogAgent的memory参数或手动管理消息列表。Pipeline 或 Workflow 执行卡住或无输出1. 某个智能体的reply方法陷入死循环或未返回Message对象。2. 模型 API 调用超时或失败。3. Workflow 逻辑存在循环依赖。1. 在智能体的reply方法中添加日志打印。2. 检查网络和 API 状态为模型调用增加超时和重试机制。3. 绘制 Workflow 的流程图检查是否存在环。Docker 容器启动后立即退出1. 应用脚本执行完毕非持久化应用。2. 脚本中发生未捕获的异常。3. CMD 命令错误。1. 如果是 Web 服务确保应用是持续运行的如使用uvicorn app:app --host 0.0.0.0。2. 查看 Docker 日志docker logs container_id。3. 检查Dockerfile中的CMD指令是否正确。8. 最佳实践与工程建议将多智能体应用投入实际项目需要遵循一些工程化实践以确保稳定性、可维护性和安全性。配置管理密钥分离永远不要将 API Key、数据库密码等敏感信息硬编码在代码或配置文件中。使用环境变量如os.getenv(“KEY”)或专业的密钥管理服务如 AWS Secrets Manager, HashiCorp Vault。配置分层为开发、测试、生产环境准备不同的配置文件如config_dev.yaml,config_prod.yaml通过环境变量AGENTSCOPE_ENV来切换。错误处理与健壮性模型调用容错网络波动和 API 限流是常态。在模型调用层封装重试逻辑和退避策略。from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10)) def safe_model_call(model, prompt): return model(prompt)智能体超时为智能体的reply方法设置超时防止单个智能体卡住整个流水线。验证输入输出对流入智能体的消息和智能体产出的消息进行格式和内容验证。可观测性与调试结构化日志使用logging模块记录关键步骤、输入输出和错误。为不同智能体设置不同的 Logger。利用 AgentScope Web UIAgentScope 提供了 Web 界面来可视化智能体的交互和消息流在调试复杂 Workflow 时非常有用。确保在开发环境启用它。持久化对话历史将重要的对话历史保存到数据库或文件便于事后分析和模型优化。性能优化模型并行调用在 Workflow 中对于无依赖的智能体任务使用asyncio或ThreadPoolExecutor实现并行调用减少总等待时间。缓存对于内容不变或变化缓慢的模型请求如知识库查询可以考虑引入缓存机制。轻量级模型在不需要最强能力的环节使用更小、更快的模型如 GPT-3.5-turbo以降低成本和提高响应速度。安全边界输入净化对用户输入进行严格的检查和过滤防止 Prompt 注入攻击避免智能体被诱导执行不当操作。输出审查对智能体生成的内容尤其是对外发布的进行二次审查防止产生有害、偏见或不合规的内容。权限控制在多租户系统中严格隔离不同用户或组织的智能体运行环境和数据。从理解 AgentScope 2.0 的核心概念到完成环境配置和第一个智能体对话从构建线性的代码审查流水线到探索更复杂的 Workflow 编排最后通过 Docker 将应用容器化并部署。这条路径涵盖了从开发到上线的关键环节。多智能体系统的魅力在于通过分工协作解决复杂问题而 AgentScope 为你提供了实现这一愿景的高效工具箱。接下来你可以尝试将更多类型的模型如本地部署的 Llama、DeepSeek集成进来或者设计更精巧的智能体协作模式如辩论、评审、谈判等解锁 AI 应用的更多可能性。