[KongchangAI]
· 2 min read· 1,391 words

AgentScope 2.0 Hands-On Tutorial: Master Agent Orchestration and Security from Zero

AgentScope 2.0 Hands-On Tutorial: Master Agent Orchestration and Security from Zero

AgentScope 2.0 provides production-grade agent development centered on the ReAct loop, a three-dimensional security defense line, and context management.

The article introduces the core capabilities of the agent development framework AgentScope 2.0. It explains the autonomy that distinguishes agents from chatbots—thinking, calling tools, and executing tasks in a closed loop—and the resulting control challenges. AgentScope 2.0 has massive changes and should be learned directly. Its three core capabilities are: the ReAct agent loop with multi-round think-act-observe iteration, tool calling, streaming, and interruption recovery; a three-dimensional security defense line of tool review, human-in-the-loop, and sandbox isolation; and systematic context management for long tasks. Both Python and Java versions are offered, with the tutorial focusing on Python.

Why Do We Need AgentScope 2.0?

An ordinary chatbot can only answer questions, while an agent can think autonomously, call tools, and execute tasks. For example, if you ask it to analyze sales data, generate a report, and email it to the manager, it will automatically read the data, invoke Python for analysis, and then call the email tool to complete the loop. The more capable it is, the more complex development and control become—how do you ensure the agent doesn't go off the rails? How do you pinpoint issues when something goes wrong? This is exactly the problem that an agent development framework is meant to solve.

AgentScope is one such development framework that helps developers build, deploy, manage, and run agents. According to a tutorial by Bilibili creator "Teacher Shanshan," version 2.0 has devastating changes compared to 1.0, with a large number of APIs deprecated. Learning 2.0 directly is enough to meet production-grade needs.

Much of 1.0 has been overturned

Core Capability 1: The ReAct Agent Loop

ReAct is not a frontend framework; it is a combination of Reasoning and Acting. Take "check the weather in Beijing and remind me to bring an umbrella" as an example: after receiving the request, the agent first thinks—it needs to know the weather to decide whether an umbrella is needed, so it calls the weather tool. After getting the result "rain," it thinks again and decides to remind the user to bring an umbrella. The whole process is a loop of "think → act → observe → think again." Complex tasks repeat this for multiple rounds, such as reading web pages and executing Python code to analyze data, until a final result is produced.

AgentScope treats this ReAct pattern as its core construction method, providing tool calling, streaming execution, interruption recovery, and other capabilities to adapt to complex task scenarios.

Oh, I realize I need to call a tool

The idea behind the ReAct pattern can be traced back to a 2022 paper, ReAct: Synergizing Reasoning and Acting in Language Models. Before ReAct, mainstream approaches were either pure reasoning (such as Chain-of-Thought, which only generates reasoning steps but does not interact with the external environment) or pure acting (directly calling tools but lacking reasoning and planning). ReAct alternates between the two, having the model explicitly output "Thought" and "Action" at each step, then adjust the next step based on the "Observation" returned by the environment, thereby significantly reducing hallucinations and improving interpretability. Because each step's thought and action are explicit text, during debugging you can clearly see why the agent called a particular tool and on what basis—this is also why it has become the de facto standard loop pattern for agent frameworks.

Core Capability 2: A Three-Dimensional Integrated Security Defense Line

As agents gain more and more permissions—able to delete files, execute shell commands, operate databases, send emails, and call internal systems—the risk of fully autonomous operation cannot be ignored. For example, if you ask it to clean up useless files, it may misjudge and execute rm -rf; a single mistake could have a fatal impact on the production environment. AgentScope builds a security defense line with a three-layer mechanism:

Tool Review

Not all tools are allowed to be called freely. Ordinary tools such as weather queries can be executed directly; sensitive tools such as deleting database content require further checks.

Human-in-the-Loop

The agent can work autonomously, but humans have the final say on key steps. For example, when it is about to execute a DELETE statement, it pauses and waits for an administrator to approve or reject it, leaving the final interpretation of high-risk actions to humans.

The probability of error

Sandbox Isolation

Even with human-in-the-loop, approvals can still be wrong, so an isolated environment is needed. A sandbox lets the agent execute code and process files in an independent space, avoiding impact on the host system. The three layers can be used together, answering respectively "can it be done," "is it allowed to be done," and "where can it be done safely."

Prepare one for the agent

The term "sandbox" originates from the operating systems and security field and refers to technology that provides a restricted execution environment for untrusted code. Common implementations include container-based isolation (such as Docker, restricting file systems, networks, and resource quotas), virtual machine-based isolation (such as Firecracker microVMs), and language-level sandboxes (such as Python subprocesses with privilege dropping and seccomp system call filtering). In agent scenarios, sandboxes need to additionally consider requirements such as persistent files, dependency installation, and network access whitelists, so they usually provide reusable working directories and controlled network egress. Compared with tool review and human-in-the-loop, the sandbox is the "last line of defense": even if the first two layers misjudge, damage is confined to the isolated environment, and the host and production data remain unaffected.

Core Capability 3: Systematic Context Management

When an agent works for a long time, it accumulates a large amount of context: searching multiple web pages, repeatedly calling tools, and reading many files. The content returned each time keeps accumulating, the context window quickly fills up, and important information gets buried. AgentScope provides a variety of context management methods to address this challenge; the specific methods will be covered in subsequent lessons.

The context window refers to the maximum number of tokens a large model can receive in a single inference, including all content such as system prompts, historical conversations, and tool return results. Once the limit is exceeded, the model either reports an error or is forced to truncate earlier content, leading to the "Lost in the Middle" phenomenon—information located in the middle of the context is most easily ignored. Common context management strategies include: sliding window truncation to retain the most recent several rounds, summarizing and compressing historical content, externalizing long-term information to a vector database or file system for on-demand retrieval (the RAG approach), and structurally trimming overly long tool return results. Understanding the trade-offs of these mechanisms is key to assessing whether an agent can work stably over long periods.

Version Selection and Learning Path

AgentScope provides both a Python version and a Java version; the current tutorial focuses on the Python version. The official documentation supports switching to Chinese, and developers with strong self-learning ability can expand their knowledge by consulting the documentation. For beginners, starting directly with 2.0 is sufficient; there is no need to transition from 1.0.

Overall, AgentScope provides a set of production-oriented agent engineering capabilities centered on the security and context problems brought by autonomy, making it one of the optional frameworks for building complex intelligent applications.

A multilingual SDK (both Python and Java versions) is not common among agent frameworks. Its significance lies in covering teams with different technology stacks: the Python version's ecosystem is closer to model training and data processing, suitable for algorithms and rapid prototyping; the Java version facilitates enterprise-level backend system integration and can reuse existing Spring ecosystems, permission systems, and operations infrastructure. Note that the two versions may differ in evolution pace and feature coverage, and cross-language interoperability usually relies on unified communication protocols or service-oriented deployment. When choosing a version, prioritize the team's existing technology stack and deployment environment rather than simply comparing language features.

One-line Summary

AgentScope 2.0 provides production-grade agent development capabilities centered on the ReAct loop, a three-dimensional security defense line, and context management.

Paragraph Summary

The article introduces the core capabilities of the agent development framework AgentScope 2.0. It first explains the autonomy that distinguishes agents from chatbots—the ability to think, call tools, and execute tasks in a closed loop—along with the resulting control and troubleshooting challenges. AgentScope 2.0 has massive changes, so learning it directly is recommended. Its three core capabilities are: first, the ReAct agent loop, which completes complex tasks through multiple rounds of "think—act—observe—think again" iteration, and provides tool calling, streaming execution, and interruption recovery; second, a three-dimensional security defense line, where tool review decides "can it be done," human-in-the-loop decides "is it allowed to be done," and sandbox isolation decides "where it can be done safely," with the three layers usable together; third, systematic context management, addressing the problem of context accumulation burying key information in long tasks. The framework provides both Python and Java versions, with the tutorial focusing on Python.

#AgentScope 2.0#agent orchestration#ReAct agent loop#human-in-the-loop#sandbox isolation#context management
Share:

Related articles