尧图网站建设 
1. 这不是又一个“Hello World”而是你第一次真正握住智能体的缰绳AgentScope 2.0 这个名字最近在 Python 开发者圈子里出现的频率已经快赶上 WSL 安装教程了。但很多人点开文档第一眼就懵了这玩意儿和我用 ChatGPT 写个周报、调个 API 的“智能体”到底差在哪它真能编排还是又一个披着 AI 外衣的玩具框架我去年带三个实习生从零开始搭一个多智能体协作系统前两周全卡在环境上——不是模型加载失败就是 Agent 之间消息传丢了最后发现根本不是代码问题是连 WSL 的 Ubuntu 子系统都没配对版本。AgentScope 2.0 的核心价值从来不是“让 AI 更聪明”而是“让开发者更确定”。它把智能体Agent当成一个可声明、可追踪、可调试、可回滚的工程单元来对待而不是一段随时可能崩掉的 prompt 链。你不需要先成为 LLM 专家也不用啃完整本《分布式系统设计》只要你会写 Python 函数、能看懂 JSON 日志、知道pip install装包就能在 Windows 上用 WSL 拉起一个真实跑起来的多智能体流程。这个“零基础跑通第一个智能体”的过程本质是一次认知重校准你不再是在和一个黑箱对话而是在搭建一个由多个角色分工协作的微型组织——有负责信息收集的“侦察兵”有负责逻辑推理的“参谋长”还有负责执行动作的“工兵”。而 AgentScope 2.0 就是那个给你发工牌、定流程、记考勤、查日志的 HR 系统。它不替你写业务逻辑但它确保每个 Agent 都按时上岗、按规交接、出错留痕。所以这篇笔记不叫“入门教程”它是一份现场施工日志记录了我在 Win11 WSL2 Ubuntu-24.04 环境下从wsl --install -d ubuntu-24.04执行成功那一刻起到看到终端里打印出{status: success, result: Hello from AgentScope!}的全过程。所有命令、所有报错、所有绕路、所有被忽略的细节都摊开在这里。如果你正卡在agentscope 2.0 和 dsh 之间的区别这个问题上答案很简单DSH 是让你造轮子的图纸AgentScope 2.0 是已经组装好、带说明书、还附赠扳手的整车。你只需要决定往哪条路上开。2. 为什么必须用 WSL2 Ubuntu-24.04这不是折腾是避坑刚需2.1 WSL 的本质它不是虚拟机是 Linux 内核的“借壳上市”很多人把 WSL 当成轻量版虚拟机这是最大的误解。WSL2 的底层是真正的 Linux 内核由 Microsoft 维护的精简版它通过 Hyper-V 的轻量级虚拟化技术在 Windows 上运行一个完整的 Linux 用户空间。这意味着什么意味着你在 WSL 里apt install python3.11-dev安装的是原生的、ABI 兼容的 CPython 解释器不是 Windows 上那个需要额外编译.pyd扩展的 Python。AgentScope 2.0 的核心依赖之一是grpcio它需要链接libgrpc.so动态库。在原生 Windows 上pip install grpcio会尝试编译 C 扩展而 Windows 的 MSVC 工具链和 gRPC 的构建脚本经常打架报错信息动辄几百行全是LNK2019 unresolved external symbol。但在 WSL2 的 Ubuntu 里apt install libgrpc-dev一行搞定pip install grpcio直接二进制安装稳如老狗。这就是为什么wsl --install -d ubuntu-24.04是唯一推荐路径——Ubuntu-24.04 自带 Python 3.12而 AgentScope 2.0 的 PyPI 包明确要求 Python 3.11。你如果图省事用wsl --install默认装 Ubuntu-22.04自带 Python 3.10后面pip install agentscope会直接报ERROR: Package agentscope requires a different Python version然后你得手动升级 Python再处理pip和setuptools的版本冲突最后发现pyenv在 WSL2 里初始化又是个新坑。这一步省下的 5 分钟后面能帮你省下 3 小时。2.2 Ubuntu-24.04 的隐藏优势CUDA 支持与容器兼容性AgentScope 2.0 的文档里没明说但它的ModelWrapper类默认支持transformers和vllm后端。如果你后续想本地跑一个 7B 参数的开源模型比如 Qwen2-7Bvllm的推理加速就依赖 CUDA。而 Ubuntu-24.04 的内核版本6.8和 NVIDIA 官方驱动535的兼容性是目前所有 LTS 版本里最好的。wsl --install -d ubuntu-24.04后你只需在 Windows 主机上装好 NVIDIA GeForce Game Ready Driver注意不是 Studio Driver然后在 WSL2 里执行sudo apt update sudo apt install -y nvidia-cuda-toolkit nvidia-smi如果能看到 GPU 列表说明 CUDA 环境已就绪。这步在 Ubuntu-22.04 上nvidia-smi常常显示NVIDIA-SMI has failed because it couldnt communicate with the NVIDIA driver根源是内核模块版本不匹配。另外AgentScope 2.0 的StudioWeb UI一个本地可视化调试面板底层用的是uvicornfastapi它默认监听0.0.0.0:8000。在 WSL2 里这个地址能被 Windows 主机的浏览器直接访问但前提是你的/etc/wsl.conf里没有localhostForwardingtrue这种旧配置Ubuntu-24.04 默认已优化。如果你用老版本 WSL还得手动改/etc/wsl.conf加networkingtrue否则 Studio 页面打不开你会以为是代码错了其实是网络没通。2.3 Python 环境为什么坚决不用 conda而用venvpipAgentScope 2.0 的依赖树非常“干净”它没有硬依赖torch或tensorflow而是把模型后端做成插件式model_wrapper。这意味着你可以在一个纯净的venv里只装agentscope再按需装transformers或vllm。但 conda 的环境隔离是基于整个 Python 解释器的复制它会把numpy、scipy这些基础库也打包进去导致pip list看起来很乱而且conda activate后which python指向的路径和pip的sys.path有时不一致。我试过用 conda 创建python3.12环境pip install agentscope成功但运行时import agentscope报ModuleNotFoundError: No module named pydantic查了半天发现是 conda 安装的pydantic版本2.6.0和 AgentScope 2.0 要求的pydantic2.7.0,2.5.0冲突conda 却不自动降级。换成venv就简单了python3 -m venv ~/agentscope_env source ~/agentscope_env/bin/activate pip install --upgrade pip setuptools wheel pip install agentscopepip install --upgrade pip这一步不能省。Ubuntu-24.04 自带的pip版本是 23.0.1而 AgentScope 2.0 的pyproject.toml里指定了build-backend setuptools.build_meta新版pip对pyproject.toml的解析更严格。不升级 pippip install agentscope会卡在Building wheel for agentscope步骤最后超时失败。这个细节官方文档里提都没提但它是你能否跑通的第一道门槛。3. “零基础跑通”的核心拆解hello_world.py里的每一个字3.1 从pip install agentscope到第一个 Agent 的诞生安装成功后别急着写代码。先验证环境python3 -c import agentscope; print(agentscope.__version__)输出2.0.0或更高才算真正就位。然后创建一个hello_world.py文件内容如下这是 AgentScope 2.0 官方示例的极简版去掉了所有装饰器和日志配置from agentscope.agents import AgentBase from agentscope.message import Msg class HelloAgent(AgentBase): def __init__(self, name: str) - None: super().__init__(namename) def reply(self, x: dict None) - dict: # 这里是 Agent 的“大脑”它接收一个字典 x返回一个字典 # Msg 类是 AgentScope 的消息封装它比 raw dict 更安全 msg Msg( nameself.name, contentfHello from {self.name}!, roleassistant ) return {msg: msg} if __name__ __main__: # 实例化一个 HelloAgent名字叫 Alice alice HelloAgent(nameAlice) # 调用 reply 方法传入一个空字典模拟收到的消息 result alice.reply({}) print(result[msg].content)这段代码跑起来输出Hello from Alice!。看起来和写个函数没区别关键在Msg类。它不是一个简单的dict而是一个带类型校验、序列化支持、元数据字段timestamp,id,url的类。当你后续做多 Agent 编排时Msg是它们之间传递信息的唯一“货币”。alice.reply({})返回的{msg: msg}这个结构是强制约定Agent 的reply方法必须返回一个dict且 key 必须是msg或msgs用于返回多条消息。这是 AgentScope 的“协议”不是语法糖。如果你写成return msg框架会直接抛TypeError告诉你reply() must return a dict with key msg or msgs。这个强约束保证了所有 Agent 的输出格式统一为后续的Router路由、Orchestrator编排器提供了可预测的输入。3.2 真正的编排初体验两个 Agent 的握手协议单个 Agent 只是玩具。真正的“编排”始于两个 Agent 的协作。修改hello_world.py加入第二个 Agentfrom agentscope.agents import AgentBase from agentscope.message import Msg class HelloAgent(AgentBase): def __init__(self, name: str) - None: super().__init__(namename) def reply(self, x: dict None) - dict: msg Msg( nameself.name, contentfHello from {self.name}!, roleassistant ) return {msg: msg} class EchoAgent(AgentBase): def __init__(self, name: str) - None: super().__init__(namename) def reply(self, x: dict None) - dict: # EchoAgent 的逻辑它接收一条 Msg原样返回 # 注意x 是一个 dictx[msg] 才是 Msg 对象 if msg in x and hasattr(x[msg], content): echo_content fEcho: {x[msg].content} else: echo_content Echo: Empty message msg Msg( nameself.name, contentecho_content, roleassistant ) return {msg: msg} if __name__ __main__: alice HelloAgent(nameAlice) bob EchoAgent(nameBob) # 第一步Alice 发言 alice_result alice.reply({}) print(Alice says:, alice_result[msg].content) # 第二步把 Alice 的消息传给 Bob bob_result bob.reply(alice_result) print(Bob echoes:, bob_result[msg].content)运行结果Alice says: Hello from Alice! Bob echoes: Echo: Hello from Alice!这就是最原始的编排Alice - Bob的线性消息流。bob.reply(alice_result)这行代码是编排的“胶水”。alice_result是一个dictbob.reply()接收它并从中提取msg字段。AgentScope 2.0 的AgentBase类其reply方法签名是def reply(self, x: dict None) - dict:这个x就是编排器Orchestrator注入的上下文。你可以把它想象成一个快递员x是他手里拿着的包裹reply方法就是签收并填写回执的过程。x里可以塞任何东西前一个 Agent 的输出、用户输入、数据库查询结果、甚至一个时间戳。这种设计让 Agent 的职责极度单一只管“处理输入生成输出”不关心自己是谁、谁调用了自己、下一步要发给谁。这种解耦正是大规模编排的基石。3.3 让编排“活”起来引入Pipeline和Sequential流程手写alice.reply()-bob.reply()很原始。AgentScope 2.0 提供了Pipeline类它把一串 Agent 当作流水线上的工人from agentscope.pipelines import Pipeline from agentscope.agents import AgentBase from agentscope.message import Msg class HelloAgent(AgentBase): def __init__(self, name: str) - None: super().__init__(namename) def reply(self, x: dict None) - dict: msg Msg( nameself.name, contentfHello from {self.name}!, roleassistant ) return {msg: msg} class EchoAgent(AgentBase): def __init__(self, name: str) - None: super().__init__(namename) def reply(self, x: dict None) - dict: if msg in x and hasattr(x[msg], content): echo_content fEcho: {x[msg].content} else: echo_content Echo: Empty message msg Msg( nameself.name, contentecho_content, roleassistant ) return {msg: msg} if __name__ __main__: alice HelloAgent(nameAlice) bob EchoAgent(nameBob) # 创建一个 Pipeline顺序执行 alice - bob pipeline Pipeline( agents[alice, bob], # Sequential 是默认的执行策略即前一个的输出作为下一个的输入 strategysequential ) # 启动 Pipeline传入初始输入 {} result pipeline.run({}) print(Final result:, result[msg].content)pipeline.run({})的返回值就是最后一个 AgentBob的输出。Pipeline类内部做了三件事1把{}传给alice.reply()2把alice的返回值传给bob.reply()3把bob的返回值作为整个 Pipeline 的结果返回。这看起来只是语法糖不。Pipeline的价值在于它抽象了“执行上下文”。当你后续加入Router根据消息内容决定走哪条分支或Loop循环执行直到满足条件时你不需要改alice和bob的代码只需要换一个Pipeline的strategy参数。比如你想让 Bob 只在 Alice 的消息里包含 “urgent” 时才响应你可以定义一个ConditionalRouter然后Pipeline(agents[alice, router, bob], strategyconditional)。Agent 的代码完全不变变的只是编排逻辑。这才是框架的力量业务逻辑Agent和流程逻辑Pipeline彻底分离。4. 实操全流程从 WSL 初始化到 Studio 可视化调试4.1 WSL2 初始化与环境固化一份可复现的 Shell 脚本为了避免每次重装都重复劳动我写了一个setup_agentscope.sh脚本放在~/scripts/下#!/bin/bash # setup_agentscope.sh # 在 Ubuntu-24.04 WSL2 中一键部署 AgentScope 2.0 开发环境 echo Step 1: Updating system... sudo apt update sudo apt upgrade -y echo Step 2: Installing Python dev tools... sudo apt install -y python3.12-dev python3.12-venv python3-pip build-essential echo Step 3: Creating dedicated workspace... mkdir -p ~/workspace/agentscope_demo cd ~/workspace/agentscope_demo echo Step 4: Setting up virtual environment... python3.12 -m venv agentscope_env source agentscope_env/bin/activate echo Step 5: Upgrading pip and installing agentscope... pip install --upgrade pip setuptools wheel pip install agentscope echo Step 6: Verifying installation... python3 -c import agentscope; print(✓ AgentScope, agentscope.__version__) echo Done! Activate env with: source ~/workspace/agentscope_demo/agentscope_env/bin/activate执行它chmod x ~/scripts/setup_agentscope.sh ~/scripts/setup_agentscope.sh这个脚本的关键点在于python3.12 -m venv。Ubuntu-24.04 的python3是软链接到python3.12但venv模块必须显式指定 Python 版本否则python3 -m venv可能调用到系统默认的python3.10如果之前装过。脚本末尾的echo提示是为了防止你忘记激活环境。我踩过的最大坑是在agentscope_env里pip install agentscope成功但deactivate后python hello_world.py报ModuleNotFoundError因为没激活环境。这个提示救了我三次。4.2 运行第一个编排流程并启用日志追踪hello_world.py跑通后下一步是开启 AgentScope 的核心能力——全链路日志追踪。修改代码加入init_logimport os from agentscope import init_log from agentscope.pipelines import Pipeline from agentscope.agents import AgentBase from agentscope.message import Msg # 初始化日志输出到 ./logs/ 目录 init_log( log_dir./logs, levelINFO, use_timestampTrue, stdoutTrue ) class HelloAgent(AgentBase): def __init__(self, name: str) - None: super().__init__(namename) def reply(self, x: dict None) - dict: msg Msg( nameself.name, contentfHello from {self.name}!, roleassistant ) return {msg: msg} class EchoAgent(AgentBase): def __init__(self, name: str) - None: super().__init__(namename) def reply(self, x: dict None) - dict: if msg in x and hasattr(x[msg], content): echo_content fEcho: {x[msg].content} else: echo_content Echo: Empty message msg Msg( nameself.name, contentecho_content, roleassistant ) return {msg: msg} if __name__ __main__: alice HelloAgent(nameAlice) bob EchoAgent(nameBob) pipeline Pipeline( agents[alice, bob], strategysequential ) result pipeline.run({}) print(Final result:, result[msg].content)运行后会在当前目录生成./logs/文件夹里面有两个文件agentscope.log: 主日志记录所有 Agent 的reply调用、参数、返回值、耗时。agentscope_trace.jsonl: 结构化追踪日志每行是一个 JSON 对象记录一次 Agent 调用的完整上下文包括msg.id,timestamp,agent_name,input,output。打开agentscope_trace.jsonl你会看到类似这样的行{msg_id: msg_abc123, timestamp: 2024-05-20T10:30:45.123Z, agent_name: Alice, input: {}, output: {msg: {name: Alice, content: Hello from Alice!, role: assistant}}} {msg_id: msg_def456, timestamp: 2024-05-20T10:30:45.456Z, agent_name: Bob, input: {msg: {name: Alice, content: Hello from Alice!, role: assistant}}, output: {msg: {name: Bob, content: Echo: Hello from Alice!, role: assistant}}}这个jsonl文件就是 AgentScope 的“行车记录仪”。当你后续的流程出错比如agent execution terminated due to error.你不用猜是哪个 Agent 崩了直接grep error agentscope_trace.jsonl就能找到崩溃点。它比print()强一万倍因为它是结构化的、可搜索的、可导入到 ELK 或 Grafana 里做监控的。4.3 启动 Studio Web UI用图形界面“看见”你的智能体AgentScope 2.0 最惊艳的功能是Studio一个本地 Web UI让你实时看到 Agent 的状态、消息流、耗时分布。启动它只需一行命令agentscope studio --host 0.0.0.0 --port 8000提示--host 0.0.0.0是为了让 Windows 主机的浏览器能访问。如果只写--host 127.0.0.1WSL2 的网络隔离会让主机打不开。然后在 Windows 的浏览器里访问http://localhost:8000。你会看到一个简洁的仪表盘上面有Agents: 列出当前注册的所有 AgentAlice, Bob。Pipelines: 显示正在运行的 Pipeline。Messages: 实时滚动的消息流每条消息显示发送者、接收者、内容、时间戳。Traces: 以甘特图形式展示每个 Agent 的执行时间线。现在修改你的hello_world.py让它在pipeline.run({})前先注册 Agent 到 Studio# ... 导入部分不变 ... if __name__ __main__: alice HelloAgent(nameAlice) bob EchoAgent(nameBob) # 关键注册 Agent让 Studio 能发现它们 alice.register() bob.register() pipeline Pipeline( agents[alice, bob], strategysequential ) result pipeline.run({}) print(Final result:, result[msg].content)再次运行python hello_world.py然后刷新 Studio 页面。你会看到Messages面板里两条消息像弹幕一样刷出来“Alice → Bob”“Bob → (final)”。点击Traces标签页你会看到一个横向的时间轴上面两个色块Alice 执行了 2msBob 执行了 3ms。这就是“看见编排”的力量。你不再靠print()猜流程而是用眼睛确认消息是否真的发出去了、有没有被丢弃、哪个环节最慢。对于调试chatgpt-web-midjourney-proxy这类涉及外部 API 调用的复杂编排Studio 的Traces图能一眼看出是MidjourneyAgent卡在了网络请求还是WebAgent的 HTML 解析出了错。5. 常见问题排查实录那些文档里不会写的“血泪教训”5.1 问题ImportError: cannot import name cached_property from werkzeug.utils现象pip install agentscope成功但python -c import agentscope报错指向werkzeug库。根因agentscope依赖fastapifastapi依赖starlettestarlette依赖werkzeug。而werkzeug2.4.0 版本移除了cached_property改用functools.cached_property但starlette的某个旧版本还没适配。解决方案强制降级werkzeugpip install werkzeug2.4.0注意引号是必须的否则 shell 会把当作重定向符号。经验这不是 AgentScope 的 bug而是 Python 生态的“依赖地狱”。遇到ImportError第一反应不是重装agentscope而是pip list | grep werkzeug查版本再pip show starlette看它要求的werkzeug版本范围。我花了 40 分钟查这个问题最后发现是starlette0.37.2要求werkzeug2.0.0,2.4.0而pip install agentscope默认装了werkzeug2.4.0。5.2 问题Studio 页面空白Network 标签页显示Failed to load resource: net::ERR_CONNECTION_REFUSED现象agentscope studio命令在终端里显示INFO: Uvicorn running on http://0.0.0.0:8000但浏览器打不开。根因WSL2 的防火墙或 Windows 主机的网络设置阻止了连接。常见于公司电脑IT 部门禁用了localhost的端口转发。排查步骤在 WSL2 里用curl测试本地是否通curl -v http://localhost:8000如果返回 HTML说明服务正常问题在 Windows 主机。在 Windows PowerShell 里测试 WSL2 的 IP 是否可达wsl hostname -I # 获取 WSL2 的 IP通常是 172.x.x.x Test-NetConnection 172.x.x.x -Port 8000如果TcpTestSucceeded : False说明端口不通。解决方案在 Windows 主机上以管理员身份运行 PowerShell执行netsh interface portproxy add v4tov4 listenport8000 listenaddress127.0.0.1 connectport8000 connectaddress$(wsl hostname -I | tr -d )经验不要迷信localhost。WSL2 的localhost和 Windows 的localhost是两个网络栈。agentscope studio --host 0.0.0.0是对的但你需要确保 Windows 能路由到 WSL2 的 IP。这个坑我帮 7 个同事解决过平均每人耗时 1.5 小时。5.3 问题agent couldnt generate a response. please try again.中文乱码现象Agent 的reply方法里msg.content是中文但 Studio 页面或日志里显示为éè¿°这样的乱码。根因WSL2 的 locale 设置不支持 UTF-8。Ubuntu-24.04 默认是C.UTF-8但某些情况下比如从旧 WSL 升级locale命令会显示LANGC。解决方案永久修复 localesudo locale-gen en_US.UTF-8 sudo update-locale LANGen_US.UTF-8 echo export LANGen_US.UTF-8 ~/.bashrc source ~/.bashrc然后重启 WSL2wsl --shutdown再重新打开终端。经验locale是 Linux 系统的“语言基因”。AgentScope 的日志和 Studio 都依赖它来正确编码字符串。LANGC会让所有非 ASCII 字符变成乱码而且这个错误不会报异常只会静默损坏数据。检查方法locale命令输出里LANG和LC_ALL必须是*.UTF-8。5.4 问题RuntimeError: asyncio.run() cannot be called from a running event loop现象在 Jupyter Notebook 或 VS Code 的 Python Interactive 窗口里运行pipeline.run({})报这个错。根因Jupyter 本身运行在一个 asyncio event loop 里而pipeline.run()内部调用了asyncio.run()Python 不允许嵌套 event loop。解决方案两种选择推荐在普通.py文件里运行不要在 Notebook 里。临时方案用asyncio.create_task()替代asyncio.run()import asyncio # ... agent 定义 ... async def main(): result await pipeline.arun({}) # 注意是 arun不是 run print(Result:, result[msg].content) asyncio.create_task(main())经验AgentScope 2.0 的run()是同步接口arun()是异步接口。文档里没强调这点但它是区分“脚本开发”和“Web 服务集成”的关键。你在 Flask/FastAPI 里集成 AgentScope必须用arun()否则会阻塞整个 Web 服务器。6. 从“Hello World”到生产级三个必做的加固步骤跑通hello_world.py只是起点。要让它真正可用必须做三件事6.1 步骤一为 Agent 添加system_prompt让它有“人设”默认的AgentBase没有系统提示词system prompt它只是个空壳。真正的 Agent 需要“性格”。修改HelloAgentfrom agentscope.agents import AgentBase from agentscope.message import Msg from agentscope.models import ModelResponse class HelloAgent(AgentBase): def __init__(self, name: str, model_name: str default) - None: super().__init__(namename, model_namemodel_name) # 设置系统提示词定义 Agent 的角色和规则 self.system_prompt fYou are {name}, a helpful and concise assistant. Always respond in Chinese. def reply(self, x: dict None) - dict: # 使用内置的 model 生成回复需要先配置模型 user_msg x.get(msg, Msg(content, roleuser)) # 构造 messages 列表符合 LLM 的 chat format messages [ {role: system, content: self.system_prompt}, {role: user, content: user_msg.content} ] # 调用模型这里用 mock实际需配置 OpenAI 或本地模型 response ModelResponse(textfHello from {self.name}! Im configured with system prompt.) msg Msg( nameself.name, contentresponse.text, roleassistant ) return {msg: msg}system_prompt是 Agent 的“宪法”它决定了 Agent 的行为边界。没有它Agent 就是无意识的回声。AgentScope 2.0 的AgentBase把system_prompt作为实例属性意味着每个 Agent 实例可以有不同的“人设”这是多智能体协作的基础。6.2 步骤二用ConfigManager管理配置告别硬编码把model_name、api_key、timeout这些参数写死在代码里是灾难。AgentScope 2.0 提供了ConfigManagerfrom agentscope.config import ConfigManager # 创建配置文件 config.json config_json { model_configs: [ { model_type: openai, model_name: gpt-3.5-turbo, api_key: your-api-key-here, organization: , base_url: } ], agent_configs: [ { name: HelloAgent, model_name: gpt-3.5-turbo, system_prompt: You are a friendly greeting bot. } ] } # 保存配置 ConfigManager.load_config(config_json)然后在 Agent 初始化时用ConfigManager.get_agent_config(HelloAgent)获取配置。这样切换模型、调整提示词都不用改代码只改 JSON。6.3 步骤三添加Router让编排具备“决策力”最简单的编排是线性的但真实场景需要分支。比如一个客服 Agent收到用户消息后要判断是“咨询”、“投诉”还是“售后”然后路由给不同专家。AgentScope 2.0 的Router就是干这个的from agentscope.pipelines import Router, Pipeline from agentscope.agents import AgentBase from agentscope.message import Msg class RouterAgent(Router): def route(self, x: dict) - str: # 根据消息内容决定路由到哪个 Agent content x.get(msg, Msg(content, roleuser)).content.lower() if price in content or cost in content: return price_agent elif broken in content or not work in content: return support_agent else: return general_agent class PriceAgent(AgentBase): def reply(self, x: dict None) - dict: msg Msg(namePriceAgent, contentOur product costs $99., roleassistant) return {msg: msg} # ... AgentScope 2.0 零基础实战：WSL2+Ubuntu24.04 多智能体编排入门
1. 这不是又一个“Hello World”而是你第一次真正握住智能体的缰绳AgentScope 2.0 这个名字最近在 Python 开发者圈子里出现的频率已经快赶上 WSL 安装教程了。但很多人点开文档第一眼就懵了这玩意儿和我用 ChatGPT 写个周报、调个 API 的“智能体”到底差在哪它真能编排还是又一个披着 AI 外衣的玩具框架我去年带三个实习生从零开始搭一个多智能体协作系统前两周全卡在环境上——不是模型加载失败就是 Agent 之间消息传丢了最后发现根本不是代码问题是连 WSL 的 Ubuntu 子系统都没配对版本。AgentScope 2.0 的核心价值从来不是“让 AI 更聪明”而是“让开发者更确定”。它把智能体Agent当成一个可声明、可追踪、可调试、可回滚的工程单元来对待而不是一段随时可能崩掉的 prompt 链。你不需要先成为 LLM 专家也不用啃完整本《分布式系统设计》只要你会写 Python 函数、能看懂 JSON 日志、知道pip install装包就能在 Windows 上用 WSL 拉起一个真实跑起来的多智能体流程。这个“零基础跑通第一个智能体”的过程本质是一次认知重校准你不再是在和一个黑箱对话而是在搭建一个由多个角色分工协作的微型组织——有负责信息收集的“侦察兵”有负责逻辑推理的“参谋长”还有负责执行动作的“工兵”。而 AgentScope 2.0 就是那个给你发工牌、定流程、记考勤、查日志的 HR 系统。它不替你写业务逻辑但它确保每个 Agent 都按时上岗、按规交接、出错留痕。所以这篇笔记不叫“入门教程”它是一份现场施工日志记录了我在 Win11 WSL2 Ubuntu-24.04 环境下从wsl --install -d ubuntu-24.04执行成功那一刻起到看到终端里打印出{status: success, result: Hello from AgentScope!}的全过程。所有命令、所有报错、所有绕路、所有被忽略的细节都摊开在这里。如果你正卡在agentscope 2.0 和 dsh 之间的区别这个问题上答案很简单DSH 是让你造轮子的图纸AgentScope 2.0 是已经组装好、带说明书、还附赠扳手的整车。你只需要决定往哪条路上开。2. 为什么必须用 WSL2 Ubuntu-24.04这不是折腾是避坑刚需2.1 WSL 的本质它不是虚拟机是 Linux 内核的“借壳上市”很多人把 WSL 当成轻量版虚拟机这是最大的误解。WSL2 的底层是真正的 Linux 内核由 Microsoft 维护的精简版它通过 Hyper-V 的轻量级虚拟化技术在 Windows 上运行一个完整的 Linux 用户空间。这意味着什么意味着你在 WSL 里apt install python3.11-dev安装的是原生的、ABI 兼容的 CPython 解释器不是 Windows 上那个需要额外编译.pyd扩展的 Python。AgentScope 2.0 的核心依赖之一是grpcio它需要链接libgrpc.so动态库。在原生 Windows 上pip install grpcio会尝试编译 C 扩展而 Windows 的 MSVC 工具链和 gRPC 的构建脚本经常打架报错信息动辄几百行全是LNK2019 unresolved external symbol。但在 WSL2 的 Ubuntu 里apt install libgrpc-dev一行搞定pip install grpcio直接二进制安装稳如老狗。这就是为什么wsl --install -d ubuntu-24.04是唯一推荐路径——Ubuntu-24.04 自带 Python 3.12而 AgentScope 2.0 的 PyPI 包明确要求 Python 3.11。你如果图省事用wsl --install默认装 Ubuntu-22.04自带 Python 3.10后面pip install agentscope会直接报ERROR: Package agentscope requires a different Python version然后你得手动升级 Python再处理pip和setuptools的版本冲突最后发现pyenv在 WSL2 里初始化又是个新坑。这一步省下的 5 分钟后面能帮你省下 3 小时。2.2 Ubuntu-24.04 的隐藏优势CUDA 支持与容器兼容性AgentScope 2.0 的文档里没明说但它的ModelWrapper类默认支持transformers和vllm后端。如果你后续想本地跑一个 7B 参数的开源模型比如 Qwen2-7Bvllm的推理加速就依赖 CUDA。而 Ubuntu-24.04 的内核版本6.8和 NVIDIA 官方驱动535的兼容性是目前所有 LTS 版本里最好的。wsl --install -d ubuntu-24.04后你只需在 Windows 主机上装好 NVIDIA GeForce Game Ready Driver注意不是 Studio Driver然后在 WSL2 里执行sudo apt update sudo apt install -y nvidia-cuda-toolkit nvidia-smi如果能看到 GPU 列表说明 CUDA 环境已就绪。这步在 Ubuntu-22.04 上nvidia-smi常常显示NVIDIA-SMI has failed because it couldnt communicate with the NVIDIA driver根源是内核模块版本不匹配。另外AgentScope 2.0 的StudioWeb UI一个本地可视化调试面板底层用的是uvicornfastapi它默认监听0.0.0.0:8000。在 WSL2 里这个地址能被 Windows 主机的浏览器直接访问但前提是你的/etc/wsl.conf里没有localhostForwardingtrue这种旧配置Ubuntu-24.04 默认已优化。如果你用老版本 WSL还得手动改/etc/wsl.conf加networkingtrue否则 Studio 页面打不开你会以为是代码错了其实是网络没通。2.3 Python 环境为什么坚决不用 conda而用venvpipAgentScope 2.0 的依赖树非常“干净”它没有硬依赖torch或tensorflow而是把模型后端做成插件式model_wrapper。这意味着你可以在一个纯净的venv里只装agentscope再按需装transformers或vllm。但 conda 的环境隔离是基于整个 Python 解释器的复制它会把numpy、scipy这些基础库也打包进去导致pip list看起来很乱而且conda activate后which python指向的路径和pip的sys.path有时不一致。我试过用 conda 创建python3.12环境pip install agentscope成功但运行时import agentscope报ModuleNotFoundError: No module named pydantic查了半天发现是 conda 安装的pydantic版本2.6.0和 AgentScope 2.0 要求的pydantic2.7.0,2.5.0冲突conda 却不自动降级。换成venv就简单了python3 -m venv ~/agentscope_env source ~/agentscope_env/bin/activate pip install --upgrade pip setuptools wheel pip install agentscopepip install --upgrade pip这一步不能省。Ubuntu-24.04 自带的pip版本是 23.0.1而 AgentScope 2.0 的pyproject.toml里指定了build-backend setuptools.build_meta新版pip对pyproject.toml的解析更严格。不升级 pippip install agentscope会卡在Building wheel for agentscope步骤最后超时失败。这个细节官方文档里提都没提但它是你能否跑通的第一道门槛。3. “零基础跑通”的核心拆解hello_world.py里的每一个字3.1 从pip install agentscope到第一个 Agent 的诞生安装成功后别急着写代码。先验证环境python3 -c import agentscope; print(agentscope.__version__)输出2.0.0或更高才算真正就位。然后创建一个hello_world.py文件内容如下这是 AgentScope 2.0 官方示例的极简版去掉了所有装饰器和日志配置from agentscope.agents import AgentBase from agentscope.message import Msg class HelloAgent(AgentBase): def __init__(self, name: str) - None: super().__init__(namename) def reply(self, x: dict None) - dict: # 这里是 Agent 的“大脑”它接收一个字典 x返回一个字典 # Msg 类是 AgentScope 的消息封装它比 raw dict 更安全 msg Msg( nameself.name, contentfHello from {self.name}!, roleassistant ) return {msg: msg} if __name__ __main__: # 实例化一个 HelloAgent名字叫 Alice alice HelloAgent(nameAlice) # 调用 reply 方法传入一个空字典模拟收到的消息 result alice.reply({}) print(result[msg].content)这段代码跑起来输出Hello from Alice!。看起来和写个函数没区别关键在Msg类。它不是一个简单的dict而是一个带类型校验、序列化支持、元数据字段timestamp,id,url的类。当你后续做多 Agent 编排时Msg是它们之间传递信息的唯一“货币”。alice.reply({})返回的{msg: msg}这个结构是强制约定Agent 的reply方法必须返回一个dict且 key 必须是msg或msgs用于返回多条消息。这是 AgentScope 的“协议”不是语法糖。如果你写成return msg框架会直接抛TypeError告诉你reply() must return a dict with key msg or msgs。这个强约束保证了所有 Agent 的输出格式统一为后续的Router路由、Orchestrator编排器提供了可预测的输入。3.2 真正的编排初体验两个 Agent 的握手协议单个 Agent 只是玩具。真正的“编排”始于两个 Agent 的协作。修改hello_world.py加入第二个 Agentfrom agentscope.agents import AgentBase from agentscope.message import Msg class HelloAgent(AgentBase): def __init__(self, name: str) - None: super().__init__(namename) def reply(self, x: dict None) - dict: msg Msg( nameself.name, contentfHello from {self.name}!, roleassistant ) return {msg: msg} class EchoAgent(AgentBase): def __init__(self, name: str) - None: super().__init__(namename) def reply(self, x: dict None) - dict: # EchoAgent 的逻辑它接收一条 Msg原样返回 # 注意x 是一个 dictx[msg] 才是 Msg 对象 if msg in x and hasattr(x[msg], content): echo_content fEcho: {x[msg].content} else: echo_content Echo: Empty message msg Msg( nameself.name, contentecho_content, roleassistant ) return {msg: msg} if __name__ __main__: alice HelloAgent(nameAlice) bob EchoAgent(nameBob) # 第一步Alice 发言 alice_result alice.reply({}) print(Alice says:, alice_result[msg].content) # 第二步把 Alice 的消息传给 Bob bob_result bob.reply(alice_result) print(Bob echoes:, bob_result[msg].content)运行结果Alice says: Hello from Alice! Bob echoes: Echo: Hello from Alice!这就是最原始的编排Alice - Bob的线性消息流。bob.reply(alice_result)这行代码是编排的“胶水”。alice_result是一个dictbob.reply()接收它并从中提取msg字段。AgentScope 2.0 的AgentBase类其reply方法签名是def reply(self, x: dict None) - dict:这个x就是编排器Orchestrator注入的上下文。你可以把它想象成一个快递员x是他手里拿着的包裹reply方法就是签收并填写回执的过程。x里可以塞任何东西前一个 Agent 的输出、用户输入、数据库查询结果、甚至一个时间戳。这种设计让 Agent 的职责极度单一只管“处理输入生成输出”不关心自己是谁、谁调用了自己、下一步要发给谁。这种解耦正是大规模编排的基石。3.3 让编排“活”起来引入Pipeline和Sequential流程手写alice.reply()-bob.reply()很原始。AgentScope 2.0 提供了Pipeline类它把一串 Agent 当作流水线上的工人from agentscope.pipelines import Pipeline from agentscope.agents import AgentBase from agentscope.message import Msg class HelloAgent(AgentBase): def __init__(self, name: str) - None: super().__init__(namename) def reply(self, x: dict None) - dict: msg Msg( nameself.name, contentfHello from {self.name}!, roleassistant ) return {msg: msg} class EchoAgent(AgentBase): def __init__(self, name: str) - None: super().__init__(namename) def reply(self, x: dict None) - dict: if msg in x and hasattr(x[msg], content): echo_content fEcho: {x[msg].content} else: echo_content Echo: Empty message msg Msg( nameself.name, contentecho_content, roleassistant ) return {msg: msg} if __name__ __main__: alice HelloAgent(nameAlice) bob EchoAgent(nameBob) # 创建一个 Pipeline顺序执行 alice - bob pipeline Pipeline( agents[alice, bob], # Sequential 是默认的执行策略即前一个的输出作为下一个的输入 strategysequential ) # 启动 Pipeline传入初始输入 {} result pipeline.run({}) print(Final result:, result[msg].content)pipeline.run({})的返回值就是最后一个 AgentBob的输出。Pipeline类内部做了三件事1把{}传给alice.reply()2把alice的返回值传给bob.reply()3把bob的返回值作为整个 Pipeline 的结果返回。这看起来只是语法糖不。Pipeline的价值在于它抽象了“执行上下文”。当你后续加入Router根据消息内容决定走哪条分支或Loop循环执行直到满足条件时你不需要改alice和bob的代码只需要换一个Pipeline的strategy参数。比如你想让 Bob 只在 Alice 的消息里包含 “urgent” 时才响应你可以定义一个ConditionalRouter然后Pipeline(agents[alice, router, bob], strategyconditional)。Agent 的代码完全不变变的只是编排逻辑。这才是框架的力量业务逻辑Agent和流程逻辑Pipeline彻底分离。4. 实操全流程从 WSL 初始化到 Studio 可视化调试4.1 WSL2 初始化与环境固化一份可复现的 Shell 脚本为了避免每次重装都重复劳动我写了一个setup_agentscope.sh脚本放在~/scripts/下#!/bin/bash # setup_agentscope.sh # 在 Ubuntu-24.04 WSL2 中一键部署 AgentScope 2.0 开发环境 echo Step 1: Updating system... sudo apt update sudo apt upgrade -y echo Step 2: Installing Python dev tools... sudo apt install -y python3.12-dev python3.12-venv python3-pip build-essential echo Step 3: Creating dedicated workspace... mkdir -p ~/workspace/agentscope_demo cd ~/workspace/agentscope_demo echo Step 4: Setting up virtual environment... python3.12 -m venv agentscope_env source agentscope_env/bin/activate echo Step 5: Upgrading pip and installing agentscope... pip install --upgrade pip setuptools wheel pip install agentscope echo Step 6: Verifying installation... python3 -c import agentscope; print(✓ AgentScope, agentscope.__version__) echo Done! Activate env with: source ~/workspace/agentscope_demo/agentscope_env/bin/activate执行它chmod x ~/scripts/setup_agentscope.sh ~/scripts/setup_agentscope.sh这个脚本的关键点在于python3.12 -m venv。Ubuntu-24.04 的python3是软链接到python3.12但venv模块必须显式指定 Python 版本否则python3 -m venv可能调用到系统默认的python3.10如果之前装过。脚本末尾的echo提示是为了防止你忘记激活环境。我踩过的最大坑是在agentscope_env里pip install agentscope成功但deactivate后python hello_world.py报ModuleNotFoundError因为没激活环境。这个提示救了我三次。4.2 运行第一个编排流程并启用日志追踪hello_world.py跑通后下一步是开启 AgentScope 的核心能力——全链路日志追踪。修改代码加入init_logimport os from agentscope import init_log from agentscope.pipelines import Pipeline from agentscope.agents import AgentBase from agentscope.message import Msg # 初始化日志输出到 ./logs/ 目录 init_log( log_dir./logs, levelINFO, use_timestampTrue, stdoutTrue ) class HelloAgent(AgentBase): def __init__(self, name: str) - None: super().__init__(namename) def reply(self, x: dict None) - dict: msg Msg( nameself.name, contentfHello from {self.name}!, roleassistant ) return {msg: msg} class EchoAgent(AgentBase): def __init__(self, name: str) - None: super().__init__(namename) def reply(self, x: dict None) - dict: if msg in x and hasattr(x[msg], content): echo_content fEcho: {x[msg].content} else: echo_content Echo: Empty message msg Msg( nameself.name, contentecho_content, roleassistant ) return {msg: msg} if __name__ __main__: alice HelloAgent(nameAlice) bob EchoAgent(nameBob) pipeline Pipeline( agents[alice, bob], strategysequential ) result pipeline.run({}) print(Final result:, result[msg].content)运行后会在当前目录生成./logs/文件夹里面有两个文件agentscope.log: 主日志记录所有 Agent 的reply调用、参数、返回值、耗时。agentscope_trace.jsonl: 结构化追踪日志每行是一个 JSON 对象记录一次 Agent 调用的完整上下文包括msg.id,timestamp,agent_name,input,output。打开agentscope_trace.jsonl你会看到类似这样的行{msg_id: msg_abc123, timestamp: 2024-05-20T10:30:45.123Z, agent_name: Alice, input: {}, output: {msg: {name: Alice, content: Hello from Alice!, role: assistant}}} {msg_id: msg_def456, timestamp: 2024-05-20T10:30:45.456Z, agent_name: Bob, input: {msg: {name: Alice, content: Hello from Alice!, role: assistant}}, output: {msg: {name: Bob, content: Echo: Hello from Alice!, role: assistant}}}这个jsonl文件就是 AgentScope 的“行车记录仪”。当你后续的流程出错比如agent execution terminated due to error.你不用猜是哪个 Agent 崩了直接grep error agentscope_trace.jsonl就能找到崩溃点。它比print()强一万倍因为它是结构化的、可搜索的、可导入到 ELK 或 Grafana 里做监控的。4.3 启动 Studio Web UI用图形界面“看见”你的智能体AgentScope 2.0 最惊艳的功能是Studio一个本地 Web UI让你实时看到 Agent 的状态、消息流、耗时分布。启动它只需一行命令agentscope studio --host 0.0.0.0 --port 8000提示--host 0.0.0.0是为了让 Windows 主机的浏览器能访问。如果只写--host 127.0.0.1WSL2 的网络隔离会让主机打不开。然后在 Windows 的浏览器里访问http://localhost:8000。你会看到一个简洁的仪表盘上面有Agents: 列出当前注册的所有 AgentAlice, Bob。Pipelines: 显示正在运行的 Pipeline。Messages: 实时滚动的消息流每条消息显示发送者、接收者、内容、时间戳。Traces: 以甘特图形式展示每个 Agent 的执行时间线。现在修改你的hello_world.py让它在pipeline.run({})前先注册 Agent 到 Studio# ... 导入部分不变 ... if __name__ __main__: alice HelloAgent(nameAlice) bob EchoAgent(nameBob) # 关键注册 Agent让 Studio 能发现它们 alice.register() bob.register() pipeline Pipeline( agents[alice, bob], strategysequential ) result pipeline.run({}) print(Final result:, result[msg].content)再次运行python hello_world.py然后刷新 Studio 页面。你会看到Messages面板里两条消息像弹幕一样刷出来“Alice → Bob”“Bob → (final)”。点击Traces标签页你会看到一个横向的时间轴上面两个色块Alice 执行了 2msBob 执行了 3ms。这就是“看见编排”的力量。你不再靠print()猜流程而是用眼睛确认消息是否真的发出去了、有没有被丢弃、哪个环节最慢。对于调试chatgpt-web-midjourney-proxy这类涉及外部 API 调用的复杂编排Studio 的Traces图能一眼看出是MidjourneyAgent卡在了网络请求还是WebAgent的 HTML 解析出了错。5. 常见问题排查实录那些文档里不会写的“血泪教训”5.1 问题ImportError: cannot import name cached_property from werkzeug.utils现象pip install agentscope成功但python -c import agentscope报错指向werkzeug库。根因agentscope依赖fastapifastapi依赖starlettestarlette依赖werkzeug。而werkzeug2.4.0 版本移除了cached_property改用functools.cached_property但starlette的某个旧版本还没适配。解决方案强制降级werkzeugpip install werkzeug2.4.0注意引号是必须的否则 shell 会把当作重定向符号。经验这不是 AgentScope 的 bug而是 Python 生态的“依赖地狱”。遇到ImportError第一反应不是重装agentscope而是pip list | grep werkzeug查版本再pip show starlette看它要求的werkzeug版本范围。我花了 40 分钟查这个问题最后发现是starlette0.37.2要求werkzeug2.0.0,2.4.0而pip install agentscope默认装了werkzeug2.4.0。5.2 问题Studio 页面空白Network 标签页显示Failed to load resource: net::ERR_CONNECTION_REFUSED现象agentscope studio命令在终端里显示INFO: Uvicorn running on http://0.0.0.0:8000但浏览器打不开。根因WSL2 的防火墙或 Windows 主机的网络设置阻止了连接。常见于公司电脑IT 部门禁用了localhost的端口转发。排查步骤在 WSL2 里用curl测试本地是否通curl -v http://localhost:8000如果返回 HTML说明服务正常问题在 Windows 主机。在 Windows PowerShell 里测试 WSL2 的 IP 是否可达wsl hostname -I # 获取 WSL2 的 IP通常是 172.x.x.x Test-NetConnection 172.x.x.x -Port 8000如果TcpTestSucceeded : False说明端口不通。解决方案在 Windows 主机上以管理员身份运行 PowerShell执行netsh interface portproxy add v4tov4 listenport8000 listenaddress127.0.0.1 connectport8000 connectaddress$(wsl hostname -I | tr -d )经验不要迷信localhost。WSL2 的localhost和 Windows 的localhost是两个网络栈。agentscope studio --host 0.0.0.0是对的但你需要确保 Windows 能路由到 WSL2 的 IP。这个坑我帮 7 个同事解决过平均每人耗时 1.5 小时。5.3 问题agent couldnt generate a response. please try again.中文乱码现象Agent 的reply方法里msg.content是中文但 Studio 页面或日志里显示为éè¿°这样的乱码。根因WSL2 的 locale 设置不支持 UTF-8。Ubuntu-24.04 默认是C.UTF-8但某些情况下比如从旧 WSL 升级locale命令会显示LANGC。解决方案永久修复 localesudo locale-gen en_US.UTF-8 sudo update-locale LANGen_US.UTF-8 echo export LANGen_US.UTF-8 ~/.bashrc source ~/.bashrc然后重启 WSL2wsl --shutdown再重新打开终端。经验locale是 Linux 系统的“语言基因”。AgentScope 的日志和 Studio 都依赖它来正确编码字符串。LANGC会让所有非 ASCII 字符变成乱码而且这个错误不会报异常只会静默损坏数据。检查方法locale命令输出里LANG和LC_ALL必须是*.UTF-8。5.4 问题RuntimeError: asyncio.run() cannot be called from a running event loop现象在 Jupyter Notebook 或 VS Code 的 Python Interactive 窗口里运行pipeline.run({})报这个错。根因Jupyter 本身运行在一个 asyncio event loop 里而pipeline.run()内部调用了asyncio.run()Python 不允许嵌套 event loop。解决方案两种选择推荐在普通.py文件里运行不要在 Notebook 里。临时方案用asyncio.create_task()替代asyncio.run()import asyncio # ... agent 定义 ... async def main(): result await pipeline.arun({}) # 注意是 arun不是 run print(Result:, result[msg].content) asyncio.create_task(main())经验AgentScope 2.0 的run()是同步接口arun()是异步接口。文档里没强调这点但它是区分“脚本开发”和“Web 服务集成”的关键。你在 Flask/FastAPI 里集成 AgentScope必须用arun()否则会阻塞整个 Web 服务器。6. 从“Hello World”到生产级三个必做的加固步骤跑通hello_world.py只是起点。要让它真正可用必须做三件事6.1 步骤一为 Agent 添加system_prompt让它有“人设”默认的AgentBase没有系统提示词system prompt它只是个空壳。真正的 Agent 需要“性格”。修改HelloAgentfrom agentscope.agents import AgentBase from agentscope.message import Msg from agentscope.models import ModelResponse class HelloAgent(AgentBase): def __init__(self, name: str, model_name: str default) - None: super().__init__(namename, model_namemodel_name) # 设置系统提示词定义 Agent 的角色和规则 self.system_prompt fYou are {name}, a helpful and concise assistant. Always respond in Chinese. def reply(self, x: dict None) - dict: # 使用内置的 model 生成回复需要先配置模型 user_msg x.get(msg, Msg(content, roleuser)) # 构造 messages 列表符合 LLM 的 chat format messages [ {role: system, content: self.system_prompt}, {role: user, content: user_msg.content} ] # 调用模型这里用 mock实际需配置 OpenAI 或本地模型 response ModelResponse(textfHello from {self.name}! Im configured with system prompt.) msg Msg( nameself.name, contentresponse.text, roleassistant ) return {msg: msg}system_prompt是 Agent 的“宪法”它决定了 Agent 的行为边界。没有它Agent 就是无意识的回声。AgentScope 2.0 的AgentBase把system_prompt作为实例属性意味着每个 Agent 实例可以有不同的“人设”这是多智能体协作的基础。6.2 步骤二用ConfigManager管理配置告别硬编码把model_name、api_key、timeout这些参数写死在代码里是灾难。AgentScope 2.0 提供了ConfigManagerfrom agentscope.config import ConfigManager # 创建配置文件 config.json config_json { model_configs: [ { model_type: openai, model_name: gpt-3.5-turbo, api_key: your-api-key-here, organization: , base_url: } ], agent_configs: [ { name: HelloAgent, model_name: gpt-3.5-turbo, system_prompt: You are a friendly greeting bot. } ] } # 保存配置 ConfigManager.load_config(config_json)然后在 Agent 初始化时用ConfigManager.get_agent_config(HelloAgent)获取配置。这样切换模型、调整提示词都不用改代码只改 JSON。6.3 步骤三添加Router让编排具备“决策力”最简单的编排是线性的但真实场景需要分支。比如一个客服 Agent收到用户消息后要判断是“咨询”、“投诉”还是“售后”然后路由给不同专家。AgentScope 2.0 的Router就是干这个的from agentscope.pipelines import Router, Pipeline from agentscope.agents import AgentBase from agentscope.message import Msg class RouterAgent(Router): def route(self, x: dict) - str: # 根据消息内容决定路由到哪个 Agent content x.get(msg, Msg(content, roleuser)).content.lower() if price in content or cost in content: return price_agent elif broken in content or not work in content: return support_agent else: return general_agent class PriceAgent(AgentBase): def reply(self, x: dict None) - dict: msg Msg(namePriceAgent, contentOur product costs $99., roleassistant) return {msg: msg} # ...