AgentScope 的安装和基础使用

发表于 2026-09-07 分类于 AI ， AI Agent 阅读次数：

AgentScope 是阿里巴巴开源的多智能体（Multi-Agent）框架，本文介绍其安装方式与基础使用，包括 Agent 创建、模型配置、多 Agent 对话等。

AgentScope 简介

AgentScope 是阿里巴巴开源的多智能体（Multi-Agent）框架，当前版本为 2.0，在 GitHub 上已获得约 30k stars。

官方定位：

Build and run agents you can see, understand and trust.（构建并运行你「看得见、理解得了、可信任」的智能体）

核心特性

ReAct 智能体：结构化输出、实时中断与恢复、串行 / 并发批量工具调用
Toolkit：统一管理 Python 函数、MCP 服务器、Skill，内置编码、文件、搜索等工具
多模型支持：OpenAI、Anthropic、DashScope（通义千问）、Gemini、DeepSeek、Ollama 等主流提供商
上下文管理：自动压缩、工具结果卸载、RAG 与记忆注入中间件
事件系统：统一事件总线，支持流式推理、工具调用、多模态内容（文本/图片/音频）
权限与 HITL：细粒度工具 / 资源控制，支持确认模式与 bypass 模式
长期记忆：Agent 自主记忆，可切换后端（ReMe、Mem0）
Workspace/Sandbox：隔离代码执行环境（本地、Docker、E2B、K8s 等）
Agent Service：内置 FastAPI 后端 + Web UI，支持多租户、多会话、IM 通道（飞书、钉钉、Discord）

安装

环境要求

Python 3.10+（推荐 3.11+）
建议在虚拟环境中安装

使用 uv 安装（官方推荐）

uv 是极速的 Python 包管理工具，安装速度远快于 pip。

第一步：安装 uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

第二步：创建虚拟环境

uv venv ~/.venvs/agentscope
source ~/.venvs/agentscope/bin/activate   # macOS / Linux
# .venvs\agentscope\Scripts\activate      # Windows

第三步：安装 AgentScope

uv pip install agentscope

使用 pip 安装

pip install agentscope

从源码安装

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

安装额外依赖

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

# Windows
pip install agentscope[full]

验证安装

import agentscope
print(agentscope.__version__)
# 2.0.7.post1

核心概念

Message（消息）

Msg 是最基础的数据结构，用于智能体间信息交换、UI 展示与 memory 存储。

字段	类型	说明
`name`	`str`	消息发送者名字 / 身份
`role`	`"system"` / `"assistant"` / `"user"`	发送者角色
`content`	`str \| list[ContentBlock]`	消息内容
`metadata`	`dict \| None`	附加元数据，常用于结构化输出

支持的内容块类型：TextBlock、ThinkingBlock、ImageBlock、AudioBlock、VideoBlock、ToolUseBlock、ToolResultBlock。

from agentscope.message import Msg, TextBlock, ImageBlock

# 纯文本消息
msg = Msg(name="Jarvis", role="assistant", content="Hi! How can I help you?")

# 多模态消息
msg = Msg(
    name="Jarvis",
    role="assistant",
    content=[
        TextBlock(type="text", text="Here is an image."),
        ImageBlock(type="image", url="https://example.com/img.jpg"),
    ],
)

# 工具方法
msg.get_text_content()                   # 汇总所有 TextBlock 为字符串
msg.get_content_blocks(block_type=...)   # 获取指定类型 block
msg.has_content_blocks(block_type=...)   # 检查是否包含指定类型 block

Agent（智能体）

AgentBase 将智能体行为抽象为三个核心方法：

reply：处理传入消息并生成响应
observe：接收消息（不返回响应）
handle_interrupt：处理实时中断

ReActAgent 在此基础上将 reply 拆分为两阶段：推理（reasoning） 和 执行（acting）。

Toolkit（工具集）

任何可调用对象均可作为工具（同步 / 异步函数、方法、类均可）：

from agentscope.tool import Toolkit, Bash, Grep, Glob, Read, Write, Edit, execute_python_code

# 内置工具
toolkit = Toolkit(tools=[Bash(), Grep(), Glob(), Read(), Write(), Edit()])

# 注册自定义函数
toolkit.register_tool_function(execute_python_code)

基础使用

配置模型

DashScope（通义千问）

import os
from agentscope.model import DashScopeChatModel

model = DashScopeChatModel(
    model_name="qwen-max",
    api_key=os.environ["DASHSCOPE_API_KEY"],
    stream=False,
)

OpenAI

from agentscope.model import OpenAIChatModel

# 原生 OpenAI
model = OpenAIChatModel(
    model_name="gpt-4o",
    api_key=os.environ["OPENAI_API_KEY"],
    stream=True,
)

# OpenAI 兼容接口（vLLM、DeepSeek 等）
model = OpenAIChatModel(
    model_name="deepseek-chat",
    client_kwargs={"base_url": "https://api.deepseek.com/v1"},
    api_key=os.environ["DEEPSEEK_API_KEY"],
)

Ollama（本地模型）

from agentscope.model import OllamaChatModel

model = OllamaChatModel(
    model_name="llama3",
    client_kwargs={"host": "http://localhost:11434"},
)

创建 ReAct Agent

import asyncio
import os

from agentscope.agent import ReActAgent
from agentscope.formatter import DashScopeChatFormatter
from agentscope.memory import InMemoryMemory
from agentscope.message import Msg
from agentscope.model import DashScopeChatModel
from agentscope.tool import Toolkit, execute_python_code


async def main() -> None:
    toolkit = Toolkit()
    toolkit.register_tool_function(execute_python_code)

    jarvis = ReActAgent(
        name="Jarvis",
        sys_prompt="You're a helpful assistant named Jarvis.",
        model=DashScopeChatModel(
            model_name="qwen-max",
            api_key=os.environ["DASHSCOPE_API_KEY"],
            stream=True,
        ),
        formatter=DashScopeChatFormatter(),
        toolkit=toolkit,
        memory=InMemoryMemory(),
    )

    msg = Msg(
        name="user",
        content="Hi! Jarvis, run Hello World in Python.",
        role="user",
    )
    await jarvis(msg)


asyncio.run(main())

在控制台中与 Agent 交互（2.0 新 API）

AgentScope 2.0 提供了 launch_console，可在终端中与智能体进行流式对话，内置工具调用确认和 Ctrl + C 中断。

import asyncio
import os

from agentscope.agent import Agent
from agentscope.console import launch_console
from agentscope.credential import DashScopeCredential
from agentscope.model import DashScopeChatModel
from agentscope.tool import Toolkit, Bash, Grep, Glob, Read, Write, Edit


async def main() -> None:
    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",
        ),
        toolkit=Toolkit(
            tools=[Bash(), Grep(), Glob(), Read(), Write(), Edit()]
        ),
    )

    await launch_console(agent)


asyncio.run(main())

自定义 Agent

通过继承 AgentBase 可以完全自定义 Agent 的行为：

import os
from agentscope.agent import AgentBase
from agentscope.formatter import DashScopeChatFormatter
from agentscope.memory import InMemoryMemory
from agentscope.message import Msg
from agentscope.model import DashScopeChatModel


class MyAgent(AgentBase):
    def __init__(self) -> None:
        super().__init__()
        self.name = "Friday"
        self.sys_prompt = "You're a helpful assistant named Friday."
        self.model = DashScopeChatModel(
            model_name="qwen-max",
            api_key=os.environ["DASHSCOPE_API_KEY"],
            stream=False,
        )
        self.formatter = DashScopeChatFormatter()
        self.memory = InMemoryMemory()

    async def reply(self, msg: Msg | list[Msg] | None) -> Msg:
        await self.memory.add(msg)
        prompt = await self.formatter.format(
            [
                Msg("system", self.sys_prompt, "system"),
                *await self.memory.get_memory(),
            ],
        )
        response = await self.model(prompt)
        reply_msg = Msg(name=self.name, content=response.content, role="assistant")
        await self.memory.add(reply_msg)
        await self.print(reply_msg)
        return reply_msg

    async def observe(self, msg: Msg | list[Msg] | None) -> None:
        await self.memory.add(msg)

    async def handle_interrupt(self) -> Msg:
        return Msg(
            name=self.name,
            content="I noticed you interrupted me, how can I help you?",
            role="assistant",
        )

多 Agent 对话

MsgHub 广播

MsgHub 是异步上下文管理器，同一 hub 内的 Agent 会自动广播彼此的消息：

import asyncio
import os

from agentscope.agent import ReActAgent
from agentscope.formatter import DashScopeMultiAgentFormatter
from agentscope.memory import InMemoryMemory
from agentscope.message import Msg
from agentscope.model import DashScopeChatModel
from agentscope.pipeline import MsgHub
from agentscope.tool import Toolkit


def create_agent(name: str, model) -> ReActAgent:
    return ReActAgent(
        name=name,
        sys_prompt=f"You're a student named {name}.",
        model=model,
        formatter=DashScopeMultiAgentFormatter(),
        toolkit=Toolkit(),
        memory=InMemoryMemory(),
    )


async def main() -> None:
    model = DashScopeChatModel(
        model_name="qwen-max",
        api_key=os.environ["DASHSCOPE_API_KEY"],
    )

    alice = create_agent("Alice", model)
    bob = create_agent("Bob", model)
    charlie = create_agent("Charlie", model)

    async with MsgHub(
        [alice, bob, charlie],
        announcement=Msg(
            "system",
            "Now you meet each other, please give a brief self-introduction.",
            "system",
        ),
    ):
        await alice()
        await bob()
        await charlie()


asyncio.run(main())

流式输出

import asyncio
import os
from agentscope.model import DashScopeChatModel


async def main() -> None:
    model = DashScopeChatModel(
        model_name="qwen-max",
        api_key=os.environ["DASHSCOPE_API_KEY"],
        stream=True,
    )

    generator = await model(
        messages=[{"role": "user", "content": "Count from 1 to 10."}],
    )
    async for chunk in generator:
        print(chunk, end="", flush=True)


asyncio.run(main())

模型提供商一览

模型提供商	类名	流式	工具调用	视觉	推理
OpenAI	`OpenAIChatModel`	✅	✅	✅	✅
DashScope（通义）	`DashScopeChatModel`	✅	✅	✅	✅
Anthropic（Claude）	`AnthropicChatModel`	✅	✅	✅	✅
Google Gemini	`GeminiChatModel`	✅	✅	✅	✅
Ollama（本地）	`OllamaChatModel`	✅	✅	✅	✅
vLLM（OpenAI 兼容）	`OpenAIChatModel`	✅	✅	-	-
DeepSeek（OpenAI 兼容）	`OpenAIChatModel`	✅	✅	-	✅

参考资料

AgentScope GitHub
AgentScope 官方文档
uv 包管理工具
论文：AgentScope: A Flexible yet Robust Multi-Agent Platform