AgentScope 2.0 Tutorial: Run Your First Multi-Agent System in 10 Minutes with Docker

Run Your First Multi-Agent System with AgentScope in 10 Minutes

I spent an entire weekend trying to get a three-agent system working with another framework. When I switched to AgentScope, I had the same thing running in under 10 minutes. Not exaggerating. Here's exactly how I did it — including the mistakes I made so you don't repeat them.

Prerequisites (What You'll Need)

• Python 3.11+ — Older versions won't work. I lost 30 minutes on this.
• Docker — For the sandbox. Optional if you just want to test locally.
• An OpenAI API key (or any LLM provider — AgentScope supports them all)
• ~500MB disk space for the base image

Step 1: Installation

Two ways to run AgentScope. I've tried both:

Option A: Docker (Recommended — 2 minutes)

docker pull agentscope/copaw:latest
docker run -d --name agentscope \
  -p 8080:8080 \
  -v $(pwd)/agentscope_data:/data \
  agentscope/copaw:latest

Wait about 30 seconds for the first boot. You'll know it's ready when you see "AgentScope server started on port 8080" in the logs. If you don't see it within a minute — check if port 8080 is already in use. That got me the first time.

Option B: pip install (3 minutes)

pip install agentscope
agentscope start --port 8080

Step 2: Configure Your First Agent

Create a file called my_agent.py:

import agentscope

# Initialize with OpenAI (or swap to any provider)
agentscope.init(
    model_configs={
        "config_name": "my_gpt4",
        "model_type": "openai",
        "model_name": "gpt-4o",
        "api_key": "sk-..."  # Use env var in production!
    }
)

# Create a simple research agent
researcher = agentscope.Agent(
    name="Researcher",
    model_config_name="my_gpt4",
    sys_prompt="You are a research assistant. Find information and summarize it clearly."
)

# Create a writer agent
writer = agentscope.Agent(
    name="Writer",
    model_config_name="my_gpt4",
    sys_prompt="You are a technical writer. Take research notes and create well-structured articles."
)

# Connect them in a pipeline
pipeline = agentscope.Pipeline(
    agents=[researcher, writer],
    mode="sequential"  # researcher -> writer
)

# Run it
result = pipeline.run("Explain how RAG works in AI systems")
print(result)

Step 3: Enable the Web UI

AgentScope comes with a built-in web UI for monitoring. Just set one config flag:

agentscope.init(
    use_monitor=True,  # This enables the web UI
    monitor_port=8081  # Accessible at http://localhost:8081
)

Now open http://localhost:8081 in your browser. You'll see a real-time dashboard showing:

• Active agents and their current state
• Message history between agents (with timestamps)
• Tool calls being made (and their results)
• Memory usage and performance metrics

Step 4: Add MCP Tools

This is where AgentScope really shines. Adding MCP servers takes two lines:

# Connect an MCP server
agentscope.register_mcp_tool(
    name="database_query",
    server_url="http://localhost:8000/mcp",
    tools=["query", "schema"]
)

# Now your agents can use it
researcher.add_tool("database_query")

I connected three MCP servers (PostgreSQL, web search, and file system) in under 5 minutes. No custom connectors, no parsing logic — it just worked.

Step 5: Set Up Permissions (Don't Skip This)

This saved me from a disaster. When I first set up an agent with file system access, it tried to delete a project folder. The permission system caught it:

from agentscope.permission import PermissionPolicy

policy = PermissionPolicy()
policy.add_rule("read_only", paths=["/data/projects/*"])
policy.add_rule("block", paths=["/data/projects/*/delete"])

agent.set_permission_policy(policy)

Start with the "log-only" mode first — it records what agents would do without actually executing. Check the logs, adjust the rules, then switch to enforcement mode.

Common Mistakes I Made

Performance Numbers (Real Data)

Wrapping Up

AgentScope 2.0 is hands-down the most pragmatic agent framework I've used this year. The Docker setup takes 2 minutes, the web UI gives you full visibility into what agents are doing, and the permission system means you can safely deploy to production. I've migrated three projects to it and haven't looked back.

One honest caveat: The documentation is still catching up with the 2.0 release. Some advanced features (like custom middleware) rely on the source code for now. But the basics are well-covered and the community on Discord is responsive.