AgentScope 介绍

AgentScope 是一个面向智能体的编程框架，旨在用简单高效的方式来构建智能体应用程序。该框架提供从模型封装、工具管理、会话/记忆、消息路由到可视化监控的全套功能，帮助开发者快速构建、调试并部署多智能体与单智能体的生产级应用。

AgentScope 支持异步执行和流式返回，兼容多种 LLM 服务（本地模型或第三方 API），并提供 AgentScope Studio 与 AgentScope Runtime 等生态组件，覆盖从开发到生产的完整闭环。

项目亮点

实时介入（可打断并中途增加提问）
ReActAgent 原生支持实时介入（Realtime Steering）：在智能体运行过程中可以被外部打断，用户或系统可在任意时刻插入新的问题或指令。框架将打断事件视作可观测的状态/记忆片段，智能体可以即时响应新增输入并在处理后无缝恢复到原先的对话流，极大提升交互灵活性与可控性（适用于客服插入、更正指令、多人协作中断等场景）。

AgentScope Studio（可视化WebUI）
通过 AgentScope Studio，开发者可以直观追踪、调试基于 AgentScope 构建的智能体应用，轻松监控运行状态、调试行为和优化协作流程。

细粒度 MCP 控制
开发者可以通过本地可调用函数灵活访问 MCP 工具，以任意方式使用——无论是直接调用、赋能给智能体，还是包装为更复杂的复合工具，能满足不同场景下的自定义需求。

多智能体对话
AgentScope 提供多种 pipeline，简化多智能体之间的对话构建与协作编排。框架支持并行工具调用、自动状态管理与高效路由，使多智能体系统在任务分工、信息共享与协同推理时表现稳健。

加入 赋范大模型技术社区 ，免费领取【本教程代码】+【更多大模型Agent实战教程】+无门槛技术交流，期待你的加入！

快速上手 AgentScope

下面将通过示例代码展示如何使用 Agentscope 框架构建一个支持并发工具调用、长期记忆、MCP、会话管理和可视化溯源的 ReAct 智能体。帮助读者快速上手 Agentscope 项目。

环境准备

首先需要安装必要的依赖：

# 从源码安装 Agentscope
git clone -b main https://github.com/agentscope-ai/agentscope.git
cd agentscope
pip install -e .

# 安装 Agentscope 可视化工具
npm install -g @agentscope/studio

然后在项目根目录创建 .env 文件，配置你的 API Key：

阿里百炼到 官网 获取 API Key

高德地图到 官网 获取 API Key

DASHSCOPE_API_KEY=你的阿里百炼 API Key
GAODE_API_KEY=你的高德地图API Key

启动 Agentscope Studio

命令行启动 Agentscope Studio 可视化工具：

as_studio

启动后可到 http://localhost:3000/ 访问 WebUI 界面：

引入依赖库

这里主要做了以下操作：

• load_dotenv()：加载环境变量
• 引入 智能体、模型、工具、会话、记忆等相关模块

import os  
import asyncio
import json  
"""
 Agentscope 引入模块介绍：
   - agentscope: 框架核心入口
   - agent: 提供 ReActAgent（智能推理与执行代理）和 UserAgent（用户交互代理）
   - model: DashScopeChatModel，用于聊天生成和对话管理
   - formatter: DashScopeChatFormatter，用于输出格式化
   - message: Msg 与 TextBlock，用于消息封装与传递
   - module: StateModule，管理代理状态
   - session: JSONSession，保存会话与上下文信息
   - memory: InMemoryMemory 与 Mem0LongTermMemory，短期与长期记忆
   - mcp: HttpStatefulClient 与 HttpStatelessClient，状态/无状态 HTTP 客户端
   - tool: 工具集管理及执行函数（shell、Python、文本文件查看）
   - embedding: DashScopeTextEmbedding，将文本转换为向量表示
   - plan: PlanNotebook，任务计划与工作流管理
"""
import agentscope 
from agentscope.agent import ReActAgent, UserAgent 
from agentscope.model import DashScopeChatModel  
from agentscope.formatter import DashScopeChatFormatter  
from agentscope.message import TextBlock, Msg
from agentscope.module import StateModule
from agentscope.session import JSONSession
from agentscope.memory import InMemoryMemory, Mem0LongTermMemory  
from agentscope.mcp import HttpStatefulClient, HttpStatelessClient
from agentscope.tool import (
    Toolkit,
    ToolResponse,
    execute_shell_command,
    execute_python_code,
    view_text_file,
)
from agentscope.embedding import DashScopeTextEmbedding  
from agentscope.plan import PlanNotebook
from dotenv import load_dotenv

load_dotenv()  # 加载 .env 文件中的环境变量

Agentscope Studio 可视化追踪

AgentScope 实现了基于 OpenTelemetry 的追踪来监控和调试 智能体应用程序的执行
这里连接到自带的 AgentScope Studio 可视化工具

agentscope.init(studio_url="http://localhost:3000")

创建工具包 Toolkit

• 通过toolkit.register_tool_function(tool_name) 注册内置或自定义工具，智能体可通过这些工具完成复杂任务。

这里注册了 shell 命令执行工具、Python 代码执行工具、文本文件查看工具和自定义工具 example_tool_function。

toolkit = Toolkit()  
toolkit.register_tool_function(execute_shell_command)   # 注册 shell 命令执行工具
toolkit.register_tool_function(execute_python_code) # 注册 Python 代码执行工具
toolkit.register_tool_function(view_text_file)  # 注册文本文件查看工具
toolkit.register_tool_function(example_tool_function)   # 注册自定义工具

创建长期记忆

长期记忆使用向量存储，可帮助智能体保留历史对话和知识：

• DashScopeChatModel：大语言模型
• DashScopeTextEmbedding：向量化模型，用于语义搜索和记忆

long_term_memory = Mem0LongTermMemory(
    model=DashScopeChatModel(
        api_key=os.environ.get("DASHSCOPE_API_KEY"),
        model_name="qwen-max",
        enable_thinking=False,
        stream=False,
    ),
    embedding_model=DashScopeTextEmbedding(
        api_key=os.environ.get("DASHSCOPE_API_KEY"),
        model_name="text-embedding-v2",
    ),
    user_name="demo_user",
)

创建 ReActAgent

 agent = ReActAgent(  
        name="Friday",  
        sys_prompt="你是一个功能强大的AI助手",  
        model=DashScopeChatModel(  
            api_key=os.environ.get("DASHSCOPE_API_KEY"),  
            model_name="qwen-max",
            enable_thinking=False,  
            stream=True,    #流式输出
            generate_kwargs={"parallel_tool_calls": True},    # 告诉模型支持并行工具调用
        ),  
        formatter=DashScopeChatFormatter(),  
        toolkit=toolkit,  
        memory=InMemoryMemory(),  
        long_term_memory=long_term_memory,  
        long_term_memory_mode="both",  # 同时支持智能体控制和静态控制  
        enable_meta_tool=True,  # 启用元工具功能  
        parallel_tool_calls=True,   # 支持并发调用工具
        plan_notebook=PlanNotebook(),  # 支持计划管理  
        print_hint_msg=False,  # 关闭提示消息打印
    )  

加入 赋范大模型技术社区 ，免费领取【本教程代码】+【更多大模型Agent实战教程】+无门槛技术交流，期待你的加入！

创建 MCP 客户端

• 通过HttpStatelessClient创建无状态 MCP 客户端
• 通过HttpStatefulClient创建有状态 MCP 客户端
• 通过 toolkit.register_mcp_client(mcp_client) 将MCP注册到工具包中供智能体调用。

这里创建一个无状态 MCP 客户端，用于访问高德地图 API。

stateless_client = HttpStatelessClient(
    name="gaode_mcp",
    transport="streamable_http",
    url=f"https://mcp.amap.com/mcp?key={os.environ.get('GAODE_API_KEY')}",
)
await toolkit.register_mcp_client(stateless_client)

会话管理

• 使用 JSONSession(save_dir) 保存和加载智能体状态：

session = JSONSession(save_dir="./sessions")

try:
    await session.load_session_state(session_id="user_demo", agent=agent)
    print("✅ 成功加载上一次会话状态。")
except FileNotFoundError:
    print("⚠️ 未找到上一次会话，开始新会话。")

用户交互

创建用户智能体，并循环接收输入

• 可通过 session.save_session_state(session_id ,agent) 保存会话状态
• 输入 exit 可退出循环。

user = UserAgent(name="User")
msg = None
while True:
    msg = await user(msg)
    if msg.get_text_content() == "exit":
        break
    msg = await agent(msg)
    # 每次生成消息后保存状态
    await session.save_session_state(session_id="user_demo", agent=agent)
    print("✅ 已保存当前会话状态。")

自定义工具函数

我们可以自定义工具函数来扩展智能体的功能

example - 测试并发自定义工具：
用于测试智能体并发工具调用。观察输出内容中 ‘tag1’ 和 ‘tag2’ 的开始和结束时间，验证并发效果。

async def example_tool_function(tag: str) -> ToolResponse:
    from datetime import datetime
    start_time = datetime.now().strftime("%H:%M:%S.%f")

    # 休眠 3 秒以模拟长时间运行的任务
    await asyncio.sleep(3)

    end_time = datetime.now().strftime("%H:%M:%S.%f")
    return ToolResponse(
        content=[
            TextBlock(
                type="text",
                text=f"标签 {tag} 开始于 {start_time}，结束于 {end_time}。",
            ),
        ],
    )  

加入 赋范大模型技术社区 ，免费领取【本教程代码】+【更多大模型Agent实战教程】+无门槛技术交流，期待你的加入！