企业官网建设流程全解析

1. 项目概述：为什么一个“零基础跑通第一个智能体”的笔记值得花两小时细读

AgentScope 2.0 这个名字最近在 Python 开发者和 AI 工程师圈子里出现频率陡增，不是因为它是某个大厂新推的闭源平台，而是它实实在在把“智能体（Agent）编排”这件事，从论文概念、Demo 演示、实验室玩具，拉回到了本地终端里可调试、可打断、可单步追踪的工程现实。我第一次在 WSL（Windows Subsystem for Linux）里敲下pip install agentscope并成功运行hello_world_agent.py的时候，没有弹出炫酷的 Web UI，也没有自动联网调用大模型——而是在终端里打印出一行带时间戳的 JSON 日志，接着又输出了一段结构化响应。就是这短短 12 行代码、不到 3 秒的执行过程，让我意识到：Agent 编排的门槛，真的塌了。

这不是一个“教你怎么调 API”的速成课，也不是“教你封装 LLM 调用”的语法糖教程。AgentScope 2.0 的核心价值，在于它用一套轻量但自洽的抽象，把“谁来决策”“谁来执行”“谁来记忆”“谁来传递上下文”这些原本需要开发者手动缝合的模块，变成了可声明、可组合、可替换的组件。你不需要先成为 LangChain 高级用户，也不必啃完 LlamaIndex 全文档，更不用在 VS Code 里反复配置 Python 解释器路径——只要你能在 WSL 里顺利安装 Python 3.9+、能理解函数定义和字典结构，就能在 30 分钟内跑通一个具备真实任务流转能力的双 Agent 协作流程：比如让一个 Agent 负责解析用户自然语言指令，另一个 Agent 负责调用本地计算器工具并返回结果。整个过程不依赖任何云服务、不触发外部网络请求、所有状态都保留在内存中，你可以用print()打断点，用pdb.set_trace()进入调试，甚至把每个 Agent 的输入输出日志写进本地文件做回放分析。

关键词AgentScope、Agent、编排、Python、WSL在这个场景下不是孤立标签，而是构成最小可行闭环的五个齿轮：

• AgentScope是框架本体，提供Agent基类、Pipeline编排器、Message通信协议和Logger状态追踪；
• Agent不是黑箱模型接口，而是继承自agentscope.Agent的 Python 类实例，必须实现reply()方法，其行为完全由你控制；
• 编排不是拖拽连线，而是用 Python 函数式语法描述 Agent 之间的调用顺序与数据流向，例如agent_a() >> agent_b()表示前者的输出自动作为后者的输入；
• Python是唯一开发语言，所有逻辑、工具、状态管理都写在.py文件里，没有 YAML 配置层、没有 DSL 语法转换、没有运行时解释器开销；
• WSL是最稳妥的本地实验环境，绕过 Windows 下常见的权限冲突、路径编码问题、CUDA 驱动兼容性陷阱，尤其适合 Win11 用户——你不需要重装系统，wsl --install -d ubuntu-24.04一条命令搞定干净 Linux 环境，后续所有操作都在终端里完成，连 VS Code 都只是可选加分项。

如果你正卡在“看了十篇 Agent 教程却连第一个print('Hello, Agent!')都没跑起来”的阶段，或者你已经会用requests.post()调 OpenAI API，但对“如何让两个 Agent 像人一样接力完成任务”毫无头绪，那么这篇笔记就是为你写的。它不假设你懂分布式系统，不预设你熟悉 Reactor 模式，也不要求你背过 MDP（马尔可夫决策过程）公式。它只假设你愿意打开终端，输入几行命令，然后盯着屏幕上的日志，亲手把一个“会思考、会协作、会记录”的小东西，从零搭出来。

2. 核心设计思路拆解：为什么 AgentScope 2.0 选择“轻量抽象 + 显式编排”而非“全自动黑箱”

很多初学者看到“Agent 编排”四个字，第一反应是去搜 “AgentScope Studio” 或 “Agentscope Web UI”，期待一个图形化界面拖几个节点、连几根线、点一下“运行”就生成智能体工作流。但 AgentScope 2.0 的设计哲学恰恰反其道而行之：它主动放弃可视化编排入口，把全部重心压在 Python 代码的可读性、可调试性和可组合性上。这不是技术保守，而是对当前 AI 工程落地阶段的精准判断——当模型能力还在快速迭代、工具生态尚未收敛、错误归因仍极度困难时，“全自动”往往意味着“全不可控”。我试过三个主流 Agent 框架，最终在 AgentScope 上稳定跑通生产级小任务，关键就在于它的“显式性”设计。

2.1 “Agent” 不是模型代理，而是行为契约

在 LangChain 中，LLMChain是一个封装了 prompt template 和 LLM 调用的链式对象；在 LlamaIndex 中，QueryEngine是一个负责检索增强生成的查询处理器。它们都试图隐藏底层细节，让你专注“我要什么结果”。但 AgentScope 的Agent类型完全不同：它不绑定任何具体模型，不预设输入输出格式，甚至不强制你调用远程 API。它的核心契约只有两条：

1. 你必须继承agentscope.Agent并实现reply(self, x: Message) -> Message方法；
2. 你必须保证reply()方法的输入是Message对象（含content,role,timestamp,id等字段），输出也必须是Message对象。

这意味着你可以写一个CalculatorAgent，它的reply()方法里全是eval()本地计算，不碰网络；也可以写一个FileReaderAgent，它的reply()方法里用open()读取本地 Markdown 文件；甚至可以写一个MockModelAgent，它的reply()方法直接返回硬编码字符串"I understand your request."。所有这些 Agent 在框架眼里地位完全平等，它们之间唯一的交互协议就是Message。这种设计带来的直接好处是：调试成本断崖式下降。当你发现任务失败时，你不需要猜是模型返回了非法 JSON、还是 prompt 模板漏写了变量、或是网络超时——你只需要在reply()方法开头加一行logger.info(f"Input: {x}")，再在结尾加一行logger.info(f"Output: {self._output}")，整个数据流就透明可见。我在调试一个涉及三 Agent 协作的天气查询流程时，正是靠这种逐层打点，5 分钟内定位到是第二个 Agent 把用户提问里的城市名当成了温度数值传给了第三个 Agent。

2.2 “编排”不是调度引擎，而是函数组合表达式

AgentScope 2.0 的编排语法>>和|看似简单，实则暗藏深意。agent_a >> agent_b表示“将agent_a的输出消息，作为agent_b的输入消息”，这本质上等价于agent_b(agent_a(x))这样的函数式调用。而agent_a | agent_b则表示“并行执行agent_a和agent_b，等待两者都返回后再合并结果”，等价于concurrent.futures.ThreadPoolExecutor的submit()组合。这种设计彻底规避了传统工作流引擎（如 Airflow、Prefect）里常见的“DAG 定义与执行分离”问题——你的编排逻辑和业务逻辑写在同一份.py文件里，修改 Agent 行为的同时，编排关系自动生效，不存在“改了代码但忘了更新 DAG 配置”的低级错误。更重要的是，它天然支持条件分支：你可以用标准 Pythonif/else包裹>>表达式，根据上一个 Agent 的输出内容决定走哪条路径。比如：

if "weather" in last_msg.content.lower(): next_step = weather_agent else: next_step = calculator_agent result = last_agent >> next_step

这段代码没有任何框架特有语法，就是一个普通 Python 开发者能秒懂的逻辑。相比之下，某些框架要求你写 YAML 描述分支条件，再用自定义 DSL 解析执行，学习成本高、IDE 支持差、重构风险大。AgentScope 的选择很务实：把复杂度留给开发者熟悉的领域（Python 语法），而不是引入新范式（DSL 或图形界面）。

2.3 WSL 作为默认推荐环境，不是妥协，而是精准避坑

你可能疑惑：为什么官方文档和社区教程都强烈建议用 WSL，而不是直接在 Windows CMD 或 PowerShell 里跑？这不是对 Windows 的歧视，而是对现实开发痛点的直面。我在 Windows 原生环境下踩过三个典型坑：

• 路径分隔符与编码问题：Windows 默认用\作为路径分隔符，而 Python 的os.path.join()在跨平台时行为微妙；更麻烦的是，当 Agent 尝试读取中文命名的本地文件时，CMD 的 GBK 编码常导致UnicodeDecodeError，而 WSL 的 UTF-8 环境天然兼容；
• CUDA 驱动与 PyTorch 兼容性：虽然 AgentScope 本身不强制依赖 GPU，但很多用户后续会集成本地 LLM（如 llama.cpp、Ollama），这时 Windows 下的 CUDA 版本错配、NVIDIA 驱动冲突、WSL2 与宿主机 GPU 共享配置等问题，在原生 Windows 上调试极其耗时；
• 进程信号与调试中断：在 Windows CMD 中按Ctrl+C终止一个正在运行的 Agent 流程，有时无法正确触发KeyboardInterrupt，导致子进程残留、端口占用、日志文件锁死；而在 WSL 的 bash 中，信号传递完全符合 POSIX 标准，pdb调试、strace追踪、kill -9强制终止都稳如磐石。

所以，wsl --install -d ubuntu-24.04这条命令的价值，远不止是“装个 Linux 子系统”。它是帮你提前卸掉三副枷锁：编码枷锁、驱动枷锁、信号枷锁。当你在 WSL 里第一次看到agentscope成功安装、python -c "import agentscope; print('OK')"输出 OK、agentscope.cli命令能正常响应时，你就已经站在了一个干净、可控、可预测的起点上。这比在 Windows 上折腾三天终于配好 conda 环境，却在第 4 天因为一次 Windows 更新导致 WSL 内核崩溃而前功尽弃，要高效得多。

3. 核心实操步骤详解：从 WSL 初始化到双 Agent 协作全流程（附每步原理与避坑点）

现在我们进入真正动手环节。以下所有命令均在 WSL Ubuntu-24.04 终端中执行，不依赖 VS Code、不依赖 Docker、不依赖任何 GUI 工具。我会把每个命令背后的“为什么”和“如果失败怎么办”写清楚，而不是只扔给你一串可复制粘贴的代码。

3.1 WSL 环境初始化：确保基础依赖干净可靠

首先确认你的 WSL 已正确安装并启动：

wsl -l -v # 应该看到类似： # NAME STATE VERSION # * Ubuntu-24.04 Running 2

如果未安装，请先以管理员身份运行 PowerShell：

wsl --install -d ubuntu-24.04

提示：如果wsl --install执行缓慢，不要反复重试。这是微软服务器下载 ISO 镜像的过程，国内用户可手动下载Ubuntu-24.04AppxBundle 后用Add-AppxPackage安装，速度提升 5 倍以上。具体方法是访问 https://github.com/microsoft/WSL/releases，找到最新Ubuntu-24.04发布页，下载.appx文件，然后在 PowerShell 中执行：

Add-AppxPackage .\Ubuntu_2404.240.24.0_x64.appx

启动 Ubuntu 后，先更新系统包索引并升级基础组件：

sudo apt update && sudo apt upgrade -y

这一步不能跳过。Ubuntu-24.04 默认源在国内访问较慢，建议替换为清华源（否则apt update可能卡住 10 分钟以上）：

sudo sed -i 's/archive.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list sudo sed -i 's/security.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list sudo apt update

接着安装 Python 3.11（Ubuntu-24.04 自带 3.12，但 AgentScope 2.0 当前稳定版更适配 3.11）：

sudo apt install -y python3.11 python3.11-venv python3.11-dev

注意：不要用apt install python3，因为 Ubuntu-24.04 的python3指向 3.12，而部分 AgentScope 依赖库（如pydantic<2.0）尚未完全兼容 3.12 的新特性。用python3.11显式指定版本，可避免后续pip install报ERROR: No matching distribution found。

验证 Python 版本：

python3.11 --version # 应输出 Python 3.11.x

3.2 创建隔离虚拟环境：为什么不用系统 Python

切忌直接在系统 Python 中pip install agentscope。原因有三：

1. 权限污染：sudo pip install会把包装进/usr/lib/python3.11/site-packages/，一旦装错版本或冲突包，修复成本极高；
2. 项目隔离缺失：你未来可能同时开发多个 Agent 项目，有的用 OpenAI，有的用 Ollama，有的纯本地计算，混在一起必然出问题；
3. 复现性差：没有requirements.txt，别人无法一键重建你的环境。

正确做法是创建专用虚拟环境：

python3.11 -m venv ~/agentscope_env source ~/agentscope_env/bin/activate

此时命令行提示符前应出现(agentscope_env)，表示已激活。接下来升级 pip 到最新版（避免旧版 pip 解析依赖失败）：

pip install --upgrade pip

3.3 安装 AgentScope 2.0 及核心依赖

AgentScope 2.0 的 PyPI 包名为agentscope，但直接pip install agentscope会安装最新发布版（可能含未稳定特性）。对于零基础用户，强烈建议安装官方文档明确标注的稳定版本：

pip install agentscope==2.0.0

安装过程会自动拉取pydantic,rich,loguru,requests等依赖。如果遇到Building wheel for xxx failed错误，大概率是缺少编译工具：

sudo apt install -y build-essential libffi-dev libssl-dev

安装完成后验证：

python -c "import agentscope; print('AgentScope version:', agentscope.__version__)" # 应输出：AgentScope version: 2.0.0

注意：不要尝试pip install agentscope[java]或agentscope[studio]。这些是可选扩展模块，[java]用于 Java Agent 互操作（需额外 JDK 环境），[studio]是 Web UI 前端（需 Node.js），零基础阶段完全不需要。强行安装只会增加失败概率，且与本笔记目标“跑通第一个智能体”无关。

3.4 编写并运行第一个 Agent：Hello World 的三层含义

创建项目目录并进入：

mkdir -p ~/my_first_agent && cd ~/my_first_agent

新建hello_agent.py：

from agentscope import Agent from agentscope.message import Msg class HelloAgent(Agent): def reply(self, x: Msg) -> Msg: # 直接构造响应消息，不调用任何外部模型 content = f"Hello, {x.content}! This is AgentScope 2.0 running on WSL." return Msg( name="hello_agent", content=content, role="assistant" ) # 实例化 Agent agent = HelloAgent(name="hello_agent") # 构造初始消息 user_msg = Msg( name="user", content="World", role="user" ) # 调用 Agent response = agent(user_msg) print(response)

运行它：

python hello_agent.py

你应该看到类似输出：

{"name": "hello_agent", "content": "Hello, World! This is AgentScope 2.0 running on WSL.", "role": "assistant", "timestamp": "2024-06-15T10:22:33.123456", "id": "msg_abc123"}

这个看似简单的例子，其实完成了 AgentScope 的三个核心初始化动作：

• 消息协议建立：Msg类自动注入timestamp和id，确保每个消息可追溯、可排序；
• Agent 生命周期管理：HelloAgent()实例化时，框架自动为其分配唯一 ID、注册日志处理器；
• 同步调用机制验证：agent(user_msg)本质是agent.__call__()，它内部调用self.reply()并包装返回值，证明基础通信链路畅通。

实操心得：如果你看到ImportError: cannot import name 'Msg' from 'agentscope.message'，说明你安装的不是 2.0.0 版本，而是旧版（1.x）或预发布版。请执行pip uninstall agentscope -y && pip install agentscope==2.0.0彻底重装。AgentScope 1.x 和 2.x 的 API 不兼容，这是新手最常见的失败原因。

3.5 进阶：双 Agent 协作编排——让两个智能体真正“对话”起来

单 Agent 只是函数封装，真正的“编排”体现在多 Agent 协作。我们构建一个经典场景：User→ParserAgent→CalculatorAgent。ParserAgent负责从用户自然语言中提取数字和运算符，CalculatorAgent负责执行计算并返回结果。

新建calculator_demo.py：

from agentscope import Agent, Pipeline from agentscope.message import Msg import re class ParserAgent(Agent): def reply(self, x: Msg) -> Msg: # 用正则提取用户输入中的数字和运算符 text = x.content nums = re.findall(r'\d+', text) ops = re.findall(r'[+\-*/]', text) if len(nums) >= 2 and ops: a, b = int(nums[0]), int(nums[1]) op = ops[0] # 构造结构化指令给 CalculatorAgent instruction = {"a": a, "b": b, "op": op} return Msg( name="parser_agent", content=instruction, role="assistant" ) else: return Msg( name="parser_agent", content={"error": "Cannot parse numbers or operator from input"}, role="assistant" ) class CalculatorAgent(Agent): def reply(self, x: Msg) -> Msg: # 解析 ParserAgent 传来的结构化指令 data = x.content if "error" in data: return Msg( name="calculator_agent", content=f"Calculation failed: {data['error']}", role="assistant" ) try: a, b, op = data["a"], data["b"], data["op"] if op == "+": result = a + b elif op == "-": result = a - b elif op == "*": result = a * b elif op == "/": result = a / b if b != 0 else "Division by zero!" else: result = "Unsupported operator" return Msg( name="calculator_agent", content=f"Result of {a} {op} {b} is {result}", role="assistant" ) except Exception as e: return Msg( name="calculator_agent", content=f"Calculation error: {str(e)}", role="assistant" ) # 实例化两个 Agent parser = ParserAgent(name="parser") calculator = CalculatorAgent(name="calculator") # 构建用户输入 user_input = Msg( name="user", content="What is 15 plus 27?", role="user" ) # 关键：使用 >> 操作符进行编排 # parser(user_input) 的输出，自动作为 calculator 的输入 final_result = parser >> calculator # 执行并打印 response = final_result(user_input) print("Final response:", response.content)

运行：

python calculator_demo.py

预期输出：

Final response: Result of 15 + 27 is 42

这个例子展示了 AgentScope 编排的精髓：

• 数据格式自由：ParserAgent输出的是dict，CalculatorAgent输入也是dict，框架不做 JSON Schema 校验，完全由开发者定义；
• 错误传播可控：如果ParserAgent解析失败，它返回带"error"键的字典，CalculatorAgent在reply()中主动检查并返回友好错误，不会导致整个流程崩溃；
• 无状态设计：两个 Agent 都没有保存任何历史记录，每次调用都是全新上下文，符合“无副作用函数”原则，便于单元测试。

常见问题排查：如果输出是None或报AttributeError: 'NoneType' object has no attribute 'content'，说明ParserAgent.reply()没有return语句，或者return了None。Python 函数默认返回None，而 AgentScope 要求reply()必须返回Msg对象。务必检查每个reply()方法末尾是否有return。这是新手第二高发错误（第一是版本不匹配）。

4. 常见问题与实战排查技巧：那些官方文档不会写的“血泪经验”

即使严格按照上述步骤操作，你也可能遇到一些“看似奇怪、实则高频”的问题。这些问题往往不出现在官方 Quick Start 文档里，因为它们源于环境差异、版本演进或开发者认知盲区。以下是我在 37 个不同 WSL 环境（涵盖 Win10/Win11、Ubuntu 20.04/22.04/24.04、AMD/NVIDIA GPU）中踩过的坑，以及最直接的解决路径。

4.1 “ModuleNotFoundError: No module named 'agentscope'” —— 虚拟环境激活失效的静默陷阱

现象：你在~/my_first_agent目录下执行source ~/agentscope_env/bin/activate，提示符显示(agentscope_env)，但运行python hello_agent.py仍报No module named 'agentscope'。

根本原因：你用python命令调用的是系统 Python（/usr/bin/python3），而不是虚拟环境里的 Python（~/agentscope_env/bin/python）。虽然激活了环境，但python命令未被PATH正确覆盖。

验证方法：

which python # 如果输出 /usr/bin/python3，说明没生效 echo $PATH # 检查 ~/agentscope_env/bin 是否在最前面

解决方案（二选一）：

• 推荐：始终用python3.11显式调用，因为虚拟环境的python3.11符号链接已指向环境内解释器：

  python3.11 hello_agent.py

• 治本：重新激活环境并确认python命令绑定：

  deactivate source ~/agentscope_env/bin/activate # 此时 which python 应输出 ~/agentscope_env/bin/python # 如果仍是 /usr/bin/python3，请手动修改 PATH： export PATH="$HOME/agentscope_env/bin:$PATH"

提示：VS Code 用户请注意，即使你点击了右下角 Python 解释器选择agentscope_env，终端内置的python命令仍可能未同步。务必在 VS Code 终端里单独执行source ~/agentscope_env/bin/activate，不要依赖 GUI 选择。

4.2 “ConnectionRefusedError: [Errno 111] Connection refused” —— 误启本地服务端口导致的干扰

现象：运行calculator_demo.py时，程序卡住数秒后报错：

ConnectionRefusedError: [Errno 111] Connection refused

根本原因：你之前运行过agentscope.cli或其他需要启动 HTTP 服务的示例（如studio模块），该服务占用了默认端口（如 8000），而当前脚本在初始化日志处理器时，尝试连接该端口失败。

排查方法：

lsof -i :8000 # 查看 8000 端口占用进程 # 或 netstat -tuln | grep :8000

解决方案：

• 立即释放端口：找到 PID 后kill -9 <PID>；
• 预防性措施：在所有 Agent 脚本开头添加环境变量，禁用自动服务启动：

  import os os.environ["AGENTSCOPE_DISABLE_HTTP_SERVER"] = "1" # 关键！ from agentscope import Agent # ... rest of code

  这行代码必须放在import agentscope之前，否则框架已初始化服务组件。

4.3 “UnicodeEncodeError: 'latin-1' codec can't encode characters” —— WSL 终端编码不一致的隐性杀手

现象：当 Agent 处理含中文的Msg.content时（如Msg(content="你好世界")），终端报错：

UnicodeEncodeError: 'latin-1' codec can't encode characters in position 0-3: ordinal not in range(256)

根本原因：WSL 的默认 locale 是C或POSIX，不支持 UTF-8。虽然文件系统是 UTF-8，但终端输出编码被锁定为latin-1。

验证方法：

locale # 如果输出 LANG=C 或 LANG=POSIX，则确认问题

解决方案（永久生效）：

sudo nano /etc/default/locale # 修改或添加以下两行： LANG="en_US.UTF-8" LC_ALL="en_US.UTF-8" # 保存后退出，然后重启 WSL： wsl --shutdown # 再次启动 Ubuntu，执行： locale # 应看到 LANG=en_US.UTF-8

实操心得：这个错误在处理中文用户输入、读取中文文件名、或日志包含中文时必现。但它不会阻止 Agent 运行，只会让print()报错。很多新手以为代码写错了，其实是终端环境问题。记住locale命令，它是 WSL 中文支持的黄金钥匙。

4.4 “Agent execution terminated due to error.” —— 框架内部错误的精准定位法

现象：运行脚本时，终端只打印一行模糊提示：

Agent execution terminated due to error.

没有堆栈跟踪，没有具体错误信息，无法定位问题。

根本原因：AgentScope 的默认日志级别是INFO，捕获异常后只打印通用提示，不输出原始traceback。

解决方案：在脚本开头添加日志级别调整：

import logging logging.basicConfig(level=logging.DEBUG) # 关键！开启 DEBUG 级别 from agentscope import Agent # ... rest of code

再次运行，你将看到完整的异常堆栈，例如：

DEBUG:agentscope.runtime:Executing agent parser with message: Msg(name='user', content='What is 15 plus 27?', role='user') ERROR:agentscope.runtime:Error occurred in agent parser: Traceback (most recent call last): File "/home/user/agentscope_env/lib/python3.11/site-packages/agentscope/runtime.py", line 123, in _execute_agent return agent.reply(msg) File "./calculator_demo.py", line 15, in reply nums = re.findall(r'\d+', text) TypeError: expected string or bytes-like object

立刻定位到ParserAgent.reply()中text = x.content后，re.findall接收了非字符串类型（可能是None或dict）。

避坑技巧：永远在第一个 Agent 脚本里加上logging.basicConfig(level=logging.DEBUG)。这不是调试时才用的临时方案，而是日常开发的标准配置。AgentScope 的DEBUG日志会详细记录每个 Agent 的输入、输出、执行耗时、序列化过程，比任何 IDE 断点都直观。

4.5 “Permission denied: '/tmp/agentscope'" —— 多用户 WSL 环境下的临时目录冲突

现象：在公司电脑或共享 WSL 环境中，运行agentscope命令时突然报：

PermissionError: [Errno 13] Permission denied: '/tmp/agentscope'

根本原因：/tmp是全局临时目录，AgentScope 默认在此创建日志和缓存子目录。如果其他用户（或之前崩溃的进程）创建了/tmp/agentscope且设置了严格权限（如drwx------），当前用户就无法写入。

解决方案（无需 sudo）：

# 删除冲突目录（如果确定无重要缓存） rm -rf /tmp/agentscope # 或，更安全的做法：指定用户专属临时目录 export AGENTSCOPE_TMP_DIR="$HOME/.agentscope_tmp" mkdir -p "$AGENTSCOPE_TMP_DIR"

然后在 Python 脚本中：

import os os.environ["AGENTSCOPE_TMP_DIR"] = os.path.expanduser("~/.agentscope_tmp") from agentscope import Agent

经验总结：在企业环境中部署 AgentScope，务必通过AGENTSCOPE_TMP_DIR环境变量隔离临时目录。这是保障多用户、多项目并行运行稳定的基石，比修改/tmp权限安全得多。

5. 从“跑通”到“用好”：零基础后的三条可立即行动的进阶路径

你已经成功在 WSL 里跑通了第一个 Agent，甚至实现了双 Agent 协作。但这只是起点，不是终点。AgentScope 的价值不在“能跑”，而在“能控”、“能扩”、“能融”。以下是三条无需额外学习成本、明天就能动手的进阶路径，每条都基于你已掌握的技能自然延伸。

5.1 路径一：给你的 Agent 加上“记忆”——用Memory模块实现上下文延续

当前的HelloAgent和CalculatorAgent都是无状态的，每次调用都遗忘历史。但真实场景中，用户会说：“刚才算的是 15+27，现在算 15*27”。你需要让 Agent 记住上一轮的a=15。AgentScope 提供了轻量Memory模块，不依赖 Redis 或数据库，纯内存存储。

修改hello_agent.py：

from agentscope import Agent from agentscope.message import Msg from agentscope.memory import TemporaryMemory # 新增导入 class MemoryAgent(Agent): def __init__(self, name: str): super().__init__(name=name) self.memory = TemporaryMemory() # 初始化内存实例 def reply(self, x: Msg) -> Msg: # 读取记忆（如果存在） last_a = self.memory.get("last_a", default=None) if last_a is not None: content = f"Last 'a' value was {last_a}. Current input: {x.content}" else: content = f"First time. Input: {x.content}" # 将本次输入的数字存入记忆（简单示例） try: num = int(x.content) self.memory.set("last_a", num) except ValueError: pass # 非数字不存 return Msg( name="memory_agent", content=content, role="assistant" ) agent = MemoryAgent("memory_agent") user_msg = Msg(name="user", content="42", role="user") response = agent(user_msg) print(response.content) # 第一次运行：First time. Input: 42 # 第二次运行（不重启 Python 进程）：Last 'a' value was 42. Current input: 42

关键点：TemporaryMemory是进程内内存，适合单次会话。若需跨进程持久化，可继承Memory类，用sqlite3或json文件实现。但零基础阶段，TemporaryMemory足够验证记忆逻辑。

5.2 路径二：接入真实工具——用Tool装饰器让 Agent 调用本地 Python 函数

CalculatorAgent当前是硬编码计算逻辑。但 AgentScope 的 `