AgentScope 2.0 快速入门：从第一个 Agent 到工具调用

Agent 开发看起来概念很多：Model、Tool、Memory、RAG、Middleware、Sandbox、Multi-Agent……如果一开始就把这些名词全部摊开，很容易把框架学成“API 背诵”。

AgentScope 反而适合用一个很简单的方式理解：先有一个会不断“思考 → 行动 → 观察”的 Agent，然后再给它接模型、工具、上下文、权限和运行环境。

本文基于 AgentScope 2.0。写作时 PyPI 最新稳定版为 2.0.6（2026-08-07），官方 latest 文档已经指向 2.0.7dev。2.0 相比 1.x 有明显 API 变化，网上旧教程不要直接照抄。

一、AgentScope 是什么？

AgentScope 是一个开源 Agent 开发框架。2.0 的目标不只是“让模型调用工具”，而是从 Agent SDK 一直覆盖到上下文管理、权限、Sandbox、RAG、长期记忆、Middleware、事件流和 Agent Service。

它的核心不是预先写死一大堆流程，而是尽量利用模型自身的 reasoning 和 tool use 能力，再由框架提供工程边界。

可以先把它理解成下面这张图：

最重要的几个概念：

• Agent：推理和行动循环的核心。

• Model：LLM，例如 Qwen、OpenAI、DeepSeek、Claude、Gemini、Ollama。

• Toolkit：Agent 能使用的工具集合，可包含 Python Tool、MCP、Skill。

• Context：当前任务需要携带的上下文，不只是聊天记录。

• Permission：决定工具调用能否执行、是否需要用户确认。

• Workspace / Sandbox：给文件读写、Shell、代码执行提供受控运行环境。

• Middleware：在 Agent 生命周期关键位置插入日志、权限、上下文压缩等横切逻辑。

所以 AgentScope 并不是单纯的“多 Agent 库”。多 Agent 只是它能支持的一种应用形态。

二、先注意版本：不要把 1.x 教程和 2.0 混着写

这是现在学习 AgentScope 最容易踩的坑。

老教程里经常能看到：

• ReActAgent

• Msg

• 单独配置 Formatter

• 旧版 Toolkit 注册方式

而当前 2.0 主线已经把核心抽象进一步收敛到 Agent，消息、事件、权限、上下文等能力也做了较大调整。

如果新项目直接开始，建议以官方 2.x 文档为准。

三、安装 AgentScope

AgentScope 2.0 要求 Python 3.11+，官方推荐使用 uv。

uv pip install agentscope

如果需要完整可选依赖：

# Windows
uv pip install agentscope[full]

# macOS / Linux
uv pip install agentscope\[full\]

确认版本：

import agentscope

print(agentscope.__version__)

四、第一个 Agent

先不要加 RAG、Memory、多 Agent，第一步只做一个最小 Agent。

下面使用 DashScope 作为模型提供商：

import asyncio
import os

from agentscope.agent import Agent
from agentscope.credential import DashScopeCredential
from agentscope.message import UserMsg
from agentscope.model import DashScopeChatModel
from agentscope.tool import Toolkit


async def main():
    agent = Agent(
        name="Friday",
        system_prompt="你是一个简洁、可靠的技术助手。",
        model=DashScopeChatModel(
            credential=DashScopeCredential(
                api_key=os.environ["DASHSCOPE_API_KEY"]
            ),
            model="qwen-plus",
        ),
        toolkit=Toolkit(tools=[]),
    )

    message = UserMsg(
        name="user",
        content="解释一下什么是 Agent。",
    )

    reply = await agent.reply(message)
    print(reply)


asyncio.run(main())

这里真正需要关注的只有四个东西：

Agent
 ├─ system_prompt
 ├─ model
 ├─ toolkit
 └─ input message

换句话说：

Agent = 模型 + 指令 + 能力 + 运行循环。

换模型怎么办？

AgentScope 把模型提供商抽象为 Credential + Model。

例如官方 2.0 当前内置支持 OpenAI、Anthropic、DashScope、DeepSeek、Gemini、Moonshot、xAI、Ollama 等 Chat Model。

如果改用 DeepSeek，核心思路就是替换对应的 Credential 和 Model：

from agentscope.credential import DeepSeekCredential
from agentscope.model import DeepSeekChatModel

model = DeepSeekChatModel(
    credential=DeepSeekCredential(
        api_key=os.environ["DEEPSEEK_API_KEY"]
    ),
    model="deepseek-chat",
)

业务层的 Agent 逻辑不需要跟着重写。

五、Agent 为什么不只是一次模型调用？

普通 Chat 最常见的过程是：

用户问题 → LLM → 文本答案

Agent 则可能是：

用户任务
  ↓
LLM 判断下一步
  ↓
调用工具
  ↓
读取工具结果
  ↓
继续判断
  ↓
再次调用工具 / 输出答案

这就是 ReAct 类 Agent 最核心的工作方式。

例如用户说：

帮我计算 123456 × 789，再把结果写进 result.txt。

模型本身不应该直接“假装文件已经写入”。一个真正的 Agent 会根据能力决定：

1. 需要计算；

2. 需要写文件；

3. 调用对应 Tool；

4. 获取 Tool Result；

5. 确认任务完成后再回复用户。

Tool 才是 Agent 从“会说”变成“会做”的关键。

六、给 Agent 增加 Tool

AgentScope 2.0 的 Tool 可以来自多种来源：

• 内置工具：Bash、PowerShell、Read、Write、Edit、Grep、Glob 等；

• 普通 Python 函数；

• 自定义 ToolBase；

• MCP Server；

• Skill。

1. 最简单：把普通 Python 函数包装成 Tool

from agentscope.tool import FunctionTool, Toolkit


def get_order_status(order_id: str) -> str:
    """查询订单状态。

    Args:
        order_id: 订单编号。
    """
    # 实际项目中这里可以调用数据库或业务 API
    return f"订单 {order_id} 当前状态：已发货"


toolkit = Toolkit(
    tools=[
        FunctionTool(
            get_order_status,
            is_read_only=True,
        )
    ]
)

然后交给 Agent：

agent = Agent(
    name="OrderAgent",
    system_prompt="你负责帮助用户查询订单。",
    model=model,
    toolkit=toolkit,
)

此时用户再问：

帮我看看订单 A20260814001 到哪了？

模型可以根据 Tool 的名称、说明和参数 Schema，自主判断是否调用 get_order_status。

2. 为什么函数的类型和注释很重要？

FunctionTool 会从 Python 函数中提取：

• 函数名 → Tool 名称；

• docstring → Tool 描述；

• type hints → Tool 参数 Schema。

所以写 Agent Tool 时，不要把函数签名写得含糊不清。

不推荐：

def run(data):
    ...

更推荐：

def get_order_status(order_id: str) -> str:
    """根据订单编号查询订单状态。"""
    ...

Tool 的 Schema 越清楚，模型越容易正确选择和调用。

七、Toolkit 是干什么的？

Toolkit 可以理解成 Agent 的“能力注册表”。

它并不是单纯的 list[function]，还负责统一管理：

Python Tool
MCP Tool
Skill
Tool Group
       ↓
    Toolkit
       ↓
     Agent

AgentScope 2.0 还支持 Tool Group。对于工具很多的 Agent，可以按组启用或禁用，避免一次性把所有工具都暴露给模型。

这在大型 Agent 系统里很重要，因为工具并不是越多越好：

• Prompt / Schema 体积会增加；

• 工具选择可能更混乱；

• 权限边界更难控制；

• 不相关能力会干扰模型决策。

八、Context、Memory、RAG 是一回事吗？

不是。

可以简单区分：

一个 Agent 当前可能同时拥有：

System Prompt
+ 当前会话历史
+ Tool Result
+ RAG 检索片段
+ Long-Term Memory
+ Runtime State
        ↓
     Context
        ↓
       LLM

AgentScope 2.0 还把上下文压缩、工具结果卸载、运行时状态注入放到了框架层处理，这就是它比“自己手写一个 while 循环调用 LLM”更有工程价值的地方之一。

九、Middleware 在 AgentScope 里是什么？

Middleware 可以理解成：

不修改 Agent 主业务逻辑，但在 Agent 生命周期的关键节点插入额外行为。

例如：

• 记录日志；

• 统计 Token；

• Tracing；

• 修改 System Prompt；

• 上下文压缩；

• 权限判断；

• 长期记忆注入；

• 对工具调用做额外处理。

它和 Web 框架里的 Middleware 思想非常接近：都是把横切逻辑从主流程里拆出去。

所以不要把 Agent Middleware 理解成某一种特殊的 AI 技术，它本质上仍然是一个生命周期扩展机制。

十、为什么还需要 Permission 和 Sandbox？

只做聊天时问题不大，一旦 Agent 拥有这些能力：

Shell
文件写入
数据库修改
Git
部署
浏览器操作
外部 API

安全边界就变得非常重要。

例如模型想执行：

rm -rf ./data

如果框架只是“模型返回 Tool Call → 后端无脑执行”，那实际上只是把 LLM 直接接到了系统权限上。

AgentScope 2.0 把 Permission 和 Workspace / Sandbox 作为一等能力：

LLM
 ↓
Tool Call
 ↓
Permission
 ↓
Workspace / Sandbox
 ↓
真正执行

这也是 Demo Agent 与生产 Agent 的重要分界线。

十一、什么时候需要多 Agent？

不要因为框架支持 Multi-Agent，就默认一个系统应该拆成很多 Agent。

例如：

查询天气
写文件
调用数据库
搜索知识库

这些通常都只是同一个 Agent 的不同 Tool，没有必要拆四个 Agent。

更适合拆多 Agent 的情况是：

• 角色目标明显不同；

• 每个角色需要完全不同的上下文或工具；

• 需要独立并行处理；

• 需要 Reviewer / Planner / Worker 这样的协作关系；

• 不同 Agent 需要互相交接任务。

一个实用的演进路线如下：

先把单 Agent 做稳定，再考虑 Multi-Agent。

十二、AgentScope 与 LangGraph、Spring AI 怎么看？

它们并不是严格的一一替代关系。

可以用一个很粗略的心智模型区分：

AgentScope
更偏完整 Agent Runtime / SDK / 工程能力

LangGraph
更偏图结构、状态与工作流编排

Spring AI
更偏 Java / Spring 应用接入模型、Tool、RAG 等 AI 能力

如果你的核心需求是：

我想快速搭一个能调用工具、支持上下文、权限、Sandbox，后续还能服务化的 Agent。

AgentScope 很值得直接试。

如果你的核心需求是：

我需要非常明确地控制每一个节点、状态跳转和工作流。

那么图编排框架通常会更自然。

如果整个系统本身就是大型 Spring Boot 企业项目，也可以同时评估 AgentScope Java 2.0，它已经有独立 Java 实现，不必默认“AgentScope = Python only”。

十三、快速入门应该学到哪里？

建议学习顺序：

1. Agent + Model
      ↓
2. UserMsg / reply / reply_stream
      ↓
3. FunctionTool + Toolkit
      ↓
4. Permission
      ↓
5. Context / RAG / Memory
      ↓
6. Middleware
      ↓
7. Workspace / Sandbox
      ↓
8. Agent Service
      ↓
9. Multi-Agent

不要倒过来一上来研究复杂 Multi-Agent Workflow。

Agent 系统真正的难点通常不是“创建几个 Agent 对象”，而是：

• 给模型什么上下文；

• 暴露哪些工具；

• 工具 Schema 是否准确；

• 执行权限如何限制；

• 长任务如何恢复；

• Tool Result 如何进入上下文；

• 如何观测、调试和评估整个执行轨迹。

AgentScope 2.0 的价值，也正是在这些工程问题上逐渐形成了一套完整抽象。

总结

如果只记住一句话：

AgentScope 是围绕 Agent 推理-行动循环构建的一套 Agent 工程框架，而不是“多 Agent 对话库”。

第一次使用时，不需要一次掌握所有模块。先完成这条链路即可：

UserMsg
  ↓
Agent
  ↓
Model 判断
  ↓
Tool Call
  ↓
Tool Result
  ↓
Final Reply

等这条最小链路跑通，再逐步加入 Context、Memory、RAG、Permission、Sandbox 和服务化能力，AgentScope 的设计就会非常清楚。

参考资料

• AgentScope 2.0 官方文档：https://docs.agentscope.io/

• AgentScope 2.0 Quickstart：https://docs.agentscope.io/versions/2.0.7dev/en/quickstart

• Agent 核心抽象：https://docs.agentscope.io/versions/2.0.7dev/en/building-blocks/agent/overview

• Python Tool：https://docs.agentscope.io/versions/2.0.7dev/en/building-blocks/tool/python-tool

• Model：https://docs.agentscope.io/versions/2.0.7dev/en/building-blocks/model/overview

• Release Notes：https://docs.agentscope.io/versions/2.0.7dev/en/release-notes

• GitHub：https://github.com/agentscope-ai/agentscope

• AgentScope Java 2.0：https://java.agentscope.io/v2/en/intro.html