Last month, I hit a wall. I was building a research pipeline where one agent needed to scrape web pages, another had to extract and summarize key data, and a third needed to compile everything into a structured report. I started with a popular agent framework, but within a week I was drowning in rigid orchestration patterns, custom callback hooks, and boilerplate just to pass a message between two agents. The framework had opinions about how my agents should think, and those opinions didn't match my problem.
That's when a colleague pointed me toward AgentScope 2.0. What caught my eye was its philosophy: instead of constraining models with strict prompts and opinionated orchestrations, it leans into the model's own reasoning and tool-use abilities. After spending a few weeks building with it, I've found it strikes a genuinely useful balance between structure and flexibility. Here's how to get started, learned the hard way so you don't have to.
The Problem AgentScope Actually Solves
Most agent frameworks fall into one of two camps. Either they're so abstract you spend more time building infrastructure than solving your actual problem, or they're so opinionated you're fighting the framework at every turn. AgentScope 2.0 positions itself differently—it gives you production-ready primitives (agents, tools, memory, events, permissions) and then mostly gets out of your way.
The key features that matter in practice:
- Event system for communication between agents and frontend/human-in-the-loop
- Permission system for fine-grained control over what tools and resources agents can access
- Workspace/sandbox support so your agents can run code in isolated Docker or E2B environments
- Middleware system that lets you hook into the reasoning-acting loop without rewriting it
Step 1: Installation and Setup
First things first—AgentScope requires Python 3.10+. I'm using 3.11 for this walkthrough.
# Install the core package
pip install agentscope
# You'll also want the runtime extras for service deployment
pip install "agentscope[runtime]"
The first surprise I hit: AgentScope uses a configuration-driven approach for model setup. You define your model configurations in a JSON or Python file rather than passing API keys everywhere in your code. This felt weird at first, but it actually makes multi-model setups much cleaner.
Create a 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",
"generate_args": {
"temperature": 0.7
}
},
{
"config_name": "gpt-4o-mini",
"model_type": "openai_chat",
"model_name": "gpt-4o-mini",
"api_key": "your-api-key-here",
"generate_args": {
"temperature": 0.3
}
}
]
}
Then in your code, you load it once:
import agentscope
agentscope.init(model_configs="./model_config.json")
I made the mistake early on of trying to pass API keys directly in agent constructors. Don't do that—always use the config file. It saves you from a mess of environment variable juggling when you scale to multiple agents with different models.
Step 2: Building Your First Agent
AgentScope provides base agent classes you extend. The most straightforward is DialogAgent for conversational agents, but for real work you'll usually want ReActAgent which implements the reasoning-acting loop.
Let's build a simple research agent that can search the web and summarize findings:
from agentscope.agents import ReActAgent
from agentscope.service import ServiceToolkit
# Create a toolkit with web search capability
toolkit = ServiceToolkit()
toolkit.add(
agentscope.service.WebSearch,
search_engine="bing",
api_key="your-bing-api-key"
)
# Create the agent
research_agent = ReActAgent(
name="researcher",
model_config_name="gpt-4o",
tool_list=toolkit,
max_iters=5,
prompt_template="""You are a research assistant. When given a topic:
1. Search for relevant information
2. Extract key facts and findings
3. Summarize your findings clearly
Always cite your sources from the search results."""
)
The max_iters parameter is crucial—it controls how many reasoning-acting cycles the agent can go through. I initially left this at the default (10) and watched my agent burn through API credits going in circles on ambiguous queries. Five iterations is a good starting point for most tasks.
Step 3: Adding Memory
One of AgentScope 2.0's recent additions is agentic memory. This isn't just a chat history—it's structured memory that agents can actively manage. Here's how to set it up:
from agentscope.memory import TemporaryMemory
# Create a memory instance
memory = TemporaryMemory()
# Attach it to your agent
research_agent = ReActAgent(
name="researcher",
model_config_name="gpt-4o",
tool_list=toolkit,
max_iters=5,
memory=memory
)
For production use, you'll want persistent memory. AgentScope supports RAG-based memory and has recently integrated Mem0 for more sophisticated memory management:
from agentscope.memory import Mem0Memory
persistent_memory = Mem0Memory(
user_id="research_user_1",
api_key="your-mem0-key"
)
I ran into a gotcha here: TemporaryMemory doesn't persist across agent sessions by default. If you need agents to remember things between runs, you must use a persistent backend. I lost an hour debugging "why doesn't my agent remember yesterday's research" before realizing this.
Step 4: Multi-Agent Workflows
This is where AgentScope shines. Let's build a two-agent pipeline—our researcher and a writer that takes research output and creates a final report:
from agentscope.agents import DialogAgent
from agentscope.pipeline import SequentialPipeline
# Writer agent
writer_agent = DialogAgent(
name="writer",
model_config_name="gpt-4o",
prompt_template="""You are a technical writer. Take the research
findings provided and write a clear, well-structured report.
Use markdown formatting with headers, bullet points, and
a summary section at the end."""
)
# Connect them in a pipeline
pipeline = SequentialPipeline([research_agent, writer_agent])
# Run it
result = pipeline("Research the current state of WebAssembly
for server-side computing")
print(result.content)
The SequentialPipeline passes the output of one agent as input to the next. But AgentScope also supports more complex patterns. For my research project, I needed a fork-join pattern where multiple researchers work in parallel and a synthesizer combines their findings:
from agentscope.pipeline import ForkJoinPipeline
# Multiple specialized researchers
security_researcher = ReActAgent(
name="security_researcher",
model_config_name="gpt-4o",
tool_list=toolkit,
max_iters=3,
prompt_template="Research security aspects of the given topic."
)
performance_researcher = ReActAgent(
name="performance_researcher",
model_config_name="gpt-4o",
tool_list=toolkit,
max_iters=3,
prompt_template="Research performance benchmarks and metrics."
)
# Fork to parallel researchers, join at synthesizer
pipeline = ForkJoinPipeline(
fork_agents=[security_researcher, performance_researcher],
join_agent=writer_agent
)
Step 5: Sandbox Execution and Permissions
If your agents need to run code (and they will), you need sandboxing. AgentScope has built-in support for Docker and E2B backends:
from agentscope.service import PythonSandbox
sandbox = PythonSandbox(backend="docker")
toolkit.add(sandbox)
The permission system lets you control what tools each agent can access. This is essential for production—you don't want a researcher agent accidentally deleting files:
from agentscope.permission import PermissionConfig
research_agent = ReActAgent(
name="researcher",
model_config_name="gpt-4o",
tool_list=toolkit,
max_iters=5,
permission=PermissionConfig(
allowed_tools=["web_search", "python_sandbox"],
denied_tools=["file_write", "shell_exec"]
)
)
Step 6: Deploying as a Service
AgentScope Runtime lets you deploy your agent pipeline as an actual service with multi-tenancy and session isolation:
from agentscope.runtime import AgentServer
server = AgentServer(
pipeline=pipeline,
host="0.0.0.0",
port=8000,
multi_tenant=True
)
server.start()
This gives you a REST API endpoint you can call from any frontend. The built-in event system handles streaming responses and human-in-the-loop interactions.
Practical Tips and Honest Limitations
What works well:
- The configuration-driven model setup is genuinely better than scattering API keys through code
- The middleware system is elegant—you can add logging, rate limiting, or custom behavior without touching agent logic
- Sandbox support out of the box saves you from building your own isolation layer
- The documentation has improved significantly since 2.0, with actual runnable examples
Where it falls short:
- The learning curve for the event system is steep if you haven't worked with event-driven architectures before
- Error messages can be opaque—I spent too long debugging a silent failure caused by a typo in my model config's
model_typefield - The RAG service is new and still has rough edges; for complex retrieval scenarios, you might need to supplement with your own vector store
- Debugging multi-agent loops is hard. When an agent goes off the rails, tracing which iteration and which tool call caused the drift requires digging into logs that could be more structured
My biggest lesson: Start with a single agent and get it working reliably before adding more. Multi-agent systems compound complexity fast. I built a three-agent pipeline on day one and spent three days debugging message-passing issues. When I rebuilt it one agent at a time, each testing in isolation before connecting, the whole thing came together in an afternoon.
AgentScope 2.0 isn't perfect, but it's the first framework I've used where I spent more time on my actual problem than on the framework itself. That's a low bar, but it matters more than people admit.