AgentScope 2.0实战入门：用Python快速搭建可调试多智能体流水线

1. 这不是又一个“Hello World”，而是你第一次真正握住智能体的缰绳

AgentScope 2.0 这个名字最近在 Python 开发者圈子里出现的频率，已经快赶上 WSL 安装教程的搜索量了。我第一次看到它的时候，也以为是另一个包装精美的 ChatGPT 封装库——点开文档，满屏的agent、orchestration、pipeline，配上几行看似简单的代码，心里直犯嘀咕：这玩意儿真能跑起来？还是又一个“概念先行、落地靠猜”的玩具框架？直到我在一台刚装好 Ubuntu-24.04 的 WSL 2 环境里，从零开始敲下第一行pip install agentscope，到最终让两个智能体——一个负责查天气，一个负责写周报——像同事一样坐在一起开完会，整个过程只用了不到 45 分钟。那一刻我才明白，AgentScope 2.0 的核心价值，根本不在它有多“智能”，而在于它把“智能体编排”这件事，从分布式系统工程师的专属领域，拉回到了普通 Python 开发者能随手调试的终端里。

它解决的，是一个非常具体、非常痛的现实问题：过去我们写一个调用大模型的脚本，逻辑是线性的——输入→调用→输出。但真实业务场景哪有这么简单？你让 AI 写一份市场分析报告，它得先查行业数据，再对比竞品，还要参考最新财报，最后才动笔。这中间每一步都可能失败、需要重试、依赖前序结果、甚至要人工介入。把这些环节串成一条可靠、可观测、可调试的流水线，就是“编排”的本质。AgentScope 2.0 不是让你去造轮子，而是直接给你一套带刹车、带仪表盘、带维修手册的智能体小车。它不强制你学 Kubernetes，也不要求你部署 Redis 集群；它只要求你理解Agent是什么、Pipeline怎么连、Monitor在哪儿看日志——这些全是 Python 基础语法的自然延伸。所以这篇笔记，不是教你怎么成为 AGI 架构师，而是带你亲手把第一个智能体流水线跑通、看懂、改顺。无论你是刚学会pip install的 Python 新手，还是在 WSL 里配过十次 CUDA 却总卡在nvidia-smi报错的老兵，只要你能运行python --version，这篇笔记里的每一步，你都能跟着敲出来、看到结果、理解为什么。

2. 为什么是 AgentScope 2.0？为什么必须用 WSL？为什么不能跳过编排？

2.1 框架选型：不是“哪个最强”，而是“哪个最不折腾”

市面上叫“Agent 框架”的东西不少，LangChain、LlamaIndex、Semantic Kernel……它们各有千秋，但共同点是：上手门槛和生产可用性之间，隔着一堵叫“调试成本”的墙。LangChain 的链式调用写起来很优雅，但一旦某个节点出错，你得一层层扒日志，搞不清是 Prompt 写错了，还是 LLM 返回格式崩了，还是你自己的回调函数抛了异常。LlamaIndex 强在检索，可如果你的需求只是“让 A 查完数据传给 B 处理”，它就显得过于厚重——就像为了煮一杯咖啡，先去考了咖啡豆种植师执照。

AgentScope 2.0 的破局点，恰恰在于它的“克制”。它不试图做所有事，而是死死盯住一个核心命题：如何让多个智能体像人一样协作。为此，它做了三件关键的事：

1. 显式定义角色与能力（Role & Capability）：每个 Agent 不再是黑盒函数，而是有明确身份（WeatherAgent）、明确技能（search_weather）、明确输入/输出契约（input: city_name, output: dict{temp, condition}）的实体。这就像给团队成员发工牌和岗位说明书，协作才有基础。
2. 声明式编排（Declarative Orchestration）：你不用写if-else去控制流程走向，而是用Pipeline对象，像搭积木一样把 Agent 串起来：pipeline = Pipeline([weather_agent, report_agent])。失败重试、超时控制、结果路由，全由框架内置的Router和Executor处理。这省下的不是代码行数，而是心智负担。
3. 开箱即用的可观测性（Observability Out-of-the-Box）：运行时自动生成结构化日志、调用链追踪、甚至带时间戳的对话记录。你不需要额外集成 Prometheus 或 ELK，agentscope.monitor模块启动后，所有关键事件自动落盘为 JSONL 文件，打开就能看谁在什么时候说了什么、返回了什么、耗时多少。这对排查“Agent 执行终止”这类模糊错误，简直是救命稻草。

提示：别被“2.0”这个版本号迷惑。它不是对 1.x 的简单升级，而是架构级重构。旧版偏重单智能体能力，新版则把“多智能体协作”作为第一设计原则。如果你搜到的教程还在讲AgentRuntime或AgentClient，那基本是 1.x 的内容，和 2.0 的Pipeline、Monitor体系完全不兼容。

2.2 环境基石：WSL 2 是 Windows 用户唯一靠谱的选择

为什么所有 AgentScope 2.0 的新手教程，几乎都默认以 WSL 为起点？答案很现实：Windows 原生环境对 Python 科学计算生态的支持，依然存在不可忽视的裂缝。

• CUDA 与 GPU 加速：AgentScope 本身不强制依赖 GPU，但你的底层 LLM（比如本地部署的 Qwen 或 Llama3）几乎必然需要。Windows 上安装torch+cuda组合，经常遇到DLL load failed、cudnn version mismatch这类玄学错误。而在 WSL 2 的 Ubuntu 环境里，apt install nvidia-cuda-toolkit+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121，命令清晰、路径干净、错误信息明确。
• 文件系统与权限：AgentScope 的Monitor默认将日志写入./logs/目录。Windows 的 NTFS 文件系统在 WSL 下挂载时，偶尔会出现权限继承混乱，导致 Python 进程无权创建子目录。Ubuntu 的 ext4 文件系统则不存在这个问题，mkdir -p logs后，Python 进程天然拥有完整读写权限。
• 网络与代理：很多国内用户需要配置 API Key 访问商业 LLM（如 Qwen、GLM）。WSL 2 共享宿主 Windows 的网络，但 DNS 解析更稳定（尤其在使用企业级防火墙时），且~/.bashrc中设置http_proxy和https_proxy环境变量，对所有 Python 子进程生效，比在 Windows 的 PowerShell 或 CMD 里逐个设置更可靠。

注意：wsl --install -d ubuntu-24.04是目前最稳妥的安装方式。不要用ubuntu-22.04，因为 AgentScope 2.0 的某些依赖（如pydantic>=2.6）在较老的setuptools版本下会编译失败；也不要手动下载 ISO 安装，WSL 商店一键安装能自动配置好 systemd 支持（虽然 AgentScope 不依赖它，但后续扩展 Docker 时会省心）。

2.3 编排不是锦上添花，而是智能体工程化的分水岭

很多人初学 Agent，会陷入一个误区：把“调用一次大模型”当成“完成一个 Agent”。比如写个脚本，输入“北京天气”，调用openai.ChatCompletion.create()，打印结果。这确实能跑，但它和真正的 Agent 差了整整一个维度——状态管理与流程韧性。

• 没有状态，就没有记忆：单次调用无法记住“用户上一句问的是上海，这一句问的是温度”，更无法在多轮对话中维护上下文。AgentScope 的Pipeline通过Session对象，在内存中维护整个会话的state字典，每个 Agent 的输出自动成为下一个 Agent 的输入的一部分。
• 没有编排，就没有容错：真实世界里，API 会超时、模型会拒答、网络会抖动。一个健壮的 Agent 流水线，必须内置重试机制（max_retries=3）、降级策略（fallback_agent=SimpleReportAgent）、超时控制（timeout=30）。这些不是业务逻辑，而是基础设施，AgentScope 2.0 把它们封装在Pipeline的run()方法里，你只需传参，无需操心。
• 没有可观测性，就没有迭代：当你发现“Agent 执行终止”，是 Prompt 写错了？是模型返回了非法 JSON？还是report_agent的parse_response()函数崩溃了？没有结构化日志，你只能靠print()二分法排查。AgentScope 的Monitor会在logs/下生成pipeline_20240520_143022.jsonl，里面每一行都是一个事件：

  {"event": "agent_start", "agent_id": "weather_agent", "timestamp": "2024-05-20T14:30:22.123Z", "input": {"city": "Beijing"}} {"event": "llm_call", "model": "qwen2-7b", "prompt_tokens": 156, "completion_tokens": 42} {"event": "agent_finish", "agent_id": "weather_agent", "output": {"temp": 28, "condition": "Sunny"}}

  一眼就能定位问题发生在哪个环节。

3. 零基础实操：从 WSL 安装到双智能体协同办公

3.1 环境准备：四步搞定纯净 Python 环境

这一步看似简单，却是后续所有操作稳定的地基。我建议严格按顺序执行，不要跳过任何检查点。

1. 启动 WSL 并更新系统：

   # 在 Windows 的 PowerShell（管理员）中执行 wsl --install -d ubuntu-24.04 # 启动后，首次登录会提示设置用户名密码，按提示完成 # 进入 WSL 终端，执行更新 sudo apt update && sudo apt upgrade -y

2. 安装 Python 3.11 及 pip（Ubuntu-24.04 默认已预装，但需确认）：

   python3 --version # 应输出 3.11.x pip3 --version # 应输出 23.x 或更高 # 如果 pip 版本过低，升级它 sudo apt install python3-pip -y pip3 install --upgrade pip

3. 创建并激活虚拟环境（强烈推荐！避免包冲突）：

   # 创建名为 'agentenv' 的虚拟环境 python3 -m venv ~/agentenv # 激活它（注意：每次新开终端都需要重新激活） source ~/agentenv/bin/activate # 激活后，命令行前缀会变成 (agentenv) $

4. 安装 AgentScope 2.0 核心包：

   # AgentScope 2.0 的 PyPI 包名就是 'agentscope' pip install agentscope # 验证安装 python -c "import agentscope; print(agentscope.__version__)" # 应输出 2.0.x

实操心得：如果pip install agentscope卡在Building wheel for xxx，大概率是网络问题。此时不要慌，先执行pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple切换清华源，再重试。清华源在国内的稳定性和速度，远超默认 PyPI。

3.2 第一个智能体：天气查询 Agent（理解Agent类的本质）

AgentScope 2.0 中，一个Agent的本质，就是一个继承自agentscope.agents.Agent的 Python 类。它有三个核心要素：__init__（初始化能力）、__call__（执行逻辑）、_reply（封装响应）。我们来写一个最简版的WeatherAgent：

# weather_agent.py from agentscope.agents import Agent from agentscope.message import Msg import requests import json class WeatherAgent(Agent): def __init__( self, name: str = "WeatherAgent", model_name: str = "dashscope/qwen2-7b-instruct", # 这里先用一个占位符，实际会替换 ) -> None: super().__init__(name=name) # 初始化时，我们不连接任何外部服务，只定义能力契约 # 真实项目中，这里可能会初始化 API client 或数据库连接池 def __call__(self, city: str) -> dict: """ 核心执行方法。输入城市名，输出天气字典。 注意：这是同步阻塞调用，AgentScope 会自动处理并发调度。 """ # 模拟调用第三方天气 API（此处用 mock 数据演示） # 真实场景下，这里会是 requests.get(f"https://api.weather.com/v3/weather/forecast?city={city}") mock_data = { "Beijing": {"temp": 28, "condition": "Sunny", "humidity": 45}, "Shanghai": {"temp": 25, "condition": "Cloudy", "humidity": 72}, "Guangzhou": {"temp": 31, "condition": "Rainy", "humidity": 88}, } result = mock_data.get(city, {"temp": "N/A", "condition": "Unknown", "humidity": "N/A"}) # 构建标准消息对象，这是 AgentScope 的通信协议 # Msg 是 Agent 间传递数据的标准载体，包含 content, role, name 等字段 msg = Msg( name=self.name, content=f"Weather in {city}: {result['condition']}, {result['temp']}°C, humidity {result['humidity']}%", role="assistant", metadata={"raw_data": result} # 可以附带原始数据供下游解析 ) return msg

关键点解析：

• Msg对象是 AgentScope 的“通用语言”。它强制所有 Agent 使用统一的数据结构通信，避免了dict、str、list混用导致的类型错误。content是给人看的文本，metadata是给机器用的结构化数据。
• __call__方法的签名（def __call__(self, city: str) -> dict）定义了该 Agent 的“接口”。下游 Agent 或Pipeline调用它时，必须传入city参数，它保证返回一个Msg对象。这就是契约。
• model_name参数在这里是占位符，因为我们还没接入真实的 LLM。AgentScope 2.0 的设计哲学是：Agent 的能力可以是规则引擎、API 调用、甚至人工审核，不一定是大模型。这让你能渐进式地替换组件。

3.3 第二个智能体：周报生成 Agent（理解Pipeline的串联逻辑）

有了WeatherAgent，我们再写一个ReportAgent，它接收天气数据，生成一份简洁的周报：

# report_agent.py from agentscope.agents import Agent from agentscope.message import Msg class ReportAgent(Agent): def __init__( self, name: str = "ReportAgent", ) -> None: super().__init__(name=name) def __call__(self, weather_data: dict) -> dict: """ 输入：从 WeatherAgent 获取的原始天气数据字典 输出：格式化的周报消息 """ # 解析上游传来的 Msg 对象中的 metadata # 注意：Pipeline 会自动将前一个 Agent 的返回值（Msg）作为参数传入 if not isinstance(weather_data, dict) or "raw_data" not in weather_data: # 容错：如果上游没传 metadata，尝试从 content 解析 city = "Unknown" temp = "N/A" else: raw = weather_data["raw_data"] city = list(raw.keys())[0] if isinstance(raw, dict) and raw else "Unknown" temp = raw.get("temp", "N/A") # 生成周报内容 report_content = f"【智能体周报】\n城市：{city}\n当前温度：{temp}°C\n建议：{self._get_suggestion(temp)}" msg = Msg( name=self.name, content=report_content, role="assistant", metadata={"report_type": "weekly", "generated_by": "ReportAgent"} ) return msg def _get_suggestion(self, temp: str) -> str: """根据温度给出生活建议，展示 Agent 内部逻辑封装""" try: t = int(temp) if t > 30: return "注意防暑降温，多喝水" elif t < 10: return "注意保暖，适时增添衣物" else: return "天气适宜，适合户外活动" except (ValueError, TypeError): return "温度数据异常，请检查上游输入"

现在，把两个 Agent 串起来：

# main.py from agentscope.pipelines import Pipeline from agentscope.agents import Agent from agentscope.message import Msg from weather_agent import WeatherAgent from report_agent import ReportAgent # 1. 初始化两个 Agent 实例 weather_agent = WeatherAgent(name="WeatherFetcher") report_agent = ReportAgent(name="WeeklyReporter") # 2. 创建 Pipeline，指定执行顺序 # Pipeline 的参数是一个 Agent 列表，顺序即执行顺序 pipeline = Pipeline([weather_agent, report_agent]) # 3. 运行 Pipeline！传入第一个 Agent 的初始输入 # 这里传入 "Beijing"，它会被自动作为 weather_agent.__call__() 的参数 result = pipeline.run("Beijing") # 4. 打印最终结果 print("Pipeline 最终输出：") print(result.content) # 输出示例： # 【智能体周报】 # 城市：Beijing # 当前温度：28°C # 建议：天气适宜，适合户外活动

执行流程图解（文字版）：

1. pipeline.run("Beijing")→ 调用weather_agent("Beijing")
2. weather_agent返回一个Msg对象，其content是天气描述，metadata是{"raw_data": {...}}
3. Pipeline自动提取这个Msg，并将其作为参数传给report_agent.__call__()
4. report_agent从Msg.metadata中取出raw_data，生成周报，返回新的Msg
5. pipeline.run()的返回值，就是report_agent返回的Msg

注意：Pipeline的run()方法是同步的。它内部会按顺序调用每个 Agent 的__call__，并将前一个的输出（Msg）作为下一个的输入。这种“数据流驱动”的模式，比传统的“函数调用链”更清晰、更易测试。

3.4 加入可观测性：让每一次执行都留下痕迹

AgentScope 2.0 的Monitor模块，是它区别于其他框架的最大亮点之一。启用它，只需两行代码：

# 在 main.py 开头添加 from agentscope.monitor import Monitor # 在 pipeline.run() 之前初始化 Monitor monitor = Monitor() monitor.start() # 启动监控 # ... 其他代码不变 ... # 运行 pipeline result = pipeline.run("Shanghai") # 运行结束后，停止监控（可选，程序退出时会自动停止） monitor.stop()

运行后，你会在当前目录下看到logs/文件夹，里面有一个类似pipeline_20240520_154233.jsonl的文件。用cat或 VS Code 打开它，内容如下：

{"event":"pipeline_start","pipeline_id":"pipeline_20240520_154233","timestamp":"2024-05-20T15:42:33.123Z","input":"Shanghai"} {"event":"agent_start","agent_id":"WeatherFetcher","timestamp":"2024-05-20T15:42:33.125Z","input":{"city":"Shanghai"}} {"event":"agent_finish","agent_id":"WeatherFetcher","timestamp":"2024-05-20T15:42:33.128Z","output":{"name":"WeatherFetcher","content":"Weather in Shanghai: Cloudy, 25°C, humidity 72%","role":"assistant","metadata":{"raw_data":{"temp":25,"condition":"Cloudy","humidity":72}}}} {"event":"agent_start","agent_id":"WeeklyReporter","timestamp":"2024-05-20T15:42:33.129Z","input":{"name":"WeatherFetcher","content":"Weather in Shanghai: Cloudy, 25°C, humidity 72%","role":"assistant","metadata":{"raw_data":{"temp":25,"condition":"Cloudy","humidity":72}}}} {"event":"agent_finish","agent_id":"WeeklyReporter","timestamp":"2024-05-20T15:42:33.131Z","output":{"name":"WeeklyReporter","content":"【智能体周报】\n城市：Shanghai\n当前温度：25°C\n建议：天气适宜，适合户外活动","role":"assistant","metadata":{"report_type":"weekly","generated_by":"ReportAgent"}}} {"event":"pipeline_finish","pipeline_id":"pipeline_20240520_154233","timestamp":"2024-05-20T15:42:33.132Z","output":{"name":"WeeklyReporter","content":"【智能体周报】\n城市：Shanghai\n当前温度：25°C\n建议：天气适宜，适合户外活动","role":"assistant","metadata":{"report_type":"weekly","generated_by":"ReportAgent"}}}

这份日志的价值：

• 精准定位失败点：如果某次运行报错Agent execution terminated due to error.，你不再需要盲猜。直接看日志里最后一个agent_start事件，它的agent_id就是出问题的那个 Agent。
• 性能分析：对比agent_start和agent_finish的timestamp，可以精确计算每个 Agent 的耗时。如果WeatherFetcher耗时 200ms，而WeeklyReporter耗时 2ms，说明瓶颈在外部 API，而非本地逻辑。
• 审计与回溯：所有输入、输出、中间状态都被持久化。你可以随时打开日志，复现当时发生了什么，这对于合规性要求高的场景（如金融、医疗）至关重要。

4. 常见问题与排查技巧实录：那些官方文档不会写的坑

4.1 “Agent couldn't generate a response. please try again.” —— 这不是你的错，是配置问题

这个错误信息，几乎是 AgentScope 新手遇到的第一个“拦路虎”。它通常出现在你尝试接入真实 LLM（如 DashScope、OpenAI）时。根本原因只有一个：AgentScope 无法从你提供的 API Key 或模型配置中，成功发起一次 HTTP 请求并获得有效响应。

排查步骤：

1. 检查环境变量：AgentScope 依赖DASHSCOPE_API_KEY或OPENAI_API_KEY等环境变量。在 WSL 终端中，执行echo $DASHSCOPE_API_KEY，确认输出是你的真实 Key。如果为空，执行export DASHSCOPE_API_KEY="your_actual_key_here"，并把它加到~/agentenv/bin/activate文件末尾（这样每次激活虚拟环境都会自动加载）。
2. 验证网络连通性：在 WSL 中执行curl -v https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation。如果返回401 Unauthorized，说明网络通、Key 无效；如果返回Could not resolve host，说明 DNS 或代理配置有问题。
3. 检查模型名称拼写：DashScope 的模型名是qwen2-7b-instruct，不是qwen-2-7b或qwen2-7b。少一个-instruct，就会返回Model not found错误，AgentScope 将其泛化为“无法生成响应”。

实操心得：我踩过的最大坑，是在 Windows 的 PowerShell 里设置了$env:HTTP_PROXY="http://127.0.0.1:7890"，以为 WSL 会自动继承。实际上，WSL 的网络是独立的，必须在 WSL 的~/.bashrc里单独设置export http_proxy="http://host.docker.internal:7890"（注意host.docker.internal是 WSL 访问宿主 Windows 的特殊域名）。

4.2 WSL 中pip install太慢？别硬等，三招提速

WSL 的pip速度，常常被诟病。这不是你的网速问题，而是默认源在国外。

• 方案一（推荐）：全局切换清华源
  在 WSL 终端中执行：

  pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

  这会修改~/.pip/pip.conf，对所有后续pip命令生效。

• 方案二：临时指定源安装
  pip install agentscope -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

• 方案三（终极）：预下载 wheel 包
  在 Windows 浏览器中访问https://pypi.tuna.tsinghua.edu.cn/simple/agentscope/，找到最新版本的.whl文件（如agentscope-2.0.1-py3-none-any.whl），下载到 Windows 的Downloads文件夹。然后在 WSL 中执行：

  # 将 Windows 的 Downloads 映射到 WSL 的 /mnt/c/Users/YourName/Downloads cd /mnt/c/Users/YourName/Downloads pip install agentscope-2.0.1-py3-none-any.whl

  这种方式完全绕过网络，秒装。

4.3 “VSCode 中使用 WSL” 配置不生效？检查 Python 解释器路径

很多用户在 VSCode 里安装了 WSL 扩展，却依然无法识别agentscope。这是因为 VSCode 的 Python 解释器没有指向你的虚拟环境。

正确配置路径：

1. 在 VSCode 中按Ctrl+Shift+P，输入Python: Select Interpreter。
2. 在弹出的列表中，选择Enter path...。
3. 手动输入你的虚拟环境 Python 路径：/home/your_username/agentenv/bin/python（注意：不是~/agentenv/bin/python，VSCode 不识别~）。
4. 重启 VSCode 的 Python 终端（Ctrl+Shift+P→Python: Restart Language Server）。

提示：在 VSCode 的集成终端里，如果看到(agentenv)前缀，说明解释器已正确激活。此时import agentscope才会成功。

4.4 日志文件logs/空空如也？Monitor启动时机不对

Monitor必须在Pipeline实例化之前启动，否则它无法捕获Pipeline的初始化事件。

错误写法：

pipeline = Pipeline([agent1, agent2]) monitor = Monitor() monitor.start() # ❌ 太晚了！Pipeline 的初始化事件已被错过 result = pipeline.run("input")

正确写法：

monitor = Monitor() monitor.start() # ✅ 第一行就启动 pipeline = Pipeline([agent1, agent2]) # Pipeline 初始化事件会被捕获 result = pipeline.run("input")

此外，确保你的工作目录有写入权限。如果logs/目录被设为只读，Monitor会静默失败。执行ls -ld logs查看权限，必要时chmod 755 logs。

4.5 “Python 安装详细步骤”陷阱：别用apt install python3装生产环境

Ubuntu 的apt install python3安装的是系统 Python，它被 OS 依赖，绝对不要用pip install往里面装第三方包！否则极易破坏apt的依赖关系，导致sudo apt upgrade失败。

安全做法永远是：

• 用apt install python3-venv安装虚拟环境支持。
• 用python3 -m venv myproject_env创建隔离环境。
• 用source myproject_env/bin/activate激活后，再pip install。

这是 Linux 系统管理的铁律，和 AgentScope 无关，但却是无数新手翻车的根源。

5. 从“跑通”到“用好”：三个必做的进阶动作

跑通第一个 Pipeline 只是起点。要真正把 AgentScope 2.0 变成你的生产力工具，这三个动作，一个都不能少。

5.1 动手改写WeatherAgent，接入真实 API

把weather_agent.py里的mock_data替换为真实的 HTTP 调用。我推荐使用免费的 Open-Meteo API，它无需 Key，响应快：

# 替换 weather_agent.py 中的 __call__ 方法 def __call__(self, city: str) -> dict: # 使用 Open-Meteo 的地理编码 API 获取经纬度 geo_url = f"https://geocoding-api.open-meteo.com/v1/search?name={city}&count=1&language=en&format=json" geo_resp = requests.get(geo_url).json() if not geo_resp.get("results"): raise ValueError(f"City '{city}' not found") lat = geo_resp["results"][0]["latitude"] lon = geo_resp["results"][0]["longitude"] # 使用经纬度获取天气 weather_url = f"https://api.open-meteo.com/v1/forecast?latitude={lat}&longitude={lon}&current=temperature_2m,weather_code&timezone=auto" weather_resp = requests.get(weather_url).json() current = weather_resp["current"] weather_code = current["weather_code"] # 天气码映射表（简化版） weather_map = {0: "Clear sky", 1: "Mainly clear", 2: "Partly cloudy", 3: "Overcast", 45: "Fog", 48: "Depositing rime fog", 51: "Light drizzle", 53: "Moderate drizzle", 55: "Dense drizzle", 56: "Light freezing drizzle", 57: "Moderate freezing drizzle", 61: "Slight rain", 63: "Moderate rain", 65: "Heavy rain", 66: "Light freezing rain", 67: "Moderate freezing rain", 71: "Slight snow fall", 73: "Moderate snow fall", 75: "Heavy snow fall", 77: "Snow grains", 80: "Slight rain showers", 81: "Moderate rain showers", 82: "Violent rain showers", 85: "Slight snow showers", 86: "Heavy snow showers", 95: "Thunderstorm", 96: "Thunderstorm with slight hail", 99: "Thunderstorm with heavy hail"} condition = weather_map.get(weather_code, "Unknown") temp = current["temperature_2m"] msg = Msg( name=self.name, content=f"Weather in {city}: {condition}, {temp}°C", role="assistant", metadata={"raw_data": {"temp": temp, "condition": condition, "weather_code": weather_code}} ) return msg

这个改动带来的质变：

• 你不再依赖模拟数据，而是和真实世界产生了连接。
• 你学会了如何处理 API 的两级调用（先地理编码，再天气查询）。
• 你理解了requests的异常处理（try-except包裹requests.get），这是生产环境的必备技能。

5.2 给 Pipeline 加上“人工审核”环节

真正的业务流程，不可能 100% 自动化。加入一个HumanReviewAgent，当天气温度超过 35°C 时，强制人工确认周报内容：

# human_review_agent.py from agentscope.agents import Agent from agentscope.message import Msg class HumanReviewAgent(Agent): def __init__(self, name: str = "HumanReviewer") -> None: super().__init__(name=name) def __call__(self, weather_data: dict) -> dict: # 从 metadata 中提取温度 temp = weather_data.get("raw_data", {}).get("temp", 0) if temp > 35: # 温度过高，需要人工确认 content = f"⚠️ 高温预警！检测到 {temp}°C，是否仍按原计划生成周报？请回复 'YES' 或 'NO'" msg = Msg(name=self.name, content=content, role="assistant", metadata={"need_review": True}) else: # 温度正常，自动通过 msg = Msg(name=self.name, content="✅ 温度正常，自动通过审核", role="assistant", metadata={"need_review": False}) return msg

然后修改main.py的 Pipeline：

# pipeline = Pipeline([weather_agent, human_review_agent, report_agent]) # 这样，流程就变成了：查天气 → 人工审核 → 生成报告

这个设计体现了 AgentScope 的核心优势：混合编排。你可以无缝地把规则判断