AgentScope【一、概要】

AgentScope 全方位详细教程(2026最新版)

AgentScope是阿里通义实验室开源的生产级多智能体开发框架,以"智能体导向编程"为核心,提供SDK、Runtime、Studio三位一体架构,支持从单智能体到分布式多智能体系统的全流程开发、调试与部署。以下从原理、版本、安装部署、API使用、初级/高级功能全维度详解,附完整可运行示例。

一、核心原理与架构

1.1 设计理念

  • 透明可控:全组件可见、无黑箱封装,支持运行时动态干预与调试
  • 模型无关:统一抽象模型接口,兼容通义、GPT、Claude、Ollama等17+LLM提供商
  • 多智能体优先:以消息驱动为核心,原生支持多智能体协作、并行执行与状态管理
  • 生产就绪:内置安全沙箱、容错重试、分布式部署、全链路监控能力

1.2 三位一体核心架构

  1. AgentScope SDK(核心框架)

    • 智能体层:AgentBase、ReActAgent、DialogAgent等基础智能体,封装reply/observe行为
    • 编排层:MsgHub消息中枢、Pipeline流水线,管理多智能体消息路由与执行流
    • 核心服务:模型适配器、工具包(Toolkit)、记忆系统、格式化器、日志追踪
    • 基础设施:MCP模型调度、OpenTelemetry可观测性、配置管理
  2. AgentScope Runtime(安全运行时)

    • 沙箱隔离:支持Docker/K8s/BoxLite沙箱,安全执行代码、文件、浏览器、训练等任务
    • 分布式部署:支持K8s、函数计算、阿里云ACK,一键部署为生产服务
    • 状态管理:会话持久化、中断恢复、负载均衡、高可用保障
  3. AgentScope Studio(可视化平台)

    • 拖拽式智能体编排、实时对话调试、日志监控、性能分析
    • 访问地址:http://localhost:8000(启动后自动开放)

1.3 核心工作机制

  • 消息驱动:所有智能体交互通过Msg对象完成,支持文本/图片/文件/多模态数据
  • ReAct范式:推理(Reasoning)→ 行动(Acting)→ 观察(Observation)循环,支持并行工具调用
  • 记忆分层:短期会话记忆、长期向量记忆、自定义记忆钩子,支持增删改查与检索
  • 工具标准化:函数自动注册、参数校验、执行隔离、结果格式化,兼容自定义/第三方工具

二、版本信息(2026.4最新)

三、安装与部署

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 常见问题

  1. 安装报错externally-managed-environment

    • 原因:系统Python环境受保护
    • 解决:必须使用虚拟环境(参考3.1节)
  2. 模型调用失败

    • 检查:API密钥是否正确、环境变量是否生效、网络是否通畅
    • 日志:查看logs/目录下的日志文件
  3. 沙箱无法启动

    • 检查:Docker是否运行、镜像是否拉取成功
    • M1/M2芯片:启用Rosetta 2(colima start --vm-type=vz --vz-rosetta)

8.2 最佳实践

  1. 开发流程

    • 本地:用agentscope studio可视化调试
    • 测试:用本地沙箱验证功能
    • 生产:用K8s/函数计算部署
  2. 性能优化

    • 异步:IO密集型任务用async/await
    • 并行:多工具调用启用并行执行
    • 缓存:频繁查询结果启用记忆缓存
  3. 安全规范

    • 所有代码/文件执行必须用沙箱
    • 敏感API密钥用环境变量,不硬编码
    • 生产环境关闭调试日志

九、进阶学习路径

  1. 官方资源

  2. 扩展学习

    • Runtime沙箱高级用法:文件/浏览器/训练沙箱
    • 自定义智能体:继承AgentBase实现专属逻辑
    • 模型微调:AgentScopeTune工具优化智能体表现
    • 企业级部署:监控、告警、扩容、灰度发布

AgentScope是目前国内最成熟的生产级多智能体框架,从简单对话到复杂分布式系统均可快速落地。以上教程覆盖从入门到高级的全流程,结合官方示例与实际业务场景,可快速构建高质量AI智能体应用。

posted @ 2026-04-09 13:43  蓝迷梦  阅读(8155)  评论(0)    收藏  举报