agentscope-ai/agentscope · 上手攻略

• 仓库：agentscope-ai/agentscope
• 链接：https://github.com/agentscope-ai/agentscope
• 分类：ai / agent / llm-infra
• 作者：Jay
• 更新：2026-07-09

👀 它是什么

AgentScope 是一个面向生产环境、易用且高度可扩展的多 Agent 框架，由阿里巴巴达摩院开发维护，2026 年 5 月发布了 2.0 大版本。核心理念是："Build and run agents you can see, understand and trust"——让开发者能够可视化、可理解、可信赖地运行 Agent 系统。

AgentScope 2.0 的关键新特性：

• 事件驱动架构（Event System）：统一的事件总线，支持前端实时展示 Agent 思考过程。
• 权限系统（Permission System）：细粒度可配置的 Tool 和资源访问控制。
• 多租户 / 多会话服务：生产级服务支持，跨租户和会话的隔离。
• Workspace / Sandbox：工具和代码在隔离环境中运行，支持本地、Docker、E2B 后端。
• 可扩展中间件：组合式 Hook，定制 Agent 的推理-行动循环。
• 长期记忆（Long-term Memory）：支持 Mem0、ReMe 等记忆模块。

定位上，AgentScope 与 LangChain/CrewAI 同属 Agent 编排框架，但更侧重运行时可视化和生产级多 Agent 编排。

🧩 解决什么问题

当前主流 Agent 框架（LangChain、LlamaIndex Agent）在实际使用中有几个痛点：

1. 黑箱执行：Agent 在调用 Tool 时发生了什么，开发者难以追踪，只能靠日志盲调。
2. 多 Agent 协作复杂：多个 Agent 之间的消息路由、状态共享、团队协作没有统一抽象。
3. 生产部署困难：本地跑得通，部署到服务时需要大量改造。
4. 权限控制缺失：Agent 默认可以调用任意 Tool，没有细粒度权限管理。

AgentScope 的解法：

• 事件流（Event Stream）：Agent 的每一步（LLM 调用开始/结束、Tool 执行、文本块产生）都有事件推送，可以实时渲染到前端。
• Actor + 消息路由模型：每个 Agent 是独立的 Actor，通过消息传递协作，天然支持多 Agent 团队。
• Agent Service：一键将 Agent 部署为带 Web UI 的多租户服务。
• Permission System：声明式权限配置，控制 Agent 能调用哪些 Tool、访问哪些资源。

🚀 快速安装

基本安装

前置要求：Python 3.11+（AgentScope 2.0 不支持 Python 3.10 及以下）

pip install agentscope
# 或
uv pip install agentscope

从源码安装（开发者模式）

git clone -b main https://github.com/agentscope-ai/agentscope.git
cd agentscope
pip install -e .
# 或
uv pip install -e .

启动 Web UI 服务（多 Agent 服务）

git clone -b main https://github.com/agentscope-ai/agentscope.git
cd agentscope/examples/agent_service

# 启动后端服务
python main.py

# 另一个终端，启动前端
cd agentscope/examples/web_ui
pnpm install
pnpm dev
# 访问 http://localhost:3000

🔧 核心用法

用法 1：单 Agent（5 分钟上手）

import os
from agentscope.agent import Agent
from agentscope.tool import Toolkit, Bash, Grep, Glob, Read, Write, Edit
from agentscope.credential import DashScopeCredential
from agentscope.model import DashScopeChatModel
from agentscope.message import UserMsg
from agentscope.event import EventType
import asyncio

async def main():
    agent = Agent(
        name="Friday",
        system_prompt="You're a helpful assistant named Friday.",
        model=DashScopeChatModel(
            credential=DashScopeCredential(
                api_key=os.environ["DASHSCOPE_API_KEY"]
            ),
            model="qwen3.6-plus",    # 注：2026年模型名可能有更新
        ),
        toolkit=Toolkit(
            tools=[
                Bash(),
                Grep(),
                Glob(),
                Read(),
                Write(),
                Edit(),
            ]
        ),
    )

    # 事件流式处理
    async for evt in agent.reply_stream(UserMsg("Tony", "Hi, Friday!")):
        match evt.type:
            case EventType.REPLY_START:
                print("开始回复")
            case EventType.TEXT_BLOCK_DELTA:
                print(evt.data, end="", flush=True)
            case EventType.TOOL_CALL_START:
                print(f"\n[调用工具] {evt.data}")
            case EventType.TOOL_CALL_END:
                print(f"[工具返回] {evt.data}")

asyncio.run(main())

⚠️ 注意：上述示例使用阿里云 DashScope（通义千问）模型，也可以替换为其他支持的模型。qwen3.6-plus 模型名为 2026 年中旬版本，具体可用模型列表请参考 DashScope 官方文档。

用法 2：事件流与可视化

AgentScope 的核心优势在于事件流。以下是完整的事件类型：

from agentscope.event import EventType

async for evt in agent.reply_stream(user_msg):
    match evt.type:
        case EventType.REPLY_START:          # Agent 开始回复
            ...
        case EventType.MODEL_CALL_START:     # 开始 LLM 调用
            ...
        case EventType.MODEL_CALL_END:       # LLM 调用结束
            ...
        case EventType.TEXT_BLOCK_START:     # 开始输出文本块
            ...
        case EventType.TEXT_BLOCK_DELTA:     # 文本块增量
            print(evt.data, end="", flush=True)
        case EventType.TEXT_BLOCK_END:       # 文本块结束
            print()
        case EventType.TOOL_CALL_START:     # 开始调用 Tool
            print(f"\n🔧 调用: {evt.data}")
        case EventType.TOOL_CALL_END:       # Tool 执行结束
            ...
        case EventType.ERROR:               # 发生错误
            print(f"❌ 错误: {evt.data}")

用法 3：多 Agent 团队协作

from agentscope import Agent
from agentscope.model import OpenAIChatModel
from agentscope.message import UserMsg
import asyncio

researcher = Agent(
    name="Researcher",
    system_prompt="你是一名研究员，负责搜索和分析信息。",
    model=OpenAIChatModel(api_key=os.environ["OPENAI_API_KEY"], model="gpt-4o"),
)

writer = Agent(
    name="Writer",
    system_prompt="你是一名作家，负责将研究结果整理成文章。",
    model=OpenAIChatModel(api_key=os.environ["OPENAI_API_KEY"], model="gpt-4o"),
)

async def team_work():
    # 研究员搜索信息
    research_result = await researcher.async_reply(
        UserMsg("system", "搜索关于量子计算的最新进展")
    )
    # 作家整理成文
    article = await writer.async_reply(
        UserMsg("system", f"将以下内容整理成文章：{research_result}")
    )
    print(article)

asyncio.run(team_work())

用法 4：RAG（检索增强生成）

from agentscope.rag import RAGPipeline
from agentscope.embedding import OpenAIEmbedding

rag = RAGPipeline(
    embedding=OpenAIEmbedding(api_key=os.environ["OPENAI_API_KEY"]),
    vector_store="chroma",          # Chroma 是默认内置向量库
    collection_name="my_docs",
)

# 索引文档
rag.index_documents(["path/to/doc1.pdf", "path/to/doc2.txt"])

# 检索并生成
result = rag.query("某问题的答案是什么？")
print(result.answer)
print(f"来源: {result.sources}")

用法 5：长期记忆（Long-term Memory）

from agentscope.memory import Mem0Memory

memory = Mem0Memory(
    api_key=os.environ["MEM0_API_KEY"]   # 需要 Mem0 API Key
)

agent = Agent(
    name="Assistant",
    # ...
    memory=memory,
)

🎯 典型适用场景

⚠️ 坑与注意事项

1. Python 3.11+ 强制要求：AgentScope 2.0 不支持 Python 3.10，如果你在旧项目环境中安装会直接报错。
2. 默认模型需要配置：没有开箱即用的免费模型，需要配置 DashScope（阿里云）、OpenAI 或其他支持 API Key 的模型。
3. Web UI 需要额外依赖：前端用 pnpm，如果你的环境没有 Node.js/pnpm，需要额外安装。
4. 事件流需要 async/await：对于习惯了同步代码的开发者，事件流的 async 写法有学习成本。
5. 生产部署需要 K8s 或 Docker：虽然有 Agent Service，但多租户生产级部署需要一定的 DevOps 经验。
6. 文档中文资源有限：官方文档英文为主，中文社区资料较少，遇到问题多看 GitHub Issues 和 Discord。
7. Sentinel/权限系统复杂度：Permission System 功能强大但配置项多，简单场景下可以先跳过不用。

🔄 与同类对比

简评：AgentScope 最大的差异化在于事件驱动的可视化调试和生产级的多租户服务。如果你是 LangChain 老用户，受够了"Agent 跑起来不知道里面发生了什么"，AgentScope 的事件流会让你眼前一亮；如果你需要快速上线一个带 Web UI 的多 Agent 服务，AgentScope 的 Agent Service 比 LangChain 的 LangServe 更开箱即用。

✨ 一句话推荐结论

如果你在找一个能看见每一步思考过程、支持多 Agent 协作、而且能直接部署为 Web 服务的 Agent 框架，AgentScope 2.0 是 2026 年最值得关注的新选择——尤其是对已经厌倦了 LangChain 黑箱调试的团队。

📚 信息来源

• GitHub README（含中文）：https://github.com/agentscope-ai/agentscope
• 官方文档：https://docs.agentscope.io/
• GitHub Discussions / Issues：https://github.com/agentscope-ai/agentscope/issues
• Discord 社区：https://discord.gg/eYMpfnkG8h
• AgentScope 2.0 论文（arXiv）：https://arxiv.org/abs/2508.16279
• v1 论文（arXiv）：https://arxiv.org/abs/2402.14034