AgentScope【一、概要】
AgentScope 全方位详细教程(2026最新版)
AgentScope是阿里通义实验室开源的生产级多智能体开发框架,以"智能体导向编程"为核心,提供SDK、Runtime、Studio三位一体架构,支持从单智能体到分布式多智能体系统的全流程开发、调试与部署。以下从原理、版本、安装部署、API使用、初级/高级功能全维度详解,附完整可运行示例。
一、核心原理与架构
1.1 设计理念
- 透明可控:全组件可见、无黑箱封装,支持运行时动态干预与调试
- 模型无关:统一抽象模型接口,兼容通义、GPT、Claude、Ollama等17+LLM提供商
- 多智能体优先:以消息驱动为核心,原生支持多智能体协作、并行执行与状态管理
- 生产就绪:内置安全沙箱、容错重试、分布式部署、全链路监控能力
1.2 三位一体核心架构
-
AgentScope SDK(核心框架)
- 智能体层:
AgentBase、ReActAgent、DialogAgent等基础智能体,封装reply/observe行为 - 编排层:
MsgHub消息中枢、Pipeline流水线,管理多智能体消息路由与执行流 - 核心服务:模型适配器、工具包(Toolkit)、记忆系统、格式化器、日志追踪
- 基础设施:MCP模型调度、OpenTelemetry可观测性、配置管理
- 智能体层:
-
AgentScope Runtime(安全运行时)
- 沙箱隔离:支持Docker/K8s/BoxLite沙箱,安全执行代码、文件、浏览器、训练等任务
- 分布式部署:支持K8s、函数计算、阿里云ACK,一键部署为生产服务
- 状态管理:会话持久化、中断恢复、负载均衡、高可用保障
-
AgentScope Studio(可视化平台)
- 拖拽式智能体编排、实时对话调试、日志监控、性能分析
- 访问地址:
http://localhost:8000(启动后自动开放)
1.3 核心工作机制
- 消息驱动:所有智能体交互通过
Msg对象完成,支持文本/图片/文件/多模态数据 - ReAct范式:推理(Reasoning)→ 行动(Acting)→ 观察(Observation)循环,支持并行工具调用
- 记忆分层:短期会话记忆、长期向量记忆、自定义记忆钩子,支持增删改查与检索
- 工具标准化:函数自动注册、参数校验、执行隔离、结果格式化,兼容自定义/第三方工具
二、版本信息(2026.4最新)
- 稳定版:
1.0.18(2026-03-26发布) - Runtime版:
1.1.3(2026-03-31发布) - Python要求:3.10+(推荐3.10~3.12)
- 协议:Apache-2.0开源协议
- GitHub:https://github.com/agentscope-ai/agentscope
- 官方文档:https://doc.agentscope.io
三、安装与部署
3.1 基础环境准备
# 1. 检查Python版本(必须≥3.10)
python --version
# 2. 创建并激活虚拟环境(推荐,避免系统环境冲突)
python -m venv agentscope-env
# Linux/Mac
source agentscope-env/bin/activate
# Windows
agentscope-env\Scripts\activate
# 3. 安装Docker(可选,用于Runtime沙箱)
# 参考:https://docs.docker.com/get-docker/
3.2 核心框架安装(3种方式)
方式1:PyPI安装(推荐)
# 基础版(核心SDK)
pip install agentscope
# 完整版(含Runtime、Studio、所有模型依赖)
pip install agentscope[full] # Windows
pip install 'agentscope[full]' # Linux/Mac
# 开发版(含测试、文档依赖)
pip install agentscope[dev]
方式2:源码安装(最新特性)
git clone https://github.com/agentscope-ai/agentscope.git
cd agentscope
pip install -e . # 可编辑模式安装
方式3:验证安装
python -c "import agentscope; print(agentscope.__version__)"
# 输出:1.0.18(或对应版本)
3.3 模型配置(关键步骤)
创建model_config.json,支持多模型同时配置:
{
"model_configs": [
{
"config_name": "dashscope_qwen",
"model_type": "dashscope_chat",
"model_name": "qwen-max",
"api_key": "${DASHSCOPE_API_KEY}",
"temperature": 0.1,
"stream": true
},
{
"config_name": "openai_gpt4",
"model_type": "openai_chat",
"model_name": "gpt-4o",
"api_key": "${OPENAI_API_KEY}",
"base_url": "https://api.openai.com/v1"
},
{
"config_name": "ollama_llama3",
"model_type": "ollama_chat",
"model_name": "llama3:8b",
"base_url": "http://localhost:11434"
}
]
}
设置环境变量(Linux/Mac):
export DASHSCOPE_API_KEY="sk-xxx"
export OPENAI_API_KEY="sk-xxx"
Windows(PowerShell):
$env:DASHSCOPE_API_KEY="sk-xxx"
$env:OPENAI_API_KEY="sk-xxx"
3.4 本地启动与Studio可视化
# 启动Studio可视化平台(自动加载model_config.json)
agentscope studio
# 访问:http://localhost:8000
3.5 生产部署(Runtime)
本地沙箱部署(Docker)
# 安装Runtime
pip install agentscope-runtime
# 拉取基础沙箱镜像
docker pull agentscope/base-sandbox:latest
# 部署为本地服务
agentscope deploy local app.py --name my-agent-service
云端K8s部署(阿里云ACK)
# 一键部署为Knative服务
agentscope deploy knative app.py \
--image-name my-agent-image \
--namespace agentscope-runtime \
--secret demo-credential
四、基础API使用(Hello World)
4.1 初始化框架
import agentscope
# 方式1:加载JSON配置文件
agentscope.init(
model_configs="model_config.json",
project="MyFirstAgent",
logger_level="INFO" # DEBUG/INFO/WARNING/ERROR
)
# 方式2:直接传入配置字典
model_config = {
"config_name": "qwen_test",
"model_type": "dashscope_chat",
"model_name": "qwen-turbo",
"api_key": "sk-xxx"
}
agentscope.init(model_configs=[model_config])
4.2 消息对象(Msg)
所有交互基于Msg类,支持多模态:
from agentscope.message import Msg
# 文本消息
msg1 = Msg(
name="user",
content="你好",
role="user"
)
# 多模态消息(文本+图片)
msg2 = Msg(
name="user",
content={
"text": "这张图片是什么?",
"image": "https://example.com/image.jpg"
}
)
# 消息传递
print(msg1.content) # 输出:你好
4.3 基础智能体(DialogAgent)
最简单的对话智能体:
from agentscope.agents import DialogAgent, UserAgent
# 创建对话AI
assistant = DialogAgent(
name="助手",
sys_prompt="你是一个乐于助人的AI助手,回答简洁准确",
model_config_name="dashscope_qwen" # 对应配置文件的config_name
)
# 创建用户交互代理
user = UserAgent()
# 单轮对话
response = assistant(Msg("user", "什么是AgentScope?"))
print(f"助手:{response.content}")
4.4 多轮对话循环
# 多轮对话(输入exit退出)
msg = None
while True:
# AI响应
msg = assistant(msg)
print(f"{msg.name}: {msg.content}")
# 用户输入
msg = user(msg)
if msg.content.lower() == "exit":
print("对话结束")
break
五、初级功能实战
5.1 ReAct智能体(工具调用)
ReActAgent支持"思考→调用工具→观察结果"循环,是核心智能体类型。
步骤1:定义工具函数
from agentscope.tools import tool
# 用@tool装饰器自动注册工具
@tool
def get_weather(city: str) -> str:
"""获取指定城市的天气信息
Args:
city: 城市名称
Returns:
天气描述字符串
"""
# 模拟API调用
return f"{city}今日天气:晴,25℃,微风"
@tool
def search_news(topic: str) -> str:
"""搜索指定主题的新闻
Args:
topic: 新闻主题
Returns:
新闻摘要
"""
return f"关于{topic}的最新新闻:AI框架AgentScope发布1.0.18版本,新增分布式部署能力"
步骤2:创建ReAct智能体
from agentscope.agents import ReActAgent
agent = ReActAgent(
name="AI助手",
sys_prompt="你是一个全能助手,可调用工具获取信息,回答用户问题",
model_config_name="dashscope_qwen",
tools=[get_weather, search_news], # 绑定工具
max_iters=5, # 最大工具调用次数
enable_memory=True # 启用记忆
)
步骤3:执行工具调用
# 测试1:调用天气工具
response = agent(Msg("user", "北京今天天气怎么样?"))
print(response.content)
# 测试2:调用新闻工具
response = agent(Msg("user", "AgentScope有什么最新消息?"))
print(response.content)
# 测试3:多工具组合
response = agent(Msg("user", "上海天气如何?有没有相关旅游新闻?"))
print(response.content)
5.2 多智能体协作(双智能体对话)
from agentscope.agents import DialogAgent
from agentscope.pipelines import SequentialPipeline
# 创建两个专业智能体
writer = DialogAgent(
name="作家",
sys_prompt="你是专业作家,擅长创作故事",
model_config_name="dashscope_qwen"
)
critic = DialogAgent(
name="评论家",
sys_prompt="你是资深评论家,精准分析故事优缺点",
model_config_name="dashscope_qwen"
)
# 构建顺序执行流水线
pipeline = SequentialPipeline(agents=[writer, critic])
# 启动协作
result = pipeline(Msg("user", "写一个科幻短篇故事,然后给出评价"))
print(result.content)
5.3 多智能体群聊(MsgHub)
from agentscope.message import MsgHub
from agentscope.agents import DialogAgent
# 创建3个智能体
alice = DialogAgent(name="Alice", sys_prompt="你是Alice,喜欢聊天", model_config_name="dashscope_qwen")
bob = DialogAgent(name="Bob", sys_prompt="你是Bob,技术专家", model_config_name="dashscope_qwen")
charlie = DialogAgent(name="Charlie", sys_prompt="你是Charlie,幽默风趣", model_config_name="dashscope_qwen")
# 创建消息中枢(群聊)
msghub = MsgHub(agents=[alice, bob, charlie])
# 启动群聊
msghub.broadcast(Msg("user", "大家觉得AI未来会如何改变生活?"))
5.4 记忆系统使用
from agentscope.memory import InMemoryMemory
from agentscope.agents import DialogAgent
# 创建带记忆的智能体
memory_agent = DialogAgent(
name="记忆助手",
sys_prompt="你记得用户之前说过的所有话",
model_config_name="dashscope_qwen",
memory=InMemoryMemory(remember_num=10) # 记住最近10轮对话
)
# 多轮对话测试
memory_agent(Msg("user", "我叫张三,喜欢打篮球"))
memory_agent(Msg("user", "我今年25岁"))
# 验证记忆
response = memory_agent(Msg("user", "你还记得我的名字和爱好吗?"))
print(response.content) # 输出:你叫张三,喜欢打篮球,今年25岁
六、高级功能实战
6.1 异步并行执行(提升效率)
import asyncio
import agentscope
from agentscope.agents import ReActAgent
from agentscope.tools import tool
# 初始化异步框架
agentscope.init(model_configs="model_config.json")
# 定义异步工具
@tool
async def async_get_weather(city: str) -> str:
await asyncio.sleep(1) # 模拟IO延迟
return f"{city}天气:阴,22℃"
@tool
async def async_get_hotel(city: str) -> str:
await asyncio.sleep(1)
return f"{city}推荐酒店:五星级酒店2家,经济型酒店5家"
# 创建异步智能体
async_agent = ReActAgent(
name="异步助手",
sys_prompt="你可以并行调用多个工具",
model_config_name="dashscope_qwen",
tools=[async_get_weather, async_get_hotel]
)
# 并行执行
async def main():
# 并行调用两个工具(总耗时≈1s,而非2s)
result = await async_agent(Msg("user", "帮我查一下杭州的天气和酒店信息"))
print(result.content)
asyncio.run(main())
6.2 运行时中断与干预
from agentscope.interrupt import interrupt_context
from agentscope.agents import ReActAgent
from agentscope.tools import tool
# 定义耗时工具
@tool
def long_calculate(x: int) -> int:
"""耗时计算"""
import time
time.sleep(5)
return x * 100
# 创建支持中断的智能体
interrupt_agent = ReActAgent(
name="计算助手",
sys_prompt="你负责复杂计算,支持随时中断",
model_config_name="dashscope_qwen",
tools=[long_calculate],
enable_interrupt=True # 启用中断
)
# 带中断的执行
with interrupt_context() as ctx:
# 3秒后中断
ctx.interrupt_after(3)
try:
response = interrupt_agent(Msg("user", "计算12345的100倍"))
print(response.content)
except InterruptedError:
print("任务已被中断!")
6.3 自定义沙箱(安全代码执行)
from agentscope_runtime.sandbox import BaseSandbox
# 创建代码沙箱(隔离环境)
sandbox = BaseSandbox(
image="agentscope/base-sandbox:latest",
memory_limit="512m",
cpu_limit=1,
timeout=30
)
# 安全执行Python代码
code = """
def fib(n):
a, b = 0, 1
for _ in range(n):
a, b = b, a+b
return a
print(fib(20))
"""
result = sandbox.run_code(code, language="python")
print("执行结果:", result.output)
print("是否错误:", result.error)
6.4 分布式多智能体部署
# app.py(分布式服务代码)
import agentscope
from agentscope.agents import DialogAgent
from agentscope.service import AgentService
agentscope.init(model_configs="model_config.json")
# 创建分布式智能体
dist_agent = DialogAgent(
name="分布式助手",
sys_prompt="我是分布式部署的AI服务",
model_config_name="dashscope_qwen"
)
# 启动服务
if __name__ == "__main__":
service = AgentService(agent=dist_agent, host="0.0.0.0", port=8888)
service.run()
客户端调用:
from agentscope.service import AgentClient
# 连接远程智能体
client = AgentClient(url="http://localhost:8888")
# 远程调用
response = client.call(Msg("user", "你部署在哪里?"))
print(response.content)
6.5 多模态智能体(图文处理)
from agentscope.agents import MultiModalAgent
# 创建多模态智能体
mm_agent = MultiModalAgent(
name="多模态助手",
sys_prompt="你能理解图片和文本内容",
model_config_name="dashscope_qwen",
enable_vision=True # 启用视觉能力
)
# 发送图文消息
response = mm_agent(Msg(
name="user",
content={
"text": "描述这张图片的内容",
"image": "https://example.com/cat.jpg"
}
))
print(response.content)
七、完整项目示例:智能旅行规划师
7.1 项目结构
travel_agent/
├── main.py # 主程序
├── model_config.json # 模型配置
└── tools.py # 工具函数
7.2 tools.py
from agentscope.tools import tool
@tool
def get_weather(city: str) -> str:
"""获取城市天气"""
return f"{city}:晴,24-30℃,适合出行"
@tool
def search_attractions(city: str) -> str:
"""搜索景点"""
return f"{city}热门景点:西湖、灵隐寺、千岛湖(评分4.8+)"
@tool
def recommend_restaurants(city: str) -> str:
"""推荐餐厅"""
return f"{city}特色美食:西湖醋鱼、龙井虾仁、叫化鸡"
7.3 main.py
import asyncio
import agentscope
from agentscope.agents import ReActAgent
from tools import get_weather, search_attractions, recommend_restaurants
# 初始化
agentscope.init(model_configs="model_config.json")
# 创建旅行规划智能体
travel_agent = ReActAgent(
name="旅行规划师",
sys_prompt="你是专业旅行规划师,调用天气、景点、美食工具,生成详细旅行计划",
model_config_name="dashscope_qwen",
tools=[get_weather, search_attractions, recommend_restaurants],
max_iters=3
)
# 异步执行
async def plan_trip(city: str):
print(f"正在为您规划{city}旅行...")
result = await travel_agent(Msg("user", f"帮我规划{city}一日游计划,包含天气、景点、美食"))
print("\n=== 旅行计划 ===")
print(result.content)
if __name__ == "__main__":
asyncio.run(plan_trip("杭州"))
7.4 运行结果
正在为您规划杭州旅行...
=== 旅行计划 ===
杭州一日游计划:
1. 天气情况:晴,24-30℃,非常适合户外出行
2. 景点安排:
- 上午:西湖(游船、断桥残雪)
- 下午:灵隐寺(祈福、参观古建筑)
3. 美食推荐:
- 午餐:西湖醋鱼、龙井虾仁
- 晚餐:叫化鸡、杭州小笼包
4. 注意事项:天气炎热,注意防晒补水
八、常见问题与最佳实践
8.1 常见问题
-
安装报错
externally-managed-environment- 原因:系统Python环境受保护
- 解决:必须使用虚拟环境(参考3.1节)
-
模型调用失败
- 检查:API密钥是否正确、环境变量是否生效、网络是否通畅
- 日志:查看
logs/目录下的日志文件
-
沙箱无法启动
- 检查:Docker是否运行、镜像是否拉取成功
- M1/M2芯片:启用Rosetta 2(
colima start --vm-type=vz --vz-rosetta)
8.2 最佳实践
-
开发流程
- 本地:用
agentscope studio可视化调试 - 测试:用本地沙箱验证功能
- 生产:用K8s/函数计算部署
- 本地:用
-
性能优化
- 异步:IO密集型任务用
async/await - 并行:多工具调用启用并行执行
- 缓存:频繁查询结果启用记忆缓存
- 异步:IO密集型任务用
-
安全规范
- 所有代码/文件执行必须用沙箱
- 敏感API密钥用环境变量,不硬编码
- 生产环境关闭调试日志
九、进阶学习路径
-
官方资源
- 文档:https://doc.agentscope.io
- GitHub:https://github.com/agentscope-ai/agentscope
- 示例:
examples/目录(含50+实战案例)
-
扩展学习
- Runtime沙箱高级用法:文件/浏览器/训练沙箱
- 自定义智能体:继承
AgentBase实现专属逻辑 - 模型微调:
AgentScopeTune工具优化智能体表现 - 企业级部署:监控、告警、扩容、灰度发布
AgentScope是目前国内最成熟的生产级多智能体框架,从简单对话到复杂分布式系统均可快速落地。以上教程覆盖从入门到高级的全流程,结合官方示例与实际业务场景,可快速构建高质量AI智能体应用。
本文来自博客园,作者:蓝迷梦,转载请注明原文链接:https://www.cnblogs.com/hewei-blogs/articles/19840372

浙公网安备 33010602011771号