aiclawhot

如何使用开源的 AgentScope

open-source入门12 分钟阅读2026/7/2

上个月，我撞到了南墙。当时我正在搭建一个多步骤的研究流水线：需要一个 Agent 负责浏览网页，另一个将搜索结果综合成报告，第三个负责核实引用来源。我试着用一款流行的 Agent 框架把它们串联起来，但结果我花在跟回调循环、状态管理和执行报错死磕上的时间，比真正写业务逻辑的时间还要多。一旦 Agent 在执行长任务的中途挂掉，整个链路就会彻底崩溃，而调试简直就像在一堆 print 语句里大海捞针。

正是这种抓狂，让我找到了 AgentScope——一个开源的多 Agent 框架，它在构建 Agent 系统时采用了一种截然不同的思路。在用它搭建和部署了几个星期后，我可以带你看看它到底是怎么运作的——优缺点全包。

AgentScope 解决了什么问题

大多数 Agent 框架只是把 Agent 当作简单的“提示词-响应”包装器。但 AgentScope 的构建理念是基于这样一个现实：Agent 需要做实事——使用工具、管理长上下文、从故障中恢复，以及与其他 Agent 和人类进行协调。它是为团队所说的“智能体应用”设计的，在这种应用中，大模型（LLM）不再只是单纯响应，而是进行推理、行动和迭代。

其核心理念基于 ReAct 范式（Reason + Act，推理+行动），但 AgentScope 在此基础上进行了扩展，加入了系统性的异步设计、内置的工具权限以及运行时沙箱，这样你的 Agent 就能安全地执行代码，而不至于把你的基础设施搞崩溃。

入门：安装与配置

首先，我们来安装它。AgentScope 需要 Python 3.9 及以上版本：

pip install agentscope

为了获得包含可视化工作室和沙箱功能的完整体验，我建议安装全部附加组件：

pip install "agentscope[full]"

你需要配置的第一件事就是模型访问权限。AgentScope 支持多个模型供应商，并内置了重试和降级逻辑——光是这个功能就让我少头疼了好几个小时。创建一个名为 model_config.json 的配置文件：

{
  "model_configs": [
    {
      "config_name": "gpt-4o",
      "model_type": "openai_chat",
      "model_name": "gpt-4o",
      "api_key": "your-api-key-here"
    },
    {
      "config_name": "gpt-4o-mini-fallback",
      "model_type": "openai_chat",
      "model_name": "gpt-4o-mini",
      "api_key": "your-api-key-here"
    }
  ]
}

这个降级配置至关重要。当我批量运行 50 个研究任务时，主模型触发了频率限制。AgentScope 自动降级到了备用模型，我连一行重试循环的代码都没写。正是这种工程层面的支撑，把一个“玩具框架”和“生产级工具”区分了开来。

构建你的第一个 Agent

我们来搞点实用的：构建一个能搜索网页并总结结果的研究 Agent。AgentScope 提供了内置的 Agent 类，但你也可以自定义。

import agentscope
from agentscope.agents import ReActAgent
from agentscope.service import ServiceFactory

# 初始化框架
agentscope.init(model_configs="model_config.json")

# 创建一个具备网页搜索能力的研究 Agent
research_agent = ReActAgent(
    name="researcher",
    model_config_name="gpt-4o",
    service_list=[
        ServiceFactory.create("web_search"),
        ServiceFactory.create("text_summarization"),
    ],
    max_iters=5,
)

ReActAgent 是 AgentScope 的内置 Agent 之一。它会自动遵循“推理-行动-观察”的循环。当你给它一个任务时，它会推理出该用什么工具，调用该工具，观察结果，然后再决定是需要更多信息还是已经得出了最终答案。

运行起来也很简单：

result = research_agent("Research the latest developments in Rust's async ecosystem and provide a summary")
print(result.content)

让我惊喜的是它的透明度。AgentScope 会记录推理循环的每一步——Agent 想了什么、调用了哪个工具、传了什么参数，以及观察到了什么。当出现问题时，你真的能看清推理是在哪里崩坏的。

多 Agent 协作：重头戏来了

单个 Agent 固然不错，但真正的威力在于协作。我用三个 Agent 重建了我的研究流水线：

from agentscope.agents import ReActAgent, UserAgent
from agentscope.pipeline import SequentialPipeline

# 研究 Agent - 查找信息
researcher = ReActAgent(
    name="researcher",
    model_config_name="gpt-4o",
    service_list=[ServiceFactory.create("web_search")],
)

# 写作 Agent - 综合发现
writer = ReActAgent(
    name="writer",
    model_config_name="gpt-4o",
    service_list=[ServiceFactory.create("text_summarization")],
)

# 验证 Agent - 核实引用
verifier = ReActAgent(
    name="verifier",
    model_config_name="gpt-4o",
    service_list=[ServiceFactory.create("web_search")],
)

# 将它们串联起来
pipeline = SequentialPipeline([researcher, writer, verifier])

result = pipeline("Write a brief on quantum computing error correction with verified citations")

SequentialPipeline 会把上一个 Agent 的输出传给下一个。但 AgentScope 也支持更复杂的模式。对于可以并行执行的任务，有 ForkedPipeline；对于 Agent 之间的对话流，有 DialogPipeline。

我早期犯过一个错误，让我白白浪费了一下午：我试图让验证 Agent 直接修改写作 Agent 的输出。但在 AgentScope 中，每个 Agent 只能对它接收到的消息进行操作。解决办法是调整验证 Agent 的提示词，让它输出修改后的文本版本，而不仅仅是列出问题。一旦我理解了这种消息传递模型，一切就豁然开朗了。

沙箱：安全执行

对于自主 Agent，我最担心的之一就是安全性。一个能执行任意代码或进行无限制 API 调用的 Agent 绝对是个隐患。AgentScope 2.0 引入了运行时沙箱，可以隔离 Agent 的执行环境。

from agentscope.runtime import SandboxRuntime

# 创建沙箱环境
runtime = SandboxRuntime(
    workspace="./agent_workspace",
    permissions={
        "allow_network": True,
        "allow_file_write": True,
        "restricted_paths": ["/etc", "/var"],
    }
)

# 在沙箱内运行 Agent
with runtime:
    result = research_agent("Download and analyze the CSV from example.com/data.csv")

沙箱限制了 Agent 可以访问的内容。我特意构造了一个试图读取 /etc/passwd 的提示词来测试——沙箱干净利落地拦截了它，并记录了这次尝试。如果你打算让 Agent 处理用户提供的输入或在生产环境中运行，这个功能绝对是刚需。

记忆：让 Agent 拥有记忆

默认情况下，Agent 在不同会话之间是无状态的。但真实的应用需要持久化。AgentScope 集成了 ReMe，这是一个记忆管理工具包，能让 Agent 拥有持久且可检索的记忆。

from agentscope.memory import ReMeMemory

# 为 Agent 附加持久记忆
researcher.memory = ReMeMemory(
    storage_type="vector",
    persist_dir="./agent_memories/researcher",
)

# 现在 Agent 可以跨会话记忆了
researcher("I'm particularly interested in systems programming languages")
# ... 后续会话 ...
researcher("What's new in the programming language world?")
# Agent 会根据存储的偏好，优先考虑系统编程相关的话题

我发现这对我构建的个人助理 Agent 特别有用。它能记住我对引用格式的偏好、写作风格，甚至我信任哪些信息源。基于向量的检索意味着它不会把所有信息一股脑塞进上下文窗口，而是根据当前查询提取相关的记忆。

可视化工作室：调试长执行轨迹

调试 Agent 的行为是出了名的痛苦。AgentScope 内置了一个可视化工作室，让你可以追踪 Agent 执行的每一步。运行完一个流水线后，你可以这样启动工作室：

as-studio --log-dir ./runs/2024-01-15-research-pipeline

这会打开一个网页界面，你可以看到每个 Agent 的完整执行轨迹——每一步的推理、工具调用和观察结果。当我的验证 Agent 一直拒绝有效引用时，工作室向我展示了它误判了研究 Agent 的输出格式。我能准确看到导致混淆的消息，并据此调整提示词。

实话实说的局限性

用了几个星期后，以下是我发现 AgentScope 的不足之处：

文档缺口。 这个框架发展很快（AgentScope 2.0 刚发布），有些功能在 GitHub Issues 里的文档比官方文档还要详细。我花了一个让人崩溃的晚上才搞清楚配置自定义工具的正确方法，因为示例代码已经过时了。

Java 生态隔离。 面向企业级 JVM 应用有一个 AgentScope-Java，但它是一个独立的代码库，模式也有所不同。如果你需要 Agent 之间的 Python-Java 互操作，只能自己想办法桥接了。

资源消耗。 沙箱和记忆系统会增加开销。在我的机器上，运行三个带有持久记忆和沙箱的 Agent 大约消耗了 4GB 内存。对于简单任务来说，这感觉有些沉重。

HiClaw 的复杂性。 处理人在回路协作的多 Agent 操作系统是通过 Matrix 聊天室实现的，虽然功能强大，但学习曲线非常陡峭。我配置了一次就发现对我的用例来说有点杀鸡用牛刀了——除非你真的需要实时的人机协作，否则还是坚持用简单的流水线吧。

实用建议

  1. 从 ReActAgent 开始，然后再构建自定义 Agent。内置 Agent 已经正确处理了推理循环，你可以通过提示词和工具选择来定制行为。

  2. 一定要配置降级模型。 频率限制和 API 宕机是家常便饭。花两分钟设置降级模型，能为你省下无数运行失败的时间。

  3. 从第一天起就用可视化工作室。 别等到出了问题才用。尽早熟悉追踪界面，能在你需要调试时大幅提升速度。

  4. 针对消息传递设计提示词。 每个 Agent 接收到的输入就是上一个 Agent 的输出。在写 Agent 提示词时要牢记这一点——明确告诉每个 Agent，它应该为下一个 Agent 产出什么格式的结果。

  5. 部署前在沙箱中测试。 哪怕你对自己的提示词再放心，也要用对抗性输入在沙箱里测一测。在本地发现权限问题，总比在生产环境中发现要好得多。

AgentScope 不是最易上手的框架，但它是少数几个能真正应对生产级 Agent 系统那种混乱现实的框架——故障、安全、协作和调试。如果你要做的不仅仅是个 Demo，这些能力可比快速启动重要得多。

相关 Agent

O

OpenClaw

开源 AI Agent 框架，用于构建自主工作流

了解更多 →