AgentScope

April 15, 2026 · View on GitHub

本文档为本目录所有技术声明提供源码引用证据。所有引用基于 /root/git/agentscope（AgentScope 0.x，2026 年 4 月当前）。

1. 代码规模与元数据

1.1 Python 代码量

$ find src -name "*.py" | wc -l
215
$ find src -name "*.py" | xargs wc -l | tail -1
  43574 total

声明：AgentScope 共 215 个 Python 文件 / 43,574 行代码。

1.2 许可证、Python 版本

pyproject.toml:3-21

[project]
name = "agentscope"
dynamic = ["version"]
description = "AgentScope: A Flexible yet Robust Multi-Agent Platform."
readme = "README.md"
authors = [
    { name = "SysML team of Alibaba Tongyi Lab", email = "gaodawei.gdw@alibaba-inc.com" }
]
license = "Apache-2.0"
keywords = ["deep-learning", "multi agents", "agents"]
...
requires-python = ">=3.10"

声明：

  • 许可证：Apache-2.0
  • Python：>=3.10
  • 作者：Alibaba Tongyi Lab SysML team

1.3 核心依赖

pyproject.toml:22-45

dependencies = [
    "aioitertools",
    "anthropic",
    "dashscope",
    "docstring_parser",
    "filetype",
    "json5",
    "json_repair",
    "mcp>=1.13",
    "numpy",
    "openai",
    "python-datauri",
    "opentelemetry-api>=1.39.0",
    "opentelemetry-sdk>=1.39.0",
    "opentelemetry-exporter-otlp>=1.39.0",
    "opentelemetry-semantic-conventions>=0.60b0",
    "python-socketio",
    "shortuuid",
    "tiktoken",
    ...
]

关键依赖：anthropic + openai + dashscope（Alibaba）三大 SDK，mcp>=1.13 官方 MCP，完整 OTel 栈。

1.4 README 定位

README.md:61-64

AgentScope is a production-ready, easy-to-use agent framework with
essential abstractions that work with rising model capability and
built-in support for finetuning. We design for increasingly agentic
LLMs. Our approach leverages the models' reasoning and tool use
abilities rather than constraining them with strict prompts and
opinionated orchestrations.

2. Agent 基础类

2.1 AgentBase

src/agentscope/agent/_agent_base.py:30-31

class AgentBase(StateModule, metaclass=_AgentMeta):
    """Base class for asynchronous agents."""

2.2 ReActAgentBase（抽象 ReAct）

src/agentscope/agent/_react_agent_base.py:12-19

"""
The ReAct agent base class. To support ReAct algorithm, this class
extends the AgentBase class by adding two abstract interfaces:
reasoning and acting, while supporting hook functions at four
positions: pre-reasoning, post-reasoning, pre-acting, and post-acting
by the `_ReActAgentMeta` metaclass.
"""

2.3 Hook 类型清单

src/agentscope/agent/_agent_base.py:36-138

supported_hook_types: list[str] = [
    "pre_reply",
    "post_reply",
    "pre_print",
    "post_print",
    "pre_observe",
    "post_observe",
]

src/agentscope/agent/_react_agent_base.py:21-32

supported_hook_types: list[str] = [
    # ... base hooks ...
    "pre_reasoning",
    "post_reasoning",
    "pre_acting",
    "post_acting",
]

声明：共 10 种 hook 事件，分为 6 个基础（reply/print/observe × pre/post）+ 4 个 ReAct（reasoning/acting × pre/post）。

3. ReActAgent 主循环

3.1 默认 max_iters

src/agentscope/agent/_react_agent.py:197

max_iters (`int`, defaults to `10`): The maximum number of
iterations of the reasoning-acting loops.

声明：默认最大迭代数 = 10。

3.2 reply() 主循环

src/agentscope/agent/_react_agent.py:428-437

# -------------- The reasoning-acting loop --------------
# Cache the structured output generated in the finish function call
structured_output = None
reply_msg = None
for _ in range(self.max_iters):
    # -------------- Memory compression --------------
    await self._compress_memory_if_needed()

    # -------------- The reasoning process --------------
    msg_reasoning = await self._reasoning(tool_choice)

3.3 并行工具调用

src/agentscope/agent/_react_agent.py:237

parallel_tool_calls (`bool`, defaults to `False`): When LLM generates
multiple tool calls, whether to execute them in parallel.

src/agentscope/agent/_react_agent.py:440-451

futures = [
    self._acting(tool_call)
    for tool_call in msg_reasoning.get_content_blocks(
        "tool_use",
    )
]
# Parallel tool calls or not
if self.parallel_tool_calls:
    structured_outputs = await asyncio.gather(*futures)
else:
    # Sequential tool calls
    structured_outputs = [await _ for _ in futures]

声明：parallel tool call 默认关闭，开启后用 asyncio.gather 并发。

3.4 退出条件

src/agentscope/agent/_react_agent.py:513-518

elif not msg_reasoning.has_content_blocks("tool_use"):
    # Exit the loop when no structured output is required (or
    # already satisfied) and only text response is generated
    msg_reasoning.metadata = structured_output
    reply_msg = msg_reasoning
    break

声明：模型输出纯文本（无 tool_use block）→ 退出 loop。

3.5 _reasoning 方法

src/agentscope/agent/_react_agent.py:540-572

async def _reasoning(
    self,
    tool_choice: Literal["auto", "none", "required"] | None = None,
) -> Msg:
    """Perform the reasoning process."""
    # ...
    res = await self.model(
        prompt,
        tools=self.toolkit.get_json_schemas(),
        tool_choice=tool_choice,
    )

3.6 _acting 方法

src/agentscope/agent/_react_agent.py:657-715

async def _acting(self, tool_call: ToolUseBlock) -> dict | None:
    """Perform the acting process, and return the structured output if
    it's generated and verified in the finish function call."""
    # ...
    tool_res = await self.toolkit.call_tool_function(tool_call)

    # Async generator handling
    async for chunk in tool_res:
        # Turn into a tool result block
        tool_res_msg.content[0][
            "output"
        ] = chunk.content

3.7 Knowledge Base 检索

src/agentscope/agent/_react_agent.py:402

# Retrieve relevant documents from the knowledge base(s) if any
await self._retrieve_from_knowledge(msg)

3.8 Memory 压缩配置

src/agentscope/agent/_react_agent.py:107-162

class CompressionConfig(BaseModel):
    """The compression related configuration in AgentScope"""
    enable: bool
    agent_token_counter: TokenCounterBase
    trigger_threshold: int
    keep_recent: int = 3

声明：压缩配置包含 trigger_threshold（触发阈值）和 keep_recent: int = 3（保留最近 3 条）。

4. Toolkit

4.1 Toolkit 类定义

src/agentscope/tool/_toolkit.py:117-138

"""
Toolkit is the core module to register, manage and delete tool functions,
MCP clients, Agent skills in AgentScope.

About tool functions:
- Register and parse JSON schemas from their docstrings automatically.
- Group-wise tools management, and agentic tools activation/deactivation.
- Extend the tool function JSON schema dynamically with Pydantic BaseModel.
- Tool function execution with unified streaming interface.
"""

4.2 Tool 注册与 Schema 解析

src/agentscope/tool/_toolkit.py:336-534（register_tool_function 范围）

src/agentscope/tool/_toolkit.py:409-425

json_schema = json_schema or _parse_tool_function(
    tool_func,
    include_long_description=include_long_description,
    include_var_positional=include_var_positional,
    include_var_keyword=include_var_keyword,
)

4.3 MCP 集成

src/agentscope/tool/_toolkit.py:23

import mcp

src/agentscope/mcp/_client_base.py:18

class MCPClientBase:
    """Base class for MCP clients."""

声明：AgentScope 使用官方 mcp>=1.13 SDK（pyproject.toml:30）。

5. Memory System

5.1 MemoryBase 抽象

src/agentscope/memory/_working_memory/_base.py:11

class MemoryBase(StateModule):
    """The base class for memory in agentscope."""

5.2 Memory 后端文件

src/agentscope/memory/_working_memory/
├── _base.py
├── _in_memory_memory.py        # InMemoryMemory
├── _redis_memory.py            # RedisMemory
├── _sqlalchemy_memory.py       # SQLAlchemyMemory
└── _tablestore_memory.py       # TablestoreMemory (Alibaba)

声明：4 种 working memory 后端。

6. Plan 模块

6.1 PlanNotebook 类定义

src/agentscope/plan/_plan_notebook.py:172

"""The plan notebook to manage the plan, providing hints and plan related
tool functions to the agent."""

6.2 Plan 数据模型

src/agentscope/plan/__init__.py:4-10

from ._plan_model import (
    SubTask,
    Plan,
)

6.3 SubTask 状态机

src/agentscope/plan/_plan_notebook.py:119-133

if subtask.state == "todo":
    n_todo += 1
elif subtask.state == "in_progress":
    n_in_progress += 1
    in_progress_subtask_idx = idx
elif subtask.state == "done":
    n_done += 1
elif subtask.state == "abandoned":
    n_abandoned += 1

声明：subtask 4 个状态：todo / in_progress / done / abandoned。

6.4 Plan Hint 注入模板

src/agentscope/plan/_plan_notebook.py:50-68

when_a_subtask_in_progress: str = (
    "The current plan:\n"
    "```\n"
    "{plan}\n"
    "```\n"
    "Now the subtask at index {subtask_idx}, named '{subtask_name}', is "
    "'in_progress'. Its details are as follows:\n"
    "```\n"
    "{subtask}\n"
    "```\n"
    ...
)

7. A2A 协议

7.1 A2A 模块说明

src/agentscope/a2a/__init__.py:2

"""The A2A related modules."""

7.2 A2A 可选依赖

pyproject.toml:50

a2a = [
    "a2a-sdk",
    "httpx",
    # TODO: split the card resolvers from the a2a dependency
    "nacos-sdk-python>=3.0.0",
]

声明：A2A 通过官方 a2a-sdk 实现，Nacos 作为服务发现 backend。

7.3 AgentCard Resolver 抽象

src/agentscope/a2a/_base.py:18-25

@abstractmethod
async def get_agent_card(self, *args: Any, **kwargs: Any) -> AgentCard:
    """Get Agent Card from the configured source.

    Returns:
        `AgentCard`:
            The resolved agent card object.
    """

8. Tracing

8.1 OTel 依赖

pyproject.toml:34-37

opentelemetry-api>=1.39.0,
opentelemetry-sdk>=1.39.0,
opentelemetry-exporter-otlp>=1.39.0,
opentelemetry-semantic-conventions>=0.60b0,

8.2 13 个 Span Extractor

src/agentscope/tracing/_trace.py:24-45

from ._extractor import (
    _get_agent_request_attributes,
    _get_agent_span_name,
    _get_agent_response_attributes,
    _get_llm_request_attributes,
    _get_llm_span_name,
    _get_llm_response_attributes,
    _get_tool_request_attributes,
    _get_tool_span_name,
    _get_tool_response_attributes,
    _get_formatter_request_attributes,
    _get_formatter_span_name,
    _get_formatter_response_attributes,
    _get_generic_function_request_attributes,
    _get_generic_function_span_name,
    _get_generic_function_response_attributes,
    _get_embedding_request_attributes,
    _get_embedding_span_name,
    _get_embedding_response_attributes,
)

声明：5 类操作 × 3 种 extractor (span_name + request_attrs + response_attrs) = 15 个函数（上面 15 + 2 generic = 17，但覆盖 5 类实体）。

9. Tune / Tuner

9.1 tune() 接口

src/agentscope/tune/_tune.py:16-97

def tune(
    *,
    workflow_func: WorkflowType,
    judge_func: JudgeType | None = None,
    train_dataset: DatasetConfig | None = None,
    eval_dataset: DatasetConfig | None = None,
    model: TunerModelConfig | None = None,
    ...
) -> None:
    """Train the agent workflow with the specific configuration."""

9.2 Trinity-RFT 集成

src/agentscope/tune/_tune.py:61-68

try:
    from trinity.cli.launcher import run_stage
    from trinity.utils.dlc_utils import setup_ray_cluster, stop_ray_cluster
except ImportError as e:
    raise ImportError(
        "Trinity-RFT is not installed. Please install it with "
        "`pip install trinity-rft`.",
    ) from e

声明：微调功能通过 Trinity-RFT 实现，支持 Ray 分布式训练。

10. Realtime + TTS

10.1 TTSModelBase

src/agentscope/tts/_tts_base.py:12-39

class TTSModelBase(ABC):
    """Base class for TTS models in AgentScope.

    This base class provides general abstraction for both realtime and
    non-realtime TTS models (depending on whether streaming input is
    supported).
    """
    supports_streaming_input: bool = False
    model_name: str
    stream: bool

10.2 TTS Provider 列表

src/agentscope/tts/__init__.py:1-9

声明：支持 OpenAI TTS / DashScope / Google Gemini / DashScope CosyVoice。

10.3 Realtime WebSocket

src/agentscope/realtime/_base.py:13

class RealtimeModelBase:
    """The realtime model base class."""

src/agentscope/realtime/_base.py:68-93

async def connect(
    self,
    outgoing_queue: Queue,
    instructions: str,
    tools: list[dict] | None = None,
) -> None:
    """Establish a connection to the realtime model."""
    import websockets

    self._websocket = await websockets.connect(
        self.websocket_url,
        additional_headers=self.websocket_headers,
    )

11. MsgHub 多 Agent

11.1 MsgHub 类定义

src/agentscope/pipeline/_msghub.py:14

class MsgHub:
    """MsgHub class that controls the subscription of the participated agents.

    Example:
        In the following example, the reply message from `agent1`, `agent2`,
        and `agent3` will be broadcast to all the other agents in the MsgHub.
    """

12. Session

12.1 SessionBase

src/agentscope/session/_session_base.py:8

class SessionBase:
    """The base class for session in agentscope."""

    @abstractmethod
    async def save_session_state(
        self,
        session_id: str,
        user_id: str = "",
        **state_modules_mapping: StateModule,
    ) -> None:
        """Save the session state"""

13. Formatter

13.1 FormatterBase

src/agentscope/formatter/_formatter_base.py:11

class FormatterBase:
    """The base class for formatters."""

    @abstractmethod
    async def format(self, *args: Any, **kwargs: Any) -> list[dict[str, Any]]:
        """Format the Msg objects to a list of dictionaries that satisfy the
        API requirements."""

13.2 Formatter 文件清单

src/agentscope/formatter/
├── _formatter_base.py
├── _openai_formatter.py
├── _anthropic_formatter.py
├── _dashscope_formatter.py
├── _gemini_formatter.py
├── _deepseek_formatter.py
├── _ollama_formatter.py
└── _a2a_formatter.py

声明：7 个具体 formatter 实现。

14. Evaluate

14.1 EvaluatorBase

src/agentscope/evaluate/_evaluator/_evaluator_base.py:18

class EvaluatorBase:
    """The class that runs the evaluation process."""

    def __init__(
        self,
        name: str,
        benchmark: BenchmarkBase,
        n_repeat: int,
        storage: EvaluatorStorageBase,
    ) -> None:

14.2 Ray 并行依赖

pyproject.toml:145

evaluate = ["ray"]

15. 验证状态总表

声明验证源码引用
Python >= 3.10✓pyproject.toml:21
Apache-2.0✓pyproject.toml:10
215 .py 文件 / 43,574 行✓find + wc -l
ReAct 显式 reasoning+acting✓_react_agent_base.py:12-19
默认 max_iters=10✓_react_agent.py:197
并行 tool call 可选✓_react_agent.py:237, 440-451
10 种 hook 事件✓_agent_base.py:36-138 + _react_agent_base.py:21-32
Memory 压缩 keep_recent=3✓_react_agent.py:107-162
4 种 working memory 后端✓memory/_working_memory/*.py
Plan 4 状态机✓_plan_notebook.py:119-133
A2A via 官方 a2a-sdk✓pyproject.toml:50
MCP via mcp>=1.13✓pyproject.toml:30 + _toolkit.py:23
OTel tracing 13 extractor✓tracing/_trace.py:24-45
Trinity-RFT 微调✓_tune.py:61-68
Realtime WebSocket✓realtime/_base.py:68-93
7 个 formatter✓formatter/*.py

分析版本：AgentScope 0.x（2026 年 4 月） 源码位置：/root/git/agentscope 分析日期：2026-04-14