Last month, I hit a wall. I was building a multi-step research pipeline where one agent needed to browse the web, another had to synthesize findings into a report, and a third had to verify the citations. I tried wiring it together with a popular agent framework, but I spent more time fighting with callback loops, state management, and execution errors than actually building the logic. When an agent failed midway through a long task, the whole chain collapsed, and debugging felt like searching for a needle in a stack of print statements.
That frustration led me to AgentScope, an open-source multi-agent framework that takes a distinctly different approach to building agent systems. After spending a few weeks building and deploying with it, I can walk you through how it actually works—warts and all.
The Problem AgentScope Solves
Most agent frameworks treat agents as simple prompt-and-response wrappers. AgentScope is built around the reality that agents need to do things—use tools, manage long-running contexts, recover from failures, and coordinate with each other and humans. It's designed for what the team calls "agentic applications," where LLMs don't just respond but reason, act, and iterate.
The core philosophy is grounded in the ReAct paradigm (Reason + Act), but AgentScope extends this with systematic asynchronous design, built-in tool permissions, and a runtime sandbox so your agents can actually execute code safely without burning down your infrastructure.
Getting Started: Installation and Setup
First, let's get it installed. AgentScope requires Python 3.9+:
pip install agentscope
For the full experience with the visual studio and sandbox features, I recommend installing with all extras:
pip install "agentscope[full]"
The first thing you need to configure is your model access. AgentScope supports multiple model providers and has built-in retry and fallback logic—which alone saved me hours of headache. Create a configuration file called model_config.json:
{
"model_configs": [
{
"config_name": "gpt-4o",
"model_type": "openai_chat",
"model_name": "gpt-4o",
"api_key": "your-api-key-here"
},
{
"config_name": "gpt-4o-mini-fallback",
"model_type": "openai_chat",
"model_name": "gpt-4o-mini",
"api_key": "your-api-key-here"
}
]
}
The fallback setup is crucial. When I was running a batch of 50 research tasks, the primary model hit rate limits. AgentScope automatically fell back to the secondary model without me writing a single retry loop. That's the kind of engineering support that separates a toy framework from a production tool.
Building Your First Agent
Let's build something real: a research agent that can search the web and summarize findings. AgentScope provides built-in agent classes, but you can also create custom ones.
import agentscope
from agentscope.agents import ReActAgent
from agentscope.service import ServiceFactory
# Initialize the framework
agentscope.init(model_configs="model_config.json")
# Create a research agent with web search capability
research_agent = ReActAgent(
name="researcher",
model_config_name="gpt-4o",
service_list=[
ServiceFactory.create("web_search"),
ServiceFactory.create("text_summarization"),
],
max_iters=5,
)
The ReActAgent is one of AgentScope's built-in agents. It follows the Reason-Act-Observe loop automatically. When you give it a task, it reasons about what tool to use, calls that tool, observes the result, and decides whether it needs more information or has a final answer.
Running it is straightforward:
result = research_agent("Research the latest developments in Rust's async ecosystem and provide a summary")
print(result.content)
What surprised me was the transparency. AgentScope logs every step of the reasoning loop—what the agent thought, which tool it called, what arguments it passed, and what it observed. When things go wrong, you can actually see where the reasoning broke down.
Multi-Agent Coordination: Where It Gets Interesting
Single agents are fine, but the real power comes from coordination. I rebuilt my research pipeline using three agents:
from agentscope.agents import ReActAgent, UserAgent
from agentscope.pipeline import SequentialPipeline
# Research agent - finds information
researcher = ReActAgent(
name="researcher",
model_config_name="gpt-4o",
service_list=[ServiceFactory.create("web_search")],
)
# Writer agent - synthesizes findings
writer = ReActAgent(
name="writer",
model_config_name="gpt-4o",
service_list=[ServiceFactory.create("text_summarization")],
)
# Verifier agent - checks citations
verifier = ReActAgent(
name="verifier",
model_config_name="gpt-4o",
service_list=[ServiceFactory.create("web_search")],
)
# Chain them together
pipeline = SequentialPipeline([researcher, writer, verifier])
result = pipeline("Write a brief on quantum computing error correction with verified citations")
The SequentialPipeline passes the output of each agent to the next. But AgentScope also supports more complex patterns. For tasks that can be parallelized, there's ForkedPipeline. For conversational flows between agents, there's DialogPipeline.
I made a mistake early on that cost me an afternoon: I tried to have the verifier agent directly modify the writer's output. But in AgentScope, each agent operates on the message it receives. The fix was to structure the verifier's prompt to output a corrected version of the text, not just a list of issues. Once I understood the message-passing model, everything clicked.
The Sandbox: Safe Execution
One of my biggest concerns with autonomous agents is safety. An agent that can execute arbitrary code or make unrestricted API calls is a liability. AgentScope 2.0 introduced a runtime sandbox that isolates agent execution.
from agentscope.runtime import SandboxRuntime
# Create a sandboxed environment
runtime = SandboxRuntime(
workspace="./agent_workspace",
permissions={
"allow_network": True,
"allow_file_write": True,
"restricted_paths": ["/etc", "/var"],
}
)
# Run agent within the sandbox
with runtime:
result = research_agent("Download and analyze the CSV from example.com/data.csv")
The sandbox restricts what agents can access. I tested this by intentionally crafting a prompt that tried to read /etc/passwd—the sandbox blocked it cleanly and logged the attempt. This is essential if you're letting agents handle user-provided inputs or run in production.
Memory: Making Agents Remember
By default, agents are stateless between sessions. But real applications need persistence. AgentScope integrates with ReMe, a memory management toolkit that gives agents persistent, retrievable memory.
from agentscope.memory import ReMeMemory
# Attach persistent memory to an agent
researcher.memory = ReMeMemory(
storage_type="vector",
persist_dir="./agent_memories/researcher",
)
# Now the agent remembers across sessions
researcher("I'm particularly interested in systems programming languages")
# ... later session ...
researcher("What's new in the programming language world?")
# The agent will prioritize systems programming topics based on stored preferences
I found this particularly useful for a personal assistant agent I built. It remembers my preferences for citation formats, writing style, and even which sources I trust. The vector-based retrieval means it doesn't just dump everything into the context window—it pulls relevant memories based on the current query.
The Visual Studio: Debugging Long Trajectories
Debugging agent behavior is notoriously painful. AgentScope includes a visual studio that lets you trace every step of an agent's execution. After running a pipeline, you can launch the studio:
as-studio --log-dir ./runs/2024-01-15-research-pipeline
This opens a web interface where you can see the full trajectory of each agent—every reasoning step, tool call, and observation. When my verifier agent kept rejecting valid citations, the studio showed me it was misinterpreting the output format from the researcher. I could see the exact message that caused the confusion and adjust the prompt accordingly.
Honest Limitations
After several weeks of use, here's where AgentScope falls short:
Documentation gaps. The framework is evolving fast (AgentScope 2.0 just landed), and some features are better documented in GitHub issues than in official docs. I spent a frustrating evening figuring out the correct way to configure custom tools because the example code was outdated.
Java ecosystem separation. There's an AgentScope-Java for enterprise JVM applications, but it's a separate codebase with different patterns. If you need Python-Java interop between agents, you're on your own bridging them.
Resource consumption. The sandbox and memory systems add overhead. Running three agents with persistent memory and sandboxing consumed about 4GB of RAM on my machine. For simple tasks, this feels heavy.
HiClaw complexity. The multi-agent OS (HiClaw) that handles human-in-the-loop coordination via Matrix rooms is powerful but has a steep learning curve. I set it up once and decided it was overkill for my use case—stick with simpler pipelines unless you genuinely need real-time human-agent collaboration.
Practical Tips
Start with
ReActAgentbefore building custom agents. The built-in agent handles the reasoning loop correctly, and you can customize behavior through prompts and tool selection.Always configure a fallback model. Rate limits and API outages will happen. The two minutes you spend setting up a fallback model will save you hours of failed runs.
Use the visual studio from day one. Don't wait until something breaks. Getting familiar with the trace interface early makes debugging dramatically faster when you need it.
Structure prompts for message-passing. Each agent receives the previous agent's output as its input. Write your agent prompts with this in mind—explicitly tell each agent what format to produce for the next agent.
Test in the sandbox before deploying. Even if you trust your prompts, test with adversarial inputs in the sandbox. It's better to discover permission issues locally than in production.
AgentScope isn't the simplest framework to pick up, but it's one of the few that actually handles the messy reality of production agent systems—failures, safety, coordination, and debugging. If you're building anything beyond a demo, that matters more than a quick start.