AgentScope 2.0 Deep Dive: A Complete Guide to the Multi-Agent Development Framework

What Is AgentScope? The Evolution from Chatbots to Agents

Before diving into the framework details, we need to understand a fundamental question: What exactly is the difference between an Agent and a regular chatbot?

A regular chatbot only answers questions — you ask something, it responds. An Agent, on the other hand, can not only converse but also think autonomously, invoke tools, and execute tasks. Consider a typical scenario: you assign an Agent the task of "analyzing today's sales data, generating a report, and emailing it to the company manager." The Agent will independently read the sales data, call Python data analysis functions, generate the report, and finally use an email tool to send it.

The concept of an Agent originates from classical AI research, traceable back to the field of distributed artificial intelligence in the 1990s. Unlike simple Q&A chatbots, Agents possess three core characteristics: Autonomy — the ability to operate independently without continuous human intervention; Reactivity — the ability to perceive environmental changes and respond accordingly; and Social Ability — the ability to collaborate and interact with other Agents or humans. The current AI Agent boom exists precisely because the reasoning capabilities of large language models have made these three characteristics achievable in general-purpose scenarios for the first time.

As Agents become capable of doing more and more, problems emerge: How do we develop them, control them, and ensure they don't go rogue? When something goes wrong, how do we pinpoint the exact issue? This is exactly why agent development frameworks were created, and Alibaba's AgentScope is one representative product in this space.

Simple definition: AgentScope is a development framework that helps developers handle the entire lifecycle of Agent building, deployment, management, and execution — essentially an engineering tool for "managing Agents."

Why Learn Version 2.0 Directly?

AgentScope 2.0 underwent a major architectural upgrade compared to 1.0: numerous APIs were deprecated and the architecture was substantially refactored. This means if you learned 1.0 before studying 2.0, you'd find much of your knowledge needs to be relearned. Therefore, for newcomers, there's no need to start with 1.0 — jump straight into 2.0, as it's already production-ready.

Agent development frameworks went through a rapid iteration cycle during 2023-2024. Early frameworks like LangChain and AutoGen primarily addressed the orchestration of LLM call chains, but as Agent applications moved from experimentation to production, developers demanded more: stable error recovery mechanisms, fine-grained permission controls, efficient context management, and multi-Agent coordination capabilities. AgentScope 2.0's large-scale refactoring was a direct response to this trend — many experimental APIs from 1.0 were replaced with more mature design patterns suited for production needs, which is why the two versions have significant incompatibilities.

Core Capability 1: How ReAct Agents Work

The name ReAct is easily confused with the frontend framework React, but the two are completely unrelated. Here, ReAct stands for Reasoning + Acting — a pattern for building agents that "think and act simultaneously."

The ReAct pattern was first proposed by researchers from Princeton University and the Google Brain team in their 2022 paper ReAct: Synergizing Reasoning and Acting in Language Models. Before this, the field had two mainstream paradigms: Chain-of-Thought — having the model reason step by step without interacting with the external environment; and Act-only — having the model directly invoke tools without a reasoning process. ReAct's innovation was interweaving both: at each step, the model first generates a reasoning process (Thought), then decides what action to take (Action), and finally observes the action's result (Observation), forming a closed loop. This pattern significantly improved Agent success rates and interpretability on complex tasks.

Let's understand this loop with an example: suppose you tell an Agent, "Check Beijing's weather today, and if it's raining, remind me to bring an umbrella." The LLM itself doesn't know whether it's raining in Beijing today, so the Agent goes through this process:

1. Receive the request: The user asks whether they need an umbrella
2. Think (Thought): Whether to bring an umbrella depends on the weather, so I need to check the weather first
3. Act (Action): Call the weather query tool
4. Observe (Observation): The tool returns "It's raining in Beijing today"
5. Think again: Since it's raining, I should remind the user to bring an umbrella
6. Return the answer: "It's raining in Beijing — I recommend bringing an umbrella"

The key point is that this loop doesn't execute just once. For complex tasks, the Agent may repeatedly go through the "think → invoke tool → observe result → think again" cycle: reading web pages, running Python code for data analysis, calling tools multiple times, breaking down and completing complex tasks layer by layer.

AgentScope uses ReAct as its core approach to building agents and provides tool invocation, streaming execution, and checkpoint & resume capabilities around it, making it better suited for complex task scenarios.

Checkpoint & Resume is a critical capability for production-grade Agent systems. In real deployments, Agents executing complex tasks may take tens of minutes or even hours, during which they might encounter network interruptions, API rate limiting, server restarts, and other unexpected situations. Without a checkpoint & resume mechanism, all completed intermediate steps and accumulated context would be lost, forcing the Agent to start from scratch. AgentScope's checkpoint & resume capability allows the system to save its current state at any step (including conversation history, tool call results, and intermediate reasoning artifacts) and continue execution from the breakpoint after fault recovery — this is especially important for long-running automated workflows.

Core Capability 2: A Three-Dimensional Security Defense

If an Agent can only answer "What's the weather in Beijing?", security is barely a concern. But when an Agent's permissions grow — able to delete files, execute code, run Shell commands, operate databases, send emails, and even access internal company systems — would you dare let it run fully autonomously?

Imagine this scenario: you ask an Agent to clean up unused files in a project. It determines a file is unnecessary and directly executes rm -rf, accidentally deleting the wrong thing. rm -rf is a forced recursive deletion command in Unix/Linux systems that has caused multiple serious incidents in IT history. In 2017, a GitLab engineer accidentally executed a similar command during manual database maintenance, deleting 300GB of production data — they ultimately relied on a 6-hour-old backup for partial recovery. When the power to execute such dangerous operations is handed to an AI Agent, the risk is amplified further — because the Agent might determine a directory is "useless" based on flawed reasoning, and its decision-making process lacks the experiential intuition and contextual understanding of a human engineer.

While the probability of Agent errors isn't high, even a single mistake can be fatal to a production environment. This is exactly the problem that security defenses are designed to solve. AgentScope provides three layers of protection:

Layer 1: Tool审查 — Tool Review (Can it do this?)

Not all tools can be called freely. For ordinary tools like checking the weather, direct execution is fine. But if an Agent is about to invoke a sensitive tool that would delete database contents, the framework needs to perform a review check, just in case.

Layer 2: Human-in-the-Loop (Does the human allow it?)

Agents can work autonomously, but humans have the final say on critical steps. For example, when an Agent is about to execute a high-risk operation like DELETE FROM ..., it pauses execution and requests administrator approval. If approved, it proceeds; if rejected, it stops or makes adjustments. This mechanism doesn't limit the Agent's autonomy — it preserves human decision-making authority over high-risk actions.

Layer 3: Sandbox Isolation (Where can it safely do this?)

Even with human-in-the-loop controls, humans can make approval errors too. That's why sandbox isolation is needed — preparing an isolated runtime environment for the Agent where it can execute code and process files without affecting the real external systems.

From a technical implementation perspective, a security sandbox is a technology that isolates a program's runtime environment from the host system. In Agent scenarios, sandboxes are typically implemented using container technology (such as Docker) or virtual machines, creating a restricted file system, network, and process space for the Agent. Code executed by the Agent within the sandbox can only access pre-allocated resources — even if the code contains malicious behavior or logical errors, it cannot affect the host system. Beyond AgentScope, products like OpenAI's Code Interpreter and E2B (Everything to Backend) also widely adopt sandbox technology. It's worth noting that sandboxes aren't a silver bullet — certain operations that need to access external APIs or real databases still require additional permission control strategies, which is why the three layers of defense need to work together.

The three mechanisms can be used in combination: tool review addresses "can it do this," human-in-the-loop addresses "does the human allow it," and sandbox isolation addresses "where can it safely do this" — together forming a three-dimensional security defense.

Core Capability 3: Systematic Context Management

Imagine an Agent that has been working continuously for two hours, during which it searched 20 web pages, invoked tools 30 times, and read dozens of files. Each tool call might return 5,000 or even 10,000 words, and this content accumulates continuously into a massive context.

However, an LLM's context window is not infinite. Context window limitations stem from the computational complexity of the self-attention mechanism in the Transformer architecture — standard self-attention scales quadratically with sequence length (O(n²)), meaning every time the context doubles, computational costs quadruple. Although current models have significantly expanded window capacity (e.g., GPT-4 Turbo supports 128K tokens, Claude supports 200K tokens), in scenarios where Agents work for extended periods, accumulated tool returns, web page content, and file data can easily exceed these limits.

More importantly, even within the window range, research has shown that models exhibit the "Lost in the Middle" phenomenon with very long contexts — information in the middle portions tends to be overlooked by the model. This means simply expanding the window doesn't fully solve the problem. As context grows larger, important information gets "drowned out," causing Agent performance to degrade. Therefore, AgentScope provides systematic context management tools that strategically compress, summarize, and filter historical information to address the challenges of long tasks and extended conversations.

AgentScope 2.0: A Production-Oriented Agent Engineering Framework

As Agents become increasingly capable and can autonomously complete complex tasks, their autonomy also introduces two major challenges: security risks and long-context management difficulties. AgentScope is designed precisely around these pain points, offering a complete set of Agent engineering capabilities:

• ReAct pattern supports reasoning and execution loops for complex tasks
• Three-dimensional security defense (tool review, human-in-the-loop, sandbox isolation) ensures controllability
• Systematic context management addresses information accumulation in long-running tasks

Additionally, AgentScope offers both Python and Java versions. The Python version is currently the mainstream choice for learning, and the official documentation supports both Chinese and English, making self-study convenient.

As a production-oriented intelligent application development framework, AgentScope 2.0 provides developers with a complete toolchain from building to managing Agents. For developers looking to enter the multi-agent development space, starting directly with 2.0 is currently the most efficient choice.

Key Takeaways