三个月前我还在“智能体到底是什么”这个问题上打转，最近被 AgentScope 2.0 的文档狠狠种草，花了一个周末从零开始搭出了自己的第一个智能体，又把两个 Agent 串成了一个带流程编排的小应用。这篇就是那天从装包到跑通全过程的记录，比较适合零基础但想了解智能体开发、尤其是想搞明白 Agent 编排到底是干嘛的朋友。我会用最直白的代码和步骤带你走一遍，读完你至少能跑出一个真正调用大模型的 Agent，而不是停留在“看过无数概念”的阶段。
1. 为什么需要编排：单 Agent 到多 Agent 的距离
1.1 单 Agent 的真相：模型加提示词
先说个扎心的真相：一个最基础的 Agent，本质就是一套“大模型 + 提示词 + 循环”的壳子。你给它一个任务描述，它调用底层 LLM，拿到结果后返回给你。很多人以为智能体是某种黑魔法，其实拆开看就三层：感知输入、调用模型推理、输出动作。
我一开始犯的错就是把 Agent 想得太神秘。直到自己在 AgentScope 2.0 里用不到十行代码跑出第一个回复，才意识到单个 Agent 的工作方式和“包装好的 ChatGPT API”差不多。区别在于，Agent 通常会有一个明确的角色定义、一段稳定的系统提示词，以及可扩展的工具调用能力，这让它比直接裸调 API 更容易复用在复杂流程里。
你可以把一个单 Agent 想成“一个只干活不抬头看路的实习生”。问他问题，他答得不错；但如果你丢给他一个多步骤任务，他就容易漏步骤、串逻辑，甚至自己发挥出完全不对路的东西。这不是模型笨，而是缺少整套流程的结构性约束。
1.2 多 Agent 协作的复杂度来源
那为什么不干脆让一个 Agent 把所有事情干完？因为现实里的任务往往牵扯多种角色和能力，硬塞给一个 Agent 会让提示词膨胀到失控，而且任何一步出错都很难定位。更常见的做法是拆解：A 负责理解需求，B 负责生成方案，C 负责检查结果，每个 Agent 专职做好一件事。
但拆完以后新的问题就来了：消息格式怎么统一？谁先执行谁后执行？中间某个 Agent 返回了异常结果，整条链路要不要停？后面的 Agent 需要前面几步的哪些信息？这些问题就是“编排”要解决的。
我举个特别常见的例子，翻译加总结。单个 Agent 也可以做，但效果常常是翻译完顺便总结，两个任务互相干扰。拆成“翻译 Agent”和“总结 Agent”之后，翻译结果单独产出，总结 Agent 只针对译文工作，两边职责清晰，哪个环节崩了也好单独修。
1.3 AgentScope 2.0 的答案：编排层
AgentScope 2.0 的核心思路，就是把“智能体应用”拆成几个稳定部件：Agent、消息、Pipeline。Agent 负责单点能力，消息负责在 Agent 之间传递信息，Pipeline 负责决定消息走什么路径、按什么顺序、在什么条件下流转。
这种分层设计最大的好处是开发时可以单独测试每个 Agent。可以把“翻译 Agent”替换成另一家模型的接口，不用动其他代码；也可以把“总结 Agent”挪到另一个 Pipeline 分支里复用。编排层就像一个流水线，你调整的是工位顺序和传送带方向，而不是重新造机器。
我第一次接触这套抽象时觉得有点多余，等真写了一个带条件分支的多 Agent 流程，才意识到如果没有这层“路由逻辑”，我写的就不是业务代码而是到处都是 if else 的屎山了。编排解决的根本问题不是“让 Agent 能对话”，而是“让 Agent 的协作过程可控、可维护、可观测”。
2. 环境准备：先让框架跑起来
2.1 安装：一条命令搞定
AgentScope 2.0 对 Python 版本有要求，官方推荐 3.9 及以上。我本机用的是 Python 3.10，整个过程没遇到版本壁垒。安装非常简单：
pip install agentscope如果你在公司网络环境，或者 PyPI 下载速度很感人，可以加国内镜像源：
pip install agentscope -i https://pypi.tuna.tsinghua.edu.cn/simple装完之后强烈建议先确认一下版本，因为我就是在这里踩了坑：默认源可能装到旧版 1.x，而非 2.0。验证方式：
import agentscope print(agentscope.__version__)我当天第一次打印出来是 0.x 的旧版本号，马上意识到装错了源，换到官方源重新安装后才看到 2.x 的版本号。所以看到这篇记录的朋友，装完先别急着写代码，版本对不上一切都白搭。
2.2 模型接入：没有大模型就没有智能
AgentScope 本身不生产模型，它只是一个调度框架。你需要准备一个可以调用的 LLM 后端。这里我优先选择 DashScope 的通义千问，因为 AgentScope 对自家生态的适配最顺滑。如果你的团队已经买了其他厂商的 API，也没关系，2.0 支持多种模型后端，OpenAI 兼容接口基本是标配。
配置模型的方式是统一的model_configs。我在项目里是这样写的：
import agentscope agentscope.init( model_configs=[ { "model_type": "dashscope_chat", "config_name": "qwen-plus-cfg", "model_name": "qwen-plus", "api_key": "sk-你的密钥", } ] )注意，这里有个实操细节：不要把 API Key 直接写死在代码里，尤其是你要把代码提交到仓库的时候。我习惯用环境变量读取：
import os api_key = os.getenv("DASHSCOPE_API_KEY")关联到 init 配置里。这样既安全，又方便在不同环境间切换。
如果你用的是本地模型，比如 Ollama 起了一个 qwen 模型，那可以把模型配置改成 OpenAI 兼容协议，指向本地端口。具体字段以官方文档为准，代码形态和上面差不多。
2.3 三个必须搞懂的概念：Agent / Msg / Pipeline
在往下写代码之前，我先快速过一遍 AgentScope 2.0 的三个核心概念。理解了这三个词，后面看代码会非常顺。
Agent 是智能体单元。你可以把“翻译员”“总结员”各种角色分别封装成 Agent，每个 Agent 有自己的名字、系统提示词和绑定的模型配置。一个 Agent 最少就是这三样。
Msg 是消息载体。Agent 之间不是直接调用函数传参，而是通过 Msg 对象传递。Msg 通常带着发送者名字、文本内容、角色信息。这个设计保证了整个系统是松耦合的，任何一个 Agent 只需要关心“收到一个消息，返回一个消息”。
Pipeline 是编排层的核心。它决定了 Msg 从哪个 Agent 出发、经过哪些 Agent、是否要分支、是否要并行。你可以把 Pipeline 理解成车间里的传送带，Agent 是工位，Msg 是流动的零件。2.0 在这块做了不少重构，比 1.x 的 msghub 方式更好理解，也更接近“流程可视化”的直觉。
我第一次看文档这三个概念的时候觉得抽象，等真正写完一段代码回头再看，就发现其实非常朴素：Agent 干活，Msg 传话，Pipeline 定路线。
3. 零基础实操：跑通第一个单 Agent 智能体
3.1 最小示例：Hello Agent
理论聊得再多，不如直接跑一段代码。下面这个例子是“零基础跑通第一个智能体”最简版本，你复制到 Python 脚本里，只要 API Key 没问题，基本能一次跑通。
import agentscope from agentscope.agent import DialogAgent from agentscope.message import Msg agentscope.init( model_configs=[ { "model_type": "dashscope_chat", "config_name": "qwen-plus-cfg", "model_name": "qwen-plus", "api_key": "sk-你的密钥", } ] ) assistant = DialogAgent( name="assistant", sys_prompt="你是一个靠谱的助手，回答尽量简洁直接，不要长篇大论。", model_config_name="qwen-plus-cfg", ) user_msg = Msg( name="user", content="你好，请用一句话介绍你自己。", role="user", ) reply = assistant(user_msg) print(reply.content)这段代码的预期输出是一句模型的自我介绍。看到屏幕上打印出自然语言回复，而不是报错堆栈，你的第一个智能体就算正式跑通了。
3.2 逐行拆解这段代码到底做了什么
我们一行一行看。
agentscope.init是初始化入口。它负责加载配置、建立模型连接、准备运行时环境。你后面如果要用到 Studio 之类的调试工具，也是在这里打开开关。
接着导入DialogAgent。这是 AgentScope 内置的一个最常用的 Agent 实现，适合处理多轮对话。你不一定要自己写 Agent 类，很多场景可以直接拿来用，改名字和提示词就行。
实例化 Assistant 的时候，三个参数值得认真对待：name是这个 Agent 在系统里的身份标识，后续消息流转都会用到；sys_prompt是给这个 Agent 定的“人设”，直接影响回复质量；model_config_name指向你在 init 里配置的那个模型。
然后是Msg。这里我创建了一条来自 user 的消息。注意role字段，它告诉系统这条消息是用户发的。Agent 收到 Msg 后会在内部拼装上下文，然后调用模型推理。
最后一行assistant(user_msg)是这个 Agent 的入口方法。Agent 这种“可调用对象”的设计用起来很顺手，传入 Msg，返回新的 Msg，完全符合前面说的消息流转逻辑。reply是一个 Msg 对象，里面的content才是模型生成的文本。
3.3 运行与调试：看到什么算真正成功
我第一次跑这段代码，其实没有顺利。遇到的第一个问题是 api_key 写错，报了个认证错误，我盯着错误信息看了十分钟才意识到是复制密钥时多了个空格。这里提醒大家，密钥别手打，直接复制粘贴，注意首尾空格。
第二个问题是“没有任何输出”。原因是我把print(reply.content)写成了print(reply)，打印出来的是一大串消息对象的元信息，里面确实有内容但被包装在结构里，看着像报错。如果你也看到类似一串带name和role字段的字典样式输出，别慌，改成.content再打印。
如果代码跑通了，我想让你额外做一件事：在agentscope.init里打开调试或 Studio 相关配置，去可视化界面里看看消息是怎么流转的。AgentScope 2.0 在可观测性上做得不错，你能直观看到当前 Agent 收到了什么、模型返回了什么、耗时多少。我后续调多 Agent 流程时，这个面板帮我省了太多事。
4. 进阶编排：让两个 Agent 协作起来
4.1 最简单的双 Agent 协作：翻译加总结
单 Agent 跑通之后，真正的重头戏是编排。我选了一个最容易上手的场景：翻译加总结。用户输入一段英文技术文档，第一个 Agent 负责翻译成中文，第二个 Agent 负责从译文里提取三个核心要点。
之所以选这个场景，是因为它的依赖关系非常清晰：总结必须发生在翻译之后，天然适合串行编排。你不需要处理并行、投票、兜底这些复杂逻辑，能把“前一个 Agent 的输出变成后一个 Agent 的输入”这件事跑通，编排的主干就算学会了。
为了讲清楚编排原理，我先用最朴素的 Python 代码串起两个 Agent，不用框架提供的 Pipeline API。这样的好处是你先理解调度逻辑本身，再去看官方提供的高级封装，视角会非常通透。
4.2 Pipeline 串行编排实现：用最朴素的循环先跑通
下面是双 Agent 协作的完整代码。我在代码里保留了详细注释，方便你对照理解。
import agentscope from agentscope.agent import DialogAgent from agentscope.message import Msg agentscope.init( model_configs=[ { "model_type": "dashscope_chat", "config_name": "qwen-plus-cfg", "model_name": "qwen-plus", "api_key": "sk-你的密钥", } ] ) # 翻译 Agent translator = DialogAgent( name="translator", sys_prompt="你是一名专业的技术文档翻译。把用户输入的英文翻译成中文，不要额外解释。", model_config_name="qwen-plus-cfg", ) # 总结 Agent summarizer = DialogAgent( name="summarizer", sys_prompt="你是一名技术编辑。从用户提供的中文文本中提取三个核心要点，用简洁的列表形式输出。", model_config_name="qwen-plus-cfg", ) input_msg = Msg( name="user", content="Agent orchestration is the process of coordinating multiple AI agents to complete complex tasks.", role="user", ) # 第一步：翻译 translated = translator(input_msg) # 第二步：把翻译结果作为总结 Agent 的输入 summary = summarizer(translated) print("翻译结果：") print(translated.content) print("\n核心要点：") print(summary.content)这段代码的关键在倒数第二行：summarizer(translated)。我们把翻译 Agent 返回的 Msg 直接传给总结 Agent。Msg 对象里既包含翻译后的文本，也带着来源信息，总结 Agent 能正常解析并生成新消息。
我在实际运行中观察到，两个 Agent 的输出质量都挺稳定。翻译 Agent 规规矩矩地给出中文译文，总结 Agent 基于译文提炼要点，没有出现“两个 Agent 抢话”的问题。这就是消息封装的好处：每个 Agent 都在处理一个明确的消息对象，而不是去访问一堆全局变量。
4.3 加一个条件分支：让编排更智能
串行流程跑通后，我开始尝试条件分支。场景是这样：用户提了一个问题，我先让一个轻量分类 Agent 判断问题是否和代码相关，再根据判断结果路由到“代码专家 Agent”或“通用助手 Agent”。
这个模式在实际业务里非常常见，本质上就是智能客服分流。实现思路其实不复杂：分类 Agent 返回一个关键词或标签，主流程用 if 判断走哪条分支。
router = DialogAgent( name="router", sys_prompt="""你是一个问题分类器。只能回答两个词：code 或 general。 如果用户问题涉及写代码、排查代码报错、算法逻辑，回答 code； 其他问题一律回答 general。""", model_config_name="qwen-plus-cfg", ) code_expert = DialogAgent( name="code_expert", sys_prompt="你是资深程序员，擅长给出简洁可运行的代码示例。", model_config_name="qwen-plus-cfg", ) general_assistant = DialogAgent( name="general_assistant", sys_prompt="你是通用助手，回答日常问题。", model_config_name="qwen-plus-cfg", ) question = Msg( name="user", content="Python 里怎么把列表里的元素去重并保持顺序？", role="user", ) route_result = router(question).content.strip().lower() if "code" in route_result: final_answer = code_expert(question) else: final_answer = general_assistant(question) print(final_answer.content)分类 Agent 的提示词我特意设计成只输出固定词，这样后续判断非常可靠。实际使用中你会发现，只要给模型限定输出格式，分支路由的稳定性很高。但也有翻车的时候，后面“常见问题”部分我会细说。
这段代码没有用到 Pipeline 的高级 API，但已经构成了最基础的编排骨架：消息在多个 Agent 间流转，主干流程根据中间结果做决策。理解了这一点，再去看框架提供的 Pipeline 各种模式，你会觉得非常亲切。
5. 常见问题与排查技巧实录
5.1 安装失败或版本不对：先看版本再查别的
安装阶段最常见的坑就是我前面提到的版本问题。很多人以为自己装的是 2.0，跑起来才发现 import 的接口不存在，折腾半天。
我的排查顺序一般是：
- 用
pip show agentscope查看当前版本； - 用
python -c "import agentscope; print(agentscope.__version__)"确认运行时版本； - 如果版本不对，先卸载再重装，指定版本号安装，例如
pip install agentscope==2.0.x； - 遇到依赖冲突，建议新建虚拟环境，一个项目一个环境，别图省事全堆系统里。
还有一次我在 Windows 上安装遇到编译错误，后来发现是 Python 版本太老。升级到 3.10 之后问题消失。建议直接用 3.10 或 3.11，兼容性最稳。
5.2 模型 API 调用报错：先拆消息再查密钥
模型调用报错的类型五花八门，我遇到最多的是这几种：
- 401 认证错误：api_key 不对，检查有没有多余空格、有没有把占位符“sk-你的密钥”直接提交；
- 404 模型不存在：model_name 写错了，去模型平台控制台确认你开通了哪个模型；
- 超时或限流：某些时段模型服务繁忙，代码里建议加重试，或者换
qwen-turbo这类响应更快的轻量模型调试。
调试模型调用有个小技巧：先用官方提供的极简 API 请求脚本测通模型本身，再接入 AgentScope。这样能把“模型配置问题”和“框架使用问题”隔离开。我调试的时候就是先直接用 DashScope 的 SDK 发了一条请求，确认密钥和模型名都正确，再回头查 AgentScope 的配置格式。
5.3 编排死循环或结果为空：检查终止条件
多 Agent 编排里最怕的就是死循环。尤其是你在自定义 Agent 协作流程时，如果 Agent A 的输出永远触发 Agent B 继续回答，而 B 的输出又永远触发 A，程序就卡死了。
我在实验阶段遇到过两次，原因都是终止条件不明确。解决思路有几种：
- 设置最大轮数，比如最多交互 3 次强制退出；
- 约定结束标记，让 Agent 在任务完成时输出特定字符串，主流程检测到就 break；
- 减少自由对话，用明确的 Pipeline 阶段控制，而不是让两个 Agent 无限制对话。
另一个让我困惑的问题是“结果为空但没报错”。后来发现是 Agent 返回的 Msg 里 content 字段是空字符串，可能是因为模型输出被提示词里的格式要求吞掉了。处理方式是检查返回内容，如果为空则重试一次，或者在提示词里强调“必须输出正文”。
5.4 编排结果质量差：问题多半在提示词不在框架
很多初学者一出问题就怀疑框架不行，其实大部分质量问题是提示词设计不到位。我踩过的教训是：AgentScope 2.0 再会编排，也不能替你想清楚每个 Agent 的职责边界。
我的提示词写作套路是：角色 + 任务边界 + 输出格式 + 反例约束。比如翻译 Agent 的提示词里会写“不要解释，不要额外发表意见”；分类 Agent 的提示词里会写“只能回答 code 或 general，不能输出其他内容”。这些约束看着简单，但对模型输出稳定性提升非常明显。
如果多个 Agent 协作时结果经常不一致，可以在单 Agent 层面先多加几轮测试。把每个 Agent 单独拎出来喂不同输入，观察输出是否符合预期。单个 Agent 都稳定了，编排层才可能稳定。
我还发现温度参数对编排稳定性影响很大。需要固定格式输出的分类 Agent，温度调低一些；需要创造性内容的生成 Agent，温度可以稍高。AgentScope 在模型配置里一般都支持传这些生成参数，值得按场景调一调。
5.5 前后消息上下文互相污染：注意 Msg 传递范围
这个问题比较隐蔽。在我自己的多 Agent 流程里，最初我把所有历史消息都传给每个 Agent，结果翻译 Agent 会看到总结 Agent 的消息，导致输出带着上一站的“记忆”，非常混乱。
解决办法是控制每个 Agent 接收的消息范围。该传的传，不该传的坚决不传。在 Pipeline 设计里，你可以决定每个阶段输入哪些消息，而不是把所有内容一股脑全塞进去。这就好比流水线上每个工位只需要面前的零件，不必知道整条产线的全部秘密。
6. 我的实操体会与后续打算
这篇文章里的代码虽然短，但每一个模块我都是实际运行过的。从零开始到跑通多 Agent 编排，最大的感受是 AgentScope 2.0 把智能体开发的门槛拉低了不少，你不用自己造消息队列、不用手搓并发，只要你把 Agent 的职责和流转逻辑想清楚，框架能把剩下的脏活扛起来。
我个人后续想往这几个方向继续折腾：一是给 Agent 挂上外部工具，让它能查数据库、调搜索引擎，这样就不只是“对话型选手”了；二是试试 AgentScope 2.0 里更复杂的 Pipeline 并行模式，让多个 Agent 同时处理不同任务再汇总；三是尝试接入本地部署的小模型，跑一套纯离线方案。每一个方向如果跑通了，我都会继续整理成笔记发出来。
最后分享一个我调 Agent 时一直在用的习惯：凡是 Agent 相关的提示词，我都单独放在一个配置文件里，不硬编码在业务代码中。因为后续你会频繁调整提示词，如果散落在代码里，改一个字的代价是重新排查整个文件；集中管理之后，改提示词就是改配置，甚至可以让非开发同学一起参与优化。这条经验看似简单，但在我这几天的实操里，帮我省下的时间比想象中多得多。
